test(harness): keep the visual double's signature tied to production

Moves set_scrolling_state's frame_hold into the test double here, where
DisplayManager gains it, rather than in #534 where it arrived a PR early.
CodeRabbit flagged the #534 version correctly: a double that accepts an
argument production does not lets the call pass every harness run and
raise TypeError on the panel, which is the one failure a safety harness
exists to prevent.

The drift has now gone both ways across two branches -- double behind
production on this branch, double ahead of it on #534 -- so it is pinned
instead of remembered. test_display_double_parity.py compares the two
signatures and fails with the direction of the drift named. It reads the
files with ast rather than importing them, because display_manager
imports rgbmatrix at module scope and this check should hold on a laptop
and in CI as well as on a Pi.

Plugins begin passing frame_hold in ledmatrix-plugins#462, which is why
production and the double both need it before that lands.

Full suite: 3889 passed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014RRtqXDCnvnY6EQwhT5CV9

CHANGELOG.md

@@ -17,81 +17,6 @@ release that ships it.
 accepts both, but the store flags the old spelling as deprecated
 (`store_manager.py`) and only the new one is in `schema/manifest_schema.json`.
 
-## 3.3.0
-
-**The release the sports scoreboards floor on to delete their bundled copies.**
-3.2.0 shipped the unified sports library and made `ledmatrix_min_version`
-enforceable; this ships the last three shared modules and completes the store
-gate, so a scoreboard can now floor here and carry no fallback at all.
-
-New modules a plugin may import via `src.*` and floor on 3.3.0 for:
-
-- `src/common/sports_card.py` — settings, colour, font and date helpers for a
-  scoreboard's `game_renderer.py`. Free functions taking `config`/`fonts`
-  explicitly, so nothing about the caller's class is assumed.
-- `src/common/sports_game_renderer.py` — `SportsGameRendererMixin`: scroll/Vegas
-  card geometry (centre gap, logo slot and cache key, layout offsets, the
-  upcoming-card date and time layout). No `__init__` and no state, so adoption
-  is one line on the class statement.
-- `src/common/sports_shared.py` — `SportsCoreSharedMixin`,
-  `SportsLiveSharedMixin`, `SportsRecentSharedMixin`: the `sports.py` bodies
-  byte-identical in all eight lineage-sharing scoreboards.
-
-All three sit under `src/common/` rather than `src/base_classes/sports/`,
-deliberately: importing that package pulls `core.py` → `DisplayManager` →
-`rgbmatrix`, and these are pure logic. Plugins importing them must not acquire a
-hardware dependency.
-
-Three notes for anyone adopting `sports_shared`:
-
-- `SportsRecentSharedMixin` defines `__init__`. Its bare `super()` binds to the
-  mixin, so it reaches the host only when the mixin is listed **first** in the
-  bases. Reversing that order silently skips the host constructor.
-- Methods that resolve the plugin's `config_schema.json` use `_plugin_dir()`,
-  which walks the MRO rather than reading `__file__` — `__file__` is now
-  `src/common/`. It walks because `SportsCore` is an ABC: a subclass built with
-  `type(name, bases, ns)` reports `__module__` as `"abc"`.
-- `_get_timezone`, `_extract_game_details` and `_fetch_data` are byte-identical
-  across the eight but stay in the plugins. The first binds a per-plugin
-  timezone module whose contents differ; the other two are the abstract stubs
-  that define the sport.
-
-**The store's compatibility gate is now on every registry-managed route.** 3.2.0
-gated `install_plugin`. This release gates the git-pull update path and
-`install_from_url`, so a plugin whose floor the core cannot meet is refused
-after download with no partial directory left behind.
-
-### Fixed
-
-- **ESPN 403s.** `site.api` began rejecting the User-Agent strings this repo
-  sent on 2026-08-04; every shared-data-source scoreboard returned
-  `403 Forbidden`. Requests now send an identifying token with a project URL —
-  browser-style strings and bare custom tokens are both refused.
-- **Low-memory boards becoming unreachable under load** while still answering
-  pings and serving the web UI. Fetched payloads are released after delivery
-  rather than pinned on the completed request for up to an hour, malloc arenas
-  are capped, and log volume and SD writes are reduced. Available memory is now
-  reported in Tools diagnostics.
-- **A failed logo download pinning a team to a grey box**: the placeholder was
-  written under the real logo's filename, so later attempts found a file and
-  reported success without retrying.
-- **A plugin enabled but never loaded is retried** rather than staying absent
-  with `error = null`.
-- `ttl` now controls cache expiry; abandoned cache writes no longer leave temp
-  files; one cache-cleanup thread per directory rather than per manager.
-- Odds are fetched for the games displayed, not the whole schedule window, and a
-  stalled ESPN no longer stalls the whole plugin update.
-- Array-item secrets are no longer wiped or logged.
-- A restored backup matches the device it was taken from.
-- The web UI reports the real error instead of "unknown", rejects non-finite
-  JSON numbers, and stops checkbox groups posting back hidden options.
-
-### Added
-
-- `display.hardware.orientation` for panels mounted upside down.
-- Vegas keeps live content in the ticker rather than being preempted by it.
-- Schemas can label enum dropdown options.
-
 ## 3.2.0
 
 **The first release shipping the unified sports library.** This is the version

docs/SCROLL_PERFORMANCE.md

