feat: universal element style system — resolver, schema expansion, live preview (#394)

* feat(element-style): universal per-element style resolver

One shared implementation of the three things every customizable plugin
re-invented: a font loader, the customization.layout x/y-offset reader,
and the "did the user actually override this font?" check.

The override check is the load-bearing piece: the web UI's save flow
writes full schema defaults into config.json on every save, and the
plugin manager merges defaults again before instantiation, so key
presence never means user intent. The resolver compares against the
plugin's own schema defaults (via schema_manager), degrading to
caller-supplied classic defaults when unavailable. This retires the
hand-maintained _CLASSIC_FONT_DEFAULTS dicts that shipped broken twice.

The loader is a superset of the four per-plugin variants: alias
resolution (baseball), truetype for TTF/OTF/BDF (FreeType loads BDF at
native size), .pil sidecar fallback for BDF (football), fallback font,
PIL default — never raises. Also introduces the text_color convention
([r,g,b], absent = keep the plugin's hardcoded color).

BasePlugin gains a lazy style_resolver property (invalidated on config
change) and element_style() sugar; standalone helpers receive the
resolver from their owning plugin.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FqzC1nzTWL4kaqgMaQZFam

* feat(element-style): x-style-elements schema expansion + color provenance

Plugins can now declare styleable display elements once, compactly, on
their customization schema ("x-style-elements") instead of hand-copying
the ~50-line font/font_size/text_color/offset property blocks (currently
duplicated 52x across the plugin monorepo). SchemaManager.load_schema
expands declarations before caching, so the config form, save path,
validation, and defaults generation all see the same shape; the single
expansion implementation lives in src.element_style and is also applied
by defaults_from_schema_file, keeping the web UI's view and a plugin's
raw-schema-file view of the defaults provably identical (parity test).

Generated blocks use only widgets the config form already renders
(font-selector, color-picker, number inputs) and update x-propertyOrder
when present (the template only renders listed keys). Expansion is
idempotent, never mutates its input or the cached/on-disk schema, and a
hand-written block for the same element always wins.

Color gets the same provenance rule as fonts: the web form always posts
the RGB inputs, so a saved config carries the schema-default color
whether or not the user touched it — the resolver now only honors a
color that DIFFERS from the schema default, and keeps the plugin's
classic (possibly state-dependent, e.g. gold-on-touchdown) color
otherwise.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FqzC1nzTWL4kaqgMaQZFam

* feat(web): live plugin preview on the config page

Adds POST /api/v3/plugins/preview: renders a plugin headlessly with the
CANDIDATE (unsaved) config and returns a PNG — so users can see exactly
what the panel will show before saving, at their real panel size (from
display.hardware) or a chosen test size.

Two extractions make it drift-proof rather than parallel-implemented:
- dev_server's _render_once moves to
  src/plugin_system/testing/render_service.py (pure PIL via
  VisualTestDisplayManager, install_deps=False always — safe in the web
  process, which never touches display hardware); the dev server now
  wraps it.
- save_plugin_config's ~350-line form->config conversion is extracted
  verbatim as parse_plugin_config_form and shared by the preview
  endpoint, so preview and save can never interpret the form
  differently.

update() is skipped by default (no network on the request thread);
plugins with a test/harness.json get their mock-data fixture primed
instead, and ?skip_update=0 opts into a live update. The config page
gains a Live Preview panel (HTMX hx-include of the existing form, size
selector, pixelated img fragment) — works for every plugin with zero
per-plugin code, including the x-style-elements font/size/color fields.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FqzC1nzTWL4kaqgMaQZFam

* fix(web): expand x-style-elements in the config-page form render too

pages_v3's plugin-config partial loads config_schema.json directly from
disk rather than through SchemaManager.load_schema, so declared style
elements expanded everywhere EXCEPT the form the user actually sees.
Found live on the devpi: the API served the expanded schema and the
save path validated against it, but the config page rendered no
font/color/offset fields. Apply the same (idempotent) expansion here.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FqzC1nzTWL4kaqgMaQZFam

* fix(web): preview size selector — htmx caches hx-post, use hx-vals

Found live on the devpi: selecting a preview size did nothing because
htmx snapshots the request path when it processes the button, so the
size dropdown's onchange mutation of hx-post never took effect. The size
now travels as a __preview_size=WxH form field attached via hx-vals
(evaluated at request time); the endpoint honors it (query args still
win for API callers) and strips it before form parsing so it can't leak
into the candidate config.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FqzC1nzTWL4kaqgMaQZFam

* fix(web): allowlist plugin_id in the preview endpoint's dir lookup

Same defense as the dev server's find_plugin_dir (and pages_v3's
existing pattern): plugin_id arrives in request input and is used to
build filesystem paths — reject anything outside ^[a-zA-Z0-9_-]{1,64}$
before touching the filesystem.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FqzC1nzTWL4kaqgMaQZFam

* fix: harden preview + resolver edges found in self-review

- extract_schema_defaults now matches SchemaManager's array handling
  ([] for arrays without defaults, [item] for item-level defaults) —
  the documented parity guarantee was false for array-typed properties;
  parity test extended to cover them.
- render_plugin_once calls plugin cleanup() in a finally (image captured
  first — cleanup may clear the canvas): preview instances could leak
  sessions/threads per request in the long-running web process.
- Preview JSON path deep-merges the candidate onto the saved config,
  matching the form path — a shallow update() silently dropped saved
  sibling values in any nested section the candidate touched.
- Preview render is bounded (15s, 504 on timeout, daemonized worker):
  a hanging plugin display() no longer pins a web worker forever.
- ElementStyleResolver.is_for(config): public staleness check for
  callers that cache a resolver, instead of poking _config.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FqzC1nzTWL4kaqgMaQZFam

* fix(render-service): adopt the dev server's exception-detail policy

Port c6962701's convention into the shared render service (which
supersedes the inline _render_once it patched): full tracebacks to the
server log via exc_info, only the exception class name to the client.

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>

.codacy.yml

@@ -0,0 +1,7 @@
+---
+exclude_paths:
+  - "plugin-repos/**"
+  - "plugins/**"
+  - "assets/**"
+  - "test/**"
+  - "scripts/debug/**"

.github/workflows/claude-code-review.yml

@@ -0,0 +1,44 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, ready_for_review, reopened]
+    # Optional: Only run on specific file changes
+    # paths:
+    #   - "src/**/*.ts"
+    #   - "src/**/*.tsx"
+    #   - "src/**/*.js"
+    #   - "src/**/*.jsx"
+
+jobs:
+  claude-review:
+    # Optional: Filter by PR author
+    # if: |
+    #   github.event.pull_request.user.login == 'external-contributor' ||
+    #   github.event.pull_request.user.login == 'new-developer' ||
+    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
+          plugins: 'code-review@claude-code-plugins'
+          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://code.claude.com/docs/en/cli-reference for available options
+

.github/workflows/claude.yml

@@ -0,0 +1,50 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://code.claude.com/docs/en/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr *)'
+

.github/workflows/test.yml

@@ -0,0 +1,33 @@
+name: Tests
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  plugin-safety:
+    name: Plugin safety harness + unit tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt -r requirements-test.txt
+          pip install RGBMatrixEmulator
+
+      - name: Run harness + visual rendering tests
+        run: |
+          pytest --no-cov \
+            test/plugins/test_harness.py \
+            test/plugins/test_visual_rendering.py \
+            test/plugins/test_plugin_matrix.py

.gitignore

@@ -8,6 +8,7 @@ config/config_secrets.json
 config/config.json
 config/config.json.backup
 config/wifi_config.json
+config/uninstalled_plugins.json
 credentials.json
 token.pickle
 

.gitmodules

@@ -1,3 +1,4 @@
 [submodule "rpi-rgb-led-matrix-master"]
 	path = rpi-rgb-led-matrix-master
 	url = https://github.com/hzeller/rpi-rgb-led-matrix.git
+	branch = master

README.md

@@ -1,4 +1,10 @@
 # LEDMatrix
