fix(fonts): load 4x6 on its pixel grid, from any working directory (#565)

* fix(fonts): load 4x6 on its pixel grid, from any working directory

`extra_small_font` loaded 4x6-font.ttf at 6, off the face's 7px grid.
Under `draw.fontmode = "1"` the mono rasteriser thresholds each glyph at
50% coverage, so every glyph lost its fourth column and deformed:
christmas-countdown rendered "UNTIL" as "VM1JL". The advance is 5px at
both sizes, so snapping to 7 reflows nothing.

- Sizes in DisplayManager._load_fonts go through crisp_size() instead of
  literals. crisp_size / FONT_PIXEL_GRID / FONT_NAME_ALIASES move to
  src/common/font_layout.py; sports_card re-exports them.
- Mirror the fix in VisualTestDisplayManager, the harness's fork of
  _load_fonts. Without it every golden is blessed at the old size.
- Resolve bundled font paths against the install root, not the cwd.
  FontManager._resolve_asset_path now delegates to
  font_layout.resolve_asset_path (kept by name; plugins probe for it).
- The startup banner's middle rung snaps to 7; the 5 rung stays off-grid
  on purpose (the only size that fits a dotted quad on 64px).
- loading.py reads all plugin JSON as UTF-8 (cp1252 on Windows aborted
  check_plugin.py on a 0x9d byte).
- check_plugin.py reports in ASCII and never dies on an unencodable char.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(fonts): resolve relative asset paths from the install root, not the cwd

resolve_asset_path checked os.path.exists(relative_path) unconditionally,
so a relative asset path was still resolved against the process cwd first
-- exactly the dependency this module exists to remove. An unrelated
working directory that happens to contain assets/fonts/4x6-font.ttf (a
stale checkout, a copied assets folder, another project) would shadow the
real bundled font instead of the install root ever being consulted.

Only an absolute path is now returned as-is; a relative path always
resolves against _INSTALL_ROOT first, matching the docstring's stated
contract. FontManager._resolve_asset_path delegates to this function, so
it's covered by the same fix.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

src/common/font_layout.py

@@ -20,11 +20,23 @@ with on an LED panel.
 
 Use :func:`load_truetype` in place of ``ImageFont.truetype`` anywhere the
 result is drawn to a panel or compared against a golden image.
+
+The module also owns the other two things that decide whether a bundled face
+renders reproducibly, for the same reason — they are properties of the font
+file, not of whoever is drawing with it:
+
+* :func:`crisp_size` and :data:`FONT_PIXEL_GRID` — the size each face renders
+  on whole pixels at. ``4x6-font.ttf`` has a 7px grid, which is why the 6 that
+  reads as its natural size is the wrong number everywhere it appears.
+* :func:`resolve_asset_path` — ``assets/fonts/...`` resolved against the
+  install root rather than the process cwd.
 """
 
 from __future__ import annotations
 
-from typing import Any, Union
+import os
+from pathlib import Path
+from typing import Any, Dict, Union
 
 from PIL import ImageFont
 
@@ -41,3 +53,74 @@ def load_truetype(font: Union[str, Any], size: int, **kwargs: Any) -> ImageFont.
     """
     kwargs.setdefault("layout_engine", LAYOUT_ENGINE)
     return ImageFont.truetype(font, size, **kwargs)
+
+
+# --------------------------------------------------------------------------
+# Bundled-asset path resolution
+# --------------------------------------------------------------------------
+
+#: The install root, derived from this module's own location
+#: (``<root>/src/common/font_layout.py``) rather than from the process cwd.
+_INSTALL_ROOT = Path(__file__).resolve().parents[2]
+
+
+def resolve_asset_path(relative_path: str) -> str:
+    """Resolve a repo-relative asset path independently of the process cwd.
+
+    Prefers the path as given — so an absolute path is returned untouched and
+    behaviour is unchanged wherever the cwd already happened to be the install
+    root — then the install root derived above, then the original string so a
+    caller that wants to raise and fall back still can.
+
+    Without the fallback, any process started outside the install root (the
+    plugin safety harness, a manual ``python run.py`` from ``$HOME``, a unit
+    file written without ``WorkingDirectory``) silently loses every font and
+    degrades to PIL's default face.
+    """
+    if os.path.isabs(relative_path) and os.path.exists(relative_path):
+        return relative_path
+    candidate = _INSTALL_ROOT / relative_path
+    if candidate.exists():
+        return str(candidate)
+    return relative_path
+
+
+# --------------------------------------------------------------------------
+# Pixel-grid snapping
+# --------------------------------------------------------------------------
+
+#: Family aliases the web UI may write, mapped to the shipped filename.
+FONT_NAME_ALIASES: Dict[str, str] = {
+    "press_start": "PressStart2P-Regular.ttf",
+    "four_by_six": "4x6-font.ttf",
+}
+
+#: Pixel grid each face renders crisply on. Off-grid sizes anti-alias, which
+#: on an LED matrix is a dim lamp rather than a soft edge — and worse under
+#: ``draw.fontmode = "1"``, where the mono rasteriser thresholds each glyph at
+#: 50% coverage: an off-grid 4x6 glyph renders 3px wide instead of 4, so W/M
+#: and 0/8 stop being distinguishable. Off-grid sizes also make ``getlength``
+#: return a FreeType-dependent fractional advance, which is how two panels on
+#: one config centre the same string differently.
+FONT_PIXEL_GRID: Dict[str, int] = {
+    "PressStart2P-Regular.ttf": 8,
+    "4x6-font.ttf": 7,
+}
+
+
+def crisp_size(font_file, desired, aliases=None, grid_table=None):
+    """Snap *desired* to the nearest size *font_file* renders crisply at.
+
+    A face with no known grid is returned unchanged, so a user-supplied font is
+    never second-guessed.
+
+    ``aliases`` and ``grid_table`` default to the shared tables; a plugin that
+    ships an extra face can pass its own without forking this.
+    """
+    aliases = FONT_NAME_ALIASES if aliases is None else aliases
+    grid_table = FONT_PIXEL_GRID if grid_table is None else grid_table
+    font_file = aliases.get(font_file, font_file)
+    grid = grid_table.get(font_file)
+    if not grid or not desired or desired <= 0:
+        return desired
+    return max(grid, int(round(float(desired) / grid)) * grid)

src/common/sports_card.py

@@ -22,6 +22,10 @@ from datetime import datetime, timezone
 from typing import Any, Dict, Optional, Tuple
 from zoneinfo import ZoneInfo
 
+from src.common.font_layout import (  # noqa: F401 - re-exported, see below
+    FONT_NAME_ALIASES, FONT_PIXEL_GRID, crisp_size,
+)
+
 logger = logging.getLogger(__name__)
 
 __all__ = [
@@ -52,18 +56,12 @@ FAVORITE_RESULT_COLOR_DEFAULTS: Dict[str, Tuple[int, int, int]] = {
     "tie": (255, 200, 0),
 }
 
-#: Family aliases the web UI may write, mapped to the shipped filename.
-FONT_NAME_ALIASES: Dict[str, str] = {
-    "press_start": "PressStart2P-Regular.ttf",
-    "four_by_six": "4x6-font.ttf",
-}
-
-#: Pixel grid each face renders crisply on. Off-grid sizes anti-alias, which
-#: on an LED matrix is a dim lamp rather than a soft edge.
-FONT_PIXEL_GRID: Dict[str, int] = {
-    "PressStart2P-Regular.ttf": 8,
-    "4x6-font.ttf": 7,
-}
+# Re-exported rather than defined: the grid tables and the snapping rule are
+# properties of the font files, which the display core needs too (it loads the
+# same two faces in DisplayManager._load_fonts). They live in
+# src/common/font_layout.py so there is one definition; they stay in this
+# module's namespace and __all__ so the eight scoreboards that delegate to
+# `sports_card.crisp_size` are untouched.
 
 MONTH_ABBR = ("Jan", "Feb", "Mar", "Apr", "May", "Jun",
               "Jul", "Aug", "Sep", "Oct", "Nov", "Dec")
@@ -357,24 +355,6 @@ def format_game_time(config: Optional[Dict[str, Any]], time_text: str) -> str:
 _SCHEMA_FONT_SIZE_CACHE: Dict[str, Dict[str, int]] = {}
 
 
-def crisp_size(font_file, desired, aliases=None, grid_table=None):
-    """Snap *desired* to the nearest size *font_file* renders crisply at.
-
-    A face with no known grid is returned unchanged, so a user-supplied
-    font is never second-guessed.
-
-    ``aliases`` and ``grid_table`` default to the shared tables; a plugin
-    that ships an extra face can pass its own without forking this.
-    """
-    aliases = FONT_NAME_ALIASES if aliases is None else aliases
-    grid_table = FONT_PIXEL_GRID if grid_table is None else grid_table
-    font_file = aliases.get(font_file, font_file)
-    grid = grid_table.get(font_file)
-    if not grid or not desired or desired <= 0:
-        return desired
-    return max(grid, int(round(float(desired) / grid)) * grid)
-
-
 def schema_font_size(schema_path: str, element_key) -> Optional[int]:
     """The font_size this plugin's config_schema.json declares, or None.
 

src/display_manager.py

@@ -34,7 +34,7 @@ else:
 from contextlib import contextmanager
 from pathlib import Path
 from PIL import Image, ImageDraw, ImageFont
-from src.common.font_layout import load_truetype
+from src.common.font_layout import crisp_size, load_truetype, resolve_asset_path
 import threading
 import time
 from collections import OrderedDict
@@ -403,7 +403,9 @@ class DisplayManager:
             
             # Initialize font with Press Start 2P
             try:
-                self.font = load_truetype("assets/fonts/PressStart2P-Regular.ttf", 8)
+                self.font = load_truetype(
+                    self._font_asset(self._PRESS_START),
+                    crisp_size(self._PRESS_START, 8))
                 logger.info("Initial Press Start 2P font loaded successfully")
             except Exception as e:
                 logger.error(f"Failed to load initial font: {e}")
@@ -592,9 +594,19 @@ class DisplayManager:
         Pillow had; with the engine pinned it does not, so the rung the
         worst case actually needs is here rather than implied.
         """
+        # The middle rung is on the 7px grid; the bottom one is deliberately
+        # not. 4x6 advances the same whether it is asked for 6 or 7 -- the
+        # dotted quad is 66px at both -- so the middle rung costs no width and
+        # gains the fourth column in every glyph, which is the difference
+        # between reading an address off a wall and guessing at it. The 5 rung
+        # is the exception this screen needs: it drops the advance to 4px and
+        # the quad to 51px, the only rung that fits a 64px panel, and no
+        # on-grid size does that. It is the one place in the core that draws
+        # 4x6 off-grid on purpose.
         candidates = [self.font,
-                      ("assets/fonts/4x6-font.ttf", 6),
-                      ("assets/fonts/4x6-font.ttf", 5)]
+                      (self._font_asset(self._FOUR_BY_SIX),
+                       crisp_size(self._FOUR_BY_SIX, 6)),
+                      (self._font_asset(self._FOUR_BY_SIX), 5)]
         narrowest = None
         for candidate in candidates:
             try:
@@ -966,6 +978,28 @@ class DisplayManager:
         except Exception as e:
             logger.error(f"Error drawing BDF text: {e}", exc_info=True)
 
+    #: The bundled faces, and the size each is *asked* for. Every size here is
+    #: run through `crisp_size`, so a number that drifts off the face's pixel
+    #: grid is snapped rather than rendered anti-aliased -- see the note on
+    #: `extra_small_font` below.
+    _FONT_DIR = "assets/fonts"
+    _PRESS_START = "PressStart2P-Regular.ttf"
+    _FOUR_BY_SIX = "4x6-font.ttf"
+
+    @classmethod
+    def _font_asset(cls, filename: str) -> str:
+        """Install-root-relative path to a bundled face.
+
+        `_load_fonts` named these relative to the process cwd, which holds
+        under the packaged systemd unit (WorkingDirectory is the install root)
+        and nowhere else: the plugin safety harness, `python run.py` from
+        $HOME, or a unit file written without WorkingDirectory all loaded
+        nothing and fell through to `ImageFont.load_default()`. That failure is
+        silent -- the panel just renders in PIL's default face at whatever size
+        the layout was computed for.
+        """
+        return resolve_asset_path(f"{cls._FONT_DIR}/{filename}")
+
     def _load_fonts(self):
         """Load fonts with proper error handling."""
         # Font objects get new id()s after reload, so the text-width cache would
@@ -973,16 +1007,17 @@ class DisplayManager:
         self._text_width_cache.clear()
         try:
             # Load Press Start 2P font
-            self.regular_font = load_truetype("assets/fonts/PressStart2P-Regular.ttf", 8)
+            press_start = self._font_asset(self._PRESS_START)
+            self.regular_font = load_truetype(press_start, crisp_size(self._PRESS_START, 8))
             logger.info("Press Start 2P font loaded successfully")
             
             # Use the same font for small text (currently same size; adjust size here if needed)
-            self.small_font = load_truetype("assets/fonts/PressStart2P-Regular.ttf", 8)
+            self.small_font = load_truetype(press_start, crisp_size(self._PRESS_START, 8))
             logger.info("Press Start 2P small font loaded successfully")
 
             # Load 5x7 BDF font for calendar events
             try:
-                self.calendar_font_path = "assets/fonts/5x7.bdf"
+                self.calendar_font_path = self._font_asset("5x7.bdf")
                 logger.info(f"Attempting to load 5x7 font from: {self.calendar_font_path}")
                 
                 if not os.path.exists(self.calendar_font_path):
@@ -1017,11 +1052,26 @@ class DisplayManager:
             self.bdf_5x7_font = self.calendar_font 
             logger.info(f"Assigned calendar_font (type: {type(self.bdf_5x7_font).__name__}) to bdf_5x7_font.")
 
-            # Load 4x6 font as extra_small_font
+            # Load 4x6 font as extra_small_font.
+            #
+            # Asked for 6 -- the size the face's name suggests -- for years,
+            # and 6 is off its 7px pixel grid. Plugins draw this face with
+            # `draw.fontmode = "1"`, and the mono rasteriser thresholds each
+            # glyph at 50% coverage, so off-grid every glyph came out 3px wide
+            # instead of 4. The lost column deforms the letterforms rather than
+            # merely thinning them: christmas-countdown rendered "UNTIL" as
+            # "VM1JL" and "CHRISTMAS" as "CHAJS1MAS", and zero loses the left
+            # half of its bowl. Those renders were committed as golden images.
+            #
+            # `crisp_size` snaps it to 7. The advance is unchanged -- 5px per
+            # glyph at either size -- so nothing reflows and no layout gets
+            # tighter; a string is at most a pixel or two wider because the
+            # last glyph finally occupies the width it was always given.
             try:
-                font_path = "assets/fonts/4x6-font.ttf"
-                logger.info(f"Attempting to load 4x6 TTF font from: {font_path} at size 6")
-                self.extra_small_font = load_truetype(font_path, 6)
+                font_path = self._font_asset(self._FOUR_BY_SIX)
+                size = crisp_size(self._FOUR_BY_SIX, 6)
+                logger.info(f"Attempting to load 4x6 TTF font from: {font_path} at size {size}")
+                self.extra_small_font = load_truetype(font_path, size)
                 logger.info(f"4x6 TTF extra small font loaded successfully from {font_path}")
             except Exception as font_err:
                 logger.error(f"Failed to load 4x6 TTF font: {font_err}. Falling back.")

src/font_manager.py

@@ -38,7 +38,7 @@ import time
 from collections import OrderedDict
 from pathlib import Path
 from PIL import ImageFont
-from src.common.font_layout import load_truetype
+from src.common.font_layout import load_truetype, resolve_asset_path
 from typing import Dict, Tuple, Optional, Union, Any, List
 
 logger = logging.getLogger(__name__)
@@ -665,20 +665,14 @@ class FontManager:
     def _resolve_asset_path(relative_path: str) -> str:
         """Resolve a repo-relative asset path independently of the process cwd.
 
-        Prefers the working directory (preserving behavior when the process
-        runs from the install root), then falls back to the install root
-        derived from this module's own location. Without the fallback, any
-        process started outside the install root (e.g. the plugin safety
-        harness on CI) silently loses every font and degrades to PIL's
-        default face.
+        Thin delegate to :func:`src.common.font_layout.resolve_asset_path`,
+        which holds the one definition (``DisplayManager._load_fonts`` needs
+        the same resolution and must not import this class for it). The method
+        stays because plugins probe for it by name to share the core's notion
+        of "install root" -- see the `_resolve_font_path` helpers in the
+        scoreboard plugins.
         """
-        if os.path.exists(relative_path):
-            return relative_path
-        install_root = Path(__file__).resolve().parent.parent
-        candidate = install_root / relative_path
-        if candidate.exists():
-            return str(candidate)
-        return relative_path
+        return resolve_asset_path(relative_path)
 
     def _initialize_fonts(self):
         """Initialize font catalog and validate configuration."""

src/plugin_system/testing/loading.py

@@ -25,11 +25,20 @@ def find_plugin_dir(plugin_id: str, search_dirs: Sequence[Union[str, Path]]) ->
 
 
 def load_manifest(plugin_dir: Union[str, Path]) -> Dict[str, Any]:
-    """Load and return manifest.json from a plugin directory."""
+    """Load and return manifest.json from a plugin directory.
+
+    Read as UTF-8 explicitly, not in the platform default encoding: JSON is
+    UTF-8 by RFC 8259, but `open()` honours the locale, which is cp1252 on
+    Windows. A manifest carrying any non-ASCII byte (an em dash in a
+    description, a degree sign in a mode name) therefore raised
+    UnicodeDecodeError and aborted the whole `check_plugin.py --all` run on the
+    byte rather than failing just that plugin. The three sibling loaders below
+    read JSON from the same plugin trees and had the same bug.
+    """
     manifest_path = Path(plugin_dir) / 'manifest.json'
     if not manifest_path.exists():
         raise FileNotFoundError(f"No manifest.json in {plugin_dir}")
-    with open(manifest_path, 'r') as f:
+    with open(manifest_path, 'r', encoding='utf-8') as f:
         return json.load(f)
 
 
@@ -77,7 +86,7 @@ def load_config_defaults(plugin_dir: Union[str, Path]) -> Dict[str, Any]:
     schema_path = Path(plugin_dir) / 'config_schema.json'
     if not schema_path.exists():
         return {}
-    with open(schema_path, 'r') as f:
+    with open(schema_path, 'r', encoding='utf-8') as f:
         schema = json.load(f)
     return _defaults_from_properties(schema.get('properties', {}))
 
@@ -106,7 +115,7 @@ def load_harness_spec(plugin_dir: Union[str, Path]) -> Dict[str, Any]:
     spec_path = Path(plugin_dir) / 'test' / 'harness.json'
     if not spec_path.exists():
         return {}
-    with open(spec_path, 'r') as f:
+    with open(spec_path, 'r', encoding='utf-8') as f:
         spec = json.load(f)
 
     # Resolve mock_data path and inline its contents for convenience.
@@ -120,7 +129,7 @@ def load_harness_spec(plugin_dir: Union[str, Path]) -> Dict[str, Any]:
                 f"harness.json references mock_data '{mock_rel}' but "
                 f"{mock_path} does not exist"
             )
