feat(layout): adaptive layout & font scaling system for plugins

Add src/adaptive_layout.py — opt-in core helpers so plugins render
legibly on any panel size without hand-tuned per-display layouts:

- Region: integer rect algebra (bands/columns/weighted splits/centering)
  that partitions space so text bands can't overlap by construction
- Font ladders: ordered (family, size) steps known to render crisply
  (LADDER_GRID: X11 BDFs at native sizes; LADDER_ARCADE: PressStart2P at
  8px multiples) — fitting walks the ladder instead of scaling pixel
  fonts fractionally
- LayoutContext: breakpoint tiers, geometry scale vs. a declared design
  size, and cached fit_text/fit_lines/font_for_rows queries

Generalizes the three patterns proven in the field: f1-scoreboard's
scale factor, masters-tournament's tiers, baseball-scoreboard's font
fallback ladder.

Wiring: BasePlugin gains a lazy .layout property and draw_fit();
FontManager gains get_native_bdf_size() and a cache_generation counter;
manifest schema gains display.design_size and requires.display_size
max_width/max_height; 96x48 joins DEFAULT_TEST_SIZES; the bounds-check
harness records negative-coordinate draws; TextHelper's broken
measurement helpers are fixed.

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

src/plugin_system/base_plugin.py

@@ -15,6 +15,19 @@ import logging
 from src.logging_config import get_logger
 
 
+_shared_fallback_font_manager: Optional[Any] = None
+
+
+def _fallback_font_manager() -> Any:
+    """Shared FontManager for environments (unit tests, mocks) where the
+    plugin manager doesn't carry one. Scans assets/fonts like the real one."""
+    global _shared_fallback_font_manager
+    if _shared_fallback_font_manager is None:
+        from src.font_manager import FontManager
+        _shared_fallback_font_manager = FontManager({})
+    return _shared_fallback_font_manager
+
+
 class VegasDisplayMode(Enum):
     """
     Display mode for Vegas scroll integration.
@@ -130,6 +143,97 @@ class BasePlugin(ABC):
         """
         raise NotImplementedError("Plugins must implement display()")
 