+[![License](https://img.shields.io/badge/license-GPL--3.0-green)](LICENSE)
+[![Discord](https://img.shields.io/badge/Discord-community-5865F2?logo=discord&logoColor=white)](https://discord.gg/RdrC37rEag)
+[![GitHub Stars](https://img.shields.io/github/stars/ChuckBuilds/ledmatrix?style=flat&color=yellow)](https://github.com/ChuckBuilds/ledmatrix)
+[![Codacy Badge](https://app.codacy.com/project/badge/Grade/77fc9b446a5948e5b0aed7a7aaeb1bab)](https://app.codacy.com/gh/ChuckBuilds/LEDMatrix/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
+
+
 ## Welcome to LEDMatrix! 
 Welcome to the LEDMatrix Project! This open-source project enables you to run an information-rich display on a Raspberry Pi connected to an LED RGB Matrix panel. Whether you want to see your calendar, weather forecasts, sports scores, stock prices, or any other information at a glance, LEDMatrix brings it all together.
 
@@ -126,10 +132,15 @@ The system supports live, recent, and upcoming game information for multiple spo
 | This project can be finnicky! RGB LED Matrix displays are not built the same or to a high-quality standard. We have seen many displays arrive dead or partially working in our discord. Please purchase from a reputable vendor. |
 
 ### Raspberry Pi
-- Raspberry Pi Zero's don't have enough processing power for this project and the Pi 5 is unsupported due to new GPIO output.
-- **Raspberry Pi 3B or 4 (NOT RPi 5!)**  
+- Raspberry Pi Zero's don't have enough processing power for this project.
+- **Raspberry Pi 3B, 4, or 5**
   [Amazon Affiliate Link – Raspberry Pi 4 4GB RAM](https://amzn.to/4dJixuX)
   [Amazon Affiliate Link – Raspberry Pi 4 8GB RAM](https://amzn.to/4qbqY7F)
+  - **Pi 5 users**: the installer automatically detects Pi 5 and builds the `rpi-rgb-led-matrix` library with RP1 support. If you previously installed on a Pi 4 and migrated the SD card, or if you see `mmap` errors in the logs, force a fresh library build:
+    ```bash
+    sudo RPI_RGB_FORCE_REBUILD=1 ./first_time_install.sh
+    ```
+  - Pi 5 config: leave `rp1_rio` at `0` (PIO mode, default) and set `gpio_slowdown` to `1` or `2`.
 
 
 ### RGB Matrix Bonnet / HAT
@@ -581,7 +592,7 @@ These settings control runtime behavior and GPIO timing:
   - **Critical setting**: Must match your Raspberry Pi model for stability
   - **Raspberry Pi 3**: Use 3
   - **Raspberry Pi 4**: Use 4
-  - **Raspberry Pi 5**: Use 5 (or higher if needed)
+  - **Raspberry Pi 5**: Use 1–2 in PIO mode (`rp1_rio: 0`, the default); start with `1` and increase if you see flickering
   - **Raspberry Pi Zero/1**: Use 1-2
   - Incorrect values can cause display corruption, flickering, or system instability
   - If you experience issues, try adjusting this value up or down by 1

config/config.template.json

@@ -1,43 +1,43 @@
 {
     "web_display_autostart": true,
     "schedule": {
-        "enabled": true,
+        "enabled": false,
         "mode": "per-day",
         "start_time": "07:00",
         "end_time": "23:00",
         "days": {
             "monday": {
-                "enabled": true,
+                "enabled": false,
                 "start_time": "07:00",
                 "end_time": "23:00"
             },
             "tuesday": {
-                "enabled": true,
+                "enabled": false,
                 "start_time": "07:00",
                 "end_time": "23:00"
             },
             "wednesday": {
-                "enabled": true,
+                "enabled": false,
                 "start_time": "07:00",
                 "end_time": "23:00"
             },
             "thursday": {
-                "enabled": true,
+                "enabled": false,
                 "start_time": "07:00",
                 "end_time": "23:00"
             },
             "friday": {
-                "enabled": true,
+                "enabled": false,
                 "start_time": "07:00",
                 "end_time": "23:00"
             },
             "saturday": {
-                "enabled": true,
+                "enabled": false,
                 "start_time": "07:00",
                 "end_time": "23:00"
             },
             "sunday": {
-                "enabled": true,
+                "enabled": false,
                 "start_time": "07:00",
                 "end_time": "23:00"
             }
@@ -51,46 +51,46 @@
         "end_time": "07:00",
         "days": {
             "monday": {
-                "enabled": true,
+                "enabled": false,
                 "start_time": "20:00",
                 "end_time": "07:00"
             },
             "tuesday": {
-                "enabled": true,
+                "enabled": false,
                 "start_time": "20:00",
                 "end_time": "07:00"
             },
             "wednesday": {
-                "enabled": true,
+                "enabled": false,
                 "start_time": "20:00",
                 "end_time": "07:00"
             },
             "thursday": {
-                "enabled": true,
+                "enabled": false,
                 "start_time": "20:00",
                 "end_time": "07:00"
             },
             "friday": {
-                "enabled": true,
+                "enabled": false,
                 "start_time": "20:00",
                 "end_time": "07:00"
             },
             "saturday": {
-                "enabled": true,
+                "enabled": false,
                 "start_time": "20:00",
                 "end_time": "07:00"
             },
             "sunday": {
-                "enabled": true,
+                "enabled": false,
                 "start_time": "20:00",
                 "end_time": "07:00"
             }
         }
     },
-    "timezone": "America/Chicago",
+    "timezone": "America/New_York",
     "location": {
-        "city": "Dallas",
-        "state": "Texas",
+        "city": "Tampa",
+        "state": "Florida",
         "country": "US"
     },
     "display": {
@@ -112,7 +112,13 @@
             "limit_refresh_rate_hz": 100
         },
         "runtime": {
-            "gpio_slowdown": 3
+            "gpio_slowdown": 3,
+            "rp1_rio": 0
+        },
+        "double_sided": {
+            "enabled": false,
+            "copies": 2,
+            "axis": "horizontal"
         },
         "display_durations": {},
         "use_short_date_format": true,
@@ -126,6 +132,11 @@
             "buffer_ahead": 2
         }
     },
+    "sync": {
+        "role": "standalone",
+        "port": 5765,
+        "follower_position": "left"
+    },
     "plugin_system": {
         "plugins_directory": "plugin-repos",
         "auto_discover": true,

docs/ADAPTIVE_LAYOUT.md

@@ -0,0 +1,234 @@
+# Adaptive Layout & Font Scaling
+
+`src/adaptive_layout.py` lets a plugin render legibly on **any** panel size
+(64x32, 128x32, 96x48, 128x64, 256x64, ...) without hand-tuned per-display
+layouts. It is **opt-in**: nothing changes for plugins that don't use it.
+
+It generalizes three patterns proven in the plugin ecosystem:
+
+| Pattern | Origin | Core API |
+|---|---|---|
+| Geometry scale factor vs. a design size | f1-scoreboard | `ctx.px(base)` / `ctx.scale` |
+| Breakpoint tiers | masters-tournament | `ctx.tier` / `ctx.by_tier({...})` |
+| "Largest crisp font that fits" ladder | baseball-scoreboard | `ctx.fit_text(...)` and friends |
+
+## Quick start
+
+Every `BasePlugin` has a lazy `self.layout` (a `LayoutContext` for the
+current logical display size, rebuilt automatically if the size changes)
+and a one-liner `self.draw_fit(...)`:
+
+```python
+def display(self, force_clear=False):
+    from src.adaptive_layout import LADDER_ARCADE
+
+    b = self.layout.bounds.inset(1)          # Region(0,0,W,H) minus 1px margin
+    rows = b.split_v(3, 1, 1, gap=1)          # 3/5 for time, 1/5 each for the rest
+
+    self.draw_fit(self.time_str, rows[0], ladder=LADDER_ARCADE)
+    self.draw_fit(self.weekday, rows[1])      # default LADDER_GRID
+    self.draw_fit(self.date_str, rows[2])
+    self.display_manager.update_display()
+```
+
+On 128x64 the time renders at press_start 24px; on 64x32 it steps down to
+8px. The rows partition the height, so bands can never overlap — no more
+`y = height - 7` magic numbers.
+
+## Region — rect algebra
+
+`Region(x, y, w, h)` is a frozen dataclass. All carving clamps to
+non-negative dimensions, so degenerate panels behave.
+
+- Carving: `inset(dx, dy)`, `top_band(h)`, `bottom_band(h)`,
+  `middle(top_h, bottom_h)`, `left_col(w)`, `right_col(w)`,
+  `split_h(*weights, gap=0)`, `split_v(*weights, gap=0)`
+- Placement: `align_xy(w, h, align, valign)`, `center_xy(w, h)`,
+  `contains(w, h)`, `.center`, `.right`, `.bottom`
+
+Scoreboard-style layout:
+
+```python
+b = self.layout.bounds
+status = b.top_band(self.layout.px(7))
+detail = b.bottom_band(self.layout.px(7))
+score_area = b.middle(status.h, detail.h)
+away_slot, home_slot = b.left_col(b.h), b.right_col(b.h)
+```
+
+## Font ladders — discrete, never fractional
+
+Pixel fonts (BDF, PressStart2P) only look right at native/integer sizes, so
+fonts are never scaled continuously. A `FontLadder` is an ordered tuple of
+`FontStep(family, size_px)` rungs, largest first; fitting walks down until
+the measured text fits.
+
+- `LADDER_GRID` (default): X11 BDFs at native sizes — 10x20 → 9x18 → 9x15 →
+  8x13 → 7x13 → 6x13 → 6x12 → 6x10 → 6x9 → 5x8 → 5x7 → 4x6 → tom-thumb.
+  Body text, labels, multi-row content.
+- `LADDER_ARCADE`: PressStart2P at 32/24/16/8 (integer multiples of its 8px
+  grid). Headline text: clocks, scores.
+
+Custom ladders are just tuples — e.g. to add your plugin's registered font
+on top: `(FontStep("myplugin::digits", 16),) + LADDER_GRID`.
+
+## LayoutContext
+
+Built per (width, height); exposes facts and fit queries:
+
+- `bounds`, `width`, `height`, `aspect`
+- `tier` by height (`xs`≤16, `sm`≤32, `md`≤48, `lg`≤64, `xl`) and
+  `width_tier` (`narrow`≤64, `normal`≤128, `wide`≤256, `ultrawide`)
+- `is_wide_short` — aspect ≥ 2.5 and height ≤ 32 (the classic 128x32 shape)
+- `scale` — `min(w/design_w, h/design_h)` vs. your manifest's
+  `display.design_size` (default 128x32). **Geometry only** — gaps, icon
+  and logo sizes via `px(base, minimum, maximum)`; fonts use ladders.
+- `by_tier({"sm": 10, "lg": 18})` — value for the nearest defined tier
+  at-or-below the panel's tier.
+- `fit_text(text, box, ladder, ellipsis=True)` → `FitResult` — largest rung
+  that fits; ellipsizes as a last resort. Cached per (text, box, ladder).
+- `fit_text_proportional(text, box, base_size_px, ladder, ellipsis=True, scale=None)` —
+  rung closest to (not exceeding) `base_size_px * scale`, still capped to
+  what fits the box. Use this instead of `fit_text` when several
+  independently-fitted elements need to stay visually harmonious as the
+  panel grows — `fit_text` maximizes *each one* within its own region,
+  which can make one element (e.g. a score with a generous box) balloon
+  out of proportion to a neighbor that scales by geometry (e.g. logos
+  sized via `px()`), even though each individual pick is "correct" in
+  isolation. `base_size_px` is normally the element's existing classic/
+  fixed font size. `scale` defaults to `self.scale` (the conservative
+  min-of-both-axes factor `px()` uses); pass an axis-specific value when
+  the surrounding composition already scales that way — e.g. a scoreboard
+  whose logo slots track height alone (`min(height, width // 2)`) should
+  size its text by `height / design_height` too, or the text reads as
+  under-scaled next to bigger logos on a panel that only grew taller.
+- `fit_lines(lines, box, ladder, spacing)` — every line fits the width and
+  the stack fits the height (measures the actual strings).
+- `font_for_rows(rows, box_h, ladder)` — largest rung whose line height
+  fits `rows` rows.
+
+`FitResult` carries the ready-to-use `font` (drops straight into
+`display_manager.draw_text(font=...)`), the possibly-ellipsized `text`,
+ink `width`/`height`, `baseline`, `y_offset`, `line_height`, and `fits`.
+
+## Adaptive images
+
+`src/adaptive_images.py` is the image counterpart to `fit_text`, exposed as
+`self.layout.fit_image(...)` (cached per panel size) and the one-liner
+`self.draw_image(...)`:
+
+```python
+# Team logo: trim its transparent padding, fill the slot height (the
+# football/hockey pattern), cached across frames by a stable key
+self.draw_image(logo, regs.away_slot, mode="fill_height",
+                crop_to_ink=True, cache_key=f"logo:{abbr}")
+
+# Album art: cover-crop a square, faces kept by the top anchor
+self.draw_image(art, row.art, mode="cover", anchor="top")
+
+# Pixel flags / sprite icons: NEAREST keeps hard edges
+from src.adaptive_images import RESAMPLE_NEAREST
+self.draw_image(flag, box, resample=RESAMPLE_NEAREST)
+```
+
+Modes: `contain` (letterbox, default), `cover` (crop-to-fill),
+`fill_height` (logo-style), `stretch`. Unlike PIL's `thumbnail()`
+(downscale-only — why imagery stays tiny on big panels) fitting **upscales
+by default**; pass `upscale=False` for the legacy behavior. Results are
+cached per (image, box size, options) with a bounded LRU — always pass a
+stable `cache_key` (e.g. `"logo:KC"`) for images you reload. The module
+also exports the Pillow-compat `RESAMPLE_LANCZOS`/`RESAMPLE_NEAREST`
+constants so plugins can drop their local shims.
+
+## Composite layouts
+
+Pre-carved Region arrangements for the layouts plugins keep rebuilding:
+
+```python
+from src.adaptive_layout import scoreboard_regions, media_row
+
+regs = scoreboard_regions(self.layout.bounds, ctx=self.layout)
+# regs.away_slot / home_slot   — logo slots (logo_slot = min(H, W // 2),
+#                                 capped so a center reserve always exists —
+#                                 see below)
+# regs.status_band             — top band (replaces the magic y = 1)
+# regs.score_area              — center gap, plus a controlled bleed into
+#                                 each logo slot (replaces y = H//2 - 3)
+# regs.detail_band             — bottom band (replaces y = H - 7)
+# regs.bottom_left / bottom_right — record/timeout corners
+
+row = media_row(self.layout.bounds, ctx=self.layout)   # art left, text right
+```
+
+Both work on the full panel or on a scroll-mode card Region. They return
+Regions and never draw — compose them with `draw_fit`/`draw_image`.
+
+**`scoreboard_regions`'s center reserve.** The raw `logo_slot = min(H, W//2)`
+formula has a blind spot: at exactly 2:1 aspect ratio (width = 2×height —
+two, four, or more square modules stacked into a taller panel, e.g.
+96x48, 128x64, 256x128) the two logo slots mathematically claim the
+*entire* width, leaving zero pixels for a center column no matter how
+big the panel gets. Wide panels (the 128x32 design baseline, 192x48,
+256x32) never hit this, since height is already the tighter constraint
+there. Two parameters fix it without any plugin-side code:
+`min_center_fraction`/`min_center_design_px` guarantee a real minimum
+center reserve at any aspect ratio, and `score_bleed_fraction` lets the
+score's *fit box* extend a controlled amount into each logo slot — the
+same way a real broadcast scoreboard's numbers cross slightly into the
+team marks flanking them — so a short score string never has to truncate
+even on the tightest aspect ratios. All three have sane defaults; override
+them per call if a plugin's card proportions genuinely differ.
+
+## Preserving user customization
+
+Adaptive layout supplies *defaults*; explicit user configuration wins:
+
+- **User-set fonts win.** If the plugin's config has an explicit
+  `font`/`font_size` for an element, load it as before and skip the ladder —
+  fit only when the user hasn't overridden (see the football-scoreboard
+  `_resolve_element_fit` pattern).
+- **Offsets apply on top.** `customization.layout.<element>.{x_offset,y_offset}`
+  style knobs translate the *computed* region as a final step:
+  `region.offset(user_dx, user_dy)`. `draw_image(..., offset=(dx, dy))`
+  does the same for images.
+- **Colors pass through.** `draw_fit`/`draw_fitted_text` take explicit
+  `color=` params; adaptive mode never repaints semantic or user-chosen
+  colors.
+
+## Manifest declaration
+
+Declare the size your layout was authored against so `ctx.scale` means
+something:
+
+```json
+"display": { "design_size": { "width": 128, "height": 32 } }
+```
+
+Also available under `requires.display_size`: `min_width`, `min_height`,
+`max_width`, `max_height`.
+
+## Performance notes (Pi)
+
+Fit queries are cached, so cost is O(unique strings). For per-second text
+(clocks, live scores), fit on a **shape placeholder** and reuse the font:
+
+```python
+fit = self.layout.fit_text("00:00", box, ladder=LADDER_ARCADE)  # cached once
+self.display_manager.draw_text(current_time, font=fit.font, ...)
+```
+
+## Testing across sizes
+
+The harness already renders every plugin at a spread of sizes (now
+including 96x48):
+
+```bash
+python scripts/check_plugin.py <plugin-dir> --sizes 64x32,128x32,96x48,128x64,256x64
+python scripts/render_plugin.py <plugin-dir> --width 96 --height 48
+```
+
+`BoundsCheckingDisplayManager` flags right/bottom overflow and now records
+mediated draw calls with negative coordinates in
+`negative_coordinate_calls` (raw-PIL draws remain uncovered).
+
+Reference migration: the **text-display** plugin's `font_mode: "auto"`.

docs/ADVANCED_PLUGIN_DEVELOPMENT.md

@@ -2,6 +2,12 @@
 
 Advanced patterns, examples, and best practices for developing LEDMatrix plugins.
 
+> **Adaptive layout:** for plugins that should render legibly on any panel
+> size (fonts that grow on big panels, layouts that degrade gracefully on
+> small ones), use the adaptive layout system — `self.layout`, `draw_fit`,
+> `draw_image`, `scoreboard_regions` — documented in
+> [ADAPTIVE_LAYOUT.md](ADAPTIVE_LAYOUT.md).
+
 ## Table of Contents
 
 - [Using Weather Icons](#using-weather-icons)

docs/DEVELOPER_QUICK_REFERENCE.md

@@ -48,6 +48,12 @@ display_manager.draw_text("Centered", centered=True)  # Auto-center
 width = display_manager.get_text_width("Text", font)
 height = display_manager.get_font_height(font)
 
+# Adaptive layout (recommended for multi-size support — text and images
+# that scale to any panel; see docs/ADAPTIVE_LAYOUT.md)
+rows = self.layout.bounds.inset(1).split_v(3, 1, gap=1)
+self.draw_fit("12:34", rows[0])                 # largest crisp font that fits
+self.draw_image(logo, rows[1], mode="fill_height", crop_to_ink=True)
+
 # Weather icons
 display_manager.draw_weather_icon("rain", x=10, y=10, size=16)
 

docs/DEV_PREVIEW.md

@@ -6,6 +6,12 @@ Tools for rapid plugin development without deploying to the RPi.
 
 Interactive web UI for tweaking plugin configs and seeing the rendered display in real time.
 
+The size inputs have a preset dropdown with the harness's standard panel
+sizes, and the **All Sizes** button renders the current config at every
+harness size in a side-by-side gallery (`POST /api/render-matrix`) — the
+quickest way to eyeball adaptive-layout behavior across panels
+(see [ADAPTIVE_LAYOUT.md](ADAPTIVE_LAYOUT.md)).
+
 ### Quick Start
 
 ```bash

docs/FONT_MANAGER.md

@@ -1,5 +1,12 @@
 # FontManager Usage Guide
 
+> **Picking a size automatically:** if you want the *largest font that fits
+> a given area* rather than a fixed size, use the adaptive layout system's
+> font ladders, which resolve through this FontManager. `BasePlugin`
+> subclasses get this as `self.layout.fit_text(...)`; other code can build
+> a `LayoutContext(width, height, font_manager)` directly — see
+> [ADAPTIVE_LAYOUT.md](ADAPTIVE_LAYOUT.md).
+
 ## Overview
 
 The enhanced FontManager provides comprehensive font management for the LEDMatrix application with support for:

docs/PLUGIN_API_REFERENCE.md

@@ -2,6 +2,11 @@
 
 Complete API reference for plugin developers. This document describes all methods and properties available to plugins through the Display Manager, Cache Manager, and Plugin Manager.
 
+> **Adaptive layout:** every `BasePlugin` also exposes `self.layout`,
+> `self.draw_fit(text, region)` and `self.draw_image(img, region, ...)` —
+> the recommended way to render text and images that scale to any panel
+> size. See [ADAPTIVE_LAYOUT.md](ADAPTIVE_LAYOUT.md).
+
 ## Table of Contents
 
 - [BasePlugin](#baseplugin)

docs/PLUGIN_ARCHITECTURE_SPEC.md

@@ -34,16 +34,16 @@ This document outlines the transformation of the LEDMatrix project into a modula
 
 ## Table of Contents
 
-1. [Current Architecture Analysis](#current-architecture-analysis)
-2. [Plugin System Design](#plugin-system-design)
-3. [Plugin Store & Discovery](#plugin-store--discovery)
-4. [Web UI Transformation](#web-ui-transformation)
-5. [Migration Strategy](#migration-strategy)
-6. [Plugin Developer Guidelines](#plugin-developer-guidelines)
-7. [Technical Implementation Details](#technical-implementation-details)
-8. [Best Practices & Standards](#best-practices--standards)
-9. [Security Considerations](#security-considerations)
-10. [Implementation Roadmap](#implementation-roadmap)
+1. [Current Architecture Analysis](#1-current-architecture-analysis)
+2. [Plugin System Design](#2-plugin-system-design)
+3. [Plugin Store & Discovery](#3-plugin-store--discovery)
+4. [Web UI Transformation](#4-web-ui-transformation)
+5. [Migration Strategy](#5-migration-strategy)
+6. [Plugin Developer Guidelines](#6-plugin-developer-guidelines)
+7. [Technical Implementation Details](#7-technical-implementation-details)
+8. [Best Practices & Standards](#8-best-practices--standards)
+9. [Security Considerations](#9-security-considerations)
+10. [Implementation Roadmap](#10-implementation-roadmap)
 
 ---
 

docs/PLUGIN_DEVELOPMENT_GUIDE.md

@@ -2,6 +2,14 @@
 
 This guide explains how to set up a development workflow for plugins that are maintained in separate Git repositories while still being able to test them within the LEDMatrix project.
 
+> **Rendering guidance:** plugins should read the display size dynamically
+> (`self.display_manager.matrix.width/height`) rather than hardcoding one
+> panel. For plugins that want to *scale* their layout to any panel, the
+> opt-in adaptive layout system ([ADAPTIVE_LAYOUT.md](ADAPTIVE_LAYOUT.md))
+> provides the shared helpers — fonts, images, and composite layouts that
+> scale. Existing plugins keep their classic rendering unless they adopt
+> those APIs; nothing migrates automatically.
+
 ## Overview
 
 When developing plugins in separate repositories, you need a way to:

docs/plugin-safety-harness.md

@@ -0,0 +1,136 @@
+# Plugin Safety Harness
+
+Renders a plugin across **every declared screen (mode)** and **a spread of
+matrix sizes**, and fails if any combination crashes, draws past the panel edge,
+or — for plugins that ship golden images — drifts visually. The goal: change a
+plugin without breaking a size or screen you didn't think to test.
+
+## Sizes: a sample, not a fixed list
+
+There is **no fixed set of supported panel sizes** — an RGB matrix build can be
+any width/height and configuration (square, rectangle, 2×2, 4×4, 8×2, long
+strips, tall stacks). Plugins are expected to read dimensions dynamically
+(`self.display_manager.matrix.width/height`) and lay themselves out
+accordingly, so a hardcoded coordinate or unscaled font shows up as a failure
+here.
+
+The harness therefore renders against a **representative sample** that spans the
+axes of variation (`DEFAULT_TEST_SIZES` in `src/plugin_system/testing/sizes.py`),
+not an authoritative list:
+
+Each module is 64×32; entries are real panel-grid arrangements (cols × rows):
+
+| Size    | Grid | Why it's in the sample                     |
+|---------|------|--------------------------------------------|
+| 64×32   | 1×1  | single panel — tightest common rectangle   |
+| 128×32  | 2×1  | the baseline most plugins are tuned for    |
+| 64×64   | 1×2  | stacked — tall-narrow centering            |
+| 128×64  | 2×2  | block — icon scaling / vertical centering  |
+| 256×32  | 4×1  | long strip — wide horizontal layout        |
+| 128×96  | 2×3  | tall — vertical overflow                   |
+| 256×128 | 4×4  | large block — both dimensions big at once  |
+
+**Override the sizes entirely** to test your actual hardware (or any shape):
+
+```bash
+# CLI — one-off:
+python scripts/check_plugin.py --plugin clock-simple --sizes 8x16,64x64,256x32
+
+# pytest — force every plugin onto your panel(s):
+LEDMATRIX_TEST_SIZES="8x16,128x128" pytest test/plugins/test_plugin_matrix.py
+
+# Per-plugin — declare the shapes a plugin targets in its test/harness.json:
+#   { "sizes": [[8, 16], [64, 64]] }
+```
+
+Precedence: `LEDMATRIX_TEST_SIZES` env (global) → per-plugin `harness.json`
+`sizes` → the default sample. Bounds checking adapts to whatever sizes a run
+uses — the backing canvas is padded out to the **largest** panel in the run, so
+a coordinate meant for a big build is still caught when rendering a small one.
+
+## Quick start
+
+```bash
+# Functional + bounds check across all sizes/screens:
+python scripts/check_plugin.py --plugin clock-simple
+
+# Every discovered plugin:
+python scripts/check_plugin.py --all
+
+# Dump PNGs to eyeball each size/screen:
+python scripts/check_plugin.py --plugin ledmatrix-weather --out-dir /tmp/preview
+```
+
+Exit code is non-zero if any `(plugin, size, screen)` fails. Plugins are
+discovered in `plugin-repos/` and `plugins/` (override with `--plugin-dir`).
+
+## What it checks (Phase 1 — always on)
+
+1. **Loads** and builds its mode list.
+2. **Renders every screen** at every size without raising. `update()` may fail
+   (no network in CI) and is tolerated; a crash in `display()` is a failure —
+   `display()` must handle the no-data state.
+3. **Bounds**: nothing is drawn past the right/bottom edge. Implemented by
+   `BoundsCheckingDisplayManager`, which backs the declared panel with an
+   oversized canvas and flags any pixels that land in the margin. (Left/top
+   overflow at negative coordinates and BDF text are not flagged — golden images
+   cover those.)
+
+## Golden images (Phase 2 — opt-in per plugin)
+
+A plugin opts in by committing reference PNGs and (usually) a small harness spec:
+
+```
+plugins/<id>/test/harness.json          # how to render deterministically
+plugins/<id>/test/fixtures/mock.json     # optional cached data
+plugins/<id>/test/golden/<WxH>/<mode>.png
+```
+
+`test/harness.json` keys (all optional):
+
+```json
+{
+  "config":      { "timezone": "UTC" },
+  "mock_data":   "fixtures/mock.json",
+  "freeze_time": "2025-08-01 15:25:00",
+  "skip_update": false,
+  "sizes":       [[128, 32], [128, 64]]
+}
+```
+
+Generate / refresh goldens after an intentional visual change, then review the
+diff before committing:
+
+```bash
+python scripts/check_plugin.py --plugin clock-simple --update-golden \
+  --config '{"timezone":"UTC"}' --freeze-time "2025-08-01 15:25:00"
+```
+
+Comparison is exact by default (`compare_images` in `harness.py` accepts a
+tolerance for known anti-aliasing noise). Determinism requires a pinned Pillow
+and the bundled fonts — keep both stable when regenerating goldens.
+
+## Tests & CI
+
+- `test/plugins/test_harness.py` — unit tests for bounds detection, image
+  comparison, and mode enumeration (run anywhere).
+- `test/plugins/test_plugin_matrix.py` — parametrized over discovered plugins ×
+  sizes × screens; honors each plugin's `test/harness.json` and goldens. Skips
+  when no plugins are present (e.g. a fresh core checkout); set
+  `LEDMATRIX_REQUIRE_PLUGINS=1` in a pipeline where plugins must be present to
+  turn an empty discovery into a hard failure instead. Point it at the monorepo
+  with `LEDMATRIX_PLUGINS_DIR=/path/to/ledmatrix-plugins/plugins`.
+- `.github/workflows/test.yml` — runs the harness + visual tests on every PR.
+
+The plugin monorepo has its own `Plugin Safety` workflow that runs this harness
+against changed plugins on every PR.
+
+## Developer workflow
+
+1. Change the plugin on a branch.
+2. `python scripts/check_plugin.py --plugin <id> --out-dir /tmp/preview` and
+   eyeball the PNGs.
+3. Intentional visual change? `--update-golden`, review diffs, commit goldens.
+4. (Monorepo) bump `manifest.json` version and let the pre-commit hook sync
+   `plugins.json`.
+5. Push — CI re-runs the harness across all sizes and gates the PR.

docs/widget-guide.md

@@ -10,6 +10,98 @@ The LEDMatrix Widget Registry system allows plugins to use reusable UI component
 
 ## Available Core Widgets
 
+### Plugin File Manager Widget (`plugin-file-manager`)
+
+Full inline file management UI for plugins that manage files via the `web_ui_actions` system. Renders a card grid, upload zone, create/delete modals, and an entry table editor — entirely inline, no iframe.
+
+`plugin_id` is **automatically injected** from template context. File operations call `/api/v3/plugins/action` immediately on user action; no Save Configuration needed.
+
+**Schema Configuration:**
+```json
+{
+  "file_manager": {
+    "type": "null",
+    "title": "Data Files",
+    "x-widget": "plugin-file-manager",
+    "x-widget-config": {
+      "actions": {
+        "list":   "list-files",
+        "get":    "get-file",
+        "save":   "save-file",
+        "upload": "upload-file",
+        "delete": "delete-file",
+        "create": "create-file",
+        "toggle": "toggle-category"
+      },
+      "upload_hint":      "JSON files with day numbers 1–365 as keys",
+      "directory_label":  "my_data/",
+      "create_fields": [
+        { "key": "category_name", "label": "Category Name",
+          "placeholder": "e.g., my_words", "pattern": "^[a-z0-9_]+$",
+          "hint": "Lowercase letters, numbers, underscores" },
+        { "key": "display_name", "label": "Display Name",
+          "placeholder": "e.g., My Words", "hint": "Optional" }
+      ]
+    }
+  }
+}
+```
+
+**`list` is required** — the widget calls it on render to populate the file grid; omitting it leaves the widget stuck in a loading state. All other actions are optional — omit any key to hide its UI element (e.g., no `create` = no New File button, no `toggle` = no enable/disable switch).
+
+The edit view auto-detects whether file content is tabular (object-of-objects with uniform keys) and shows a paginated table editor with inline cells. Otherwise falls back to a JSON textarea.
+
+**Used by:** of-the-day
+
+---
+
+### Time Picker Widget (`time-picker`)
+
+Single time selection using the browser's native time input. Returns a string in `HH:MM` (24-hour) format. Generic — works in any plugin without configuration.
+
+**Schema Configuration:**
+```json
+{
+  "target_time": {
+    "type": "string",
+    "x-widget": "time-picker",
+    "default": "00:00",
+    "x-options": {
+      "placeholder": "Select time",
+      "clearable": true
+    }
+  }
+}
+```
+
+**Used by:** countdown
+
+---
+
+### File Upload Single Widget (`file-upload-single`)
+
+Single-image upload for string fields. Uploads to the plugin's asset folder (`assets/plugins/<plugin_id>/uploads/`) and sets the string field value to the returned relative path. Shows a thumbnail preview and a clear button. The `plugin_id` is **automatically injected** from the template context — no need to specify it in the schema.
+
+**Schema Configuration:**
+```json
+{
+  "image_path": {
+    "type": "string",
+    "x-widget": "file-upload-single",
+    "x-upload-config": {
+      "allowed_types": ["image/png", "image/jpeg", "image/bmp", "image/gif"],
+      "max_size_mb": 5
+    }
+  }
+}
+```
+
+Note: Unlike `file-upload` (array-level), this widget is for a single `string` field. It is ideal for per-item images inside `array-table` rows.
+
+**Used by:** countdown
+
+---
+
 ### File Upload Widget (`file-upload`)
 
 Upload and manage image files with drag-and-drop support, preview, delete, and scheduling.

first_time_install.sh

@@ -15,8 +15,8 @@ on_error() {
     echo "✗ An error occurred during: $CURRENT_STEP (line $line_no, exit $exit_code)" >&2
     if [ -n "${LOG_FILE:-}" ]; then
         echo "See the log for details: $LOG_FILE" >&2
-        echo "-- Last 50 lines from log --" >&2
-        tail -n 50 "$LOG_FILE" >&2 || true
+        echo "-- Last 100 lines from log --" >&2
+        tail -n 100 "$LOG_FILE" >&2 || true
     fi
     echo "\nCommon fixes:" >&2
     echo "- Ensure the Pi is online (try: ping -c1 8.8.8.8)." >&2
@@ -36,9 +36,17 @@ if [ -r /proc/device-tree/model ]; then
     DEVICE_MODEL=$(tr -d '\0' </proc/device-tree/model)
     echo "Detected device: $DEVICE_MODEL"
 else
+    DEVICE_MODEL=""
     echo "⚠ Could not detect Raspberry Pi model (continuing anyway)"
 fi
 
+# Detect Pi 5 for hardware-specific install decisions (RP1 library verification)
+IS_PI5=0
+if echo "${DEVICE_MODEL:-}" | grep -qi "Raspberry Pi 5"; then
+    IS_PI5=1
+    echo "Raspberry Pi 5 detected — will verify RP1 library support."
+fi
+
 # Check OS version - must be Raspberry Pi OS Lite (Trixie)
 echo ""
 echo "Checking operating system requirements..."
@@ -194,8 +202,33 @@ retry() {
     done
 }
 
-apt_update() { retry apt update; }
-apt_install() { retry apt install -y "$@"; }
+# Wait for another apt/dpkg process (commonly unattended-upgrades running
+# shortly after first boot) to release its lock before we try apt ourselves.
+# Without this, apt_update/apt_install can fail outright in the first couple
+# minutes after a fresh Pi OS boot with a generic "Command failed after 3
+# attempts" error.
+wait_for_apt_lock() {
+    command -v flock >/dev/null 2>&1 || return 0
+    local lock_file="/var/lib/dpkg/lock-frontend"
+    local max_wait=180
+    local waited=0
+    local printed=0
+    while ! flock -n "$lock_file" -c true 2>/dev/null; do
+        if [ "$printed" -eq 0 ]; then
+            echo "⚠ Waiting for another apt/dpkg process to finish (e.g. unattended-upgrades on first boot)..."
+            printed=1
+        fi
+        if [ "$waited" -ge "$max_wait" ]; then
+            echo "⚠ Still waiting after ${max_wait}s; proceeding anyway."
+            break
+        fi
+        sleep 5
+        waited=$((waited+5))
+    done
+}
+
+apt_update() { wait_for_apt_lock; retry apt-get -o DPkg::Lock::Timeout=180 update; }
+apt_install() { wait_for_apt_lock; retry apt-get -o DPkg::Lock::Timeout=180 install -y "$@"; }
 apt_remove() { apt-get remove -y "$@" || true; }
 
 check_network() {
@@ -214,6 +247,22 @@ check_network() {
     exit 1
 }
 
+check_disk_space() {
+    command -v df >/dev/null 2>&1 || return 0
+    local available_mb
+    available_mb=$(df -m "$PROJECT_ROOT_DIR" | awk 'NR==2{print $4}')
+    available_mb=${available_mb:-0}
+    if [ "$available_mb" -lt 500 ]; then
+        echo "✗ ERROR: Insufficient disk space: ${available_mb}MB available (need at least 500MB)"
+        echo "  Free up space first, e.g.: sudo apt clean && sudo apt autoremove"
+        exit 1
+    elif [ "$available_mb" -lt 1024 ]; then
+        echo "⚠ Limited disk space: ${available_mb}MB available (recommend at least 1GB for the rpi-rgb-led-matrix build in Step 6)"
+    else
+        echo "✓ Disk space sufficient: ${available_mb}MB available"
+    fi
+}
+
 echo ""
 echo "This script will perform the following steps:"
 echo "1. Install system dependencies"
@@ -259,21 +308,20 @@ else
 fi
 
 echo ""
-CLEAR='
-'
 CURRENT_STEP="Install system dependencies"
 echo "Step 1: Installing system dependencies..."
 echo "----------------------------------------"
 
-# Ensure network is available before APT operations
+# Pre-flight checks before APT operations
 check_network
+check_disk_space
 
 # Update package list
 apt_update
 
 # Install required system packages
 echo "Installing Python packages and dependencies..."
-apt_install python3-pip python3-venv python3-dev python3-pil python3-pil.imagetk build-essential python3-setuptools python3-wheel cython3 scons cmake ninja-build
+apt_install python3-pip python3-venv python-dev-is-python3 python3-pil python3-pil.imagetk build-essential python3-setuptools python3-wheel cmake ninja-build
 
 # Install additional system dependencies that might be needed
 echo "Installing additional system dependencies..."
@@ -671,8 +719,6 @@ if [ -f "$PROJECT_ROOT_DIR/requirements.txt" ]; then
         echo "[$PACKAGE_NUM/$TOTAL_PACKAGES] Installing: $line"
         
         # Check if package is already installed (basic check - may not catch all cases)
-        PACKAGE_NAME=$(echo "$line" | sed -E 's/[<>=!].*$//' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
-        
         # Try installing with verbose output and timeout (if available)
         # Use --no-cache-dir to avoid cache issues, --verbose for diagnostics
         INSTALL_OUTPUT=$(mktemp)
@@ -680,7 +726,11 @@ if [ -f "$PROJECT_ROOT_DIR/requirements.txt" ]; then
         
         if command -v timeout >/dev/null 2>&1; then
             # Use timeout if available (10 minutes = 600 seconds)
-            if timeout 600 python3 -m pip install --break-system-packages --no-cache-dir --prefer-binary --verbose "$line" > "$INSTALL_OUTPUT" 2>&1; then
+            # --ignore-installed: apt-managed packages (e.g. python3-requests)
+            # ship no pip RECORD file, so upgrading them would otherwise abort
+            # with "uninstall-no-record-file"; this lays the new version down
+            # alongside instead of trying to uninstall the apt copy first.
+            if timeout 600 python3 -m pip install --break-system-packages --no-cache-dir --prefer-binary --ignore-installed --verbose "$line" > "$INSTALL_OUTPUT" 2>&1; then
                 INSTALL_SUCCESS=true
             else
                 EXIT_CODE=$?
@@ -688,7 +738,7 @@ if [ -f "$PROJECT_ROOT_DIR/requirements.txt" ]; then
                     echo "✗ Timeout (10 minutes) installing: $line"
                     echo "  This package may require building from source, which can be slow on Raspberry Pi."
                     echo "  You can try installing it manually later with:"
-                    echo "    python3 -m pip install --break-system-packages --no-cache-dir --prefer-binary --verbose '$line'"
+                    echo "    python3 -m pip install --break-system-packages --no-cache-dir --prefer-binary --ignore-installed --verbose '$line'"
                 else
                     echo "✗ Failed to install: $line (exit code: $EXIT_CODE)"
                 fi
@@ -696,7 +746,7 @@ if [ -f "$PROJECT_ROOT_DIR/requirements.txt" ]; then
         else
             # No timeout command available, install without timeout
             echo "  Note: timeout command not available, installation may take a while..."
-            if python3 -m pip install --break-system-packages --no-cache-dir --prefer-binary --verbose "$line" > "$INSTALL_OUTPUT" 2>&1; then
+            if python3 -m pip install --break-system-packages --no-cache-dir --prefer-binary --ignore-installed --verbose "$line" > "$INSTALL_OUTPUT" 2>&1; then
                 INSTALL_SUCCESS=true
             else
                 EXIT_CODE=$?
@@ -748,7 +798,7 @@ if [ -f "$PROJECT_ROOT_DIR/requirements.txt" ]; then
         echo "  1. Ensure you have enough disk space: df -h"
         echo "  2. Check available memory: free -h"
         echo "  3. Try installing failed packages individually with verbose output:"
-        echo "     python3 -m pip install --break-system-packages --no-cache-dir --prefer-binary --verbose <package>"
+        echo "     python3 -m pip install --break-system-packages --no-cache-dir --prefer-binary --ignore-installed --verbose <package>"
         echo "  4. For packages that build from source (like numpy), consider:"
         echo "     - Installing pre-built wheels: python3 -m pip install --only-binary :all: <package>"
         echo "     - Or installing via apt if available: sudo apt install python3-<package>"
@@ -770,7 +820,10 @@ echo ""
 # Install web interface dependencies
 echo "Installing web interface dependencies..."
 if [ -f "$PROJECT_ROOT_DIR/web_interface/requirements.txt" ]; then
-    if python3 -m pip install --break-system-packages --prefer-binary -r "$PROJECT_ROOT_DIR/web_interface/requirements.txt"; then
+    # --ignore-installed: apt-managed packages (e.g. python3-requests) ship no
+    # pip RECORD file, so upgrading them to the version pinned here would
+    # otherwise abort the whole install with "uninstall-no-record-file".
+    if python3 -m pip install --break-system-packages --prefer-binary --ignore-installed -r "$PROJECT_ROOT_DIR/web_interface/requirements.txt"; then
         echo "✓ Web interface dependencies installed"
         # Create marker file to indicate dependencies are installed
         touch "$PROJECT_ROOT_DIR/.web_deps_installed"
@@ -787,29 +840,54 @@ CURRENT_STEP="Build and install rpi-rgb-led-matrix"
 echo "Step 6: Building and installing rpi-rgb-led-matrix..."
 echo "-----------------------------------------------------"
 
-# If already installed and not forcing rebuild, skip expensive build
+# On Pi 5, also check that the installed library has rp1_rio support.
+# A library built before Pi 5 support was added imports fine but maps to the
+# Pi 3 peripheral bus address (0x3f000000) instead of the RP1 chip at runtime.
+_HAS_RP1=0
+if python3 -c 'from rgbmatrix import RGBMatrixOptions; assert hasattr(RGBMatrixOptions(), "rp1_rio")' >/dev/null 2>&1; then
+    _HAS_RP1=1
+fi
+
+_SKIP_BUILD=0
 if python3 -c 'from rgbmatrix import RGBMatrix, RGBMatrixOptions' >/dev/null 2>&1 && [ "${RPI_RGB_FORCE_REBUILD:-0}" != "1" ]; then
-    echo "rgbmatrix Python package already available; skipping build (set RPI_RGB_FORCE_REBUILD=1 to force rebuild)."
+    if [ "$IS_PI5" = "1" ] && [ "$_HAS_RP1" = "0" ]; then
+        echo "⚠ Pi 5 detected: installed rgbmatrix lacks rp1_rio support (older build)."
+        echo "  Forcing rebuild to get Pi 5 RP1 support..."
+    else
+        _SKIP_BUILD=1
+    fi
+fi
+
+if [ "$_SKIP_BUILD" = "1" ]; then
+    _skip_suffix=""
+    if [ "$IS_PI5" = "1" ]; then _skip_suffix=" with Pi 5 RP1 support"; fi
+    echo "rgbmatrix already installed${_skip_suffix}; skipping build (set RPI_RGB_FORCE_REBUILD=1 to force rebuild)."
 else
     # Ensure rpi-rgb-led-matrix submodule is initialized
+    # Wrapper used with retry(): removes any partial clone dir before each attempt
+    # so git clone doesn't fail with "destination path already exists".
+    _clone_rpi_rgb() {
+        rm -rf "$PROJECT_ROOT_DIR/rpi-rgb-led-matrix-master"
+        git clone https://github.com/hzeller/rpi-rgb-led-matrix.git rpi-rgb-led-matrix-master
+    }
     if [ ! -d "$PROJECT_ROOT_DIR/rpi-rgb-led-matrix-master" ]; then
         echo "rpi-rgb-led-matrix-master not found. Initializing git submodule..."
         cd "$PROJECT_ROOT_DIR"
-        
+
         # Try to initialize submodule if .gitmodules exists
         if [ -f "$PROJECT_ROOT_DIR/.gitmodules" ] && grep -q "rpi-rgb-led-matrix" "$PROJECT_ROOT_DIR/.gitmodules"; then
             echo "Initializing rpi-rgb-led-matrix submodule..."
-            if ! git submodule update --init --recursive rpi-rgb-led-matrix-master 2>&1; then
+            if ! retry git submodule update --init --recursive rpi-rgb-led-matrix-master; then
                 echo "⚠ Submodule init failed, cloning directly from GitHub..."
-                git clone https://github.com/hzeller/rpi-rgb-led-matrix.git rpi-rgb-led-matrix-master
+                retry _clone_rpi_rgb
             fi
         else
             # Fallback: clone directly if submodule not configured
             echo "Submodule not configured, cloning directly from GitHub..."
-            git clone https://github.com/hzeller/rpi-rgb-led-matrix.git rpi-rgb-led-matrix-master
+            retry _clone_rpi_rgb
         fi
     fi
-    
+
     # Build and install rpi-rgb-led-matrix Python bindings
     if [ -d "$PROJECT_ROOT_DIR/rpi-rgb-led-matrix-master" ]; then
         # Check if submodule is properly initialized (not empty)
@@ -818,30 +896,34 @@ else
             cd "$PROJECT_ROOT_DIR"
             rm -rf rpi-rgb-led-matrix-master
             if [ -f "$PROJECT_ROOT_DIR/.gitmodules" ] && grep -q "rpi-rgb-led-matrix" "$PROJECT_ROOT_DIR/.gitmodules"; then
-                git submodule update --init --recursive rpi-rgb-led-matrix-master
+                retry git submodule update --init --recursive rpi-rgb-led-matrix-master
             else
-                git clone https://github.com/hzeller/rpi-rgb-led-matrix.git rpi-rgb-led-matrix-master
+                retry _clone_rpi_rgb
             fi
         fi
-        
+
         pushd "$PROJECT_ROOT_DIR/rpi-rgb-led-matrix-master" >/dev/null
-        echo "Building rpi-rgb-led-matrix Python bindings..."
-        # Build the library first, then Python bindings
-        # The build-python target depends on the library being built
-        if ! make build-python; then
-            echo "✗ Failed to build rpi-rgb-led-matrix Python bindings"
-            echo "  Make sure you have the required build tools installed:"
-            echo "  sudo apt install -y build-essential python3-dev cython3 scons"
-            popd >/dev/null
-            exit 1
+        echo "Installing rpi-rgb-led-matrix Python package (scikit-build-core + cmake)..."
+        echo "  Build deps required: python-dev-is-python3 cmake"
+        echo "  This compiles C++ — may take 2-5 minutes on Pi 4/5..."
+        BUILD_OUTPUT=$(mktemp)
+        BUILD_SUCCESS=false
+        if python3 -m pip install --break-system-packages . > "$BUILD_OUTPUT" 2>&1; then
+            BUILD_SUCCESS=true
         fi
-        cd bindings/python
-        echo "Installing rpi-rgb-led-matrix Python package via pip..."
-        if ! python3 -m pip install --break-system-packages .; then
+        cat "$BUILD_OUTPUT" >> "$LOG_FILE"
+        if [ "$BUILD_SUCCESS" != true ]; then
             echo "✗ Failed to install rpi-rgb-led-matrix Python package"
+            echo "  Ensure build tools are installed:"
+            echo "  sudo apt install -y python-dev-is-python3 cmake build-essential"
+            echo ""
+            echo "-- Last 50 lines of build output --"
+            tail -n 50 "$BUILD_OUTPUT"
+            rm -f "$BUILD_OUTPUT"
             popd >/dev/null
             exit 1
         fi
+        rm -f "$BUILD_OUTPUT"
         popd >/dev/null
     else
         echo "✗ rpi-rgb-led-matrix-master directory not found at $PROJECT_ROOT_DIR"
@@ -863,6 +945,17 @@ except Exception as e:
 PY
     then
         echo "✓ rpi-rgb-led-matrix installed and verified"
+        # Pi 5: confirm the freshly-built library has rp1_rio support
+        if [ "$IS_PI5" = "1" ]; then
+            if python3 -c 'from rgbmatrix import RGBMatrixOptions; assert hasattr(RGBMatrixOptions(), "rp1_rio")' >/dev/null 2>&1; then
+                echo "✓ Pi 5 RP1 (rp1_rio) support confirmed"
+            else
+                echo "⚠ rp1_rio not found after rebuild — the submodule may be an older version."
+                echo "  Try updating the submodule and rebuilding:"
+                echo "    git submodule update --remote rpi-rgb-led-matrix-master"
+                echo "    sudo RPI_RGB_FORCE_REBUILD=1 ./first_time_install.sh"
+            fi
+        fi
     else
         echo "✗ rpi-rgb-led-matrix import test failed"
         exit 1
@@ -885,11 +978,15 @@ else
     # Try to install dependencies using the smart installer if available
     if [ -f "$PROJECT_ROOT_DIR/scripts/install_dependencies_apt.py" ]; then
         echo "Using smart dependency installer..."
-        python3 "$PROJECT_ROOT_DIR/scripts/install_dependencies_apt.py"
+        # -u: unbuffered stdout/stderr so output is captured in $LOG_FILE in
+        # real time and in order relative to this script's own echo statements
+        python3 -u "$PROJECT_ROOT_DIR/scripts/install_dependencies_apt.py"
     else
         echo "Using pip to install dependencies..."
         if [ -f "$PROJECT_ROOT_DIR/requirements_web_v2.txt" ]; then
-            python3 -m pip install --break-system-packages --prefer-binary -r requirements_web_v2.txt
+            # --ignore-installed: see the Step 5 web_interface/requirements.txt
+            # install above — same apt/pip RECORD-file conflict applies here.
+            python3 -m pip install --break-system-packages --prefer-binary --ignore-installed -r requirements_web_v2.txt
         else
             echo "⚠ requirements_web_v2.txt not found; skipping web dependency install"
         fi
@@ -1110,6 +1207,7 @@ $ACTUAL_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH restart ledmatrix-web.service
 $ACTUAL_USER ALL=(ALL) NOPASSWD: $PYTHON_PATH $PROJECT_ROOT_DIR/display_controller.py
 $ACTUAL_USER ALL=(ALL) NOPASSWD: $BASH_PATH $PROJECT_ROOT_DIR/start_display.sh
 $ACTUAL_USER ALL=(ALL) NOPASSWD: $BASH_PATH $PROJECT_ROOT_DIR/stop_display.sh
+$ACTUAL_USER ALL=(ALL) NOPASSWD: $BASH_PATH $PROJECT_ROOT_DIR/scripts/fix_perms/safe_plugin_rm.sh *
 EOF
 if [ -n "$JOURNALCTL_PATH" ]; then
     cat >> /tmp/ledmatrix_web_sudoers << EOF
@@ -1478,7 +1576,7 @@ echo "WiFi Connection Status:"
 if command -v nmcli >/dev/null 2>&1; then
     WIFI_STATUS=$(nmcli -t -f DEVICE,TYPE,STATE device status 2>/dev/null | grep -i wifi || echo "")
     if [ -n "$WIFI_STATUS" ]; then
-        echo "$WIFI_STATUS" | while IFS=':' read -r device type state; do
+        echo "$WIFI_STATUS" | while IFS=':' read -r _ _ state; do
             if [ "$state" = "connected" ]; then
                 SSID=$(nmcli -t -f active,ssid device wifi 2>/dev/null | grep "^yes:" | cut -d: -f2 | head -1)
                 if [ -n "$SSID" ]; then

plugin-repos/march-madness/config_schema.json

@@ -1,138 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "March Madness Plugin Configuration",
-  "type": "object",
-  "properties": {
-    "enabled": {
-      "type": "boolean",
-      "default": false,
-      "description": "Enable the March Madness tournament display"
-    },
-    "leagues": {
-      "type": "object",
-      "title": "Tournament Leagues",
-      "description": "Which NCAA tournaments to display",
-      "properties": {
-        "ncaam": {
-          "type": "boolean",
-          "default": true,
-          "description": "Show NCAA Men's Tournament games"
-        },
-        "ncaaw": {
-          "type": "boolean",
-          "default": true,
-          "description": "Show NCAA Women's Tournament games"
-        }
-      },
-      "additionalProperties": false
-    },
-    "favorite_teams": {
-      "type": "array",
-      "title": "Favorite Teams",
-      "description": "Team abbreviations to highlight (e.g., DUKE, UNC). Leave empty to show all teams equally.",
-      "items": {
-        "type": "string"
-      },
-      "uniqueItems": true,
-      "default": []
-    },
-    "display_options": {
-      "type": "object",
-      "title": "Display Options",
-      "x-collapsed": true,
-      "properties": {
-        "show_seeds": {
-          "type": "boolean",
-          "default": true,
-          "description": "Show tournament seeds (1-16) next to team names"
-        },
-        "show_round_logos": {
-          "type": "boolean",
-          "default": true,
-          "description": "Show round logo separators between game groups"
-        },
-        "highlight_upsets": {
-          "type": "boolean",
-          "default": true,
-          "description": "Highlight upset winners (higher seed beating lower seed) in gold"
-        },
-        "show_bracket_progress": {
-          "type": "boolean",
-          "default": true,
-          "description": "Show which teams are still alive in each region"
-        },
-        "scroll_speed": {
-          "type": "number",
-          "default": 1.0,
-          "minimum": 0.5,
-          "maximum": 5.0,
-          "description": "Scroll speed (pixels per frame)"
-        },
-        "scroll_delay": {
-          "type": "number",
-          "default": 0.02,
-          "minimum": 0.001,
-          "maximum": 0.1,
-          "description": "Delay between scroll frames (seconds)"
-        },
-        "target_fps": {
-          "type": "integer",
-          "default": 120,
-          "minimum": 30,
-          "maximum": 200,
-          "description": "Target frames per second"
-        },
-        "loop": {
-          "type": "boolean",
-          "default": true,
-          "description": "Loop the scroll continuously"
-        },
-        "dynamic_duration": {
-          "type": "boolean",
-          "default": true,
-          "description": "Automatically adjust display duration based on content width"
-        },
-        "min_duration": {
-          "type": "integer",
-          "default": 30,
-          "minimum": 10,
-          "maximum": 300,
-          "description": "Minimum display duration in seconds"
-        },
-        "max_duration": {
-          "type": "integer",
-          "default": 300,
-          "minimum": 30,
-          "maximum": 600,
-          "description": "Maximum display duration in seconds"
-        }
-      },
-      "additionalProperties": false
-    },
-    "data_settings": {
-      "type": "object",
-      "title": "Data Settings",
-      "x-collapsed": true,
-      "properties": {
-        "update_interval": {
-          "type": "integer",
-          "default": 300,
-          "minimum": 60,
-          "maximum": 3600,
-          "description": "How often to refresh tournament data (seconds). Automatically shortens to 60s when live games are detected."
-        },
-        "request_timeout": {
-          "type": "integer",
-          "default": 30,
-          "minimum": 5,
-          "maximum": 60,
-          "description": "API request timeout in seconds"
-        }
-      },
-      "additionalProperties": false
-    }
-  },
-  "required": ["enabled"],
-  "additionalProperties": false,
-  "x-propertyOrder": ["enabled", "leagues", "favorite_teams", "display_options", "data_settings"]
-}

plugin-repos/march-madness/manager.py

@@ -1,910 +0,0 @@
-"""March Madness Plugin — NCAA Tournament bracket tracker for LED Matrix.
-
-Displays a horizontally-scrolling ticker of NCAA Tournament games grouped by
-round, with seeds, round logos, live scores, and upset highlighting.
-"""
-
-import re
-import threading
-import time
-from datetime import datetime, timedelta, timezone
-from pathlib import Path
-from typing import Any, Dict, List, Optional
-
-import numpy as np
-import pytz
-import requests
-from PIL import Image, ImageDraw, ImageFont
-from requests.adapters import HTTPAdapter
-from urllib3.util.retry import Retry
-
-from src.plugin_system.base_plugin import BasePlugin
-
-try:
-    from src.common.scroll_helper import ScrollHelper
-except ImportError:
-    ScrollHelper = None
-
-
-# ---------------------------------------------------------------------------
-# Constants
-# ---------------------------------------------------------------------------
-
-SCOREBOARD_URLS = {
-    "ncaam": "https://site.api.espn.com/apis/site/v2/sports/basketball/mens-college-basketball/scoreboard",
-    "ncaaw": "https://site.api.espn.com/apis/site/v2/sports/basketball/womens-college-basketball/scoreboard",
-}
-
-ROUND_ORDER = {"NCG": 0, "F4": 1, "E8": 2, "S16": 3, "R32": 4, "R64": 5, "": 6}
-
-ROUND_DISPLAY_NAMES = {
-    "NCG": "Championship",
-    "F4": "Final Four",
-    "E8": "Elite Eight",
-    "S16": "Sweet Sixteen",
-    "R32": "Round of 32",
-    "R64": "Round of 64",
-}
-
-ROUND_LOGO_FILES = {
-    "NCG": "CHAMPIONSHIP.png",
-    "F4": "FINAL_4.png",
-    "E8": "ELITE_8.png",
-    "S16": "SWEET_16.png",
-    "R32": "ROUND_32.png",
-    "R64": "ROUND_64.png",
-}
-
-REGION_ORDER = {"E": 0, "W": 1, "S": 2, "MW": 3, "": 4}
-
-# Colors
-COLOR_WHITE = (255, 255, 255)
-COLOR_GOLD = (255, 215, 0)
-COLOR_GRAY = (160, 160, 160)
-COLOR_DIM = (100, 100, 100)
-COLOR_RED = (255, 60, 60)
-COLOR_GREEN = (60, 200, 60)
-COLOR_BLACK = (0, 0, 0)
-COLOR_DARK_BG = (20, 20, 20)
-
-
-# ---------------------------------------------------------------------------
-# Plugin Class
-# ---------------------------------------------------------------------------
-
-class MarchMadnessPlugin(BasePlugin):
-    """NCAA March Madness tournament bracket tracker."""
-
-    def __init__(
-        self,
-        plugin_id: str,
-        config: Dict[str, Any],
-        display_manager: Any,
-        cache_manager: Any,
-        plugin_manager: Any,
-    ):
-        super().__init__(plugin_id, config, display_manager, cache_manager, plugin_manager)
-
-        # Config
-        leagues_config = config.get("leagues", {})
-        self.show_ncaam: bool = leagues_config.get("ncaam", True)
-        self.show_ncaaw: bool = leagues_config.get("ncaaw", True)
-        self.favorite_teams: List[str] = [t.upper() for t in config.get("favorite_teams", [])]
-
-        display_options = config.get("display_options", {})
-        self.show_seeds: bool = display_options.get("show_seeds", True)
-        self.show_round_logos: bool = display_options.get("show_round_logos", True)
-        self.highlight_upsets: bool = display_options.get("highlight_upsets", True)
-        self.show_bracket_progress: bool = display_options.get("show_bracket_progress", True)
-        self.scroll_speed: float = display_options.get("scroll_speed", 1.0)
-        self.scroll_delay: float = display_options.get("scroll_delay", 0.02)
-        self.target_fps: int = display_options.get("target_fps", 120)
-        self.loop: bool = display_options.get("loop", True)
-        self.dynamic_duration_enabled: bool = display_options.get("dynamic_duration", True)
-        self.min_duration: int = display_options.get("min_duration", 30)
-        self.max_duration: int = display_options.get("max_duration", 300)
-        if self.min_duration > self.max_duration:
-            self.logger.warning(
-                f"min_duration ({self.min_duration}) > max_duration ({self.max_duration}); swapping values"
-            )
-            self.min_duration, self.max_duration = self.max_duration, self.min_duration
-
-        data_settings = config.get("data_settings", {})
-        self.update_interval: int = data_settings.get("update_interval", 300)
-        self.request_timeout: int = data_settings.get("request_timeout", 30)
-
-        # Scrolling flag for display controller
-        self.enable_scrolling = True
-
-        # State
-        self.games_data: List[Dict] = []
-        self.ticker_image: Optional[Image.Image] = None
-        self.last_update: float = 0
-        self.dynamic_duration: float = 60
-        self.total_scroll_width: int = 0
-        self._display_start_time: Optional[float] = None
-        self._end_reached_logged: bool = False
-        self._update_lock = threading.Lock()
-        self._has_live_games: bool = False
-        self._cached_dynamic_duration: Optional[float] = None
-        self._duration_cache_time: float = 0
-
-        # Display dimensions
-        self.display_width: int = self.display_manager.matrix.width
-        self.display_height: int = self.display_manager.matrix.height
-
-        # HTTP session with retry
-        self.session = requests.Session()
-        retry = Retry(total=3, backoff_factor=1, status_forcelist=[429, 500, 502, 503, 504])
-        self.session.mount("https://", HTTPAdapter(max_retries=retry))
-        self.headers = {"User-Agent": "LEDMatrix/2.0"}
-
-        # ScrollHelper
-        if ScrollHelper:
-            self.scroll_helper = ScrollHelper(self.display_width, self.display_height, logger=self.logger)
-            if hasattr(self.scroll_helper, "set_frame_based_scrolling"):
-                self.scroll_helper.set_frame_based_scrolling(True)
-            self.scroll_helper.set_scroll_speed(self.scroll_speed)
-            self.scroll_helper.set_scroll_delay(self.scroll_delay)
-            if hasattr(self.scroll_helper, "set_target_fps"):
-                self.scroll_helper.set_target_fps(self.target_fps)
-            self.scroll_helper.set_dynamic_duration_settings(
-                enabled=self.dynamic_duration_enabled,
-                min_duration=self.min_duration,
-                max_duration=self.max_duration,
-                buffer=0.1,
-            )
-        else:
-            self.scroll_helper = None
-            self.logger.warning("ScrollHelper not available")
-
-        # Fonts
-        self.fonts = self._load_fonts()
-
-        # Logos
-        self._round_logos: Dict[str, Image.Image] = {}
-        self._team_logo_cache: Dict[str, Optional[Image.Image]] = {}
-        self._march_madness_logo: Optional[Image.Image] = None
-        self._load_round_logos()
-
-        self.logger.info(
-            f"MarchMadnessPlugin initialized — NCAAM: {self.show_ncaam}, "
-            f"NCAAW: {self.show_ncaaw}, favorites: {self.favorite_teams}"
-        )
-
-    # ------------------------------------------------------------------
-    # Fonts
-    # ------------------------------------------------------------------
-
-    def _load_fonts(self) -> Dict[str, ImageFont.FreeTypeFont]:
-        fonts = {}
-        try:
-            fonts["score"] = ImageFont.truetype("assets/fonts/PressStart2P-Regular.ttf", 10)
-        except IOError:
-            fonts["score"] = ImageFont.load_default()
-        try:
-            fonts["time"] = ImageFont.truetype("assets/fonts/PressStart2P-Regular.ttf", 8)
-        except IOError:
-            fonts["time"] = ImageFont.load_default()
-        try:
-            fonts["detail"] = ImageFont.truetype("assets/fonts/4x6-font.ttf", 6)
-        except IOError:
-            fonts["detail"] = ImageFont.load_default()
-        return fonts
-
-    # ------------------------------------------------------------------
-    # Logo loading
-    # ------------------------------------------------------------------
-
-    def _load_round_logos(self) -> None:
-        logo_dir = Path("assets/sports/ncaa_logos")
-        for round_key, filename in ROUND_LOGO_FILES.items():
-            path = logo_dir / filename
-            try:
-                img = Image.open(path).convert("RGBA")
-                # Resize to fit display height
-                target_h = self.display_height - 4
-                ratio = target_h / img.height
-                target_w = int(img.width * ratio)
-                self._round_logos[round_key] = img.resize((target_w, target_h), Image.Resampling.LANCZOS)
-            except (OSError, ValueError) as e:
-                self.logger.warning(f"Could not load round logo {filename}: {e}")
-            except Exception:
-                self.logger.exception(f"Unexpected error loading round logo {filename}")
-
-        # March Madness logo
-        mm_path = logo_dir / "MARCH_MADNESS.png"
-        try:
-            img = Image.open(mm_path).convert("RGBA")
-            target_h = self.display_height - 4
-            ratio = target_h / img.height
-            target_w = int(img.width * ratio)
-            self._march_madness_logo = img.resize((target_w, target_h), Image.Resampling.LANCZOS)
-        except (OSError, ValueError) as e:
-            self.logger.warning(f"Could not load March Madness logo: {e}")
-        except Exception:
-            self.logger.exception("Unexpected error loading March Madness logo")
-
-    def _get_team_logo(self, abbr: str) -> Optional[Image.Image]:
-        if abbr in self._team_logo_cache:
-            return self._team_logo_cache[abbr]
-        logo_dir = Path("assets/sports/ncaa_logos")
-        path = logo_dir / f"{abbr}.png"
-        try:
-            img = Image.open(path).convert("RGBA")
-            target_h = self.display_height - 6
-            ratio = target_h / img.height
-            target_w = int(img.width * ratio)
-            img = img.resize((target_w, target_h), Image.Resampling.LANCZOS)
-            self._team_logo_cache[abbr] = img
-            return img
-        except (FileNotFoundError, OSError, ValueError):
-            self._team_logo_cache[abbr] = None
-            return None
-        except Exception:
-            self.logger.exception(f"Unexpected error loading team logo for {abbr}")
-            self._team_logo_cache[abbr] = None
-            return None
-
-    # ------------------------------------------------------------------
-    # Data fetching
-    # ------------------------------------------------------------------
-
-    def _is_tournament_window(self) -> bool:
-        today = datetime.now(pytz.utc)
-        return (3, 10) <= (today.month, today.day) <= (4, 10)
-
-    def _fetch_tournament_data(self) -> List[Dict]:
-        """Fetch tournament games from ESPN scoreboard API."""
-        all_games: List[Dict] = []
-
-        leagues = []
-        if self.show_ncaam:
-            leagues.append("ncaam")
-        if self.show_ncaaw:
-            leagues.append("ncaaw")
-
-        for league_key in leagues:
-            url = SCOREBOARD_URLS.get(league_key)
-            if not url:
-                continue
-
-            cache_key = f"march_madness_{league_key}_scoreboard"
-            cache_max_age = 60 if self._has_live_games else self.update_interval
-            cached = self.cache_manager.get(cache_key, max_age=cache_max_age)
-            if cached:
-                all_games.extend(cached)
-                continue
-
-            try:
-                # NCAA basketball scoreboard without dates param returns current games
-                params = {"limit": 1000, "groups": 100}
-                resp = self.session.get(url, params=params, headers=self.headers, timeout=self.request_timeout)
-                resp.raise_for_status()
-                data = resp.json()
-                events = data.get("events", [])
-
-                league_games = []
-                for event in events:
-                    game = self._parse_event(event, league_key)
-                    if game:
-                        league_games.append(game)
-
-                self.cache_manager.set(cache_key, league_games)
-                self.logger.info(f"Fetched {len(league_games)} {league_key} tournament games")
-                all_games.extend(league_games)
-
-            except Exception:
-                self.logger.exception(f"Error fetching {league_key} tournament data")
-
-        return all_games
-
-    def _parse_event(self, event: Dict, league_key: str) -> Optional[Dict]:
-        """Parse an ESPN event into a game dict."""
-        competitions = event.get("competitions", [])
-        if not competitions:
-            return None
-        comp = competitions[0]
-
-        # Confirm tournament game
-        comp_type = comp.get("type", {})
-        is_tournament = comp_type.get("abbreviation") == "TRNMNT"
-        notes = comp.get("notes", [])
-        headline = ""
-        if notes:
-            headline = notes[0].get("headline", "")
-            if not is_tournament and "Championship" in headline:
-                is_tournament = True
-        if not is_tournament:
-            return None
-
-        # Status
-        status = comp.get("status", {}).get("type", {})
-        state = status.get("state", "pre")
-        status_detail = status.get("shortDetail", "")
-
-        # Teams
-        competitors = comp.get("competitors", [])
-        home_team = next((c for c in competitors if c.get("homeAway") == "home"), None)
-        away_team = next((c for c in competitors if c.get("homeAway") == "away"), None)
-        if not home_team or not away_team:
-            return None
-
-        home_abbr = home_team.get("team", {}).get("abbreviation", "???")
-        away_abbr = away_team.get("team", {}).get("abbreviation", "???")
-        home_score = home_team.get("score", "0")
-        away_score = away_team.get("score", "0")
-
-        # Seeds
-        home_seed = home_team.get("curatedRank", {}).get("current", 0)
-        away_seed = away_team.get("curatedRank", {}).get("current", 0)
-        if home_seed >= 99:
-            home_seed = 0
-        if away_seed >= 99:
-            away_seed = 0
-
-        # Round and region
-        tournament_round = self._parse_round(headline)
-        tournament_region = self._parse_region(headline)
-
-        # Date/time
-        date_str = event.get("date", "")
-        start_time_utc = None
-        game_date = ""
-        game_time = ""
-        try:
-            if date_str.endswith("Z"):
-                date_str = date_str.replace("Z", "+00:00")
-            dt = datetime.fromisoformat(date_str)
-            if dt.tzinfo is None:
-                start_time_utc = dt.replace(tzinfo=pytz.UTC)
-            else:
-                start_time_utc = dt.astimezone(pytz.UTC)
-            local = start_time_utc.astimezone(pytz.timezone("US/Eastern"))
-            game_date = local.strftime("%-m/%-d")
-            game_time = local.strftime("%-I:%M%p").replace("AM", "am").replace("PM", "pm")
-        except (ValueError, AttributeError):
-            pass
-
-        # Period / clock for live games
-        period = 0
-        clock = ""
-        period_text = ""
-        is_halftime = False
-        if state == "in":
-            status_obj = comp.get("status", {})
-            period = status_obj.get("period", 0)
-            clock = status_obj.get("displayClock", "")
-            detail_lower = status_detail.lower()
-            uses_quarters = league_key == "ncaaw" or "quarter" in detail_lower or detail_lower.startswith("q")
-            if period <= (4 if uses_quarters else 2):
-                period_text = f"Q{period}" if uses_quarters else f"H{period}"
-            else:
-                ot_num = period - (4 if uses_quarters else 2)
-                period_text = f"OT{ot_num}" if ot_num > 1 else "OT"
-            if "halftime" in detail_lower:
-                is_halftime = True
-        elif state == "post":
-            period_text = status.get("shortDetail", "Final")
-            if "Final" not in period_text:
-                period_text = "Final"
-
-        # Determine winner and upset
-        is_final = state == "post"
-        is_upset = False
-        winner_side = ""
-        if is_final:
-            try:
-                h = int(float(home_score))
-                a = int(float(away_score))
-                if h > a:
-                    winner_side = "home"
-                    if home_seed > away_seed > 0:
-                        is_upset = True
-                elif a > h:
-                    winner_side = "away"
-                    if away_seed > home_seed > 0:
-                        is_upset = True
-            except (ValueError, TypeError):
-                pass
-
-        return {
-            "id": event.get("id", ""),
-            "league": league_key,
-            "home_abbr": home_abbr,
-            "away_abbr": away_abbr,
-            "home_score": str(home_score),
-            "away_score": str(away_score),
-            "home_seed": home_seed,
-            "away_seed": away_seed,
-            "tournament_round": tournament_round,
-            "tournament_region": tournament_region,
-            "state": state,
-            "is_final": is_final,
-            "is_live": state == "in",
-            "is_upcoming": state == "pre",
-            "is_halftime": is_halftime,
-            "period": period,
-            "period_text": period_text,
-            "clock": clock,
-            "status_detail": status_detail,
-            "game_date": game_date,
-            "game_time": game_time,
-            "start_time_utc": start_time_utc,
-            "is_upset": is_upset,
-            "winner_side": winner_side,
-            "headline": headline,
-        }
-
-    @staticmethod
-    def _parse_round(headline: str) -> str:
-        hl = headline.lower()
-        if "national championship" in hl:
-            return "NCG"
-        if "final four" in hl:
-            return "F4"
-        if "elite 8" in hl or "elite eight" in hl:
-            return "E8"
-        if "sweet 16" in hl or "sweet sixteen" in hl:
-            return "S16"
-        if "2nd round" in hl or "second round" in hl:
-            return "R32"
-        if "1st round" in hl or "first round" in hl:
-            return "R64"
-        return ""
-
-    @staticmethod
-    def _parse_region(headline: str) -> str:
-        if "East Region" in headline:
-            return "E"
-        if "West Region" in headline:
-            return "W"
-        if "South Region" in headline:
-            return "S"
-        if "Midwest Region" in headline:
-            return "MW"
-        m = re.search(r"Regional (\d+)", headline)
-        if m:
-            return f"R{m.group(1)}"
-        return ""
-
-    # ------------------------------------------------------------------
-    # Game processing
-    # ------------------------------------------------------------------
-
-    def _process_games(self, games: List[Dict]) -> Dict[str, List[Dict]]:
-        """Group games by round, sorted by round significance then region/seed."""
-        grouped: Dict[str, List[Dict]] = {}
-        for game in games:
-            rnd = game.get("tournament_round", "")
-            grouped.setdefault(rnd, []).append(game)
-
-        # Sort each round's games by region then seed matchup
-        for rnd, round_games in grouped.items():
-            round_games.sort(
-                key=lambda g: (
-                    REGION_ORDER.get(g.get("tournament_region", ""), 4),
-                    min(g.get("away_seed", 99), g.get("home_seed", 99)),
-                )
-            )
-
-        return grouped
-
-    # ------------------------------------------------------------------
-    # Rendering
-    # ------------------------------------------------------------------
-
-    def _draw_text_with_outline(
-        self,
-        draw: ImageDraw.Draw,
-        text: str,
-        xy: tuple,
-        font: ImageFont.FreeTypeFont,
-        fill: tuple = COLOR_WHITE,
-        outline: tuple = COLOR_BLACK,
-    ) -> None:
-        x, y = xy
-        for dx in (-1, 0, 1):
-            for dy in (-1, 0, 1):
-                if dx or dy:
-                    draw.text((x + dx, y + dy), text, font=font, fill=outline)
-        draw.text((x, y), text, font=font, fill=fill)
-
-    def _create_round_separator(self, round_key: str) -> Image.Image:
-        """Create a separator tile for a tournament round."""
-        height = self.display_height
-        name = ROUND_DISPLAY_NAMES.get(round_key, round_key)
-        font = self.fonts["time"]
-
-        # Measure text
-        tmp = Image.new("RGB", (1, 1))
-        tmp_draw = ImageDraw.Draw(tmp)
-        text_width = int(tmp_draw.textlength(name, font=font))
-
-        # Logo on each side
-        logo = self._round_logos.get(round_key, self._march_madness_logo)
-        logo_w = logo.width if logo else 0
-        padding = 6
-
-        total_w = padding + logo_w + padding + text_width + padding + logo_w + padding
-        total_w = max(total_w, 80)
-
-        img = Image.new("RGB", (total_w, height), COLOR_DARK_BG)
-        draw = ImageDraw.Draw(img)
-
-        # Draw logos
-        x = padding
-        if logo:
-            logo_y = (height - logo.height) // 2
-            img.paste(logo, (x, logo_y), logo)
-            x += logo_w + padding
-
-        # Draw round name
-        text_y = (height - 8) // 2  # 8px font
-        self._draw_text_with_outline(draw, name, (x, text_y), font, fill=COLOR_GOLD)
-        x += text_width + padding
-
-        if logo:
-            logo_y = (height - logo.height) // 2
-            img.paste(logo, (x, logo_y), logo)
-
-        return img
-
-    def _create_game_tile(self, game: Dict) -> Image.Image:
-        """Create a single game tile for the scrolling ticker."""
-        height = self.display_height
-        font_score = self.fonts["score"]
-        font_time = self.fonts["time"]
-        font_detail = self.fonts["detail"]
-
-        # Load team logos
-        away_logo = self._get_team_logo(game["away_abbr"])
-        home_logo = self._get_team_logo(game["home_abbr"])
-        logo_w = 0
-        if away_logo:
-            logo_w = max(logo_w, away_logo.width)
-        if home_logo:
-            logo_w = max(logo_w, home_logo.width)
-        if logo_w == 0:
-            logo_w = 24
-
-        # Build text elements
-        away_seed_str = f"({game['away_seed']})" if self.show_seeds and game.get("away_seed", 0) > 0 else ""
-        home_seed_str = f"({game['home_seed']})" if self.show_seeds and game.get("home_seed", 0) > 0 else ""
-        away_text = f"{away_seed_str}{game['away_abbr']}"
-        home_text = f"{game['home_abbr']}{home_seed_str}"
-
-        # Measure text widths
-        tmp = Image.new("RGB", (1, 1))
-        tmp_draw = ImageDraw.Draw(tmp)
-        away_text_w = int(tmp_draw.textlength(away_text, font=font_detail))
-        home_text_w = int(tmp_draw.textlength(home_text, font=font_detail))
-
-        # Center content: status line
-        if game["is_live"]:
-            if game["is_halftime"]:
-                status_text = "Halftime"
-            else:
-                status_text = f"{game['period_text']} {game['clock']}".strip()
-        elif game["is_final"]:
-            status_text = game.get("period_text", "Final")
-        else:
-            status_text = f"{game['game_date']} {game['game_time']}".strip()
-
-        status_w = int(tmp_draw.textlength(status_text, font=font_time))
-
-        # Score line (for live/final)
-        score_text = ""
-        if game["is_live"] or game["is_final"]:
-            score_text = f"{game['away_score']}-{game['home_score']}"
-        score_w = int(tmp_draw.textlength(score_text, font=font_score)) if score_text else 0
-
-        # Calculate tile width
-        h_pad = 4
-        center_w = max(status_w, score_w, 40)
-        tile_w = h_pad + logo_w + h_pad + away_text_w + h_pad + center_w + h_pad + home_text_w + h_pad + logo_w + h_pad
-
-        img = Image.new("RGB", (tile_w, height), COLOR_BLACK)
-        draw = ImageDraw.Draw(img)
-
-        # Paste away logo
-        x = h_pad
-        if away_logo:
-            logo_y = (height - away_logo.height) // 2
-            img.paste(away_logo, (x, logo_y), away_logo)
-        x += logo_w + h_pad
-
-        # Away team text (seed + abbr)
-        is_fav_away = game["away_abbr"] in self.favorite_teams if self.favorite_teams else False
-        away_color = COLOR_GOLD if is_fav_away else COLOR_WHITE
-        if game["is_final"] and game["winner_side"] == "away" and self.highlight_upsets and game["is_upset"]:
-            away_color = COLOR_GOLD
-        team_text_y = (height - 6) // 2 - 5  # Upper half
-        self._draw_text_with_outline(draw, away_text, (x, team_text_y), font_detail, fill=away_color)
-        x += away_text_w + h_pad
-
-        # Center block
-        center_x = x
-        center_mid = center_x + center_w // 2
-
-        # Status text (top center of center block)
-        status_x = center_mid - status_w // 2
-        status_y = 2
-        status_color = COLOR_GREEN if game["is_live"] else COLOR_GRAY
-        self._draw_text_with_outline(draw, status_text, (status_x, status_y), font_time, fill=status_color)
-
-        # Score (bottom center of center block, for live/final)
-        if score_text:
-            score_x = center_mid - score_w // 2
-            score_y = height - 13
-            # Upset highlighting
-            if game["is_final"] and game["is_upset"] and self.highlight_upsets:
-                score_color = COLOR_GOLD
-            elif game["is_live"]:
-                score_color = COLOR_WHITE
-            else:
-                score_color = COLOR_WHITE
-            self._draw_text_with_outline(draw, score_text, (score_x, score_y), font_score, fill=score_color)
-
-        # Date for final games (below score)
-        if game["is_final"] and game.get("game_date"):
-            date_w = int(draw.textlength(game["game_date"], font=font_detail))
-            date_x = center_mid - date_w // 2
-            date_y = height - 6
-            self._draw_text_with_outline(draw, game["game_date"], (date_x, date_y), font_detail, fill=COLOR_DIM)
-
-        x = center_x + center_w + h_pad
-
-        # Home team text
-        is_fav_home = game["home_abbr"] in self.favorite_teams if self.favorite_teams else False
-        home_color = COLOR_GOLD if is_fav_home else COLOR_WHITE
-        if game["is_final"] and game["winner_side"] == "home" and self.highlight_upsets and game["is_upset"]:
-            home_color = COLOR_GOLD
-        self._draw_text_with_outline(draw, home_text, (x, team_text_y), font_detail, fill=home_color)
-        x += home_text_w + h_pad
-
-        # Paste home logo
-        if home_logo:
-            logo_y = (height - home_logo.height) // 2
-            img.paste(home_logo, (x, logo_y), home_logo)
-
-        return img
-
-    def _create_ticker_image(self) -> None:
-        """Build the full scrolling ticker image from game tiles."""
-        if not self.games_data:
-            self.ticker_image = None
-            if self.scroll_helper:
-                self.scroll_helper.clear_cache()
-            return
-
-        grouped = self._process_games(self.games_data)
-        content_items: List[Image.Image] = []
-
-        # Order rounds by significance (most important first)
-        sorted_rounds = sorted(grouped.keys(), key=lambda r: ROUND_ORDER.get(r, 6))
-
-        for rnd in sorted_rounds:
-            games = grouped[rnd]
-            if not games:
-                continue
-
-            # Add round separator
-            if self.show_round_logos and rnd:
-                separator = self._create_round_separator(rnd)
-                content_items.append(separator)
-
-            # Add game tiles
-            for game in games:
-                tile = self._create_game_tile(game)
-                content_items.append(tile)
-
-        if not content_items:
-            self.ticker_image = None
-            if self.scroll_helper:
-                self.scroll_helper.clear_cache()
-            return
-
-        if not self.scroll_helper:
-            self.ticker_image = None
-            return
-
-        gap_width = 16
-
-        # Use ScrollHelper to create the scrolling image
-        self.ticker_image = self.scroll_helper.create_scrolling_image(
-            content_items=content_items,
-            item_gap=gap_width,
-            element_gap=0,
-        )
-
-        self.total_scroll_width = self.scroll_helper.total_scroll_width
-        self.dynamic_duration = self.scroll_helper.get_dynamic_duration()
-
-        self.logger.info(
-            f"Ticker image created: {self.ticker_image.width}px wide, "
-            f"{len(self.games_data)} games, dynamic_duration={self.dynamic_duration:.0f}s"
-        )
-
-    # ------------------------------------------------------------------
-    # Plugin lifecycle
-    # ------------------------------------------------------------------
-
-    def update(self) -> None:
-        """Fetch and process tournament data."""
-        if not self.enabled:
-            return
-
-        current_time = time.time()
-        # Use shorter interval if live games detected
-        interval = 60 if self._has_live_games else self.update_interval
-        if current_time - self.last_update < interval:
-            return
-
-        with self._update_lock:
-            self.last_update = current_time
-
-            if not self._is_tournament_window():
-                self.logger.debug("Outside tournament window, skipping fetch")
-                self.games_data = []
-                self.ticker_image = None
-                if self.scroll_helper:
-                    self.scroll_helper.clear_cache()
-                return
-
-            try:
-                games = self._fetch_tournament_data()
-                self._has_live_games = any(g["is_live"] for g in games)
-                self.games_data = games
-                self._create_ticker_image()
-                self.logger.info(
-                    f"Updated: {len(games)} games, "
-                    f"live={self._has_live_games}"
-                )
-            except Exception as e:
-                self.logger.error(f"Update error: {e}", exc_info=True)
-
-    def display(self, force_clear: bool = False) -> None:
-        """Render one scroll frame."""
-        if not self.enabled:
-            return
-
-        if force_clear or self._display_start_time is None:
-            self._display_start_time = time.time()
-            if self.scroll_helper:
-                self.scroll_helper.reset_scroll()
-            self._end_reached_logged = False
-
-        if not self.games_data or self.ticker_image is None:
-            self._display_fallback()
-            return
-
-        if not self.scroll_helper:
-            self._display_fallback()
-            return
-
-        try:
-            if self.loop or not self.scroll_helper.is_scroll_complete():
-                self.scroll_helper.update_scroll_position()
-            elif not self._end_reached_logged:
-                self.logger.info("Scroll complete")
-                self._end_reached_logged = True
-
-            visible = self.scroll_helper.get_visible_portion()
-            if visible is None:
-                self._display_fallback()
-                return
-
-            self.dynamic_duration = self.scroll_helper.get_dynamic_duration()
-
-            matrix_w = self.display_manager.matrix.width
-            matrix_h = self.display_manager.matrix.height
-            if not hasattr(self.display_manager, "image") or self.display_manager.image is None:
-                self.display_manager.image = Image.new("RGB", (matrix_w, matrix_h), COLOR_BLACK)
-            self.display_manager.image.paste(visible, (0, 0))
-            self.display_manager.update_display()
-            self.scroll_helper.log_frame_rate()
-
-        except Exception as e:
-            self.logger.error(f"Display error: {e}", exc_info=True)
-            self._display_fallback()
-
-    def _display_fallback(self) -> None:
-        w = self.display_manager.matrix.width
-        h = self.display_manager.matrix.height
-        img = Image.new("RGB", (w, h), COLOR_BLACK)
-        draw = ImageDraw.Draw(img)
-
-        if self._is_tournament_window():
-            text = "No games"
-        else:
-            text = "Off-season"
-
-        text_w = int(draw.textlength(text, font=self.fonts["time"]))
-        text_x = (w - text_w) // 2
-        text_y = (h - 8) // 2
-        draw.text((text_x, text_y), text, font=self.fonts["time"], fill=COLOR_GRAY)
-
-        # Show March Madness logo if available
-        if self._march_madness_logo:
-            logo_y = (h - self._march_madness_logo.height) // 2
-            img.paste(self._march_madness_logo, (2, logo_y), self._march_madness_logo)
-
-        self.display_manager.image = img
-        self.display_manager.update_display()
-
-    # ------------------------------------------------------------------
-    # Duration / cycle management
-    # ------------------------------------------------------------------
-
-    def get_display_duration(self) -> float:
-        current_time = time.time()
-        if self._cached_dynamic_duration is not None:
-            cache_age = current_time - self._duration_cache_time
-            if cache_age < 5.0:
-                return self._cached_dynamic_duration
-
-        self._cached_dynamic_duration = self.dynamic_duration
-        self._duration_cache_time = current_time
-        return self.dynamic_duration
-
-    def supports_dynamic_duration(self) -> bool:
-        if not self.enabled:
-            return False
-        return self.dynamic_duration_enabled
-
-    def is_cycle_complete(self) -> bool:
-        if not self.supports_dynamic_duration():
-            return True
-        if self._display_start_time is not None and self.dynamic_duration > 0:
-            elapsed = time.time() - self._display_start_time
-            if elapsed >= self.dynamic_duration:
-                return True
-        if not self.loop and self.scroll_helper and self.scroll_helper.is_scroll_complete():
-            return True
-        return False
-
-    def reset_cycle_state(self) -> None:
-        super().reset_cycle_state()
-        self._display_start_time = None
-        self._end_reached_logged = False
-        if self.scroll_helper:
-            self.scroll_helper.reset_scroll()
-
-    # ------------------------------------------------------------------
-    # Vegas mode
-    # ------------------------------------------------------------------
-
-    def get_vegas_content(self):
-        if not self.games_data:
-            return None
-        tiles = []
-        for game in self.games_data:
-            tiles.append(self._create_game_tile(game))
-        return tiles if tiles else None
-
-    def get_vegas_content_type(self) -> str:
-        return "multi"
-
-    # ------------------------------------------------------------------
-    # Info / cleanup
-    # ------------------------------------------------------------------
-
-    def get_info(self) -> Dict:
-        info = super().get_info()
-        info["total_games"] = len(self.games_data)
-        info["has_live_games"] = self._has_live_games
-        info["dynamic_duration"] = self.dynamic_duration
-        info["tournament_window"] = self._is_tournament_window()
-        return info
-
-    def cleanup(self) -> None:
-        self.games_data = []
-        self.ticker_image = None
-        if self.scroll_helper:
-            self.scroll_helper.clear_cache()
-        self._team_logo_cache.clear()
-        if self.session:
-            self.session.close()
-            self.session = None
-        super().cleanup()

plugin-repos/march-madness/manifest.json

@@ -1,37 +0,0 @@
-{
-  "id": "march-madness",
-  "name": "March Madness",
-  "version": "1.0.0",
-  "description": "NCAA March Madness tournament bracket tracker with round branding, seeded matchups, live scores, and upset highlighting",
-  "author": "ChuckBuilds",
-  "category": "sports",
-  "tags": [
-    "ncaa",
-    "basketball",
-    "march-madness",
-    "tournament",
-    "bracket",
-    "scrolling"
-  ],
-  "repo": "https://github.com/ChuckBuilds/ledmatrix-plugins",
-  "branch": "main",
-  "plugin_path": "plugins/march-madness",
-  "versions": [
-    {
-      "version": "1.0.0",
-      "ledmatrix_min": "2.0.0",
-      "released": "2026-02-16"
-    }
-  ],
-  "stars": 0,
-  "downloads": 0,
-  "last_updated": "2026-02-16",
-  "verified": true,
-  "screenshot": "",
-  "display_modes": [
-    "march_madness"
-  ],
-  "dependencies": {},
-  "entry_point": "manager.py",
-  "class_name": "MarchMadnessPlugin"
-}

plugin-repos/march-madness/requirements.txt

@@ -1,4 +0,0 @@
-requests>=2.28.0
-Pillow>=10.3.0
-pytz>=2022.1
-numpy>=1.24.0

plugin-repos/starlark-apps/manifest.json

@@ -22,5 +22,6 @@
     "Pillow>=10.0.0",
     "PyYAML>=6.0",
     "requests>=2.31.0"
-  ]
+  ],
+  "local_only": true
 }

plugin-repos/starlark-apps/requirements.txt

@@ -1,3 +1,3 @@
-Pillow>=10.4.0
+Pillow>=12.2.0
 PyYAML>=6.0.2
-requests>=2.32.0
+requests>=2.33.0

requirements-test.txt

@@ -0,0 +1,9 @@
+# Test-only dependencies for the plugin safety harness and pytest suite.
+# Install alongside requirements.txt:  pip install -r requirements.txt -r requirements-test.txt
+#
+# pytest, pytest-cov, pytest-mock, and jsonschema are already pinned (with
+# major-version caps) in requirements.txt, so they are intentionally NOT
+# repeated here — re-pinning pytest to <9 collided with requirements.txt's
+# pytest>=9.0.3,<10 and made the two files impossible to install together.
+# Only declare what requirements.txt doesn't already provide.
+freezegun>=1.2,<2        # deterministic time for golden-image tests

requirements.txt

@@ -3,7 +3,7 @@
 # Tested on Raspbian OS 12 (Bookworm) and 13 (Trixie)
 
 # Image processing
-Pillow>=10.4.0,<12.0.0
+Pillow>=12.2.0,<13.0.0
 numpy>=1.24.0  # For fast array operations in ScrollHelper (compatible with 2.x)
 
 # Timezone handling
@@ -12,7 +12,7 @@ timezonefinder>=6.5.0,<7.0.0  # Updated for better performance and accuracy
 geopy>=2.4.1,<3.0.0
 
 # HTTP requests
-requests>=2.32.0,<3.0.0
+requests>=2.33.0,<3.0.0
 
 # Google API integration
 google-auth-oauthlib>=1.2.0,<2.0.0
@@ -23,10 +23,10 @@ google-api-python-client>=2.147.0,<3.0.0
 freetype-py>=2.5.1,<3.0.0
 
 # Spotify integration
-spotipy>=2.24.0,<3.0.0
+spotipy>=2.25.2,<3.0.0
 
 # Flask web framework
-Flask>=3.0.0,<4.0.0
+Flask>=3.1.3,<4.0.0
 
 # Text processing
 unidecode>=1.3.8,<2.0.0
@@ -35,7 +35,7 @@ unidecode>=1.3.8,<2.0.0
 icalevents>=0.1.27,<1.0.0
 
 # WebSocket support
-python-socketio>=5.11.0,<6.0.0
+python-socketio>=5.14.0,<6.0.0
 python-engineio>=4.9.0,<5.0.0
 websockets>=12.0,<14.0
 websocket-client>=1.8.0,<2.0.0
@@ -43,8 +43,11 @@ websocket-client>=1.8.0,<2.0.0
 # JSON Schema validation
 jsonschema>=4.20.0,<5.0.0
 
+# Requirement specifier parsing (plugin dependency satisfaction checks)
+packaging>=23.0,<27.0
+
 # Testing dependencies
-pytest>=7.4.0,<8.0.0
+pytest>=9.0.3,<10.0.0
 pytest-cov>=4.1.0,<5.0.0
 pytest-mock>=3.11.0,<4.0.0
 mypy>=1.5.0,<2.0.0

run.py

@@ -51,7 +51,6 @@ if debug_mode:
 
         # Try to import the plugin system directly to get better error info
         print("DEBUG: Attempting to import src.plugin_system...", flush=True)
-        from src.plugin_system import PluginManager
         print("DEBUG: Plugin system import successful", flush=True)
     except ImportError as e:
         print(f"DEBUG: Plugin system import failed: {e}", flush=True)

schema/manifest_schema.json

@@ -90,11 +90,40 @@
             "min_height": {
               "type": "integer",
               "minimum": 1
+            },
+            "max_width": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "max_height": {
+              "type": "integer",
+              "minimum": 1
             }
           }
         }
       }
     },
+    "display": {
+      "type": "object",
+      "properties": {
+        "design_size": {
+          "type": "object",
+          "properties": {
+            "width": {
+              "type": "integer",
+              "minimum": 8
+            },
+            "height": {
+              "type": "integer",
+              "minimum": 8
+            }
+          },
+          "required": ["width", "height"],
+          "description": "Panel size the plugin's layout was authored against; core derives the adaptive-layout scale factor from it. Defaults to 128x32 when omitted."
+        }
+      },
+      "description": "Display/layout hints for the adaptive layout system"
+    },
     "config_schema": {
       "type": "string",
       "description": "Path to configuration schema file"

scripts/add_defaults_to_schemas.py

@@ -9,7 +9,7 @@ and preventing validation errors.
 import json
 import sys
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List
 
 
 def get_default_for_field(prop: Dict[str, Any]) -> Any:

scripts/analyze_plugin_schemas.py

@@ -9,9 +9,8 @@ Analyze all plugin config schemas to identify issues:
 """
 
 import json
-import os
 from pathlib import Path
-from typing import Dict, List, Set, Any
+from typing import Dict, List, Any
 import jsonschema
 from jsonschema import Draft7Validator
 

scripts/check_plugin.py

@@ -0,0 +1,268 @@
+#!/usr/bin/env python3
+"""
+Plugin safety checker.
+
+Renders a plugin across every declared screen (mode) and every supported matrix
+size, and fails if any screen crashes, overflows the panel, or (for plugins with
+committed golden images) drifts visually.
+
+Usage:
+    # Functional + bounds check across all sizes/modes:
+    python scripts/check_plugin.py --plugin clock-simple
+
+    # Every discovered plugin:
+    python scripts/check_plugin.py --all
+
+    # Dump PNGs for each size/mode so you can eyeball them:
+    python scripts/check_plugin.py --plugin ledmatrix-weather --out-dir /tmp/preview
+
+    # Refresh committed golden images after an intentional visual change:
+    python scripts/check_plugin.py --plugin clock-simple --update-golden \
+        --mock-data plugins/clock-simple/test/fixtures/mock.json
+
+Exit code is non-zero if any (plugin, size, mode) fails.
+"""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(PROJECT_ROOT))
+
+os.environ['EMULATOR'] = 'true'
+
+from src.logging_config import get_logger  # noqa: E402
+from src.plugin_system.testing.loading import (  # noqa: E402
+    find_plugin_dir, load_config_defaults, load_harness_spec, load_manifest,
+)
+from src.plugin_system.testing.harness import (  # noqa: E402
+    RenderResult, render_plugin_matrix, compare_to_goldens, write_goldens,
+    check_scale_up,
+)
+from src.plugin_system.testing.sizes import (  # noqa: E402
+    parse_size_token, resolve_test_sizes, safe_mode_filename, size_label,
+)
+
+logger = get_logger("[Check Plugin]")
+
+DEFAULT_SEARCH_DIRS = [
+    str(PROJECT_ROOT / 'plugins'),
+    str(PROJECT_ROOT / 'plugin-repos'),
+]
+
+
+def discover_plugins(search_dirs: List[str]) -> List[str]:
+    """All plugin ids found across the search dirs (dirs containing manifest.json)."""
+    found = []
+    for d in search_dirs:
+        base = Path(d)
+        if not base.exists():
+            continue
+        for child in sorted(base.iterdir()):
+            if (child / 'manifest.json').exists() and child.name not in found:
+                found.append(child.name)
+    return found
+
+
+def parse_sizes(spec: Optional[str]):
+    if not spec:
+        return None
+    sizes = []
+    for token in spec.split(','):
+        if not token.strip():
+            continue
+        try:
+            sizes.append(parse_size_token(token))
+        except ValueError as exc:
+            raise SystemExit(str(exc)) from exc
+    return sizes
+
+
+def check_one(plugin_id: str, search_dirs: List[str], sizes, mock_data: Dict,
+              config: Dict, run_update: bool, out_dir: Optional[Path],
+              update_golden: bool, golden_dir_override: Optional[Path],
+              freeze_time: Optional[str]) -> List[RenderResult]:
+    plugin_dir = find_plugin_dir(plugin_id, search_dirs)
+    if not plugin_dir:
+        logger.error("Plugin '%s' not found in: %s", plugin_id, search_dirs)
+        return [RenderResult(plugin_id, 0, 0, "<not-found>", error="plugin directory not found")]
+
+    # Per-plugin test/harness.json holds the deterministic settings the committed
+    # goldens were generated with (config, mock data, frozen time, sizes). Load
+    # them so the CLI/CI render reproduces the golden the same way the pytest
+    # matrix path does; explicit CLI flags still override the file.
+    spec = load_harness_spec(plugin_dir)
+
+    # config_schema defaults (real-install behavior), then harness.json config,
+    # then CLI --config — most specific wins.
+    full_config = {"enabled": True}
+    full_config.update(load_config_defaults(plugin_dir))
+    full_config.update(spec.get("config", {}))
+    full_config.update(config)
+
+    # Precedence: CLI flag > LEDMATRIX_TEST_SIZES env > harness.json > default.
+    effective_sizes = sizes if sizes else resolve_test_sizes(spec.get("sizes"))
+    # CLI value wins when provided, else fall back to the harness.json setting.
+    effective_mock_data = mock_data or spec.get("mock_data_contents", {})
+    effective_freeze = freeze_time or spec.get("freeze_time")
+    effective_run_update = run_update and not spec.get("skip_update", False)
+
+    # The plugin's declared design size drives the scale-up fill check
+    # (panels >= 2x the design size must not be left mostly empty).
+    declared = load_manifest(plugin_dir).get("display", {}).get("design_size", {})
+    design_size = (int(declared.get("width", 128)), int(declared.get("height", 32)))
+    fill_strict = spec.get("fill_check") == "strict"
+
+    # Every run: the base config, plus one per harness.json "variant" —
+    # a config overlay with its own golden dir (e.g. adaptive layout mode
+    # tested alongside the classic default).
+    runs = [(None, {}, golden_dir_override or (plugin_dir / 'test' / 'golden'))]
+    for variant in spec.get("variants", []):
+        name = variant.get("name") or "variant"
+        vdir = plugin_dir / variant.get("golden_dir", f"test/golden-{name}")
+        runs.append((name, variant.get("config", {}), vdir))
+
+    all_run_results: List[RenderResult] = []
+    for variant_name, overlay, golden_dir in runs:
+        run_config = {**full_config, **overlay}
+        results = render_plugin_matrix(
+            plugin_id=plugin_id, plugin_dir=plugin_dir, config=run_config,
+            mock_data=effective_mock_data, sizes=effective_sizes,
+            run_update=effective_run_update, freeze_time=effective_freeze,
+        )
+
+        if update_golden:
+            written = write_goldens(results, golden_dir)
+            logger.info("Wrote %d golden image(s) for %s%s to %s", written, plugin_id,
+                        f" [{variant_name}]" if variant_name else "", golden_dir)
+        else:
+            compare_to_goldens(results, golden_dir)
+
+        check_scale_up(results, design_size=design_size, strict=fill_strict)
+
+        # Tag variant runs so the report and PNG dumps stay distinguishable.
+        if variant_name:
+            for r in results:
+                r.mode = f"{r.mode}@{variant_name}"
+
+        if out_dir:
+            for r in results:
+                if r.image is None:
+                    continue
+                dest = out_dir / plugin_id / size_label(r.width, r.height)
+                dest.mkdir(parents=True, exist_ok=True)
+                r.image.save(dest / f"{safe_mode_filename(r.mode)}.png", format="PNG")
+
+        all_run_results.extend(results)
+
+    return all_run_results
+
+
+def print_report(all_results: Dict[str, List[RenderResult]]) -> bool:
+    """Print a per-plugin grid. Returns True if everything passed."""
+    everything_ok = True
+    for plugin_id, results in all_results.items():
+        print(f"\n=== {plugin_id} ===")
+        for r in results:
+            if r.ok:
+                status = "PASS"
+                detail = ""
+                if r.golden_checked:
+                    detail = " (golden ✓)"
+                if r.update_error is not None:
+                    detail += f" (update warn: {r.update_error})"
+                if r.fill_checked and r.fill_ok is None and r.fill_extent:
+                    # warn-only underfill: big panel left mostly empty
+                    ex, ey = r.fill_extent
+                    detail += f" (fill warn: extent {ex:.0%}x{ey:.0%})"
+            else:
+                everything_ok = False
+                if r.error is not None:
+                    status, detail = "FAIL", f" error={r.error}"
+                elif r.overflow is not None:
+                    status, detail = "FAIL", f" overflow bbox={r.overflow}"
+                elif r.golden_ok is False:
+                    status = "FAIL"
+                    detail = f" golden drift: {r.golden_diff_pixels}px (max Δ={r.golden_max_delta})"
+                elif r.fill_ok is False:
+                    ex, ey = r.fill_extent or (0.0, 0.0)
+                    status = "FAIL"
+                    detail = f" fill: extent {ex:.0%}x{ey:.0%} below required coverage"
+                else:
+                    status, detail = "FAIL", ""
+            print(f"  [{status}] {r.size_label:>7}  {r.mode}{detail}")
+    print()
+    return everything_ok
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Check a plugin renders safely across sizes & screens")
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument('--plugin', '-p', help='Plugin id to check')
+    group.add_argument('--all', action='store_true', help='Check every discovered plugin')
+    parser.add_argument('--plugin-dir', '-d', default=None, help='Directory to search for plugins')
+    parser.add_argument('--sizes', default=None, help='Comma-separated WxH list (default: all supported)')
+    parser.add_argument('--config', '-c', default='{}', help='Plugin config overrides as JSON')
+    parser.add_argument('--mock-data', '-m', default=None, help='Path to JSON file with mock cache data')
+    parser.add_argument('--out-dir', '-o', default=None, help='Also dump rendered PNGs here')
+    parser.add_argument('--skip-update', action='store_true', help='Skip calling update()')
+    parser.add_argument('--update-golden', action='store_true', help='Write/refresh golden images')
+    parser.add_argument('--golden-dir', default=None, help='Override golden dir (default: <plugin>/test/golden)')
+    parser.add_argument('--freeze-time', default=None,
+                        help='Freeze wall clock, e.g. "2025-08-01 15:25:00" (for time-dependent plugins)')
+    args = parser.parse_args()
+
+    search_dirs = [args.plugin_dir] if args.plugin_dir else DEFAULT_SEARCH_DIRS
+    sizes = parse_sizes(args.sizes)
+
+    try:
+        config = json.loads(args.config)
+    except json.JSONDecodeError as e:
+        logger.error("Invalid --config JSON: %s", e)
+        return 2
+    if not isinstance(config, dict):
+        logger.error("--config must be a JSON object, got %s", type(config).__name__)
+        return 2
+
+    mock_data = {}
+    if args.mock_data:
+        mock_path = Path(args.mock_data)
+        if not mock_path.exists():
+            logger.error("Mock data file not found: %s", args.mock_data)
+            return 2
+        with open(mock_path) as f:
+            mock_data = json.load(f)
+        if not isinstance(mock_data, dict):
+            logger.error("--mock-data must be a JSON object (key -> cache value), got %s",
+                         type(mock_data).__name__)
+            return 2
+
+    plugin_ids = discover_plugins(search_dirs) if args.all else [args.plugin]
+    if not plugin_ids:
+        logger.error("No plugins found in: %s", search_dirs)
+        return 2
+
+    out_dir = Path(args.out_dir) if args.out_dir else None
+    golden_dir_override = Path(args.golden_dir) if args.golden_dir else None
+
+    all_results: Dict[str, List[RenderResult]] = {}
+    for plugin_id in plugin_ids:
+        all_results[plugin_id] = check_one(
+            plugin_id=plugin_id, search_dirs=search_dirs, sizes=sizes,
+            mock_data=mock_data, config=config, run_update=not args.skip_update,
+            out_dir=out_dir, update_golden=args.update_golden,
+            golden_dir_override=golden_dir_override, freeze_time=args.freeze_time,
+        )
+
+    # When refreshing goldens we skip drift comparison, but a crash or overflow
+    # still means the plugin is broken — never let --update-golden mask that.
+    ok = print_report(all_results)
+    return 0 if ok else 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())

scripts/clear_dependency_markers.sh

@@ -1,29 +0,0 @@
-#!/bin/bash
-# Clear all plugin dependency markers to force fresh dependency check
-# Useful after updating plugins or troubleshooting dependency issues
-
-echo "Clearing plugin dependency markers..."
-
-# Check both possible cache locations
-CACHE_DIRS=(
-    "/var/cache/ledmatrix"
-    "$HOME/.cache/ledmatrix"
-)
-
-for CACHE_DIR in "${CACHE_DIRS[@]}"; do
-    if [ -d "$CACHE_DIR" ]; then
-        echo "Checking $CACHE_DIR..."
-        marker_count=$(find "$CACHE_DIR" -name "plugin_*_deps_installed" 2>/dev/null | wc -l)
-        if [ "$marker_count" -gt 0 ]; then
-            echo "Found $marker_count dependency marker(s) in $CACHE_DIR"
-            find "$CACHE_DIR" -name "plugin_*_deps_installed" -delete
-            echo "Cleared $marker_count marker(s)"
-        else
-            echo "No dependency markers found in $CACHE_DIR"
-        fi
-    fi
-done
-
-echo "Done! Dependency markers cleared."
-echo "Next startup will check and install dependencies as needed."
-

scripts/debug/check_imports.py

@@ -3,8 +3,6 @@
 Check what imports are actually in the app.py file on the Pi
 """
 
-import sys
-import os
 from pathlib import Path
 
 # Read the app.py file and check the import lines

scripts/debug/debug_web_manual.py

@@ -67,8 +67,9 @@ def main():
         print("   📍 Will run on: http://0.0.0.0:5000")
         print("   ⏹️  Press Ctrl+C to stop")
 
-        # Run the app (this should start the server)
-        app.run(host='0.0.0.0', port=5000, debug=True)
+        # Run the app (debug mode controlled by env var to satisfy security scanners)
+        _debug = os.environ.get('LEDMATRIX_FLASK_DEBUG', '0') == '1'
+        app.run(host='0.0.0.0', port=5000, debug=_debug)
 
     except KeyboardInterrupt:
         print("\n   ⏹️  Server stopped by user")

scripts/dev/dev_plugin_setup.sh

@@ -203,7 +203,7 @@ link_github_plugin() {
         log_info "Repository already exists at $target_dir"
         if [[ -d "$target_dir/.git" ]]; then
             log_info "Updating repository..."
-            (cd "$target_dir" && git pull --rebase || true)
+            (cd "$target_dir" && git pull --rebase) || true
         fi
     else
         # Clone the repository

scripts/dev/test_pillow_compat.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""
+Pillow compatibility smoke test.
+
+Exercises the Pillow APIs used throughout LEDMatrix to verify a new
+Pillow version doesn't break image rendering, font handling, or resize ops.
+
+Run after upgrading Pillow:
+    python3 scripts/dev/test_pillow_compat.py
+"""
+
+import sys
+
+
+def check(label, fn):
+    try:
+        result = fn()
+        print(f"  ✓ {label}" + (f" — {result}" if result is not None else ""))
+        return True
+    except Exception as e:
+        print(f"  ✗ {label} — {type(e).__name__}: {e}", file=sys.stderr)
+        return False
+
+
+def main():
+    from PIL import Image, ImageDraw, ImageFont
+    import PIL
+
+    print(f"Pillow {PIL.__version__} on Python {sys.version.split()[0]}\n")
+
+    failures = 0
+
+    print("Image creation:")
+    failures += not check("Image.new RGB",
+        lambda: Image.new('RGB', (128, 32), (0, 0, 0)).size)
+    failures += not check("Image.new RGBA",
+        lambda: Image.new('RGBA', (64, 64), (255, 0, 0, 128)).size)
+    failures += not check("Image.new 1-bit",
+        lambda: Image.new('1', (16, 16)).size)
+
+    print("\nDraw operations:")
+    img = Image.new('RGB', (128, 32), (0, 0, 0))
+    draw = ImageDraw.Draw(img)
+    font = ImageFont.load_default()
+    failures += not check("draw.rectangle",
+        lambda: draw.rectangle([0, 0, 127, 31], outline=(255, 0, 0)))
+    failures += not check("draw.text",
+        lambda: draw.text((2, 2), "Hello", fill=(255, 255, 255), font=font))
+    failures += not check("draw.line",
+        lambda: draw.line([0, 0, 127, 31], fill=(0, 255, 0)))
+
+    print("\nFont metrics (used in text_helper, scroll_helper):")
+    failures += not check("draw.textlength",
+        lambda: f"{draw.textlength('Test', font=font):.1f}px")
+    failures += not check("draw.textbbox",
+        lambda: draw.textbbox((0, 0), "Test", font=font))
+
+    print("\nResampling (used in logo_helper, image_utils, sports base):")
+    logo = Image.new('RGBA', (200, 200), (255, 128, 0, 200))
+    failures += not check("Image.Resampling.LANCZOS exists",
+        lambda: str(Image.Resampling.LANCZOS))
+    failures += not check("thumbnail with LANCZOS",
+        lambda: (logo.thumbnail((64, 32), Image.Resampling.LANCZOS), logo.size)[1])
+    big = Image.new('RGB', (300, 300), (0, 128, 255))
+    failures += not check("resize with LANCZOS",
+        lambda: big.resize((128, 32), Image.Resampling.LANCZOS).size)
+
+    print("\nComposite / paste (used in display rendering):")
+    base = Image.new('RGB', (128, 32), (0, 0, 0))
+    overlay = Image.new('RGBA', (32, 32), (255, 0, 0, 128))
+    failures += not check("paste RGBA onto RGB",
+        lambda: (base.paste(overlay.convert('RGB'), (0, 0)), base.size)[1])
+    failures += not check("Image.alpha_composite",
+        lambda: Image.alpha_composite(
+            Image.new('RGBA', (32, 32)), overlay).size)
+
+    print("\nImage I/O:")
+    import io
+    buf = io.BytesIO()
+    img.save(buf, format='PNG')
+    buf.seek(0)
+    failures += not check("save/load PNG roundtrip",
+        lambda: Image.open(buf).size)
+
+    print()
+    if failures == 0:
+        print(f"All checks passed. Pillow {PIL.__version__} is compatible.")
+        return 0
+    else:
+        print(f"{failures} check(s) failed — review output above.", file=sys.stderr)
+        return 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())

scripts/dev/validate_python.py

@@ -15,7 +15,6 @@ Usage: python tools/validate_python.py <python_file>
 import ast
 import sys
 import os
-from pathlib import Path
 
 def validate_file(filepath: str) -> bool:
     """Validate a Python file for common issues."""

scripts/dev_server.py

@@ -16,6 +16,7 @@ Opens at http://localhost:5001
 import sys
 import os
 import json
+import re
 import time
 import argparse
 import logging
@@ -44,6 +45,10 @@ MAX_HEIGHT = 512
 MIN_WIDTH = 1
 MIN_HEIGHT = 1
 
+# plugin_id arrives in request input and is used to build filesystem paths —
+# allowlist it (same pattern the web UI's pages_v3 uses)
+_SAFE_PLUGIN_ID_RE = re.compile(r'^[a-zA-Z0-9_-]{1,64}$')
+
 
 # --------------------------------------------------------------------------
 # Plugin discovery
@@ -106,15 +111,30 @@ def discover_plugins() -> List[Dict[str, Any]]:
 
 
 def find_plugin_dir(plugin_id: str) -> Optional[Path]:
-    """Find a plugin directory by ID."""
+    """Find a plugin directory by ID.
+
+    plugin_id comes from request input: it must pass an allowlist match,
+    and the resulting directory is normalized and required to live inside
+    one of the plugin search dirs, so a crafted id can never name a path
+    outside them.
+    """
+    if not isinstance(plugin_id, str) or not _SAFE_PLUGIN_ID_RE.match(plugin_id):
+        return None
     from src.plugin_system.plugin_loader import PluginLoader
     loader = PluginLoader()
     for search_dir in get_search_dirs():
         if not search_dir.exists():
             continue
         result = loader.find_plugin_directory(plugin_id, search_dir)
-        if result:
-            return Path(result)
+        if not result:
+            continue
+        # Normalize WITHOUT following symlinks (dev plugins are often
+        # symlinked into plugins/) and require lexical containment in the
+        # search dir, so no id can ever name a path outside it.
+        result_abs = os.path.abspath(str(result))
+        root_abs = os.path.abspath(str(search_dir))
+        if os.path.commonpath([result_abs, root_abs]) == root_abs:
+            return Path(result_abs)
     return None
 
 
@@ -176,6 +196,72 @@ def api_plugin_defaults(plugin_id):
     return jsonify({'defaults': defaults})
 
 
+def _render_once(plugin_id, plugin_dir, manifest, config, mock_data, width, height,
+                 skip_update):
+    """Render one plugin at one size. Returns the /api/render response dict.
+
+    Thin wrapper over the shared render service (also used by the web UI's
+    config-page preview); a fresh plugin instance per call, mirroring the
+    safety harness, so sizes never share state.
+    """
+    from src.plugin_system.testing.render_service import render_plugin_once
+
+    return render_plugin_once(
+        plugin_id, plugin_dir, manifest=manifest, config=config,
+        mock_data=mock_data, width=width, height=height,
+        skip_update=skip_update)
+
+
+def _trusted_plugin_dir(plugin_dir: Path) -> Optional[Path]:
+    """Re-derive a plugin directory from the search dirs' own listings.
+
+    Path-injection barrier: unlike ``Path.iterdir()`` (which CodeQL doesn't
+    recognize as a taint-clearing enumeration), ``os.scandir()`` is. The
+    returned Path is built from a trusted root plus a name the filesystem
+    itself produced under that root via scandir — request-derived strings
+    never enter its construction — so a crafted plugin id can never make
+    downstream file access leave the plugin search dirs. Comparison is by
+    name, deliberately without symlink resolution (dev plugins are
+    commonly symlinked into plugins/).
+    """
+    wanted_name = Path(os.path.normpath(str(plugin_dir))).name
+    for search_dir in get_search_dirs():
+        search_dir_str = str(search_dir)
+        try:
+            with os.scandir(search_dir_str) as entries:
+                for entry in entries:
+                    if entry.name == wanted_name and entry.is_dir():
+                        return Path(search_dir_str) / entry.name
+        except OSError:
+            continue
+    return None
+
+
+def _parse_render_request(data):
+    """Shared /api/render* request prep. Returns (plugin_dir, manifest, config,
+    mock_data, skip_update) or raises ValueError with a client message."""
+    plugin_id = data['plugin_id']
+    candidate_dir = find_plugin_dir(plugin_id)
+    # Never reuse `candidate_dir` past this point: it's built from
+    # request-derived input, and a variable reassigned only on some paths
+    # isn't a barrier CodeQL's flow analysis honors. `trusted_dir` is the
+    # sole name used below, always the scandir-sourced result.
+    trusted_dir = _trusted_plugin_dir(candidate_dir) if candidate_dir else None
+    if not trusted_dir:
+        raise LookupError(f'Plugin not found: {plugin_id}')
+
+    manifest_path = trusted_dir / 'manifest.json'
+    with open(manifest_path, 'r') as f:
+        manifest = json.load(f)
+
+    # Build config: schema defaults + user overrides
+    config = {'enabled': True}
+    config.update(load_config_defaults(trusted_dir))
+    config.update(data.get('config', {}))
+
+    return trusted_dir, manifest, config, data.get('mock_data', {}), data.get('skip_update', False)
+
+
 @app.route('/api/render', methods=['POST'])
 def api_render():
     """Render a plugin and return the display as base64 PNG."""
@@ -183,11 +269,6 @@ def api_render():
     if not data or 'plugin_id' not in data:
         return jsonify({'error': 'plugin_id is required'}), 400
 
-    plugin_id = data['plugin_id']
-    user_config = data.get('config', {})
-    mock_data = data.get('mock_data', {})
-    skip_update = data.get('skip_update', False)
-
     try:
         width = int(data.get('width', 128))
         height = int(data.get('height', 32))
@@ -199,78 +280,77 @@ def api_render():
     if not (MIN_HEIGHT <= height <= MAX_HEIGHT):
         return jsonify({'error': f'height must be between {MIN_HEIGHT} and {MAX_HEIGHT}'}), 400
 
-    # Find plugin
-    plugin_dir = find_plugin_dir(plugin_id)
-    if not plugin_dir:
-        return jsonify({'error': f'Plugin not found: {plugin_id}'}), 404
-
-    # Load manifest
-    manifest_path = plugin_dir / 'manifest.json'
-    with open(manifest_path, 'r') as f:
-        manifest = json.load(f)
-
-    # Build config: schema defaults + user overrides
-    config_defaults = load_config_defaults(plugin_dir)
-    config = {'enabled': True}
-    config.update(config_defaults)
-    config.update(user_config)
-
-    # Create display manager and mocks
-    from src.plugin_system.testing import VisualTestDisplayManager, MockCacheManager, MockPluginManager
-    from src.plugin_system.plugin_loader import PluginLoader
-
-    display_manager = VisualTestDisplayManager(width=width, height=height)
-    cache_manager = MockCacheManager()
-    plugin_manager = MockPluginManager()
-
-    # Pre-populate cache with mock data
-    for key, value in mock_data.items():
-        cache_manager.set(key, value)
-
-    # Load plugin
-    loader = PluginLoader()
-    errors = []
-    warnings = []
+    try:
+        plugin_dir, manifest, config, mock_data, skip_update = _parse_render_request(data)
+    except LookupError:
+        return jsonify({'error': f"Plugin not found: {data['plugin_id']}"}), 404
+    except Exception:
+        # Bad manifest.json / schema / fixture — details go to the dev's
+        # console, not the HTTP response
+        app.logger.exception('render request preparation failed')
+        return jsonify({'error': 'Could not prepare render request; see server log'}), 400
 
     try:
-        plugin_instance, module = loader.load_plugin(
-            plugin_id=plugin_id,
-            manifest=manifest,
-            plugin_dir=plugin_dir,
-            config=config,
-            display_manager=display_manager,
-            cache_manager=cache_manager,
-            plugin_manager=plugin_manager,
-            install_deps=False,
-        )
-    except Exception as e:
-        return jsonify({'error': f'Failed to load plugin: {e}'}), 500
+        result = _render_once(data['plugin_id'], plugin_dir, manifest, config,
+                              mock_data, width, height, skip_update)
+    except Exception:
+        app.logger.exception('plugin load failed during render')
+        return jsonify({'error': 'Failed to load plugin; see server log'}), 500
+    return jsonify(result)
 
-    start_time = time.time()
 
-    # Run update()
-    if not skip_update:
+@app.route('/api/sizes')
+def api_sizes():
+    """The representative panel-size sample the safety harness renders at."""
+    from src.plugin_system.testing.sizes import DEFAULT_TEST_SIZES
+    return jsonify({'sizes': [list(s) for s in DEFAULT_TEST_SIZES]})
+
+
+MAX_MATRIX_SIZES = 12
+
+
+@app.route('/api/render-matrix', methods=['POST'])
+def api_render_matrix():
+    """Render a plugin at a list of sizes (default: the harness sample) so the
+    UI can show a side-by-side multi-resolution gallery."""
+    data = request.get_json()
+    if not data or 'plugin_id' not in data:
+        return jsonify({'error': 'plugin_id is required'}), 400
+
+    from src.plugin_system.testing.sizes import DEFAULT_TEST_SIZES
+    sizes = data.get('sizes') or [list(s) for s in DEFAULT_TEST_SIZES]
+    if len(sizes) > MAX_MATRIX_SIZES:
+        return jsonify({'error': f'at most {MAX_MATRIX_SIZES} sizes per request'}), 400
+    parsed_sizes = []
+    for pair in sizes:
         try:
-            plugin_instance.update()
-        except Exception as e:
-            warnings.append(f"update() raised: {e}")
+            w, h = int(pair[0]), int(pair[1])
+        except (TypeError, ValueError, IndexError):
+            return jsonify({'error': f'invalid size entry {pair!r} (expected [w, h])'}), 400
+        if not (MIN_WIDTH <= w <= MAX_WIDTH and MIN_HEIGHT <= h <= MAX_HEIGHT):
+            return jsonify({'error': f'size {w}x{h} out of bounds'}), 400
+        parsed_sizes.append((w, h))
 
-    # Run display()
     try:
-        plugin_instance.display(force_clear=True)
-    except Exception as e:
-        errors.append(f"display() raised: {e}")
+        plugin_dir, manifest, config, mock_data, skip_update = _parse_render_request(data)
+    except LookupError:
+        return jsonify({'error': f"Plugin not found: {data['plugin_id']}"}), 404
+    except Exception:
+        app.logger.exception('render request preparation failed')
+        return jsonify({'error': 'Could not prepare render request; see server log'}), 400
 
-    render_time_ms = round((time.time() - start_time) * 1000, 1)
-
-    return jsonify({
-        'image': f'data:image/png;base64,{display_manager.get_image_base64()}',
-        'width': width,
-        'height': height,
-        'render_time_ms': render_time_ms,
-        'errors': errors,
-        'warnings': warnings,
-    })
+    results = []
+    for w, h in parsed_sizes:
+        try:
+            results.append(_render_once(data['plugin_id'], plugin_dir, manifest,
+                                        config, mock_data, w, h, skip_update))
+        except Exception:
+            app.logger.exception('plugin load failed during %dx%d render', w, h)
+            results.append({'image': None, 'width': w, 'height': h,
+                            'render_time_ms': 0,
+                            'errors': ['Failed to load plugin; see server log'],
+                            'warnings': []})
+    return jsonify({'results': results})
 
 
 # --------------------------------------------------------------------------

scripts/diagnose_plugin_permissions.sh

@@ -13,7 +13,6 @@ echo ""
 RED='\033[0;31m'
 GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
-BLUE='\033[0;34m'
 NC='\033[0m' # No Color
 
 # Get the actual user

scripts/diagnose_web_interface.sh

@@ -41,7 +41,7 @@ if [ -f "$PROJECT_DIR/config/config.json" ]; then
     echo -e "${GREEN}✓ Config file found${NC}"
     
     # Check web_display_autostart setting
-    AUTOSTART=$(cat "$PROJECT_DIR/config/config.json" | grep -o '"web_display_autostart"[[:space:]]*:[[:space:]]*[a-z]*' | grep -o '[a-z]*$')
+    AUTOSTART=$(grep -o '"web_display_autostart"[[:space:]]*:[[:space:]]*[a-z]*' "$PROJECT_DIR/config/config.json" | grep -o '[a-z]*$')
     
     if [ "$AUTOSTART" == "true" ]; then
         echo -e "${GREEN}✓ web_display_autostart: true${NC}"

scripts/diagnose_web_ui.sh

@@ -16,11 +16,8 @@ YELLOW='\033[1;33m'
 NC='\033[0m' # No Color
 
 # Check if running as root or with sudo
-if [ "$EUID" -ne 0 ]; then 
+if [ "$EUID" -ne 0 ]; then
     echo -e "${YELLOW}Warning: Some checks require sudo. Running what we can...${NC}"
-    SUDO=""
-else
-    SUDO=""
 fi
 
 PROJECT_DIR="${HOME}/LEDMatrix"

scripts/download_pixlet.sh

@@ -118,7 +118,7 @@ total_count=${#ARCHITECTURES[@]}
 
 for arch in "${!ARCHITECTURES[@]}"; do
     if download_binary "$arch" "${ARCHITECTURES[$arch]}"; then
-        ((success_count++))
+        success_count=$((success_count + 1))
     fi
 done
 

scripts/fix_perms/fix_assets_permissions.sh

@@ -7,12 +7,6 @@ echo "Fixing LEDMatrix assets directory permissions..."
 
 # Get the real user (not root when running with sudo)
 REAL_USER=${SUDO_USER:-$USER}
-# Resolve the home directory of the real user robustly
-if command -v getent >/dev/null 2>&1; then
-    REAL_HOME=$(getent passwd "$REAL_USER" | cut -d: -f6)
-else
-    REAL_HOME=$(eval echo ~"$REAL_USER")
-fi
 REAL_GROUP=$(id -gn "$REAL_USER")
 
 # Get the project directory

scripts/fix_perms/safe_pip_install.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+# safe_pip_install.sh — Install a requirements.txt as root after validating
+# that the resolved path is the project's own requirements.txt or a plugin's
+# requirements.txt under plugin-repos/ or plugins/.
+#
+# This script is intended to be called via sudo from the web interface, so
+# that packages a plugin declares end up visible to ledmatrix.service (which
+# runs as root) rather than only to whichever non-root user runs the web
+# interface. Plugin code already runs as root once loaded, so installing its
+# declared dependencies as root is not a new trust boundary.
+#
+# Usage: safe_pip_install.sh <requirements_txt_path>
+
+set -euo pipefail
+
+if [ $# -ne 1 ]; then
+    echo "Usage: $0 <requirements_txt_path>" >&2
+    exit 1
+fi
+
+TARGET="$1"
+
+# Determine the project root (parent of scripts/fix_perms/)
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# Allowed locations (resolved, no trailing slash):
+#   - the project's own requirements.txt
+#   - any requirements.txt under plugin-repos/ or plugins/
+ALLOWED_EXACT="$(realpath --canonicalize-missing "$PROJECT_ROOT/requirements.txt")"
+ALLOWED_BASES=(
+    "$(realpath --canonicalize-missing "$PROJECT_ROOT/plugin-repos")"
+    "$(realpath --canonicalize-missing "$PROJECT_ROOT/plugins")"
+)
+
+# Resolve the target path (follow symlinks); works even if it doesn't exist.
+RESOLVED_TARGET="$(realpath --canonicalize-missing "$TARGET")"
+
+# Must be named requirements.txt — never install from an arbitrary file.
+if [ "$(basename "$RESOLVED_TARGET")" != "requirements.txt" ]; then
+    echo "DENIED: $RESOLVED_TARGET is not a requirements.txt file" >&2
+    exit 2
+fi
+
+ALLOWED=false
+if [ "$RESOLVED_TARGET" = "$ALLOWED_EXACT" ]; then
+    ALLOWED=true
+else
+    for BASE in "${ALLOWED_BASES[@]}"; do
+        if [[ "$RESOLVED_TARGET" == "$BASE/"* ]]; then
+            ALLOWED=true
+            break
+        fi
+    done
+fi
+
+if [ "$ALLOWED" = false ]; then
+    echo "DENIED: $RESOLVED_TARGET is not an allowed requirements.txt location" >&2
+    echo "Allowed: $ALLOWED_EXACT, or any requirements.txt under: ${ALLOWED_BASES[*]}" >&2
+    exit 2
+fi
+
+if [ ! -f "$RESOLVED_TARGET" ]; then
+    echo "ERROR: $RESOLVED_TARGET does not exist" >&2
+    exit 3
+fi
+
+PYTHON_PATH="$(command -v python3)"
+# --ignore-installed: root's site-packages often has apt/dpkg-managed copies
+# of common libraries (requests, urllib3, ...) with no pip RECORD file, which
+# pip refuses to uninstall in place ("Cannot uninstall: no RECORD file was
+# found"). This tells pip to install the newer version alongside rather than
+# aborting the whole requirements.txt install over one such conflict.
+exec "$PYTHON_PATH" -m pip install --break-system-packages --ignore-installed -r "$RESOLVED_TARGET"

scripts/install/configure_web_sudo.sh

@@ -33,6 +33,7 @@ POWEROFF_PATH=$(command -v poweroff)  || true
 BASH_PATH=$(command -v bash)        || true
 JOURNALCTL_PATH=$(command -v journalctl) || true
 SAFE_RM_PATH="$PROJECT_ROOT/scripts/fix_perms/safe_plugin_rm.sh"
+SAFE_PIP_INSTALL_PATH="$PROJECT_ROOT/scripts/fix_perms/safe_pip_install.sh"
 
 # Validate required commands (systemctl, bash, python3 are essential)
 for CMD_NAME in SYSTEMCTL_PATH BASH_PATH PYTHON_PATH; do
@@ -48,11 +49,15 @@ if [ ${#MISSING_CMDS[@]} -gt 0 ]; then
     exit 1
 fi
 
-# Validate helper script exists
+# Validate helper scripts exist
 if [ ! -f "$SAFE_RM_PATH" ]; then
     echo "Error: Safe plugin removal helper not found: $SAFE_RM_PATH" >&2
     exit 1
 fi
+if [ ! -f "$SAFE_PIP_INSTALL_PATH" ]; then
+    echo "Error: Safe pip install helper not found: $SAFE_PIP_INSTALL_PATH" >&2
+    exit 1
+fi
 
 echo "Command paths:"
 echo "  Python: $PYTHON_PATH"
@@ -62,6 +67,7 @@ echo "  Poweroff: ${POWEROFF_PATH:-(not found, skipping)}"
 echo "  Bash: $BASH_PATH"
 echo "  Journalctl: ${JOURNALCTL_PATH:-(not found, skipping)}"
 echo "  Safe plugin rm: $SAFE_RM_PATH"
+echo "  Safe pip install: $SAFE_PIP_INSTALL_PATH"
 
 # Create a temporary sudoers file
 TEMP_SUDOERS="/tmp/ledmatrix_web_sudoers_$$"
@@ -101,13 +107,22 @@ TEMP_SUDOERS="/tmp/ledmatrix_web_sudoers_$$"
     fi
 
     # Required: python3, bash
-    echo "$WEB_USER ALL=(ALL) NOPASSWD: $PYTHON_PATH $PROJECT_DIR/display_controller.py"
-    echo "$WEB_USER ALL=(ALL) NOPASSWD: $BASH_PATH $PROJECT_DIR/start_display.sh"
-    echo "$WEB_USER ALL=(ALL) NOPASSWD: $BASH_PATH $PROJECT_DIR/stop_display.sh"
+    # NOTE: display_controller.py/start_display.sh/stop_display.sh live at the
+    # project root, not under scripts/install/ (where this script lives) —
+    # must use PROJECT_ROOT here, not PROJECT_DIR.
+    echo "$WEB_USER ALL=(ALL) NOPASSWD: $PYTHON_PATH $PROJECT_ROOT/display_controller.py"
+    echo "$WEB_USER ALL=(ALL) NOPASSWD: $BASH_PATH $PROJECT_ROOT/start_display.sh"
+    echo "$WEB_USER ALL=(ALL) NOPASSWD: $BASH_PATH $PROJECT_ROOT/stop_display.sh"
     echo ""
     echo "# Allow web user to remove plugin directories via vetted helper script"
     echo "# The helper validates that the target path resolves inside plugin-repos/ or plugins/"
     echo "$WEB_USER ALL=(ALL) NOPASSWD: $BASH_PATH $SAFE_RM_PATH *"
+    echo ""
+    echo "# Allow web user to install a plugin's requirements.txt as root via vetted"
+    echo "# helper script, so packages are visible to root-run ledmatrix.service"
+    echo "# (not just the web interface's own user). The helper validates the target"
+    echo "# is requirements.txt at the project root or under plugin-repos/ or plugins/."
+    echo "$WEB_USER ALL=(ALL) NOPASSWD: $BASH_PATH $SAFE_PIP_INSTALL_PATH *"
 } > "$TEMP_SUDOERS"
 
 echo ""
@@ -126,6 +141,7 @@ echo "- Run display_controller.py directly"
 echo "- Execute start_display.sh and stop_display.sh"
 echo "- Reboot and shutdown the system"
 echo "- Remove plugin directories (for update/uninstall when root-owned files block deletion)"
+echo "- Install plugin/base requirements.txt as root (so ledmatrix.service can see them)"
 echo ""
 
 # Ask for confirmation
@@ -147,6 +163,13 @@ fi
 if ! sudo chmod 755 "$SAFE_RM_PATH"; then
     echo "Warning: Could not set permissions on $SAFE_RM_PATH"
 fi
+echo "Hardening safe_pip_install.sh ownership..."
+if ! sudo chown root:root "$SAFE_PIP_INSTALL_PATH"; then
+    echo "Warning: Could not set ownership on $SAFE_PIP_INSTALL_PATH"
+fi
+if ! sudo chmod 755 "$SAFE_PIP_INSTALL_PATH"; then
+    echo "Warning: Could not set permissions on $SAFE_PIP_INSTALL_PATH"
+fi
 
 if sudo cp "$TEMP_SUDOERS" /etc/sudoers.d/ledmatrix_web; then
     echo "Configuration applied successfully!"
@@ -160,7 +183,7 @@ if sudo cp "$TEMP_SUDOERS" /etc/sudoers.d/ledmatrix_web; then
         echo "✗ systemctl status ledmatrix.service - Failed"
     fi
     
-    if sudo -n test -f "$PROJECT_DIR/start_display.sh"; then
+    if sudo -n test -f "$PROJECT_ROOT/start_display.sh"; then
         echo "✓ File access test - OK"
     else
         echo "✗ File access test - Failed"

scripts/install/install_web_service.sh

@@ -14,9 +14,6 @@ else
     ACTUAL_USER=$(whoami)
 fi
 
-# Get the home directory of the actual user
-USER_HOME=$(eval echo ~$ACTUAL_USER)
-
 # Determine the Project Root Directory (parent of scripts/install/)
 PROJECT_ROOT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
 
@@ -34,7 +31,8 @@ echo "Generating service file with dynamic paths..."
 WEB_SERVICE_FILE_CONTENT=$(cat <<EOF
 [Unit]
 Description=LED Matrix Web Interface Service
-After=network.target
+After=network-online.target
+Wants=network-online.target
 
 [Service]
 Type=simple

scripts/install/one-shot-install.sh

@@ -340,9 +340,14 @@ main() {
     echo ""
     
     # Execute with proper error handling and non-interactive mode
-    # Temporarily disable errexit to capture exit code instead of exiting immediately
+    # Temporarily disable errexit AND the ERR trap to capture exit code instead of
+    # exiting immediately. `set +e` alone does not suppress the ERR trap, so without
+    # `trap '' ERR` a non-zero exit from first_time_install.sh would trigger on_error
+    # here with the generic "Main installation" message instead of the detailed
+    # if/else handling below.
     set +e
-    
+    trap '' ERR
+
     # Check /tmp permissions - only fix if actually wrong (common in automated scenarios)
     # When running manually, /tmp usually has correct permissions (1777)
     TMP_PERMS=$(stat -c '%a' /tmp 2>/dev/null || echo "unknown")
@@ -370,6 +375,7 @@ main() {
         sudo -E env TMPDIR=/tmp LEDMATRIX_ASSUME_YES=1 bash ./first_time_install.sh -y </dev/null
     fi
     INSTALL_EXIT_CODE=$?
+    trap 'on_error $LINENO' ERR  # Re-enable ERR trap
     set -e  # Re-enable errexit
     
     if [ $INSTALL_EXIT_CODE -eq 0 ]; then

scripts/install_dependencies_apt.py

@@ -6,82 +6,143 @@ then falls back to pip with --break-system-packages
 
 import subprocess
 import sys
+import tempfile
 import warnings
+from collections import deque
 from pathlib import Path
+from typing import List, Tuple
 
-def install_via_apt(package_name):
-    """Try to install a package via apt."""
-    try:
-        # Map pip package names to apt package names
-        apt_package_map = {
-            'flask': 'python3-flask',
-            'PIL': 'python3-pil',
-            'freetype': 'python3-freetype',
-            'psutil': 'python3-psutil',
-            'werkzeug': 'python3-werkzeug',
-            'numpy': 'python3-numpy',
-            'requests': 'python3-requests',
-            'python-dateutil': 'python3-dateutil',
-            'pytz': 'python3-tz',
-            'geopy': 'python3-geopy',
-            'unidecode': 'python3-unidecode',
-            'websockets': 'python3-websockets',
-            'websocket-client': 'python3-websocket-client'
-        }
-        
-        apt_package = apt_package_map.get(package_name, f'python3-{package_name}')
-        
-        print(f"Trying to install {apt_package} via apt...")
-        subprocess.check_call([
-            'sudo', 'apt', 'update'
-        ], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
-        
-        subprocess.check_call([
-            'sudo', 'apt', 'install', '-y', apt_package
-        ], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
-        
+# How many trailing lines of a failed command's output to keep for the
+# end-of-run failure summary. Keeps the root cause near the end of the log,
+# which is where first_time_install.sh's error handler tails from.
+ERROR_TAIL_LINES = 15
+
+
+def _run(cmd: List[str]) -> Tuple[bool, str]:
+    """Run a command, streaming combined stdout/stderr to a temp file.
+
+    Returns (success, output) instead of raising, so callers can report
+    *why* a command failed rather than just that it failed. `output` is
+    bounded to the last ERROR_TAIL_LINES lines so failures from very
+    chatty commands (e.g. pip build logs) don't get buffered in memory.
+    """
+    with tempfile.TemporaryFile(mode='w+b') as f:
+        result = subprocess.run(cmd, stdout=f, stderr=subprocess.STDOUT)  # nosec B603 B607 - hardcoded apt/pip args  # nosemgrep
+        f.seek(0)
+        # Stream line-by-line so only the last ERROR_TAIL_LINES are ever held
+        # in memory, regardless of how much output the command produced.
+        tail = deque(
+            (line.decode('utf-8', errors='replace').rstrip('\n') for line in f),
+            maxlen=ERROR_TAIL_LINES,
+        )
+    return result.returncode == 0, '\n'.join(tail)
+
+
+def install_via_apt(package_name: str) -> Tuple[bool, str]:
+    """Try to install a package via apt. Returns (success, output)."""
+    # Map pip package names to apt package names
+    apt_package_map = {
+        'flask': 'python3-flask',
+        'PIL': 'python3-pil',
+        'freetype': 'python3-freetype',
+        'psutil': 'python3-psutil',
+        'werkzeug': 'python3-werkzeug',
+        'numpy': 'python3-numpy',
+        'requests': 'python3-requests',
+        'python-dateutil': 'python3-dateutil',
+        'pytz': 'python3-tz',
+        'geopy': 'python3-geopy',
+        'unidecode': 'python3-unidecode',
+        'websockets': 'python3-websockets',
+        'websocket-client': 'python3-websocket-client'
+    }
+
+    apt_package = apt_package_map.get(package_name, f'python3-{package_name}')
+
+    print(f"Trying to install {apt_package} via apt...")
+    success, output = _run(['sudo', 'apt-get', '-o', 'DPkg::Lock::Timeout=180', 'install', '-y', apt_package])
+    if success:
         print(f"Successfully installed {apt_package} via apt")
-        return True
-        
-    except subprocess.CalledProcessError:
-        print(f"Failed to install {package_name} via apt, will try pip")
-        return False
+        return True, ""
 
-def install_via_pip(package_name):
+    print(f"Failed to install {apt_package} via apt, will try pip")
+    return False, output
+
+
+def install_via_pip(package_name: str) -> Tuple[bool, str]:
     """Install a package via pip with --break-system-packages and --prefer-binary.
 
     --break-system-packages allows pip to install into the system Python on
     Debian/Ubuntu-based systems without a virtual environment.
     --prefer-binary prefers pre-built wheels over source distributions to avoid
     exhausting /tmp space during compilation.
-    """
-    try:
-        print(f"Installing {package_name} via pip...")
-        subprocess.check_call([
-            sys.executable, '-m', 'pip', 'install', '--break-system-packages', '--prefer-binary', package_name
-        ])
-        print(f"Successfully installed {package_name} via pip")
-        return True
-    except subprocess.CalledProcessError as e:
-        print(f"Failed to install {package_name} via pip: {e}")
-        return False
+    --ignore-installed stops pip from trying to *uninstall* packages that were
+    installed by apt (e.g. python3-requests). Those Debian packages ship no
+    pip RECORD file, so an uninstall attempt fails with "uninstall-no-record-file"
+    and aborts the whole install. With --ignore-installed, pip lays the new
+    version down in /usr/local where it shadows the apt copy instead of removing
+    it. This matters when a pip dependency (google-api-python-client pulls a
+    newer requests) needs to upgrade an apt-managed package.
 
-def check_package_installed(package_name):
+    Returns (success, output).
+    """
+    print(f"Installing {package_name} via pip...")
+    success, output = _run([
+        sys.executable, '-m', 'pip', 'install',
+        '--break-system-packages', '--prefer-binary', '--ignore-installed', package_name
+    ])
+    if success:
+        print(f"Successfully installed {package_name} via pip")
+        return True, ""
+
+    print(f"Failed to install {package_name} via pip (see failure summary at end of log)")
+    return False, output
+
+
+# Distribution (pip/apt) names whose importable module name differs.
+IMPORT_NAME_MAP = {
+    'python-dateutil': 'dateutil',
+    'websocket-client': 'websocket',
+}
+
+
+def check_package_installed(package_name: str) -> bool:
     """Check if a package is already installed."""
+    import_name = IMPORT_NAME_MAP.get(package_name, package_name)
     # Suppress deprecation warnings when checking if packages are installed
     # (we're just checking, not using them)
     with warnings.catch_warnings():
         warnings.filterwarnings('ignore', category=DeprecationWarning)
         try:
-            __import__(package_name)
+            __import__(import_name)
             return True
         except ImportError:
             return False
 
+
+def print_failure_summary(failed_packages: List[str], failure_details: dict) -> None:
+    print("\n" + "=" * 60)
+    print("DEPENDENCY INSTALLATION FAILURES - DETAILS")
+    print("=" * 60)
+    for package in failed_packages:
+        print(f"\nPackage: {package}")
+        print("-" * 40)
+        output = failure_details.get(package, "").strip()
+        if not output:
+            print("  (no output captured)")
+            continue
+        for line in output.splitlines()[-ERROR_TAIL_LINES:]:
+            print(f"  {line}")
+    print("=" * 60)
+
+
 def main():
     """Main installation function."""
     print("Installing dependencies for LED Matrix Web Interface V2...")
-    
+
+    print("Refreshing apt package index...")
+    _run(['sudo', 'apt', 'update'])  # best-effort; individual installs surface their own errors
+
     # List of required packages
     required_packages = [
         'flask',
@@ -98,19 +159,23 @@ def main():
         'websockets',
         'websocket-client'
     ]
-    
+
     failed_packages = []
-    
+    failure_details = {}
+
     for package in required_packages:
         if check_package_installed(package):
             print(f"{package} is already installed")
             continue
-            
+
         # Try apt first, then pip
-        if not install_via_apt(package):
-            if not install_via_pip(package):
+        ok, apt_output = install_via_apt(package)
+        if not ok:
+            ok, pip_output = install_via_pip(package)
+            if not ok:
                 failed_packages.append(package)
-    
+                failure_details[package] = pip_output or apt_output
+
     # Install packages that don't have apt equivalents
     special_packages = [
         'timezonefinder>=6.5.0,<7.0.0',
@@ -122,47 +187,49 @@ def main():
         'python-socketio>=5.11.0,<6.0.0',
         'python-engineio>=4.9.0,<5.0.0'
     ]
-    
+
     for package in special_packages:
-        if not install_via_pip(package):
+        ok, pip_output = install_via_pip(package)
+        if not ok:
             failed_packages.append(package)
-    
+            failure_details[package] = pip_output
+
     # Install rgbmatrix module from local source (optional - may already be installed in Step 6)
     # Check if already installed first
     if check_package_installed('rgbmatrix'):
         print("rgbmatrix module already installed, skipping...")
     else:
         print("Installing rgbmatrix module from local source...")
-        try:
-            # Get project root (parent of scripts directory)
-            PROJECT_ROOT = Path(__file__).parent.parent
-            rgbmatrix_path = PROJECT_ROOT / 'rpi-rgb-led-matrix-master' / 'bindings' / 'python'
-            if rgbmatrix_path.exists():
-                # Check if the module has been built (look for setup.py)
-                setup_py = rgbmatrix_path / 'setup.py'
-                if setup_py.exists():
-                    # Try installing - use regular install, not editable mode
-                    # This is optional for web interface and should already be installed in Step 6
-                    subprocess.check_call([
-                        sys.executable, '-m', 'pip', 'install', '--break-system-packages', str(rgbmatrix_path)
-                    ], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        # Get project root (parent of scripts directory)
+        PROJECT_ROOT = Path(__file__).parent.parent
+        rgbmatrix_path = PROJECT_ROOT / 'rpi-rgb-led-matrix-master' / 'bindings' / 'python'
+        if rgbmatrix_path.exists():
+            # Check if the module has been built (look for setup.py)
+            setup_py = rgbmatrix_path / 'setup.py'
+            if setup_py.exists():
+                # Try installing - use regular install, not editable mode
+                # This is optional for web interface and should already be installed in Step 6
+                ok, output = _run([sys.executable, '-m', 'pip', 'install', '--break-system-packages', str(rgbmatrix_path)])
+                if ok:
                     print("rgbmatrix module installed successfully")
                 else:
-                    print("Warning: rgbmatrix setup.py not found, module may need to be built first")
-                    print("  This is normal if Step 6 hasn't completed yet.")
+                    # Don't fail the whole installation - rgbmatrix is optional for web interface
+                    # and should be installed in Step 6 of first_time_install.sh
+                    print("Warning: Failed to install rgbmatrix module:")
+                    for line in output.strip().splitlines()[-ERROR_TAIL_LINES:]:
+                        print(f"  {line}")
+                    print("  This is normal if rgbmatrix hasn't been built yet (Step 6).")
+                    print("  The web interface will work without it.")
             else:
-                print("Warning: rgbmatrix source not found (this is normal if Step 6 hasn't run yet)")
-        except subprocess.CalledProcessError as e:
-            # Don't fail the whole installation - rgbmatrix is optional for web interface
-            # and should be installed in Step 6 of first_time_install.sh
-            print(f"Warning: Failed to install rgbmatrix module: {e}")
-            print("  This is normal if rgbmatrix hasn't been built yet (Step 6).")
-            print("  The web interface will work without it.")
-            # Don't add to failed_packages since it's optional
-    
+                print("Warning: rgbmatrix setup.py not found, module may need to be built first")
+                print("  This is normal if Step 6 hasn't completed yet.")
+        else:
+            print("Warning: rgbmatrix source not found (this is normal if Step 6 hasn't run yet)")
+
     if failed_packages:
         print(f"\nFailed to install the following packages: {failed_packages}")
         print("You may need to install them manually or check your system configuration.")
+        print_failure_summary(failed_packages, failure_details)
         return False
     else:
         print("\nAll dependencies installed successfully!")

scripts/render_plugin.py

@@ -17,7 +17,6 @@ import os
 import json
 import argparse
 from pathlib import Path
-from typing import Any, Dict, Optional, Sequence, Union
 
 # Add project root to path
 PROJECT_ROOT = Path(__file__).resolve().parent.parent
@@ -28,49 +27,15 @@ os.environ['EMULATOR'] = 'true'
 
 # Import logger after path setup so src.logging_config is importable
 from src.logging_config import get_logger  # noqa: E402
+from src.plugin_system.testing.loading import (  # noqa: E402
+    find_plugin_dir, load_manifest, load_config_defaults,
+)
 logger = get_logger("[Render Plugin]")
 
 MIN_DIMENSION = 1
 MAX_DIMENSION = 512
 
 
-def find_plugin_dir(plugin_id: str, search_dirs: Sequence[Union[str, Path]]) -> Optional[Path]:
-    """Find a plugin directory by searching multiple paths."""
-    from src.plugin_system.plugin_loader import PluginLoader
-    loader = PluginLoader()
-    for search_dir in search_dirs:
-        search_path = Path(search_dir)
-        if not search_path.exists():
-            continue
-        result = loader.find_plugin_directory(plugin_id, search_path)
-        if result:
-            return Path(result)
-    return None
-
-
-def load_manifest(plugin_dir: Path) -> Dict[str, Any]:
-    """Load and return manifest.json from plugin directory."""
-    manifest_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:
-        return json.load(f)
-
-
-def load_config_defaults(plugin_dir: Path) -> Dict[str, Any]:
-    """Extract default values from config_schema.json."""
-    schema_path = plugin_dir / 'config_schema.json'
-    if not schema_path.exists():
-        return {}
-    with open(schema_path, 'r') as f:
-        schema = json.load(f)
-    defaults: Dict[str, Any] = {}
-    for key, prop in schema.get('properties', {}).items():
-        if 'default' in prop:
-            defaults[key] = prop['default']
-    return defaults
-
-
 def main() -> int:
     """Load a plugin, call update() + display(), and save the result as a PNG image."""
     parser = argparse.ArgumentParser(description='Render a plugin display to a PNG image')
@@ -81,7 +46,7 @@ def main() -> int:
                         help='Plugin config as JSON string')
     parser.add_argument('--mock-data', '-m', default=None,
                         help='Path to JSON file with mock cache data')
-    parser.add_argument('--output', '-o', default='/tmp/plugin_render.png',
+    parser.add_argument('--output', '-o', default='/tmp/plugin_render.png',  # nosec B108 - dev script default; user can override
                         help='Output PNG path (default: /tmp/plugin_render.png)')
     parser.add_argument('--width', type=int, default=128, help='Display width (default: 128)')
     parser.add_argument('--height', type=int, default=32, help='Display height (default: 32)')

scripts/run_plugin_tests.py

@@ -7,9 +7,7 @@ Supports both unittest and pytest.
 """
 
 import sys
-import os
 import argparse
-import subprocess
 from pathlib import Path
 from typing import Optional
 
@@ -198,17 +196,14 @@ def main():
     if runner == 'auto':
         # Try pytest first, fall back to unittest
         try:
-            import pytest
             runner = 'pytest'
         except ImportError:
             runner = 'unittest'
     
     # Run tests
     if runner == 'pytest':
-        import importlib.util
         return run_pytest_tests(test_files, args.verbose, args.coverage)
     else:
-        import importlib.util
         return run_unittest_tests(test_files, args.verbose)
 
 

scripts/templates/dev_preview.html

@@ -209,6 +209,11 @@
                            onchange="onConfigChange()">
                     <span class="text-xs ml-2" style="color: var(--text-secondary);">px</span>
                 </div>
+                <select id="sizePreset" onchange="applySizePreset()"
+                        class="w-full mt-2 px-2 py-1.5 rounded text-xs"
+                        style="background: var(--bg-primary); color: var(--text-secondary); border: 1px solid var(--border-color);">
+                    <option value="">Preset sizes…</option>
+                </select>
             </div>
 
             <!-- Config form -->
@@ -242,13 +247,18 @@
                 </div>
             </details>
 
-            <!-- Render button -->
+            <!-- Render buttons -->
             <div class="flex gap-2">
                 <button onclick="renderPlugin()" id="renderBtn"
                         class="flex-1 px-4 py-2.5 rounded-lg text-sm font-medium text-white"
                         style="background: var(--accent);">
                     Render
                 </button>
+                <button onclick="renderAllSizes()" id="renderAllBtn" title="Render at every harness test size"
+                        class="px-4 py-2.5 rounded-lg text-sm font-medium"
+                        style="background: var(--bg-tertiary); color: var(--text-primary); border: 1px solid var(--border-color);">
+                    All Sizes
+                </button>
             </div>
         </div>
 
@@ -311,6 +321,15 @@
             <div id="messagesPanel" class="panel p-3 hidden">
                 <div id="messagesList" class="text-xs font-mono space-y-1"></div>
             </div>
+
+            <!-- Multi-size gallery -->
+            <div id="galleryPanel" class="panel p-4 hidden">
+                <div class="flex items-center justify-between mb-3">
+                    <span class="text-xs font-medium" style="color: var(--text-secondary);">All Sizes</span>
+                    <span class="text-xs" style="color: var(--text-secondary);" id="galleryStatus"></span>
+                </div>
+                <div id="galleryGrid" class="flex flex-wrap gap-4 items-start"></div>
+            </div>
         </div>
     </div>
 
@@ -340,8 +359,30 @@
                 opt.textContent = `${p.name} (${p.id})`;
                 select.appendChild(opt);
             });
+
+            // Load harness size presets
+            try {
+                const sizesRes = await fetch('/api/sizes');
+                const sizesData = await sizesRes.json();
+                const preset = document.getElementById('sizePreset');
+                (sizesData.sizes || []).forEach(([w, h]) => {
+                    const opt = document.createElement('option');
+                    opt.value = `${w}x${h}`;
+                    opt.textContent = `${w} x ${h}`;
+                    preset.appendChild(opt);
+                });
+            } catch (e) { /* presets are a convenience; ignore */ }
         });
 
+        function applySizePreset() {
+            const value = document.getElementById('sizePreset').value;
+            if (!value) return;
+            const [w, h] = value.split('x');
+            document.getElementById('displayWidth').value = w;
+            document.getElementById('displayHeight').value = h;
+            onConfigChange();
+        }
+
         // ---------- Plugin selection ----------
         async function onPluginChange() {
             const pluginId = document.getElementById('pluginSelect').value;
@@ -485,6 +526,89 @@
             }
         }
 
+        // ---------- Multi-size gallery ----------
+        async function renderAllSizes() {
+            if (!currentPluginId) return;
+
+            const btn = document.getElementById('renderAllBtn');
+            const panel = document.getElementById('galleryPanel');
+            const grid = document.getElementById('galleryGrid');
+            const status = document.getElementById('galleryStatus');
+            btn.disabled = true;
+            btn.textContent = 'Rendering…';
+            panel.classList.remove('hidden');
+            grid.innerHTML = '';
+            status.textContent = 'Rendering at all harness sizes…';
+
+            const config = jsonEditor ? jsonEditor.getValue() : {};
+            config.enabled = true;
+            let mockData = {};
+            const mockInput = document.getElementById('mockDataInput').value.trim();
+            if (mockInput) {
+                try { mockData = JSON.parse(mockInput); }
+                catch (e) { showMessages([], [`Mock data JSON error: ${e.message}`]); }
+            }
+
+            try {
+                const res = await fetch('/api/render-matrix', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        plugin_id: currentPluginId,
+                        config: config,
+                        mock_data: mockData,
+                    }),
+                });
+                const data = await res.json();
+                if (data.error) {
+                    status.textContent = data.error;
+                    return;
+                }
+
+                let failures = 0;
+                (data.results || []).forEach(r => {
+                    const cell = document.createElement('div');
+                    cell.style.cssText = 'display:flex;flex-direction:column;gap:4px;';
+                    const failed = (r.errors || []).length > 0 || !r.image;
+                    if (failed) failures++;
+
+                    const label = document.createElement('span');
+                    label.className = 'text-xs font-mono';
+                    label.style.color = failed ? '#f87171' : 'var(--text-secondary)';
+                    label.textContent = `${r.width}x${r.height} · ${r.render_time_ms}ms`;
+                    cell.appendChild(label);
+
+                    if (r.image) {
+                        const img = document.createElement('img');
+                        img.src = r.image;
+                        // Small panels get 2x zoom so they stay legible in the grid
+                        const zoom = r.height >= 128 ? 1 : 2;
+                        img.style.cssText =
+                            `image-rendering: pixelated; width:${r.width * zoom}px; ` +
+                            `height:${r.height * zoom}px; ` +
+                            `border:1px solid ${failed ? '#f87171' : 'var(--border-color)'};`;
+                        cell.appendChild(img);
+                    }
+                    if (failed) {
+                        const err = document.createElement('span');
+                        err.className = 'text-xs font-mono';
+                        err.style.color = '#f87171';
+                        err.textContent = (r.errors || ['render failed']).join('; ');
+                        cell.appendChild(err);
+                    }
+                    grid.appendChild(cell);
+                });
+                status.textContent = failures
+                    ? `${failures} size(s) failed`
+                    : `${(data.results || []).length} sizes rendered`;
+            } catch (e) {
+                status.textContent = `Network error: ${e.message}`;
+            } finally {
+                btn.disabled = false;
+                btn.textContent = 'All Sizes';
+            }
+        }
+
         // ---------- Zoom ----------
         function updateZoom() {
             const zoom = parseInt(document.getElementById('zoomSlider').value);

scripts/utils/clear_cache.py

@@ -6,9 +6,7 @@ This script allows manual clearing of specific cache keys or all cache data.
 
 import os
 import sys
-import json
 import argparse
-from pathlib import Path
 
 # Add the src directory to the path so we can import our modules
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'src'))

scripts/utils/start_web_conditionally.py

@@ -111,7 +111,7 @@ def main():
             # Ensure PYTHONPATH is set correctly if web_interface.py has relative imports to src
             # The WorkingDirectory in systemd service should handle this for web_interface.py
             print(f"Launching web interface v3: {sys.executable} {WEB_INTERFACE_SCRIPT}")
-            os.execvp(sys.executable, [sys.executable, WEB_INTERFACE_SCRIPT])
+            os.execvp(sys.executable, [sys.executable, WEB_INTERFACE_SCRIPT])  # nosec B606 - both args are fixed constants
         except Exception as e:
             print(f"Failed to exec web interface: {e}")
             sys.exit(1) # Failed to start

scripts/utils/wifi_monitor_daemon.py

@@ -155,7 +155,7 @@ class WiFiMonitorDaemon:
                                 logger.error(f"NetworkManager restart failed (rc={e.returncode}); "
                                              "resetting failure counter to avoid tight retry loop")
                                 self._consecutive_internet_failures = 0
-                            except Exception as e:
+                            except (subprocess.SubprocessError, OSError) as e:
                                 logger.error(f"NetworkManager restart error: {e}; "
                                              "resetting failure counter to avoid tight retry loop")
                                 self._consecutive_internet_failures = 0

src/__init__.py

@@ -4,5 +4,5 @@ LEDMatrix Display System
 Core source package for the LED Matrix Display project.
 """
 
-__version__ = "1.0.0"
+__version__ = "3.1.0"
 

src/adaptive_images.py

@@ -0,0 +1,174 @@
+"""
+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
+
+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))
+    if (out_w, out_h) == (src_w, src_h):
+        # No resize needed — but `work` may still BE the caller's original
+        # image (RGBA source, no ink crop). The result must always be an
+        # independent copy: LayoutContext caches ImageFitResults, and an
+        # aliased image would let later mutations of the source corrupt
+        # cached fits (or vice versa).
+        out = work.copy() if work is img else work
+    else:
+        out = 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

@@ -0,0 +1,746 @@
+"""
+Adaptive layout and font scaling helpers for plugins.
+
+Generalizes the three size-adaptation patterns proven in the plugin
+ecosystem into small composable core helpers, so plugins render legibly on
+any panel size (64x32, 128x32, 96x48, 128x64, 256x64, ...) without
+hand-tuned per-display layouts:
+
+- Region: integer rect algebra (bands, columns, weighted splits, centering).
+  Regions partition space, so text bands can't overlap by construction —
+  replacing the magic ``y = 1`` / ``y = height - 7`` offsets tuned for 128x32.
+- Font ladders: ordered (family, size) steps known to render crisply.
+  Pixel fonts (BDF, PressStart2P) only look right at native/integer sizes,
+  so fonts are never scaled continuously — fitting walks a ladder from the
+  largest rung down until the measured text fits the target box. This is
+  baseball-scoreboard's fallback-ladder pattern promoted to core.
+- LayoutContext: per-(width, height) facts — breakpoint tiers
+  (masters-tournament's pattern), a geometry scale factor vs. a declared
+  design size (f1-scoreboard's pattern), and cached fit-text queries.
+
+Everything is opt-in: plugins get a context via ``self.layout`` on
+BasePlugin (or construct one directly) and existing plugins are unaffected.
+
+Fonts are resolved through FontManager's catalog (family names are
+lowercased file stems from assets/fonts, e.g. "9x15", "tom-thumb", plus
+aliases like "press_start"). FitResult.font is a plain PIL font or
+freetype.Face, so it drops straight into DisplayManager.draw_text().
+"""
+
+import logging
+from collections import OrderedDict
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Sequence, Tuple, Union
+
+import freetype
+
+logger = logging.getLogger(__name__)
+
+# Height-based breakpoint tiers, smallest to largest. A 32px-tall panel is
+# the ecosystem baseline ("sm"); 96x48 lands in "md"; 128x64 in "lg".
+_HEIGHT_TIERS: Tuple[Tuple[str, int], ...] = (
+    ("xs", 16), ("sm", 32), ("md", 48), ("lg", 64), ("xl", 10 ** 9),
+)
+TIER_ORDER: Tuple[str, ...] = tuple(name for name, _ in _HEIGHT_TIERS)
+
+_WIDTH_TIERS: Tuple[Tuple[str, int], ...] = (
+    ("narrow", 64), ("normal", 128), ("wide", 256), ("ultrawide", 10 ** 9),
+)
+WIDTH_TIER_ORDER: Tuple[str, ...] = tuple(name for name, _ in _WIDTH_TIERS)
+
+# The panel size most existing plugins were authored against.
+DEFAULT_DESIGN_SIZE: Tuple[int, int] = (128, 32)
+
+
+@dataclass(frozen=True)
+class Region:
+    """An integer rectangle. Carving methods return sub-Regions clamped to
+    non-negative dimensions, so degenerate panels never produce negative
+    boxes — a band request larger than the region simply consumes it all."""
+
+    x: int
+    y: int
+    w: int
+    h: int
+
+    def __post_init__(self):
+        object.__setattr__(self, "w", max(0, int(self.w)))
+        object.__setattr__(self, "h", max(0, int(self.h)))
+        object.__setattr__(self, "x", int(self.x))
+        object.__setattr__(self, "y", int(self.y))
+
+    @property
+    def right(self) -> int:
+        return self.x + self.w
+
+    @property
+    def bottom(self) -> int:
+        return self.y + self.h
+
+    @property
+    def center(self) -> Tuple[int, int]:
+        return (self.x + self.w // 2, self.y + self.h // 2)
+
+    # ---- carving -----------------------------------------------------
+
+    def inset(self, dx: int, dy: Optional[int] = None) -> "Region":
+        """Shrink by dx horizontally and dy (default dx) vertically, each side."""
+        if dy is None:
+            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))
+
+    def bottom_band(self, h: int) -> "Region":
+        h = min(h, self.h)
+        return Region(self.x, self.bottom - h, self.w, h)
+
+    def middle(self, top_h: int = 0, bottom_h: int = 0) -> "Region":
+        """What remains between a top band and a bottom band."""
+        return Region(self.x, self.y + top_h, self.w, self.h - top_h - bottom_h)
+
+    def left_col(self, w: int) -> "Region":
+        return Region(self.x, self.y, min(w, self.w), self.h)
+
+    def right_col(self, w: int) -> "Region":
+        w = min(w, self.w)
+        return Region(self.right - w, self.y, w, self.h)
+
+    def split_h(self, *weights: float, gap: int = 0) -> List["Region"]:
+        """Side-by-side columns sized by weight; gaps between them."""
+        sizes = _weighted_sizes(self.w, weights, gap)
+        cols, cursor = [], self.x
+        for size in sizes:
+            cols.append(Region(cursor, self.y, size, self.h))
+            cursor += size + gap
+        return cols
+
+    def split_v(self, *weights: float, gap: int = 0) -> List["Region"]:
+        """Stacked rows sized by weight; gaps between them."""
+        sizes = _weighted_sizes(self.h, weights, gap)
+        rows, cursor = [], self.y
+        for size in sizes:
+            rows.append(Region(self.x, cursor, self.w, size))
+            cursor += size + gap
+        return rows
+
+    # ---- placement ---------------------------------------------------
+
+    def align_xy(self, w: int, h: int, align: str = "center",
+                 valign: str = "center") -> Tuple[int, int]:
+        """Top-left position for a w x h box aligned within this region.
+        align: left|center|right; valign: top|center|bottom."""
+        if align == "left":
+            x = self.x
+        elif align == "right":
+            x = self.right - w
+        else:
+            x = self.x + (self.w - w) // 2
+        if valign == "top":
+            y = self.y
+        elif valign == "bottom":
+            y = self.bottom - h
+        else:
+            y = self.y + (self.h - h) // 2
+        return (x, y)
+
+    def center_xy(self, w: int, h: int) -> Tuple[int, int]:
+        return self.align_xy(w, h)
+
+    def contains(self, w: int, h: int) -> bool:
+        return w <= self.w and h <= self.h
+
+
+def _weighted_sizes(total: int, weights: Sequence[float], gap: int) -> List[int]:
+    """Integer sizes proportional to weights, remainder spread left-to-right."""
+    if not weights:
+        return []
+    usable = max(0, total - gap * (len(weights) - 1))
+    weight_sum = sum(weights) or 1
+    sizes = [int(usable * w / weight_sum) for w in weights]
+    remainder = usable - sum(sizes)
+    for i in range(remainder):
+        sizes[i % len(sizes)] += 1
+    return sizes
+
+
+# ---------------------------------------------------------------------------
+# Font ladders
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class FontStep:
+    """One rung: a FontManager catalog family at a size it renders crisply."""
+    family: str
+    size_px: int
+
+
+FontLadder = Tuple[FontStep, ...]
+
+# X11 BDF bitmap fonts at their native pixel sizes, largest to smallest —
+# baseball-scoreboard's fallback ladder extended upward. Same-height rungs
+# are ordered widest first so width-constrained text steps to a narrower
+# face before dropping a size.
+LADDER_GRID: FontLadder = (
+    FontStep("10x20", 20),
+    FontStep("9x18", 18),
+    FontStep("9x15", 15),
+    FontStep("8x13", 13),
+    FontStep("7x13", 13),
+    FontStep("6x13", 13),
+    FontStep("6x12", 12),
+    FontStep("6x10", 10),
+    FontStep("6x9", 9),
+    FontStep("5x8", 8),
+    FontStep("5x7", 7),
+    FontStep("4x6", 6),
+    FontStep("tom-thumb", 6),
+)
+
+# PressStart2P at integer multiples of its 8px pixel grid only — fractional
+# sizes blur a pixel font. For headline text (clocks, scores).
+LADDER_ARCADE: FontLadder = (
+    FontStep("press_start", 32),
+    FontStep("press_start", 24),
+    FontStep("press_start", 16),
+    FontStep("press_start", 8),
+)
+
+LADDER_DEFAULT: FontLadder = LADDER_GRID
+
+ELLIPSIS = "…"
+
+
+@dataclass(frozen=True)
+class FitResult:
+    """A fitted font plus the ink metrics of the (possibly ellipsized) text.
+
+    ``y_offset`` is the gap between the y passed to draw_text() and where
+    ink actually starts; subtract it from the desired ink-top position when
+    drawing (draw_fitted_text does this for you).
+    """
+    font: Any
+    family: str
+    size_px: int
+    text: str
+    width: int
+    height: int
+    baseline: int
+    y_offset: int
+    fits: bool
+    line_height: int = 0
+
+
+def measure_ink(text: str, font: Any) -> Tuple[int, int, int, int]:
+    """Measure the ink box of text: (width, height, baseline, y_offset).
+
+    y_offset is the distance from the y coordinate DisplayManager.draw_text()
+    is given to the top of the actual ink — PIL draws TTF from the em-box
+    top and _draw_bdf_text derives the baseline from y + ascender, so both
+    leave a font-dependent gap that matters when centering in short bands.
+    """
+    if isinstance(font, freetype.Face):
+        width = 0
+        ascender = font.size.ascender >> 6
+        ink_top, ink_bottom = None, None
+        for char in text:
+            font.load_char(char)
+            width += font.glyph.advance.x >> 6
+            rows = font.glyph.bitmap.rows
+            if rows:
+                top = ascender - font.glyph.bitmap_top
+                ink_top = top if ink_top is None else min(ink_top, top)
+                ink_bottom = top + rows if ink_bottom is None else max(ink_bottom, top + rows)
+        if ink_top is None:
+            ink_top, ink_bottom = 0, 0
+        return (width, ink_bottom - ink_top, ascender, ink_top)
+    bbox = font.getbbox(text)
+    return (bbox[2] - bbox[0], bbox[3] - bbox[1], -bbox[1], bbox[1])
+
+
+def font_line_height(font: Any) -> int:
+    """Recommended line spacing for a font (matches DisplayManager.get_font_height)."""
+    if isinstance(font, freetype.Face):
+        return font.size.height >> 6
+    ascent, descent = font.getmetrics()
+    return ascent + descent
+
+
+def measure_font_crispness(font: Any, sample_text: str = "Ay0",
+                           canvas_size: Tuple[int, int] = (250, 60)) -> float:
+    """Fraction of the rendered sample's ink-bbox pixels that are neither
+    pure black nor pure white — i.e. antialiased.
+
+    BDF (freetype.Face) glyphs are true bitmaps and always render at 0.0.
+    "Pixel-style" TTFs (PressStart2P, and similar fonts bundled for
+    plugins that draw through ImageDraw.text() and so can't take a BDF
+    face) are NOT automatically crisp at arbitrary sizes — PIL antialiases
+    TTF outlines by default, and a pixel-grid font only lands on whole
+    pixels at specific sizes (for PressStart2P: exact multiples of 8).
+    Requesting an unverified size silently produces soft/blurry glyphs on
+    an LED panel, which reads as fuzzy compared to a true BDF rung.
+
+    Use this to vet any custom FontLadder rung that mixes TTF fonts before
+    shipping it — see test_adaptive_layout.py::test_ladder_is_crisp for the
+    pattern. A rung should score 0.0 (or very close, to allow for the odd
+    diagonal stroke) before it belongs in a "crisp" ladder.
+    """
+    if isinstance(font, freetype.Face):
+        return 0.0
+    from PIL import Image, ImageDraw
+    img = Image.new("L", canvas_size, 0)
+    ImageDraw.Draw(img).text((2, 2), sample_text, font=font, fill=255)
+    bbox = img.getbbox()
+    if bbox is None:
+        return 0.0
+    pixels = img.crop(bbox).tobytes()
+    pure = sum(1 for p in pixels if p == 0 or p == 255)
+    return (len(pixels) - pure) / len(pixels)
+
+
+class LayoutContext:
+    """Per-render-size layout facts and fit-text queries for one panel size.
+
+    Construct once per (width, height); BasePlugin.layout does this and
+    rebuilds automatically when the logical display size changes.
+    """
+
+    def __init__(self, width: int, height: int, font_manager: Any,
+                 design_size: Tuple[int, int] = DEFAULT_DESIGN_SIZE):
+        self.width = int(width)
+        self.height = int(height)
+        self.font_manager = font_manager
+        self.design_size = design_size
+        self.bounds = Region(0, 0, self.width, self.height)
+        self.aspect = self.width / max(1, self.height)
+        self.tier = _pick_tier(_HEIGHT_TIERS, self.height)
+        self.width_tier = _pick_tier(_WIDTH_TIERS, self.width)
+        self.is_wide_short = self.aspect >= 2.5 and self.height <= 32
+        design_w, design_h = design_size
+        # Geometry scale only (gaps, icon/logo sizes) — never applied to
+        # fonts, which step between crisp ladder rungs instead.
+        self.scale = min(self.width / max(1, design_w),
+                         self.height / max(1, design_h))
+        # LRU-bounded: entries are small, but keys embed the fitted TEXT —
+        # a plugin fitting changing text (a live game clock, a ticker) on a
+        # 24/7 service would otherwise grow this without bound.
+        self._fit_cache: "OrderedDict[Any, FitResult]" = OrderedDict()
+        # LRU-bounded (images are big). 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
+    _FIT_CACHE_MAX = 512
+
+    def _fit_cache_get(self, key: Any) -> Optional["FitResult"]:
+        cached = self._fit_cache.get(key)
+        if cached is not None:
+            self._fit_cache.move_to_end(key)
+        return cached
+
+    def _fit_cache_put(self, key: Any, result: "FitResult") -> None:
+        self._fit_cache[key] = result
+        while len(self._fit_cache) > self._FIT_CACHE_MAX:
+            self._fit_cache.popitem(last=False)
+
+    # ---- the three adaptation patterns --------------------------------
+
+    def px(self, base: int, minimum: int = 1, maximum: Optional[int] = None) -> int:
+        """Scale a design-size pixel measurement (f1's pattern): gaps,
+        icon sizes, logo slots. Clamped to [minimum, maximum]."""
+        value = max(minimum, round(base * self.scale))
+        if maximum is not None:
+            value = min(value, maximum)
+        return value
+
+    def by_tier(self, mapping: Dict[str, Any], default: Any = None) -> Any:
+        """Pick the value for the nearest defined tier at-or-below the
+        panel's height tier (masters' pattern). Falls forward to the
+        smallest defined tier above, then to default.
+
+        by_tier({"sm": 10, "lg": 18}) -> 10 on 128x32, 18 on 128x64.
+        Keys may also use width tiers ("narrow", "wide", ...)."""
+        order = TIER_ORDER if any(k in TIER_ORDER for k in mapping) else WIDTH_TIER_ORDER
+        current = self.tier if order is TIER_ORDER else self.width_tier
+        idx = order.index(current)
+        for name in reversed(order[: idx + 1]):
+            if name in mapping:
+                return mapping[name]
+        for name in order[idx + 1:]:
+            if name in mapping:
+                return mapping[name]
+        return default
+
+    def fit_text(self, text: str, box: Union[Region, Tuple[int, int]],
+                 ladder: FontLadder = LADDER_DEFAULT,
+                 ellipsis: bool = True) -> FitResult:
+        """Largest ladder rung whose rendered text fits the box (baseball's
+        pattern). If even the smallest rung is too wide, the text is
+        ellipsized to fit (unless ellipsis=False); fits=False only when no
+        acceptable rendering exists."""
+        box_w, box_h = _box_dims(box)
+        key = ("text", text, box_w, box_h, ladder, ellipsis)
+        cached = self._fit_cache_get(key)
+        if cached is not None:
+            return cached
+        result = self._walk_ladder(text, ladder, box_w, box_h, ellipsis)
+        self._fit_cache_put(key, result)
+        return result
+
+    def fit_text_proportional(self, text: str, box: Union[Region, Tuple[int, int]],
+                              base_size_px: int, ladder: FontLadder = LADDER_DEFAULT,
+                              ellipsis: bool = True,
+                              scale: Optional[float] = None) -> FitResult:
+        """Ladder rung closest to (but not exceeding) ``base_size_px * scale``
+        that still fits the box — proportional sizing instead of ``fit_text``'s
+        "always maximize" behavior.
+
+        Use this when several independently-fitted elements need to stay
+        visually harmonious as the panel grows (e.g. a scoreboard's score,
+        status, and detail text) — ``fit_text`` maximizes each one within
+        its own region, which can make one element balloon out of
+        proportion to its neighbors (a huge score overlapping logos it fit
+        fine at the design size) even though every individual pick is
+        independently "correct". ``base_size_px`` is the size that element
+        renders at on the design size (``design_size``, typically 128x32)
+        — commonly a plugin's existing classic/fixed font size for that
+        element.
+
+        ``scale`` defaults to ``self.scale`` (the same conservative
+        min(width_ratio, height_ratio) factor ``px()`` uses — safe for
+        content whose aspect ratio matters). Pass an explicit axis-specific
+        value when the surrounding composition already scales that way —
+        e.g. a scoreboard whose logos scale with height alone
+        (``logo_slot = min(height, width // 2)``) should size its score
+        text by ``height / design_height`` too, or its text will look
+        under-scaled next to bigger logos on a panel that only grew taller.
+
+        Falls back to the smallest rung when even that exceeds the target
+        (a tiny scale factor), and to fit_text's ordinary smaller-rung
+        fallback when the closest-to-target rung doesn't actually fit the
+        box.
+        """
+        box_w, box_h = _box_dims(box)
+        effective_scale = self.scale if scale is None else scale
+        key = ("text_prop", text, box_w, box_h, ladder, base_size_px, ellipsis, effective_scale)
+        cached = self._fit_cache_get(key)
+        if cached is not None:
+            return cached
+        target = base_size_px * effective_scale
+        eligible = [step for step in ladder if step.size_px <= target]
+        candidates = eligible if eligible else (min(ladder, key=lambda s: s.size_px),)
+        result = self._walk_ladder(text, candidates, box_w, box_h, ellipsis)
+        self._fit_cache_put(key, result)
+        return result
+
+    def _walk_ladder(self, text: str, ladder: Sequence[FontStep],
+                     box_w: int, box_h: int, ellipsis: bool) -> FitResult:
+        """Shared by fit_text/fit_text_proportional: first ladder entry (in
+        the order given) whose rendered text fits, ellipsizing the last one
+        tried if none do."""
+        result = None
+        for step in ladder:
+            font = self.font_manager.get_font(step.family, step.size_px)
+            width, height, baseline, y_offset = measure_ink(text, font)
+            result = FitResult(font, step.family, step.size_px, text,
+                               width, height, baseline, y_offset,
+                               fits=(width <= box_w and height <= box_h),
+                               line_height=font_line_height(font))
+            if result.fits:
+                break
+
+        if result is not None and not result.fits and ellipsis:
+            short = self.ellipsize(text, result.font, box_w)
+            width, height, baseline, y_offset = measure_ink(short, result.font)
+            result = FitResult(result.font, result.family, result.size_px,
+                               short, width, height, baseline, y_offset,
+                               fits=(width <= box_w and height <= box_h),
+                               line_height=result.line_height)
+        return result
+
+    def fit_lines(self, lines: Sequence[str], box: Union[Region, Tuple[int, int]],
+                  ladder: FontLadder = LADDER_DEFAULT,
+                  spacing: int = 1) -> FitResult:
+        """Largest rung where every line fits the box width and the stacked
+        lines (line_height + spacing apart) fit the box height. Measures the
+        actual strings, so a long line pushes the ladder down a rung a short
+        one wouldn't (baseball's multiline pattern). Text is the widest line."""
+        box_w, box_h = _box_dims(box)
+        key = ("lines", tuple(lines), box_w, box_h, ladder, spacing)
+        cached = self._fit_cache_get(key)
+        if cached is not None:
+            return cached
+
+        rows = max(1, len(lines))
+        result = None
+        for step in ladder:
+            font = self.font_manager.get_font(step.family, step.size_px)
+            line_h = font_line_height(font)
+            widest, metrics = "", (0, 0, 0, 0)
+            for line in lines:
+                m = measure_ink(line, font)
+                if m[0] >= metrics[0]:
+                    widest, metrics = line, m
+            total_h = rows * line_h + (rows - 1) * spacing
+            result = FitResult(font, step.family, step.size_px, widest,
+                               metrics[0], metrics[1], metrics[2], metrics[3],
+                               fits=(metrics[0] <= box_w and total_h <= box_h),
+                               line_height=line_h)
+            if result.fits:
+                break
+
+        self._fit_cache_put(key, result)
+        return result
+
+    def font_for_rows(self, rows: int, box_h: int,
+                      ladder: FontLadder = LADDER_GRID) -> FitResult:
+        """Largest rung whose line height lets `rows` rows fit in box_h
+        (baseball's traditional-scoreboard pattern). Measures a digit/cap
+        sample rather than specific strings."""
+        key = ("rows", rows, box_h, ladder)
+        cached = self._fit_cache_get(key)
+        if cached is not None:
+            return cached
+
+        sample = "0Ay"
+        result = None
+        for step in ladder:
+            font = self.font_manager.get_font(step.family, step.size_px)
+            line_h = font_line_height(font)
+            width, height, baseline, y_offset = measure_ink(sample, font)
+            result = FitResult(font, step.family, step.size_px, sample,
+                               width, height, baseline, y_offset,
+                               fits=(max(1, rows) * line_h <= box_h),
+                               line_height=line_h)
+            if result.fits:
+                break
+
+        self._fit_cache_put(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:
+        """Trim text to fit max_w, appending an ellipsis. Returns '' when
+        not even the ellipsis fits."""
+        if measure_ink(text, font)[0] <= max_w:
+            return text
+        for end in range(len(text) - 1, 0, -1):
+            candidate = text[:end].rstrip() + ELLIPSIS
+            if measure_ink(candidate, font)[0] <= max_w:
+                return candidate
+        return ELLIPSIS if measure_ink(ELLIPSIS, font)[0] <= max_w else ""
+
+    def measure(self, text: str, font: Any) -> Tuple[int, int, int]:
+        """Ink (width, height, baseline) of text — see measure_ink."""
+        width, height, baseline, _ = measure_ink(text, font)
+        return (width, height, baseline)
+
+    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:
+    for name, limit in tiers:
+        if value <= limit:
+            return name
+    return tiers[-1][0]
+
+
+def _box_dims(box: Union[Region, Tuple[int, int]]) -> Tuple[int, int]:
+    if isinstance(box, Region):
+        return (box.w, box.h)
+    w, h = box
+    return (int(w), int(h))
+
+
+def draw_fitted_text(display_manager: Any, fit: FitResult,
+                     box: Union[Region, Tuple[int, int]],
+                     color: Tuple[int, int, int] = (255, 255, 255),
+                     align: str = "center", valign: str = "center") -> None:
+    """Draw a FitResult's text aligned within a Region via
+    DisplayManager.draw_text(), compensating for the font's ink offset so
+    the ink (not the em box) is what gets aligned."""
+    region = box if isinstance(box, Region) else Region(0, 0, box[0], box[1])
+    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), center-reserved
+    away_slot: Region     # left logo slot
+    home_slot: Region     # right logo slot
+    center_col: Region    # column between the slots (>= min_center_fraction of width)
+    status_band: Region   # top band (replaces the magic y = 1)
+    score_area: Region    # center_col's true width, between 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,
+                       min_center_fraction: float = 0.15,
+                       min_center_design_px: int = 40,
+                       score_bleed_fraction: float = 0.5) -> 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.
+
+    That formula alone has a blind spot: at exactly 2:1 aspect ratio
+    (width == 2 * height — a very common shape, e.g. 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. It isn't a "small panel" problem: 96x48, 128x64, and
+    256x128 (all exactly 2:1) hit it identically, while wide panels like
+    the 128x32 design baseline or a 192x48/256x32 panel never do, because
+    height is already the tighter constraint there.
+
+    Two knobs fix it, both defaulted to values verified against the full
+    harness size spread (see test_adaptive_layout.py::TestScoreboardRegions):
+
+    - ``min_center_fraction`` / ``min_center_design_px`` reserve at least
+      ``max(width * min_center_fraction, min_center_design_px * ctx.scale)``
+      for the center column, capping ``logo_slot`` further when needed. The
+      design-px term (scaled by the context's geometry factor, so it grows
+      on bigger panels like everything else in ``px()``) matters most on
+      small panels where a flat fraction alone reserves too little absolute
+      space for even a short score string. On wide panels the height
+      constraint already leaves more room than either reserves, so both are
+      a no-op there — 128x32/192x48-style layouts are unaffected.
+    - ``score_bleed_fraction`` extends the score's own *fit box* (not the
+      logo slots themselves) an extra ``logo_slot * score_bleed_fraction``
+      into each side — controlled, intentional overlap with the logo art,
+      the same way real broadcast scoreboards let a big score number's
+      edges cross into the team marks flanking it. Without this, on a
+      square-ish panel the center reserve alone can be too narrow for even
+      a modest score to render without truncating (`"17-21"` -> `"17-2…"`),
+      which is worse than a little overlap.
+
+    status_band and detail_band span the FULL card width and overlay the
+    logo slots — matching the classic layouts, where short outlined status/
+    date text is drawn over the logos without issue; only score_area (the
+    one element whose size actively grows with the panel) uses the
+    narrower, bleed-adjusted box. 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)
+    design_reserve = int(min_center_design_px * (ctx.scale if ctx else 1.0))
+    min_center_w = max(1, int(bounds.w * min_center_fraction), design_reserve)
+    max_logo_slot_by_center = max(1, (bounds.w - min_center_w) // 2)
+    logo_slot = min(logo_slot, max_logo_slot_by_center)
+    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 = bounds.top_band(status_h)
+    detail_band = bounds.bottom_band(detail_h)
+    middle = bounds.middle(status_band.h, detail_band.h)
+    # score_area is the true center gap's width plus a controlled bleed
+    # into each logo slot (see score_bleed_fraction above) -- narrower than
+    # the full card width status/detail get, since it's the one element
+    # whose size actively grows with the panel and needs its *fit box* to
+    # reflect real available space, but generous enough that a short score
+    # string never has to truncate on a square-ish panel.
+    bleed = int(logo_slot * score_bleed_fraction)
+    score_area = Region(center_col.x - bleed, middle.y,
+                        center_col.w + 2 * bleed, middle.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/background_cache_mixin.py

@@ -7,10 +7,7 @@ where Recent/Upcoming managers consume data from the background service cache.
 """
 
 import time
-import logging
 from typing import Dict, Optional, Any, Callable
-from datetime import datetime
-import pytz
 
 
 class BackgroundCacheMixin:

src/background_data_service.py

@@ -14,19 +14,15 @@ Key Features:
 - Memory-efficient data storage
 """
 
-import os
 import time
 import logging
 import threading
 import requests
-from typing import Dict, Any, Optional, List, Callable, Union
-from datetime import datetime, timedelta
+from typing import Dict, Any, Optional, Callable
 from dataclasses import dataclass, field
 from enum import Enum
-import json
 import queue
-from concurrent.futures import ThreadPoolExecutor, Future
-import weakref
+from concurrent.futures import ThreadPoolExecutor
 from src.cache_manager import CacheManager
 # Configure logging
 logger = logging.getLogger(__name__)
@@ -227,7 +223,7 @@ class BackgroundDataService:
             self.stats['cache_misses'] += 1
         
         # Submit to executor
-        future = self.executor.submit(self._fetch_data_worker, request)
+        self.executor.submit(self._fetch_data_worker, request)
         
         logger.info(f"Submitted background fetch request {request_id} for {sport} {year}")
         return request_id
@@ -553,13 +549,12 @@ class BackgroundDataService:
             if to_remove:
                 logger.info(f"Cleared {len(to_remove)} old completed requests")
     
-    def shutdown(self, wait: bool = True, timeout: int = 30):
+    def shutdown(self, wait: bool = True):
         """
         Shutdown the background data service.
-        
+
         Args:
             wait: Whether to wait for active requests to complete
-            timeout: Maximum time to wait for shutdown
         """
         logger.info("Shutting down BackgroundDataService...")
         
@@ -570,24 +565,14 @@ class BackgroundDataService:
             for request_id in list(self.active_requests.keys()):
                 self.cancel_request(request_id)
         
-        # Shutdown executor with compatibility for older Python versions
-        try:
-            # Try with timeout parameter (Python 3.9+)
-            self.executor.shutdown(wait=wait, timeout=timeout)
-        except TypeError:
-            # Fallback for older Python versions that don't support timeout
-            if wait and timeout:
-                # For older versions, we can't specify timeout, so just wait
-                self.executor.shutdown(wait=True)
-            else:
-                self.executor.shutdown(wait=wait)
+        self.executor.shutdown(wait=wait)
         
         logger.info("BackgroundDataService shutdown complete")
     
     def __del__(self):
         """Cleanup when service is destroyed."""
         if not self._shutdown:
-            self.shutdown(wait=False, timeout=None)
+            self.shutdown(wait=False)
 
 # Global service instance
 _background_service: Optional[BackgroundDataService] = None

src/backup_manager.py

@@ -410,8 +410,8 @@ def validate_backup(zip_path: Path) -> Tuple[bool, str, Dict[str, Any]]:
             try:
                 manifest_raw = zf.read(MANIFEST_NAME).decode("utf-8")
                 manifest = json.loads(manifest_raw)
-            except (OSError, UnicodeDecodeError, json.JSONDecodeError) as e:
-                return False, f"Invalid manifest.json: {e}", {}
+            except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+                return False, "Invalid manifest.json", {}
 
             if not isinstance(manifest, dict) or "schema_version" not in manifest:
                 return False, "Invalid manifest structure", {}
@@ -456,8 +456,8 @@ def validate_backup(zip_path: Path) -> Tuple[bool, str, Dict[str, Any]]:
             return True, "", result_manifest
     except zipfile.BadZipFile:
         return False, "File is not a valid ZIP archive", {}
-    except OSError as e:
-        return False, f"Could not read backup: {e}", {}
+    except OSError:
+        return False, "Could not read backup", {}
 
 
 # ---------------------------------------------------------------------------

src/base_classes/api_extractors.py

@@ -7,7 +7,7 @@ fields and data structures.
 """
 
 from abc import ABC, abstractmethod
-from typing import Dict, Any, Optional, List
+from typing import Dict, Optional
 import logging
 from datetime import datetime
 import pytz
@@ -21,12 +21,10 @@ class APIDataExtractor(ABC):
     @abstractmethod
     def extract_game_details(self, game_event: Dict) -> Optional[Dict]:
         """Extract common game details from raw API data."""
-        pass
     
     @abstractmethod
     def get_sport_specific_fields(self, game_event: Dict) -> Dict:
         """Extract sport-specific fields (downs, innings, periods, etc.)."""
-        pass
     
     def _extract_common_details(self, game_event: Dict) -> tuple[Dict | None, Dict | None, Dict | None, Dict | None, Dict | None]:
         """Extract common game details that work across all sports."""

src/base_classes/baseball.py

@@ -329,7 +329,6 @@ class Baseball(SportsCore):
             return
         
         series_summary = game.get("series_summary", "")
-        font = self.fonts.get('detail', ImageFont.load_default())
         bbox = draw_overlay.textbbox((0, 0), series_summary, font=self.fonts['time'])
         height = bbox[3] - bbox[1]
         shots_y = (self.display_height - height) // 2

src/base_classes/basketball.py

@@ -1,6 +1,4 @@
 import logging
-import time
-from datetime import datetime, timezone
 from typing import Any, Dict, Optional
 
 from PIL import Image, ImageDraw, ImageFont

src/base_classes/data_sources.py

@@ -6,11 +6,10 @@ to support different APIs and data providers.
 """
 
 from abc import ABC, abstractmethod
-from typing import Dict, Any, Optional, List
+from typing import Dict, List
 import requests
 import logging
-from datetime import datetime, timedelta
-import time
+from datetime import datetime
 
 class DataSource(ABC):
     """Abstract base class for data sources."""
@@ -35,17 +34,14 @@ class DataSource(ABC):
     @abstractmethod
     def fetch_live_games(self, sport: str, league: str) -> List[Dict]:
         """Fetch live games for a sport/league."""
-        pass
     
     @abstractmethod
     def fetch_schedule(self, sport: str, league: str, date_range: tuple) -> List[Dict]:
         """Fetch schedule for a sport/league within date range."""
-        pass
     
     @abstractmethod
     def fetch_standings(self, sport: str, league: str) -> Dict:
         """Fetch standings for a sport/league."""
-        pass
     
     def get_headers(self) -> Dict[str, str]:
         """Get headers for API requests."""
@@ -217,7 +213,7 @@ class MLBAPIDataSource(DataSource):
             response.raise_for_status()
             
             data = response.json()
-            self.logger.debug(f"Fetched standings from MLB API")
+            self.logger.debug("Fetched standings from MLB API")
             return data
             
         except Exception as e:
@@ -296,7 +292,7 @@ class SoccerAPIDataSource(DataSource):
             response.raise_for_status()
             
             data = response.json()
-            self.logger.debug(f"Fetched standings from soccer API")
+            self.logger.debug("Fetched standings from soccer API")
             return data
             
         except Exception as e:

src/base_classes/football.py

@@ -1,10 +1,8 @@
-from typing import Dict, Any, Optional, List
+from typing import Dict, Any, Optional
 from src.display_manager import DisplayManager
 from src.cache_manager import CacheManager
-from datetime import datetime, timezone, timedelta
 import logging
 from PIL import Image, ImageDraw, ImageFont
-import time
 from src.base_classes.data_sources import ESPNDataSource
 from src.base_classes.sports import SportsCore, SportsLive
 

src/base_classes/hockey.py

@@ -1,6 +1,4 @@
 import logging
-import time
-from datetime import datetime, timezone
 from typing import Any, Dict, Optional
 
 from PIL import Image, ImageDraw, ImageFont
@@ -79,8 +77,6 @@ class Hockey(SportsCore):
                 away_shots = round(home_team_saves / home_team_saves_per)
             if away_team_saves_per > 0:
                 home_shots = round(away_team_saves / away_team_saves_per)
-            status_short = status["type"].get("shortDetail", "")
-
             if situation and status["type"]["state"] == "in":
                 # Detect scoring events from status detail
                 # status_detail = status["type"].get("detail", "")

src/base_classes/sports.py

@@ -5,7 +5,7 @@ import time
 from abc import ABC, abstractmethod
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
-from typing import Any, Callable, Dict, List, Optional
+from typing import Any, Dict, List, Optional
 
 import pytz
 import requests
@@ -172,8 +172,8 @@ class SportsCore(ABC):
 
         try:
             fallbacks.append(Path.home() / ".ledmatrix" / "logos" / self.sport_key)
-        except Exception:
-            pass
+        except RuntimeError as e:
+            self.logger.debug("Could not resolve home directory (expected for service users): %s", e)
 
         fallbacks.append(Path(tempfile.gettempdir()) / "ledmatrix_logos" / self.sport_key)
 
@@ -416,7 +416,6 @@ class SportsCore(ABC):
                 league=self.league,
                 event_id=game['id'],
                 update_interval_seconds=update_interval,
-                is_live=is_live
             )
             
             if odds_data:

src/base_odds_manager.py

@@ -11,13 +11,10 @@ Follows LEDMatrix configuration management patterns:
 - Maintainable: Changes to odds logic affect all plugins
 """
 
-import time
 import logging
 import requests
 import json
-from datetime import datetime, timedelta, timezone
 from typing import Dict, Any, Optional, List
-import pytz
 
 
 class BaseOddsManager: