feat: adaptive layout system — size-aware regions, crisp font ladders, image fitting (#393)

* 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> * feat(layout): adaptive image fitting + composite region helpers Add src/adaptive_images.py — the image counterpart to fit_text: - fit_image(img, box, mode=contain|cover|fill_height|stretch, crop_to_ink, anchor, resample, upscale) promoting the proven plugin patterns (football's crop-to-ink fill-height logos, masters' cover crop + NEAREST flags, static-image's letterbox). Upscales by default — thumbnail()'s downscale-only behavior is why imagery stays tiny on big panels. - draw_fitted_image() pastes aligned within a Region with alpha mask. - One central Pillow>=9.1 RESAMPLE shim replacing ~15 plugin copies. LayoutContext.fit_image() caches results per (identity, box size, options) with a 64-entry LRU; id()-keyed entries pin the source image. BasePlugin.draw_image() is the one-liner adoption path beside draw_fit. Composites in adaptive_layout.py: Region.offset() (user x/y-offset passthrough), scoreboard_regions() (the two-logos-plus-score card math duplicated across six sports plugins, logo_slot = min(H, W//2)), and media_row() (art-left/text-right). Fix LogoHelper's size-blind cache key (stale sizes on panel change); deprecation note on dead image_utils.py. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(harness): scale-up fill check, config variants, multi-size dev gallery Quality gates for adaptive layout: - fill_metrics()/check_scale_up() in the safety harness: overflow catches content too big for a panel, but nothing caught content that stays tiny on panels >= 2x the plugin's declared design size. The check measures lit-content extents and warns (or fails, when a plugin opts into "fill_check": "strict" in test/harness.json) below 50% coverage on the doubled axis. Warn-only by default so no existing plugin breaks. - harness.json "variants": extra runs with config overlays and their own golden dirs, so an opt-in mode (e.g. layout_mode: adaptive) is golden- tested beside the classic default. check_plugin.py loops base + variants and labels variant results mode@name. - Dev preview server: GET /api/sizes (harness size sample), POST /api/render-matrix (render at up to 12 sizes in one call), size-preset dropdown, and an "All Sizes" side-by-side gallery in the preview UI. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(plugins): adaptive-lib discoverability + advisory version compat warning Discoverability: re-export the adaptive layout/image API from src.common (the blessed-helpers package plugin authors already know) — canonical paths stay src.adaptive_layout / src.adaptive_images so nothing breaks. Document it in src/common/README.md and cross-link ADAPTIVE_LAYOUT.md from the developer docs authors actually read (quick reference, API reference, advanced dev, font manager, dev preview, plugin dev guide); ADAPTIVE_LAYOUT.md gains adaptive-images, composite-layouts and preserving-user-customization sections. Compat: PluginLoader now logs one advisory warning (never raises) when a plugin's manifest declares a min LEDMatrix version newer than the running core, checking the min_ledmatrix_version / requires.* / versions[] spellings found in the wild. Guarded against stale core version numbers. src/__init__.py __version__ bumped 1.0.0 -> 3.1.0 to match the latest release tag (v3.1.0) — it had never been updated and the compat check needs a truthful number. NOTE: verify this matches the intended release numbering before the next tag. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(layout): add measure_font_crispness — verify a ladder rung isn't blurry PIL antialiases TTF outlines by default; a 'pixel-style' font only rasterizes without antialiasing at specific sizes (for PressStart2P: exact multiples of its 8px design grid). A ladder rung at an unverified size silently renders blurry on an LED panel — this exact bug shipped in both text-display's and football-scoreboard's custom TTF ladders (non-8-multiple PressStart2P sizes, and '5by7.regular'/'4x6-font' at sizes that were never actually crisp). measure_font_crispness(font, sample_text) renders the sample and reports the fraction of ink-bbox pixels that are neither pure black nor pure white. BDF fonts (real bitmaps) always score 0.0; TTF ladders should be verified against this before shipping — see the new TestFontFitting::test_ladder_arcade_is_crisp pattern. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(layout): add fit_text_proportional — proportional sizing vs. always-maximize fit_text always picks the largest ladder rung that fits its box. That's right when an element owns dedicated space, but wrong when several independently-fitted elements need to stay visually harmonious as the panel grows: a score's box might have generous room while a neighboring logo scales by a fixed geometry factor via px() — fit_text lets the score balloon out of proportion (even overlapping the logo) even though its individual pick is technically correct. fit_text_proportional(text, box, base_size_px, ladder) instead targets base_size_px * self.scale (the same scale factor px() already uses), picking the nearest ladder rung at or below that target, still capped to what fits the box, floored at the smallest rung when the target is below every rung. Refactored the shared largest-that-fits/ellipsize walk into _walk_ladder() so fit_text and fit_text_proportional don't duplicate it. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(layout): fit_text_proportional gains an axis-specific scale override self.scale (min(width_ratio, height_ratio)) is the right conservative default for anything whose aspect ratio matters, but a caller whose surrounding composition already scales along a single axis — e.g. football-scoreboard's logo_slot = min(height, width // 2), which tracks height alone — needs text sized the same way, or it reads as under-scaled next to logos that grew on a panel that only got taller (128x32 -> 128x64: self.scale stays 1.0 since width didn't grow, but logos still double). fit_text_proportional(..., scale=None) now accepts an explicit override; None keeps the existing self.scale default. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(layout): scoreboard_regions reserves real center space at 2:1 aspect ratios logo_slot = min(height, width // 2) has a blind spot: at exactly 2:1 aspect ratio (width == 2 * height -- a very common shape: two, four, or more square modules stacked into a taller panel) width // 2 and height are equal, so the two logo slots claim the ENTIRE width and leave zero pixels for a center column, no matter how large the panel gets. Not a 'small panel' problem -- 96x48, 128x64, and 256x128 (all exactly 2:1) hit it identically, while the 128x32 design baseline and panels like 192x48 or 256x32 never do, because height is already the tighter constraint there. Two new parameters fix it in the one shared helper every scoreboard-style plugin composes through: - min_center_fraction / min_center_design_px reserve at least max(width * fraction, design_px * ctx.scale) for the center column, capping logo_slot further when needed. The scaled design-px term matters on small panels where a flat fraction alone reserves too little absolute space. - score_bleed_fraction extends the score's own fit box (not the logo slots themselves) a controlled amount into each side -- the same way real broadcast scoreboards let a big score number's edges cross into the team marks flanking it. Without this the reserve alone can still be too narrow for a short score to render without truncating. score_area is now genuinely narrower than the full card width (previously identical to status_band/detail_band, which still span the full width and overlay the logos -- short text there was never the problem). Verified against the full harness size spread: a real game score like '17-21' never needs ellipsis at any tested 2:1-or-tighter aspect ratio (test_score_never_needs_ellipsis_for_a_short_score), and wide panels (128x32/192x48/256x32-style) are provably unaffected. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs: document scoreboard_regions' center-reserve and score-bleed params Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix: address CodeRabbit review on PR #393 - docs: scope the self.layout note to BasePlugin subclasses (others build a LayoutContext directly) and make explicit that adaptive layout is opt-in — classic rendering stays unless a plugin adopts the APIs. - dev_server: broaden the render-request catch (a bad manifest.json now returns a clean 400 instead of an unhandled 500) and stop echoing raw exception text in the loader-failure responses — full tracebacks go to the dev server's console log instead. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FqzC1nzTWL4kaqgMaQZFam * fix(dev-server): allowlist plugin_id before any path lookup CodeQL (py/path-injection): plugin_id arrives in request input and flows into filesystem paths via find_plugin_dir. Gate it with the same ^[a-zA-Z0-9_-]{1,64}$ allowlist the web UI's pages_v3 uses, at the single choke point every route resolves through. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FqzC1nzTWL4kaqgMaQZFam * fix(dev-server): lexical containment check on resolved plugin dirs CodeQL doesn't recognize the interprocedural allowlist as a path-injection barrier; add the canonical one — normalize (without following symlinks, since dev plugins are commonly symlinked into plugins/) and require the result to stay inside the search dir. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FqzC1nzTWL4kaqgMaQZFam * fix(dev-server): inline normpath containment barrier before render CodeQL doesn't credit the sanitization inside find_plugin_dir along this flow; apply its documented barrier (normpath + startswith against the allowed roots) inline in _parse_render_request, on the exact path that reaches the render/load sinks. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FqzC1nzTWL4kaqgMaQZFam * fix(dev-server): derive plugin dir from trusted directory listings CodeQL's barrier-guard recognition doesn't see a startswith check inside an any() comprehension, so the normalize-and-prefix approach still flagged. Break the taint outright instead: after lookup, re-derive the directory by enumerating the search dirs (iterdir) and matching by path equality — the Path used for all downstream file access is built solely from trusted listings, never from request input. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FqzC1nzTWL4kaqgMaQZFam * fix(dev-server): use os.scandir for path-injection barrier, redact stack traces from render responses CodeQL doesn't model Path.iterdir() as a taint-clearing enumeration the way it does os.scandir() -- _trusted_plugin_dir's iterdir-based rebuild still traced plugin_id through to the manifest.json open(). Switched to scandir, matching the pattern already verified clean on PR #396. Also stops surfacing raw exception text (update()/display() failures) in the JSON render response -- logs full detail server-side via exc_info instead, returning only the exception class name to the client. And drops path values from three plugin_loader debug/error logs that CodeQL flags as clear-text-logging of externally-influenced data, keeping plugin_id (not flagged) for context. * fix(dev-server): remove conditional-reassignment ambiguity in plugin_dir resolution CodeQL's path-injection flow still traced through _parse_render_request after the scandir fix -- the tainted find_plugin_dir() result and the scandir-derived _trusted_plugin_dir() result shared the same variable name (plugin_dir), reassigned only on the truthy branch. That merge point apparently isn't treated as a barrier by the flow analysis, so it kept tracing the pre-reassignment value through to the manifest open(). Split into two distinct names -- candidate_dir (tainted, used only to call _trusted_plugin_dir) and trusted_dir (the only name used for any downstream file access) -- so there's no reassigned variable for the flow to walk through. * fix: remove unused imports flagged by Codacy Union in adaptive_images.py and field in adaptive_layout.py are both imported but never used -- the last two Codacy findings on this PR, matching the same fix already applied on PR #396. * fix(layout): bound the fit cache; never alias the source image in fits Two latent issues found in a self-review pass: - LayoutContext._fit_cache was an unbounded dict (the image cache got an LRU cap, the text-fit cache didn't). Cache keys embed the fitted TEXT, so a plugin fitting changing strings — a live game clock, a ticker — on a 24/7 service grows it forever. Now LRU-bounded at 512 entries via the same pattern as the image cache. - fit_image returned the caller's ORIGINAL image object when the source was already RGBA at target size (contain/fill_height, no ink crop). ImageFitResult is documented as an independent copy, and LayoutContext caches results — an aliased image lets later mutations of the source corrupt cached fits (or vice versa). Copy in that branch. Both covered by new regression tests. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FqzC1nzTWL4kaqgMaQZFam --------- Co-authored-by: Chuck <chuck@example.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-01 16:58:06 +00:00 · 2026-07-12 10:38:52 -04:00
parent 05e7c43b27
commit 7f7f0d6464
31 changed files with 2875 additions and 112 deletions
@@ -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,133 @@ 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 draw_image(self, img: Any, box: Any, *,
+                   mode: str = "contain", align: str = "center",
+                   valign: str = "center", crop_to_ink: bool = False,
+                   anchor: str = "center", resample: Optional[Any] = None,
+                   cache_key: Optional[Any] = None,
+                   offset: tuple = (0, 0)) -> Any:
+        """
+        Fit an image into a Region and paste it aligned within that region
+        onto the display canvas — the image counterpart to draw_fit().
+
+        Args:
+            img: Source PIL image (logos, art, icons)
+            box: Region (or (w, h) tuple) to fit and align within
+            mode: "contain" (letterbox), "cover" (crop-to-fill),
+                  "fill_height" (logo-style), "stretch"
+            crop_to_ink: Trim transparent padding before fitting
+            anchor: "center" or "top" for cover crops
+            resample: PIL filter; default LANCZOS. Use RESAMPLE_NEAREST
+                  (from src.adaptive_images) for pixel art/flags
+            cache_key: Stable identity (e.g. "logo:KC") for cross-reload
+                  caching; defaults to the image object's identity
+            offset: Final (dx, dy) translation — the hook for user
+                  x/y-offset customization
+
+        Returns:
+            ImageFitResult (processed image + dimensions + scale)
+        """
+        from src.adaptive_images import draw_fitted_image
+
+        ifit = self.layout.fit_image(img, box, mode=mode,
+                                     crop_to_ink=crop_to_ink, anchor=anchor,
+                                     resample=resample, cache_key=cache_key)
+        draw_fitted_image(self.display_manager, ifit, box,
+                          align=align, valign=valign, offset=offset)
+        return ifit
+
+    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.
@@ -437,8 +437,7 @@ class PluginLoader:
                if not Path(existing_file).resolve().is_relative_to(resolved_dir):
                    evicted[mod_name] = sys.modules.pop(mod_name)
                    self.logger.debug(
-                        "Evicted stale module '%s' (from %s) before loading plugin in %s",
-                        mod_name, existing_file, plugin_dir,
+                        "Evicted stale bare-name module '%s' before loading plugin", mod_name,
                    )
            except (ValueError, TypeError):
                continue
@@ -551,7 +550,7 @@ class PluginLoader:
            plugin_dir_str = str(plugin_dir)
            if plugin_dir_str not in sys.path:
                sys.path.insert(0, plugin_dir_str)
-                self.logger.debug("Added plugin directory to sys.path: %s", plugin_dir_str)
+                self.logger.debug("Added plugin %s's directory to sys.path", plugin_id)

            # Import the plugin module
            module_name = f"plugin_{plugin_id.replace('-', '_')}"
@@ -563,8 +562,8 @@ class PluginLoader:

            spec = importlib.util.spec_from_file_location(module_name, entry_file)
            if spec is None or spec.loader is None:
+                self.logger.error("Could not create module spec for plugin %s", plugin_id)
                error_msg = f"Could not create module spec for {entry_file}"
-                self.logger.error(error_msg)
                raise PluginError(error_msg, plugin_id=plugin_id, context={'entry_file': str(entry_file)})

            module = importlib.util.module_from_spec(spec)
@@ -683,6 +682,55 @@ class PluginLoader:
            self.logger.error(error_msg, exc_info=True)
            raise PluginError(error_msg, plugin_id=plugin_id) from e
    
+    @staticmethod
+    def _parse_semver(value: Any) -> Optional[Tuple[int, int, int]]:
+        """Parse 'X.Y.Z' (extra parts/suffixes ignored) into a comparable
+        3-tuple, or None when unparseable."""
+        if not isinstance(value, str):
+            return None
+        parts = value.strip().lstrip('v').split('.')
+        try:
+            nums = [int(''.join(ch for ch in p if ch.isdigit()) or 0) for p in parts[:3]]
+        except ValueError:
+            return None
+        while len(nums) < 3:
+            nums.append(0)
+        return tuple(nums)  # type: ignore[return-value]
+
+    def _warn_if_incompatible(self, plugin_id: str, manifest: Dict[str, Any]) -> None:
+        """Log one warning when a plugin declares a minimum LEDMatrix version
+        newer than the running core. Advisory only — never raises — so a
+        plugin that guards optional features with try/except keeps working.
+        """
+        declared = (
+            manifest.get('min_ledmatrix_version')
+            or manifest.get('requires', {}).get('min_ledmatrix_version')
+        )
+        if not declared:
+            versions = manifest.get('versions') or []
+            if versions and isinstance(versions[0], dict):
+                declared = (versions[0].get('ledmatrix_min_version')
+                            or versions[0].get('ledmatrix_min'))
+        needed = self._parse_semver(declared)
+        if needed is None:
+            return
+
+        from src import __version__ as core_version
+        current = self._parse_semver(core_version)
+        # Anti-spam guard: if the core's own version number is stale (below
+        # the ecosystem floor every shipped plugin declares), comparing would
+        # warn on nearly everything — skip with a debug note instead.
+        if current is None or current < (2, 0, 0):
+            self.logger.debug(
+                "Skipping version compatibility check for %s: core __version__ "
+                "(%s) is below the ecosystem floor", plugin_id, core_version)
+            return
+        if needed > current:
+            self.logger.warning(
+                "Plugin %s declares min LEDMatrix version %s but this core is %s — "
+                "features it relies on may be missing; update the core or expect "
+                "degraded fallbacks", plugin_id, declared, core_version)
+
    def load_plugin(
        self,
        plugin_id: str,
@@ -715,6 +763,8 @@ class PluginLoader:
        Raises:
            PluginError: If loading fails
        """
+        self._warn_if_incompatible(plugin_id, manifest)
+
        # Install dependencies if needed
        if install_deps:
            if plugins_dir is None:
@@ -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) --

@@ -73,6 +73,10 @@ class RenderResult:
    golden_ok: Optional[bool] = None
    golden_diff_pixels: int = 0
    golden_max_delta: int = 0
+    # fill / scale-up check (populated only for sizes >= 2x the design size)
+    fill_checked: bool = False
+    fill_ok: Optional[bool] = None       # False only in strict mode
+    fill_extent: Optional[Tuple[float, float]] = None  # (extent_x, extent_y)

    @property
    def size_label(self) -> str:
@@ -86,6 +90,8 @@ class RenderResult:
            return False
        if self.golden_checked and self.golden_ok is False:
            return False
+        if self.fill_ok is False:
+            return False
        return True


@@ -301,6 +307,74 @@ def compare_to_goldens(results: List[RenderResult], golden_dir: Path,
    return results


+# ---------------------------------------------------------------------------
+# Fill / scale-up check
+# ---------------------------------------------------------------------------
+#
+# Overflow catches content that is too BIG for a panel; nothing catches
+# content that stays tiny on a panel much larger than the plugin's design
+# size (e.g. 128x32 content in the corner of a 256x128 renders "green").
+# These helpers measure how much of the panel the lit content spans so the
+# harness can flag plugins that don't scale up.
+
+# A pixel counts as "lit" above this luminance — low enough to catch dim
+# content, high enough to ignore near-black noise.
+_LIT_THRESHOLD = 16
+# Content must span at least this fraction of an axis that is >= 2x the
+# design size. Lenient on purpose: margins are fine, a tiny corner is not.
+_MIN_FILL_EXTENT = 0.5
+
+
+def fill_metrics(image: Image.Image) -> Tuple[float, float, float]:
+    """Measure lit-content coverage: (extent_x, extent_y, ink_ratio).
+
+    extent_* are the lit bounding box's spans as fractions of the panel;
+    ink_ratio is the fraction of pixels lit (reporting only — sparse pixel
+    fonts legitimately have low ink ratios)."""
+    lit = image.convert("L").point(lambda p: 255 if p > _LIT_THRESHOLD else 0)
+    bbox = lit.getbbox()
+    if bbox is None:
+        return (0.0, 0.0, 0.0)
+    extent_x = (bbox[2] - bbox[0]) / image.width
+    extent_y = (bbox[3] - bbox[1]) / image.height
+    ink = sum(1 for p in lit.getdata() if p) / (image.width * image.height)
+    return (extent_x, extent_y, ink)
+
+
+def check_scale_up(results: List[RenderResult],
+                   design_size: Tuple[int, int] = (128, 32),
+                   min_extent: float = _MIN_FILL_EXTENT,
+                   strict: bool = False) -> List[RenderResult]:
+    """Flag renders that leave a big panel mostly empty.
+
+    For each result whose panel is at least 2x the design size on an axis,
+    require the lit content to span >= min_extent of that axis. Mutates the
+    results' fill_* fields. In the default warn-only mode fill_ok is left
+    None (reported, never failing); strict=True sets fill_ok=False, which
+    fails RenderResult.ok — opt in per plugin via harness.json
+    {"fill_check": "strict"} once its adaptive layout is in place.
+    """
+    design_w, design_h = design_size
+    for r in results:
+        if r.image is None or r.error is not None:
+            continue
+        check_x = r.width >= 2 * design_w
+        check_y = r.height >= 2 * design_h
+        if not (check_x or check_y):
+            continue
+        extent_x, extent_y, _ink = fill_metrics(r.image)
+        r.fill_checked = True
+        r.fill_extent = (round(extent_x, 3), round(extent_y, 3))
+        underfilled = ((check_x and extent_x < min_extent)
+                       or (check_y and extent_y < min_extent))
+        if underfilled and strict:
+            r.fill_ok = False
+        elif not underfilled:
+            r.fill_ok = True
+        # warn-only underfill: fill_ok stays None; fill_extent tells the story
+    return results
+
+
 def write_goldens(results: List[RenderResult], golden_dir: Path) -> int:
    """Write each successfully-rendered result to its golden path. Returns count."""
    written = 0
@@ -56,7 +56,15 @@ def load_harness_spec(plugin_dir: Union[str, Path]) -> Dict[str, Any]:
          "config":     {...},            # config overrides
          "mock_data":  "fixtures/mock.json",  # path (relative to plugin dir) to cache fixtures
          "freeze_time": "2025-08-01 15:25:00",
-          "skip_update": false
+          "skip_update": false,
+          "fill_check": "warn",           # or "strict": underfilled big panels FAIL
+          "variants": [                   # extra runs with config overlays and
+            {                             # their own golden dirs — e.g. an
+              "name": "adaptive",         # opt-in adaptive mode tested beside
+              "config": {"layout_mode": "adaptive"},   # the classic default
+              "golden_dir": "test/golden-adaptive"
+            }
+          ]
        }
    Returns {} when no harness.json exists.
    """
@@ -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."""
@@ -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