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>

src/adaptive_images.py

@@ -0,0 +1,166 @@
+"""
+Adaptive image fitting for plugins — the image counterpart to
+src/adaptive_layout.py's text fitting.
+
+Promotes the proven in-field image patterns into one shared helper so
+plugins stop hand-copying resize/cache code:
+
+- "crop transparent padding, then fill the row height" (football/hockey
+  logo pattern) -> ``crop_to_ink=True, mode="fill_height"``
+- "crop-to-fill with a top anchor for faces" (masters-tournament headshot
+  pattern) -> ``mode="cover", anchor="top"``
+- "letterbox to fit, centered on a background" (static-image pattern)
+  -> ``mode="contain"``
+- NEAREST for pixel art/flags vs LANCZOS for photos (masters flag pattern)
+  -> ``resample=RESAMPLE_NEAREST``
+
+Unlike PIL's ``thumbnail()`` (downscale-only — the reason plugin imagery
+stays tiny on big panels), ``fit_image`` upscales by default so content
+genuinely adapts to larger displays; pass ``upscale=False`` for the old
+behavior.
+
+Use via ``LayoutContext.fit_image(...)`` (cached per panel size) or
+``BasePlugin.draw_image(...)``; the module-level functions are the
+uncached primitives.
+"""
+
+from dataclasses import dataclass
+from typing import Any, Optional, Tuple, Union
+
+from PIL import Image
+
+# The one Pillow >= 9.1 compat shim (replaces the per-plugin copies).
+try:
+    RESAMPLE_LANCZOS = Image.Resampling.LANCZOS
+    RESAMPLE_NEAREST = Image.Resampling.NEAREST
+except AttributeError:  # Pillow < 9.1
+    RESAMPLE_LANCZOS = Image.LANCZOS
+    RESAMPLE_NEAREST = Image.NEAREST
+
+FIT_MODES = ("contain", "cover", "fill_height", "stretch")
+
+
+@dataclass(frozen=True)
+class ImageFitResult:
+    """A processed RGBA copy of a source image, sized for a target box."""
+    image: Image.Image
+    width: int
+    height: int
+    scale: float          # scale applied vs the (possibly ink-cropped) source
+    mode: str
+    source_size: Tuple[int, int]
+
+    @property
+    def is_empty(self) -> bool:
+        return self.width <= 0 or self.height <= 0
+
+
+_EMPTY_IMAGE = Image.new("RGBA", (1, 1), (0, 0, 0, 0))
+
+
+def _empty_result(mode: str, source_size: Tuple[int, int]) -> ImageFitResult:
+    return ImageFitResult(_EMPTY_IMAGE, 0, 0, 0.0, mode, source_size)
+
+
+def _box_dims(box: Any) -> Tuple[int, int]:
+    """Accept a Region (duck-typed .w/.h) or a (w, h) tuple."""
+    if hasattr(box, "w") and hasattr(box, "h"):
+        return (int(box.w), int(box.h))
+    w, h = box
+    return (int(w), int(h))
+
+
+def fit_image(img: Image.Image, box: Any, *, mode: str = "contain",
+              crop_to_ink: bool = False, anchor: str = "center",
+              resample: Any = None, upscale: bool = True) -> ImageFitResult:
+    """Fit an image into a box, preserving crispness policy per content type.
+
+    Args:
+        img: Source PIL image (any mode; output is always RGBA).
+        box: Region or (w, h) target box.
+        mode: "contain" (letterbox), "cover" (crop-to-fill),
+              "fill_height" (height == box height, contain-capped by width),
+              "stretch" (exact resize).
+        crop_to_ink: Trim fully-transparent padding (getbbox) before fitting —
+              logos shipped with generous padding otherwise render small.
+        anchor: For "cover" crops: "center" or "top" (keeps faces/tops).
+        resample: PIL resampling filter; defaults to RESAMPLE_LANCZOS.
+              Use RESAMPLE_NEAREST for pixel art, flags, and sprite icons.
+        upscale: Allow scaling above source size (default True — the adaptive
+              point). False mimics the legacy thumbnail() behavior.
+    """
+    if mode not in FIT_MODES:
+        raise ValueError(f"Unknown fit mode '{mode}' (expected one of {FIT_MODES})")
+    box_w, box_h = _box_dims(box)
+    if box_w <= 0 or box_h <= 0 or img.width <= 0 or img.height <= 0:
+        return _empty_result(mode, img.size)
+
+    resample = RESAMPLE_LANCZOS if resample is None else resample
+
+    work = img if img.mode == "RGBA" else img.convert("RGBA")
+    if crop_to_ink:
+        bbox = work.getbbox()
+        if bbox is None:  # fully transparent
+            return _empty_result(mode, img.size)
+        work = work.crop(bbox)
+
+    src_w, src_h = work.size
+
+    if mode == "stretch":
+        out = work.resize((box_w, box_h), resample)
+        return ImageFitResult(out, box_w, box_h, box_w / src_w, mode, (src_w, src_h))
+
+    if mode == "cover":
+        scale = max(box_w / src_w, box_h / src_h)
+        if not upscale:
+            scale = min(scale, 1.0)
+        scaled_w = max(1, round(src_w * scale))
+        scaled_h = max(1, round(src_h * scale))
+        out = work.resize((scaled_w, scaled_h), resample)
+        # Crop the overhang down to the box (only when the scaled image is
+        # larger; with upscale=False it may be smaller and is left as-is).
+        crop_w, crop_h = min(box_w, scaled_w), min(box_h, scaled_h)
+        left = (scaled_w - crop_w) // 2
+        top = 0 if anchor == "top" else (scaled_h - crop_h) // 2
+        out = out.crop((left, top, left + crop_w, top + crop_h))
+        return ImageFitResult(out, out.width, out.height, scale, mode, (src_w, src_h))
+
+    # contain / fill_height share the "preserve aspect, no crop" path
+    if mode == "fill_height":
+        scale = box_h / src_h
+        # contain-cap: never exceed the box width (football's logo_slot rule)
+        scale = min(scale, box_w / src_w)
+    else:  # contain
+        scale = min(box_w / src_w, box_h / src_h)
+    if not upscale:
+        scale = min(scale, 1.0)
+    out_w = max(1, round(src_w * scale))
+    out_h = max(1, round(src_h * scale))
+    out = work if (out_w, out_h) == (src_w, src_h) else work.resize((out_w, out_h), resample)
+    return ImageFitResult(out, out_w, out_h, scale, mode, (src_w, src_h))
+
+
+def draw_fitted_image(display_manager: Any, ifit: ImageFitResult, box: Any, *,
+                      align: str = "center", valign: str = "center",
+                      offset: Tuple[int, int] = (0, 0)) -> Optional[Tuple[int, int]]:
+    """Paste a fitted image aligned within a Region onto the display canvas.
+
+    Pastes with the image's own alpha mask. Returns the (x, y) actually used
+    so callers can position adjacent decorations, or None when nothing was
+    drawn (empty fit / no canvas).
+    """
+    if ifit is None or ifit.is_empty:
+        return None
+    image = getattr(display_manager, "image", None)
+    if image is None:
+        return None
+    if hasattr(box, "align_xy"):
+        x, y = box.align_xy(ifit.width, ifit.height, align, valign)
+    else:
+        box_w, box_h = _box_dims(box)
+        x = (box_w - ifit.width) // 2
+        y = (box_h - ifit.height) // 2
+    x += int(offset[0])
+    y += int(offset[1])
+    image.paste(ifit.image, (x, y), ifit.image)
+    return (x, y)