+    # -------------------------------------------------------------------------
+    # Adaptive layout support (opt-in)
+    # -------------------------------------------------------------------------
+    @property
+    def layout(self) -> Any:
+        """
+        LayoutContext for the current logical display size.
+
+        Lazily built and rebuilt automatically when the display size changes
+        (e.g. Vegas segment widths, double-sided logical screens). Provides
+        Region carving (self.layout.bounds), breakpoint tiers, a geometry
+        scale factor vs. the manifest's display.design_size, and fit-text
+        queries against font ladders. See src/adaptive_layout.py.
+
+        Example:
+            rows = self.layout.bounds.inset(1).split_v(3, 1, gap=1)
+            self.draw_fit(big_text, rows[0], ladder=LADDER_ARCADE)
+            self.draw_fit(small_text, rows[1])
+        """
+        from src.adaptive_layout import LayoutContext
+
+        width = getattr(self.display_manager, "width", None)
+        height = getattr(self.display_manager, "height", None)
+        if not width or not height:
+            matrix = getattr(self.display_manager, "matrix", None)
+            width = getattr(matrix, "width", 128)
+            height = getattr(matrix, "height", 32)
+
+        font_manager = self._get_font_manager()
+        generation = getattr(font_manager, "cache_generation", 0)
+        cached = getattr(self, "_layout_context", None)
+        if (cached is not None
+                and (cached.width, cached.height) == (width, height)
+                and getattr(self, "_layout_font_generation", None) == generation):
+            return cached
+
+        context = LayoutContext(
+            width, height, font_manager,
+            design_size=self._get_design_size(),
+        )
+        self._layout_context = context
+        self._layout_font_generation = generation
+        return context
+
+    def draw_fit(self, text: str, box: Any,
+                 color: tuple = (255, 255, 255),
+                 ladder: Optional[Any] = None,
+                 align: str = "center", valign: str = "center") -> Any:
+        """
+        Fit text to a Region with the largest crisp font that fits, then draw
+        it aligned within that region via the display manager.
+
+        Args:
+            text: Text to display (ellipsized if even the smallest rung is too wide)
+            box: Region (or (w, h) tuple anchored at 0,0) to fit and align within
+            color: RGB color tuple
+            ladder: FontLadder to walk (default LADDER_GRID; use LADDER_ARCADE
+                    for headline text like clocks and scores)
+            align/valign: alignment of the text ink within the box
+
+        Returns:
+            FitResult (font, family, size_px, text, ink metrics, fits flag)
+        """
+        from src.adaptive_layout import LADDER_DEFAULT, draw_fitted_text
+
+        fit = self.layout.fit_text(text, box, ladder=ladder or LADDER_DEFAULT)
+        draw_fitted_text(self.display_manager, fit, box,
+                         color=color, align=align, valign=valign)
+        return fit
+
+    def _get_font_manager(self) -> Any:
+        """The shared FontManager, or a module-level fallback when running
+        under mocks/harnesses that don't provide one."""
+        font_manager = getattr(self.plugin_manager, "font_manager", None)
+        if font_manager is not None and hasattr(font_manager, "get_font"):
+            return font_manager
+        return _fallback_font_manager()
+
+    def _get_design_size(self) -> tuple:
+        """Panel size this plugin's layout was authored against, from the
+        manifest's optional display.design_size (defaults to 128x32)."""
+        from src.adaptive_layout import DEFAULT_DESIGN_SIZE
+
+        if self.plugin_manager and hasattr(self.plugin_manager, "plugin_manifests"):
+            manifest = self.plugin_manager.plugin_manifests.get(self.plugin_id, {})
+            declared = manifest.get("display", {}).get("design_size", {})
+            width, height = declared.get("width"), declared.get("height")
+            if width and height:
+                return (int(width), int(height))
+        return DEFAULT_DESIGN_SIZE
+
     def get_display_duration(self) -> float:
         """
         Get the display duration for this plugin instance.

src/plugin_system/testing/bounds_display_manager.py

@@ -10,8 +10,11 @@ that don't scale down to a smaller panel.
 
 Limitations (documented on purpose):
 - Overflow past the LEFT or TOP edge (negative coordinates) is still clipped by
-  PIL and not detected here. The dominant real-world breakage is content that is
-  too wide/tall for a smaller panel, which this catches.
+  PIL and not detected pixel-wise here. The dominant real-world breakage is
+  content that is too wide/tall for a smaller panel, which this catches.
+  As a partial net, draw_text/draw_image calls made with negative coordinates
+  through this manager are recorded in `negative_coordinate_calls` — but draws
+  made directly on the raw PIL canvas remain uncovered.
 - BDF text is clipped to the declared bounds by the parent's bitmap drawer, so
   BDF overflow is not flagged. Golden-image regression covers those plugins.
 - If a plugin replaces the canvas with its own image (display_manager.image = ...),
@@ -56,6 +59,21 @@ class BoundsCheckingDisplayManager(VisualTestDisplayManager):
         super().__init__(self._canvas_width, self._canvas_height)
         # Plugins must see the DECLARED size, not the padded canvas size.
         self.matrix = _MatrixProxy(self._declared_width, self._declared_height)
+        # (text-or-'image', x, y) for every mediated draw call given a
+        # negative coordinate — PIL clips these silently, so record them.
+        self.negative_coordinate_calls: list = []
+
+    # -- negative-coordinate (left/top overflow) recording --
+
+    def draw_text(self, text, x=None, y=None, *args, **kwargs):
+        if (x is not None and x < 0) or (y is not None and y < 0):
+            self.negative_coordinate_calls.append((text, x, y))
+        return super().draw_text(text, x, y, *args, **kwargs)
+
+    def draw_image(self, image, x, y, *args, **kwargs):
+        if x < 0 or y < 0:
+            self.negative_coordinate_calls.append(('image', x, y))
+        return super().draw_image(image, x, y, *args, **kwargs)
 
     # -- declared dimensions (override parent's image-derived properties) --
 

src/plugin_system/testing/mocks.py

@@ -161,6 +161,13 @@ class MockPluginManager:
         self.plugin_manifests: Dict[str, Dict] = {}
         self.get_plugin_calls = []
         self.get_all_plugins_calls = []
+        # Real FontManager so BasePlugin.layout / draw_fit behave identically
+        # under the harness (it only needs assets/fonts on disk).
+        try:
+            from src.font_manager import FontManager
+            self.font_manager: Optional[Any] = FontManager({})
+        except Exception:
+            self.font_manager = None
     
     def get_plugin(self, plugin_id: str) -> Optional[Any]:
         """Get a plugin instance."""

src/plugin_system/testing/sizes.py

@@ -28,6 +28,7 @@ DEFAULT_TEST_SIZES: List[Tuple[int, int]] = [
     (64, 32),    # 1x1 — single panel, the tightest common rectangle
     (128, 32),   # 2x1 — the baseline most plugins are tuned for
     (64, 64),    # 1x2 — stacked, exercises tall-narrow centering
+    (96, 48),    # non-64x32-module panel (e.g. Waveshare), off-grid dims
     (128, 64),   # 2x2 — block, icon scaling / vertical centering
     (256, 32),   # 4x1 — long strip, wide horizontal layout
     (128, 96),   # 2x3 — tall, exercises vertical overflow