-        with open(mock_path, 'r') as mf:
+        with open(mock_path, 'r', encoding='utf-8') as mf:
             spec['mock_data_contents'] = json.load(mf)
     return spec
 

src/plugin_system/testing/visual_display_manager.py

@@ -31,7 +31,7 @@ from pathlib import Path
 from typing import Any, List, Optional, Tuple
 
 from PIL import Image, ImageDraw, ImageFont
-from src.common.font_layout import load_truetype
+from src.common.font_layout import crisp_size, load_truetype
 
 from src.logging_config import get_logger
 
@@ -141,9 +141,10 @@ class VisualTestDisplayManager:
             fonts_dir = project_root / 'assets' / 'fonts'
 
             # Press Start 2P — regular and small (both 8px)
-            ttf_path = str(fonts_dir / 'PressStart2P-Regular.ttf')
-            self.regular_font = load_truetype(ttf_path, 8)
-            self.small_font = load_truetype(ttf_path, 8)
+            press_start = 'PressStart2P-Regular.ttf'
+            ttf_path = str(fonts_dir / press_start)
+            self.regular_font = load_truetype(ttf_path, crisp_size(press_start, 8))
+            self.small_font = load_truetype(ttf_path, crisp_size(press_start, 8))
             self.font = self.regular_font  # alias used by some code paths
 
             # 5x7 BDF font via freetype
@@ -160,10 +161,15 @@ class VisualTestDisplayManager:
                 self.calendar_font = self.small_font
                 self.bdf_5x7_font = self.small_font
 
-            # 4x6 extra small TTF
+            # 4x6 extra small TTF, snapped to the face's 7px grid exactly as
+            # DisplayManager._load_fonts does. Sizing this independently is how
+            # the harness would render -- and bless goldens -- in a face the
+            # panel never uses: at the off-grid 6 this asked for, every glyph
+            # loses its fourth column under `draw.fontmode = "1"`.
             try:
-                xs_path = str(fonts_dir / '4x6-font.ttf')
-                self.extra_small_font = load_truetype(xs_path, 6)
+                four_by_six = '4x6-font.ttf'
+                xs_path = str(fonts_dir / four_by_six)
+                self.extra_small_font = load_truetype(xs_path, crisp_size(four_by_six, 6))
             except (FileNotFoundError, OSError) as e:
                 logger.debug("Extra small font not available, using fallback: %s", e)
                 self.extra_small_font = self.small_font