src/adaptive_layout.py

@@ -28,6 +28,7 @@ freetype.Face, so it drops straight into DisplayManager.draw_text().
 """
 
 import logging
+from collections import OrderedDict
 from dataclasses import dataclass, field
 from typing import Any, Dict, List, Optional, Sequence, Tuple, Union
 
@@ -88,6 +89,12 @@ class Region:
             dy = dx
         return Region(self.x + dx, self.y + dy, self.w - 2 * dx, self.h - 2 * dy)
 
+    def offset(self, dx: int, dy: int) -> "Region":
+        """Translate without resizing — the hook for user x/y-offset
+        customization: compute regions first, then apply the user's
+        configured offsets as a final translation."""
+        return Region(self.x + dx, self.y + dy, self.w, self.h)
+
     def top_band(self, h: int) -> "Region":
         return Region(self.x, self.y, self.w, min(h, self.h))
 
@@ -290,6 +297,12 @@ class LayoutContext:
         self.scale = min(self.width / max(1, design_w),
                          self.height / max(1, design_h))
         self._fit_cache: Dict[Any, FitResult] = {}
+        # LRU-bounded (images are big, unlike text fits). Entries hold a
+        # strong reference to the source image when keyed by id() so the id
+        # can't be recycled out from under the cache.
+        self._image_cache: "OrderedDict[Any, Tuple[Any, Any]]" = OrderedDict()
+
+    _IMAGE_CACHE_MAX = 64
 
     # ---- the three adaptation patterns --------------------------------
 
@@ -414,6 +427,41 @@ class LayoutContext:
         self._fit_cache[key] = result
         return result
 
+    # ---- images ---------------------------------------------------------
+
+    def fit_image(self, img: Any, box: Union[Region, Tuple[int, int]], *,
+                  mode: str = "contain", crop_to_ink: bool = False,
+                  anchor: str = "center", resample: Any = None,
+                  upscale: bool = True, cache_key: Any = None) -> Any:
+        """Fit an image into a box (see src/adaptive_images.py for modes),
+        cached per (image, box size, options) for this panel size.
+
+        Prefer a stable ``cache_key`` (e.g. "logo:KC") for images that get
+        reloaded — the default id()-based key is safe (the entry pins the
+        source image) but misses across reloads of the same content.
+        """
+        from src.adaptive_images import fit_image as _fit_image
+
+        box_w, box_h = _box_dims(box)
+        resample_name = getattr(resample, "name", repr(resample)) if resample is not None else "default"
+        identity = cache_key if cache_key is not None else ("id", id(img))
+        key = ("image", identity, img.size, box_w, box_h, mode,
+               crop_to_ink, anchor, resample_name, upscale)
+
+        cached = self._image_cache.get(key)
+        if cached is not None:
+            self._image_cache.move_to_end(key)
+            return cached[0]
+
+        result = _fit_image(img, (box_w, box_h), mode=mode,
+                            crop_to_ink=crop_to_ink, anchor=anchor,
+                            resample=resample, upscale=upscale)
+        # Pin the source only for id()-keyed entries (see docstring).
+        self._image_cache[key] = (result, img if cache_key is None else None)
+        while len(self._image_cache) > self._IMAGE_CACHE_MAX:
+            self._image_cache.popitem(last=False)
+        return result
+
     # ---- text utilities ------------------------------------------------
 
     def ellipsize(self, text: str, font: Any, max_w: int) -> str:
@@ -435,6 +483,7 @@ class LayoutContext:
     def clear_cache(self) -> None:
         """Drop cached fit results (call after fonts are reloaded)."""
         self._fit_cache.clear()
+        self._image_cache.clear()
 
 
 def _pick_tier(tiers: Tuple[Tuple[str, int], ...], value: int) -> str:
@@ -462,3 +511,85 @@ def draw_fitted_text(display_manager: Any, fit: FitResult,
     x, y = region.align_xy(fit.width, fit.height, align, valign)
     display_manager.draw_text(fit.text, x=x, y=y - fit.y_offset,
                               color=color, font=fit.font)
+
+
+# ---------------------------------------------------------------------------
+# Composite layouts — the region arrangements repeated across plugins,
+# expressed as Region math so migrated plugins stop hand-copying coordinate
+# formulas. Deliberately tiny: these return Regions, they don't draw.
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class ScoreboardRegions:
+    """The two-logos-plus-center-score card shared by the sports plugins."""
+    bounds: Region
+    logo_slot: int        # width of each logo slot: min(H, W // 2)
+    away_slot: Region     # left logo slot
+    home_slot: Region     # right logo slot
+    center_col: Region    # column between the slots (0-wide on square panels)
+    status_band: Region   # top band (replaces the magic y = 1)
+    score_area: Region    # center column minus the bands (replaces y = H//2 - 3)
+    detail_band: Region   # bottom band (replaces the magic y = H - 7)
+    bottom_left: Region   # bottom corner: away records / timeouts
+    bottom_right: Region  # bottom corner: home records / timeouts
+
+
+def scoreboard_regions(bounds: Region, *, ctx: Optional["LayoutContext"] = None,
+                       status_h: Optional[int] = None,
+                       detail_h: Optional[int] = None) -> ScoreboardRegions:
+    """Carve a game-card Region into the standard scoreboard arrangement.
+
+    Encodes the invariant duplicated across the sports plugins:
+    ``logo_slot = min(height, width // 2)`` (capped at half the card so the
+    home slot never collapses), away logo centered in the left slot, home in
+    the right, score/status/detail stacked in the middle column. Band
+    heights default to the classic 128x32 values, scaled by the context's
+    geometry factor when one is provided. Works on a full panel or on a
+    scroll-mode card Region.
+    """
+    if status_h is None:
+        status_h = ctx.px(9, minimum=7) if ctx else 9
+    if detail_h is None:
+        detail_h = ctx.px(8, minimum=7) if ctx else 8
+
+    logo_slot = min(bounds.h, bounds.w // 2)
+    away_slot = bounds.left_col(logo_slot)
+    home_slot = bounds.right_col(logo_slot)
+    center_col = Region(bounds.x + logo_slot, bounds.y,
+                        bounds.w - 2 * logo_slot, bounds.h)
+    status_band = center_col.top_band(status_h)
+    detail_band = center_col.bottom_band(detail_h)
+    score_area = center_col.middle(status_band.h, detail_band.h)
+    bottom = bounds.bottom_band(detail_h)
+    return ScoreboardRegions(
+        bounds=bounds, logo_slot=logo_slot,
+        away_slot=away_slot, home_slot=home_slot, center_col=center_col,
+        status_band=status_band, score_area=score_area, detail_band=detail_band,
+        bottom_left=bottom.left_col(logo_slot),
+        bottom_right=bottom.right_col(logo_slot),
+    )
+
+
+@dataclass(frozen=True)
+class MediaRow:
+    """Art/icon on the left, text column on the right (music's idiom)."""
+    art: Region
+    body: Region
+
+
+def media_row(bounds: Region, *, ctx: Optional["LayoutContext"] = None,
+              square: bool = True, gap: Optional[int] = None) -> MediaRow:
+    """Split a Region into an art slot and a body column.
+
+    With ``square=True`` the art slot is bounds.h wide (album-art style);
+    otherwise it takes the left half. The gap defaults to 2px scaled by the
+    context's geometry factor.
+    """
+    if gap is None:
+        gap = ctx.px(2, minimum=1) if ctx else 2
+    art_w = bounds.h if square else bounds.w // 2
+    art_w = min(art_w, bounds.w)
+    art = bounds.left_col(art_w)
+    body = Region(bounds.x + art_w + gap, bounds.y,
+                  bounds.w - art_w - gap, bounds.h)
+    return MediaRow(art=art, body=body)

src/common/logo_helper.py

@@ -72,9 +72,20 @@ class LogoHelper:
             
         Returns:
             PIL Image object or None if loading fails
+
+        Note: for new adaptive-layout code prefer ``BasePlugin.draw_image``
+        / ``LayoutContext.fit_image`` (src/adaptive_images.py) for the
+        fitting step — LogoHelper remains useful for its download and
+        placeholder logic.
         """
-        # Check cache first
+        # Resolve the effective target size BEFORE the cache lookup so the
-        cache_key = f"{team_abbr}_{logo_path}"
+        # key is size-qualified — a panel-size change must not return a
+        # logo resized for the old dimensions.
+        if max_width is None:
+            max_width = int(self.display_width * 1.5)
+        if max_height is None:
+            max_height = int(self.display_height * 1.5)
+        cache_key = f"{team_abbr}_{logo_path}_{max_width}x{max_height}"
         if cache_key in self._logo_cache:
             self.logger.debug(f"Using cached logo for {team_abbr}")
             # Update LRU order (move to end)

src/image_utils.py

@@ -1,3 +1,9 @@
+"""Deprecated: use src/adaptive_images.py (fit_image) instead.
+
+This module predates the adaptive image system and has no known callers.
+It is kept only so any out-of-tree code importing it keeps working.
+"""
+
 import logging
 from PIL import Image
 

src/plugin_system/base_plugin.py

@@ -213,6 +213,42 @@ class BasePlugin(ABC):
                          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."""

test/test_adaptive_images.py

@@ -0,0 +1,196 @@
+"""Tests for adaptive image fitting (src/adaptive_images.py) and the
+LayoutContext image cache."""
+
+import pytest
+from PIL import Image
+
+from src.adaptive_images import (
+    RESAMPLE_LANCZOS,
+    RESAMPLE_NEAREST,
+    ImageFitResult,
+    draw_fitted_image,
+    fit_image,
+)
+from src.adaptive_layout import LayoutContext, Region
+from src.font_manager import FontManager
+
+
+@pytest.fixture(scope="module")
+def font_manager():
+    return FontManager({})
+
+
+@pytest.fixture
+def ctx(font_manager):
+    return LayoutContext(128, 32, font_manager)
+
+
+def _solid(w, h, color=(255, 0, 0, 255)):
+    return Image.new("RGBA", (w, h), color)
+
+
+def _padded_logo(ink_w=10, ink_h=10, pad=10):
+    """Transparent canvas with a solid ink block in the middle — models a
+    logo shipped with generous transparent padding."""
+    img = Image.new("RGBA", (ink_w + 2 * pad, ink_h + 2 * pad), (0, 0, 0, 0))
+    img.paste(_solid(ink_w, ink_h), (pad, pad))
+    return img
+
+
+class TestFitModes:
+    def test_contain_letterboxes_and_upscales(self):
+        fit = fit_image(_solid(10, 5), (40, 40))
+        assert (fit.width, fit.height) == (40, 20)  # aspect preserved
+        assert fit.scale == 4.0
+
+    def test_contain_no_upscale(self):
+        fit = fit_image(_solid(10, 5), (40, 40), upscale=False)
+        assert (fit.width, fit.height) == (10, 5)
+        assert fit.scale == 1.0
+
+    def test_cover_fills_and_crops(self):
+        fit = fit_image(_solid(10, 20), (40, 40), mode="cover")
+        assert (fit.width, fit.height) == (40, 40)
+
+    def test_cover_top_anchor(self):
+        # top half red, bottom half blue; cover-crop a wide box with top anchor
+        img = Image.new("RGBA", (20, 40), (0, 0, 255, 255))
+        img.paste(_solid(20, 20, (255, 0, 0, 255)), (0, 0))
+        fit = fit_image(img, (20, 20), mode="cover", anchor="top")
+        assert fit.image.getpixel((10, 5))[:3] == (255, 0, 0)  # kept the top
+
+    def test_fill_height_matches_box_height(self):
+        fit = fit_image(_solid(10, 10), (64, 32), mode="fill_height")
+        assert fit.height == 32 and fit.width == 32
+
+    def test_fill_height_capped_by_width(self):
+        # very wide source: height-fill would overflow the box width
+        fit = fit_image(_solid(100, 10), (40, 32), mode="fill_height")
+        assert fit.width <= 40
+
+    def test_stretch_exact(self):
+        fit = fit_image(_solid(3, 7), (25, 13), mode="stretch")
+        assert (fit.width, fit.height) == (25, 13)
+
+    def test_crop_to_ink(self):
+        fit = fit_image(_padded_logo(), (30, 30), crop_to_ink=True)
+        # 10x10 ink upscaled to fill 30x30 (padding would have kept it small)
+        assert (fit.width, fit.height) == (30, 30)
+        no_crop = fit_image(_padded_logo(), (30, 30), crop_to_ink=False)
+        assert no_crop.width == 30  # whole padded canvas scaled instead
+
+    def test_fully_transparent_source(self):
+        img = Image.new("RGBA", (10, 10), (0, 0, 0, 0))
+        fit = fit_image(img, (20, 20), crop_to_ink=True)
+        assert fit.is_empty
+
+    def test_degenerate_box(self):
+        assert fit_image(_solid(10, 10), (0, 20)).is_empty
+        assert fit_image(_solid(10, 10), Region(0, 0, 20, 0)).is_empty
+
+    def test_output_always_rgba(self):
+        rgb = Image.new("RGB", (10, 10), (1, 2, 3))
+        assert fit_image(rgb, (20, 20)).image.mode == "RGBA"
+
+    def test_nearest_keeps_hard_edges(self):
+        # 2x2 checker scaled 8x: NEAREST keeps pure colors, LANCZOS blends
+        img = Image.new("RGBA", (2, 2), (0, 0, 0, 255))
+        img.putpixel((0, 0), (255, 255, 255, 255))
+        near = fit_image(img, (16, 16), mode="stretch", resample=RESAMPLE_NEAREST)
+        colors = {near.image.getpixel((x, y))[:3] for x in range(16) for y in range(16)}
+        assert colors == {(255, 255, 255), (0, 0, 0)}
+
+    def test_unknown_mode_raises(self):
+        with pytest.raises(ValueError):
+            fit_image(_solid(4, 4), (8, 8), mode="tile")
+
+
+class TestDrawFittedImage:
+    class _DM:
+        def __init__(self, w=64, h=32):
+            self.image = Image.new("RGB", (w, h), (0, 0, 0))
+
+    def test_pastes_aligned_in_region(self):
+        dm = self._DM()
+        box = Region(10, 4, 20, 20)
+        fit = fit_image(_solid(10, 10), box)
+        xy = draw_fitted_image(dm, fit, box)
+        assert xy == box.align_xy(fit.width, fit.height)
+        assert dm.image.getpixel((xy[0] + 1, xy[1] + 1)) == (255, 0, 0)
+
+    def test_offset_translates(self):
+        dm = self._DM()
+        box = Region(0, 0, 20, 20)
+        fit = fit_image(_solid(10, 10), box)
+        x, y = draw_fitted_image(dm, fit, box, align="left", valign="top",
+                                 offset=(3, 5))
+        assert (x, y) == (3, 5)
+
+    def test_empty_fit_noops(self):
+        dm = self._DM()
+        fit = fit_image(_solid(10, 10), (0, 0))
+        assert draw_fitted_image(dm, fit, Region(0, 0, 10, 10)) is None
+
+
+class TestContextImageCache:
+    def test_size_keyed_hit_and_miss(self, ctx):
+        img = _solid(10, 10)
+        a = ctx.fit_image(img, (20, 20), cache_key="logo:A")
+        assert ctx.fit_image(img, (20, 20), cache_key="logo:A") is a
+        b = ctx.fit_image(img, (30, 30), cache_key="logo:A")
+        assert b is not a and b.width == 30  # different box size = new entry
+
+    def test_id_keyed_default(self, ctx):
+        img = _solid(10, 10)
+        a = ctx.fit_image(img, (20, 20))
+        assert ctx.fit_image(img, (20, 20)) is a
+
+    def test_id_safety_pins_source(self, ctx):
+        # id()-keyed entries must pin the source image so a recycled id
+        # can't alias a dead image's cache entry.
+        img = _solid(10, 10)
+        ctx.fit_image(img, (20, 20))
+        pinned = [entry[1] for entry in ctx._image_cache.values()]
+        assert img in pinned
+
+    def test_cache_key_entries_do_not_pin(self, ctx):
+        img = _solid(10, 10)
+        ctx.fit_image(img, (20, 20), cache_key="logo:X")
+        key = next(k for k in ctx._image_cache if k[1] == "logo:X")
+        assert ctx._image_cache[key][1] is None
+
+    def test_lru_eviction(self, ctx):
+        for i in range(ctx._IMAGE_CACHE_MAX + 5):
+            ctx.fit_image(_solid(4, 4), (8, 8), cache_key=f"k{i}")
+        assert len(ctx._image_cache) == ctx._IMAGE_CACHE_MAX
+        assert not any(k[1] == "k0" for k in ctx._image_cache)  # oldest evicted
+
+    def test_clear_cache_clears_images(self, ctx):
+        ctx.fit_image(_solid(4, 4), (8, 8), cache_key="k")
+        ctx.clear_cache()
+        assert len(ctx._image_cache) == 0
+
+
+class TestBasePluginDrawImage:
+    def test_draw_image_end_to_end(self):
+        from src.plugin_system.base_plugin import BasePlugin
+        from src.plugin_system.testing.mocks import (
+            MockCacheManager, MockDisplayManager, MockPluginManager,
+        )
+
+        class _P(BasePlugin):
+            def update(self):
+                pass
+
+            def display(self, force_clear=False):
+                pass
+
+        plugin = _P("t", {}, MockDisplayManager(64, 32),
+                    MockCacheManager(), MockPluginManager())
+        logo = _padded_logo()
+        box = plugin.layout.bounds.left_col(32)
+        ifit = plugin.draw_image(logo, box, mode="fill_height",
+                                 crop_to_ink=True, cache_key="logo:T")
+        assert ifit.height == 32
+        # pasted onto the mock's canvas
+        assert plugin.display_manager.image.getpixel((16, 16)) != (0, 0, 0)

test/test_adaptive_layout.py

@@ -10,7 +10,10 @@ from src.adaptive_layout import (
     Region,
     draw_fitted_text,
     measure_ink,
+    media_row,
+    scoreboard_regions,
 )
+from src.plugin_system.testing.sizes import DEFAULT_TEST_SIZES
 from src.font_manager import FontManager
 
 
@@ -77,6 +80,60 @@ class TestRegion:
         assert r.left_col(32) == Region(0, 0, 32, 32)
         assert r.right_col(32) == Region(96, 0, 32, 32)
 
+    def test_offset_translates_without_resizing(self):
+        r = Region(5, 5, 20, 10).offset(3, -2)
+        assert r == Region(8, 3, 20, 10)
+
+
+class TestScoreboardRegions:
+    @pytest.mark.parametrize("w,h", DEFAULT_TEST_SIZES + [(8, 8)])
+    def test_invariants_at_all_sizes(self, w, h):
+        regs = scoreboard_regions(Region(0, 0, w, h))
+        assert regs.logo_slot == min(h, w // 2)
+        # slots hug the edges and never overlap the center column
+        assert regs.away_slot.x == 0 and regs.home_slot.right == w
+        assert regs.away_slot.right <= regs.center_col.x or regs.center_col.w == 0
+        assert regs.center_col.right <= regs.home_slot.x or regs.center_col.w == 0
+        # bands stack inside the center column without overlap
+        assert regs.status_band.bottom <= regs.score_area.y or regs.score_area.h == 0
+        assert regs.score_area.bottom <= regs.detail_band.y or regs.score_area.h == 0
+        # everything within bounds, nothing negative
+        for reg in (regs.away_slot, regs.home_slot, regs.center_col,
+                    regs.status_band, regs.score_area, regs.detail_band,
+                    regs.bottom_left, regs.bottom_right):
+            assert reg.w >= 0 and reg.h >= 0
+            assert reg.x >= 0 and reg.y >= 0
+            assert reg.right <= w and reg.bottom <= h
+
+    def test_ctx_scales_band_heights(self, font_manager):
+        small = scoreboard_regions(Region(0, 0, 128, 32),
+                                   ctx=LayoutContext(128, 32, font_manager))
+        big = scoreboard_regions(Region(0, 0, 256, 64),
+                                 ctx=LayoutContext(256, 64, font_manager))
+        assert big.status_band.h > small.status_band.h
+
+    def test_works_on_offset_card_region(self):
+        card = Region(10, 4, 100, 24)
+        regs = scoreboard_regions(card)
+        assert regs.away_slot.x == 10
+        assert regs.home_slot.right == card.right
+
+
+class TestMediaRow:
+    def test_square_art_plus_body(self):
+        row = media_row(Region(0, 0, 128, 32))
+        assert row.art == Region(0, 0, 32, 32)
+        assert row.body.x == 32 + 2 and row.body.right == 128
+
+    def test_non_square(self):
+        row = media_row(Region(0, 0, 100, 20), square=False, gap=4)
+        assert row.art.w == 50
+        assert row.body.x == 54
+
+    def test_narrow_panel_clamps(self):
+        row = media_row(Region(0, 0, 16, 32))
+        assert row.art.w == 16 and row.body.w == 0
+
 
 class TestLayoutContext:
     def test_tiers(self, font_manager):