@@ -0,0 +1,266 @@
+# Scroll Performance
+
+How scrolling is paced on this hardware, what was wrong with it, and how to
+configure a plugin so its marquee is smooth.
+
+Measured on a Raspberry Pi 4 driving a 2×128×64 chain (256×64 logical) at
+`limit_refresh_rate_hz: 100`. Numbers below come from that panel.
+
+| | before | after |
+|---|---|---|
+| scroll frame rate | 44–46 fps | **100 fps, locked** |
+| frames ≥ 45 ms | 14–17% | none observed |
+| dominant frame time | 20 ms | **10 ms** |
+| disk cache write (~1 MB) | 14.8 ms | **5.4 ms** |
+
+---
+
+## The one rule that matters
+
+**Motion is smooth when the strip advances a whole number of pixels per panel
+refresh.**
+
+Advancing one pixel per refresh on a 100 Hz panel gives 100 px/s. Slower crisp
+speeds come from holding each frame for several refreshes -- 50 px/s is one
+pixel every second refresh -- which is covered under *Choosing a speed* below.
+A speed that lands on no such combination has to do one of two bad things:
+
+- **blend** two adjacent columns to render a half-step — on pixel-font text
+  this alternates crisp and smeared frames and reads as shimmer, or as the
+  text jumping a pixel ahead of itself;
+- **repeat** a frame — the strip stands still, then jumps, which reads as
+  judder.
+
+Neither is tunable away. Pick a speed that divides evenly.
+
+`src.common.scroll_config` solves this for you: `configure()` snaps a requested
+speed to the nearest one the panel can actually show in whole pixels, and
+`scripts/scroll_speeds.py` prints the full ladder for your hardware.
+
+## Choosing a speed
+
+The crisp speeds are not a fixed list -- they depend on how fast *your* panel
+refreshes, which depends on its size, `pwm_bits`, `gpio_slowdown` and the Pi
+model. A Pi Zero driving a long chain has a completely different set of good
+speeds from a Pi 4 driving a short one.
+
+```bash
+# what can this panel do? (reads your configured refresh rate)
+python3 scripts/scroll_speeds.py
+
+# what does it ACTUALLY manage, rather than what is configured?
+sudo systemctl stop ledmatrix
+sudo python3 scripts/scroll_speeds.py --measure
+sudo systemctl start ledmatrix
+
+# highlight the closest option to the speed you want
+python3 scripts/scroll_speeds.py --want 45
+
+# try one on the panel
+sudo systemctl stop ledmatrix
+sudo python3 scripts/scroll_speeds.py --demo 50
+sudo systemctl start ledmatrix
+```
+
+Sample ladder for a 100 Hz panel:
+
+```
+  20.0 px/s  (1px every 5 refreshes =  20.0 fps, slightly stepped)
+  25.0 px/s  (1px every 4 refreshes =  25.0 fps, slightly stepped)
+  33.3 px/s  (1px every 3 refreshes =  33.3 fps, smooth)
+  50.0 px/s  (1px every 2 refreshes =  50.0 fps, smooth)
+  66.7 px/s  (2px every 3 refreshes =  33.3 fps, smooth)
+ 100.0 px/s  (1px every 1 refresh  = 100.0 fps, smooth)
+```
+
+### How a slow speed stays crisp
+
+`SwapOnVSync(canvas, framerate_fraction)` holds each frame for N panel
+refreshes. **The panel keeps refreshing at its full rate either way**, so
+holding a frame costs nothing in flicker -- it only changes how often a *new*
+image is presented. That is what allows 50 px/s to be one whole pixel every
+second refresh, instead of half a pixel every refresh (which has no good
+rendering, only a choice between blur and judder).
+
+`scroll_config.configure()` snaps the requested speed to the nearest entry on
+the ladder and reports the hold that speed needs. It does **not** apply the
+hold: the hold belongs to a scroll, not to a plugin's lifetime, and plugins
+share one display manager -- one set at construction is reset the moment any
+other plugin finishes scrolling. Apply it yourself when the scroll starts:
+
+```python
+settings = scroll_config.configure(
+    self.scroll_helper,
+    plugin_config=self.config,
+    global_config=self.global_config,
+    display_manager=self.display_manager,   # supplies the panel refresh rate
+)
+
+# ...then, each time this plugin begins scrolling:
+self.display_manager.set_scrolling_state(True, frame_hold=settings.frame_hold)
+```
+
+Passing `display_manager` only lets `configure` read the true refresh rate from
+`display.hardware`, which a plugin config cannot see. Skipping the
+`set_scrolling_state` call is the mistake that matters: the speed still
+resolves, but the panel keeps presenting a new frame every refresh, so a slow
+snapped speed falls back to fractional pixels. Pass `snap_to_crisp=False` to
+keep an exact requested speed and accept the artefacts.
+
+Speeds slower than about 20 px/s are stepped no matter what, because a 1-pixel
+advance at 20 fps is simply a coarse increment. That is the pixel pitch, not a
+software limit; the only way to move in smaller increments is sub-pixel
+blending, which this display does not tolerate (see above).
+
+## Configuring a plugin
+
+Use the shared resolver rather than reading config keys yourself:
+
+```python
+from src.common import scroll_config
+
+settings = scroll_config.configure(
+    self.scroll_helper,
+    plugin_config=self.config,
+    global_config=self.global_config,
+    refresh_hz=scroll_config.refresh_hz_from_config(self.global_config),
+    plugin_logger=self.logger,
+)
+```
+
+It resolves every config shape in one place, applies the speed, and returns
+what it did. Precedence, highest first:
+
+1. `display_options.scroll_speed` + `scroll_delay` — **the recommended form**
+2. `display.scroll_speed` + `scroll_delay` — deprecated shape
+3. `scroll_speed` + `scroll_delay` at the root — legacy flat
+4. `scroll_pixels_per_second` — deprecated
+5. the global `display` block
+6. the built-in default (100 px/s)
+
+`scroll_speed` is pixels per frame and `scroll_delay` is the frame period in
+seconds, so the pair means `scroll_speed / scroll_delay` px/s. The recommended
+config for a 100 Hz panel:
+
+```json
+"display_options": { "scroll_speed": 1.0, "scroll_delay": 0.01 }
+```
+
+### Why the deprecated key ranks below the explicit pair
+
+Because some plugins give `scroll_pixels_per_second` a **schema default**, and
+schema defaults are merged into plugin config. Ranking it above the pair means
+it is always present and always wins, so the documented settings become
+unreachable. That is a real, shipped bug — see
+[ledmatrix-plugins#408](https://github.com/ChuckBuilds/ledmatrix-plugins/issues/408).
+
+If you are writing a plugin: do not give a deprecated key a schema default.
+
+## What was actually wrong
+
+Four independent faults, each found by measurement.
+
+### 1. The frame loop slept on top of a wait it had already done
+
+`display_controller.py` ran the high-FPS loop as `render → SwapOnVSync (blocks
+to the panel's refresh) → time.sleep(0.008) → plugin ticks`. The sleep was
+unconditional and added to a wait that had already happened. Render work
+measured ~4 ms, so each iteration cost ~12 ms against a 10 ms refresh grid —
+every swap missed a refresh and landed on the next one. The loop settled at
+exactly 50 fps while asking for 125, with no headroom, so ~14% of frames
+slipped a further refresh.
+
+Now the loop sleeps only the remainder of the frame budget, with a 1 ms floor
+so plugin threads still get the GIL.
+
+### 2. `SwapOnVSync` held the GIL while blocking
+
+The rgbmatrix binding declares it without `nogil` (unlike `SetPixel`, `Clear`
+and `Fill` immediately above it in `cppinc.pxd`), so the render thread held the
+GIL for the entire vsync wait — most of every frame. Background threads were
+starved into long uninterruptible bursts; a 1.5 MB API response costs ~17 ms to
+parse and ~18 ms to re-encode for the cache, and `json.raw_decode` cannot be
+preempted mid-document. Those bursts are what the render loop then waited on.
+
+Fixed by rebuilding the binding: `scripts/build_rgbmatrix_nogil.sh`.
+
+### 3. Sub-pixel blending was wrong for this display
+
+Enabling it made things worse, not better — see the rule at the top. It is off
+by default and only Vegas mode opts in via `set_sub_pixel_scrolling(True)`.
+
+### 4. Frame-based stepping raced the vsync clock
+
+Frame-based mode gated motion on a wall clock at `1/scroll_delay` steps per
+second. Plugins set `scroll_delay` to the frame period, which puts that
+comparison exactly on its own threshold: a frame arriving a hair early moved
+zero pixels and rendered an identical frame, which dirty-tracking skipped, so
+it returned in ~2 ms and the beat repeated. No `scroll_delay` value tunes this
+out — a shorter delay just trades stalled frames for periodic double-steps.
+
+`ScrollHelper` now accumulates elapsed time in both modes at the same
+configured speed, so position stays proportional to real time.
+
+## Diagnosing a juddery scroller
+
+**`Avg FPS` will lie to you.** It is a 100-frame moving average, and a 2 ms
+duplicate frame plus a 21 ms double-wait average to exactly 10 ms. A ticker
+that is stalling on half its frames still reports a healthy `100.0`.
+
+Look at the **distribution** instead:
+
+```bash
+journalctl -u ledmatrix --since "-10min" --no-pager \
+  | grep -oE "Frame time: [0-9.]+ms" | awk '{print $3}' | sed 's/ms//' \
+  | awk '{printf "%.0f\n", $1}' | sort -n | uniq -c
+```
+
+Reading it, on a 100 Hz panel:
+
+| you see | it means |
+|---|---|
+| everything at 10 ms | healthy |
+| a mode at ~2 ms | **duplicate frames** — the swap was skipped because the image did not change. The scroller is advancing less than one pixel per frame. |
+| a mode at 20/30/50 ms | frames missing refreshes — per-frame work is overrunning, or a background thread is holding the GIL |
+| `Avg FPS` above 100 | duplicates present, unless the scroll cycle has completed and is idling |
+
+Then confirm what the plugin actually loaded — config edits do not always reach
+the running code:
+
+```bash
+journalctl -u ledmatrix --since "-5min" --no-pager | grep -iE "px/s|px/frame"
+```
+
+If a plugin logs its scroll config **twice** with different modes, the second
+line is what is running.
+
+## Rebuilding the binding
+
+```bash
+bash scripts/build_rgbmatrix_nogil.sh              # build into a scratch dir
+sudo bash scripts/build_rgbmatrix_nogil.sh --install
+sudo bash scripts/build_rgbmatrix_nogil.sh --rollback
+```
+
+The build never touches the installed module. `--install` backs up the original
+to `~/rgbmatrix-core.so.ORIGINAL` first, and rolls back automatically if the
+service does not come back healthy. Requires `build-essential`; Cython is
+installed into a cached venv under `~/.cache/ledmatrix-cython`.
+
+Re-run it after upgrading `rpi-rgb-led-matrix`, since a library upgrade
+replaces the patched binding.
+
+## Faster JSON
+
+`src/cache/disk_cache.py` uses `orjson` when it is importable and falls back to
+the stdlib otherwise, so it is optional:
+
+```bash
+sudo pip3 install --break-system-packages orjson
+```
+
+Encoding is where it pays — about 7× on this hardware. Decoding gains far less
+(~1.3× on large payloads) because the cost there is building Python objects,
+not scanning text. That is also why moving parsing to a subprocess does not
+help: `pickle.loads` of the same payload costs 8.1 ms against `json.loads` at
+10.9 ms, so the work just moves rather than disappearing.

docs/SPORTS_UNIFICATION.md

@@ -27,7 +27,7 @@ These are independent concerns. Conflating them is what produces god classes.
 | Plugin loads on a core that predates a module | Guarded import with a bundled fallback (`try: from src.X import Y / except ModuleNotFoundError: from y import Y`) |
 | Plugin loads on a core that predates a *method* | Capability probing — `hasattr(SportsCore, "_detect_stale_games")` — never a version comparison. The loader's compat check is advisory-only (it logs and continues), so probing is the real protection. |
 | Core changes never break a plugin's rendering | The **view-model contract**: `_extract_game_details_common` returns a dict whose `GUARANTEED_KEYS` are frozen by `test/test_skin_system.py::TestViewModelContract`. Keys may be added, never renamed or removed. |
-| A plugin can drop its bundled copy safely | The **sunset rule**: its manifest must floor `ledmatrix_min_version` at the first core release shipping the module (recorded in `CHANGELOG.md`) — *necessary but not sufficient*. The store enforces that floor on every registry-managed install and on both supported update paths (sideloading via `install_from_url` is not gated), but a floor cannot reach a user who never updates, so the copy also waits for the B6 gate below. |
+| A plugin can drop its bundled copy safely | The **sunset rule**: its manifest must floor `ledmatrix_min_version` at the first core release shipping the module (recorded in `CHANGELOG.md`) — *necessary but not sufficient*. Nothing enforces that floor today, so the copy also waits for the B6 gate below. |
 
 The core API is **additive-only**. A method the plugins call is never removed or
 given a new required parameter; new behavior arrives as new methods with
@@ -204,7 +204,7 @@ legacy compatibility rather than the mechanism.
 B0–B3 are merged and shipping in core 3.2.0. Everything that remains is
 **rollout**, and it splits into three phases with very different risk profiles.
 The original plan folded the last two together; they are separated here because
-one of them cannot break a user on an old core and the other can.
+one of them is safe by construction and the other is not.
 
 | Phase | Scope | Status | Gate |
 |---|---|---|---|
@@ -212,9 +212,9 @@ one of them cannot break a user on an old core and the other can.
 | **B1** | Promote the nine universal methods; convert `sports.py` → package | ✅ | Characterization suite green; no behavior change intended |
 | **B2** | `CelebrationMixin` + rotation strategies as opt-in capabilities | ✅ | Non-adopters have zero new code in their MRO; strategies checked against verbatim plugin transcriptions |
 | **B3** | Upstream the scroll **orchestration** layer as `src/common/sports_scroll.py`, reading `global_config['target_fps']` natively | ✅ | Content building stays per-sport |
-| **B4** | Ship 3.2.0 *and* make version reporting trustworthy | ✅ | Released 2026-08-03; tag, release and `src.__version__` agree; compatibility gate merged (#428, #431, #433) |
+| **B4** | Ship 3.2.0 *and* make version reporting trustworthy | ⏳ **next** | Tag, release, and `src.__version__` agree; compatibility gate merged |
-| **B5** | Adoption — guarded core imports, all eight. **Bundled copies stay.** | ✅ | All eight adopted; harness byte-identical; see the B5 retrospective below — four shipped broken and were repaired in plugins #251 |
+| **B5** | Adoption — guarded core imports: three pilots, then the remaining six. **Bundled copies stay.** | after B4 | Per plugin: harness + goldens byte-identical, then a device soak |
-| **B6** | Sunset — delete the bundled copies | ✅ | Ran 2026-09-01, all eight. Floors at 3.2.0; the store refuses on all three routes in (#431/#433, #508, #510). See "B6 — what actually happened" |
+| **B6** | Sunset — delete the bundled copies | **blocked** | B4's gate shipped *and* in users' hands (see below) |
 
 ### B4 — what "ship 3.2.0" actually requires
 
@@ -234,20 +234,6 @@ a floor can be trusted against, and today it is not:
   compares the plugin's manifest version against the registry's
   `latest_version` and nothing else.
 
-  *Fixed, in two parts.* `install_plugin` gained the gate in #431/#433, which
-  covers every registry-managed install and, through `_reinstall_with_rollback`,
-  the update path that re-downloads.
-  `update_plugin`'s git branch pulls in place and re-downloads nothing, so it
-  stayed ungated until `_gate_pulled_commit` closed it — checked after the pull
-  (the registry carries no floor field, so the incoming floor is unknowable
-  before it) and undone with `git reset --hard` to the pre-pull commit. That
-  route is rare in practice, since monorepo plugins install as archives; it was
-  closed because the sunset rule in the plugins repo's
-  `08-shared-sports-code.md` states as **condition 3** that the core enforces
-  the floor "at install/update time", and B6 rests on that being true rather
-  than merely written down. `install_from_url` — sideloading a plugin from a
-  URL — is still ungated.
-
 So B4 is: tag and release 3.2.0; make the tag, the release, and `__version__`
 agree, and keep them agreeing; reconsider the `< 2.0.0` skip; migrate manifests
 from `ledmatrix_min` to `ledmatrix_min_version`; and add the install/update
@@ -276,21 +262,13 @@ default is the more restrictive.
 `compatible_versions`. No manifest still carries it, so there is nothing to
 migrate there.)
 
-### B5 — the *fallback* is safe by construction; the modern path is not
+### B5 — adoption is safe by construction
-
-The heading matters, because the unqualified version of this claim is false and
-this document proves it two sections down: four of the eight adopted plugins
-shipped with scroll mode broken on a 3.2.0 core. What is safe by construction is
-narrower than "adoption".
 
 A plugin adopting core imports keeps its bundled copy and reaches it through the
-guarded import (see the Upgradability table above). On a core that doesn't ship
+guarded import (see the Upgradability table above). On a core that ships the
-the module the plugin falls back and behaves exactly as it does today. That
+module the plugin uses core code; on one that doesn't it falls back and behaves
-fallback compatibility — and only that — is safe by construction. On a core that
+exactly as it does today. There is no version of this step that breaks a user,
-*does* ship the module, correctness is not automatic — object-level and scroll-mode validation
+which is why it does not wait for B6's gate.
-(building both classes and comparing, per the retrospective below) is required
-to prove full behavior. There is no version of this step that breaks a user *on
-an old core*, which is why it does not wait for B6's gate.
 
 The hockey scroll-display pilot is **already validated**: adopted against a core
 carrying 3.2.0, `scroll_display.py` went from 691 to 289 lines and all 16 harness
@@ -319,8 +297,7 @@ been in users' hands long enough that the population running a core without it
 is small.** The bundled copies cost disk space; deleting them early costs
 scoreboards, silently. That trade is not close.
 
-Before the first sunset, add a **compatibility regression test**. **Built:**
+Before the first sunset, add a **compatibility regression test**. It has to
-core `test/test_sports_sunset_matrix.py` (#505). It has to
 cover four cases, not one — B5's safety claim and B6's failure mode are
 different propositions and only the second is obvious:
 
@@ -344,144 +321,35 @@ gate rather than trusting the failure to be noticed.
 The same suite should exercise the install/update gate, since it is the other
 half of the guarantee.
 
-### B6 — what actually happened
-
-**Ran 2026-09-01, across all eight scoreboards.** Held from 2026-08-05 to
-2026-09-01 on the argument below, which is kept because the reasoning applies to
-the next module, not because it is still in force.
-
-**The hold, and why it lifted.** The stated gate was evidence of 3.2.0 uptake —
-"a few months of it being the default download, or store-side install data".
-That evidence never arrived and could not: the core updates by
-`git pull --rebase`, so release-asset counts cannot measure uptake, and no
-store-side telemetry exists. What changed instead is that the *risk* the gate
-protected against was closed directly. The store now refuses a plugin whose
-floor exceeds the running core on **all three** routes in:
-
-| route | gated by |
-|---|---|
-| `install_plugin` — every path that re-downloads, `_reinstall_with_rollback` included | #431, #433 |
-| `update_plugin`'s git branch — pulls in place, re-downloads nothing | #508 |
-| `install_from_url` — sideloading | #510 |
-
-With all three closed a pre-3.2.0 user cannot receive a sunset plugin at all;
-they keep the version they already run. The population the hold existed to
-protect is protected by refusal rather than by a bundled copy — which is what
-the copy was standing in for.
-
-**What shipped.** Eight plugins, ~5,800 lines of frozen fallback deleted. Each:
-copy removed, guarded import collapsed to a plain one, floor raised to 3.2.0,
-`test_core_fallback.py` rewritten as `test_core_scroll.py` asserting the sunset
-rather than the fallback. `scripts/check_scroll_adoption.py` gained
-`sunset_violations` and a `SUNSET_PLUGINS` set naming all eight, so a
-resurrected copy or a returned guard fails CI.
-
-Delivered as plugins #346 (hockey, later folded into #351), #349 (football),
-#350 (baseball), #351 (the remaining six).
-
-**Two things found by doing it, both worth carrying forward:**
-
-- **Only one fallback held orchestration logic the core lacked.** baseball's
-  `_configure_scroll_helper` reinterpreted `scroll_speed` as pixels-per-*frame*
-  when `speed × delay` fell outside the 0.1–5.0 window — measured, 10–20×
-  faster than configured for a speed between 1.0 and 5.0. Standardised onto the
-  core's behaviour (honour the documented px/sec, clamp) rather than preserved.
-  Every other difference across the eight was a docstring, an unreachable
-  `scroll_helper is None` guard, or an equivalent diagnostic.
-- **Two tests had been leaning on the guard without anyone knowing.**
-  `soccer/test_live_screens.py` stubbed `src` in a way that shadowed the core,
-  so its guarded import fell back and the test had been exercising the *frozen
-  copy* rather than the shipping class since B5. Before sunsetting anything else
-  that carries a guarded core import, grep for tests that stub `src`.
-
-**The floor-raising traps still apply** to any future sunset: four plugins
-declare their floor top-level, where editing `versions[0]` is a silent no-op,
-and the floor has three live spellings (`min_ledmatrix_version`,
-`requires.min_ledmatrix_version`, `versions[].ledmatrix_min_version`, plus
-deprecated `ledmatrix_min`). See
-`src/plugin_system/compatibility.py:declared_min_version` for the resolution
-order any floor-raising tool must reproduce — and note the name is **inverted**
-between the top level and `versions[]`.
-
-**Still not adopted, deliberately:** `data_sources.py`, `game_renderer.py` and
-`base_odds_manager.py`. The standing decision held them until B6 closed; it now
-has, so they can be reconsidered — with B5's lesson applied, which is to build
-the object and diff rendered output rather than trust a static check.
-
-### B5 retrospective — what the adoption actually cost
-
-Recorded because it is the evidence behind the two decisions above, and because
-"the adoption went fine" is not what happened.
-
-**Four of the eight shipped with scroll mode broken** on a 3.2.0 core, and were
-repaired in plugins-repo #251. The restructure lifted the content methods
-verbatim but left the state they read off `self` behind: separator-icon
-constants (hockey, basketball, lacrosse) and the game-renderer cache (afl).
-hockey/basketball/lacrosse could not construct the scroll display at all; afl
-raised inside `prepare_scroll_content`, which the core base *catches*, so its
-only symptom was scroll mode silently drawing nothing.
-
-Three things are worth carrying forward:
-
-- **The bundled fallback did not protect anyone from this.** The break was on
-  the modern path, which the fallback never touches. Carrying the second copy
-  bought nothing against the actual defect while creating the divergence that
-  produced it. That is an argument *for* B6, not against it.
-- **Every gate was green.** The safety harness renders the scoreboard screens,
-  not scroll mode; `test_core_fallback.py` checked that methods existed and that
-  their *globals* resolved, and `self.NHL_SEPARATOR_ICON` is an attribute read,
-  invisible to an AST scan for `Name` loads. The fix was to stop reasoning about
-  source and **build the object**: construct both classes on both paths, compare
-  the separator icons they end up with, and assert the adopted class ends up
-  with every instance attribute the bundled one sets.
-- **Test what the change touches, not what is convenient to render.** Scroll
-  mode had no coverage because the harness could not reach it. A comparison
-  harness that renders the same games through both paths and diffs the pixels
-  needs no per-sport knowledge of the right answer, only that adopting core code
-  did not change it.
-
-**The ledger.** Before adoption, eight duplicated copies totalled 5,685 lines.
-After adoption plus the frozen legacy copies it was 10,610; removing the dead
-inline duplication (plugins #252) brought it to roughly 8,620. B6 would take it
-to about 3,300 including the shared core module — some 2,400 fewer than before
-this project started. **Until B6 runs, the adoption is net negative on disk**,
-and its one delivered user-visible gain is that adopted plugins honour the
-global `target_fps` instead of hardcoding ~100 FPS.
-
-### Decision: stop adopting further modules until B6 closes
-
-`data_sources.py` (9 copies), `game_renderer.py` (8) and `base_odds_manager.py`
-are the obvious next candidates. **Do not adopt them yet.** Each adoption adds
-carrying cost — a second copy to keep in step — against a payoff that is
-contingent on B6, and B6 is gated on an installed base we cannot currently
-measure. Consolidate what is already committed; revisit when B6 does.
-
 ## What's next
 
-Steps 1–5 of the original plan are **done**: 3.2.0 is tagged and published with
+In order. Each step is independently useful and independently revertible.
-a version number CI now asserts (#428), the compatibility gate is in
-`install_plugin` and reads `compatible_versions` as well as the floor
-(#431, #433), the newest manifest entry is required to use `ledmatrix_min_version`
-(plugins #244), and all eight plugins have adopted the scroll orchestration
-(plugins #245–#249, repaired in #251, tidied in #252).
 
-What actually remains, smallest first:
+1. **Tag and publish v3.2.0.** The code is already on `main` (`21825cbf`).
-
+   Nothing else blocks this, and it is what makes `ledmatrix_min_version:
-1. **Soak the adoptions on hardware.** football and hockey have been run on a
+   "3.2.0"` refer to something real.
-   live rig through real games; baseball was watched through one earlier. The
+2. **Make the version number honest.** Have the release process assert that the
-   rest are proven by harness, unit tests and pixel comparison. Out-of-season
+   tag, the GitHub release, and `src.__version__` agree — a check in CI is
-   sports cannot be soaked until their season starts. When you do, **check the
+   cheaper than the confusion of the last two releases. Then revisit the
-   rig's `*_display_mode` first** — a board in `switch` mode will happily load a
+   `< 2.0.0` skip in `_warn_if_incompatible`, which currently silences the
-   sunset plugin and tell you nothing about the scroll code the sunset changed.
+   warning for the users who most need it.
-2. **Cut 3.3.0.** Not required by B6 — its floors are 3.2.0, which is released —
+3. **Add the compatibility gate** to `StoreManager.install_plugin` and
-   but `calendar` 1.2.3 floors at 3.3.0 for the device-authorization endpoints
+   `.update_plugin`: refuse a plugin whose declared floor exceeds
-   that landed after 3.2.0, so it is un-installable until the release exists.
+   `src.__version__`, and surface the reason in the store UI rather than only
-3. **Reconsider the held modules** (`data_sources.py`, `game_renderer.py`,
+   the log. This is the single change that turns the floor from documentation
-   `base_odds_manager.py`) now that the sunset has closed. `game_renderer.py` is
+   into a guarantee, and B6 depends on it.
-   the largest single duplication left: ~11,500 lines across eight plugins, with
+4. **Migrate the manifests** to `ledmatrix_min_version`, and reconcile them with
-   ~36,500 more in the eight `sports.py`. Note that core already ships
+   `compatible_versions` (see above — that field is the required, canonical one,
-   `src/base_classes/sports/` (~143KB, promoted in B1/B2) that **no plugin
+   and the gate does not read it yet). Currently 28 plugins spell the floor both
-   imports** — check whether it has drifted before treating it as the target.
+   ways across their `versions[]` entries, 12 use only the old spelling, and 2
+   only the new. Scope the sweep to the nine sports plugins if a 42-plugin
+   version-bump wave isn't worth it — but the `compatible_versions` half has to
+   cover every manifest the gate can refuse, or define explicit legacy handling,
+   before the gate is allowed to block anything.
+5. **Run B5 adoption** — hockey, soccer, football, then the remaining six.
+   Bundled copies stay. Byte-identical harness output per plugin, then a soak.
+6. **Only then plan B6**, with the compatibility regression test described above
+   in CI first.
 
 ## How to keep this project healthy
 

first_time_install.sh

@@ -1740,15 +1740,12 @@ journald_effective() {
        systemd-analyze cat-config systemd/journald.conf >/dev/null 2>&1; then
         systemd-analyze cat-config systemd/journald.conf 2>/dev/null
     else
-        cat /etc/systemd/journald.conf /etc/systemd/journald.conf.d/*.conf 2>/dev/null || true
+        cat /etc/systemd/journald.conf /etc/systemd/journald.conf.d/*.conf 2>/dev/null
     fi
 }
 journald_conf="$(journald_effective)"
-# Both settings are optional, and stock images ship them commented out. grep
+journald_storage="$(printf '%s\n' "$journald_conf" | grep -E '^[[:space:]]*Storage=' | tail -n1 | cut -d= -f2 | tr -d '[:space:]')"
-# exits 1 on no match, which pipefail turns fatal under set -e — an absent
+journald_cap="$(printf '%s\n' "$journald_conf" | grep -E '^[[:space:]]*SystemMaxUse=' | tail -n1 | cut -d= -f2 | tr -d '[:space:]')"
-# setting must read as empty, not abort the install.
-journald_storage="$(printf '%s\n' "$journald_conf" | grep -E '^[[:space:]]*Storage=' | tail -n1 | cut -d= -f2 | tr -d '[:space:]' || true)"
-journald_cap="$(printf '%s\n' "$journald_conf" | grep -E '^[[:space:]]*SystemMaxUse=' | tail -n1 | cut -d= -f2 | tr -d '[:space:]' || true)"
 
 if [ "$journald_storage" = "persistent" ] && [ -n "$journald_cap" ]; then
     echo "Persistent journald storage already configured (SystemMaxUse=$journald_cap)"
@@ -1774,7 +1771,7 @@ else
     # after ledmatrix-persistent.conf (zz-local.conf and friends) still wins.
     # Writing the file is not evidence it took effect -- re-read and say so
     # plainly rather than reporting success we cannot confirm.
-    journald_now="$(journald_effective | grep -E '^[[:space:]]*Storage=' | tail -n1 | cut -d= -f2 | tr -d '[:space:]' || true)"
+    journald_now="$(journald_effective | grep -E '^[[:space:]]*Storage=' | tail -n1 | cut -d= -f2 | tr -d '[:space:]')"
     if [ "$journald_now" = "persistent" ]; then
         echo "  Persistent journald storage active"
     else

requirements.txt

@@ -55,6 +55,18 @@ packaging>=23.0,<27.0
 #                     range as a hard dependency — keep the two in sync.
 #   pip install 'psutil>=6.0.0,<7.0.0'
 #
+# orjson            — faster JSON for the disk cache
+#                     (src/cache/disk_cache.py). Encoding a ~1MB cache
+#                     record drops from ~12ms to ~1.6ms on a Pi 4, which
+#                     matters because that work holds the GIL and stalls
+#                     the render thread mid-scroll. Falls back to the
+#                     stdlib json when missing — see docs/SCROLL_PERFORMANCE.md.
+#                     The 3.11.6 floor is CVE-2025-67221: orjson.dumps did not
+#                     limit recursion on deeply nested documents, and the disk
+#                     cache encodes payloads parsed straight from third-party
+#                     APIs. 3.11.6 covers the Python range above.
+#   pip install 'orjson>=3.11.6,<4.0'
+#
 # Flask-Limiter     — request rate limiting in web_interface/app.py
 #                     (accidental-abuse protection, not security). The
 #                     web interface starts without rate limiting when

scripts/build_rgbmatrix_nogil.sh

@@ -0,0 +1,330 @@
+#!/usr/bin/env bash
+#
+# Rebuild the rgbmatrix Python binding so it releases the GIL.
+#
+# WHY THIS EXISTS
+# ---------------
+# The upstream binding declares FrameCanvas::SwapOnVSync WITHOUT `nogil`
+# (cppinc.pxd), unlike SetPixel/Clear/Fill on the lines just above it.
+# SwapOnVSync blocks until the panel's next vertical sync -- up to a full
+# refresh period on every frame -- so the render thread was holding the GIL
+# for most of every frame. Background threads (API fetches, JSON parsing,
+# image decode) were starved into long uninterruptible bursts, which in turn
+# made the render loop miss refreshes.
+#
+# Measured on a Pi 4 driving a 2x128x64 chain at limit_refresh_rate_hz=100:
+#
+#     before   ~44 fps average, 14-17% of frames 41-53ms
+#     after    100 fps, median 10.00ms, p95 10.05ms, 0% stalls
+#
+# The per-pixel blit (SetPixelsPillow) can also release the GIL and walk the
+# Pillow buffer row-major, but that is OFF by default and you almost certainly
+# want to leave it that way. Row-major changes what a partially-written frame
+# looks like: column-major tearing shows as a vertical seam, row-major tearing
+# shows as a horizontal split between the panel's upper and lower halves. On a
+# 1/32 scan panel that reads as a one-pixel "fold" across the middle of every
+# panel -- reported on hardware, and it went away when the blit was reverted.
+# Enable with RGB_PATCH_BLIT=1 only if you have measured that you need it;
+# essentially all of the gain above comes from the SwapOnVSync change alone.
+#
+# SAFETY
+# ------
+# Builds into a scratch directory; touches the installed module only in the
+# --install step, and backs up the original first. Roll back at any time with:
+#
+#     sudo bash scripts/build_rgbmatrix_nogil.sh --rollback
+#
+# USAGE
+#     bash scripts/build_rgbmatrix_nogil.sh              # build only
+#     sudo bash scripts/build_rgbmatrix_nogil.sh --install
+#     sudo bash scripts/build_rgbmatrix_nogil.sh --rollback
+#
+set -uo pipefail
+
+# Resolve the invoking user's home, not root's. --install runs under sudo,
+# where $HOME is /root, so every default path below pointed somewhere the
+# build had never written and the install died with "no built module found".
+if [ -n "${SUDO_USER:-}" ]; then
+    OWNER_HOME="$(getent passwd "$SUDO_USER" | cut -d: -f6)"
+fi
+OWNER_HOME="${OWNER_HOME:-$HOME}"
+
+SRC_TREE="${RGB_SRC_TREE:-$OWNER_HOME/LEDMatrix/rpi-rgb-led-matrix-master}"
+BUILD_DIR="${RGB_BUILD_DIR:-$OWNER_HOME/rgbmatrix-nogil-build}"
+VENV="${RGB_CYTHON_VENV:-$OWNER_HOME/.cache/ledmatrix-cython}"
+BACKUP="${RGB_BACKUP:-$OWNER_HOME/rgbmatrix-core.so.ORIGINAL}"
+PATCH_BLIT="${RGB_PATCH_BLIT:-0}"
+
+die() { echo "FATAL: $*" >&2; exit 1; }
+
+# This script runs under `set -uo pipefail` -- no -e -- so an unchecked
+# systemctl failure is silently ignored. That matters most for `stop`: leaving
+# the old service running means cp overwrites a module the running process has
+# mapped, the following `start` succeeds as a no-op, and the health check sees
+# an active unit and reports SUCCESS for a binding that was never loaded.
+# A machine with no ledmatrix.service at all is a normal build host, so that
+# case is skipped rather than treated as a failure.
+service_present() { systemctl cat ledmatrix.service >/dev/null 2>&1; }
+
+service_do() {
+    local verb="$1"
+    if ! service_present; then
+        echo "   (no ledmatrix.service installed - skipping $verb)"
+        return 0
+    fi
+    systemctl "$verb" ledmatrix || die "systemctl $verb ledmatrix failed"
+}
+
+py_site() {
+    python3 -c 'import rgbmatrix, os; print(os.path.dirname(rgbmatrix.__file__))' 2>/dev/null
+}
+
+# The extension filename the interpreter that builds -- and then loads -- this
+# module actually uses, e.g. core.cpython-313-aarch64-linux-gnu.so. The build
+# venv is made with --system-site-packages from python3, so the two agree;
+# falling back keeps --install working when the venv has been cleaned up.
+abi_name() {
+    local py="$VENV/bin/python"
+    [ -x "$py" ] || py=python3
+    "$py" -c \
+        'import sysconfig; print("core" + sysconfig.get_config_var("EXT_SUFFIX"))' \
+        2>/dev/null
+}
+
+# Exactly the current interpreter's artifact, never merely the first one that
+# sorts. Staging copies $SRC_TREE wholesale, so a core.cpython-*.so left in the
+# source tree by an earlier build comes along for the ride; build_ext --inplace
+# only ever overwrites the current ABI's name, and a glob piped to `head -1`
+# sorts cpython-311 ahead of cpython-313. That installed a stale, unpatched
+# module as core.so while the GIL check below -- which reads the freshly
+# generated core.cpp, not the .so -- still reported success.
+abi_so() {
+    local name path
+    name="$(abi_name)" || return 1
+    [ -n "$name" ] || return 1
+    path="$BUILD_DIR/bindings/python/rgbmatrix/$name"
+    [ -f "$path" ] || return 1
+    printf '%s\n' "$path"
+}
+
+do_rollback() {
+    local dst; dst="$(py_site)"
+    [ -n "$dst" ] || die "could not locate the installed rgbmatrix package"
+    [ -f "$BACKUP" ] || die "no backup at $BACKUP"
+    service_do stop
+    cp -a "$BACKUP" "$dst/core.so" || die "restore failed"
+    find "$dst" -name __pycache__ -type d -exec rm -rf {} + 2>/dev/null
+    service_do start
+    echo "rolled back to the original core.so"
+    exit 0
+}
+
+do_install() {
+    local so dst
+    so="$(abi_so)"; [ -n "$so" ] || die "no built module found - run the build first"
+    dst="$(py_site)"; [ -n "$dst" ] || die "could not locate the installed rgbmatrix package"
+
+    if [ ! -f "$BACKUP" ]; then
+        cp -a "$dst/core.so" "$BACKUP" || die "could not back up the original"
+        echo "backed up original core.so -> $BACKUP"
+    else
+        echo "backup already present at $BACKUP (keeping the true original)"
+    fi
+
+    service_do stop
+    cp "$so" "$dst/core.so" || die "install failed"
+    find "$dst" -name __pycache__ -type d -exec rm -rf {} + 2>/dev/null
+    service_do start
+
+    echo "waiting 25s for the display to come back..."
+    sleep 25
+    local healthy=1
+    systemctl is-active --quiet ledmatrix || healthy=0
+    if journalctl -u ledmatrix --since "40 sec ago" --no-pager \
+         | grep -qiE "Traceback|ImportError|Segmentation fault|undefined symbol"; then
+        healthy=0
+    fi
+    if [ "$healthy" = "1" ]; then
+        echo "SUCCESS - running on the rebuilt binding"
+    else
+        echo "UNHEALTHY - rolling back"
+        cp -a "$BACKUP" "$dst/core.so" \
+            || echo "ROLLBACK FAILED: could not restore $BACKUP -> $dst/core.so" >&2
+        if service_present && ! systemctl restart ledmatrix; then
+            echo "ROLLBACK FAILED: ledmatrix did not restart - the display is" \
+                 "down; restore manually with 'sudo bash $0 --rollback'" >&2
+        fi
+        journalctl -u ledmatrix --since "90 sec ago" --no-pager | tail -25
+        exit 1
+    fi
+    exit 0
+}
+
+case "${1:-}" in
+    --rollback) do_rollback ;;
+    --install)  do_install ;;
+    "" )        ;;
+    *)          die "unknown option: $1" ;;
+esac
+
+# ---------------------------------------------------------------- build ----
+[ -d "$SRC_TREE" ] || die "matrix source tree not found at $SRC_TREE (set RGB_SRC_TREE)"
+command -v g++ >/dev/null || die "g++ not installed (apt install build-essential)"
+
+echo "==> staging a scratch copy at $BUILD_DIR"
+rm -rf "$BUILD_DIR"
+cp -r "$SRC_TREE" "$BUILD_DIR" || die "copy failed"
+
+# Drop any extension artifacts that came across from the source tree. Nothing
+# downstream should be able to pick one up, and build_ext --inplace can decide
+# a copied .so is already up to date and skip the compile entirely.
+find "$BUILD_DIR/bindings/python/rgbmatrix" -maxdepth 1 \
+     -name 'core*.so' -delete 2>/dev/null
+
+echo "==> patching the bindings to release the GIL"
+python3 - "$BUILD_DIR" "$PATCH_BLIT" <<'PYEOF' || die "patch failed"
+import io
+import sys
+
+base = sys.argv[1] + "/bindings/python/rgbmatrix/"
+patch_blit = len(sys.argv) > 2 and sys.argv[2] == "1"
+
+# --- declare SwapOnVSync as nogil ---------------------------------------
+p = base + "cppinc.pxd"
+s = io.open(p, encoding="utf-8").read()
+OLD_DECL = "        FrameCanvas *SwapOnVSync(FrameCanvas*, uint8_t)\n"
+NEW_DECL = "        FrameCanvas *SwapOnVSync(FrameCanvas*, uint8_t) nogil\n"
+if OLD_DECL in s:
+    io.open(p, "w", encoding="utf-8", newline="\n").write(s.replace(OLD_DECL, NEW_DECL, 1))
+    print("   cppinc.pxd: SwapOnVSync declared nogil")
+elif NEW_DECL in s:
+    print("   cppinc.pxd: already nogil")
+else:
+    sys.exit("could not find the SwapOnVSync declaration")
+
+# --- release the GIL across the vsync wait ------------------------------
+p = base + "core.pyx"
+s = io.open(p, encoding="utf-8").read()
+
+OLD_SWAP = (
+    "    def SwapOnVSync(self, FrameCanvas newFrame, uint8_t framerate_fraction = 1):\n"
+    "        return __createFrameCanvas("
+    "self.__matrix.SwapOnVSync(newFrame.__canvas, framerate_fraction))\n"
+)
+NEW_SWAP = (
+    "    def SwapOnVSync(self, FrameCanvas newFrame, uint8_t framerate_fraction = 1):\n"
+    "        # Blocks until the panel's next vertical sync. Holding the GIL\n"
+    "        # across that wait starves every other Python thread for most of\n"
+    "        # each frame. Pointers are hoisted into C locals so the blocking\n"
+    "        # call itself needs no Python state.\n"
+    "        cdef cppinc.RGBMatrix* matrix = self.__matrix\n"
+    "        cdef cppinc.FrameCanvas* frame = newFrame.__canvas\n"
+    "        cdef uint8_t fraction = framerate_fraction\n"
+    "        cdef cppinc.FrameCanvas* swapped\n"
+    "        with nogil:\n"
+    "            swapped = matrix.SwapOnVSync(frame, fraction)\n"
+    "        return __createFrameCanvas(swapped)\n"
+)
+if OLD_SWAP in s:
+    s = s.replace(OLD_SWAP, NEW_SWAP, 1)
+    print("   core.pyx: SwapOnVSync releases the GIL")
+elif "swapped = matrix.SwapOnVSync(frame, fraction)" in s:
+    print("   core.pyx: SwapOnVSync already patched")
+else:
+    sys.exit("could not find the SwapOnVSync body")
+
+# --- optional: release the GIL across the blit --------------------------
+OLD_BLIT = (
+    "        buffer = get_pillow_buffer(image_capsule)\n"
+    "\n"
+    "        for col in range(max(0, -xstart), min(width, frame_width - xstart)):\n"
+    "            for row in range(max(0, -ystart), min(height, frame_height - ystart)):\n"
+    "                pixel = buffer[row][col]\n"
+    "                r = (pixel ) & 0xFF\n"
+    "                g = (pixel >> 8) & 0xFF\n"
+    "                b = (pixel >> 16) & 0xFF\n"
+    "                my_canvas.SetPixel(xstart+col, ystart+row, r, g, b)\n"
+)
+NEW_BLIT = (
+    "        buffer = get_pillow_buffer(image_capsule)\n"
+    "\n"
+    "        # Bounds hoisted so the blit needs no Python state and can run\n"
+    "        # without the GIL: it touches only a C buffer and a C++ canvas.\n"
+    "        # NOTE: row-major order makes a torn frame show as a horizontal\n"
+    "        # split across the panel's halves. See the header before enabling.\n"
+    "        cdef int col_start = max(0, -xstart)\n"
+    "        cdef int col_end = min(width, frame_width - xstart)\n"
+    "        cdef int row_start = max(0, -ystart)\n"
+    "        cdef int row_end = min(height, frame_height - ystart)\n"
+    "\n"
+    "        with nogil:\n"
+    "            for row in range(row_start, row_end):\n"
+    "                for col in range(col_start, col_end):\n"
+    "                    pixel = buffer[row][col]\n"
+    "                    r = (pixel ) & 0xFF\n"
+    "                    g = (pixel >> 8) & 0xFF\n"
+    "                    b = (pixel >> 16) & 0xFF\n"
+    "                    my_canvas.SetPixel(xstart+col, ystart+row, r, g, b)\n"
+)
+if patch_blit:
+    if OLD_BLIT in s:
+        s = s.replace(OLD_BLIT, NEW_BLIT, 1)
+        print("   core.pyx: pixel blit releases the GIL, row-major")
+    elif "for row in range(row_start, row_end):" in s:
+        print("   core.pyx: blit already patched")
+    else:
+        sys.exit("could not find the SetPixelsPillow loop")
+else:
+    print("   core.pyx: blit left unpatched (RGB_PATCH_BLIT=1 to enable)")
+
+io.open(p, "w", encoding="utf-8", newline="\n").write(s)
+PYEOF
+
+echo "==> building librgbmatrix.a (this takes a few minutes)"
+nice -n 10 make -C "$BUILD_DIR/lib" -j2 >/dev/null 2>&1 \
+    || die "library build failed - rerun 'make -C $BUILD_DIR/lib' to see why"
+[ -f "$BUILD_DIR/lib/librgbmatrix.a" ] || die "librgbmatrix.a was not produced"
+
+echo "==> preparing Cython"
+[ -d "$VENV" ] || python3 -m venv --system-site-packages "$VENV" || die "venv failed"
+"$VENV/bin/pip" install --quiet cython || die "cython install failed"
+
+cat > "$BUILD_DIR/bindings/python/setup.py" <<'EOF'
+from setuptools import setup, Extension
+from Cython.Build import cythonize
+
+core = Extension(
+    "rgbmatrix.core",
+    sources=["rgbmatrix/core.pyx", "rgbmatrix/shims/pillow.c"],
+    include_dirs=["../../include", "rgbmatrix/shims"],
+    extra_objects=["../../lib/librgbmatrix.a"],
+    language="c++",
+    extra_compile_args=["-O3", "-Wall", "-fno-exceptions", "-std=c++11"],
+    extra_link_args=["-lrt", "-lm", "-lpthread"],
+)
+
+setup(name="rgbmatrix",
+      ext_modules=cythonize([core], language_level="3str",
+                            compiler_directives={"binding": False}))
+EOF
+
+echo "==> compiling the extension"
+( cd "$BUILD_DIR/bindings/python" && "$VENV/bin/python" setup.py build_ext --inplace ) \
+    >/dev/null 2>&1 || die "extension build failed"
+
+SO="$(abi_so)" || true
+[ -n "$SO" ] || die "no .so produced - expected $(abi_name) in $BUILD_DIR/bindings/python/rgbmatrix"
+
+# Verify the GIL really is released before anyone installs this.
+EXPECTED=1; [ "$PATCH_BLIT" = "1" ] && EXPECTED=2
+PAIRS=$(grep -c "PyEval_SaveThread\|Py_UNBLOCK_THREADS" \
+        "$BUILD_DIR/bindings/python/rgbmatrix/core.cpp")
+[ "$PAIRS" -ge "$EXPECTED" ] \
+    || die "generated C++ has $PAIRS GIL-release sites, expected >= $EXPECTED"
+
+echo
+echo "BUILT: $SO"
+echo "       ($PAIRS GIL-release site(s) in the generated C++)"
+echo
+echo "Install with:   sudo bash $0 --install"
+echo "Roll back with: sudo bash $0 --rollback"

scripts/scroll_speeds.py

@@ -0,0 +1,238 @@
+#!/usr/bin/env python3
+"""Show and try the scroll speeds your panel can display cleanly.
+
+Motion looks smooth when the strip advances a WHOLE number of pixels per panel
+refresh. Anything else has to blend two columns (which on pixel-font text reads
+as shimmer) or repeat frames unevenly (which reads as judder). So the speeds
+worth using are not arbitrary -- they are
+
+    refresh_hz / frame_hold * pixels_per_frame
+
+for whole numbers of frame_hold and pixels_per_frame, and that ladder depends
+on how fast YOUR panel actually refreshes. A Pi Zero driving a big chain will
+have a completely different set of good speeds from a Pi 4 driving a small one.
+
+    # what can this panel do? (no hardware needed, uses your configured rate)
+    python3 scripts/scroll_speeds.py
+
+    # measure what the panel ACTUALLY manages, rather than what is configured
+    sudo systemctl stop ledmatrix
+    sudo python3 scripts/scroll_speeds.py --measure
+    sudo systemctl start ledmatrix
+
+    # what would a 60Hz panel offer?
+    python3 scripts/scroll_speeds.py --hz 60
+
+    # try one on the panel
+    sudo systemctl stop ledmatrix
+    sudo python3 scripts/scroll_speeds.py --demo 50
+    sudo systemctl start ledmatrix
+
+This script never starts or stops the display service itself -- that is left to
+you, so a crash here can never leave the panel dark.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from src.common import scroll_config  # noqa: E402
+
+CONFIG = Path(__file__).resolve().parent.parent / "config" / "config.json"
+
+
+def load_hardware():
+    try:
+        with open(CONFIG, encoding="utf-8") as handle:
+            return (json.load(handle).get("display") or {}).get("hardware") or {}
+    except (OSError, ValueError):
+        return {}
+
+
+def build_options(hardware, refresh_override=None):
+    from rgbmatrix import RGBMatrixOptions
+
+    o = RGBMatrixOptions()
+    o.rows = int(hardware.get("rows", 32))
+    o.cols = int(hardware.get("cols", 64))
+    o.chain_length = int(hardware.get("chain_length", 1))
+    o.parallel = int(hardware.get("parallel", 1))
+    o.brightness = int(hardware.get("brightness", 80))
+    o.hardware_mapping = hardware.get("hardware_mapping", "regular")
+    o.pwm_bits = int(hardware.get("pwm_bits", 11))
+    o.pwm_dither_bits = int(hardware.get("pwm_dither_bits", 0))
+    o.pwm_lsb_nanoseconds = int(hardware.get("pwm_lsb_nanoseconds", 130))
+    o.led_rgb_sequence = hardware.get("led_rgb_sequence", "RGB")
+    o.scan_mode = int(hardware.get("scan_mode", 0))
+    o.row_address_type = int(hardware.get("row_address_type", 0))
+    o.multiplexing = int(hardware.get("multiplexing", 0))
+    o.gpio_slowdown = int(hardware.get("gpio_slowdown", 2))
+    o.limit_refresh_rate_hz = (
+        int(refresh_override) if refresh_override is not None
+        else int(hardware.get("limit_refresh_rate_hz", 0))
+    )
+    return o
+
+
+def open_matrix(hardware, refresh_override=None):
+    """Construct the matrix, or explain why it will not open."""
+    if os.geteuid() != 0:
+        sys.exit("this needs root for GPIO access - rerun with sudo")
+    try:
+        from rgbmatrix import RGBMatrix
+    except ImportError:
+        sys.exit("rgbmatrix is not installed on this machine")
+    try:
+        return RGBMatrix(options=build_options(hardware, refresh_override))
+    except Exception as exc:  # pragma: no cover - hardware dependent
+        sys.exit(
+            "could not open the panel ({}).\n"
+            "If the display service is running it owns the GPIO - stop it first:\n"
+            "    sudo systemctl stop ledmatrix".format(exc)
+        )
+
+
+def measure_refresh(hardware, seconds=6.0):
+    """Actual refresh rate, by running uncapped and timing the swaps.
+
+    SwapOnVSync blocks until the panel's next refresh, so an unthrottled loop
+    runs at exactly the panel's rate. This is what an older Pi or a longer
+    chain will really give you, as opposed to whatever limit_refresh_rate_hz
+    optimistically asks for.
+    """
+    matrix = open_matrix(hardware, refresh_override=0)
+    canvas = matrix.CreateFrameCanvas()
+    canvas = matrix.SwapOnVSync(canvas)  # discard the first, it includes setup
+    frames = 0
+    started = time.perf_counter()
+    while time.perf_counter() - started < seconds:
+        canvas = matrix.SwapOnVSync(canvas)
+        frames += 1
+    measured = frames / (time.perf_counter() - started)
+    matrix.Clear()
+    return measured
+
+
+def demo(hardware, target, seconds):
+    """Scroll text at the crisp speed nearest `target`."""
+    from PIL import Image, ImageDraw, ImageFont
+
+    hz = float(hardware.get("limit_refresh_rate_hz") or scroll_config.DEFAULT_REFRESH_HZ)
+    choice = scroll_config.solve_crisp(target, hz)
+    print("asked for {:.0f} px/s -> {}".format(target, choice.describe()))
+
+    matrix = open_matrix(hardware)
+    canvas = matrix.CreateFrameCanvas()
+    W, H = canvas.width, canvas.height
+
+    font = None
+    for path, size in (
+        (str(Path(__file__).resolve().parent.parent / "assets/fonts/PressStart2P-Regular.ttf"), 16),
+        ("/usr/share/fonts/truetype/dejavu/DejaVuSansMono-Bold.ttf", 26),
+    ):
+        try:
+            font = ImageFont.truetype(path, size)
+            break
+        except OSError:
+            continue
+    if font is None:
+        font = ImageFont.load_default()
+
+    text = "  {:.0f} px/s  ***  THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG  ***".format(
+        choice.pixels_per_second)
+    box = ImageDraw.Draw(Image.new("RGB", (8, 8))).textbbox((0, 0), text, font=font)
+    tw, th = box[2] - box[0], box[3] - box[1]
+    reps = max(2, (W * 3) // max(tw, 1) + 1)
+    strip = Image.new("RGB", (tw * reps, H), (0, 0, 0))
+    draw = ImageDraw.Draw(strip)
+    for i in range(reps):
+        draw.text((i * tw, (H - th) // 2 - box[1]), text, font=font, fill=(255, 210, 60))
+
+    offset = 0
+    frames = 0
+    started = time.time()
+    while time.time() - started < seconds:
+        window = strip.crop((offset, 0, offset + W, H))
+        if window.width < W:
+            whole = Image.new("RGB", (W, H), (0, 0, 0))
+            head = strip.crop((offset, 0, strip.width, H))
+            whole.paste(head, (0, 0))
+            whole.paste(strip.crop((0, 0, W - head.width, H)), (head.width, 0))
+            window = whole
+        canvas.SetImage(window)
+        canvas = matrix.SwapOnVSync(canvas, choice.frame_hold)
+        offset = (offset + choice.pixels_per_frame) % strip.width
+        frames += 1
+    elapsed = time.time() - started
+    print("  {} frames in {:.1f}s = {:.1f} fps = {:.1f} px/s actual".format(
+        frames, elapsed, frames / elapsed, frames * choice.pixels_per_frame / elapsed))
+    matrix.Clear()
+
+
+def print_ladder(hz, highlight=None):
+    print("")
+    print("Whole-pixel scroll speeds at {:.1f}Hz refresh".format(hz))
+    print("(the panel refreshes at {:.0f}Hz for every one of these - holding a "
+          "frame costs no flicker)".format(hz))
+    print("")
+    for entry in scroll_config.crisp_ladder(hz):
+        if entry.pixels_per_second > hz * 3:
+            break
+        mark = " <-- nearest to {:.0f}".format(highlight) if (
+            highlight is not None
+            and entry.pixels_per_second == scroll_config.solve_crisp(highlight, hz).pixels_per_second
+        ) else ""
+        print("  " + entry.describe() + mark)
+    print("")
+    print("Set one in config.json as pixels per second, e.g.")
+    print('  "display_options": {{"scroll_pixels_per_second": {:.0f}}}'.format(
+        scroll_config.solve_crisp(highlight if highlight else hz / 2, hz).pixels_per_second))
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--hz", type=float,
+                    help="refresh rate to compute the ladder for (default: your config)")
+    ap.add_argument("--measure", action="store_true",
+                    help="measure the panel's real refresh rate (needs root, service stopped)")
+    ap.add_argument("--demo", type=float, metavar="PXPS",
+                    help="scroll text at the crisp speed nearest this (needs root)")
+    ap.add_argument("--seconds", type=float, default=15.0, help="demo duration")
+    ap.add_argument("--want", type=float, metavar="PXPS",
+                    help="highlight the entry nearest this speed")
+    args = ap.parse_args()
+
+    hardware = load_hardware()
+    configured = float(hardware.get("limit_refresh_rate_hz") or 0)
+
+    if args.demo is not None:
+        demo(hardware, args.demo, args.seconds)
+        return
+
+    if args.measure:
+        measured = measure_refresh(hardware)
+        print("measured panel refresh: {:.1f}Hz".format(measured))
+        if configured:
+            print("configured limit_refresh_rate_hz: {:.0f}".format(configured))
+            if measured < configured * 0.95:
+                print("  -> the panel cannot reach the configured rate; the ladder")
+                print("     below uses what it actually manages")
+        print_ladder(measured, args.want)
+        return
+
+    hz = args.hz or configured or scroll_config.DEFAULT_REFRESH_HZ
+    if not args.hz and not configured:
+        print("no limit_refresh_rate_hz in config; assuming {:.0f}Hz".format(hz))
+        print("run with --measure to find your panel's real rate")
+    print_ladder(hz, args.want)
+
+
+if __name__ == "__main__":
+    main()

src/__init__.py

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

src/background_data_service.py

@@ -478,22 +478,8 @@ class BackgroundDataService:
                     cb(result)
                 except Exception as e:
                     logger.error(f"Error in callback for request {request.id}: {e}")
-
+                # Delivered. Drop both references -- they point at the same
-            # Released AFTER the loop, not inside it. Every callback here holds
+                # object, so one survivor keeps the whole payload resident.
-            # the same FetchResult, so releasing per-delivery handed the first
-            # one the data and every joiner `result.data is None` -- which is
-            # not a quiet degradation: they read `result.data.get('events')` and
-            # raise AttributeError, which this very loop catches and logs, so
-            # the symptom was one ERROR line and a manager that silently never
-            # got its schedule. Deduplication is the normal case, not a corner:
-            # a sport's recent, upcoming and live managers all ride one season
-            # fetch.
-            #
-            # Guarded on `callbacks`, because a request submitted without one
-            # has no other way to collect its payload than polling get_result().
-            # The old per-delivery release got that right by accident: an empty
-            # list never entered the loop body.
-            if callbacks:
                 self._release_payload(result)
                 request.result = None
 
@@ -503,11 +489,8 @@ class BackgroundDataService:
     def _release_payload(result: FetchResult) -> None:
         """Drop a delivered payload, keeping the result's status and timings.
 
-        Only called once EVERY callback has been handed the data -- callers
+        Only called once a callback has been handed the data. Consumers read
-        that joined an in-flight fetch share this object, so releasing between
+        fetched data back from the cache under ``cache_key``; the copy carried
-        deliveries strips the payload out from under the ones still queued.
-        Consumers read fetched data back from the cache under ``cache_key``;
-        the copy carried
         here was pinning a parsed season schedule -- 946 games for NCAA
         football, roughly a tenth of total RAM on a 1GB Pi -- in memory until
         the hourly sweep.

src/cache/disk_cache.py

@@ -5,6 +5,7 @@ Handles persistent disk-based caching with atomic writes and error recovery.
 """
 
 import json
+import math
 import os
 import time
 import tempfile
@@ -14,6 +15,11 @@ import zlib
 from typing import Dict, Any, Optional, Protocol
 from datetime import datetime
 
+try:  # optional: large speedup on the cache write path, see _dumps below
+    import orjson
+except ImportError:  # pragma: no cover - exercised on hosts without the wheel
+    orjson = None
+
 # How old an abandoned write's temp file must be before the sweep removes it.
 # A real write holds its temp file for milliseconds, so an hour is far beyond
 # any in-flight write while still clearing the same day's debris. Deliberately
@@ -40,13 +46,97 @@ class CacheStrategyProtocol(Protocol):
 
 
 class DateTimeEncoder(json.JSONEncoder):
-    """JSON encoder that handles datetime objects."""
+    """JSON encoder that handles datetime objects.
+
+    Retained for the stdlib fallback path and for any caller importing it.
+    """
     def default(self, obj: Any) -> Any:
         if isinstance(obj, datetime):
             return obj.isoformat()
         return super().default(obj)
 
 
+def _datetime_default(obj: Any) -> Any:
+    """Serialise datetimes exactly as DateTimeEncoder did."""
+    if isinstance(obj, datetime):
+        return obj.isoformat()
+    raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")
+
+
+def _replace_nonfinite(obj: Any) -> Any:
+    """Non-finite floats -> None, matching what ``orjson.dumps`` writes.
+
+    Only reached once a strict pass has proved there is something to replace,
+    so the ordinary write path never pays for this walk.
+    """
+    if isinstance(obj, float):
+        return obj if math.isfinite(obj) else None
+    if isinstance(obj, dict):
+        return {k: _replace_nonfinite(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_replace_nonfinite(v) for v in obj]
+    return obj
+
+
+# NON-FINITE FLOATS
+# -----------------
+# JSON has no NaN or Infinity. The stdlib emits them anyway as an extension;
+# orjson refuses to and writes null. That divergence is not acceptable in a
+# cache whose files outlive the decision of which encoder is installed, so the
+# policy here is one behaviour on both paths:
+#
+#   writing  non-finite floats become null, whichever encoder is in use
+#   reading  files already on disk that carry the stdlib's NaN/Infinity
+#            tokens stay readable, whichever encoder is in use
+#
+# Without the write half, installing orjson silently changed cached values.
+# Without the read half, installing orjson turned every legacy record holding a
+# NaN into a "corrupted cache file" that DiskCache.get logged as an error and
+# deleted. Both halves are covered by test/test_cache_nonfinite_floats.py.
+
+
+if orjson is not None:
+    # Encoding the cache record dominated the background fetch worker: on a
+    # Pi 4, stdlib json.dumps runs ~12ms per MB and holds the GIL for all of
+    # it, which stalls the render thread mid-scroll. orjson measures ~7x
+    # faster on the same payloads (11.9ms -> 1.6ms for 985KB). Decoding gains
+    # far less (~1.3x on large payloads) because the cost there is building
+    # the Python objects, not scanning the text, but it is still free to take.
+    #
+    # OPT_NON_STR_KEYS: stdlib json coerces int/float dict keys to strings;
+    # orjson raises without this, and cache records do carry numeric keys.
+    # OPT_PASSTHROUGH_DATETIME: orjson would otherwise emit its own RFC 3339
+    # form for datetimes instead of calling default(). Routing them through
+    # _datetime_default keeps byte-for-byte parity with the records already
+    # on disk.
+    _DUMPS_OPTS = orjson.OPT_NON_STR_KEYS | orjson.OPT_PASSTHROUGH_DATETIME
+
+    def _dumps(data: Any) -> bytes:
+        return orjson.dumps(data, default=_datetime_default, option=_DUMPS_OPTS)
+
+    def _loads(raw: bytes) -> Any:
+        try:
+            return orjson.loads(raw)
+        except orjson.JSONDecodeError:
+            # Legacy record written by the stdlib path, carrying NaN or
+            # Infinity. Genuinely malformed files raise again from here, as
+            # json.JSONDecodeError, which is what DiskCache.get expects.
+            return json.loads(raw)
+else:
+    def _dumps(data: Any) -> bytes:
+        try:
+            return json.dumps(data, cls=DateTimeEncoder,
+                              allow_nan=False).encode("utf-8")
+        except ValueError:
+            # allow_nan=False is what detects the non-finite values; the walk
+            # runs only now that we know there is one to replace.
+            return json.dumps(_replace_nonfinite(data), cls=DateTimeEncoder,
+                              allow_nan=False).encode("utf-8")
+
+    def _loads(raw: bytes) -> Any:
+        return json.loads(raw)
+
+
 class DiskCache:
     """Manages persistent disk-based cache."""
     
@@ -99,8 +189,8 @@ class DiskCache:
         
         try:
             with self._lock:
-                with open(cache_path, 'r', encoding='utf-8') as f:
+                with open(cache_path, 'rb') as f:
-                    record = json.load(f)
+                    record = _loads(f.read())
             
             # Determine record timestamp (prefer embedded, else file mtime)
             record_ts = None
@@ -189,12 +279,12 @@ class DiskCache:
         # write path below, and cache files are machine-read only — indenting
         # them just multiplied the bytes written to the SD card.
         try:
-            payload = json.dumps(data, cls=DateTimeEncoder)
+            payload = _dumps(data)
         except (TypeError, ValueError) as e:
             self.logger.warning("Cache data for key '%s' not serializable: %s", key, e)
             return
 
-        digest = zlib.adler32(payload.encode('utf-8'))
+        digest = zlib.adler32(payload)
 
         try:
             # Atomic write to avoid partial/corrupt files
@@ -242,7 +332,7 @@ class DiskCache:
                         # wear source (dozens of fsyncs/min on API-heavy
                         # installs) for data that can be re-downloaded.
                         try:
-                            with os.fdopen(fd, 'w', encoding='utf-8') as tmp_file:
+                            with os.fdopen(fd, 'wb') as tmp_file:
                                 tmp_file.write(payload)
                             os.replace(tmp_path, cache_path)
                             self._write_digests[key] = digest
@@ -260,7 +350,7 @@ class DiskCache:
                     else:
                         # Fallback: direct write (not atomic, but better than failing)
                         try:
-                            with open(cache_path, 'w', encoding='utf-8') as cache_file:
+                            with open(cache_path, 'wb') as cache_file:
                                 cache_file.write(payload)
                             self._write_digests[key] = digest
                             # Set proper permissions: 660 (rw-rw----) for group-readable cache files
@@ -290,7 +380,7 @@ class DiskCache:
                             # is a different path, so future sets must keep
                             # retrying the primary location.
                             fallback_path = os.path.join(fallback_dir, os.path.basename(cache_path))
-                            with open(fallback_path, 'w', encoding='utf-8') as tmp_file:
+                            with open(fallback_path, 'wb') as tmp_file:
                                 tmp_file.write(payload)
                             # Set proper permissions: 660 (rw-rw----) for group-readable cache files
                             try:

src/common/__init__.py

@@ -23,6 +23,13 @@ from src.common.error_handler import (
 )
 from src.common.api_helper import APIHelper
 from src.common.scroll_helper import ScrollHelper
+from src.common import scroll_config
+from src.common.scroll_config import (
+    ScrollSettings,
+    configure as configure_scroll,
+    resolve as resolve_scroll_settings,
+    refresh_hz_from_config,
+)
 from src.common.logo_helper import LogoHelper
 from src.common.text_helper import TextHelper
 
@@ -60,6 +67,11 @@ __all__ = [
     'log_and_raise',
     'APIHelper',
     'ScrollHelper',
+    'scroll_config',
+    'ScrollSettings',
+    'configure_scroll',
+    'resolve_scroll_settings',
+    'refresh_hz_from_config',
     'LogoHelper',
     'TextHelper',
     # adaptive layout & images

src/common/logo_helper.py

@@ -143,10 +143,8 @@ class LogoHelper:
         """
         logo_path = Path(logo_path)
         
-        # Try to load existing logo first. A placeholder written by a previous
+        # Try to load existing logo first
-        # failed download does not count: it wears the real logo's filename, so
+        if logo_path.exists():
-        # trusting the file's existence is what left teams as grey boxes.
-        if logo_path.exists() and not self._is_stale_placeholder(logo_path):
             return self.load_logo(team_abbr, logo_path, max_width, max_height)
         
         # Download if URL provided and file doesn't exist
@@ -154,61 +152,13 @@ class LogoHelper:
             try:
                 self.logger.info(f"Downloading logo for {team_abbr} from {logo_url}")
                 self._download_logo(logo_url, logo_path)
-                # The file on disk just changed. Any cached image for it is the
-                # placeholder we came here to replace, and load_logo() answers
-                # from the cache before touching the disk -- so without this the
-                # real logo would not appear until the process restarted.
-                self._invalidate_cached_logo(team_abbr, logo_path)
                 return self.load_logo(team_abbr, logo_path, max_width, max_height)
             except Exception as e:
                 self.logger.error(f"Failed to download logo for {team_abbr}: {e}")
-                # The retry failed, so restart the back-off. The stale
-                # placeholder is still on disk with its old timestamp, and
-                # leaving it there means the next call retries immediately --
-                # a download attempt per call, which is what the back-off
-                # exists to prevent.
-                self._refresh_stale_placeholder(logo_path)
         
         # Create placeholder if all else fails
         return self._create_placeholder_logo(team_abbr, max_width, max_height)
     
-    def _invalidate_cached_logo(self, team_abbr: str, logo_path: Path) -> None:
-        """Drop every cached size of one logo after its file changed on disk."""
-        prefix = f"{team_abbr}_{logo_path}_"
-        for key in [k for k in self._logo_cache if k.startswith(prefix)]:
-            self._logo_cache.pop(key, None)
-            if key in self._cache_order:
-                self._cache_order.remove(key)
-
-    @staticmethod
-    def _refresh_stale_placeholder(logo_path: Path) -> None:
-        """Restart the retry back-off after a failed download attempt."""
-        try:
-            from src.logo_downloader import refresh_placeholder_timestamp
-        except ImportError:
-            return
-        refresh_placeholder_timestamp(logo_path)
-
-    @staticmethod
-    def _is_stale_placeholder(logo_path: Path) -> bool:
-        """True if the file is a placeholder old enough to be worth retrying.
-
-        Imported lazily so this module keeps working against a core build whose
-        logo_downloader predates placeholder marking.
-        """
-        try:
-            from src.logo_downloader import (
-                PLACEHOLDER_RETRY_SECONDS,
-                is_placeholder_logo,
-                placeholder_age_seconds,
-            )
-        except ImportError:
-            return False
-        if not is_placeholder_logo(logo_path):
-            return False
-        age = placeholder_age_seconds(logo_path)
-        return age is None or age >= PLACEHOLDER_RETRY_SECONDS
-
     def get_logo_variations(self, team_abbr: str) -> List[str]:
         """
         Get possible filename variations for a team abbreviation.

src/common/scroll_config.py

@@ -0,0 +1,440 @@
+"""One place that turns plugin config into a configured ScrollHelper.
+
+Five ticker plugins each hand-rolled this resolution (odds-ticker, news and
+ledmatrix-leaderboard reference the deprecated ``scroll_pixels_per_second``
+key 16-18 times apiece), and they disagreed in ways that were invisible until
+someone watched the panel:
+
+* odds-ticker read ``scroll_pixels_per_second`` on the *recommended* config
+  path and let it override ``scroll_speed``/``scroll_delay``. Because that key
+  carries a schema default, the documented settings were dead for every user
+  -- see ChuckBuilds/ledmatrix-plugins#408.
+* ledmatrix-leaderboard read the same key only as a fallback, so identical
+  config produced different speeds in the two plugins.
+* stock-news derived px/frame from it via its own arithmetic.
+
+What matters on the hardware
+----------------------------
+Motion is smooth when the strip advances a **whole number of pixels per panel
+refresh**. On a 100Hz panel that means 100 px/s, 200 px/s, and so on. Anything
+else has to either blend adjacent columns (which on pixel-font text reads as
+shimmer) or repeat frames (which reads as judder). :func:`resolve` warns when
+the requested speed will not divide evenly, because that is a real display
+artefact and not a rounding detail.
+
+Speed is always expressed to the helper as pixels per second and applied in
+time-based mode. Frame-based stepping gates motion on a wall clock at
+``1/scroll_delay`` steps per second; plugins set ``scroll_delay`` to the frame
+period, which puts that comparison exactly on its own threshold and makes the
+step count flip on sub-millisecond jitter. Accumulating elapsed time keeps
+position proportional to real time instead.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, replace
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+#: Speed used when a plugin supplies nothing usable. One pixel per refresh on a
+#: 100Hz panel, which is the slowest crisp scroll that hardware can show.
+DEFAULT_PIXELS_PER_SECOND = 100.0
+
+#: Bounds accepted from config. Below the floor a marquee appears frozen;
+#: above the ceiling it outruns any panel's refresh and tears.
+MIN_PIXELS_PER_SECOND = 1.0
+MAX_PIXELS_PER_SECOND = 500.0
+
+#: Assumed refresh when the caller does not say. Matches the usual
+#: ``display.hardware.limit_refresh_rate_hz``.
+DEFAULT_REFRESH_HZ = 100.0
+
+#: How far px/s may sit from a whole number of pixels per refresh before it is
+#: worth warning about. 0.05px per frame is invisible; a third of a pixel is not.
+_WHOLE_PIXEL_TOLERANCE = 0.05
+
+
+#: Longest a frame may be held before motion reads as a slideshow rather than
+#: a scroll. 6 refreshes at 100Hz is ~17px/s, already visibly stepped.
+MAX_FRAME_HOLD = 8
+
+#: Largest whole-pixel jump per presented frame before motion looks like it is
+#: teleporting rather than sliding.
+MAX_PIXELS_PER_FRAME = 6
+
+
+@dataclass(frozen=True)
+class CrispSpeed:
+    """A speed the panel can show with whole-pixel motion.
+
+    ``pixels_per_second`` is always ``refresh_hz / frame_hold * pixels_per_frame``
+    exactly -- no rounding, no fractional pixel positions, so nothing has to be
+    blended or repeated unevenly.
+
+    :param frame_hold: refreshes each frame is held for. This is rgbmatrix's
+        ``SwapOnVSync(canvas, framerate_fraction)``. The panel keeps refreshing
+        at full rate either way, so holding a frame costs nothing in flicker.
+    :param pixels_per_frame: whole pixels advanced per presented frame.
+    """
+
+    pixels_per_second: float
+    frame_hold: int
+    pixels_per_frame: int
+    refresh_hz: float
+
+    @property
+    def frames_per_second(self) -> float:
+        return self.refresh_hz / self.frame_hold
+
+    @property
+    def steppiness(self) -> str:
+        """Rough readability hint for this combination."""
+        if self.pixels_per_frame > 2:
+            return "jumpy"
+        if self.frames_per_second < 20:
+            return "stepped"
+        if self.frames_per_second < 30:
+            return "slightly stepped"
+        return "smooth"
+
+    def describe(self) -> str:
+        return (
+            f"{self.pixels_per_second:6.1f} px/s  "
+            f"({self.pixels_per_frame}px every {self.frame_hold} refresh"
+            f"{'es' if self.frame_hold != 1 else ' '} = "
+            f"{self.frames_per_second:5.1f} fps, {self.steppiness})"
+        )
+
+
+def crisp_ladder(
+    refresh_hz: float = DEFAULT_REFRESH_HZ,
+    max_frame_hold: int = MAX_FRAME_HOLD,
+    max_pixels_per_frame: int = MAX_PIXELS_PER_FRAME,
+):
+    """Every whole-pixel speed this panel can show, slowest first.
+
+    Duplicates are collapsed keeping the gentlest option: 100 px/s is reachable
+    as 1px every refresh or 2px every 2nd refresh, and the former moves in
+    smaller increments, so that is the one worth offering.
+    """
+    best = {}
+    for hold in range(1, max_frame_hold + 1):
+        for ppf in range(1, max_pixels_per_frame + 1):
+            pps = refresh_hz / hold * ppf
+            key = round(pps, 3)
+            candidate = CrispSpeed(pps, hold, ppf, refresh_hz)
+            incumbent = best.get(key)
+            if incumbent is None or ppf < incumbent.pixels_per_frame:
+                best[key] = candidate
+    return [best[k] for k in sorted(best)]
+
+
+#: How much a bigger pixel step costs, as a fraction of the target speed.
+#: Tuned so 66.7px/s (2px at 33fps) beats 50px/s (1px at 50fps) when 60 was
+#: asked for, but 33.3px/s (1px, smooth) still beats 28.6px/s (2px at 14fps)
+#: when 30 was asked for -- being 11% slow is worth far less than looking bad.
+_STEP_PENALTY = 0.05
+_SLOW_FPS_PENALTY = 0.25   # below 20fps
+_LOWISH_FPS_PENALTY = 0.10  # below 25fps
+
+
+def _quality_cost(candidate: "CrispSpeed", target: float) -> float:
+    """Lower is better. Numeric closeness alone picks bad-looking speeds.
+
+    Nearest-by-value would answer "30 px/s" with 28.6 px/s -- which is 2px
+    jumps at 14fps -- over 33.3 px/s, which is single-pixel motion at 33fps and
+    obviously better on the panel. Proximity has to be traded against how the
+    motion actually reads.
+    """
+    error = abs(candidate.pixels_per_second - target) / max(target, 1e-6)
+    cost = error + _STEP_PENALTY * (candidate.pixels_per_frame - 1)
+    fps = candidate.frames_per_second
+    if fps < 20:
+        cost += _SLOW_FPS_PENALTY
+    elif fps < 25:
+        cost += _LOWISH_FPS_PENALTY
+    return cost
+
+
+def solve_crisp(
+    target_pixels_per_second: float,
+    refresh_hz: float = DEFAULT_REFRESH_HZ,
+    max_frame_hold: int = MAX_FRAME_HOLD,
+    max_pixels_per_frame: int = MAX_PIXELS_PER_FRAME,
+) -> CrispSpeed:
+    """The whole-pixel speed that will look best for what was asked for.
+
+    Not simply the nearest -- see :func:`_quality_cost`. Ties break toward the
+    smaller pixel step and the shorter hold.
+    """
+    ladder = crisp_ladder(refresh_hz, max_frame_hold, max_pixels_per_frame)
+    # Clamp into the ladder's range first. Relative error saturates near 1.0
+    # for a target far outside it, so the quality penalty would dominate and
+    # answer "10000 px/s" with the *slowest* entry -- smooth, and useless.
+    target = min(max(target_pixels_per_second, ladder[0].pixels_per_second),
+                 ladder[-1].pixels_per_second)
+    return min(
+        ladder,
+        key=lambda c: (round(_quality_cost(c, target), 6),
+                       c.pixels_per_frame, c.frame_hold),
+    )
+
+
+@dataclass(frozen=True)
+class ScrollSettings:
+    """The resolved outcome, and which config key produced it."""
+
+    pixels_per_second: float
+    source: str
+    target_fps: Optional[float] = None
+    pixels_per_frame: Optional[float] = None
+    warning: Optional[str] = None
+    #: The whole-pixel speed actually applied, when snapping was enabled.
+    crisp: Optional[CrispSpeed] = None
+    #: What the config asked for, before snapping.
+    requested_pixels_per_second: Optional[float] = None
+
+    @property
+    def frame_hold(self) -> int:
+        """Refreshes to hold each frame for; pass to set_scrolling_state()."""
+        return self.crisp.frame_hold if self.crisp else 1
+
+    def describe(self) -> str:
+        text = f"{self.pixels_per_second:.1f} px/s (from {self.source})"
+        if self.pixels_per_frame is not None:
+            text += f" = {self.pixels_per_frame:.2f} px/frame"
+        if self.target_fps:
+            text += f" at {self.target_fps:.0f} fps"
+        return text
+
+
+def _coerce(value: Any) -> Optional[float]:
+    """A positive float, or None. Config reaches us with nulls and strings."""
+    if value is None or isinstance(value, bool):
+        return None
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        return None
+    return number if number > 0 else None
+
+
+def _from_speed_and_delay(block: Any) -> Optional[float]:
+    """px/s from a ``scroll_speed`` (px/frame) + ``scroll_delay`` (s) pair."""
+    if not isinstance(block, dict):
+        return None
+    speed = _coerce(block.get("scroll_speed"))
+    delay = _coerce(block.get("scroll_delay"))
+    if speed is None or delay is None:
+        return None
+    return speed / delay
+
+
+def resolve(
+    plugin_config: Optional[Dict[str, Any]] = None,
+    global_config: Optional[Dict[str, Any]] = None,
+    default_pixels_per_second: float = DEFAULT_PIXELS_PER_SECOND,
+    refresh_hz: Optional[float] = None,
+) -> ScrollSettings:
+    """Resolve one scroll speed from the several shapes plugins accept.
+
+    Precedence, highest first. The deprecated flat key sits *below* the
+    explicit pairs deliberately: it carries schema defaults in some plugins, so
+    ranking it above them silently disables the documented settings.
+
+    1. ``display_options.scroll_speed`` + ``scroll_delay``  (current)
+    2. ``display.scroll_speed`` + ``scroll_delay``          (deprecated shape)
+    3. ``scroll_speed`` + ``scroll_delay`` at the root      (legacy flat)
+    4. ``scroll_pixels_per_second``, nested or flat         (deprecated)
+    5. the global ``display`` block
+    6. ``default_pixels_per_second``
+
+    :param refresh_hz: panel refresh, used only to check whether the resolved
+        speed lands on whole pixels per frame and to fill in ``target_fps``.
+    """
+    plugin_config = plugin_config or {}
+    global_config = global_config or {}
+    refresh = _coerce(refresh_hz) or DEFAULT_REFRESH_HZ
+
+    display_options = plugin_config.get("display_options")
+    display_block = plugin_config.get("display")
+
+    candidates = [
+        (_from_speed_and_delay(display_options), "display_options.scroll_speed/delay"),
+        (_from_speed_and_delay(display_block), "display.scroll_speed/delay"),
+        (_from_speed_and_delay(plugin_config), "scroll_speed/delay (root)"),
+    ]
+    for block, label in (
+        (display_options, "display_options.scroll_pixels_per_second"),
+        (display_block, "display.scroll_pixels_per_second"),
+        (plugin_config, "scroll_pixels_per_second"),
+    ):
+        if isinstance(block, dict):
+            candidates.append((_coerce(block.get("scroll_pixels_per_second")), label))
+
+    global_display = global_config.get("display")
+    candidates.append((_from_speed_and_delay(global_display), "global display.scroll_speed/delay"))
+
+    pixels_per_second = None
+    source = "default"
+    for value, label in candidates:
+        if value is not None:
+            pixels_per_second, source = value, label
+            break
+    if pixels_per_second is None:
+        pixels_per_second = default_pixels_per_second
+
+    clamped = max(MIN_PIXELS_PER_SECOND, min(MAX_PIXELS_PER_SECOND, pixels_per_second))
+    warning = None
+    if clamped != pixels_per_second:
+        warning = (
+            f"scroll speed {pixels_per_second:.1f} px/s out of range, "
+            f"clamped to {clamped:.1f}"
+        )
+        pixels_per_second = clamped
+
+    pixels_per_frame = pixels_per_second / refresh if refresh > 0 else None
+    if warning is None and pixels_per_frame is not None:
+        offset = abs(pixels_per_frame - round(pixels_per_frame))
+        if pixels_per_frame < 1.0 - _WHOLE_PIXEL_TOLERANCE or offset > _WHOLE_PIXEL_TOLERANCE:
+            suggestion = max(1.0, round(pixels_per_frame)) * refresh
+            warning = (
+                f"{pixels_per_second:.1f} px/s is {pixels_per_frame:.2f} px per "
+                f"refresh at {refresh:.0f}Hz, so some frames repeat and the "
+                f"scroll will judder; {suggestion:.0f} px/s divides evenly"
+            )
+
+    return ScrollSettings(
+        pixels_per_second=pixels_per_second,
+        source=source,
+        target_fps=refresh,
+        pixels_per_frame=pixels_per_frame,
+        warning=warning,
+    )
+
+
+def configure(
+    scroll_helper: Any,
+    plugin_config: Optional[Dict[str, Any]] = None,
+    global_config: Optional[Dict[str, Any]] = None,
+    default_pixels_per_second: float = DEFAULT_PIXELS_PER_SECOND,
+    refresh_hz: Optional[float] = None,
+    plugin_logger: Optional[logging.Logger] = None,
+    display_manager: Any = None,
+    snap_to_crisp: bool = True,
+) -> ScrollSettings:
+    """Resolve the config and apply it to ``scroll_helper``.
+
+    Applied in time-based mode: see the module docstring for why frame-based
+    stepping is not used. ``hasattr`` guards keep this usable against older
+    ScrollHelper builds that a plugin may be running on.
+
+    :param display_manager: consulted for the panel's refresh rate only (it can
+        see display.hardware; a plugin cannot). The frame hold is NOT applied
+        here -- see the note in the body. The caller must pass
+        ``settings.frame_hold`` to ``display_manager.set_scrolling_state(True,
+        ...)`` when it starts scrolling, or a sub-refresh speed still presents
+        a new frame every refresh and the motion falls back to fractional
+        pixels.
+    :param snap_to_crisp: move the requested speed to the nearest speed the
+        panel can show in whole pixels. On by default because a speed that does
+        not divide evenly has no good rendering, only a choice of artefacts.
+
+    :returns: the settings applied, so the caller can log or assert on them.
+    """
+    log = plugin_logger or logger
+
+    # Refresh rate, most authoritative first: what the caller passed, then the
+    # display manager (which can see display.hardware; a plugin cannot), then
+    # the global config, then the default.
+    #
+    # This has to be settled BEFORE resolve(), not after. resolve() uses the
+    # refresh to fill in target_fps, pixels_per_frame and the judder warning,
+    # so deriving it afterwards described a 100Hz panel to everyone running at
+    # 60 -- and with snap_to_crisp=False nothing downstream corrected it, so
+    # set_target_fps() paced the helper to 100 FPS on a 60Hz panel.
+    hz = _coerce(refresh_hz)
+    if hz is None and display_manager is not None:
+        hz = _coerce(getattr(display_manager, "refresh_hz", None))
+    if hz is None:
+        hz = refresh_hz_from_config(global_config)
+
+    settings = resolve(
+        plugin_config,
+        global_config,
+        default_pixels_per_second=default_pixels_per_second,
+        refresh_hz=hz,
+    )
+    applied = settings.pixels_per_second
+    choice = None
+
+    if snap_to_crisp:
+        choice = solve_crisp(settings.pixels_per_second, hz)
+        applied = choice.pixels_per_second
+        settings = replace(
+            settings,
+            pixels_per_second=applied,
+            requested_pixels_per_second=settings.pixels_per_second,
+            crisp=choice,
+            pixels_per_frame=float(choice.pixels_per_frame),
+            # Snapping resolves the whole-pixel problem the warning describes.
+            warning=None if settings.warning and "judder" in settings.warning
+            else settings.warning,
+        )
+
+    if hasattr(scroll_helper, "set_frame_based_scrolling"):
+        scroll_helper.set_frame_based_scrolling(False)
+    scroll_helper.set_scroll_speed(applied)
+    if choice and hasattr(scroll_helper, "set_target_fps"):
+        scroll_helper.set_target_fps(choice.frames_per_second)
+    elif settings.target_fps and hasattr(scroll_helper, "set_target_fps"):
+        scroll_helper.set_target_fps(settings.target_fps)
+
+    # Deliberately NOT applied here. The hold belongs to a scroll, not to a
+    # plugin's lifetime: plugins share one display manager, and one left set at
+    # construction is reset the moment any other plugin finishes scrolling.
+    # Callers pass settings.frame_hold to set_scrolling_state(True, ...) when
+    # they start scrolling. configure() only reports what is needed.
+
+    if choice:
+        requested = settings.requested_pixels_per_second
+        if abs(requested - applied) > 0.05:
+            log.info(
+                "Scroll configured: %s (asked for %.1f px/s from %s; "
+                "nearest whole-pixel speed on a %.0fHz panel)",
+                choice.describe(), requested, settings.source, hz,
+            )
+        else:
+            log.info("Scroll configured: %s (from %s)",
+                     choice.describe(), settings.source)
+        if choice.frame_hold > 1:
+            log.debug(
+                "Scroll needs a frame hold of %d - pass settings.frame_hold to "
+                "display_manager.set_scrolling_state(True, ...) each scroll",
+                choice.frame_hold,
+            )
+    else:
+        log.info("Scroll configured: %s", settings.describe())
+
+    if settings.warning:
+        log.warning("Scroll speed: %s", settings.warning)
+    return settings
+
+
+def refresh_hz_from_config(global_config: Optional[Dict[str, Any]]) -> float:
+    """The panel's refresh cap from the global config, or the default."""
+    if not isinstance(global_config, dict):
+        return DEFAULT_REFRESH_HZ
+    # Each level is checked for being a mapping rather than merely truthy: a
+    # malformed config where display or display.hardware is a string or a list
+    # raised AttributeError out of what is meant to be a total function with a
+    # default, taking down every caller that asked for the refresh rate.
+    display = global_config.get("display")
+    if not isinstance(display, dict):
+        return DEFAULT_REFRESH_HZ
+    hardware = display.get("hardware")
+    if not isinstance(hardware, dict):
+        return DEFAULT_REFRESH_HZ
+    return _coerce(hardware.get("limit_refresh_rate_hz")) or DEFAULT_REFRESH_HZ

src/common/scroll_helper.py

@@ -16,6 +16,7 @@ Features:
 """
 
 import logging
+import math
 import time
 from typing import Optional, Dict, Any
 from PIL import Image
@@ -29,6 +30,49 @@ except ImportError:
     HAS_SCIPY = False
 
 
+def frame_stats(frame_times: list) -> Dict[str, Any]:
+    """Summary statistics over one window of frame durations (seconds).
+
+    Split out of log_frame_rate() so the arithmetic can be tested without a
+    clock. Median and p95 are the real ones: the median takes both middle
+    samples on an even window, and p95 is nearest-rank, so a 100-frame window
+    reports the 95th sorted sample rather than the 96th. That matters twice
+    over, because the median is also the threshold the stall and skip counts
+    are measured against.
+    """
+    window = sorted(frame_times)
+    n = len(window)
+    median = (window[n // 2] if n % 2
+              else (window[n // 2 - 1] + window[n // 2]) / 2.0)
+    mean = sum(window) / n
+    # Anything past 1.5x the median missed a panel refresh; anything under
+    # half of it never reached the panel at all (dirty tracking skipped the
+    # swap, so the frame did not wait for vsync).
+    return {
+        "frames": n,
+        "fps": (1.0 / mean) if mean > 0 else 0.0,
+        "median": median,
+        "p95": window[max(0, math.ceil(0.95 * n) - 1)],
+        "max": window[-1],
+        "min": window[0],
+        "stalls": sum(1 for f in window if f > median * 1.5),
+        "skips": sum(1 for f in window if f < median * 0.5),
+    }
+
+
+def format_frame_stats(frame_times: list) -> str:
+    """The one-line rendering of frame_stats(), in milliseconds."""
+    s = frame_stats(frame_times)
+    n = s["frames"]
+    return (
+        f"{s['fps']:.1f} fps over {n} frames | "
+        f"median {s['median'] * 1000:.2f}ms p95 {s['p95'] * 1000:.2f}ms "
+        f"max {s['max'] * 1000:.2f}ms min {s['min'] * 1000:.2f}ms | "
+        f"stalls {s['stalls']} ({100.0 * s['stalls'] / n:.1f}%) "
+        f"skips {s['skips']} ({100.0 * s['skips'] / n:.1f}%)"
+    )
+
+
 class ScrollHelper:
     """
     Helper class for scrolling text and image content on LED displays.
@@ -75,8 +119,19 @@ class ScrollHelper:
         # Pre-allocated buffer for output frame (reused to avoid allocations)
         self._frame_buffer: Optional[np.ndarray] = None
         
-        # Sub-pixel scrolling settings (disabled - using high FPS integer scrolling instead)
+        # Sub-pixel scrolling: OFF by default, and that is deliberate.
-        self.sub_pixel_scrolling = False  # Disabled - use high frame rate for smoothness
+        # Blending renders a half-step by mixing two adjacent columns 50/50.
+        # On a high-resolution screen that reads as smooth motion; on a coarse
+        # LED matrix showing pixel-font text it does not. A one-pixel stroke
+        # becomes two half-brightness pixels, so frames alternate between crisp
+        # and smeared and the text appears to shimmer and jump a pixel ahead --
+        # tested on a 2x128x64 panel and clearly worse than integer stepping.
+        #
+        # The rule this display obeys: motion is smooth when it advances a
+        # whole number of pixels per refresh. Anything slower must either
+        # blend (blur) or repeat frames (judder); blending is the worse of the
+        # two here. Vegas mode still opts in via set_sub_pixel_scrolling().
+        self.sub_pixel_scrolling = False
         self._last_integer_position = 0  # Cache for integer position to avoid repeated calculations
         
         # Frame-based scrolling settings
@@ -105,6 +160,9 @@ class ScrollHelper:
         self.last_frame_time = time.time()
         self.last_fps_log_time = time.time()
         self.frame_times = []
+        # Every frame time since the last stats line, so the 5s summary can
+        # report the tail rather than one arbitrary sample. Cleared on log.
+        self._window: list = []
         
         # Scrolling state management
         self.is_scrolling = False
@@ -244,19 +302,31 @@ class ScrollHelper:
             if self.last_step_time == 0.0:
                 self.last_step_time = current_time
             
-            # Check if scroll_delay has passed
+            # Frame-based mode advances by elapsed time, exactly like the
-            time_since_last_step = current_time - self.last_step_time
+            # time-based branch below, at the same configured speed
-            if time_since_last_step >= self.scroll_delay:
+            # (scroll_speed px per scroll_delay seconds).
-                # Move pixels (can move multiple steps if lag occurred, but cap to prevent huge jumps)
+            #
-                steps = int(time_since_last_step / self.scroll_delay)
+            # It used to step discretely: 0, 1 or 2 whole pixels depending on
-                # Cap at reasonable number to prevent huge jumps from lag
+            # whether a wall clock had passed scroll_delay. Plugins set
-                max_steps = max(1, int(0.04 / self.scroll_delay))  # Limit to 0.04s (2 steps at 50 FPS) for smoother scrolling
+            # scroll_delay to the target frame period, so that comparison sits
-                steps = min(steps, max_steps)
+            # exactly on its own threshold and the decision flips on sub-
-                pixels_to_move = self.scroll_speed * steps
+            # millisecond jitter -- a frame a hair early moved nothing and
-                # Update last_step_time, preserving fractional delay for smooth timing
+            # rendered an identical frame, a frame a hair late moved two
-                self.last_step_time = current_time - (time_since_last_step % self.scroll_delay)
+            # pixels. Rounding the step count fixed the stalls but still
+            # discarded the remainder, so the error never corrected.
+            #
+            # Accumulating elapsed time keeps position exactly proportional to
+            # real time: jitter shifts a pixel boundary by a fraction of a
+            # frame instead of flipping a whole step, and nothing is lost or
+            # gained. This is what the one visibly smooth scroller on the
+            # hardware (the stock ticker) was already doing by virtue of never
+            # enabling frame-based mode.
+            if self.scroll_delay > 0:
+                pixels_per_second = self.scroll_speed / self.scroll_delay
             else:
-                pixels_to_move = 0.0
+                pixels_per_second = self.scroll_speed * 100.0
+            pixels_to_move = pixels_per_second * delta_time
+            self.last_step_time = current_time
         else:
             # Time-based: move based on time delta (correct speed over time)
             # scroll_speed is pixels per second
@@ -1017,18 +1087,25 @@ class ScrollHelper:
         # Keep only last 100 frames for average
         if len(self.frame_times) > 100:
             self.frame_times.pop(0)
+
+        # Every frame since the last log, not just the last 100 and not just
+        # the one that happens to land on the 5s boundary. The old line
+        # reported a single instantaneous sample -- roughly 1 frame in 500 --
+        # which cannot see a stall that hits 1% of frames, and reported it
+        # next to an average that hides the same stall by construction (a 2ms
+        # duplicate and a 21ms double-wait mean exactly 10ms). Chasing scroll
+        # judder needs the tail, so keep the window and report percentiles.
+        self._window.append(frame_time)
         
         # Log FPS every 5 seconds to avoid spam
         if current_time - self.last_fps_log_time >= 5.0:
-            avg_frame_time = sum(self.frame_times) / len(self.frame_times)
+            self.logger.info(
-            avg_fps = 1.0 / avg_frame_time if avg_frame_time > 0 else 0
+                "Scroll frame stats - %s",
-            instant_fps = 1.0 / frame_time if frame_time > 0 else 0
+                format_frame_stats(self._window or [frame_time]),
-            
+            )
-            self.logger.info(f"Scroll frame stats - Avg FPS: {avg_fps:.1f}, "
-                           f"Current FPS: {instant_fps:.1f}, "
-                           f"Frame time: {frame_time*1000:.2f}ms")
             self.last_fps_log_time = current_time
             self.frame_count = 0
+            self._window = []
         
         self.last_frame_time = current_time
         self.frame_count += 1

src/common/sports_card.py

@@ -1,460 +0,0 @@
-"""Card-drawing helpers shared by every sports scoreboard plugin.
-
-The eight scoreboards each carried byte-identical copies of the functions
-below: the colour pickers, the settings lookup, the date and time formatting,
-the favourite-team rules and the font-size grid snapping. One fix had to be
-made eight times, and a new scoreboard started by copying them a ninth.
-
-Everything here is a **free function taking explicit arguments**, not a base
-class. Adoption is therefore per-function and reversible: a plugin keeps its
-method and delegates the body, so the call sites and the override points are
-untouched. That is also why `config`, `logger` and `fonts` are parameters
-rather than attributes -- the helper never reaches back into the caller.
-
-The bodies are the plugins' own code, moved rather than rewritten. The one
-deliberate difference is `crisp_size`, which takes the seven-plugin guard
-(`not desired`) instead of football's: they agree on every real input, and
-the extra guard only stops a None size raising TypeError.
-"""
-
-from datetime import datetime, timezone
-from typing import Any, Dict, Optional, Tuple
-from zoneinfo import ZoneInfo
-
-__all__ = [
-    "ELEMENT_FOR_FONT", "FAVORITE_RESULT_COLOR_DEFAULTS", "FONT_NAME_ALIASES",
-    "FONT_PIXEL_GRID", "MONTH_ABBR", "WEEKDAY_ABBR",
-    "scroll_card_option", "element_color", "font_color", "coerce_rgb",
-    "score_color_for", "recent_score_color", "favorite_teams_for",
-    "side_is_favorite", "side_score", "favorite_result",
-    "card_tzinfo", "weekday_for", "format_game_date", "format_game_time",
-    "vs_text", "upcoming_center_mode", "crisp_size", "schema_font_size",
-    "resolve_font_size", "unshare_element_fonts",
-]
-
-#: Which customization element owns each font key, for colour resolution.
-ELEMENT_FOR_FONT: Dict[str, str] = {
-    "score": "score_text",
-    "time": "period_text",
-    "team": "team_name",
-    "status": "status_text",
-    "detail": "detail_text",
-    "rank": "rank_text",
-}
-
-#: Fallback colours when favourite_result_colors is on but a slot is unset.
-FAVORITE_RESULT_COLOR_DEFAULTS: Dict[str, Tuple[int, int, int]] = {
-    "win": (0, 255, 0),
-    "loss": (255, 0, 0),
-    "tie": (255, 200, 0),
-}
-
-#: Family aliases the web UI may write, mapped to the shipped filename.
-FONT_NAME_ALIASES: Dict[str, str] = {
-    "press_start": "PressStart2P-Regular.ttf",
-    "four_by_six": "4x6-font.ttf",
-}
-
-#: Pixel grid each face renders crisply on. Off-grid sizes anti-alias, which
-#: on an LED matrix is a dim lamp rather than a soft edge.
-FONT_PIXEL_GRID: Dict[str, int] = {
-    "PressStart2P-Regular.ttf": 8,
-    "4x6-font.ttf": 7,
-}
-
-MONTH_ABBR = ("Jan", "Feb", "Mar", "Apr", "May", "Jun",
-              "Jul", "Aug", "Sep", "Oct", "Nov", "Dec")
-WEEKDAY_ABBR = ("Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun")
-
-
-# ---------------------------------------------------------------------------
-# Settings lookup
-# ---------------------------------------------------------------------------
-
-def scroll_card_option(config: Optional[Dict[str, Any]], key: str,
-                       default: Any = None) -> Any:
-    """Read one key from the scroll_card config block."""
-    block = (config or {}).get("scroll_card")
-    if isinstance(block, dict) and block.get(key) is not None:
-        return block.get(key)
-    return default
-
-
-def vs_text(config: Optional[Dict[str, Any]]) -> str:
-    """Separator drawn between the teams -- "VS", "@", "at", anything."""
-    return str(scroll_card_option(config, "vs_text", "VS"))
-
-
-def upcoming_center_mode(config: Optional[Dict[str, Any]]) -> str:
-    """Middle of an upcoming card: 'vs', 'date_time' or 'none'."""
-    mode = str(scroll_card_option(config, "upcoming_center", "vs") or "vs").lower()
-    return mode if mode in ("vs", "date_time", "none") else "vs"
-
-
-# ---------------------------------------------------------------------------
-# Colour
-# ---------------------------------------------------------------------------
-
-def element_color(config: Optional[Dict[str, Any]], element: str,
-                  default: Tuple[int, int, int] = (255, 255, 255)):
-    """Per-element text colour from customization.<element>.text_color."""
-    try:
-        cfg = (config or {}).get("customization", {}).get(element, {})
-        value = cfg.get("text_color")
-        if isinstance(value, (list, tuple)) and len(value) == 3:
-            return tuple(max(0, min(255, int(c))) for c in value)
-        if isinstance(value, str) and value.startswith("#") and len(value) == 7:
-            return tuple(int(value[i:i + 2], 16) for i in (1, 3, 5))
-    except (TypeError, ValueError):
-        pass
-    return default
-
-
-def font_color(config: Optional[Dict[str, Any]], fonts: Optional[Dict[str, Any]],
-               font, default: Tuple[int, int, int] = (255, 255, 255)):
-    """Colour for whichever element owns this face.
-
-    Matched on identity, and deliberately gives up when one object is
-    shared: the last-resort font path can hand the same face to several
-    keys, and there is no right answer for which element's colour that is.
-    White is what those draws used before, so ambiguity costs nothing.
-    """
-    try:
-        fonts = fonts or {}
-        matches = [element for key, element in ELEMENT_FOR_FONT.items()
-                   if fonts.get(key) is font]
-        if len(matches) == 1:
-            return element_color(config, matches[0], default)
-    except (AttributeError, TypeError):
-        pass
-    return default
-
-
-def coerce_rgb(value, fallback):
-    """Turn a configured [R, G, B] list into a clamped (r, g, b) tuple."""
-    # Checked before unpacking: a 3-character string ("123") would otherwise
-    # iterate into three digits and yield a colour rather than the fallback.
-    if not isinstance(value, (list, tuple)) or len(value) != 3:
-        return fallback
-    try:
-        r, g, b = (max(0, min(255, int(channel))) for channel in value)
-    except (TypeError, ValueError):
-        return fallback
-    return (r, g, b)
-
-
-# ---------------------------------------------------------------------------
-# Favourite teams
-# ---------------------------------------------------------------------------
-
-def favorite_teams_for(config: Dict[str, Any], game: Dict[str, Any]) -> list:
-    """Favorite teams that apply to this game.
-
-    Both sources are used. Games carry the league manager's *resolved*
-    favorites, which is the only place dynamic groups such as AP_TOP_25
-    appear expanded; the config is read as well so an edit takes effect on
-    already-fetched games, and so hand-built game dicts (tests, other
-    callers) still work.
-    """
-    favorites = list(game.get("favorite_teams") or [])
-    league_config = config.get(str(game.get("league", "") or ""))
-    if isinstance(league_config, dict):
-        favorites += list(league_config.get("favorite_teams") or [])
-    else:
-        favorites += list(config.get("favorite_teams") or [])
-    return favorites
-
-
-def side_is_favorite(game: Dict[str, Any], side: str, favorites: set) -> bool:
-    """Is the home/away side of this game a favorite team?
-
-    Reads both the flat (``home_abbr``) and nested (``home_team.abbrev``)
-    payload shapes, and matches on the ESPN id too, because a couple of
-    leagues (NRL) key favorites by id where abbreviations collide.
-    """
-    candidates = [game.get(f"{side}_abbr"), game.get(f"{side}_id")]
-    team = game.get(f"{side}_team")
-    if isinstance(team, dict):
-        candidates += [team.get("abbrev"), team.get("abbreviation"), team.get("id")]
-    for value in candidates:
-        if value is not None and str(value).strip().upper() in favorites:
-            return True
-    return False
-
-
-def side_score(game: Dict[str, Any], side: str) -> Optional[int]:
-    """Numeric score for one side, from either payload shape."""
-    raw = None
-    team = game.get(f"{side}_team")
-    if isinstance(team, dict) and team.get("score") is not None:
-        raw = team.get("score")
-    if raw is None:
-        raw = game.get(f"{side}_score")
-    try:
-        return int(float(str(raw).strip()))
-    except (TypeError, ValueError):
-        return None
-
-
-def favorite_result(config: Dict[str, Any], game: Dict[str, Any]) -> Optional[str]:
-    """Say how the favorite team did in a finished game.
-
-    Returns 'win', 'loss' or 'tie', or None when there is no single team
-    to root for: no favorites configured, neither side is a favorite, or
-    *both* are -- a favorite-vs-favorite game has no losing side worth
-    flagging in red. Also None when the scores are not usable numbers.
-    """
-    favorites = {
-        str(team).strip().upper()
-        for team in favorite_teams_for(config, game)
-        if str(team).strip()
-    }
-    if not favorites:
-        return None
-
-    home_fav = side_is_favorite(game, "home", favorites)
-    away_fav = side_is_favorite(game, "away", favorites)
-    if home_fav == away_fav:
-        return None
-
-    home_score = side_score(game, "home")
-    away_score = side_score(game, "away")
-    if home_score is None or away_score is None:
-        return None
-
-    if home_score == away_score:
-        return "tie"
-    favorite_score, other_score = (
-        (home_score, away_score) if home_fav else (away_score, home_score)
-    )
-    return "win" if favorite_score > other_score else "loss"
-
-
-def recent_score_color(config: Dict[str, Any], logger, game: Dict[str, Any], default):
-    """Fill color for a finished game's score, per favorite_result_colors."""
-    try:
-        settings = (config.get("customization") or {}).get(
-            "favorite_result_colors"
-        ) or {}
-        if not settings.get("enabled", False):
-            return default
-        result = favorite_result(config, game)
-        if result is None:
-            return default
-        return coerce_rgb(
-            settings.get(f"{result}_color"),
-            FAVORITE_RESULT_COLOR_DEFAULTS[result],
-        )
-    except Exception:
-        logger.debug("Could not resolve favorite result color", exc_info=True)
-        return default
-
-
-def score_color_for(config: Dict[str, Any], logger, game: Dict[str, Any],
-                    game_type: str, default=None):
-    """Fill color for a game card's score. Only finished games are tinted.
-
-    The default is the configured score colour rather than a flat white,
-    so customization.score_text.text_color shows on games the favourite
-    tint does not apply to. The tint still wins where it applies.
-    """
-    if default is None:
-        default = element_color(config, 'score_text')
-    if game_type != "recent":
-        return default
-    return recent_score_color(config, logger, game, default)
-
-
-# ---------------------------------------------------------------------------
-# Date and time
-# ---------------------------------------------------------------------------
-
-def card_tzinfo(config: Optional[Dict[str, Any]], logger):
-    """Timezone for weekday/24h conversions; falls back to UTC."""
-    configured = (config or {}).get("timezone")
-    if configured:
-        try:
-            return ZoneInfo(configured)
-        except (KeyError, ValueError, TypeError, OSError) as exc:
-            # KeyError covers ZoneInfoNotFoundError. A bad zone name in
-            # config should fall back to UTC, not blank the card.
-            logger.debug("Unusable timezone %r: %s", configured, exc)
-    return timezone.utc
-
-
-def weekday_for(config: Optional[Dict[str, Any]], logger,
-                game: Optional[Dict]) -> str:
-    """Weekday abbreviation from the game's start time, or ''."""
-    if not game:
-        return ""
-    raw = game.get("start_time_utc") or game.get("start_time")
-    if not raw:
-        return ""
-    try:
-        start = raw if isinstance(raw, datetime) else datetime.fromisoformat(
-            str(raw).replace("Z", "+00:00"))
-        return WEEKDAY_ABBR[start.astimezone(card_tzinfo(config, logger)).weekday()]
-    except (ValueError, TypeError):
-        return ""
-
-
-def format_game_date(config: Optional[Dict[str, Any]], logger, date_text: str,
-                     game: Optional[Dict] = None) -> str:
-    """Format an upcoming card's date per scroll_card.date_format."""
-    raw = str(date_text or "").strip()
-    if not raw:
-        return ""
-    fmt = str(scroll_card_option(config, "date_format", "abbrev") or "abbrev")
-    if fmt == "numeric":
-        return raw
-    parts = raw.replace("-", "/").split("/")
-    if not (len(parts) >= 2 and parts[0].strip().isdigit() and parts[1].strip().isdigit()):
-        return raw
-    month, day = int(parts[0]), int(parts[1])
-    if not 1 <= month <= 12:
-        return raw
-    name = MONTH_ABBR[month - 1]
-    if fmt == "numeric_day_first":
-        return f"{day}/{month}"
-    if fmt == "day_first":
-        return f"{day} {name}"
-    if fmt == "weekday":
-        weekday = weekday_for(config, logger, game)
-        return f"{weekday} {name} {day}" if weekday else f"{name} {day}"
-    return f"{name} {day}"
-
-
-def format_game_time(config: Optional[Dict[str, Any]], time_text: str) -> str:
-    """Return the time as-is (12h) or converted to 24h."""
-    raw = str(time_text or "").strip()
-    if not raw or str(scroll_card_option(config, "time_format", "12h")) != "24h":
-        return raw
-    cleaned = raw.upper().replace(" ", "")
-    meridiem = "AM" if cleaned.endswith("AM") else "PM" if cleaned.endswith("PM") else ""
-    if not meridiem:
-        return raw
-    try:
-        hh, _, mm = cleaned[:-2].partition(":")
-        hour, minute = int(hh), int(mm or 0)
-    except ValueError:
-        return raw
-    if not (0 <= hour <= 12 and 0 <= minute <= 59):
-        return raw
-    hour = hour % 12 + (12 if meridiem == "PM" else 0)
-    return f"{hour:02d}:{minute:02d}"
-
-
-# ---------------------------------------------------------------------------
-# Font sizing
-# ---------------------------------------------------------------------------
-
-#: Per-schema caches, keyed by the schema's absolute path. Keyed rather than
-#: global because each plugin declares its own defaults; keyed rather than
-#: per-class because the helper has no class to hang it on.
-_SCHEMA_FONT_SIZE_CACHE: Dict[str, Dict[str, int]] = {}
-
-
-def crisp_size(font_file, desired, aliases=None, grid_table=None):
-    """Snap *desired* to the nearest size *font_file* renders crisply at.
-
-    A face with no known grid is returned unchanged, so a user-supplied
-    font is never second-guessed.
-
-    ``aliases`` and ``grid_table`` default to the shared tables; a plugin
-    that ships an extra face can pass its own without forking this.
-    """
-    aliases = FONT_NAME_ALIASES if aliases is None else aliases
-    grid_table = FONT_PIXEL_GRID if grid_table is None else grid_table
-    font_file = aliases.get(font_file, font_file)
-    grid = grid_table.get(font_file)
-    if not grid or not desired or desired <= 0:
-        return desired
-    return max(grid, int(round(float(desired) / grid)) * grid)
-
-
-def schema_font_size(schema_path: str, element_key) -> Optional[int]:
-    """The font_size this plugin's config_schema.json declares, or None.
-
-    Cached per schema path. The plugins cached this on their own class; the
-    path is the same distinction expressed without one, so two plugins never
-    share an entry.
-    """
-    if not element_key:
-        return None
-    cache = _SCHEMA_FONT_SIZE_CACHE.get(schema_path)
-    if cache is None:
-        cache = {}
-        try:
-            import json
-            with open(schema_path) as fh:
-                schema = json.load(fh)
-            props = (schema.get('properties', {})
-                           .get('customization', {})
-                           .get('properties', {}))
-            for key, spec in props.items():
-                size = spec.get('properties', {}).get('font_size', {}).get('default')
-                if size is not None:
-                    cache[key] = int(size)
-        except Exception:
-            cache = {}
-        _SCHEMA_FONT_SIZE_CACHE[schema_path] = cache
-    return cache.get(element_key)
-
-
-def resolve_font_size(schema_path: str, element_config, element_key,
-                      default_size, font_name, aliases=None, grid_table=None):
-    """Size to render at: the user's choice, or a grid-snapped default.
-
-    A configured size counts as a real choice only when it differs from
-    the schema default. The web UI writes the whole schema default block
-    on every save, so "font_size == schema default" carries no intent and
-    would otherwise pin every install to an anti-aliased size forever.
-    """
-    configured = (element_config or {}).get('font_size')
-    if configured is not None:
-        try:
-            configured = int(configured)
-            if configured != schema_font_size(schema_path, element_key):
-                return configured
-        except (TypeError, ValueError):
-            pass
-    return crisp_size(font_name, default_size, aliases, grid_table)
-
-
-def unshare_element_fonts(logger, fonts):
-    """Give each colourable element its own face object.
-
-    The colour a draw gets is resolved from the face it was handed, and
-    several of these loaders legitimately hand one object to more than one
-    element -- a size resolver that lands two elements on the same face, a
-    fallback that fills every key from one default, football's narrowing
-    step that deliberately shrinks the clock along with the score. Sharing
-    the object makes the element ambiguous and the colour unresolvable.
-
-    Re-instantiating from the same path and size gives a distinct object
-    with identical metrics, so nothing about the rendering changes; only
-    the ability to tell two elements apart does. Faces that cannot be
-    rebuilt (a BDF loaded through freetype.Face, anything without a usable
-    path) are left shared, and their draws stay white as before.
-    """
-    try:
-        from PIL import ImageFont as _IF
-    except ImportError:  # pragma: no cover
-        return fonts
-    seen = {}
-    for key in ELEMENT_FOR_FONT:
-        font = fonts.get(key)
-        if font is None:
-            continue
-        if id(font) not in seen:
-            seen[id(font)] = key
-            continue
-        path, size = getattr(font, "path", None), getattr(font, "size", None)
-        if not path or not size:
-            continue
-        try:
-            fonts[key] = _IF.truetype(path, size)
-        except (OSError, ValueError, TypeError):
-            logger.debug(
-                "Could not un-share the %s face; it keeps the default colour", key)
-    return fonts

src/common/sports_game_renderer.py

@@ -1,261 +0,0 @@
-"""The scroll/Vegas card geometry the sports scoreboards all share.
-
-Eight scoreboards -- afl, baseball, basketball, football, hockey, lacrosse,
-nrl and soccer -- each carried their own ``game_renderer.py``. After the card
-helpers moved to ``src/common/sports_card.py`` the settings lookups were
-shared, but the *geometry* was not: nine methods that decide how wide the
-centre gap is, how much room a logo gets, and where an upcoming card's date
-and time land were still eight separate copies. Five were byte-identical
-across all eight plugins; the other four were identical in seven, with a
-different single outlier each time.
-
-That last detail is why this is a mixin rather than free functions. There is
-no per-sport branching to write -- baseball needs its own
-``_draw_upcoming_game_status`` and ``_logo_slot_width``, hockey its own
-``_upcoming_date_and_time``, football its own ``_score_reserve_width``, and
-every one of those is an ordinary override. The seven that agree inherit and
-say nothing.
-
-It is deliberately *only* a mixin: no ``__init__``, no state of its own. The
-plugins' constructors differ in six ways and none of that difference is worth
-unifying, so adoption is one line on the class statement plus deleting the
-methods that now come from here.
-
-What a host class must provide
-------------------------------
-Attributes: ``display_width``, ``display_height``, ``config``, ``fonts``,
-``logger``, ``_team_rankings_cache``.
-
-Methods: ``_draw_text_with_outline(draw, text, position, font, fill=None,
-outline_color=(0, 0, 0))`` -- the one hook whose body genuinely varies -- plus
-the ``sports_card`` delegations ``_scroll_card_option``,
-``_upcoming_center_mode``, ``_vs_text``, ``_element_color``,
-``_format_game_date`` and ``_format_game_time``.
-"""
-
-import math
-from typing import ClassVar, Dict, Tuple
-
-from PIL import Image, ImageDraw
-
-
-class SportsGameRendererMixin:
-    """Shared card geometry for the sports scoreboards. See module docstring."""
-
-    #: Centre strip as a fraction of card width, before clamping.
-    CENTER_GAP_RATIO: ClassVar[float] = 0.28
-    #: Clamp floor for the derived centre gap.
-    CENTER_GAP_MIN_PX: ClassVar[int] = 22
-    #: Clamp ceiling for the derived centre gap.
-    CENTER_GAP_MAX_PX: ClassVar[int] = 40
-    #: Breathing room kept between the score and each logo.
-    _SCORE_LOGO_GUTTER_PX: ClassVar[int] = 4
-    #: Widest score the centre strip must fit. Leagues that can reach three
-    #: digits a side override this with "000-000".
-    _SCORE_PROBE: ClassVar[str] = "00-00"
-
-    # ---- geometry ------------------------------------------------------
-
-    # Non-finite settings are rejected before any int()/round(): "inf" reaches
-    # these from config as a float or a string, passes an `isinstance` plus
-    # `>= 0` check unharmed, and then raises OverflowError out of int() --
-    # which the old `except (TypeError, ValueError)` did not catch, so it
-    # aborted the whole card render. Present in all eight plugins before this
-    # moved to the core; fixing it here fixes it in all eight.
-
-    def _score_reserve_width(self) -> int:
-        """Centre strip the score actually needs, measured rather than assumed.
-
-        The gap was derived from the card width alone (width x
-        CENTER_GAP_RATIO, clamped to CENTER_GAP_MAX_PX) while the score's size
-        comes from config and the element-style resolver. Nothing compared the
-        two, so any score wider than the clamp was drawn over the logos.
-        Measuring it keeps the strip wide enough for whatever font is in play.
-        """
-        try:
-            probe = ImageDraw.Draw(Image.new("RGB", (4, 4)))
-            width = probe.textlength(self._SCORE_PROBE, font=self.fonts['score'])
-            return int(width) + 2 * self._SCORE_LOGO_GUTTER_PX
-        except Exception:
-            self.logger.debug("Score reserve measurement failed", exc_info=True)
-            return 0
-
-    def _center_gap_width(self) -> int:
-        """Width of the middle strip kept clear of logos.
-
-        ``scroll_card.center_gap`` pins it outright; otherwise it scales with
-        the card width between the configurable min and max. 0 restores
-        edge-to-edge logos.
-        """
-        configured = self._scroll_card_option("center_gap")
-        if (isinstance(configured, (int, float))
-                and math.isfinite(configured) and configured >= 0):
-            return int(configured)
-        ratio = self._scroll_card_option("center_gap_ratio", self.CENTER_GAP_RATIO)
-        low = self._scroll_card_option("center_gap_min", self.CENTER_GAP_MIN_PX)
-        high = self._scroll_card_option("center_gap_max", self.CENTER_GAP_MAX_PX)
-        try:
-            ratio, low, high = float(ratio), float(low), float(high)
-            if not (math.isfinite(ratio) and math.isfinite(low)
-                    and math.isfinite(high)):
-                return self.CENTER_GAP_MIN_PX
-            scaled = round(self.display_width * ratio)
-            derived = int(max(int(low), min(int(high), scaled)))
-            # A strip narrower than the score is the bug, not a style choice.
-            # An explicit ``center_gap`` is still honoured above, including 0.
-            return max(derived, self._score_reserve_width())
-        except (TypeError, ValueError, OverflowError):
-            return self.CENTER_GAP_MIN_PX
-
-    def _logo_slot_width(self) -> int:
-        """Per-side logo slot, leaving the center gap clear.
-
-        No longer capped at display_height: the card is sized as two
-        full-height logos plus the measured gap, so what is left after the gap
-        is exactly the logo's share. The cap was what froze the logos at 46px
-        on the old flat 128px card.
-        """
-        available = (self.display_width - self._center_gap_width()) // 2
-        return max(8, available)
-
-    def _logo_cache_key(self, name: str) -> str:
-        """Cache key scoped to the logo slot.
-
-        One cache dict is shared by renderers built for different card widths,
-        so a logo sized for a wide slot must not be handed to a narrow one.
-        """
-        return f"{name}@{self._logo_slot_width()}x{self.display_height}"
-
-    def _layout_offset(self, element: str, axis: str, default: int = 0) -> int:
-        """X/Y nudge for one element, from customization.layout.
-
-        Same block the full-screen scorebug reads (sports.py
-        _get_layout_offset), so a nudge configured in the web UI now moves
-        the element on the scroll/Vegas card too -- previously the schema
-        advertised these offsets but this renderer ignored them.
-        """
-        try:
-            layout = (self.config or {}).get("customization", {}).get("layout", {})
-            value = (layout.get(element) or {}).get(axis, default)
-            if isinstance(value, bool):
-                return default
-            if isinstance(value, (int, float)):
-                return int(value) if math.isfinite(value) else default
-            if isinstance(value, str):
-                parsed = float(value)
-                return int(parsed) if math.isfinite(parsed) else default
-        except (TypeError, ValueError, OverflowError):
-            pass
-        return default
-
-    # ---- upcoming cards ------------------------------------------------
-
-    def _upcoming_date_and_time(self, game: Dict) -> Tuple[str, str]:
-        """(date, time) for an upcoming card, from the extractor's flat keys."""
-        return (
-            str(game.get("game_date", "") or ""),
-            str(game.get("game_time", "") or ""),
-        )
-
-    def _draw_upcoming_center(self, draw: "ImageDraw.ImageDraw", game: Dict) -> None:
-        """Draw the middle of an upcoming card.
-
-        Never a score: an upcoming game has not started, so the extractor's
-        0-0 is noise. Either the VS text (default), the date and time stacked,
-        or nothing at all.
-        """
-        mode = self._upcoming_center_mode()
-        if mode == "none":
-            return
-
-        if mode == "vs":
-            vs_text = self._vs_text()
-            if not vs_text:
-                return
-            vs_width = draw.textlength(vs_text, font=self.fonts['score'])
-            vs_x = (self.display_width - vs_width) // 2 + self._layout_offset('score', 'x_offset')
-            vs_y = (self.display_height // 2) - 3 + self._layout_offset('score', 'y_offset')
-            self._draw_text_with_outline(
-                draw, vs_text, (vs_x, vs_y), self.fonts['score'],
-                fill=self._element_color('score_text')
-            )
-            return
-
-        date_text, time_text = self._upcoming_date_and_time(game)
-        lines = []
-        if self._scroll_card_option("show_date", True):
-            lines.append(self._format_game_date(date_text, game))
-        if self._scroll_card_option("show_time", True):
-            lines.append(self._format_game_time(time_text))
-        lines = [t for t in lines if t]
-        if not lines:
-            return
-        font = self.fonts.get('detail') or self.fonts['time']
-        line_h = 7
-        top = (self.display_height // 2) - (len(lines) * line_h) // 2
-        top += self._layout_offset('score', 'y_offset')
-        for i, line in enumerate(lines):
-            width = draw.textlength(line, font=font)
-            x = (self.display_width - width) // 2 + self._layout_offset('score', 'x_offset')
-            self._draw_text_with_outline(
-                draw, line, (x, top + i * line_h), font,
-                fill=self._element_color('detail_text')
-            )
-
-    def _draw_upcoming_game_status(self, draw: "ImageDraw.ImageDraw", game: Dict) -> None:
-        """Draw the date and time around an upcoming card.
-
-        Time top and date bottom by default; scroll_card.swap_date_time puts
-        the date on top instead. Skipped when the pair is stacked in the
-        middle, which would otherwise print them twice.
-        """
-        if self._upcoming_center_mode() == "date_time":
-            return
-
-        date_raw, time_raw = self._upcoming_date_and_time(game)
-        date_text = (self._format_game_date(date_raw, game)
-                     if self._scroll_card_option("show_date", True) else "")
-        time_text = (self._format_game_time(time_raw)
-                     if self._scroll_card_option("show_time", True) else "")
-
-        if self._scroll_card_option("swap_date_time", False):
-            top_text, top_el, bottom_text, bottom_el = (
-                date_text, 'date', time_text, 'time')
-            top_font = self.fonts.get('detail') or self.fonts['time']
-            bottom_font = self.fonts['time']
-            top_color, bottom_color = 'detail_text', 'period_text'
-        else:
-            top_text, top_el, bottom_text, bottom_el = (
-                time_text, 'time', date_text, 'date')
-            top_font = self.fonts['time']
-            bottom_font = self.fonts.get('detail') or self.fonts['time']
-            top_color, bottom_color = 'period_text', 'detail_text'
-
-        if top_text:
-            top_width = draw.textlength(top_text, font=top_font)
-            top_x = (self.display_width - top_width) // 2 + self._layout_offset(top_el, 'x_offset')
-            top_y = 1 + self._layout_offset(top_el, 'y_offset')
-            self._draw_text_with_outline(
-                draw, top_text, (top_x, top_y), top_font,
-                fill=self._element_color(top_color)
-            )
-
-        if bottom_text:
-            bottom_width = draw.textlength(bottom_text, font=bottom_font)
-            bottom_x = ((self.display_width - bottom_width) // 2
-                        + self._layout_offset(bottom_el, 'x_offset'))
-            # Measured, not a fixed -7: the detail font is 6px in most plugins
-            # but 10px in soccer and nrl, where "Sep 19" ran past the card.
-            ink_bottom = draw.textbbox((0, 0), bottom_text, font=bottom_font)[3]
-            bottom_y = (max(0, self.display_height - ink_bottom - 1)
-                        + self._layout_offset(bottom_el, 'y_offset'))
-            self._draw_text_with_outline(
-                draw, bottom_text, (bottom_x, bottom_y), bottom_font,
-                fill=self._element_color(bottom_color)
-            )
-
-    # ---- rankings ------------------------------------------------------
-
-    def set_rankings_cache(self, rankings: Dict[str, int]) -> None:
-        """Set the team rankings cache for display."""
-        self._team_rankings_cache = rankings

src/display_controller.py

@@ -2405,6 +2405,7 @@ class DisplayController:
                             )
 
                             while True:
+                                _frame_start = time.perf_counter()
                                 try:
                                     with self._display_lock_or_skip(plugin_id) as can_display:
                                         if can_display:
@@ -2425,11 +2426,26 @@ class DisplayController:
                                 # Multi-display sync: send follower frame after each render
                                 self._send_follower_frame(manager_to_display)
 
-                                time.sleep(display_interval)
                                 self._tick_plugin_updates()
                                 self._poll_on_demand_requests()
                                 self._check_on_demand_expiration()
 
+                                # Pace to the frame deadline rather than sleeping a flat
+                                # interval on top of the work. display() has already
+                                # blocked on the panel's vsync by this point, so an
+                                # unconditional sleep is added to a wait that already
+                                # happened. Measured on a 2x128x64 chain at
+                                # limit_refresh_rate_hz=100: ~4ms of render plus a flat
+                                # 8ms put each iteration at ~12ms against a 10ms refresh
+                                # grid, so every swap missed a refresh and the loop
+                                # settled at 50fps where display_interval asks for 125 --
+                                # and with zero headroom, ~14% of frames slipped a
+                                # further refresh, which is what reads as scroll stutter.
+                                _remaining = display_interval - (time.perf_counter() - _frame_start)
+                                # Yield even when the frame overran its budget, so plugin
+                                # update threads and the web UI are not starved of the GIL.
+                                time.sleep(_remaining if _remaining > 0 else 0.001)
+
                                 if self.current_display_mode != active_mode:
                                     logger.debug("Mode changed during high-FPS loop, breaking early")
                                     break

src/display_manager.py

@@ -240,6 +240,14 @@ class DisplayManager:
         self._update_lock = threading.RLock()
         
         # Scrolling state tracking for graceful updates
+        # How many panel refreshes each pushed frame is held for. 1 means a new
+        # frame every refresh. Higher values are how a scroll runs slower than
+        # one pixel per refresh WITHOUT fractional pixel positions: the panel
+        # keeps refreshing at full rate (so flicker is unchanged) but motion
+        # advances a whole pixel every Nth refresh instead of every one.
+        # See src/common/scroll_config.py and scripts/scroll_speeds.py.
+        self._frame_hold = 1
+
         self._scrolling_state = {
             'is_scrolling': False,
             'last_scroll_activity': 0,
@@ -768,16 +776,33 @@ class DisplayManager:
                     return  # Skip hardware write — content is being captured off-screen
 
                 digest = None
+                frame_checksum = None
                 if self._dirty_tracking_enabled:
                     try:
                         brightness = getattr(self.matrix, 'brightness', None)
                     except AttributeError:
                         brightness = None
-                    digest = (zlib.adler32(self.image.tobytes()), brightness)
+                    frame_checksum = zlib.adler32(self.image.tobytes())
-                    if digest == self._last_pushed_digest:
+                    digest = (frame_checksum, brightness)
+                    if digest == self._last_pushed_digest and not self.is_currently_scrolling():
                         # Nothing changed since the last push — the panel is
                         # already showing exactly this frame.
-                        self._write_snapshot_if_due()
+                        #
+                        # Never taken mid-scroll, and that exception is the
+                        # point. SwapOnVSync is what paces the render loop, so
+                        # skipping it also skips the wait: a duplicate frame
+                        # returns in ~8ms instead of ~10ms on a 100Hz panel,
+                        # advances only 0.8px instead of 1.0px, and so makes
+                        # the *next* frame more likely to repeat as well. That
+                        # is self-sustaining -- measured at ~20% duplicate
+                        # frames mid-scroll on the odds ticker, against
+                        # essentially zero on a lighter plugin with identical
+                        # scroll settings. Swapping an identical frame costs
+                        # one canvas copy and keeps the loop locked to the
+                        # panel; falling out of that lock costs smooth motion.
+                        # Static content is unaffected: is_currently_scrolling()
+                        # expires on its own inactivity threshold.
+                        self._write_snapshot_if_due(frame_checksum)
                         return
 
                 # Copy the current image to the offscreen canvas. In double-sided
@@ -787,8 +812,10 @@ class DisplayManager:
                 else:
                     self.offscreen_canvas.SetImage(self.image)
 
-                # Swap buffers immediately
+                # Swap buffers immediately. framerate_fraction holds the frame
-                self.matrix.SwapOnVSync(self.offscreen_canvas)
+                # for N refreshes; SwapOnVSync blocks for all of them, which is
+                # what paces the render loop to the chosen frame rate.
+                self.matrix.SwapOnVSync(self.offscreen_canvas, self._frame_hold)
 
                 # Swap our canvas references
                 self.offscreen_canvas, self.current_canvas = self.current_canvas, self.offscreen_canvas
@@ -796,7 +823,7 @@ class DisplayManager:
                 self._last_pushed_digest = digest
 
                 # Write a snapshot for the web preview (throttled)
-                self._write_snapshot_if_due()
+                self._write_snapshot_if_due(frame_checksum)
         except Exception as e:
             logger.error(f"Error updating display: {e}")
 
@@ -1274,12 +1301,65 @@ class DisplayManager:
         
         return dt.strftime(f"%b %-d{suffix}") 
 
-    def set_scrolling_state(self, is_scrolling: bool):
+    @property
-        """Set the current scrolling state. Call this when a display starts/stops scrolling."""
+    def refresh_hz(self) -> float:
+        """The panel's refresh rate in Hz, from the hardware config.
+
+        The authoritative place to ask, because a plugin only receives its own
+        config section and cannot see display.hardware. Scroll pacing needs
+        this: the speeds a panel can show in whole pixels are refresh_hz
+        divided by the frame hold, so getting it wrong silently produces
+        fractional-pixel motion. See src/common/scroll_config.py.
+
+        Note this is the configured *cap*, not necessarily what the panel
+        achieves -- scripts/scroll_speeds.py --measure reports the real rate.
+        """
+        hardware = (self.config.get('display') or {}).get('hardware') or {}
+        try:
+            value = float(hardware.get('limit_refresh_rate_hz') or 0)
+        except (TypeError, ValueError):
+            value = 0.0
+        return value if value > 0 else 100.0
+
+    def set_frame_hold(self, refreshes: int) -> None:
+        """Hold each pushed frame for this many panel refreshes (>=1).
+
+        Set by the scroll configuration so a plugin can run at, say, 50px/s on
+        a 100Hz panel as one whole pixel every second refresh, rather than half
+        a pixel every refresh (which has to be blended or repeated unevenly).
+
+        Reset to 1 whenever scrolling stops, so one plugin's pacing cannot
+        leak into the next thing on screen.
+        """
+        try:
+            value = int(refreshes)
+        except (TypeError, ValueError):
+            logger.warning("Ignoring unusable frame hold: %r", refreshes)
+            return
+        self._frame_hold = max(1, min(255, value))
+
+    def set_scrolling_state(self, is_scrolling: bool, frame_hold: int = 1):
+        """Set the current scrolling state, and this scroll's frame pacing.
+
+        Call this when a display starts or stops scrolling. ``frame_hold`` is
+        how many panel refreshes each frame is held for -- 2 gives one whole
+        pixel every second refresh, which is how a scroll runs at half the
+        refresh rate without fractional pixel positions.
+
+        The hold is set here rather than once at plugin construction because
+        it must not outlive the scroll that asked for it: plugins share one
+        display manager, so a hold left set by whoever scrolled last would
+        silently re-pace the next plugin. Passing it alongside the state makes
+        the lifetime exactly the scroll, and the default of 1 means any caller
+        that does not care gets a new frame every refresh.
+        """
         current_time = time.time()
         self._scrolling_state['is_scrolling'] = is_scrolling
         if is_scrolling:
             self._scrolling_state['last_scroll_activity'] = current_time
+            self.set_frame_hold(frame_hold)
+        else:
+            self._frame_hold = 1
         logger.debug(f"Scrolling state set to: {is_scrolling}")
 
     def is_currently_scrolling(self) -> bool:
@@ -1410,11 +1490,20 @@ class DisplayManager:
                 self._viewer_fresh = False
         return self._viewer_fresh
 
-    def _write_snapshot_if_due(self) -> None:
+    def _write_snapshot_if_due(self, frame_checksum: Optional[int] = None) -> None:
         """Mirror the current frame to the preview snapshot when the policy
         says it's worth it — see src/common/snapshot_policy.py. Unchanged
         frames are never re-encoded; without viewers the cadence drops to
-        the idle keepalive."""
+        the idle keepalive.
+
+        Args:
+            frame_checksum: adler32 of the current frame, when the caller has
+                already computed one. Dirty tracking checksums every frame a
+                few lines above the call site, and re-deriving it here meant a
+                second tobytes() plus a second pass over the whole framebuffer
+                on every single frame — ~0.17ms per frame of the two combined
+                at 256x64, paid 100 times a second to reach the same number.
+        """
         try:
             now = time.time()
             viewer_fresh = self._viewer_is_fresh(now)
@@ -1424,7 +1513,8 @@ class DisplayManager:
                 self._last_snapshot_ts = 0.0
             self._viewer_was_fresh = viewer_fresh
 
-            digest = zlib.adler32(self.image.tobytes())
+            digest = (frame_checksum if frame_checksum is not None
+                      else zlib.adler32(self.image.tobytes()))
             action = snapshot_policy.decide(
                 now, self._last_snapshot_ts, self._last_snapshot_touch_ts,
                 viewer_fresh, digest != self._last_snapshot_digest)

src/logo_downloader.py

@@ -14,7 +14,6 @@ import json
 from typing import Dict, List, Optional, Tuple
 from pathlib import Path
 from PIL import Image, ImageDraw, ImageFont
-from PIL.PngImagePlugin import PngInfo
 from requests.adapters import HTTPAdapter
 from urllib3.util.retry import Retry
 from src.common.permission_utils import (
@@ -26,96 +25,6 @@ from src.common.permission_utils import (
 
 logger = logging.getLogger(__name__)
 
-#: PNG text key stamped into a generated placeholder so a later run can tell it
-#: apart from a real logo that happens to be small.
-PLACEHOLDER_MARKER = "ledmatrix_placeholder"
-
-#: Geometry of a generated placeholder, used to recognise ones written before
-#: the marker existed. Those are already on users' disks and would otherwise
-#: never be retried.
-PLACEHOLDER_SIZE = (64, 64)
-PLACEHOLDER_BG = (100, 100, 100, 255)
-
-#: How long a placeholder is trusted before the real logo is attempted again.
-#: A placeholder means the download failed, and download failures are usually
-#: transient (no network at boot, ESPN blipping). Retrying every frame would
-#: hammer the API from a Pi that is also driving a panel; never retrying leaves
-#: the team a grey box forever, which is the bug this exists to avoid.
-PLACEHOLDER_RETRY_SECONDS = 6 * 60 * 60
-
-
-def is_placeholder_logo(filepath: Path) -> bool:
-    """True if the file at ``filepath`` is a generated placeholder, not a logo.
-
-    Checks the marker first, then falls back to matching the placeholder's
-    exact geometry and background colour so files written before the marker was
-    introduced are still recognised.
-    """
-    try:
-        with Image.open(filepath) as img:
-            if img.info.get(PLACEHOLDER_MARKER):
-                return True
-            if img.size != PLACEHOLDER_SIZE:
-                return False
-            return img.convert("RGBA").getpixel((0, 0)) == PLACEHOLDER_BG
-    except Exception:
-        # Unreadable file: not provably a placeholder, and the caller's own
-        # error handling is better placed to deal with it.
-        return False
-
-
-def should_attempt_download(filepath: Path, force_download: bool = False) -> bool:
-    """Whether a real logo is worth (re)fetching for ``filepath``.
-
-    True when nothing is there, when the caller forced it, or when what is
-    there is a placeholder old enough to retry. A *fresh* placeholder says a
-    download just failed, so retrying it immediately would hammer the API for
-    a result that is very unlikely to have changed.
-    """
-    if force_download or not filepath.exists():
-        return True
-    if not is_placeholder_logo(filepath):
-        return False
-    age = placeholder_age_seconds(filepath)
-    return age is None or age >= PLACEHOLDER_RETRY_SECONDS
-
-
-def refresh_placeholder_timestamp(filepath: Path) -> bool:
-    """Restamp a placeholder so a failed retry restarts the back-off clock.
-
-    Without this a stale placeholder stays stale: every later call sees an
-    expired timestamp, retries, fails, and leaves the timestamp untouched --
-    which is a download attempt per call, the opposite of what the back-off is
-    for.
-    """
-    try:
-        if not is_placeholder_logo(filepath):
-            return False
-        metadata = PngInfo()
-        metadata.add_text(PLACEHOLDER_MARKER, str(time.time()))
-        with Image.open(filepath) as img:
-            img.copy().save(filepath, "PNG", pnginfo=metadata)
-        return True
-    except Exception:
-        logger.debug("Could not refresh placeholder timestamp for %s", filepath,
-                     exc_info=True)
-        return False
-
-
-def placeholder_age_seconds(filepath: Path) -> Optional[float]:
-    """Seconds since a placeholder was written, or None if unknown."""
-    try:
-        with Image.open(filepath) as img:
-            stamped = img.info.get(PLACEHOLDER_MARKER)
-        if stamped and stamped != "1":
-            return max(0.0, time.time() - float(stamped))
-    except Exception:
-        pass
-    try:
-        return max(0.0, time.time() - filepath.stat().st_mtime)
-    except OSError:
-        return None
-
 class LogoDownloader:
     """Centralized logo downloader for team logos from ESPN API."""
     
@@ -590,10 +499,8 @@ class LogoDownloader:
             filename = f"{self.normalize_abbreviation(abbreviation)}.png"
             filepath = Path(logo_dir) / filename
             
-            # A placeholder does not count as existing -- it is a previous
+            # Skip if already exists and not forcing download
-            # failure, and a bulk pass is exactly where it should get another
+            if filepath.exists() and not force_download:
-            # chance, subject to the same back-off as everywhere else.
-            if not should_attempt_download(filepath, force_download):
                 logger.debug(f"Skipping {display_name}: {filename} already exists")
                 continue
             
@@ -652,9 +559,8 @@ class LogoDownloader:
             filename = f"{self.normalize_abbreviation(abbreviation)}.png"
             filepath = Path(logo_dir) / filename
             
-            # Same eligibility rule as every other download site: a stale
+            # Skip if already exists and not forcing download
-            # placeholder is a failed download, not a logo.
+            if filepath.exists() and not force_download:
-            if not should_attempt_download(filepath, force_download):
                 logger.debug(f"Skipping {display_name} ({category}, {conference}): {filename} already exists")
                 continue
             
@@ -768,16 +674,11 @@ class LogoDownloader:
                 # Fallback without font
                 draw.text((16, 24), text, fill=(255, 255, 255, 255))
             
-            # Stamp it so a later run can tell this apart from a real logo and
+            logo.save(filepath)
-            # retry the download, instead of treating the file's existence as
+            
-            # proof the logo was fetched.
-            metadata = PngInfo()
-            metadata.add_text(PLACEHOLDER_MARKER, str(time.time()))
-            logo.save(filepath, "PNG", pnginfo=metadata)
-
             # Set proper file permissions after saving
             ensure_file_permissions(filepath, get_assets_file_mode())
-
+            
             logger.info(f"Created placeholder logo for {team_abbreviation} at {filepath}")
             return True
             
@@ -869,18 +770,9 @@ def download_missing_logo(league: str, team_id: str, team_abbreviation: str, log
     # Use the exact filepath that was passed in (respects config settings)
     filepath = logo_path
     
-    if filepath.exists() and not should_attempt_download(filepath):
+    if filepath.exists():
-        # Either a real logo, or a placeholder too fresh to be worth retrying.
         logger.debug(f"Logo already exists for {team_abbreviation} ({league})")
         return True
-    if filepath.exists():
-        # A placeholder is a *failed* download wearing the real logo's
-        # filename. Treating it as "already exists" is what pinned a team to a
-        # grey box permanently after one transient failure.
-        logger.info(
-            "Logo for %s (%s) is a placeholder from a failed download; "
-            "retrying the real logo", team_abbreviation, league,
-        )
     
     # Try to download the real logo first
     logger.info(f"Attempting to download logo for {team_abbreviation} from {league}")

src/plugin_system/store_manager.py

@@ -1602,26 +1602,6 @@ class PluginStoreManager:
                     'error': f'Manifest missing required fields: {", ".join(missing_fields)}'
                 }
             
-            # Refuse a plugin that needs a newer core than this one, exactly as
-            # _install_plugin_impl does after its download. Sideloading is an
-            # explicit act rather than an automatic store update, but the floor
-            # is not advice about intent -- it is a statement that the plugin
-            # cannot run here, and letting it through produces the same silent
-            # PluginState.ERROR at load. This was the last of the three routes
-            # in that skipped the check.
-            #
-            # Before the move, so the `finally` below removes the temp tree and
-            # nothing half-installed is left behind.
-            from src import __version__ as core_version
-            from src.plugin_system import compatibility
-
-            compatible, reason = compatibility.check(manifest, core_version)
-            if not compatible:
-                self.logger.error(
-                    "Refusing to install %s from %s: %s",
-                    plugin_id, repo_url, reason)
-                return {'success': False, 'error': reason}
-
             # Validate version fields consistency (warnings only, not required)
             validation_errors = self._validate_manifest_version_fields(manifest)
             if validation_errors:
@@ -2603,85 +2583,6 @@ class PluginStoreManager:
             self.logger.error(f"Error uninstalling plugin {plugin_id}: {e}")
             return False
     
-    def _gate_pulled_commit(self, plugin_id: str, plugin_path: Path,
-                            previous_sha: Optional[str]) -> bool:
-        """Apply the compatibility gate to a commit that arrived via git pull.
-
-        Every other route into an installed plugin goes through
-        ``install_plugin``, which gates in ``_install_plugin_impl``. This one
-        did not: a ``git pull`` could deliver a manifest flooring above this
-        core and nothing would notice until the plugin failed to load, which
-        surfaces as one line in the journal and a scoreboard that silently
-        stopped appearing.
-
-        Checked after the pull rather than before it, for the same reason
-        ``_install_plugin_impl`` checks after the download: the registry
-        carries no compatibility field, so the incoming floor is only knowable
-        once the new commit is on disk.
-
-        Undone with ``git reset --hard`` rather than by removing the directory.
-        This is a live checkout, the previous commit is still in the object
-        store, and the reset leaves the user on the exact version they were
-        already running -- the same promise ``_reinstall_with_rollback`` makes,
-        reached by the means this path actually has. It is also the gentler
-        option: no window in which the plugin directory does not exist, and no
-        ``.standalone-backup-`` debris if the process dies mid-way.
-
-        A manifest that cannot be read is not evidence of incompatibility, so
-        it allows. ``compatibility.check`` refuses only on evidence for the
-        same reason: a wrong refusal breaks a working install, while a wrong
-        allowance degrades to exactly the behaviour this path had before the
-        gate existed.
-        """
-        manifest_path = plugin_path / "manifest.json"
-        try:
-            with open(manifest_path, 'r', encoding='utf-8') as mf:
-                manifest = json.load(mf)
-        except (OSError, ValueError) as e:
-            self.logger.warning(
-                "Could not read %s after updating %s (%s); allowing the "
-                "update, as an unreadable manifest declares no floor",
-                manifest_path, plugin_id, e)
-            return True
-
-        from src import __version__ as core_version
-        from src.plugin_system import compatibility
-
-        compatible, reason = compatibility.check(manifest, core_version)
-        if compatible:
-            return True
-
-        self.logger.error("Refusing the update to %s: %s", plugin_id, reason)
-
-        if not previous_sha:
-            self.logger.error(
-                "Cannot roll %s back: the commit it was on before the pull is "
-                "unknown. It is now on a version this core cannot run — "
-                "reinstall it from the plugin store.", plugin_id)
-            return False
-
-        # Safe by construction: update_plugin returns before pulling unless the
-        # tree was clean or successfully stashed, so there are no uncommitted
-        # tracked edits for --hard to discard. The stash is not popped on the
-        # success path either, so the reset leaves the working tree exactly
-        # where a successful pull would have. Say "commit", not "changes".
-        reset = subprocess.run(
-            ['git', '-C', str(plugin_path), 'reset', '--hard', previous_sha],
-            capture_output=True, text=True, timeout=60, check=False)
-        if reset.returncode != 0:
-            self.logger.error(
-                "CRITICAL: could not roll %s back to commit %s: %s. It is left "
-                "on a version this core cannot run; "
-                "`git -C %s reset --hard %s` restores it.",
-                plugin_id, previous_sha[:7],
-                (reset.stderr or reset.stdout or '').strip(),
-                plugin_path, previous_sha)
-        else:
-            self.logger.info(
-                "Rolled %s back to commit %s; it stays on the version it was "
-                "already running.", plugin_id, previous_sha[:7])
-        return False
-
     def _reinstall_with_rollback(self, plugin_id: str, plugin_path: Path) -> bool:
         """Replace an installed plugin with a fresh install, atomically.
 
@@ -2959,8 +2860,6 @@ class PluginStoreManager:
                         status_result = type('obj', (object,), {'stdout': '', 'stderr': 'Status check timed out'})()
                     
                     stash_info = ""
-                    # Whether the pull can be undone without destroying work.
-                    tree_is_recoverable = not has_changes
                     if has_changes:
                         self.logger.info(f"Stashing local changes in {plugin_id} before update")
                         try:
@@ -2974,37 +2873,12 @@ class PluginStoreManager:
                             )
                             if stash_result.returncode == 0:
                                 stash_info = " (local changes were stashed)"
-                                tree_is_recoverable = True
                                 self.logger.info(f"Stashed local changes (including untracked files) for {plugin_id}")
                             else:
                                 self.logger.warning(f"Failed to stash local changes for {plugin_id}: {stash_result.stderr}")
                         except subprocess.TimeoutExpired:
                             self.logger.warning(f"Stash operation timed out for {plugin_id}, proceeding with pull")
 
-                    # Do not pull what cannot be un-pulled.
-                    #
-                    # The compatibility gate below can refuse the commit this
-                    # pull brings down, and its only way back is `git reset
-                    # --hard`, which discards uncommitted tracked edits. Those
-                    # edits are exactly what the stash above exists to protect,
-                    # so a stash that failed or timed out leaves the rollback
-                    # unable to run without destroying them.
-                    #
-                    # A pull does not necessarily refuse on a dirty tree -- git
-                    # merges happily as long as the incoming commit touches
-                    # different files -- so without this the update would
-                    # succeed, the gate would refuse, and the reset would take
-                    # the user's work with it. Refusing here costs an update in
-                    # a case that already went wrong; the alternative costs
-                    # data.
-                    if not tree_is_recoverable:
-                        self.logger.error(
-                            "Refusing to update %s: it has local changes that could "
-                            "not be stashed, and an incompatible update could then "
-                            "only be rolled back by discarding them. Commit or stash "
-                            "them by hand, then update.", plugin_id)
-                        return False
-
                     # Pull from the determined remote branch
                     self.logger.info(f"Pulling from origin/{remote_pull_branch} for {plugin_id}...")
                     pull_result = subprocess.run(
@@ -3027,14 +2901,6 @@ class PluginStoreManager:
                     elif updated_sha:
                         self.logger.info(f"Plugin {plugin_id} updated to commit {updated_sha[:7]}{stash_info}")
 
-                    # The install gate, at the only point on this path where
-                    # it can be answered. Every other route in goes through
-                    # install_plugin, which gates in _install_plugin_impl; this
-                    # one did not, so a pull could deliver a manifest flooring
-                    # above this core and nothing would notice.
-                    if not self._gate_pulled_commit(plugin_id, plugin_path, local_sha):
-                        return False
-
                     self._install_dependencies(plugin_path)
                     return True
 

src/plugin_system/testing/visual_display_manager.py

@@ -503,9 +503,18 @@ class VisualTestDisplayManager:
     # Scrolling state (no-op interface compat)
     # ------------------------------------------------------------------
 
-    def set_scrolling_state(self, is_scrolling: bool):
+    def set_scrolling_state(self, is_scrolling: bool, frame_hold: int = 1):
-        """Set the current scrolling state (no-op for testing)."""
+        """Set the current scrolling state (no-op for testing).
+
+        ``frame_hold`` mirrors the DisplayManager signature this change adds.
+        The two are kept in step deliberately: a double that accepts arguments
+        production does not lets a call pass every harness run and then raise
+        TypeError on the panel, and a double that lacks one production has
+        fails every render of a plugin that legitimately paces its scroll.
+        Plugins begin passing it in ledmatrix-plugins#462.
+        """
         self._scrolling_state['is_scrolling'] = is_scrolling
+        self._scrolling_state['frame_hold'] = frame_hold
         if is_scrolling:
             self._scrolling_state['last_scroll_activity'] = time.time()
 

test/test_background_payload_release.py

@@ -23,14 +23,8 @@ it only in passing before reading the cache back.
 Requests submitted *without* a callback keep their payload: polling
 get_result() is then the only way to collect it, so releasing would break that
 contract.
-
-And the release must happen after EVERY callback, not after each one. Callers
-that joined an in-flight fetch share a single FetchResult, so releasing per
-delivery strips the payload out from under everyone still queued -- see
-TestJoinersAllGetTheData.
 """
 
-import threading
 import time
 import pytest
 from unittest.mock import MagicMock, Mock, patch
@@ -191,90 +185,3 @@ class TestCacheHitPath:
             cache_key="nfl_2026",
         )
         assert service.get_result(req_id).data == PAYLOAD
-
-
-class TestJoinersAllGetTheData:
-    """Deduplicated callers share one FetchResult; releasing between them
-    empties it for the rest.
-
-    Not a corner case. A sport's recent, upcoming and live managers all ask for
-    the same season schedule, so the second and third are joiners on almost
-    every cycle. Releasing inside the delivery loop handed the payload to
-    whichever ran first and gave the others `result.data is None`.
-
-    The consequence was worse than a quiet degradation, because consumers do
-    `result.data.get('events')`: they raised AttributeError, the delivery loop
-    caught it, and the whole failure surfaced as a single
-    "Error in callback for request ..." line while that manager silently never
-    received its schedule.
-    """
-
-    class _BlockingSession:
-        """Holds the fetch open so a second submit lands while in flight."""
-
-        def __init__(self):
-            self.release = threading.Event()
-            self.started = threading.Event()
-
-        def get(self, *a, **k):
-            self.started.set()
-            self.release.wait(timeout=5)
-            return _resp()
-
-    def test_every_joiner_is_handed_the_payload(self, service):
-        session = self._BlockingSession()
-        seen = {}
-
-        def record(name):
-            # Read it the way the sport managers do. `result.data['events']`
-            # would raise TypeError on None; `.get` raises AttributeError,
-            # which is the error actually seen in the field.
-            def cb(result):
-                seen[name] = result.data.get('events') if result.data else None
-            return cb
-
-        with patch.object(service, "session", session):
-            first = service.submit_fetch_request(
-                sport="nhl", year=2026, url="https://x/s", cache_key="nhl_2026",
-                callback=record("first"), max_retries=0)
-            assert session.started.wait(timeout=5)
-
-            joined = service.submit_fetch_request(
-                sport="nhl", year=2026, url="https://x/s", cache_key="nhl_2026",
-                callback=record("second"), max_retries=0)
-            # Without coalescing these are two independent fetches that each
-            # own their result, and the test proves nothing about sharing.
-            assert joined == first, "the joiner should share the in-flight id"
-
-            session.release.set()
-            _wait(service, first)
-
-        deadline = time.time() + 5
-        while len(seen) < 2 and time.time() < deadline:
-            time.sleep(0.02)
-
-        assert set(seen) == {"first", "second"}, f"both must be called, got {seen}"
-        for name, events in seen.items():
-            assert events is not None, (
-                f"{name!r} was handed a released payload: the result was "
-                f"emptied before every callback had been delivered")
-            assert len(events) == 50, f"{name!r} got {events!r}"
-
-    def test_the_payload_is_still_released_once_they_have_all_had_it(self, service):
-        """The memory fix must survive the ordering fix."""
-        session = self._BlockingSession()
-
-        with patch.object(service, "session", session):
-            first = service.submit_fetch_request(
-                sport="nhl", year=2026, url="https://x/s", cache_key="nhl_2026",
-                callback=lambda r: None, max_retries=0)
-            assert session.started.wait(timeout=5)
-            service.submit_fetch_request(
-                sport="nhl", year=2026, url="https://x/s", cache_key="nhl_2026",
-                callback=lambda r: None, max_retries=0)
-            session.release.set()
-            _wait_for_release(service, first)
-
-        stored = service.get_result(first)
-        assert stored is not None and stored.data is None, (
-            "the payload must still be dropped once every callback has run")

test/test_cache_nonfinite_floats.py

@@ -0,0 +1,158 @@
+"""Non-finite floats round-trip identically with and without orjson.
+
+JSON has no NaN or Infinity. The stdlib emits them anyway as an extension;
+orjson refuses to and writes null. Cache files outlive the decision of which
+encoder is installed, so both halves of that gap are pinned here:
+
+  * writing -- installing orjson must not silently change what gets cached,
+    so the stdlib path writes null too;
+  * reading -- records already on disk carrying NaN or Infinity must stay
+    readable, or installing orjson turns each of them into a "corrupted cache
+    file" that DiskCache.get logs as an error and deletes.
+"""
+
+import importlib
+import json
+import math
+import sys
+from pathlib import Path
+from unittest import mock
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from src.cache import disk_cache as disk_cache_module  # noqa: E402
+
+
+@pytest.fixture
+def stdlib_cache():
+    """The module as it loads on a host with no orjson wheel."""
+    # A None entry in sys.modules makes `import orjson` raise ImportError,
+    # which is the branch we want, whether or not orjson is really installed.
+    with mock.patch.dict(sys.modules, {"orjson": None}):
+        module = importlib.reload(disk_cache_module)
+        assert module.orjson is None
+        yield module
+    importlib.reload(disk_cache_module)
+
+
+@pytest.fixture
+def orjson_cache():
+    """The module as it loads with orjson available."""
+    module = importlib.reload(disk_cache_module)
+    if module.orjson is None:
+        pytest.skip("orjson is not installed on this host")
+    return module
+
+
+NON_FINITE = {"nan": float("nan"), "inf": float("inf"), "ninf": float("-inf")}
+
+
+def _reject_constant(name):
+    """Make json.loads as strict as orjson about NaN/Infinity tokens."""
+    raise AssertionError(f"non-spec JSON constant in output: {name}")
+
+
+class TestWritePolicy:
+    """Non-finite floats become null on whichever encoder is in use."""
+
+    def _assert_nulled(self, module):
+        record = module._loads(module._dumps(dict(NON_FINITE, ok=1.5)))
+        assert record["nan"] is None
+        assert record["inf"] is None
+        assert record["ninf"] is None
+        # Finite values are untouched.
+        assert record["ok"] == 1.5
+
+    def test_stdlib_writes_null(self, stdlib_cache):
+        self._assert_nulled(stdlib_cache)
+
+    def test_orjson_writes_null(self, orjson_cache):
+        self._assert_nulled(orjson_cache)
+
+    def test_stdlib_emits_spec_compliant_json(self, stdlib_cache):
+        # The point of the write half: bytes written without orjson must still
+        # parse once orjson is installed later. json.loads accepts the
+        # extension tokens, so it cannot show this -- assert on the bytes, and
+        # on a strict reader when there is one.
+        raw = stdlib_cache._dumps(dict(NON_FINITE))
+        assert b"NaN" not in raw
+        assert b"Infinity" not in raw
+        assert json.loads(raw, parse_constant=_reject_constant) == {
+            "nan": None, "inf": None, "ninf": None}
+
+    def test_nested_non_finite_are_replaced(self, stdlib_cache):
+        data = {"a": [1.0, float("nan"), {"b": float("inf")}], "c": (float("-inf"),)}
+        record = stdlib_cache._loads(stdlib_cache._dumps(data))
+        assert record["a"] == [1.0, None, {"b": None}]
+        assert record["c"] == [None]
+
+    def test_finite_payloads_are_byte_identical_to_the_old_encoder(self, stdlib_cache):
+        # allow_nan=False must not change ordinary output.
+        data = {"x": 1, "y": [1.5, "s", True, None], "z": {"k": 2.25}}
+        assert stdlib_cache._dumps(data) == json.dumps(
+            data, cls=stdlib_cache.DateTimeEncoder).encode("utf-8")
+
+
+class TestReplaceNonFinite:
+    def test_leaves_ordinary_values_alone(self):
+        for value in (1, 1.5, "s", True, None, [], {}):
+            assert disk_cache_module._replace_nonfinite(value) == value
+
+    def test_replaces_every_non_finite_float(self):
+        for value in NON_FINITE.values():
+            assert disk_cache_module._replace_nonfinite(value) is None
+
+    def test_walks_nested_containers(self):
+        assert disk_cache_module._replace_nonfinite(
+            {"a": [{"b": float("nan")}]}) == {"a": [{"b": None}]}
+
+
+class TestLegacyRecordsStayReadable:
+    """Files written before orjson arrived still load."""
+
+    LEGACY = b'{"timestamp": 1000.0, "value": NaN, "other": Infinity}'
+
+    def test_stdlib_reads_legacy_tokens(self, stdlib_cache):
+        record = stdlib_cache._loads(self.LEGACY)
+        assert math.isnan(record["value"])
+        assert math.isinf(record["other"])
+
+    def test_orjson_falls_back_for_legacy_tokens(self, orjson_cache):
+        record = orjson_cache._loads(self.LEGACY)
+        assert math.isnan(record["value"])
+        assert math.isinf(record["other"])
+
+    def test_genuinely_malformed_files_still_raise(self, stdlib_cache):
+        with pytest.raises(json.JSONDecodeError):
+            stdlib_cache._loads(b'{"a": ')
+
+    def test_orjson_still_raises_for_malformed_files(self, orjson_cache):
+        with pytest.raises(json.JSONDecodeError):
+            orjson_cache._loads(b'{"a": ')
+
+
+class TestDiskCacheEndToEnd:
+    def _cache(self, module, tmp_path):
+        return module.DiskCache(str(tmp_path))
+
+    def test_legacy_file_is_not_deleted_as_corrupt(self, orjson_cache, tmp_path):
+        cache = self._cache(orjson_cache, tmp_path)
+        path = cache.get_cache_path("legacy")
+        Path(path).write_bytes(
+            b'{"timestamp": %d, "value": NaN}' % int(__import__("time").time()))
+
+        record = cache.get("legacy", max_age=None)
+
+        assert record is not None, "legacy NaN record was treated as corrupt"
+        assert math.isnan(record["value"])
+        assert Path(path).exists(), "legacy NaN record was deleted"
+
+    def test_round_trip_through_set_and_get(self, stdlib_cache, tmp_path):
+        cache = self._cache(stdlib_cache, tmp_path)
+        cache.set("k", {"timestamp": __import__("time").time(),
+                        "value": float("nan")})
+        record = cache.get("k", max_age=None)
+        assert record is not None
+        assert record["value"] is None

test/test_display_dirty_tracking.py

@@ -47,12 +47,17 @@ class _SwapSpy:
     def __init__(self, matrix):
         self.matrix = matrix
         self.count = 0
+        self.last_frame_hold = None
         self._orig = matrix.SwapOnVSync
 
     def __enter__(self):
-        def counting(canvas):
+        def counting(canvas, *args):
+            # *args carries framerate_fraction, which display_manager passes so
+            # a frame can be held for several refreshes. Signature must match
+            # the real binding or the spy hides a TypeError as a failed push.
             self.count += 1
-            return self._orig(canvas)
+            self.last_frame_hold = args[0] if args else 1
+            return self._orig(canvas, *args)
         self.matrix.SwapOnVSync = counting
         return self
 
@@ -109,6 +114,11 @@ class TestDirtyTracking:
         dm.draw.rectangle([0, 0, 30, 8], fill=(255, 255, 0))
         dm.update_display()   # push + snapshot write (first frame)
         assert os.path.exists(dm._snapshot_path)
+        # Backdate the file so the "was it bumped?" check below cannot be
+        # defeated by filesystem mtime granularity -- on Windows two writes in
+        # the same tick get identical timestamps, which made this test fail
+        # roughly two runs in three regardless of the code under test.
+        os.utime(dm._snapshot_path, (time.time() - 60, time.time() - 60))
         first_mtime = os.path.getmtime(dm._snapshot_path)
 
         # Age the write/touch bookkeeping past TOUCH_INTERVAL so the next
@@ -125,6 +135,62 @@ class TestDirtyTracking:
         assert os.path.getmtime(dm._snapshot_path) > first_mtime
 
 
+class TestScrollLock:
+    """Dirty tracking must not skip the panel push while a scroll is running.
+
+    SwapOnVSync is what paces the render loop, so skipping it also skips the
+    wait for the panel. A duplicate frame therefore returns early -- ~8ms
+    instead of ~10ms on a 100Hz panel -- which advances the strip only 0.8px
+    instead of 1.0px, which makes the NEXT frame more likely to be a duplicate
+    too. That is self-sustaining: measured at ~20% duplicate frames mid-scroll
+    on the odds ticker against essentially zero on a lighter plugin with
+    identical scroll settings. Pushing an identical frame costs one canvas
+    copy; falling out of vsync lock costs smooth motion.
+    """
+
+    def test_identical_frames_still_push_while_scrolling(self, dm):
+        dm.draw.rectangle([0, 0, 12, 12], fill=(0, 0, 255))
+        dm.update_display()
+        dm.set_scrolling_state(True)
+        try:
+            with _SwapSpy(dm.matrix) as spy:
+                dm.update_display()
+                dm.update_display()
+                dm.update_display()
+            assert spy.count == 3, "scrolling must stay locked to the panel"
+        finally:
+            dm.set_scrolling_state(False)
+
+    def test_identical_frames_are_skipped_when_not_scrolling(self, dm):
+        """The optimisation still applies to static content."""
+        dm.set_scrolling_state(False)
+        dm.draw.rectangle([0, 0, 14, 14], fill=(255, 0, 255))
+        dm.update_display()
+        with _SwapSpy(dm.matrix) as spy:
+            dm.update_display()
+            dm.update_display()
+        assert spy.count == 0
+
+    def test_stale_scrolling_state_stops_forcing_pushes(self, dm):
+        """A plugin that stops scrolling without saying so must not pin the
+        panel into always-push forever. is_currently_scrolling() expires on
+        its own inactivity threshold, and the skip has to come back with it."""
+        dm.draw.rectangle([0, 0, 16, 16], fill=(0, 255, 255))
+        dm.update_display()
+        dm.set_scrolling_state(True)
+        try:
+            # Backdate the activity marker past the inactivity threshold.
+            dm._scrolling_state['last_scroll_activity'] = (
+                time.time() - dm._scrolling_state['scroll_inactivity_threshold'] - 1.0)
+            assert dm.is_currently_scrolling() is False
+            with _SwapSpy(dm.matrix) as spy:
+                dm.update_display()
+                dm.update_display()
+            assert spy.count == 0
+        finally:
+            dm.set_scrolling_state(False)
+
+
 class TestKillSwitch:
     def test_dirty_tracking_can_be_disabled(self, dm):
         dm._dirty_tracking_enabled = False
@@ -160,3 +226,89 @@ class TestKillSwitch:
 
 if __name__ == "__main__":
     sys.exit(pytest.main([__file__, "-v"]))
+
+
+class TestFrameHold:
+    """Holding a frame for N refreshes is how a scroll runs slower than one
+    pixel per refresh without fractional pixel positions."""
+
+    def test_hold_reaches_swap_on_vsync(self, dm):
+        dm.set_scrolling_state(True)
+        dm.set_frame_hold(3)
+        try:
+            dm.draw.rectangle([0, 0, 9, 9], fill=(120, 0, 200))
+            with _SwapSpy(dm.matrix) as spy:
+                dm.update_display()
+            assert spy.count == 1
+            assert spy.last_frame_hold == 3
+        finally:
+            dm.set_scrolling_state(False)
+
+    def test_default_is_every_refresh(self, dm):
+        dm.set_scrolling_state(True)
+        try:
+            dm.draw.rectangle([0, 0, 11, 11], fill=(0, 120, 200))
+            with _SwapSpy(dm.matrix) as spy:
+                dm.update_display()
+            assert spy.last_frame_hold == 1
+        finally:
+            dm.set_scrolling_state(False)
+
+    def test_hold_resets_when_scrolling_stops(self, dm):
+        """One plugin's pacing must not leak into whatever is on screen next."""
+        dm.set_scrolling_state(True)
+        dm.set_frame_hold(5)
+        dm.set_scrolling_state(False)
+        dm.set_scrolling_state(True)
+        try:
+            dm.draw.rectangle([0, 0, 13, 13], fill=(200, 120, 0))
+            with _SwapSpy(dm.matrix) as spy:
+                dm.update_display()
+            assert spy.last_frame_hold == 1
+        finally:
+            dm.set_scrolling_state(False)
+
+    @pytest.mark.parametrize("bad,expected", [(0, 1), (-4, 1), (None, 1), ("x", 1)])
+    def test_unusable_holds_are_ignored_or_floored(self, dm, bad, expected):
+        dm.set_frame_hold(bad)
+        assert dm._frame_hold == expected
+
+
+class TestFrameHoldLifetime:
+    """The hold must last exactly as long as the scroll that asked for it.
+
+    Plugins share one display manager. A hold applied at plugin construction is
+    wiped the moment any *other* plugin finishes scrolling, so by the time the
+    first plugin renders it is back to one pixel per refresh -- the speed reads
+    correct in the log and is wrong on the panel.
+    """
+
+    def test_scrolling_state_carries_the_hold(self, dm):
+        dm.set_scrolling_state(True, frame_hold=4)
+        try:
+            dm.draw.rectangle([0, 0, 7, 7], fill=(10, 200, 10))
+            with _SwapSpy(dm.matrix) as spy:
+                dm.update_display()
+            assert spy.last_frame_hold == 4
+        finally:
+            dm.set_scrolling_state(False)
+
+    def test_another_plugin_stopping_does_not_strand_a_hold(self, dm):
+        dm.set_scrolling_state(True, frame_hold=3)
+        dm.set_scrolling_state(False)          # some other plugin finishes
+        dm.set_scrolling_state(True)           # a plugin that wants no hold
+        try:
+            dm.draw.rectangle([0, 0, 6, 6], fill=(200, 10, 10))
+            with _SwapSpy(dm.matrix) as spy:
+                dm.update_display()
+            assert spy.last_frame_hold == 1
+        finally:
+            dm.set_scrolling_state(False)
+
+    def test_default_keeps_previous_behaviour(self, dm):
+        """Callers that never heard of frame holds get one frame per refresh."""
+        dm.set_scrolling_state(True)
+        try:
+            assert dm._frame_hold == 1
+        finally:
+            dm.set_scrolling_state(False)

test/test_display_double_parity.py

@@ -0,0 +1,69 @@
+"""The visual-test double must not drift from the real DisplayManager.
+
+Both directions of drift are silent and both are damaging:
+
+  * the double accepts an argument production does not -- the call passes
+    every harness run and raises TypeError on the panel, which is precisely
+    the failure a safety harness exists to prevent;
+  * the double lacks an argument production has -- every plugin that
+    legitimately uses it fails every render, and the harness blames the
+    plugin.
+
+`set_scrolling_state` has been each of those in turn across two branches, so
+the parity is asserted rather than remembered.
+
+Read with ast rather than imported: src/display_manager.py imports rgbmatrix
+at module scope, which is absent anywhere without the panel library, and this
+check should hold on a laptop and in CI as well as on a Pi.
+"""
+
+import ast
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parent.parent
+REAL = ROOT / "src" / "display_manager.py"
+DOUBLE = ROOT / "src" / "plugin_system" / "testing" / "visual_display_manager.py"
+
+#: Methods a plugin calls on whichever manager it is handed.
+SHARED_METHODS = ["set_scrolling_state", "is_currently_scrolling"]
+
+
+def _signature(path: Path, class_hint: str, method: str):
+    """(name, default-repr) pairs for `method`, or None if it is absent."""
+    tree = ast.parse(path.read_text(encoding="utf-8"))
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.ClassDef) or class_hint not in node.name:
+            continue
+        for item in node.body:
+            if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)) and item.name == method:
+                args = [a.arg for a in item.args.args if a.arg != "self"]
+                pad = [None] * (len(args) - len(item.args.defaults))
+                defaults = pad + [ast.unparse(d) for d in item.args.defaults]
+                return list(zip(args, defaults))
+    return None
+
+
+@pytest.mark.parametrize("method", SHARED_METHODS)
+def test_the_double_matches_production(method):
+    real = _signature(REAL, "DisplayManager", method)
+    double = _signature(DOUBLE, "DisplayManager", method)
+
+    assert real is not None, f"DisplayManager lost {method}"
+    assert double is not None, \
+        f"the test double is missing {method}, so every plugin using it fails to render"
+    assert double == real, (
+        f"{method} has drifted: production takes {real}, the double takes {double}. "
+        "A double that is more permissive hides a production TypeError; one that "
+        "is less permissive fails plugins that are actually correct."
+    )
+
+
+def test_frame_hold_is_accepted_by_both():
+    """The specific argument that has drifted twice."""
+    for path, label in ((REAL, "DisplayManager"), (DOUBLE, "VisualTestDisplayManager")):
+        params = dict(_signature(path, "DisplayManager", "set_scrolling_state") or [])
+        assert "frame_hold" in params, f"{label} does not accept frame_hold"
+        assert params["frame_hold"] == "1", \
+            f"{label} must default frame_hold to 1 so existing callers are unaffected"

test/test_logo_downloader.py

@@ -8,27 +8,11 @@ ensure_logo_directory, and the download_missing_logo function path
 """
 
 import os
-import time
-
 import pytest
 from pathlib import Path
 from unittest.mock import patch, Mock, MagicMock
 
-from PIL import Image
+from src.logo_downloader import LogoDownloader
-from PIL.PngImagePlugin import PngInfo
-
-from src.logo_downloader import (
-    PLACEHOLDER_BG,
-    PLACEHOLDER_MARKER,
-    PLACEHOLDER_RETRY_SECONDS,
-    PLACEHOLDER_SIZE,
-    LogoDownloader,
-    download_missing_logo,
-    is_placeholder_logo,
-    placeholder_age_seconds,
-    refresh_placeholder_timestamp,
-    should_attempt_download,
-)
 
 
 # ---------------------------------------------------------------------------
@@ -143,211 +127,3 @@ class TestEnsureLogoDirectory:
         with patch("builtins.open", side_effect=mock_open):
             result = downloader.ensure_logo_directory(test_dir)
         assert result is False
-
-
-# ---------------------------------------------------------------------------
-# Placeholder detection and retry
-#
-# A failed download used to be cached as a placeholder wearing the real logo's
-# filename, and download_missing_logo returned early on "the file exists". One
-# transient failure therefore pinned a team to a grey box permanently.
-# ---------------------------------------------------------------------------
-
-class TestPlaceholderLogos:
-    def _placeholder(self, tmp_path, abbrev="COLL"):
-        downloader = LogoDownloader()
-        assert downloader.create_placeholder_logo(abbrev, str(tmp_path)) is True
-        return tmp_path / f"{abbrev}.png"
-
-    def test_generated_placeholder_is_recognised(self, tmp_path):
-        assert is_placeholder_logo(self._placeholder(tmp_path)) is True
-
-    def test_real_logo_is_not_a_placeholder(self, tmp_path):
-        real = tmp_path / "REAL.png"
-        Image.new("RGBA", (500, 500), (12, 34, 56, 255)).save(real)
-        assert is_placeholder_logo(real) is False
-
-    def test_legacy_unmarked_placeholder_is_recognised(self, tmp_path):
-        """Placeholders written before the marker existed must still be caught.
-
-        They are already sitting on users' disks; if they were not recognised
-        those teams would stay grey boxes forever even after this fix.
-        """
-        legacy = tmp_path / "LEGACY.png"
-        Image.new("RGBA", PLACEHOLDER_SIZE, PLACEHOLDER_BG).save(legacy)
-        assert is_placeholder_logo(legacy) is True
-
-    def test_same_size_but_different_colour_is_not_a_placeholder(self, tmp_path):
-        real = tmp_path / "SMALL.png"
-        Image.new("RGBA", PLACEHOLDER_SIZE, (10, 200, 10, 255)).save(real)
-        assert is_placeholder_logo(real) is False
-
-    def test_missing_file_is_not_a_placeholder(self, tmp_path):
-        assert is_placeholder_logo(tmp_path / "nope.png") is False
-
-    def test_existing_real_logo_short_circuits_without_downloading(self, tmp_path):
-        real = tmp_path / "REAL.png"
-        Image.new("RGBA", (500, 500), (1, 2, 3, 255)).save(real)
-        with patch.object(LogoDownloader, "download_logo") as download:
-            assert download_missing_logo(
-                "afl", "1", "REAL", real, logo_url="http://example/x.png") is True
-        download.assert_not_called()
-
-    def _age_placeholder(self, path, seconds):
-        """Rewrite a placeholder's marker so it reads as `seconds` old."""
-        metadata = PngInfo()
-        metadata.add_text(PLACEHOLDER_MARKER, str(time.time() - seconds))
-        with Image.open(path) as img:
-            img.copy().save(path, "PNG", pnginfo=metadata)
-
-    def test_stale_placeholder_triggers_a_retry(self, tmp_path):
-        path = self._placeholder(tmp_path)
-        self._age_placeholder(path, PLACEHOLDER_RETRY_SECONDS + 60)
-        assert placeholder_age_seconds(path) > PLACEHOLDER_RETRY_SECONDS
-
-        with patch.object(LogoDownloader, "download_logo", return_value=True) as download:
-            assert download_missing_logo(
-                "afl", "1", "COLL", path,
-                logo_url="http://example/coll.png") is True
-        download.assert_called_once()
-
-    def test_placeholder_age_survives_an_mtime_touch(self, tmp_path):
-        """The age comes from the stamp, not the filesystem.
-
-        Anything that rewrites file times -- a backup restore, an rsync, a
-        permissions fix script -- would otherwise reset the retry clock.
-        """
-        path = self._placeholder(tmp_path)
-        self._age_placeholder(path, PLACEHOLDER_RETRY_SECONDS + 60)
-        now = time.time()
-        os.utime(path, (now, now))
-        assert placeholder_age_seconds(path) > PLACEHOLDER_RETRY_SECONDS
-
-    def test_fresh_placeholder_does_not_retry(self, tmp_path):
-        """Rate limiting: a placeholder written seconds ago must not re-download.
-
-        Without this the fix would trade a permanent grey box for an ESPN
-        request on every frame.
-        """
-        path = self._placeholder(tmp_path)
-        with patch.object(LogoDownloader, "download_logo") as download:
-            assert download_missing_logo(
-                "afl", "1", "COLL", path,
-                logo_url="http://example/coll.png") is True
-        download.assert_not_called()
-
-
-class TestDownloadEligibility:
-    """One rule, shared by every download site.
-
-    The two bulk loops and the single-logo path each had their own idea of what
-    counted as "already have it", which is how one of them ended up retrying
-    fresh placeholders and the other skipping stale ones forever.
-    """
-
-    def _placeholder(self, tmp_path, abbrev="COLL"):
-        assert LogoDownloader().create_placeholder_logo(abbrev, str(tmp_path))
-        return tmp_path / f"{abbrev}.png"
-
-    def _age(self, path, seconds):
-        metadata = PngInfo()
-        metadata.add_text(PLACEHOLDER_MARKER, str(time.time() - seconds))
-        with Image.open(path) as img:
-            img.copy().save(path, "PNG", pnginfo=metadata)
-
-    def test_missing_file_is_eligible(self, tmp_path):
-        assert should_attempt_download(tmp_path / "nope.png") is True
-
-    def test_real_logo_is_not_eligible(self, tmp_path):
-        real = tmp_path / "REAL.png"
-        Image.new("RGBA", (500, 500), (1, 2, 3, 255)).save(real)
-        assert should_attempt_download(real) is False
-
-    def test_force_download_beats_a_real_logo(self, tmp_path):
-        real = tmp_path / "REAL.png"
-        Image.new("RGBA", (500, 500), (1, 2, 3, 255)).save(real)
-        assert should_attempt_download(real, force_download=True) is True
-
-    def test_fresh_placeholder_is_not_eligible(self, tmp_path):
-        assert should_attempt_download(self._placeholder(tmp_path)) is False
-
-    def test_stale_placeholder_is_eligible(self, tmp_path):
-        path = self._placeholder(tmp_path)
-        self._age(path, PLACEHOLDER_RETRY_SECONDS + 60)
-        assert should_attempt_download(path) is True
-
-    def test_league_bulk_loop_skips_a_fresh_placeholder(self, tmp_path):
-        """A bulk pass honours the same back-off as everything else."""
-        self._placeholder(tmp_path, "AAA")
-        downloader = LogoDownloader()
-        teams = [{"abbreviation": "AAA", "display_name": "A", "logo_url": "http://x/a.png"}]
-        with patch.object(LogoDownloader, "get_logo_directory", return_value=str(tmp_path)):
-            with patch.object(LogoDownloader, "fetch_teams_data", return_value={"sports": [{}]}):
-                with patch.object(LogoDownloader, "extract_teams_from_data", return_value=teams):
-                    with patch.object(LogoDownloader, "download_logo") as download:
-                        downloader.download_missing_logos_for_league("nfl")
-        download.assert_not_called()
-
-    def test_league_bulk_loop_retries_a_stale_placeholder(self, tmp_path):
-        path = self._placeholder(tmp_path, "AAA")
-        self._age(path, PLACEHOLDER_RETRY_SECONDS + 60)
-        downloader = LogoDownloader()
-        teams = [{"abbreviation": "AAA", "display_name": "A", "logo_url": "http://x/a.png"}]
-        with patch.object(LogoDownloader, "get_logo_directory", return_value=str(tmp_path)):
-            with patch.object(LogoDownloader, "fetch_teams_data", return_value={"sports": [{}]}):
-                with patch.object(LogoDownloader, "extract_teams_from_data", return_value=teams):
-                    with patch.object(LogoDownloader, "download_logo", return_value=True) as download:
-                        downloader.download_missing_logos_for_league("nfl")
-        download.assert_called_once()
-
-    def test_ncaa_bulk_loop_retries_a_stale_placeholder(self, tmp_path):
-        """This loop skipped placeholders forever; it now shares the rule."""
-        path = self._placeholder(tmp_path, "AAA")
-        self._age(path, PLACEHOLDER_RETRY_SECONDS + 60)
-        downloader = LogoDownloader()
-        teams = [{"abbreviation": "AAA", "display_name": "A",
-                  "logo_url": "http://x/a.png", "category": "FBS",
-                  "conference": "SEC"}]
-        with patch.object(LogoDownloader, "get_logo_directory", return_value=str(tmp_path)):
-            with patch.object(LogoDownloader, "fetch_teams_data", return_value={"sports": [{}]}):
-                with patch.object(LogoDownloader, "extract_teams_from_data", return_value=teams):
-                    with patch.object(LogoDownloader, "download_logo", return_value=True) as download:
-                        downloader.download_all_ncaa_football_logos()
-        download.assert_called_once()
-
-    def test_ncaa_bulk_loop_skips_a_fresh_placeholder(self, tmp_path):
-        self._placeholder(tmp_path, "AAA")
-        downloader = LogoDownloader()
-        teams = [{"abbreviation": "AAA", "display_name": "A",
-                  "logo_url": "http://x/a.png", "category": "FBS",
-                  "conference": "SEC"}]
-        with patch.object(LogoDownloader, "get_logo_directory", return_value=str(tmp_path)):
-            with patch.object(LogoDownloader, "fetch_teams_data", return_value={"sports": [{}]}):
-                with patch.object(LogoDownloader, "extract_teams_from_data", return_value=teams):
-                    with patch.object(LogoDownloader, "download_logo") as download:
-                        downloader.download_all_ncaa_football_logos()
-        download.assert_not_called()
-
-
-class TestRefreshPlaceholderTimestamp:
-    def test_restarts_the_back_off(self, tmp_path):
-        assert LogoDownloader().create_placeholder_logo("COLL", str(tmp_path))
-        path = tmp_path / "COLL.png"
-        metadata = PngInfo()
-        metadata.add_text(PLACEHOLDER_MARKER, str(time.time() - (PLACEHOLDER_RETRY_SECONDS + 60)))
-        with Image.open(path) as img:
-            img.copy().save(path, "PNG", pnginfo=metadata)
-        assert should_attempt_download(path) is True
-
-        assert refresh_placeholder_timestamp(path) is True
-        assert should_attempt_download(path) is False
-
-    def test_refuses_to_touch_a_real_logo(self, tmp_path):
-        real = tmp_path / "REAL.png"
-        Image.new("RGBA", (500, 500), (1, 2, 3, 255)).save(real)
-        before = real.read_bytes()
-        assert refresh_placeholder_timestamp(real) is False
-        assert real.read_bytes() == before
-
-    def test_missing_file_is_not_an_error(self, tmp_path):
-        assert refresh_placeholder_timestamp(tmp_path / "nope.png") is False

test/test_logo_helper.py

@@ -421,76 +421,3 @@ class TestSessionConfiguration:
     def test_user_agent_and_accept_headers(self, helper):
         assert helper.session.headers["User-Agent"] == "LEDMatrix-Common/1.0"
         assert helper.session.headers["Accept"] == "image/*"
-
-
-class TestStalePlaceholderHandling:
-    """load_logo_with_download must not be fooled by a cached placeholder.
-
-    A placeholder wears the real logo's filename, so both the file cache and
-    the in-memory cache can hold one and look like a hit.
-    """
-
-    def _placeholder(self, tmp_path, abbrev="COLL"):
-        from src.logo_downloader import LogoDownloader
-        assert LogoDownloader().create_placeholder_logo(abbrev, str(tmp_path))
-        return tmp_path / f"{abbrev}.png"
-
-    def _make_stale(self, path):
-        import time
-        from PIL.PngImagePlugin import PngInfo
-        from src.logo_downloader import PLACEHOLDER_MARKER, PLACEHOLDER_RETRY_SECONDS
-        metadata = PngInfo()
-        metadata.add_text(PLACEHOLDER_MARKER, str(time.time() - (PLACEHOLDER_RETRY_SECONDS + 60)))
-        with Image.open(path) as img:
-            img.copy().save(path, "PNG", pnginfo=metadata)
-
-    def test_fresh_placeholder_is_served_without_a_download(self, helper, tmp_path):
-        path = self._placeholder(tmp_path)
-        with patch.object(LogoHelper, "_download_logo") as download:
-            assert helper.load_logo_with_download("COLL", path, "http://x/c.png") is not None
-        download.assert_not_called()
-
-    def test_stale_placeholder_triggers_a_download(self, helper, tmp_path):
-        path = self._placeholder(tmp_path)
-        self._make_stale(path)
-        with patch.object(LogoHelper, "_download_logo") as download:
-            helper.load_logo_with_download("COLL", path, "http://x/c.png")
-        download.assert_called_once()
-
-    def test_replacement_logo_is_not_masked_by_the_cached_placeholder(self, helper, tmp_path):
-        """The bug this guards: load_logo answers from cache before the disk.
-
-        Without invalidation the freshly downloaded logo would not appear until
-        the process restarted.
-        """
-        path = self._placeholder(tmp_path)
-        first = helper.load_logo_with_download("COLL", path, "http://x/c.png")
-        assert first is not None
-
-        self._make_stale(path)
-
-        def fake_download(_self, _url, file_path):
-            Image.new("RGB", (500, 500), (7, 8, 9)).save(file_path, format="PNG")
-
-        with patch.object(LogoHelper, "_download_logo", fake_download):
-            second = helper.load_logo_with_download("COLL", path, "http://x/c.png")
-
-        assert second is not None
-        from src.logo_downloader import is_placeholder_logo
-        assert is_placeholder_logo(path) is False
-        assert second.getpixel((0, 0))[:3] == (7, 8, 9)
-
-    def test_failed_retry_restarts_the_back_off(self, helper, tmp_path):
-        """Otherwise a stale placeholder means a download attempt per call."""
-        from src.logo_downloader import should_attempt_download
-        path = self._placeholder(tmp_path)
-        self._make_stale(path)
-        assert should_attempt_download(path) is True
-
-        def boom(_self, _url, _file_path):
-            raise OSError("network down")
-
-        with patch.object(LogoHelper, "_download_logo", boom):
-            helper.load_logo_with_download("COLL", path, "http://x/c.png")
-
-        assert should_attempt_download(path) is False

test/test_plugin_compatibility_gate.py

@@ -19,7 +19,6 @@ The rules being pinned here, in priority order:
 """
 
 import json
-import subprocess
 from pathlib import Path
 from unittest.mock import MagicMock
 
@@ -147,18 +146,9 @@ def store(tmp_path, monkeypatch):
 
 
 class TestInstallGate:
-    """`install_plugin` is the chokepoint for every route that re-downloads:
+    """`install_plugin` is the chokepoint: `_reinstall_with_rollback` calls it,
-    `_reinstall_with_rollback` calls it, so a refused update restores the
+    so gating there covers updates too, and a refused update restores the
-    version the user already had.
+    version the user already had."""
-
-    It is not the *only* route in, and saying so here once is cheaper than
-    rediscovering it. `update_plugin` also has a git branch that pulls in
-    place and never re-downloads; that one is gated separately by
-    `_gate_pulled_commit` and pinned in `TestGitPullGate` below. A third
-    route, `install_from_url` (sideloading from a URL), is gated in that
-    function and pinned in `TestSideloadGate`. All three refuse on the same
-    rule.
-    """
 
     def _install_with_manifest(self, store, manifest, core_version, monkeypatch):
         mgr, plugins_dir = store
@@ -218,291 +208,6 @@ class TestInstallGate:
         assert (path / "manifest.json").exists()
 
 
-class TestSideloadGate:
-    """`install_from_url` never looked at the core version.
-
-    Sideloading is an explicit act rather than an automatic store update, so
-    the argument for gating it is different: not "the user did not choose
-    this", but that the floor states the plugin *cannot run here*. Letting it
-    through produces the same silent PluginState.ERROR at load that the store
-    gate exists to prevent, and the user who typed the URL is no better placed
-    to diagnose it than one who pressed Update.
-    """
-
-    def _sideload(self, store, manifest, core_version, monkeypatch):
-        mgr, plugins_dir = store
-        plugin_id = manifest["id"]
-
-        def fake_clone(repo_url, target_path, branches=None):
-            target_path.mkdir(parents=True, exist_ok=True)
-            (target_path / "manifest.json").write_text(
-                json.dumps(manifest), encoding="utf-8")
-            (target_path / "manager.py").write_text(
-                "class P: pass\n", encoding="utf-8")
-            return "main"
-
-        monkeypatch.setattr(mgr, "_install_via_git", fake_clone)
-        monkeypatch.setattr(mgr, "_install_dependencies", lambda *a, **k: True)
-
-        import src
-        monkeypatch.setattr(src, "__version__", core_version)
-        return mgr.install_from_url("https://example.invalid/plugin"), \
-            plugins_dir / plugin_id
-
-    def test_refuses_a_plugin_that_needs_a_newer_core(self, store, monkeypatch):
-        manifest = {
-            "id": "sideload-newer", "name": "Sideload", "class_name": "P",
-            "display_modes": ["a"], "min_ledmatrix_version": "9.9.9",
-        }
-        result, path = self._sideload(store, manifest, "3.2.0", monkeypatch)
-
-        assert result["success"] is False
-        assert "9.9.9" in result["error"], result["error"]
-        assert not path.exists(), (
-            "a refused sideload must not leave the plugin installed")
-
-    def test_allows_a_compatible_plugin(self, store, monkeypatch):
-        """The guard against over-refusing: a gate that blocks everything
-        passes the test above and breaks sideloading entirely."""
-        manifest = {
-            "id": "sideload-fine", "name": "Sideload", "class_name": "P",
-            "display_modes": ["a"], "min_ledmatrix_version": "3.0.0",
-        }
-        result, path = self._sideload(store, manifest, "3.2.0", monkeypatch)
-
-        assert result["success"] is True, result.get("error")
-        assert (path / "manifest.json").exists()
-
-    def test_untrustworthy_core_does_not_block_a_2_0_0_floor(
-            self, store, monkeypatch):
-        """Same rule as the other two routes: a v3.1.0 release reports 1.0.0,
-        and nearly every published manifest floors at 2.0.0."""
-        manifest = {
-            "id": "sideload-floored", "name": "Sideload", "class_name": "P",
-            "display_modes": ["a"], "versions": [{"ledmatrix_min": "2.0.0"}],
-        }
-        result, _ = self._sideload(store, manifest, "1.0.0", monkeypatch)
-
-        assert result["success"] is True, result.get("error")
-
-# --------------------------------------------------------------------------
-# The git-pull update path — the one route that does not re-download
-# --------------------------------------------------------------------------
-
-def _git_available() -> bool:
-    # OSError, not just a non-zero exit: with no git on PATH subprocess raises
-    # FileNotFoundError, and this runs at import time -- before skipif can act,
-    # so the whole module would error out instead of skipping.
-    try:
-        return subprocess.run(
-            ['git', '--version'], capture_output=True).returncode == 0
-    except OSError:
-        return False
-
-
-_HAS_GIT = _git_available()
-
-
-def _git(*args, cwd):
-    return subprocess.run(['git', *args], cwd=str(cwd),
-                          capture_output=True, text=True, check=True)
-
-
-@pytest.mark.skipif(not _HAS_GIT, reason='git not available')
-class TestGitPullGate:
-    """A plugin installed as a git checkout updates by pulling in place, so it
-    never passes through `install_plugin` and was never gated.
-
-    Real git repositories rather than mocks, because the claim under test is
-    that `git reset --hard` puts the checkout back — a mock of git would only
-    prove the call was made, which is the easy half.
-
-    Only the handful of registry entries with no `plugin_path` reach this path
-    in practice; monorepo plugins install as archives and update through
-    `_reinstall_with_rollback`. It is gated anyway because the sunset rule in
-    `docs/plugin-development/08-shared-sports-code.md` states the core enforces
-    the floor "at install/update time", and a precondition that is documented
-    but not true is worse than one that is merely missing.
-    """
-
-    @pytest.fixture
-    def checkout(self, tmp_path, monkeypatch):
-        """An origin repo holding a plugin, and a clone of it installed as
-        `plugin-repos/gitplug`, with the store pointed at it."""
-        from src.plugin_system.store_manager import PluginStoreManager
-
-        origin = tmp_path / 'origin'
-        origin.mkdir()
-        _git('init', '--initial-branch=main', '--bare', cwd=origin)
-
-        seed = tmp_path / 'seed'
-        _git('clone', str(origin), str(seed), cwd=tmp_path)
-        _git('config', 'user.email', 'test@example.com', cwd=seed)
-        _git('config', 'user.name', 'Test', cwd=seed)
-        (seed / 'manifest.json').write_text(json.dumps({
-            "id": "gitplug", "name": "Git Plug", "class_name": "P",
-            "display_modes": ["a"], "min_ledmatrix_version": "2.0.0",
-        }), encoding='utf-8')
-        (seed / 'manager.py').write_text("class P: pass\n", encoding='utf-8')
-        _git('add', '-A', cwd=seed)
-        _git('commit', '-m', 'initial', cwd=seed)
-        _git('push', '-u', 'origin', 'main', cwd=seed)
-
-        plugins_dir = tmp_path / 'plugin-repos'
-        plugins_dir.mkdir()
-        work = plugins_dir / 'gitplug'
-        _git('clone', str(origin), str(work), cwd=tmp_path)
-        _git('config', 'user.email', 'test@example.com', cwd=work)
-        _git('config', 'user.name', 'Test', cwd=work)
-
-        mgr = PluginStoreManager(plugins_dir=str(plugins_dir))
-        mgr.logger = MagicMock()
-        # No registry entry, so update_plugin takes the plain-pull branch
-        # rather than the remote-mismatch or already-current shortcuts.
-        monkeypatch.setattr(mgr, 'fetch_registry', lambda *a, **k: None)
-        monkeypatch.setattr(mgr, 'get_plugin_info', lambda *a, **k: None)
-        monkeypatch.setattr(mgr, '_install_dependencies', lambda *a, **k: True)
-        return mgr, seed, work
-
-    def _push(self, seed, manifest_text):
-        (seed / 'manifest.json').write_text(manifest_text, encoding='utf-8')
-        _git('add', '-A', cwd=seed)
-        _git('commit', '-m', 'update', cwd=seed)
-        _git('push', 'origin', 'main', cwd=seed)
-
-    def _head(self, work):
-        return _git('rev-parse', 'HEAD', cwd=work).stdout.strip()
-
-    def test_refuses_a_pulled_commit_that_needs_a_newer_core(
-            self, checkout, monkeypatch):
-        mgr, seed, work = checkout
-        before = self._head(work)
-        self._push(seed, json.dumps({
-            "id": "gitplug", "name": "Git Plug", "class_name": "P",
-            "display_modes": ["a"], "min_ledmatrix_version": "9.9.9",
-        }))
-
-        import src
-        monkeypatch.setattr(src, '__version__', '3.2.0')
-        assert mgr.update_plugin('gitplug') is False
-
-        assert self._head(work) == before, (
-            "a refused update must leave the checkout on the commit it was "
-            "already running, not on the one it cannot load")
-        floor = json.loads((work / 'manifest.json').read_text())
-        assert floor['min_ledmatrix_version'] == '2.0.0', (
-            "the reset must restore the working tree, not just the ref")
-
-    def test_allows_a_pulled_commit_the_core_can_run(
-            self, checkout, monkeypatch):
-        """The guard against over-refusing. A gate that refuses everything
-        passes the test above and breaks every update."""
-        mgr, seed, work = checkout
-        before = self._head(work)
-        self._push(seed, json.dumps({
-            "id": "gitplug", "name": "Git Plug", "class_name": "P",
-            "display_modes": ["a"], "min_ledmatrix_version": "3.0.0",
-        }))
-
-        import src
-        monkeypatch.setattr(src, '__version__', '3.2.0')
-        assert mgr.update_plugin('gitplug') is True
-        assert self._head(work) != before
-
-    def test_an_unreadable_manifest_after_pull_is_not_a_refusal(
-            self, checkout, monkeypatch):
-        """Rule 1 of this file — refuse only on evidence. A manifest that
-        will not parse declares no floor, so it is not evidence of anything."""
-        mgr, seed, work = checkout
-        self._push(seed, '{ this is not json')
-
-        import src
-        monkeypatch.setattr(src, '__version__', '3.2.0')
-        assert mgr.update_plugin('gitplug') is True
-
-    def test_an_untrustworthy_core_does_not_block_a_2_0_0_floor_on_pull(
-            self, checkout, monkeypatch):
-        """The same regression guard as
-        `test_untrustworthy_core_does_not_block_installs`, because this path
-        now shares that rule: a v3.1.0 release reports 1.0.0, and nearly every
-        published manifest floors at 2.0.0."""
-        mgr, seed, work = checkout
-        before = self._head(work)
-        self._push(seed, json.dumps({
-            "id": "gitplug", "name": "Git Plug", "class_name": "P",
-            "display_modes": ["a"], "min_ledmatrix_version": "2.0.0",
-            "description": "changed",
-        }))
-
-        import src
-        monkeypatch.setattr(src, '__version__', '1.0.0')
-        assert mgr.update_plugin('gitplug') is True
-        assert self._head(work) != before
-
-    def test_a_failed_stash_stops_the_update_before_pulling(
-            self, checkout, monkeypatch):
-        """Uncommitted work is not collateral for the gate.
-
-        The gate's only rollback is `git reset --hard`, which discards
-        uncommitted tracked edits. update_plugin stashes them first -- but when
-        that stash fails it used to pull anyway, and a pull touching different
-        files succeeds on a dirty tree. Refuse, refuse the rollback's rollback,
-        and the user's edits go with it.
-        """
-        mgr, seed, work = checkout
-        before = self._head(work)
-        (work / 'manager.py').write_text(
-            "class P:\n    MINE = 'do not lose this'\n", encoding='utf-8')
-        self._push(seed, json.dumps({
-            "id": "gitplug", "name": "Git Plug", "class_name": "P",
-            "display_modes": ["a"], "min_ledmatrix_version": "9.9.9",
-        }))
-
-        real_run = subprocess.run
-
-        def fail_stash(cmd, *a, **k):
-            if isinstance(cmd, list) and 'stash' in cmd:
-                return subprocess.CompletedProcess(cmd, 1, '', 'stash boom')
-            return real_run(cmd, *a, **k)
-
-        import src
-        monkeypatch.setattr(src, '__version__', '3.2.0')
-        monkeypatch.setattr(
-            'src.plugin_system.store_manager.subprocess.run', fail_stash)
-        assert mgr.update_plugin('gitplug') is False
-
-        assert self._head(work) == before, "must not pull what it cannot undo"
-        assert 'do not lose this' in (work / 'manager.py').read_text(), (
-            "the local edit the stash failed to save must still be there")
-
-    def test_rollback_reports_the_recovery_command_when_git_fails(
-            self, checkout, monkeypatch):
-        """If the reset itself fails the user is left on a version that cannot
-        load, so the log line has to carry the command that fixes it —
-        it is the only thing standing between them and a manual reinstall."""
-        mgr, seed, work = checkout
-        self._push(seed, json.dumps({
-            "id": "gitplug", "name": "Git Plug", "class_name": "P",
-            "display_modes": ["a"], "min_ledmatrix_version": "9.9.9",
-        }))
-
-        real_run = subprocess.run
-
-        def fail_reset(cmd, *a, **k):
-            if isinstance(cmd, list) and 'reset' in cmd:
-                return subprocess.CompletedProcess(cmd, 1, '', 'reset boom')
-            return real_run(cmd, *a, **k)
-
-        import src
-        monkeypatch.setattr(src, '__version__', '3.2.0')
-        monkeypatch.setattr(
-            'src.plugin_system.store_manager.subprocess.run', fail_reset)
-        assert mgr.update_plugin('gitplug') is False
-
-        logged = ' '.join(str(c) for c in mgr.logger.error.call_args_list)
-        assert 'reset --hard' in logged, logged
-
-
 class TestLoaderAndStoreAgree:
     """Both read the same manifests; a disagreement means one of them is
     lying to the user."""

test/test_scroll_config.py

@@ -0,0 +1,467 @@
+"""Tests for the shared scroll configuration resolver."""
+
+import logging
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from src.common.scroll_config import (  # noqa: E402
+    DEFAULT_PIXELS_PER_SECOND,
+    MAX_PIXELS_PER_FRAME,
+    crisp_ladder,
+    solve_crisp,
+    MAX_PIXELS_PER_SECOND,
+    MIN_PIXELS_PER_SECOND,
+    ScrollSettings,
+    configure,
+    refresh_hz_from_config,
+    resolve,
+)
+
+
+class FakeHelper:
+    """Records what configure() applied."""
+
+    def __init__(self, with_optional=True):
+        self.speed = None
+        self.frame_based = None
+        self.target_fps = None
+        if not with_optional:
+            del FakeHelper.set_frame_based_scrolling
+            del FakeHelper.set_target_fps
+
+    def set_scroll_speed(self, speed):
+        self.speed = speed
+
+    def set_frame_based_scrolling(self, enabled):
+        self.frame_based = enabled
+
+    def set_target_fps(self, fps):
+        self.target_fps = fps
+
+
+class FakeDisplayManager:
+    """Records the frame hold configure() applies."""
+
+    def __init__(self):
+        self.hold = None
+
+    def set_frame_hold(self, refreshes):
+        self.hold = refreshes
+
+
+class MinimalHelper:
+    """An older helper exposing only set_scroll_speed."""
+
+    def __init__(self):
+        self.speed = None
+
+    def set_scroll_speed(self, speed):
+        self.speed = speed
+
+
+class TestPrecedence:
+    def test_display_options_pair_wins(self):
+        s = resolve({"display_options": {"scroll_speed": 1.0, "scroll_delay": 0.01}})
+        assert s.pixels_per_second == 100.0
+        assert s.source == "display_options.scroll_speed/delay"
+
+    def test_display_block_used_when_options_absent(self):
+        s = resolve({"display": {"scroll_speed": 2.0, "scroll_delay": 0.01}})
+        assert s.pixels_per_second == 200.0
+        assert s.source == "display.scroll_speed/delay"
+
+    def test_root_pair_used_when_both_blocks_absent(self):
+        s = resolve({"scroll_speed": 1.0, "scroll_delay": 0.02})
+        assert s.pixels_per_second == 50.0
+
+    def test_pixels_per_second_used_when_no_pair_given(self):
+        s = resolve({"display_options": {"scroll_pixels_per_second": 120.0}})
+        assert s.pixels_per_second == 120.0
+        assert s.source == "display_options.scroll_pixels_per_second"
+
+    def test_global_display_is_the_last_resort_before_default(self):
+        s = resolve({}, {"display": {"scroll_speed": 1.0, "scroll_delay": 0.005}})
+        assert s.pixels_per_second == 200.0
+
+    def test_default_when_nothing_configured(self):
+        s = resolve({}, {})
+        assert s.pixels_per_second == DEFAULT_PIXELS_PER_SECOND
+        assert s.source == "default"
+
+
+class TestDeprecatedKeyCannotOverrideExplicitPair:
+    """Regression for ChuckBuilds/ledmatrix-plugins#408.
+
+    odds-ticker ranked scroll_pixels_per_second above the documented
+    scroll_speed/scroll_delay pair. Because that key carries a schema default,
+    the documented settings became unreachable for every user and the ticker
+    silently ran at the default speed. The pair must win.
+    """
+
+    def test_pair_beats_pixels_per_second_in_the_same_block(self):
+        s = resolve(
+            {
+                "display_options": {
+                    "scroll_speed": 1.0,
+                    "scroll_delay": 0.01,
+                    "scroll_pixels_per_second": 50.0,  # schema default
+                }
+            }
+        )
+        assert s.pixels_per_second == 100.0
+        assert "scroll_speed/delay" in s.source
+
+    def test_pair_beats_pixels_per_second_in_an_outer_block(self):
+        s = resolve(
+            {
+                "display_options": {"scroll_speed": 1.0, "scroll_delay": 0.01},
+                "scroll_pixels_per_second": 50.0,
+            }
+        )
+        assert s.pixels_per_second == 100.0
+
+
+class TestMalformedValues:
+    @pytest.mark.parametrize("bad", [None, "fast", "", {}, [], float("nan")])
+    def test_unusable_speed_falls_through(self, bad):
+        s = resolve({"display_options": {"scroll_speed": bad, "scroll_delay": 0.01}})
+        assert s.pixels_per_second == DEFAULT_PIXELS_PER_SECOND
+
+    @pytest.mark.parametrize("bad", [0, -5, 0.0])
+    def test_non_positive_values_fall_through(self, bad):
+        s = resolve({"display_options": {"scroll_pixels_per_second": bad}})
+        assert s.pixels_per_second == DEFAULT_PIXELS_PER_SECOND
+
+    def test_booleans_are_not_treated_as_numbers(self):
+        s = resolve({"display_options": {"scroll_pixels_per_second": True}})
+        assert s.pixels_per_second == DEFAULT_PIXELS_PER_SECOND
+
+    def test_zero_delay_does_not_divide_by_zero(self):
+        s = resolve({"display_options": {"scroll_speed": 1.0, "scroll_delay": 0}})
+        assert s.pixels_per_second == DEFAULT_PIXELS_PER_SECOND
+
+    def test_non_dict_blocks_are_ignored(self):
+        s = resolve({"display_options": "nonsense", "display": 5})
+        assert s.pixels_per_second == DEFAULT_PIXELS_PER_SECOND
+
+
+class TestClamping:
+    def test_absurdly_fast_is_clamped(self):
+        s = resolve({"display_options": {"scroll_pixels_per_second": 100000.0}})
+        assert s.pixels_per_second == MAX_PIXELS_PER_SECOND
+        assert s.warning and "clamped" in s.warning
+
+    def test_absurdly_slow_is_clamped(self):
+        s = resolve({"display_options": {"scroll_pixels_per_second": 0.01}})
+        assert s.pixels_per_second == MIN_PIXELS_PER_SECOND
+
+
+class TestWholePixelWarning:
+    """The display rule: whole pixels per refresh, or it judders."""
+
+    def test_no_warning_when_speed_divides_evenly(self):
+        s = resolve({"display_options": {"scroll_pixels_per_second": 100.0}}, refresh_hz=100)
+        assert s.warning is None
+        assert s.pixels_per_frame == pytest.approx(1.0)
+
+    def test_no_warning_at_an_integer_multiple(self):
+        s = resolve({"display_options": {"scroll_pixels_per_second": 200.0}}, refresh_hz=100)
+        assert s.warning is None
+
+    def test_warns_on_a_half_pixel_per_frame(self):
+        s = resolve({"display_options": {"scroll_pixels_per_second": 50.0}}, refresh_hz=100)
+        assert s.warning is not None
+        assert "judder" in s.warning
+        assert "100 px/s" in s.warning
+
+    def test_warns_on_a_fractional_multiple(self):
+        s = resolve({"display_options": {"scroll_pixels_per_second": 130.0}}, refresh_hz=100)
+        assert s.warning is not None
+
+    def test_respects_a_non_default_refresh_rate(self):
+        s = resolve({"display_options": {"scroll_pixels_per_second": 150.0}}, refresh_hz=150)
+        assert s.warning is None
+        assert s.pixels_per_frame == pytest.approx(1.0)
+
+
+class TestConfigure:
+    def test_applies_time_based_mode_and_speed(self):
+        helper = FakeHelper()
+        s = configure(helper, {"display_options": {"scroll_speed": 1.0, "scroll_delay": 0.01}})
+        assert helper.speed == 100.0
+        assert helper.frame_based is False, "must not use the wall-clock step gate"
+        assert helper.target_fps == 100.0
+        assert s.pixels_per_second == 100.0
+
+    def test_works_against_a_helper_without_optional_methods(self):
+        helper = MinimalHelper()
+        configure(helper, {"display_options": {"scroll_pixels_per_second": 100.0}})
+        assert helper.speed == 100.0
+
+    def test_snapping_removes_the_judder_warning(self, caplog):
+        """50px/s cannot be shown in whole pixels at 100Hz *per refresh*, but it
+        can as 1px every 2nd refresh -- so once snapped there is nothing to warn
+        about. resolve() alone still warns; configure() resolves it."""
+        assert "judder" in resolve(
+            {"display_options": {"scroll_pixels_per_second": 50.0}},
+            refresh_hz=100).warning
+        helper, dm = FakeHelper(), FakeDisplayManager()
+        with caplog.at_level(logging.WARNING):
+            settings = configure(
+                helper, {"display_options": {"scroll_pixels_per_second": 50.0}},
+                display_manager=dm)
+        assert settings.warning is None
+        assert not [r for r in caplog.records if "judder" in r.getMessage()]
+
+    def test_reports_the_hold_without_applying_it(self):
+        """The hold belongs to a scroll, not a plugin's lifetime -- one left set
+        at construction is wiped as soon as any other plugin stops scrolling.
+        configure() reports it; the caller passes it to set_scrolling_state."""
+        dm = FakeDisplayManager()
+        s = configure(FakeHelper(), {"display_options": {"scroll_pixels_per_second": 25.0}},
+                      display_manager=dm)
+        assert s.frame_hold == 4, "25px/s at 100Hz is 1px every 4th refresh"
+        assert dm.hold is None, "must not apply the hold behind the caller's back"
+
+    def test_full_speed_needs_no_hold(self):
+        s = configure(FakeHelper(), {"display_options": {"scroll_pixels_per_second": 100.0}},
+                      display_manager=FakeDisplayManager())
+        assert s.frame_hold == 1
+
+    def test_frame_hold_is_one_when_snapping_is_off(self):
+        s = configure(FakeHelper(), {"display_options": {"scroll_pixels_per_second": 50.0}},
+                      snap_to_crisp=False)
+        assert s.frame_hold == 1
+
+    def test_snaps_to_the_nearest_crisp_speed_and_reports_both(self):
+        s = configure(FakeHelper(), {"display_options": {"scroll_pixels_per_second": 45.0}},
+                      display_manager=FakeDisplayManager())
+        assert s.requested_pixels_per_second == 45.0
+        assert s.pixels_per_second == 50.0
+        assert s.crisp is not None and s.crisp.pixels_per_frame == 1
+
+    def test_snapping_can_be_turned_off(self):
+        s = configure(FakeHelper(), {"display_options": {"scroll_pixels_per_second": 45.0}},
+                      snap_to_crisp=False)
+        assert s.pixels_per_second == 45.0
+        assert s.crisp is None
+
+    def test_helper_target_fps_matches_the_presentation_rate(self):
+        """At a hold of 4 the panel still refreshes at 100Hz, but frames are
+        presented at 25/s -- that is the rate the helper should pace to."""
+        helper = FakeHelper()
+        configure(helper, {"display_options": {"scroll_pixels_per_second": 25.0}},
+                  display_manager=FakeDisplayManager())
+        assert helper.target_fps == pytest.approx(25.0)
+
+    def test_returns_settings_describing_the_source(self):
+        s = configure(FakeHelper(), {"display_options": {"scroll_speed": 2.0, "scroll_delay": 0.01}})
+        assert isinstance(s, ScrollSettings)
+        assert "200.0 px/s" in s.describe()
+
+
+class TestRefreshFromConfig:
+    def test_reads_the_hardware_limit(self):
+        assert refresh_hz_from_config(
+            {"display": {"hardware": {"limit_refresh_rate_hz": 150}}}
+        ) == 150.0
+
+    @pytest.mark.parametrize("cfg", [None, {}, {"display": {}}, {"display": {"hardware": {}}},
+                                     "nonsense", {"display": {"hardware": {"limit_refresh_rate_hz": None}}}])
+    def test_falls_back_to_the_default(self, cfg):
+        assert refresh_hz_from_config(cfg) == 100.0
+
+    @pytest.mark.parametrize("cfg", [
+        {"display": "nonsense"},
+        {"display": ["nonsense"]},
+        {"display": 60},
+        {"display": {"hardware": "nonsense"}},
+        {"display": {"hardware": ["nonsense"]}},
+        {"display": {"hardware": 60}},
+    ])
+    def test_malformed_nesting_falls_back_rather_than_raising(self, cfg):
+        # Truthy-but-not-a-mapping at either level used to reach .get() on a
+        # str/list and raise AttributeError out of a function whose whole
+        # contract is "a refresh rate, or the default".
+        assert refresh_hz_from_config(cfg) == 100.0
+
+
+class TestCrispLadder:
+    """Whole-pixel speeds available on a given panel."""
+
+    def test_every_entry_is_exactly_reachable(self):
+        for c in crisp_ladder(100):
+            assert c.pixels_per_second == pytest.approx(
+                c.refresh_hz / c.frame_hold * c.pixels_per_frame)
+
+    def test_sorted_slowest_first(self):
+        speeds = [c.pixels_per_second for c in crisp_ladder(100)]
+        assert speeds == sorted(speeds)
+
+    def test_no_duplicate_speeds(self):
+        speeds = [round(c.pixels_per_second, 3) for c in crisp_ladder(100)]
+        assert len(speeds) == len(set(speeds))
+
+    def test_duplicates_resolve_to_the_smaller_step(self):
+        """100px/s is 1px every refresh or 2px every 2nd; prefer the former."""
+        entry = next(c for c in crisp_ladder(100)
+                     if c.pixels_per_second == pytest.approx(100.0))
+        assert entry.pixels_per_frame == 1
+        assert entry.frame_hold == 1
+
+    def test_ladder_scales_with_the_panel(self):
+        assert any(c.pixels_per_second == pytest.approx(60.0)
+                   for c in crisp_ladder(60))
+        assert any(c.pixels_per_second == pytest.approx(30.0)
+                   for c in crisp_ladder(60))
+
+    def test_full_refresh_speed_is_present(self):
+        for hz in (60, 75, 100, 120):
+            assert any(c.pixels_per_second == pytest.approx(float(hz))
+                       for c in crisp_ladder(hz))
+
+
+class TestSolveCrisp:
+    def test_exact_targets_are_matched_exactly(self):
+        for target in (100, 50, 25, 20):
+            assert solve_crisp(target, 100).pixels_per_second == pytest.approx(target)
+
+    def test_prefers_smooth_motion_over_raw_proximity(self):
+        """30 -> 33.3 (1px, 33fps), not 28.6 (2px at 14fps) which is nearer."""
+        got = solve_crisp(30, 100)
+        assert got.pixels_per_second == pytest.approx(33.333, abs=0.01)
+        assert got.pixels_per_frame == 1
+
+    def test_does_not_chase_a_jumpy_exact_match(self):
+        """45 -> 50 (1px, smooth) beats 42.9 (3px at 14fps)."""
+        assert solve_crisp(45, 100).pixels_per_frame == 1
+
+    def test_allows_a_two_pixel_step_when_it_is_clearly_closer(self):
+        """60 -> 66.7 (2px at 33fps) rather than 50 (1px) which is 17% slow."""
+        got = solve_crisp(60, 100)
+        assert got.pixels_per_second == pytest.approx(66.667, abs=0.01)
+        assert got.pixels_per_frame == 2
+
+    def test_result_is_always_on_the_ladder(self):
+        ladder = {round(c.pixels_per_second, 3) for c in crisp_ladder(100)}
+        for target in range(5, 205, 5):
+            assert round(solve_crisp(target, 100).pixels_per_second, 3) in ladder
+
+    def test_adapts_to_a_slower_panel(self):
+        got = solve_crisp(30, 60)
+        assert got.pixels_per_second == pytest.approx(30.0)
+        assert got.pixels_per_frame == 1
+        assert got.frame_hold == 2
+
+    def test_speeds_beyond_the_panel_clamp_to_the_fastest_available(self):
+        got = solve_crisp(10_000, 100)
+        assert got.frame_hold == 1
+        assert got.pixels_per_frame == MAX_PIXELS_PER_FRAME
+
+    def test_steppiness_labels_are_sane(self):
+        assert solve_crisp(100, 100).steppiness == "smooth"
+        assert crisp_ladder(100)[0].steppiness == "stepped"
+
+
+class TestRefreshFromDisplayManager:
+    """A plugin sees only its own config section, so the display manager is the
+    authoritative source for the panel's refresh rate."""
+
+    class DM:
+        def __init__(self, hz):
+            self.refresh_hz = hz
+            self.hold = None
+
+        def set_frame_hold(self, refreshes):
+            self.hold = refreshes
+
+    def test_uses_the_display_manager_rate(self):
+        dm = self.DM(60.0)
+        s = configure(FakeHelper(), {"display_options": {"scroll_pixels_per_second": 30.0}},
+                      display_manager=dm)
+        # 30px/s on a 60Hz panel is 1px every 2nd refresh, exactly.
+        assert s.pixels_per_second == pytest.approx(30.0)
+        assert s.frame_hold == 2
+
+    def test_explicit_refresh_hz_wins_over_the_display_manager(self):
+        dm = self.DM(60.0)
+        s = configure(FakeHelper(), {"display_options": {"scroll_pixels_per_second": 25.0}},
+                      display_manager=dm, refresh_hz=100)
+        assert s.frame_hold == 4, "25px/s at 100Hz is 1px every 4th refresh"
+
+    def test_missing_attribute_falls_back_to_the_default(self):
+        class Bare:
+            def set_frame_hold(self, refreshes):
+                self.hold = refreshes
+
+        bare = Bare()
+        s = configure(FakeHelper(), {"display_options": {"scroll_pixels_per_second": 50.0}},
+                      display_manager=bare)
+        assert s.frame_hold == 2, "assumed 100Hz"
+
+    def test_reported_settings_describe_the_display_manager_rate(self):
+        """Without snapping, nothing downstream corrects a wrong refresh rate.
+
+        The rate used to be read *after* resolve() had already filled in
+        target_fps, pixels_per_frame and the judder warning from the 100Hz
+        default -- so on a 60Hz panel every one of those described 100Hz, and
+        set_target_fps() paced the helper to 100 FPS.
+        """
+        dm = self.DM(60.0)
+        helper = FakeHelper()
+        s = configure(helper, {"display_options": {"scroll_pixels_per_second": 30.0}},
+                      display_manager=dm, snap_to_crisp=False)
+
+        assert s.target_fps == pytest.approx(60.0)
+        assert s.pixels_per_frame == pytest.approx(0.5), "30px/s over 60 frames"
+        assert helper.target_fps == pytest.approx(60.0)
+
+    def test_judder_warning_is_computed_at_the_real_refresh_rate(self):
+        dm = self.DM(60.0)
+        # 60px/s is exactly 1px per refresh at 60Hz -- crisp, no warning. At
+        # the 100Hz default it is 0.6px per refresh and would be flagged.
+        s = configure(FakeHelper(), {"display_options": {"scroll_pixels_per_second": 60.0}},
+                      display_manager=dm, snap_to_crisp=False)
+        assert s.warning is None, s.warning
+
+    def test_global_config_supplies_the_rate_without_a_display_manager(self):
+        s = configure(
+            FakeHelper(),
+            {"display_options": {"scroll_pixels_per_second": 30.0}},
+            {"display": {"hardware": {"limit_refresh_rate_hz": 60}}},
+            snap_to_crisp=False,
+        )
+        assert s.target_fps == pytest.approx(60.0)
+
+
+class TestFrameHoldIsReportedNotApplied:
+    """configure() reports the hold; the caller applies it when it scrolls.
+
+    The hold belongs to a scroll, not to a plugin's lifetime -- plugins share
+    one display manager, so one set at construction is reset the moment any
+    other plugin stops scrolling.
+    """
+
+    class RecordingDM:
+        refresh_hz = 100.0
+
+        def __init__(self):
+            self.calls = []
+
+        def set_scrolling_state(self, is_scrolling, frame_hold=1):
+            self.calls.append((is_scrolling, frame_hold))
+
+        def set_frame_hold(self, refreshes):
+            self.calls.append(("set_frame_hold", refreshes))
+
+    def test_configure_does_not_touch_the_display_manager(self):
+        dm = self.RecordingDM()
+        settings = configure(
+            FakeHelper(), {"display_options": {"scroll_pixels_per_second": 25.0}},
+            display_manager=dm)
+        assert dm.calls == [], "configure() must not apply the hold itself"
+        assert settings.frame_hold == 4, "but it must report what to apply"

test/test_scroll_helper.py

@@ -11,7 +11,11 @@ import time
 from unittest.mock import patch
 from PIL import Image
 
-from src.common.scroll_helper import ScrollHelper
+from src.common.scroll_helper import (
+    ScrollHelper,
+    format_frame_stats,
+    frame_stats,
+)
 
 
 DISPLAY_W = 64
@@ -315,3 +319,77 @@ class TestGetScrollInfo:
         helper.scroll_position = 42.0
         info = helper.get_scroll_info()
         assert info["scroll_position"] == 42.0
+
+
+class TestFrameStatsPercentiles:
+    """The stats line is the instrument this whole scroll change is measured
+    with, so its median and p95 have to be the real ones.
+
+    Both are also thresholds: stalls are counted at 1.5x the median and skips
+    at 0.5x, so an off-by-one in the median biases the counts as well as the
+    printed numbers.
+    """
+
+    # 100 samples of 1..100ms. True median 50.5ms (the mean of the two middle
+    # samples, not the upper one at 51ms); nearest-rank p95 is the 95th
+    # sample at 95ms, not the 96th at 96ms.
+    HUNDRED = [i / 1000.0 for i in range(1, 101)]
+
+    def test_even_window_median_averages_both_middle_samples(self):
+        assert frame_stats(self.HUNDRED)["median"] == pytest.approx(0.0505)
+
+    def test_p95_uses_nearest_rank(self):
+        assert frame_stats(self.HUNDRED)["p95"] == pytest.approx(0.095)
+
+    def test_odd_window_median_is_the_middle_sample(self):
+        times = [i / 1000.0 for i in range(1, 102)]  # 101 samples
+        assert frame_stats(times)["median"] == pytest.approx(0.051)
+
+    def test_single_sample_window_does_not_index_out_of_range(self):
+        stats = frame_stats([0.010])
+        assert stats["median"] == pytest.approx(0.010)
+        assert stats["p95"] == pytest.approx(0.010)
+        assert stats["min"] == stats["max"] == pytest.approx(0.010)
+
+    def test_two_sample_window(self):
+        stats = frame_stats([0.010, 0.020])
+        assert stats["median"] == pytest.approx(0.015)
+        assert stats["p95"] == pytest.approx(0.020)
+
+    def test_input_order_does_not_matter(self):
+        assert frame_stats(list(reversed(self.HUNDRED))) == frame_stats(self.HUNDRED)
+
+    def test_caller_window_is_not_mutated(self):
+        times = [0.030, 0.010, 0.020]
+        frame_stats(times)
+        assert times == [0.030, 0.010, 0.020]
+
+    def test_stall_threshold_follows_the_median(self):
+        # Ten 10ms frames and two 30ms stalls: median 10ms, so >15ms is a
+        # stall -- exactly the two.
+        stats = frame_stats([0.010] * 10 + [0.030] * 2)
+        assert stats["stalls"] == 2
+        assert stats["skips"] == 0
+
+    def test_skips_are_frames_that_never_reached_the_panel(self):
+        stats = frame_stats([0.010] * 10 + [0.002] * 3)
+        assert stats["skips"] == 3
+        assert stats["stalls"] == 0
+
+    def test_fps_is_the_reciprocal_of_the_mean(self):
+        assert frame_stats([0.010] * 50)["fps"] == pytest.approx(100.0)
+
+    def test_formatted_line_reports_the_corrected_values(self):
+        line = format_frame_stats(self.HUNDRED)
+        assert "median 50.50ms" in line, line
+        assert "p95 95.00ms" in line, line
+        assert "over 100 frames" in line, line
+
+    def test_log_frame_rate_emits_the_line_and_clears_the_window(self, helper):
+        helper._window = [0.010] * 20
+        helper.last_fps_log_time = 0.0  # force the 5s boundary
+        with patch.object(helper.logger, "info") as info:
+            helper.log_frame_rate()
+        assert info.called
+        assert "Scroll frame stats" in info.call_args[0][0]
+        assert helper._window == []

test/test_sports_card.py

@@ -1,195 +0,0 @@
-"""The card helpers the eight scoreboards now share.
-
-These bodies lived in eight byte-identical copies. Moving them here means one
-fix reaches every scoreboard — and that a mistake does too, which is what this
-file guards. Each case below is one the plugins' own code already handled; the
-point is that it keeps handling it.
-
-The functions take ``config``/``logger``/``fonts`` as arguments rather than
-reading them off an instance, so a plugin keeps its method and delegates the
-body. That is what let all eight adopt this with byte-identical renders.
-"""
-
-import logging
-import json
-import os
-
-import pytest
-
-from src.common import sports_card as C
-
-
-@pytest.fixture
-def log():
-    return logging.getLogger("test_sports_card")
-
-
-class TestSettingsLookup:
-    def test_reads_the_scroll_card_block(self):
-        cfg = {"scroll_card": {"vs_text": "@"}}
-        assert C.scroll_card_option(cfg, "vs_text", "VS") == "@"
-
-    @pytest.mark.parametrize("cfg", [None, {}, {"scroll_card": None},
-                                     {"scroll_card": {"vs_text": None}}])
-    def test_missing_or_null_falls_back(self, cfg):
-        """A null in config means "unset", not "empty string"."""
-        assert C.scroll_card_option(cfg, "vs_text", "VS") == "VS"
-
-    def test_upcoming_center_rejects_unknown_modes(self):
-        for bad in ("sideways", "", None, 7):
-            assert C.upcoming_center_mode({"scroll_card": {"upcoming_center": bad}}) == "vs"
-        assert C.upcoming_center_mode({"scroll_card": {"upcoming_center": "DATE_TIME"}}) == "date_time"
-
-
-class TestColour:
-    def test_rgb_list_and_hex_both_work(self):
-        assert C.element_color({"customization": {"score_text": {"text_color": [1, 2, 3]}}},
-                               "score_text") == (1, 2, 3)
-        assert C.element_color({"customization": {"score_text": {"text_color": "#ff8000"}}},
-                               "score_text") == (255, 128, 0)
-
-    @pytest.mark.parametrize("value", ["nope", "#fff", [1, 2], None, ["a", "b", "c"]])
-    def test_unusable_colour_falls_back(self, value):
-        cfg = {"customization": {"score_text": {"text_color": value}}}
-        assert C.element_color(cfg, "score_text", (9, 9, 9)) == (9, 9, 9)
-
-    def test_coerce_rgb_clamps_rather_than_rejecting(self):
-        assert C.coerce_rgb([300, -5, 20], (0, 0, 0)) == (255, 0, 20)
-
-    def test_coerce_rgb_refuses_a_three_character_string(self):
-        """"123" would otherwise iterate into three digits and yield a colour."""
-        assert C.coerce_rgb("123", (7, 7, 7)) == (7, 7, 7)
-
-    def test_font_colour_is_resolved_by_identity(self):
-        a, b = object(), object()
-        cfg = {"customization": {"score_text": {"text_color": [4, 5, 6]}}}
-        assert C.font_color(cfg, {"score": a, "team": b}, a) == (4, 5, 6)
-
-    def test_a_shared_face_gives_up_rather_than_guessing(self):
-        """One object used for two elements has no single right colour."""
-        shared = object()
-        cfg = {"customization": {"score_text": {"text_color": [4, 5, 6]}}}
-        assert C.font_color(cfg, {"score": shared, "team": shared}, shared) == (255, 255, 255)
-
-
-class TestFavourites:
-    GAME = {"home_abbr": "TB", "away_abbr": "NO", "home_score": "21", "away_score": "17"}
-
-    def test_win_loss_and_tie(self):
-        cfg = {"favorite_teams": ["TB"]}
-        assert C.favorite_result(cfg, self.GAME) == "win"
-        assert C.favorite_result({"favorite_teams": ["NO"]}, self.GAME) == "loss"
-        tied = dict(self.GAME, home_score="3", away_score="3")
-        assert C.favorite_result(cfg, tied) == "tie"
-
-    def test_no_verdict_without_exactly_one_favourite_side(self):
-        assert C.favorite_result({}, self.GAME) is None
-        assert C.favorite_result({"favorite_teams": ["TB", "NO"]}, self.GAME) is None
-        assert C.favorite_result({"favorite_teams": ["SEA"]}, self.GAME) is None
-
-    def test_unusable_scores_give_no_verdict(self):
-        bad = dict(self.GAME, home_score="x")
-        assert C.favorite_result({"favorite_teams": ["TB"]}, bad) is None
-
-    def test_nested_payload_shape_is_read_too(self):
-        game = {"home_team": {"abbrev": "TB", "score": 9},
-                "away_team": {"abbrev": "NO", "score": 2}}
-        assert C.side_score(game, "home") == 9
-        assert C.side_is_favorite(game, "home", {"TB"}) is True
-
-    def test_matches_on_id_where_abbreviations_collide(self):
-        """NRL keys favourites by ESPN id; abbreviations are not unique there."""
-        game = {"home_abbr": "SYD", "home_id": "4321"}
-        assert C.side_is_favorite(game, "home", {"4321"}) is True
-
-    def test_game_and_config_favourites_are_both_used(self):
-        """Games carry resolved dynamic groups; config catches later edits."""
-        game = dict(self.GAME, favorite_teams=["NO"], league="nfl")
-        assert set(C.favorite_teams_for({"nfl": {"favorite_teams": ["TB"]}}, game)) == {"NO", "TB"}
-
-
-class TestDateAndTime:
-    def test_date_formats(self, log):
-        for fmt, want in [("abbrev", "Sep 5"), ("numeric", "9/5"),
-                          ("day_first", "5 Sep"), ("numeric_day_first", "5/9")]:
-            cfg = {"scroll_card": {"date_format": fmt}}
-            assert C.format_game_date(cfg, log, "9/5") == want
-
-    @pytest.mark.parametrize("raw", ["", "garbage", "13/40", "no/slash/here"])
-    def test_unparseable_dates_pass_through(self, log, raw):
-        assert C.format_game_date({}, log, raw) == raw.strip()
-
-    def test_24h_conversion(self):
-        cfg = {"scroll_card": {"time_format": "24h"}}
-        assert C.format_game_time(cfg, "7:30 PM") == "19:30"
-        assert C.format_game_time(cfg, "12:00 AM") == "00:00"
-        assert C.format_game_time(cfg, "12:15 PM") == "12:15"
-
-    def test_12h_is_left_alone_and_junk_survives(self):
-        assert C.format_game_time({}, "7:30 PM") == "7:30 PM"
-        assert C.format_game_time({"scroll_card": {"time_format": "24h"}}, "soon") == "soon"
-
-    def test_a_bad_timezone_falls_back_to_utc(self, log):
-        """A typo in config should not blank the card."""
-        from datetime import timezone
-        assert C.card_tzinfo({"timezone": "Not/AZone"}, log) is timezone.utc
-
-
-class TestFontSizing:
-    def test_snaps_to_the_faces_pixel_grid(self):
-        assert C.crisp_size("4x6-font.ttf", 6) == 7        # 7px grid
-        assert C.crisp_size("PressStart2P-Regular.ttf", 10) == 8
-        assert C.crisp_size("PressStart2P-Regular.ttf", 13) == 16
-
-    def test_an_unknown_face_is_never_second_guessed(self):
-        assert C.crisp_size("SomeUserFont.ttf", 11) == 11
-
-    def test_aliases_resolve_before_the_grid_lookup(self):
-        assert C.crisp_size("four_by_six", 6) == C.crisp_size("4x6-font.ttf", 6)
-
-    @pytest.mark.parametrize("desired", [0, -3, None])
-    def test_unusable_sizes_pass_through_without_raising(self, desired):
-        """None reached this in the field; football's variant raised TypeError."""
-        assert C.crisp_size("4x6-font.ttf", desired) == desired
-
-    def test_schema_cache_is_keyed_per_schema_not_globally(self, tmp_path):
-        """Two plugins declaring different defaults must not share an answer."""
-        a, b = tmp_path / "a.json", tmp_path / "b.json"
-        for path, size in ((a, 11), (b, 22)):
-            path.write_text(json.dumps({"properties": {"customization": {"properties": {
-                "score_text": {"properties": {"font_size": {"default": size}}}}}}}))
-        assert C.schema_font_size(str(a), "score_text") == 11
-        assert C.schema_font_size(str(b), "score_text") == 22
-
-    def test_a_missing_schema_is_not_an_error(self, tmp_path):
-        assert C.schema_font_size(str(tmp_path / "nope.json"), "score_text") is None
-
-    def test_a_configured_size_matching_the_schema_default_is_not_a_choice(self, tmp_path):
-        """The web UI writes the whole default block on every save, so
-        font_size == schema default carries no intent and must not pin the
-        install to an off-grid size forever."""
-        schema = tmp_path / "s.json"
-        schema.write_text(json.dumps({"properties": {"customization": {"properties": {
-            "score_text": {"properties": {"font_size": {"default": 10}}}}}}}))
-        got = C.resolve_font_size(str(schema), {"font_size": 10}, "score_text", 10,
-                                  "PressStart2P-Regular.ttf")
-        assert got == 8, "a default-valued size should snap to the grid"
-
-    def test_a_real_choice_wins(self, tmp_path):
-        schema = tmp_path / "s.json"
-        schema.write_text(json.dumps({"properties": {"customization": {"properties": {
-            "score_text": {"properties": {"font_size": {"default": 10}}}}}}}))
-        got = C.resolve_font_size(str(schema), {"font_size": 13}, "score_text", 10,
-                                  "PressStart2P-Regular.ttf")
-        assert got == 13, "an explicit size the user chose is not second-guessed"
-
-
-class TestTables:
-    def test_every_font_key_maps_to_an_element(self):
-        assert set(C.ELEMENT_FOR_FONT) == {"score", "time", "team", "status", "detail", "rank"}
-
-    def test_result_colours_cover_every_verdict(self):
-        assert set(C.FAVORITE_RESULT_COLOR_DEFAULTS) == {"win", "loss", "tie"}
-
-    def test_month_and_weekday_tables_are_complete(self):
-        assert len(C.MONTH_ABBR) == 12 and len(C.WEEKDAY_ABBR) == 7

test/test_sports_game_renderer.py

@@ -1,258 +0,0 @@
-"""The shared card geometry, exercised against a host that supplies only what
-the mixin's contract names.
-
-The point of these is the contract, not the arithmetic. The mixin reaches for
-``display_width``, ``fonts``, ``config`` and six ``sports_card`` delegations
-through ``self``, and the eight plugins are what actually provide them. A
-stub host that provides exactly the documented surface and nothing else is
-what catches the mixin quietly growing a dependency the plugins do not have.
-"""
-
-import pytest
-from PIL import Image, ImageDraw, ImageFont
-
-from src.common.sports_game_renderer import SportsGameRendererMixin
-
-
-class Host(SportsGameRendererMixin):
-    """The documented contract, and not one attribute more."""
-
-    def __init__(self, width=128, height=32, config=None, scroll=None):
-        self.display_width = width
-        self.display_height = height
-        self.config = config or {}
-        self.logger = _Logger()
-        self._team_rankings_cache = {}
-        self._scroll = scroll or {}
-        font = ImageFont.load_default()
-        self.fonts = {'score': font, 'time': font, 'detail': font}
-        self.drawn = []
-
-    # -- the six sports_card delegations the mixin calls --
-    def _scroll_card_option(self, key, default=None):
-        return self._scroll.get(key, default)
-
-    def _upcoming_center_mode(self):
-        return self._scroll.get('upcoming_center', 'vs')
-
-    def _vs_text(self):
-        return self._scroll.get('vs_text', 'VS')
-
-    def _element_color(self, element):
-        return (255, 255, 255)
-
-    def _format_game_date(self, raw, game):
-        return raw
-
-    def _format_game_time(self, raw):
-        return raw
-
-    # -- the one hook whose body genuinely varies per plugin --
-    def _draw_text_with_outline(self, draw, text, position, font,
-                                fill=None, outline_color=(0, 0, 0)):
-        self.drawn.append((text, position))
-
-
-class _Logger:
-    def debug(self, *a, **k):
-        pass
-
-
-def _draw():
-    return ImageDraw.Draw(Image.new("RGB", (256, 64)))
-
-
-class TestCenterGap:
-    def test_explicit_center_gap_wins_outright(self):
-        assert Host(scroll={'center_gap': 31})._center_gap_width() == 31
-
-    def test_explicit_zero_restores_edge_to_edge_logos(self):
-        # 0 is a real setting, not a falsy miss -- the guard is `>= 0`.
-        assert Host(scroll={'center_gap': 0})._center_gap_width() == 0
-
-    def test_otherwise_it_scales_with_card_width_within_the_clamp(self):
-        h = Host(width=512)
-        # 512 * 0.28 = 143, clamped to the 40px ceiling.
-        assert h._center_gap_width() >= h.CENTER_GAP_MIN_PX
-
-    def test_the_gap_never_ends_up_narrower_than_the_score(self):
-        # This is the bug the measurement exists to prevent: a derived gap
-        # smaller than the rendered score drew the score over the logos.
-        h = Host(width=64)
-        assert h._center_gap_width() >= h._score_reserve_width()
-
-    def test_a_junk_ratio_falls_back_to_the_floor(self):
-        h = Host(scroll={'center_gap_ratio': 'wide'})
-        assert h._center_gap_width() == h.CENTER_GAP_MIN_PX
-
-
-class TestNonFiniteSettings:
-    """inf reaches int() and raises OverflowError, which the old
-    `except (TypeError, ValueError)` did not catch -- so one bad config value
-    aborted the entire card render rather than falling back."""
-
-    @pytest.mark.parametrize("bad", [float("inf"), float("-inf")])
-    def test_a_non_finite_center_gap_falls_back(self, bad):
-        h = Host(scroll={'center_gap': bad})
-        assert h._center_gap_width() >= h.CENTER_GAP_MIN_PX
-
-    @pytest.mark.parametrize("bad", [float("inf"), float("-inf"), float("nan")])
-    def test_a_non_finite_ratio_falls_back_to_the_floor(self, bad):
-        h = Host(scroll={'center_gap_ratio': bad})
-        assert h._center_gap_width() == h.CENTER_GAP_MIN_PX
-
-    @pytest.mark.parametrize("bad", [float("inf"), float("-inf")])
-    def test_non_finite_clamp_bounds_fall_back(self, bad):
-        h = Host(scroll={'center_gap_min': bad, 'center_gap_max': bad})
-        assert h._center_gap_width() == h.CENTER_GAP_MIN_PX
-
-    @pytest.mark.parametrize("bad", [float("inf"), float("-inf"), "inf", "-inf", "nan"])
-    def test_a_non_finite_layout_offset_gives_the_default(self, bad):
-        cfg = {'customization': {'layout': {'score': {'x_offset': bad}}}}
-        assert Host(config=cfg)._layout_offset('score', 'x_offset', 7) == 7
-
-    def test_a_finite_value_is_still_honoured(self):
-        # The guard must not swallow ordinary settings.
-        assert Host(scroll={'center_gap': 31})._center_gap_width() == 31
-        cfg = {'customization': {'layout': {'score': {'x_offset': -3}}}}
-        assert Host(config=cfg)._layout_offset('score', 'x_offset', 7) == -3
-
-
-class TestScoreReserve:
-    def test_it_measures_the_probe_plus_both_gutters(self):
-        h = Host()
-        assert h._score_reserve_width() > 2 * h._SCORE_LOGO_GUTTER_PX
-
-    def test_a_wider_probe_reserves_more(self):
-        class Wide(Host):
-            _SCORE_PROBE = "000-000"
-        assert Wide()._score_reserve_width() > Host()._score_reserve_width()
-
-    def test_an_unmeasurable_font_reserves_nothing_rather_than_raising(self):
-        h = Host()
-        h.fonts = {'score': object()}
-        assert h._score_reserve_width() == 0
-
-
-class TestLogoSlot:
-    def test_the_slot_is_what_is_left_after_the_gap(self):
-        h = Host(width=128, scroll={'center_gap': 40})
-        assert h._logo_slot_width() == 44
-
-    def test_it_is_not_capped_at_the_card_height(self):
-        # The height cap is what froze logos at 46px on a 128px card.
-        h = Host(width=512, height=32, scroll={'center_gap': 40})
-        assert h._logo_slot_width() > h.display_height
-
-    def test_a_gap_wider_than_the_card_still_leaves_a_usable_slot(self):
-        assert Host(width=64, scroll={'center_gap': 200})._logo_slot_width() == 8
-
-    def test_the_cache_key_is_scoped_to_the_slot_not_just_the_name(self):
-        # One cache dict is shared by renderers of different card widths.
-        narrow = Host(width=64, scroll={'center_gap': 20})._logo_cache_key("NYY")
-        wide = Host(width=256, scroll={'center_gap': 20})._logo_cache_key("NYY")
-        assert narrow != wide
-
-
-class TestLayoutOffset:
-    def _host(self, value):
-        return Host(config={'customization': {'layout': {'score': {'x_offset': value}}}})
-
-    def test_it_reads_the_same_block_as_the_full_screen_scorebug(self):
-        assert self._host(5)._layout_offset('score', 'x_offset') == 5
-
-    def test_a_string_offset_from_the_web_ui_is_coerced(self):
-        assert self._host("-3")._layout_offset('score', 'x_offset') == -3
-
-    def test_a_bool_is_not_silently_an_offset_of_one(self):
-        assert self._host(True)._layout_offset('score', 'x_offset', 9) == 9
-
-    @pytest.mark.parametrize("cfg", [{}, {'customization': {}},
-                                     {'customization': {'layout': {}}}])
-    def test_a_missing_block_gives_the_default(self, cfg):
-        assert Host(config=cfg)._layout_offset('score', 'x_offset', 7) == 7
-
-    def test_an_unparseable_offset_gives_the_default(self):
-        assert self._host("left")._layout_offset('score', 'x_offset', 4) == 4
-
-
-class TestUpcomingCenter:
-    def test_none_draws_nothing(self):
-        h = Host(scroll={'upcoming_center': 'none'})
-        h._draw_upcoming_center(_draw(), {})
-        assert h.drawn == []
-
-    def test_vs_is_the_default_and_never_a_score(self):
-        # An upcoming game has not started; the extractor's 0-0 is noise.
-        h = Host()
-        h._draw_upcoming_center(_draw(), {'home_score': 0, 'away_score': 0})
-        assert [t for t, _ in h.drawn] == ['VS']
-
-    def test_an_empty_vs_string_draws_nothing(self):
-        h = Host(scroll={'vs_text': ''})
-        h._draw_upcoming_center(_draw(), {})
-        assert h.drawn == []
-
-    def test_date_time_stacks_both_lines(self):
-        h = Host(scroll={'upcoming_center': 'date_time'})
-        h._draw_upcoming_center(_draw(), {'game_date': 'Sep 19', 'game_time': '7:00 PM'})
-        assert [t for t, _ in h.drawn] == ['Sep 19', '7:00 PM']
-
-    def test_hiding_both_lines_draws_nothing(self):
-        h = Host(scroll={'upcoming_center': 'date_time',
-                         'show_date': False, 'show_time': False})
-        h._draw_upcoming_center(_draw(), {'game_date': 'Sep 19', 'game_time': '7:00 PM'})
-        assert h.drawn == []
-
-
-class TestUpcomingStatus:
-    def test_time_on_top_and_date_below_by_default(self):
-        h = Host()
-        h._draw_upcoming_game_status(_draw(), {'game_date': 'Sep 19', 'game_time': '7:00 PM'})
-        assert [t for t, _ in h.drawn] == ['7:00 PM', 'Sep 19']
-
-    def test_swap_date_time_reverses_them(self):
-        h = Host(scroll={'swap_date_time': True})
-        h._draw_upcoming_game_status(_draw(), {'game_date': 'Sep 19', 'game_time': '7:00 PM'})
-        assert [t for t, _ in h.drawn] == ['Sep 19', '7:00 PM']
-
-    def test_it_stays_out_of_the_way_when_the_centre_already_has_them(self):
-        # Otherwise the date and time print twice on the same card.
-        h = Host(scroll={'upcoming_center': 'date_time'})
-        h._draw_upcoming_game_status(_draw(), {'game_date': 'Sep 19', 'game_time': '7:00 PM'})
-        assert h.drawn == []
-
-    def test_the_bottom_line_is_measured_not_a_fixed_offset(self):
-        # A fixed -7 ran "Sep 19" past the card wherever the detail font is
-        # 10px rather than 6px.
-        h = Host(height=64)
-        h._draw_upcoming_game_status(_draw(), {'game_date': 'Sep 19', 'game_time': '7:00 PM'})
-        bottom_y = h.drawn[1][1][1]
-        assert 0 <= bottom_y < h.display_height
-
-
-class TestRankings:
-    def test_set_rankings_cache_replaces_the_cache(self):
-        h = Host()
-        h.set_rankings_cache({'UGA': 1})
-        assert h._team_rankings_cache == {'UGA': 1}
-
-
-class TestContract:
-    def test_the_mixin_carries_no_state_of_its_own(self):
-        # Adoption must be one line on the class statement; a mixin with an
-        # __init__ would force eight constructors to cooperate.
-        assert '__init__' not in SportsGameRendererMixin.__dict__
-
-    def test_a_host_providing_the_documented_surface_needs_nothing_more(self):
-        # Host defines exactly what the module docstring names. If the mixin
-        # grows a new self.* dependency, this is what fails.
-        h = Host()
-        h._center_gap_width()
-        h._logo_slot_width()
-        h._logo_cache_key("X")
-        h._layout_offset('score', 'x_offset')
-        h._upcoming_date_and_time({})
-        h._draw_upcoming_center(_draw(), {})
-        h._draw_upcoming_game_status(_draw(), {})
-        h.set_rankings_cache({})

test/test_sports_shared.py

@@ -1,321 +0,0 @@
-"""The shared sports.py mixins: their host contract, and _plugin_dir.
-
-Two things are worth testing here and the rest is not. The 45 method bodies
-moved verbatim from the plugins, so they are covered by the plugins' own tests
-and by 176 byte-identical safety-harness renders. What is genuinely new is:
-
-1. The contract. Every ``self.<CONSTANT>`` a mixin reads must be defined on the
-   mixin, or a host that does not happen to declare it raises AttributeError at
-   runtime. Two were missed on the first pass (_QUALITY_CHOICES and
-   _RANKING_COVERAGE_SECONDS); the eight plugins all declare them, so nothing
-   failed -- it would only have bitten a ninth. The test derives the list rather
-   than restating it, so the next omission fails here instead of in the field.
-
-2. ``_plugin_dir``. This is the only line of genuinely new logic in the move. In
-   sports.py these methods found config_schema.json with ``__file__``; here that
-   is src/common/, so the plugin directory has to be recovered from the
-   instance -- and getting it wrong is silent, costing grid-snapped font sizes
-   (measured at 81% anti-aliased edges) rather than raising.
-"""
-
-import ast
-import os
-import sys
-import types
-from abc import ABC
-
-import pytest
-
-from src.common import sports_shared
-from src.common.sports_shared import (
-    SportsCoreSharedMixin, SportsLiveSharedMixin, SportsRecentSharedMixin)
-
-MIXINS = (SportsCoreSharedMixin, SportsLiveSharedMixin, SportsRecentSharedMixin)
-
-
-def _constants_read_by_mixins():
-    """Every ALL-CAPS ``self.X`` the mixin bodies read, found by parsing them."""
-    tree = ast.parse(open(sports_shared.__file__).read())
-    names = set()
-    for node in ast.walk(tree):
-        if (isinstance(node, ast.Attribute)
-                and isinstance(node.value, ast.Name)
-                and node.value.id == "self"
-                and node.attr.upper() == node.attr):
-            names.add(node.attr)
-    return names
-
-
-class TestHostContract:
-    def test_every_constant_read_is_also_defined(self):
-        # Otherwise a host that does not declare it raises AttributeError the
-        # first time the code path runs -- which for these is mid-render.
-        missing = sorted(
-            name for name in _constants_read_by_mixins()
-            if not any(hasattr(m, name) for m in MIXINS))
-        assert missing == [], (
-            f"read but never defined on a mixin: {missing}. Give each a default "
-            f"on SportsCoreSharedMixin and document it in the module docstring.")
-
-    @pytest.mark.parametrize("name,expected", [
-        ("_QUALITY_CHOICES", frozenset({"any", "ranked"})),
-        ("_RANKING_COVERAGE_SECONDS", 3600),
-        ("_SCORE_PROBE_TEXT", "00-00"),
-        ("_FONT_DESIGN_HEIGHT", 32),
-    ])
-    def test_defaults_match_what_the_plugins_ship(self, name, expected):
-        # The eight plugins declare their own copies, which shadow these. The
-        # values must still agree, or a ninth plugin inheriting the default
-        # behaves differently from the eight.
-        assert getattr(SportsCoreSharedMixin, name) == expected
-
-    def test_only_the_recent_mixin_carries_a_constructor(self):
-        # SportsCore and SportsLive keep their own __init__ -- those differ per
-        # plugin. SportsRecent.__init__ was one of the 48 byte-identical bodies,
-        # so it moved with the rest; that is deliberate, not an oversight.
-        assert "__init__" not in SportsCoreSharedMixin.__dict__
-        assert "__init__" not in SportsLiveSharedMixin.__dict__
-        assert "__init__" in SportsRecentSharedMixin.__dict__
-
-    def test_the_recent_constructor_still_chains_to_the_host(self):
-        """Its zero-arg super() binds to where it is DEFINED, not where it is used.
-
-        Moving a body containing bare ``super()`` is the one move that can
-        change meaning: the compiler closes over __class__ = the defining class,
-        so after the move that is SportsRecentSharedMixin rather than the
-        plugin's SportsRecent. It still works only because the mixin is listed
-        first, leaving the host class next in the MRO -- adopt it in the other
-        order and the chain silently skips the host's __init__.
-        """
-        calls = []
-
-        class Host:
-            def __init__(self, config, display_manager, cache_manager, logger, sport_key):
-                calls.append(sport_key)
-                self.mode_config = {}
-
-        class Recent(SportsRecentSharedMixin, Host):
-            pass
-
-        inst = Recent({}, None, None, None, "nhl")
-        assert calls == ["nhl"], "the host constructor must still run"
-        assert inst.current_game_index == 0
-        assert inst.update_interval == 3600
-        assert inst._zero_clock_timestamps == {}
-
-    def test_adopting_the_recent_mixin_second_would_skip_the_host(self):
-        # The failure mode the ordering above prevents, pinned so nobody
-        # "tidies" the base list.
-        calls = []
-
-        class Host:
-            def __init__(self, *a):
-                calls.append(a)
-                self.mode_config = {}
-
-        class Wrong(Host, SportsRecentSharedMixin):
-            pass
-
-        Wrong({}, None, None, None, "nhl")
-        # Host.__init__ wins and the mixin's setup never runs at all.
-        assert not hasattr(Wrong({}, None, None, None, "nhl"), "current_game_index")
-
-
-class _Host(SportsCoreSharedMixin):
-    pass
-
-
-def _write_plugin(tmp_path, name="fakeplug", schema=True):
-    """A throwaway package on sys.path, with or without a config_schema.json."""
-    d = tmp_path / name
-    d.mkdir()
-    (d / "__init__.py").write_text("")
-    (d / "mod.py").write_text("class Leaf:\n    pass\n")
-    if schema:
-        (d / "config_schema.json").write_text(
-            '{"properties": {"customization": {"properties": '
-            '{"score": {"properties": {"font_size": {"default": 16}}}}}}}')
-    return d
-
-
-class TestPluginDir:
-    def test_it_finds_the_directory_holding_config_schema_json(self, tmp_path, monkeypatch):
-        d = _write_plugin(tmp_path)
-        monkeypatch.syspath_prepend(str(tmp_path))
-        mod = __import__("fakeplug.mod", fromlist=["Leaf"])
-        host = type("H", (mod.Leaf, SportsCoreSharedMixin), {})()
-        assert host._plugin_dir() == str(d)
-
-    def test_a_class_built_by_type_still_resolves(self, tmp_path, monkeypatch):
-        # SportsCore is an ABC, so type(name, bases, ns) reports __module__ as
-        # "abc" rather than the plugin -- which is exactly what the plugins'
-        # own tests build. Walking the MRO is what steps past it.
-        d = _write_plugin(tmp_path, "abcplug")
-        monkeypatch.syspath_prepend(str(tmp_path))
-        mod = __import__("abcplug.mod", fromlist=["Leaf"])
-
-        class Base(SportsCoreSharedMixin, mod.Leaf, ABC):
-            pass
-
-        synthetic = type("Probe", (Base,), {})
-        assert synthetic.__module__ == "abc", "precondition: the trap this guards"
-        assert synthetic.__new__(synthetic)._plugin_dir() == str(d)
-
-    def test_it_returns_none_when_no_schema_is_anywhere_on_the_mro(self, tmp_path, monkeypatch):
-        d = _write_plugin(tmp_path, "noschema", schema=False)
-        monkeypatch.syspath_prepend(str(tmp_path))
-        mod = __import__("noschema.mod", fromlist=["Leaf"])
-        host = type("H", (mod.Leaf, SportsCoreSharedMixin), {})()
-        # None rather than a wrong guess: _schema_font_size then caches empty
-        # and every element keeps its own default.
-        assert host._plugin_dir() is None
-
-    def test_it_never_returns_the_core_module_directory(self):
-        # The bug this replaced: __file__ pointed at src/common/, so the schema
-        # was never found and font sizes silently stopped snapping to the grid.
-        host = _Host()
-        core_common = os.path.dirname(os.path.abspath(sports_shared.__file__))
-        assert host._plugin_dir() != core_common
-
-    def test_a_module_with_no_file_is_skipped_not_crashed_on(self, monkeypatch):
-        # Namespace packages and some frozen/dynamic modules have no __file__.
-        ghost = types.ModuleType("ghost_no_file")
-        if hasattr(ghost, "__file__"):
-            del ghost.__file__
-        monkeypatch.setitem(sys.modules, "ghost_no_file", ghost)
-        cls = type("H", (SportsCoreSharedMixin,), {"__module__": "ghost_no_file"})
-        assert cls.__new__(cls)._plugin_dir() is None
-
-
-class TestSchemaFontSize:
-    def test_it_reads_the_plugin_schema_not_the_cores(self, tmp_path, monkeypatch):
-        d = _write_plugin(tmp_path, "sizeplug")
-        monkeypatch.syspath_prepend(str(tmp_path))
-        mod = __import__("sizeplug.mod", fromlist=["Leaf"])
-        host = type("H", (mod.Leaf, SportsCoreSharedMixin), {})()
-        assert host._schema_font_size("score") == 16
-
-    def test_an_unknown_element_is_none(self, tmp_path, monkeypatch):
-        _write_plugin(tmp_path, "unkplug")
-        monkeypatch.syspath_prepend(str(tmp_path))
-        mod = __import__("unkplug.mod", fromlist=["Leaf"])
-        host = type("H", (mod.Leaf, SportsCoreSharedMixin), {})()
-        assert host._schema_font_size("nonesuch") is None
-
-    def test_an_empty_key_is_none_without_touching_the_disk(self):
-        assert _Host()._schema_font_size("") is None
-
-    def test_a_missing_schema_degrades_to_none_rather_than_raising(self, tmp_path, monkeypatch):
-        _write_plugin(tmp_path, "bareplug", schema=False)
-        monkeypatch.syspath_prepend(str(tmp_path))
-        mod = __import__("bareplug.mod", fromlist=["Leaf"])
-        host = type("H", (mod.Leaf, SportsCoreSharedMixin), {})()
-        assert host._schema_font_size("score") is None
-
-
-class _LiveHost(SportsLiveSharedMixin):
-    """The documented contract for the live mixin, and nothing else."""
-
-    def __init__(self, no_data_interval=300, stale_game_timeout=600, over=()):
-        self.no_data_interval = no_data_interval
-        self.stale_game_timeout = stale_game_timeout
-        self.game_update_timestamps = {}
-        self._over = set(over)
-
-        class _L:
-            def __getattr__(self, _n):
-                return lambda *a, **k: None
-        self.logger = _L()
-
-    def _is_game_really_over(self, game):
-        return game.get("id") in self._over
-
-
-class TestLiveMixin:
-    """These three moved to the core, so they are tested here.
-
-    They were already covered by hockey's and lacrosse's own tests, but those
-    two plugins disable live mode in their safety-harness fixtures, so the 176
-    renders never exercise this path. Testing the mixin directly means the
-    coverage no longer depends on which plugin happens to have a unit test.
-    """
-
-    def test_a_stale_game_is_dropped_and_forgotten(self):
-        h = _LiveHost(stale_game_timeout=600)
-        import time as _t
-        h.game_update_timestamps["g1"] = {"last_seen": _t.time() - 5000}
-        games = [{"id": "g1", "home_abbr": "H", "away_abbr": "A"}]
-        h._detect_stale_games(games)
-        assert games == []
-        assert "g1" not in h.game_update_timestamps, "its timestamp must go too"
-
-    def test_a_fresh_game_survives(self):
-        h = _LiveHost(stale_game_timeout=600)
-        import time as _t
-        h.game_update_timestamps["g1"] = {"last_seen": _t.time() - 5}
-        games = [{"id": "g1"}]
-        h._detect_stale_games(games)
-        assert len(games) == 1
-
-    def test_a_game_never_seen_is_not_treated_as_stale(self):
-        # last_seen 0 means "no reading", not "seen at the epoch".
-        h = _LiveHost()
-        games = [{"id": "g1"}]
-        h._detect_stale_games(games)
-        assert len(games) == 1
-
-    def test_a_game_with_no_id_is_left_alone(self):
-        h = _LiveHost()
-        games = [{"home_abbr": "H"}]
-        h._detect_stale_games(games)
-        assert len(games) == 1
-
-    def test_a_finished_game_is_dropped_even_when_fresh(self):
-        h = _LiveHost(over=("g2",))
-        games = [{"id": "g1"}, {"id": "g2"}]
-        h._detect_stale_games(games)
-        assert [g["id"] for g in games] == ["g1"]
-
-    def test_removing_several_does_not_skip_any(self):
-        # It iterates a copy for exactly this reason; mutating the live list
-        # while looping would step over the element after each removal.
-        h = _LiveHost(over=("g1", "g2", "g3"))
-        games = [{"id": "g1"}, {"id": "g2"}, {"id": "g3"}]
-        h._detect_stale_games(games)
-        assert games == []
-
-    def test_the_idle_interval_escalates_with_the_empty_streak(self):
-        h = _LiveHost(no_data_interval=60)
-        h.live_idle_max_interval = 100000
-        base = h._idle_live_interval()
-        h._empty_live_streak = 6
-        short = h._idle_live_interval()
-        h._empty_live_streak = 24
-        long = h._idle_live_interval()
-        assert base < short < long
-
-    def test_the_ceiling_bounds_even_the_unescalated_interval(self):
-        # base > ceiling is a reachable config: the two settings are
-        # independent integers with no cross-validation. Returning base
-        # unclamped made the wait SHRINK as the streak grew.
-        h = _LiveHost(no_data_interval=3600)
-        h.live_idle_max_interval = 900
-        h._empty_live_streak = 0
-        assert h._idle_live_interval() == 900
-        h._empty_live_streak = 24
-        assert h._idle_live_interval() == 900
-
-    def test_finding_a_live_game_resets_the_streak(self):
-        h = _LiveHost()
-        h._note_live_fetch(False)
-        h._note_live_fetch(False)
-        assert h._empty_live_streak == 2
-        h._note_live_fetch(True)
-        assert h._empty_live_streak == 0
-
-    def test_the_streak_starts_from_absent_state(self):
-        # The host is not required to pre-declare _empty_live_streak.
-        h = _LiveHost()
-        assert not hasattr(h, "_empty_live_streak")
-        h._note_live_fetch(False)
-        assert h._empty_live_streak == 1