perf(fetch): cache ESPN scoreboard windows without the parts nothing reads

The sports scoreboards cache their Recent/Upcoming window as the raw ESPN
response, and it stays parsed in the memory tier while fresh. Measured on
hdpi, most of it is never drawn: per-team stat leaders, athlete cards
(featuredAthletes, probables), team and event links, headlines, video
highlights and geo broadcasts. None of those keys is read by core or by any
plugin in ledmatrix-plugins.

BackgroundDataService now drops them from an ESPN /scoreboard response
before caching and delivering it (src/common/espn_payload.py), keeping
everything else. On the five hdpi windows that is 10.6MB -> 3.0MB of JSON
and ~40MB -> ~12MB of parsed objects, and parsing an expired window gets
3-4x cheaper. submit_fetch_request(slim_payload=False) caches a response
whole.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BkfgXMqqwn2w4NN7LRzhxy

.gitattributes

@@ -6,3 +6,10 @@
 # and systemd rejects CRLF unit files.
 *.sh text eol=lf
 *.service text eol=lf
+
+# Generated by scripts/build_css.py; collapsed in diffs, not hand-edited.
+web_interface/static/v3/tailwind.css linguist-generated=true
+web_interface/static/v3/plugin-frame.css linguist-generated=true
+
+# Installed as an executable (its shebang runs it) by install_service.sh.
+scripts/install/ledmatrix_refresh_units.py text eol=lf

.github/workflows/release-version-check.yml

@@ -31,7 +31,7 @@ jobs:
 
       - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
         with:
-          python-version: "3.12"
+          python-version: "3.13"
 
       # No dependencies: the script reads src/__init__.py and CHANGELOG.md only.
       - name: Assert the tag, CHANGELOG and src.__version__ agree

.github/workflows/test.yml

@@ -14,8 +14,14 @@ permissions:
 
 jobs:
   plugin-safety:
-    name: Plugin safety harness + unit tests
+    name: Plugin safety harness + unit tests (Python ${{ matrix.python-version }})
     runs-on: ubuntu-latest
+    # The two Pythons the installer supports: Raspberry Pi OS Bookworm ships
+    # 3.11 and Trixie 3.13.
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.13"]
     env:
       # The bundled fixture plugin gives the harness at least one real plugin
       # to render, and REQUIRE_PLUGINS turns "discovered zero plugins" into a
@@ -29,7 +35,7 @@ jobs:
 
       - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
         with:
-          python-version: "3.12"
+          python-version: ${{ matrix.python-version }}
           cache: pip
 
       - name: Install dependencies
@@ -43,8 +49,13 @@ jobs:
           pytest --no-cov test/plugins/
 
   unit-tests:
-    name: Core unit tests
+    name: Core unit tests (Python ${{ matrix.python-version }})
     runs-on: ubuntu-latest
+    # Bookworm's Python (3.11) and Trixie's (3.13); see plugin-safety.
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.13"]
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
@@ -52,7 +63,7 @@ jobs:
 
       - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
         with:
-          python-version: "3.12"
+          python-version: ${{ matrix.python-version }}
           cache: pip
 
       - name: Install dependencies
@@ -84,7 +95,7 @@ jobs:
 
       - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
         with:
-          python-version: "3.12"
+          python-version: "3.13"
           cache: pip
 
       - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
@@ -113,6 +124,25 @@ jobs:
           REQUIRE_DOM: "1"
         run: node test/js/run_all.js
 
+  css-build:
+    name: Tailwind CSS is up to date
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
+        with:
+          python-version: "3.13"
+
+      # Downloads the pinned standalone Tailwind CLI (SHA-256 checked; no
+      # Node), rebuilds static/v3/tailwind.css and plugin-frame.css from the
+      # templates and JS, and fails if the committed files differ. Fix a
+      # failure by running `python3 scripts/build_css.py` and committing.
+      - name: Check the committed CSS matches a fresh build
+        run: python scripts/build_css.py --check
+
   type-check:
     name: Type check (mypy ratchet)
     runs-on: ubuntu-latest
@@ -123,7 +153,7 @@ jobs:
 
       - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
         with:
-          python-version: "3.12"
+          python-version: "3.13"
           cache: pip
 
       # The runtime requirements are installed so mypy sees the real types of
@@ -140,3 +170,39 @@ jobs:
       # them, or if a listed file is missing. See CONTRIBUTING.md.
       - name: Run mypy on the ratchet list
         run: python scripts/check_types.py
+
+  sports-drift-report:
+    name: Sports drift report (report only)
+    runs-on: ubuntu-latest
+    # A progress measure for docs/SPORTS_UNIFICATION.md, never a gate: the
+    # monorepo's own check_sports_drift.py is the gate. The step summary shows
+    # how many bodies each scoreboard method family still has.
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+
+      - name: Check out ledmatrix-plugins (main)
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          repository: ChuckBuilds/ledmatrix-plugins
+          path: ledmatrix-plugins
+          persist-credentials: false
+
+      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
+        with:
+          python-version: "3.13"
+
+      # Stdlib only; exits 0 whatever it finds.
+      - name: Report method-family drift across the nine scoreboards
+        run: |
+          python scripts/sports_drift_report.py --plugins ledmatrix-plugins \
+            --markdown --json sports-drift.json >> "$GITHUB_STEP_SUMMARY"
+          python scripts/sports_drift_report.py --plugins ledmatrix-plugins
+
+      - name: Upload the full report
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: sports-drift-report
+          path: sports-drift.json

CLAUDE.md

@@ -46,6 +46,7 @@
 - Store manager (`PluginStoreManager` in `src/plugin_system/store_manager.py`) handles install/update/uninstall
 - Monorepo plugins are installed without a `.git` directory: GitHub Trees API + raw downloads, falling back to ZIP extraction
 - Update detection for monorepo plugins uses version comparison (manifest version vs registry latest_version)
+- Optional registry entry fields (`store_registry.py`): `ledmatrix_min_version` refuses an incompatible install/update before the download (the post-download manifest gate stays as the fallback); `aliases` are the entry's other ids (manifest id `ledmatrix-weather` for `weather`), used with the `plugin_path` name by update/uninstall/reinstall to find the install — only this registry proof counts, never a bare `ledmatrix-<id>` folder (owner decision, #686; such a folder is only logged); `commit` is informational. An older plugins.json has none of them
 - Plugin configs stored in `config/config.json`, NOT in plugin directories — safe across reinstalls
 - Third-party plugins can use their own repo URL with empty `plugin_path`
 

CONTRIBUTING.md

@@ -71,7 +71,11 @@ integration tests.
    annotation-only where you can -- widen a hint rather than delete a
    defensive runtime check mypy calls unreachable. HTML/JS in
    `web_interface/` follows the patterns already in `templates/v3/`
-   and `static/v3/`.
+   and `static/v3/`. If you change a template or a static JS file,
+   run `python3 scripts/build_css.py` and commit the regenerated
+   `static/v3/tailwind.css` with it -- CI fails when the committed CSS
+   is out of date. It needs no Node; see
+   [`web_interface/README.md`](web_interface/README.md#styling-tailwind-css).
 5. **Update documentation** alongside code changes. If you add a
    config key, document it in the relevant `*.md` file (or, for
    plugins, in `config_schema.json` so the form is auto-generated).

README.md

@@ -151,6 +151,11 @@ The system supports live, recent, and upcoming game information for multiple spo
   - **1GB models (Pi 3B / 3B+), the 512MB Pi Zero 2 W and other low-memory boards**: supported, but the `rpi-rgb-led-matrix` C++ build needs more memory than the Pi has. The installer detects this automatically, compiles with fewer parallel jobs, and adds a temporary swapfile for the build which it removes afterwards. Expect that step to take 15-25 minutes instead of 2-5, and leave at least **3GB free** on the SD card. If you manage swap yourself, opt out with `--skip-swap`. To pin the compiler down further, use `--build-jobs 1`. Once running, keep an eye on memory: see [docs/LOW_MEMORY_BOARDS.md](docs/LOW_MEMORY_BOARDS.md).
 
 
+### Operating system
+- **Raspberry Pi OS Lite, Trixie (Debian 13) or Bookworm (Debian 12)**, 64-bit recommended. Trixie is the current release and the one to pick for a new SD card; an existing Bookworm install works as it is, no upgrade needed. The installer checks this first and stops with directions on anything else (Bullseye and older, the desktop edition, other distributions).
+- **Python**: whatever the OS ships, 3.13 on Trixie and 3.11 on Bookworm. Don't install a different Python; the installer and the services use the system `python3`.
+- **Networking**: NetworkManager, the default on both. Choosing a WiFi network from the web page and the `LEDMatrix-Setup` hotspot need it; if you switched to dhcpcd in `raspi-config`, switch back (Advanced Options → Network Config → NetworkManager).
+
 ### RGB Matrix Bonnet / HAT
 - [Adafruit RGB Matrix Bonnet/HAT](https://www.adafruit.com/product/3211) – supports one “chain” of horizontally connected displays  
 - [Adafruit Triple LED Matrix Bonnet](https://www.adafruit.com/product/6358) – supports up to 3 vertical “chains” of horizontally connected displays *(use `regular` as hardware mapping)*  
@@ -249,7 +254,7 @@ These are not required and you can probably rig up something basic with stuff yo
 
 <img width="512" height="361" alt="Step 2 Other " src="https://github.com/user-attachments/assets/166a22e8-8067-48df-9f80-50c91f573356" />
 
-5. Then choose Raspbian OS (64-bit) Lite (Trixie)
+5. Then choose Raspbian OS (64-bit) Lite (Trixie). Bookworm Lite (listed as Legacy) also works; see [Operating system](#operating-system) below
 
 <img width="512" height="361" alt="Step 4 Trixie Lite 64" src="https://github.com/user-attachments/assets/3b8590ce-b810-4dfe-9253-26e0d4f8ed1e" />
 

SECURITY.md

@@ -61,8 +61,31 @@ Out of scope (please report upstream):
 LEDMatrix is designed for trusted local networks. Several limitations
 are intentional rather than vulnerabilities:
 
-- **No web UI authentication.** The web interface assumes the network
-  it's running on is trusted. Don't expose port 5000 to the internet.
+- **Web UI authentication is optional and off by default.** Out of the
+  box the web interface assumes the network it's running on is trusted.
+  Setting a password under **General > Security** makes every page and
+  API route require a login or an API token (`Authorization: Bearer`),
+  with wrong passwords rate-limited per address
+  (`web_interface/auth.py`). Deliberately left open even then: requests
+  from the Pi itself (loopback without proxy headers; a reverse proxy on
+  the Pi must add `X-Forwarded-For`, or every request it relays counts as
+  local), the Wi-Fi setup flow while the Pi is in access-point mode,
+  static files, and a status-only `/api/v3/health`. The password is a
+  werkzeug hash and tokens are stored as SHA-256, in
+  `config/config_secrets.json`, which no API returns. There is no TLS:
+  over plain HTTP the password and tokens cross the LAN in the clear, so
+  still don't expose port 5000 to the internet; put a TLS reverse proxy
+  or a VPN in front for remote access. Anyone with shell access to the Pi
+  can turn login off (`scripts/reset_web_password.py`), which is the
+  documented recovery path.
+  "Trusted network" does not mean "trusted websites", though: any page
+  a LAN user opens could make their browser POST to the Pi. So the
+  interface refuses a `POST`/`PUT`/`PATCH`/`DELETE` whose `Origin` (or
+  `Referer`) header names another site (`web_interface/origin_guard.py`),
+  and `/api/v3/system/action` only accepts JSON or HTMX requests. Tools
+  that send neither header (curl, Home Assistant, the MQTT bridge) are
+  unaffected. Not covered: DNS rebinding, and anyone who can reach the
+  port directly.
 - **Plugins run unsandboxed.** Installed plugins execute in the same
   Python process as the display loop with full file-system and
   network access. Review plugin code (especially third-party plugins

config/config.template.json

@@ -1,7 +1,8 @@
 {
     "web_display_autostart": true,
     "auto_update": {
-        "enabled": false
+        "enabled": false,
+        "channel": "stable"
     },
     "schedule": {
         "enabled": false,
@@ -133,7 +134,7 @@
         "plugin_rotation_order": [],
         "use_short_date_format": true,
         "vegas_scroll": {
-            "live_in_ticker": false,
+            "live_in_ticker": true,
             "live_weight": 3,
             "favorite_live_weight": 5,
             "enabled": false,
@@ -173,6 +174,16 @@
     "plugin_system": {
         "plugins_directory": "plugin-repos"
     },
+    "fetch_service": {
+        "enabled": true,
+        "max_wait_seconds": 2,
+        "rate_limits": {
+            "*.espn.com": {
+                "per_second": 20,
+                "burst": 200
+            }
+        }
+    },
     "web-ui-info": {
         "enabled": true,
         "display_duration": 10

docs/ADVANCED_FEATURES.md

@@ -10,22 +10,27 @@ This guide covers advanced LEDMatrix features for users and developers, includin
 
 Vegas scroll mode displays content from multiple plugins in a continuous horizontal scroll, similar to news tickers seen in Las Vegas casinos. Plugins contribute content segments that flow across the display in a seamless ticker-style presentation.
 
-### Display Modes
+### How a Plugin Takes Part
 
-**SCROLL (Continuous Scrolling):**
-- Content scrolls continuously left
-- Smooth, fluid motion
-- Best for news-ticker style displays
+Each plugin has a *Vegas participation*:
 
-**FIXED_SEGMENT (Fixed-Width Block):**
-- Plugin gets fixed-width block on display
-- Content doesn't scroll out of its segment
-- Multiple plugins can share the display simultaneously
+**`scroll` (the default):**
+- The plugin's content scrolls by with everyone else's
+- Best for news-ticker style content: scores, headlines, prices, the time
 
-**STATIC (Scroll Pauses):**
-- Scrolling pauses when content is fully visible
-- Displays for specified duration, then resumes scrolling
-- Best for content that needs to be fully read
+**`pause`:**
+- The scroll stops when the plugin's turn comes round
+- The plugin draws the whole panel for its display duration, then the
+  scroll resumes
+- Best for content that needs to be read in full, or alerts
+
+**`exclude`:**
+- The plugin is left out of Vegas mode
+
+A plugin declares its default; set `vegas_participation` in a plugin's
+config to override it (see [Per-Plugin Configuration](#per-plugin-configuration)).
+Older documentation also describes a *fixed segment* mode; Vegas never
+implemented one, and it has always behaved exactly like `scroll`.
 
 ### Configuration
 
@@ -70,17 +75,31 @@ total. See the full list in
 
 ### Live Content in the Ticker
 
-By default, live content **preempts** Vegas mode: while any plugin reports
-live priority, the display controller refuses to run the ticker and shows
-that plugin's full-screen display instead. You get a big readable scoreboard,
-but the marquee stops entirely for the duration of the game.
+By default (since 3.8.0) live content **stays in the ticker** and takes
+**extra turns inside it**, and a scoreboard that supports live cards updates
+the score on a card already crossing the screen (`live_refresh`, "Update live
+content while it scrolls").
 
-Set `live_in_ticker` to keep the ticker running and let live content take
-**extra turns inside it** instead:
+To get the old behaviour back -- live content **preempts** Vegas mode: while
+any plugin reports live priority the ticker stops and that plugin's
+full-screen display is shown instead -- untick **Keep live games in the
+ticker** under Vegas mode, or set `live_in_ticker` to `false`:
+
+```json
+"vegas_scroll": {
+  "live_in_ticker": false
+}
+```
+
+Until 3.8.0 `false` was the default and every config held it, copied from
+the template. The first start on 3.8.0 turns it on once (a backup of the
+config is kept as `config.json.backup`, and `live_in_ticker_migrated` records
+that it ran); a `false` set after that is left alone.
+
+The weights below apply while live content is in the ticker:
 
 ```json
 "vegas_scroll": {
-  "live_in_ticker": true,
   "live_weight": 3,
   "favorite_live_weight": 5
 }
@@ -164,8 +183,7 @@ Override Vegas behavior for specific plugins:
 {
   "my_plugin": {
     "enabled": true,
-    "vegas_mode": "scroll",
-    "vegas_panel_count": 2,
+    "vegas_participation": "pause",
     "display_duration": 10
   }
 }
@@ -175,19 +193,30 @@ Override Vegas behavior for specific plugins:
 
 | Setting | Values | Description |
 |---------|--------|-------------|
-| `vegas_mode` | `scroll`, `fixed`, `static` | Display mode for this plugin |
-| `vegas_panel_count` | any positive integer | Width in panels (1 panel = display width) |
-| `display_duration` | seconds | Pause duration for STATIC mode |
+| `vegas_participation` | `scroll`, `pause`, `exclude` | How this plugin takes part: its content scrolls by, the scroll pauses for its turn and shows it full screen, or it is left out. Unset uses the plugin's own default |
+| `display_duration` | seconds | How long a `pause` plugin holds the screen |
+| `vegas_width_pct` | 10–100 | Width of this plugin's card, as a percentage of the panel |
+| `vegas_overflow` | `rotate`, `truncate` | What to do when its content is wider than its allowance |
+| `vegas_max_width_screens` | number of screens | The widest its card may be |
 
-Plugins may also set `vegas_overflow` and `vegas_max_width_screens` in
-their config section to control how oversized content is handled (see
-`PluginManager` in `src/plugin_system/plugin_manager.py`).
+These are core-owned settings (see
+[PLUGIN_CONFIG_CORE_PROPERTIES.md](PLUGIN_CONFIG_CORE_PROPERTIES.md)): every
+plugin accepts them whether or not its own schema lists them. Set them in
+the plugin's section of config.json, in the web UI's **Config Editor**
+tab.
+
+Some plugins also offer a `vegas_mode` setting of their own (`scroll`,
+`fixed` or `static`). It still works — `static` pauses, the other two scroll
+— but `vegas_participation` takes precedence, and `fixed` has never done
+anything different from `scroll`. The old `vegas_panel_count` setting never
+had an effect and is deprecated (removed in 3.9.0).
 
 ### Plugin Integration (Developer Guide)
 
 All of these have defaults in
 [`BasePlugin`](../src/plugin_system/base_plugin.py); override only what you
-need.
+need. The reference is
+[PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md#vegas-scroll-hooks).
 
 **1. Implement Content Method:**
 
@@ -203,43 +232,41 @@ If it returns `None` (the default), Vegas falls back to the plugin's
 (`PluginAdapter.get_content()` in
 [`src/vegas_mode/plugin_adapter.py`](../src/vegas_mode/plugin_adapter.py)).
 
-**2. Specify Content Type:**
+**2. Declare how the plugin takes part:**
 
-```python
-def get_vegas_content_type(self):
-    # 'multi' | 'static' | 'none'  -- default is 'static'
-    return 'multi'
+Most plugins need nothing: the default is `scroll`. A plugin that should
+pause the scroll, or stay out of Vegas, says so in `manifest.json`:
+
+```json
+{
+  "vegas_participation": "pause"
+}
 ```
 
-`'none'` excludes the plugin from Vegas mode.
-
-**3. Optionally Specify Display Mode:**
-
-These return `VegasDisplayMode` members, not strings:
+The user's own `vegas_participation` setting overrides the manifest. When
+the answer depends on state, override the method instead:
 
 ```python
-from src.plugin_system.base_plugin import VegasDisplayMode
-
-def get_vegas_display_mode(self):
-    return VegasDisplayMode.SCROLL
-
-def get_supported_vegas_modes(self):
-    return [VegasDisplayMode.SCROLL, VegasDisplayMode.STATIC]
+def get_vegas_participation(self):
+    # 'scroll' | 'pause' | 'exclude'
+    return 'pause' if self._alert_is_live() else 'scroll'
 ```
 
-`VegasDisplayMode` has `SCROLL` (`"scroll"`), `FIXED_SEGMENT` (`"fixed"`) and
-`STATIC` (`"static"`). The default `get_vegas_display_mode()` uses the
-plugin's `vegas_mode` config value if set, otherwise maps the content type
-(`multi` to `SCROLL`, anything else to `FIXED_SEGMENT`).
+A plugin written for an older core that declares nothing keeps its
+behaviour: `get_vegas_display_mode()` returning `VegasDisplayMode.STATIC`
+pauses, `get_vegas_content_type()` returning `'none'` excludes, and
+everything else scrolls. `get_supported_vegas_modes()`,
+`get_vegas_segment_width()` and the SCROLL / FIXED_SEGMENT distinction are
+deprecated (removed in 3.9.0): Vegas never read them.
 
 ### Content Rendering Guidelines
 
 **Image Dimensions:**
 - **Height:** Must match display height (typically 32 pixels)
-- **Width:** Varies by mode:
-  - SCROLL: Any width (recommended 64-512 pixels)
-  - FIXED_SEGMENT: `panel_count * display_width`
-  - STATIC: Any width, optimized for readability
+- **Width:** Any width for `scroll` (recommended 64-512 pixels);
+  `get_vegas_render_width()` is the width Vegas would like, and it narrows
+  `display_manager` to match while it asks. A `pause` plugin draws the
+  whole panel in `display()`.
 
 **Color Mode:**
 - Use RGB color mode
@@ -289,17 +316,10 @@ class WeatherPlugin(BasePlugin):
     def get_vegas_content(self):
         """Return cached Vegas image"""
         return self.vegas_image
-
-    def get_vegas_content_type(self):
-        return 'multi'
-
-    def get_vegas_display_mode(self):
-        return 'scroll'
-
-    def get_supported_vegas_modes(self):
-        return ['scroll', 'static']
 ```
 
+It scrolls, the default participation, so it declares nothing else.
+
 ### System Architecture
 
 Vegas mode consists of four core components working together to provide smooth 125 FPS continuous scrolling:
@@ -382,7 +402,8 @@ Vegas mode consists of four core components working together to provide smooth 1
 
 **Responsibilities:**
 - Convert plugin content to scrollable images
-- Handle different Vegas display modes (SCROLL, FIXED, STATIC)
+- Fetch the content of `scroll` plugins (a `pause` plugin is drawn by
+  its own `display()` when the scroll pauses; see StreamManager)
 - Manage fallback for plugins without Vegas support
 - Cache plugin content for performance
 
@@ -391,21 +412,16 @@ Vegas mode consists of four core components working together to provide smooth 1
    - Calls `get_vegas_content()` if available
    - Falls back to `display()` method if not
 
-2. **Handle display mode:**
-   - SCROLL: Returns image as-is for continuous scrolling
-   - FIXED_SEGMENT: Creates fixed-width block (panel_count * display_width)
-   - STATIC: Marks content for pause-when-visible behavior
-
-3. **Content type handling:**
-   - `multi`: Multiple segments (list of images)
-   - `static`: Single static image
-   - `none`: Skip this plugin in current cycle
+2. **Participation** is decided by the StreamManager, not here
+   (`resolve_vegas_participation()` in
+   [`base_plugin.py`](../src/plugin_system/base_plugin.py)): `exclude`
+   plugins never reach the adapter, and `pause` plugins are not fetched.
 
 **Fallback Behavior:**
 - If plugin doesn't implement Vegas methods:
   - Calls plugin's `display()` method
   - Captures rendered display as static image
-  - Treats as fixed segment
+  - Scrolls it by as one block
 - Ensures all plugins work in Vegas mode without explicit support
 
 #### 4. RenderPipeline
@@ -508,7 +524,7 @@ All components use thread-safe patterns:
 If a plugin doesn't implement Vegas methods:
 - System calls the plugin's `display()` method
 - Captures the rendered display as a static image
-- Treats it as a fixed segment
+- Scrolls it by as one block
 
 This ensures all plugins work in Vegas mode, even without explicit support.
 

docs/ADVANCED_PLUGIN_DEVELOPMENT.md

@@ -27,7 +27,7 @@ Advanced patterns, examples, and best practices for developing LEDMatrix plugins
 
 The Display Manager's icon methods — `draw_weather_icon()`, `draw_sun()`,
 `draw_cloud()`, `draw_rain()`, `draw_snow()` and `draw_text_with_icons()` —
-are deprecated, removed in 3.7.0. Draw your own icons instead: render them
+were removed in 3.8.0. Draw your own icons instead: render them
 onto a PIL image and paste it onto `self.display_manager.image`, or ship
 icon images with the plugin. The weather plugin's `WeatherIcons` class is an
 example. See [Deprecated APIs](PLUGIN_API_REFERENCE.md#deprecated-apis).
@@ -194,7 +194,7 @@ def update(self):
     sport_key = "nhl"
     cache_key = f"{self.plugin_id}_{sport_key}_games"
     
-    # get_background_cached_data() is deprecated, removed in 3.7.0 — use get()
+    # get_background_cached_data() was removed in 3.8.0 — use get()
     cached = self.cache_manager.get(cache_key, max_age=60)
     
     if cached:
@@ -596,8 +596,8 @@ def update(self):
 
 ```python
 def update(self):
-    # get_enabled_plugins() is deprecated, removed in 3.7.0 — check the
-    # instance's `enabled` flag instead
+    # get_enabled_plugins() was removed in 3.8.0 — check the instance's
+    # `enabled` flag instead
     weather_plugin = self.plugin_manager.get_plugin("weather")
     if weather_plugin is not None and weather_plugin.enabled:
         # Use weather data

docs/ARCHITECTURE.md

@@ -41,19 +41,140 @@ each other. They share three things:
 
 | State | Where | Written by | Read by |
 |---|---|---|---|
-| On-demand request | cache `display_on_demand_request` | web: `start_on_demand_display()` / `stop_on_demand_display()` in [`api_v3/display.py`](../web_interface/blueprints/api_v3/display.py) | display: `_poll_on_demand_requests()` |
+| On-demand command | control socket `/run/ledmatrix/control.sock` ([IPC_CONTROL_SOCKET.md](IPC_CONTROL_SOCKET.md)) | web: `start_on_demand_display()` / `stop_on_demand_display()` in [`api_v3/display.py`](../web_interface/blueprints/api_v3/display.py), via [`src/ipc/client.py`](../src/ipc/client.py) | display: [`src/ipc/server.py`](../src/ipc/server.py) acks; the render thread applies it in `_poll_on_demand_requests()` |
+| On-demand request (fallback) | cache `display_on_demand_request` | web, when the socket fails; four plugins write it directly | display: `_poll_on_demand_requests()` |
 | On-demand state | cache `display_on_demand_state` | display: `_publish_on_demand_state()` | web: `/api/v3/display/on-demand/status` |
 | Current screen | cache `display_current_state` | display | web: `/api/v3/display/current-status` |
 | Plugin errors | cache `plugin_error_snapshot` | display: `ErrorSnapshotPublisher` ([`src/error_aggregator.py`](../src/error_aggregator.py)) | web: `read_error_report()` for `/api/v3/errors/*` |
 | Error clear | cache `plugin_error_clear_request` | web | display |
 | Font usage | cache `font_usage_snapshot` | display: `FontUsagePublisher` ([`src/font_usage.py`](../src/font_usage.py)) | web: Fonts tab |
+| Fetch statistics (requests per plugin and host) | cache `fetch_stats_snapshot` | display: `FetchStatsPublisher` ([`src/common/fetch_service.py`](../src/common/fetch_service.py)), at most once a minute on change | web: `read_fetch_stats()` for `/api/v3/plugins/fetch-stats` |
 | Plugin health | cache `plugin_health:<id>` | display (web writes on reset) | web: `/api/v3/plugins/health` |
-| Preview frame | `/tmp/led_matrix_preview.png` | display: `DisplayManager`, gated by [`snapshot_policy`](../src/common/snapshot_policy.py) | web: display SSE stream, `/api/v3/health` (file age) |
-| Preview viewer marker | `/tmp/led_matrix_preview_viewer` | web, while a preview is open | display: writes full-rate snapshots only while it is fresh |
+| Plugin runtime (loaded, state, last error, version) | cache `plugin_runtime_snapshot` | display: `PluginRuntimePublisher` ([`src/plugin_system/plugin_runtime.py`](../src/plugin_system/plugin_runtime.py)) | web: `read_plugin_runtime()` for `/api/v3/plugins/installed`, `/plugins/state`, reconciliation |
+| Preview frame | `/tmp/led_matrix_preview.png` | display: `DisplayManager`, gated by [`snapshot_policy`](../src/common/snapshot_policy.py): a changed frame at most once a second with a viewer, every 30 s without | web: display SSE stream (checks the mtime every 0.25 s), `/api/v3/health` (file age) |
+| Preview viewer marker | `/tmp/led_matrix_preview_viewer` | web, about once a second while a preview is open | display: writes viewer-rate snapshots only while it is fresh (5 s) |
 | Hardware init status | `/tmp/led_matrix_hw_status.json` | display | web: `/api/v3/hardware/status` |
+| Render-loop heartbeat | `/run/ledmatrix/display-heartbeat.json` (tmpfs) | display: the render thread, via [`display_watchdog`](../src/display_watchdog.py) | web: `/api/v3/health` (`checks.display_loop`); the update health check |
 
-The on-demand start route also restarts `ledmatrix.service` by default so the
-request takes effect straight away.
+The on-demand start route starts `ledmatrix.service` when it is not running
+(`start_service`, on by default) but never restarts a running one. The routes
+send the command over the display's control socket and get an ack; when that
+fails (a stopped display, one older than the socket) they write the mailbox
+instead, which the display reads every `ON_DEMAND_POLL_INTERVAL` (0.25s), from
+its dwell sleep, its render loops and Vegas's interrupt check as well as the
+main loop. Both ways end in the same handler, `_handle_on_demand_request()`.
+The socket's handlers only queue; see [IPC_CONTROL_SOCKET.md](IPC_CONTROL_SOCKET.md)
+for the protocol, the permission model and the plan to retire the mailboxes.
+
+### Web and display processes: who runs plugins
+
+Only the display process imports plugin code, instantiates plugins and calls
+their lifecycle hooks (`update`, `display`, `on_config_change`, `on_enable`,
+`on_disable`). The web process is metadata-only: it reads plugins as files
+through `PluginCatalog`
+([`src/plugin_system/plugin_catalog.py`](../src/plugin_system/plugin_catalog.py))
+-- manifests, config schemas (through `SchemaManager`), each plugin's
+section of `config.json`, and installed versions. The catalog keeps the
+read-only method names of `PluginManager` and has nothing that can run a
+plugin (no `load_plugin`, `get_plugin` or `plugins`).
+
+How a web-side change reaches the running plugins:
+
+| Change | How the display picks it up |
+|---|---|
+| Plugin settings saved, config reset | `ConfigService` sees the new `config.json` and calls the plugin's `on_config_change` with the prepared section |
+| Plugin enabled or disabled | `ConfigService` → `_controller_config_change` flags a reconcile; `_reconcile_enabled_plugins` loads it (fresh from disk) or unloads it on the render thread |
+| Plugin uninstalled (config removed) | the removed section flips its `enabled` flag, and the reconcile unloads it |
+| Plugin installed, not enabled | nothing to do until it is enabled, which loads it |
+| Plugin updated while enabled | the update route asks the display over the control socket (`plugin.reload`) to reload it on the render thread, and answers `restart_required: false` once the new code runs. Without the socket, as the next row |
+| Plugin installed while already enabled, updated while enabled and not reloaded, or uninstalled with its config kept | **not picked up**: the display keeps running what it loaded. The route answers `restart_required: true` and the UI shows its restart banner |
+
+`display_restart_required()` in `plugin_catalog.py` holds that last rule;
+routes return it as `restart_required` (with the banner's wording in
+`restart_message`), and `window.noteRestartRequired()` in
+`static/v3/app.js` raises the banner for any response that carries it,
+`POST /api/v3/config/main` included.
+
+Runtime state shown in the UI comes from what the display publishes to the
+shared cache: health and metrics (`/api/v3/plugins/health`,
+`/plugins/metrics`), errors (`/api/v3/errors/*`), the current mode, and the
+plugin runtime snapshot described below. `enabled` is read from
+`config.json` by the display's rule (a missing flag is disabled).
+
+Plugin code still runs in the web process in one place,
+`_import_plugin_code_in_web_process()` in
+[`api_v3/__init__.py`](../web_interface/blueprints/api_v3/__init__.py): the
+Starlark routes import the starlark-apps plugin's `tronbyte_repository` and
+`pixlet_renderer` helper modules (never the plugin class), and a web-UI
+action with `oauth_flow` imports its script for `get_auth_url()`. Every
+other web-UI action runs its script as a subprocess. A later, explicit
+**plugin web-entry contract** -- a declared entry point for plugin web code
+-- replaces that function.
+
+The **control socket** from the web process to the display
+([IPC_CONTROL_SOCKET.md](IPC_CONTROL_SOCKET.md)) carries on-demand
+commands and reloads an updated plugin; its next stages stream the
+display's state and retire the cache-key mailboxes. The plugin web-entry
+contract above is still to come.
+
+### Plugin state: desired, observed, and who owns it
+
+There is one plugin state machine, and the display owns it:
+`PluginStateManager` in
+[`plugin_state.py`](../src/plugin_system/plugin_state.py) (unloaded →
+loaded → enabled ⇄ running, error, disabled), held by the display's
+`PluginManager`. It also records, per loaded plugin, the manifest version it
+loaded and when. Nothing else keeps plugin state:
+
+| Question | Answered by |
+|---|---|
+| Is it installed, at which version? | the plugins directory (`manifest.json`) |
+| Should it run? | `config.json` (`<id>.enabled`, missing = disabled) |
+| Has the user uninstalled it for good? | the store's uninstalled-plugins record |
+| Is the display running it, at which version, and why not? | the display's runtime snapshot |
+
+**The runtime snapshot.** `PluginRuntimePublisher`
+([`plugin_runtime.py`](../src/plugin_system/plugin_runtime.py)), started by
+`DisplayController` right after it creates the `PluginManager`, writes the
+cache key `plugin_runtime_snapshot`: per plugin `loaded`, `state`, `error`
+(type, a redacted message of at most 200 characters, when, recoverable),
+`version` and `loaded_at`, plus `published_at`, `stale_after` and `running`.
+The cache is on disk, usually the SD card, so it writes when something a
+reader sees changes -- throttled to once per 10 s -- and otherwise once a
+minute as a heartbeat. RUNNING, which every `update()` passes through, is
+published as ENABLED, so plugin updates alone never cause a write.
+`cleanup()` publishes `running: false`.
+
+**Reading it.** `read_plugin_runtime()` judges the snapshot before anyone
+uses it: `live` (fresh, from a running display), `stale` (older than
+`stale_after`, 3 minutes: a hung or crashed display), `stopped` or
+`unknown` (none, unreadable, or another schema). Only a live view reports
+per-plugin facts; every other status answers `null` for them, so stale
+truth cannot leak into a response. `/api/v3/plugins/installed` returns
+`loaded`, `state`, `error_info`, `loaded_version` and `loaded_at` per
+plugin and `data.runtime` (`status`, `published_at`, `age_seconds`);
+`/api/v3/plugins/state` returns the same beside the desired state.
+
+**Reconciliation**
+([`state_reconciliation.py`](../src/plugin_system/state_reconciliation.py))
+compares desired state (config + disk) with observed state (the snapshot).
+It fixes desired-state gaps -- a plugin on disk with no config section gets
+`{"enabled": false}`, a configured plugin missing from disk is reinstalled
+unless the user uninstalled it -- and only reports observed-state gaps
+(enabled but not loaded, loaded at an older version): the display loads and
+unloads by config on its own, and a version gap needs a restart.
+
+**`data/plugin_state.json` is retired.** The web process used to keep a
+second `PluginStateManager` (`state_manager.py`) persisted to that file:
+per plugin an enabled flag copied from config, a version copied from the
+manifest (when set at all), a status derived from those, and install/update
+timestamps. Reconciliation mostly synced it back to config and backups
+merged it into their plugin list. Every field is derivable (the timestamps
+from the operation history), so nothing is migrated: no code reads or
+writes the file, and a copy left on a device is inert and safe to delete.
+The two classes shared a name but not a concern -- a persisted install
+record versus the live lifecycle -- so they were not merged; the persisted
+one had nothing left to hold and was removed.
 
 ## Display loop
 
@@ -70,7 +191,8 @@ the scheduler), and sets up Vegas mode.
 enable/disable, poll on-demand requests, run scheduled plugin updates, check
 the on/off schedule and brightness, then show one screen. Priority is
 on-demand, then WiFi status messages, then live priority, then Vegas mode,
-then normal rotation.
+then normal rotation. [RUN_LOOP_REDESIGN.md](RUN_LOOP_REDESIGN.md) is the
+plan for restructuring this loop and lists its golden trace tests.
 
 - **Rotation.** `available_modes` is the ordered list of display modes;
   `current_mode_index` advances after each screen.
@@ -82,13 +204,20 @@ then normal rotation.
 - **On-demand.** A request from the web interface pins one plugin (or mode)
   for a duration. `_activate_on_demand()` / `_clear_on_demand()`; the
   session is saved under `display_on_demand_config` so it survives a
-  restart. It also keeps the display on during scheduled off hours.
+  restart. It also keeps the display on during scheduled off hours. A
+  request for a plugin that is disabled in config loads it live
+  (`_load_plugin_for_on_demand()`, `load_plugin(force_enabled=True)`)
+  without writing `config.json`; the main loop unloads it once on-demand
+  moves off it (`_release_on_demand_plugins()`).
 - **Live priority.** `_check_live_priority()` looks for a plugin whose
   `has_live_priority()` and `has_live_content()` are both true and switches
   to it, rotating between several live games.
 - **Schedule and dim schedule.** `_check_schedule()` reads `schedule`;
   `_check_dim_schedule()` reads `dim_schedule` and
-  `display.hardware.brightness`. Both are re-evaluated once a minute.
+  `display.hardware.brightness`. Both are re-evaluated once a minute, and
+  both windows are half-open: on (or dimmed) from the start time, off at
+  the end time. When an on-demand session ends, the on/off schedule is
+  re-checked at once rather than at the next minute.
 - **Long screens.** While a screen is showing (a dwell, a scroll, a Vegas
   iteration), `_service_pending_changes()` repeats the on-demand, schedule
   and brightness checks every 0.25 s, so a change does not wait for the
@@ -99,7 +228,8 @@ then normal rotation.
   changes. The controller refreshes its cached settings; enabling or
   disabling a plugin queues `_reconcile_enabled_plugins()`, which loads or
   unloads it on the display thread; each plugin gets `on_config_change()`
-  for its own section. Set `LEDMATRIX_HOT_RELOAD=false` to turn this off.
+  for its own section, under its plugin lock
+  (`PluginManager.apply_config_change()`). Set `LEDMATRIX_HOT_RELOAD=false` to turn this off.
   Matrix hardware settings are only read at start-up.
 - **Vegas mode.** [`src/vegas_mode/`](../src/vegas_mode/): the display loop
   calls `VegasModeCoordinator.run_iteration()`
@@ -113,6 +243,43 @@ then normal rotation.
   `sync.role`: a leader sends a follower its share of each frame over UDP
   (port 5765).
 
+### Liveness
+
+A render thread stuck inside a plugin leaves the service "active" and the
+panel frozen, so liveness is reported by the render thread itself
+([`src/display_watchdog.py`](../src/display_watchdog.py), standard library
+only). `beat()` from any other thread is ignored: the update worker, Vegas's
+tick thread and the prefetcher keep running while the render thread is stuck,
+and must not vouch for it.
+
+- **Check-in points.** The top of `run()`'s loop (`loop_pass()`), every
+  dwell second (`_sleep_with_plugin_updates`), every frame of the per-screen
+  loops (`_display_once`), every frame of Vegas's own loop and static pause
+  (`coordinator.run_iteration`), each plugin fetched for a Vegas cycle
+  (`StreamManager._fetch_plugin_content`), each update on the
+  `synchronous_updates` path, and every frame pushed
+  (`DisplayManager.update_display` -> `note_frame()`). Beats are
+  rate-limited to one ping and one heartbeat write every 5 s.
+- **systemd watchdog.** `ledmatrix.service` is `Type=simple` with
+  `WatchdogSec=120` and `NotifyAccess=main`. `run.py` sends
+  `WATCHDOG_USEC` = 15 minutes before importing anything heavy (start-up loads
+  plugins and runs the 20 s update budget, and the watchdog clock starts with
+  the process). After the first frame -- or the first full pass, when there is
+  nothing to draw -- the loop sends `READY=1`, restores the unit's 120 s and
+  pings. `PluginManager.load_plugin()` on the render thread (a plugin enabled
+  from the web UI, or loaded for on-demand) gets 15 minutes again, since it
+  can run pip. A missed deadline is a SIGABRT; faulthandler, enabled on
+  arming, dumps every thread's stack to the journal.
+- **Heartbeat.** `/run/ledmatrix/display-heartbeat.json`
+  (`{"pid", "mono", "wall"}`; `RuntimeDirectory=ledmatrix`, 0755, file 0644 so
+  the web user can read it). Readers compare `mono` with their own
+  `time.monotonic()` -- CLOCK_MONOTONIC is shared by every process and does not
+  jump when NTP first sets an RTC-less Pi's clock. `/api/v3/health` calls it
+  `stalled` past 60 s; no file is `not_reported` and changes nothing. A clean
+  stop removes it. Without `RuntimeDirectory=` (an older unit) the display,
+  as root, creates the directory itself; off Linux, or without root, there
+  is no heartbeat.
+
 ## Plugin system
 
 [`src/plugin_system/`](../src/plugin_system/):
@@ -121,7 +288,8 @@ then normal rotation.
 |---|---|
 | Base class plugins implement | [`base_plugin.py`](../src/plugin_system/base_plugin.py) (`BasePlugin`, `VegasDisplayMode`) |
 | Finding a plugin's directory | [`plugin_dirs.py`](../src/plugin_system/plugin_dirs.py): manifest `id` first, then directory `<id>` or `ledmatrix-<id>` |
-| Discovery, load, unload, scheduled updates | [`plugin_manager.py`](../src/plugin_system/plugin_manager.py) (`PluginManager`) |
+| Discovery, load, unload, scheduled updates (display process) | [`plugin_manager.py`](../src/plugin_system/plugin_manager.py) (`PluginManager`) |
+| Manifest, schema, config and version reads (web process) | [`plugin_catalog.py`](../src/plugin_system/plugin_catalog.py) (`PluginCatalog`; see [who runs plugins](#web-and-display-processes-who-runs-plugins)) |
 | Import and instantiate | [`plugin_loader.py`](../src/plugin_system/plugin_loader.py) (`PluginLoader.load_plugin()`: dependencies, module, class) |
 | Timeouts | [`plugin_executor.py`](../src/plugin_system/plugin_executor.py) (`PluginExecutor`, 30 s default; a timed-out thread is abandoned, not killed) |
 | Circuit breaker | [`plugin_health.py`](../src/plugin_system/plugin_health.py) (`PluginHealthTracker`: 3 consecutive failures open the circuit for 300 s) |
@@ -148,8 +316,9 @@ everything else through `_reinstall_with_rollback()`.
 ## Web interface
 
 - **App.** [`web_interface/app.py`](../web_interface/app.py) builds the
-  Flask `app` at import time, creates the managers, and registers two
-  blueprints. `web_interface/start.py` runs it on port 5000.
+  Flask `app` at import time, creates the managers -- a `PluginCatalog`,
+  never a `PluginManager` -- and registers two blueprints.
+  `web_interface/start.py` runs it on port 5000.
 - **Pages.** [`blueprints/pages_v3.py`](../web_interface/blueprints/pages_v3.py)
   serves the shell `templates/v3/base.html` at `/` and each tab as a
   partial at `/partials/<name>` (templates in
@@ -181,8 +350,19 @@ everything else through `_reinstall_with_rollback()`.
 - **Update Code** on the Overview tab and the automatic updater both call
   `perform_core_update()` in
   [`api_v3/system.py`](../web_interface/blueprints/api_v3/system.py):
-  `git pull --rebase`, reinstall changed requirement files, report whether a
-  restart is needed.
+  fetch branches and tags, move the checkout for the update channel, reinstall
+  changed requirement files, report whether a restart is needed.
+- **Update channels** (`auto_update.channel`):
+  [`web_interface/update_channel.py`](../web_interface/update_channel.py)
+  decides the move. `stable` checks out the newest `vX.Y.Z` tag (detached
+  HEAD) when it contains the current commit; `beta` is
+  `git pull --rebase --autostash` on the current branch, and leaves a
+  detached release for `main` first. A stable device newer than the newest
+  release keeps pulling `main` until a release contains its commit, so no
+  update ever moves backwards; a config without the key is written as
+  `stable` once the device reaches a release. Checkouts carry uncommitted
+  edits across with `git stash create`/`apply`, and keep them in the stash
+  list if they no longer apply.
 - **Automatic updates** (`auto_update.enabled`, off by default):
   `AutoUpdater` in [`web_interface/auto_update.py`](../web_interface/auto_update.py)
   runs in the web process, checks every 30 minutes, and updates at most
@@ -193,7 +373,11 @@ everything else through `_reinstall_with_rollback()`.
   `ledmatrix-update-verify.path`, which runs the verifier as a separate unit
   (so restarting the web service does not kill it). The verifier restarts
   both services, waits for the web API to answer and the display service to
-  stay up, and on failure resets to the previous commit and restarts again.
+  stay up -- and, when the display wrote a heartbeat before the update, to
+  keep one fresh from the restarted process (see Liveness) -- and on failure
+  returns to where HEAD was (the branch, or detached on the previous
+  release; `old_ref` in the pending file), resets to the previous commit
+  and restarts again.
   Plugin updates run only after a verified core update. State is in
   `data/auto_update_state.json` and `data/auto_update_pending.json`.
 - **Startup validator.** `StartupValidator`
@@ -201,7 +385,9 @@ everything else through `_reinstall_with_rollback()`.
   `DisplayController.__init__`: config and cache directory first, then
   enabled plugins once the plugin manager exists. It also warns when an
   installed systemd unit differs from its template in `systemd/`. Results
-  are logged; startup continues either way.
+  are logged; startup continues either way. Nothing rewrites installed units
+  on update: a unit change such as the watchdog reaches an existing install
+  only when `install_service.sh` is re-run.
 
 ## Where to start reading
 

docs/CONFIG_REFERENCE.md

@@ -17,6 +17,7 @@ tooling against it.
 |---|---|---|---|
 | `web_display_autostart` | bool, `true` | Whether the web interface service starts with the system | `scripts/utils/start_web_conditionally.py` |
 | `auto_update.enabled` | bool, `false` | Weekly automatic updates: LEDMatrix code first (health-checked, rolled back on failure), then installed plugins. Toggle in the General tab or install with `first_time_install.sh --enable-auto-update` | `web_interface/auto_update.py`, `src/auto_update_setup.py` (`is_enabled()`) |
+| `auto_update.channel` | `"stable"` or `"beta"`, `"stable"` (template) | What Update Code and the weekly update install. `stable`: the newest `vX.Y.Z` release tag (pre-releases ignored), checked out with a detached HEAD. `beta`: `main`. Never moves a device backwards: one newer than the newest release keeps following `main` until a release contains its commit. Missing (configs from before channels) behaves like `stable` and is saved as `stable` once the device is on a release. General tab, Update Channel | `web_interface/update_channel.py` (`resolve()`) |
 | `timezone` | string, `"America/New_York"` | IANA timezone for schedules and displays | `ConfigManager.get_timezone()` |
 | `target_fps` | int, `100` | Legacy "Scroll Frame Rate". Core scrolling no longer reads it: scroll frames are presented at `display.hardware.limit_refresh_rate_hz` divided by each scroll's frame hold, and speed comes from each plugin's scroll settings. Still exposed to plugins via `BasePlugin.global_config` | `src/plugin_system/base_plugin.py` |
 | `location` | object | `city` / `state` / `country`. Supplies the **default** for a plugin's own `location_city` / `location_state` / `location_country` setting, so weather, radar and friends follow this device without being configured twice. A value saved on the plugin itself still overrides it. Starlark (Tidbyt) apps get the same treatment: a `Location` field left blank on the app renders at this city (geocoded once via Open-Meteo, coordinates cached permanently) instead of the app author's default, which is usually San Francisco. If the city can't be looked up (no match, or the geocoder is unreachable; retried after 30 minutes), the app keeps its own default. | `SchemaManager.apply_device_location()`, then plugins via merged config; `src/device_location.py` for Starlark apps |
@@ -30,6 +31,13 @@ tooling against it.
 | `start_time` / `end_time` | `"HH:MM"`, `07:00`–`23:00` | Global-mode on/off times |
 | `days.<weekday>.{enabled,start_time,end_time}` | per-day objects | Per-day-mode overrides |
 
+The display is on from `start_time` up to, but not including, `end_time`:
+with `07:00`–`23:00` it turns on at 07:00 and off at 23:00. An end earlier
+than the start crosses midnight (`22:00`–`07:00` is on overnight). In
+per-day mode, the entry for the current day decides. An on-demand session
+keeps the display on during off hours; once it ends or is stopped, the
+display blanks within about a second.
+
 Read by `DisplayController._check_schedule()` (`src/display_controller.py`).
 Managed in the web UI under Schedule.
 
@@ -43,7 +51,9 @@ Same shape as `schedule` (the template sets its `mode` to `"global"`), plus:
 
 Read by `DisplayController._check_dim_schedule()` (`src/display_controller.py`;
 saved via `POST /api/v3/config/dim-schedule`). The display returns to
-`display.hardware.brightness` outside the window.
+`display.hardware.brightness` outside the window. The window has the same
+boundaries as `schedule`: dimmed from `start_time` up to, but not including,
+`end_time`.
 
 ## `display.hardware` — matrix panel hardware
 
@@ -131,6 +141,10 @@ Read by `src/vegas_mode/config.py` (`VegasScrollConfig.from_config`). See
 | `offscreen_prefetch` | bool, `true` — render every plugin's ticker content on the background thread, each on its own canvas. `false` restores handing canvas-bound plugins to the render thread, one pause at a time. Temporary; see [OFFSCREEN_RENDERING.md](OFFSCREEN_RENDERING.md) |
 | `prefetch_gate` | bool, `true` — let that background thread run Python only while the render thread is waiting for the panel, so the render thread never waits for the GIL when a refresh comes round. Only takes effect with the rebuilt rgbmatrix binding (`scripts/build_rgbmatrix_nogil.sh`). See [OFFSCREEN_RENDERING.md](OFFSCREEN_RENDERING.md) |
 | `switch_interval_ms` | float, `0` — experimental: shorten Python's GIL switch interval to this many ms while Vegas runs. `0` leaves the default (5 ms) alone |
+| `live_refresh` | bool, `true` — live elements: a plugin that supports them (scores, the flight map) has what is already scrolling updated when its data changes, instead of freezing each card as it was drawn. Always off under multi-display sync, in swap mode and with `offscreen_prefetch` off. `false` restores the frozen behaviour exactly. Per plugin: `vegas_live` in the plugin's section |
+| `live_max_hz` | float, `5` (0–10) — ceiling on how often an animated live element (a moving aircraft) is redrawn; `0` keeps data updates and turns animation off. Capped at 1 Hz without the rebuilt rgbmatrix binding |
+| `live_min_interval` | float, `2` (0.5–60) — shortest time between two data redraws of one plugin; a faster plugin is redrawn at this rate, never skipped |
+| `live_lead_screens` | float, `1` (0–5) — how far ahead of the screen, in screen widths, an animated element starts being redrawn |
 | `smooth_scroll` | bool, `true` — move a whole number of pixels per panel refresh, locked to vsync. `scroll_speed` is snapped to the nearest speed the panel can show that way (at 95Hz: 95, 47.5, 31.7 px/s…), measured against the panel's real refresh rate once scrolling starts |
 | `sub_pixel_blend` | bool, `false` — the older smoothing: advance by elapsed time and blend neighbouring pixel columns. Looks anti-aliased in the web preview but shimmers on the panel and is not locked to the refresh. Overrides `smooth_scroll` when on |
 | `extend_threshold_screens` | float, `2.0` |
@@ -147,7 +161,7 @@ Read by `src/vegas_mode/config.py` (`VegasScrollConfig.from_config`). See
 | `max_cycle_duration` | int, `240` |
 | `frame_based_scrolling` | bool, `true` — does not step or set a frame rate; motion is by elapsed time either way. When `true`, `scroll_speed` passes through a clamp of 0.1–5 px per `scroll_delay` (see next row) |
 | `scroll_delay` | float, `0.02` — not a frame period. Only used with `frame_based_scrolling`: the applied speed is `clamp(scroll_speed × scroll_delay, 0.1, 5) / scroll_delay` px/s, so at `0.02` speeds under 5 px/s run at 5, and at `0.001` nothing runs slower than 100 px/s |
-| `live_in_ticker` | bool, `false` — keep scrolling during live games instead of handing the display to a full-screen scoreboard |
+| `live_in_ticker` | bool, `true` — keep scrolling during live games instead of handing the display to a full-screen scoreboard. `false` was the default before 3.8.0; the first start on 3.8.0 turns a stored `false` on once and sets `live_in_ticker_migrated` |
 | `live_weight` | int, `3` (1–10) — slots per cycle for a plugin with live content |
 | `favorite_live_weight` | int, `5` (1–10) — slots per cycle when a plugin reports a favorite team is live |
 

docs/DEPRECATIONS_3.8.md

@@ -0,0 +1,175 @@
+# Deprecated plugin APIs: usage scan
+
+Generated by `scripts/plugin_api_usage.py` — do not edit by hand; re-run it (see [How to re-run](#how-to-re-run)).
+
+- Scanned: 2026-10-01, core 3.7.0
+- Monorepo: [ChuckBuilds/ledmatrix-plugins](https://github.com/ChuckBuilds/ledmatrix-plugins) (main @ 4de1d134), 46 plugins
+- Third-party plugins: 8 with their own repo in `plugins.json` (f1-live, gif-player, pga-tour-leaderboard, plex-marquee, ledmatrix-dresden-departures, tidbyt-baseball-scoreboard, sleeper-fantasy, ledmatrix-nascar)
+
+**37 deprecated methods: 36 unused, 1 still used, 0 need review.**
+
+Counted per plugin: a *call* is `<receiver>.method` on an object named like the owner (`cache_manager`, `display_manager`, `font_manager`, `plugin_manager`), or on `self`/`super()` in a subclass; an *override* is `def method` in a subclass of the owner. *Review* hits are `.method` on a receiver whose type the scan cannot tell. *Internal* hits sit inside another deprecated core method and go with it. *Unrelated* hits are a different class's own method with the same name (a name collision), and never block removal; neither do hits in test files.
+
+| Method | Removal | Core | Plugins (calls / overrides) | Name collisions & tests | Verdict |
+|---|---|---|---|---|---|
+| `CacheManager.has_data_changed` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `CacheManager.update_cache` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `CacheManager.setup_persistent_cache` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `CacheManager.get_sport_live_interval` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `CacheManager.get_sport_key_from_cache_key` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `CacheManager.get_background_cached_data` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `CacheManager.is_background_data_available` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `CacheManager.record_cache_hit` | 3.8.0 | core (1 internal) | — | — | unused — safe to remove in 3.8.0 |
+| `CacheManager.record_cache_miss` | 3.8.0 | core (1 internal) | — | — | unused — safe to remove in 3.8.0 |
+| `CacheManager.record_fetch_time` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `CacheManager.get_cache_metrics` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `CacheManager.log_cache_metrics` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `CacheManager.get_memory_cache_stats` | 3.8.0 | core tests (3 test calls) | — | — | unused — safe to remove in 3.8.0 |
+| `DisplayManager.draw_sun` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `DisplayManager.draw_cloud` | 3.8.0 | core (2 internals) | — | ledmatrix-weather (1 unrelated) | unused — safe to remove in 3.8.0 |
+| `DisplayManager.draw_rain` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `DisplayManager.draw_snow` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `DisplayManager.draw_weather_icon` | 3.8.0 | core (1 internal) | — | ledmatrix-weather (5 unrelateds) | unused — safe to remove in 3.8.0 |
+| `DisplayManager.draw_text_with_icons` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `DisplayManager.get_scrolling_stats` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `FontManager.get_manager_fonts` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `FontManager.get_detected_fonts` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `FontManager.unregister_plugin_fonts` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `FontManager.get_plugin_fonts` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `FontManager.set_override` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `FontManager.remove_override` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `FontManager.get_overrides` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `FontManager.get_available_fonts` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `FontManager.get_size_tokens` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `FontManager.get_performance_stats` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `FontManager.get_font_catalog` | 3.8.0 | core tests (1 test call) | — | — | unused — safe to remove in 3.8.0 |
+| `FontManager.add_font` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `FontManager.remove_font` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `FontManager.validate_font` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `BasePlugin.get_supported_vegas_modes` | 3.9.0 | core tests (2 test reviews) | blackjack (1 call, 1 override); calendar (1 override); olympics (1 override) | — | still used by blackjack, calendar, olympics — keep or migrate first |
+| `BasePlugin.get_vegas_segment_width` | 3.9.0 | core tests (1 test review) | — | — | unused — safe to remove in 3.9.0 |
+| `PluginManager.get_enabled_plugins` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+
+## Unused — safe to remove (36)
+
+`CacheManager.has_data_changed`, `CacheManager.update_cache`, `CacheManager.setup_persistent_cache`, `CacheManager.get_sport_live_interval`, `CacheManager.get_sport_key_from_cache_key`, `CacheManager.get_background_cached_data`, `CacheManager.is_background_data_available`, `CacheManager.record_cache_hit`, `CacheManager.record_cache_miss`, `CacheManager.record_fetch_time`, `CacheManager.get_cache_metrics`, `CacheManager.log_cache_metrics`, `CacheManager.get_memory_cache_stats`, `DisplayManager.draw_sun`, `DisplayManager.draw_cloud`, `DisplayManager.draw_rain`, `DisplayManager.draw_snow`, `DisplayManager.draw_weather_icon`, `DisplayManager.draw_text_with_icons`, `DisplayManager.get_scrolling_stats`, `FontManager.get_manager_fonts`, `FontManager.get_detected_fonts`, `FontManager.unregister_plugin_fonts`, `FontManager.get_plugin_fonts`, `FontManager.set_override`, `FontManager.remove_override`, `FontManager.get_overrides`, `FontManager.get_available_fonts`, `FontManager.get_size_tokens`, `FontManager.get_performance_stats`, `FontManager.get_font_catalog`, `FontManager.add_font`, `FontManager.remove_font`, `FontManager.validate_font`, `BasePlugin.get_vegas_segment_width`, `PluginManager.get_enabled_plugins`
+
+## Still used — keep or migrate first (1)
+
+`BasePlugin.get_supported_vegas_modes`
+
+## Every hit
+
+File paths are relative to the plugin's directory (core: the repo root).
+
+| Method | Where | File:line | Kind | Code |
+|---|---|---|---|---|
+| `CacheManager.get_sport_live_interval` | core | src/cache/cache_strategy.py:28 | unrelated | `def get_sport_live_interval(self, sport_key: str) -> int:` |
+| `CacheManager.get_sport_live_interval` | core | src/cache/cache_strategy.py:60 | unrelated | `live_interval = self.get_sport_live_interval(sport_key)` |
+| `CacheManager.get_sport_live_interval` | core | src/cache_manager.py:785 | unrelated | `return self._strategy_component.get_sport_live_interval(sport_key)` |
+| `CacheManager.get_sport_key_from_cache_key` | core | src/cache/cache_strategy.py:214 | unrelated | `def get_sport_key_from_cache_key(self, key: str) -> Optional[str]:` |
+| `CacheManager.get_sport_key_from_cache_key` | core | src/cache_manager.py:806 | unrelated | `return self._strategy_component.get_sport_key_from_cache_key(key)` |
+| `CacheManager.get_sport_key_from_cache_key` | core | src/cache_manager.py:816 | unrelated | `sport_key = self._strategy_component.get_sport_key_from_cache_key(key)` |
+| `CacheManager.record_cache_hit` | core | src/cache_manager.py:869 | internal (in `CacheManager.get_background_cached_data`) | `self.record_cache_hit('background')` |
+| `CacheManager.record_cache_miss` | core | src/cache_manager.py:876 | internal (in `CacheManager.get_background_cached_data`) | `self.record_cache_miss('background')` |
+| `CacheManager.record_fetch_time` | core | src/cache/cache_metrics.py:67 | unrelated | `def record_fetch_time(self, duration: float) -> None:` |
+| `CacheManager.record_fetch_time` | core | src/cache_manager.py:922 | unrelated | `self._metrics_component.record_fetch_time(duration)` |
+| `CacheManager.get_memory_cache_stats` | core tests | test/test_cache_manager_memory_tier.py:43 | test call | `stats = cm.get_memory_cache_stats()` |
+| `CacheManager.get_memory_cache_stats` | core tests | test/test_cache_manager_memory_tier.py:63 | test call | `assert cm.get_memory_cache_stats()["last_cleanup"] >= before` |
+| `CacheManager.get_memory_cache_stats` | core tests | test/test_cache_manager_memory_tier.py:68 | test call | `stats = cm.get_memory_cache_stats()` |
+| `DisplayManager.draw_sun` | core | src/plugin_system/testing/visual_display_manager.py:417 | unrelated | `def draw_sun(self, x: int, y: int, size: int = 16):` |
+| `DisplayManager.draw_cloud` | core | src/display_manager.py:1359 | internal (in `DisplayManager.draw_rain`) | `self.draw_cloud(x, y, size)` |
+| `DisplayManager.draw_cloud` | core | src/display_manager.py:1374 | internal (in `DisplayManager.draw_snow`) | `self.draw_cloud(x, y, size)` |
+| `DisplayManager.draw_cloud` | core | src/plugin_system/testing/visual_display_manager.py:421 | unrelated | `def draw_cloud(self, x: int, y: int, size: int = 16, color: Tuple[int, int, int] = (200, 200, 200)):` |
+| `DisplayManager.draw_cloud` | ledmatrix-weather | weather_icons.py:184 | unrelated | `def draw_cloud(draw: ImageDraw, x: int, y: int, size: int = 16, color: tuple = (200, 200, 200)):` |
+| `DisplayManager.draw_rain` | core | src/plugin_system/testing/visual_display_manager.py:425 | unrelated | `def draw_rain(self, x: int, y: int, size: int = 16):` |
+| `DisplayManager.draw_snow` | core | src/plugin_system/testing/visual_display_manager.py:429 | unrelated | `def draw_snow(self, x: int, y: int, size: int = 16):` |
+| `DisplayManager.draw_weather_icon` | core | src/display_manager.py:1518 | internal (in `DisplayManager.draw_text_with_icons`) | `self.draw_weather_icon(icon_type, icon_x, icon_y)` |
+| `DisplayManager.draw_weather_icon` | core | src/plugin_system/testing/visual_display_manager.py:510 | unrelated | `def draw_weather_icon(self, condition: str, x: int, y: int, size: int = 16) -> None:` |
+| `DisplayManager.draw_weather_icon` | core | src/plugin_system/testing/visual_display_manager.py:533 | unrelated | `self.draw_weather_icon(icon_type, icon_x, icon_y)` |
+| `DisplayManager.draw_weather_icon` | ledmatrix-weather | manager.py:84 | unrelated | `def draw_weather_icon(image, icon_code, x, y, size):` |
+| `DisplayManager.draw_weather_icon` | ledmatrix-weather | manager.py:1280 | unrelated | `WeatherIcons.draw_weather_icon(img, icon_code, icon_x, icon_y,` |
+| `DisplayManager.draw_weather_icon` | ledmatrix-weather | manager.py:1559 | unrelated | `WeatherIcons.draw_weather_icon(img, forecast['icon'], icon_x, icon_y, icon_size)` |
+| `DisplayManager.draw_weather_icon` | ledmatrix-weather | manager.py:1650 | unrelated | `WeatherIcons.draw_weather_icon(img, forecast['icon'], icon_x, icon_y, icon_size)` |
+| `DisplayManager.draw_weather_icon` | ledmatrix-weather | weather_icons.py:168 | unrelated | `def draw_weather_icon(image: Image.Image, icon_code: str, x: int, y: int, size: int = DEFAULT_SIZE):` |
+| `DisplayManager.draw_text_with_icons` | core | src/plugin_system/testing/visual_display_manager.py:526 | unrelated | `def draw_text_with_icons(self, text: str, icons: List[tuple] = None,` |
+| `FontManager.get_font_catalog` | core tests | test/test_deprecation.py:229 | test call | `assert fm.get_font_catalog() == fm.font_catalog` |
+| `BasePlugin.get_supported_vegas_modes` | core tests | test/test_vegas_participation.py:356 | test review | `assert plugin.get_supported_vegas_modes() == [` |
+| `BasePlugin.get_supported_vegas_modes` | core tests | test/test_vegas_participation.py:358 | test review | `assert plugin.get_supported_vegas_modes()` |
+| `BasePlugin.get_supported_vegas_modes` | blackjack | manager.py:732 | override | `def get_supported_vegas_modes(self):` |
+| `BasePlugin.get_supported_vegas_modes` | blackjack | manager.py:695 | call | `if mode in self.get_supported_vegas_modes():` |
+| `BasePlugin.get_supported_vegas_modes` | calendar | manager.py:875 | override | `def get_supported_vegas_modes(self) -> List[VegasDisplayMode]:` |
+| `BasePlugin.get_supported_vegas_modes` | olympics | manager.py:624 | override | `def get_supported_vegas_modes(self) -> List[VegasDisplayMode]:` |
+| `BasePlugin.get_vegas_segment_width` | core tests | test/test_vegas_participation.py:359 | test review | `assert plugin.get_vegas_segment_width() == 2` |
+
+## Sources scanned
+
+| Source | Group | Python files | Hits |
+|---|---|---|---|
+| core | core | 172 | 20 |
+| core tests | core-tests | 347 | 17 |
+| 7-segment-clock | monorepo | 3 | 0 |
+| afl-scoreboard | monorepo | 35 | 0 |
+| baseball-scoreboard | monorepo | 61 | 0 |
+| basketball-scoreboard | monorepo | 49 | 0 |
+| birdnet-go | monorepo | 2 | 0 |
+| blackjack | monorepo | 7 | 2 |
+| calendar | monorepo | 5 | 1 |
+| christmas-countdown | monorepo | 3 | 0 |
+| clock-simple | monorepo | 2 | 0 |
+| countdown | monorepo | 5 | 0 |
+| cricket-scoreboard | monorepo | 8 | 0 |
+| f1-scoreboard | monorepo | 15 | 0 |
+| fantasy-blitz | monorepo | 13 | 0 |
+| football-scoreboard | monorepo | 74 | 0 |
+| geochron | monorepo | 10 | 0 |
+| hello-world | monorepo | 2 | 0 |
+| hockey-scoreboard | monorepo | 52 | 0 |
+| incoming-packages | monorepo | 8 | 0 |
+| jellyfin-now-playing | monorepo | 4 | 0 |
+| lacrosse-scoreboard | monorepo | 40 | 0 |
+| ledmatrix-elections | monorepo | 12 | 0 |
+| ledmatrix-flights | monorepo | 48 | 0 |
+| ledmatrix-leaderboard | monorepo | 9 | 0 |
+| ledmatrix-music | monorepo | 11 | 0 |
+| ledmatrix-stocks | monorepo | 7 | 0 |
+| ledmatrix-weather | monorepo | 15 | 6 |
+| march-madness | monorepo | 4 | 0 |
+| masters-tournament | monorepo | 10 | 0 |
+| mqtt-notifications | monorepo | 4 | 0 |
+| news | monorepo | 6 | 0 |
+| nfl-draft | monorepo | 3 | 0 |
+| nfl-stat-leaders | monorepo | 8 | 0 |
+| nrl-scoreboard | monorepo | 30 | 0 |
+| odds-ticker | monorepo | 9 | 0 |
+| of-the-day | monorepo | 14 | 0 |
+| olympics | monorepo | 16 | 1 |
+| on-air | monorepo | 2 | 0 |
+| pomodoro-timer | monorepo | 3 | 0 |
+| soccer-scoreboard | monorepo | 47 | 0 |
+| static-image | monorepo | 3 | 0 |
+| stock-news | monorepo | 3 | 0 |
+| text-display | monorepo | 4 | 0 |
+| tide-display | monorepo | 3 | 0 |
+| ufc-scoreboard | monorepo | 38 | 0 |
+| web-ui-info | monorepo | 2 | 0 |
+| youtube-stats | monorepo | 5 | 0 |
+| f1-live | third-party | 10 | 0 |
+| gif-player | third-party | 1 | 0 |
+| pga-tour-leaderboard | third-party | 2 | 0 |
+| plex-marquee | third-party | 1 | 0 |
+| ledmatrix-dresden-departures | third-party | 1 | 0 |
+| tidbyt-baseball-scoreboard | third-party | 2 | 0 |
+| sleeper-fantasy | third-party | 1 | 0 |
+| ledmatrix-nascar | third-party | 1 | 0 |
+
+## How to re-run
+
+```bash
+# Clones the monorepo and each third-party plugin (depth 1) into a temp cache:
+python3 scripts/plugin_api_usage.py --output docs/DEPRECATIONS_3.8.md
+# Or scan a local monorepo checkout (read only) instead of cloning it:
+python3 scripts/plugin_api_usage.py --monorepo ../ledmatrix-plugins
+```
+
+Before removing a method in its release, re-run the scan against the current monorepo and registry: a plugin added since this file was generated may have started calling it. Remove only methods the fresh scan reports unused; move the rest to a later release (the test in `test/test_deprecation.py` fails while a marker names a release at or below `src.__version__`).

docs/DEVELOPER_QUICK_REFERENCE.md

@@ -54,8 +54,8 @@ rows = self.layout.bounds.inset(1).split_v(3, 1, gap=1)
 self.draw_fit("12:34", rows[0])                 # largest crisp font that fits
 self.draw_image(logo, rows[1], mode="fill_height", crop_to_ink=True)
 
-# Weather icons: draw_weather_icon() is deprecated, removed in 3.7.0 —
-# draw your own icons (the weather plugin ships WeatherIcons)
+# Weather icons: draw_weather_icon() was removed in 3.8.0 — draw your
+# own icons (the weather plugin ships WeatherIcons)
 
 # Scrolling state
 display_manager.set_scrolling_state(True)
@@ -78,7 +78,7 @@ strategy = cache_manager.get_cache_strategy("weather")
 ```
 
 `get_background_cached_data()` (use `get()`) and `get_sport_live_interval()`
-are deprecated, removed in 3.7.0. See
+were removed in 3.8.0. See
 [Deprecated APIs](PLUGIN_API_REFERENCE.md#deprecated-apis).
 
 ## Plugin Manager Quick Methods
@@ -87,8 +87,8 @@ are deprecated, removed in 3.7.0. See
 # Get plugins
 plugin = plugin_manager.get_plugin("plugin-id")
 all_plugins = plugin_manager.get_all_plugins()
-# get_enabled_plugins() is deprecated, removed in 3.7.0 — check `enabled`
-# on the entries in plugin_manager.plugins
+# get_enabled_plugins() was removed in 3.8.0 — check `enabled` on the
+# entries in plugin_manager.plugins
 
 # Get info
 info = plugin_manager.get_plugin_info("plugin-id")

docs/EMULATOR_SETUP_GUIDE.md

@@ -17,13 +17,13 @@ The LEDMatrix emulator allows you to run and test LEDMatrix displays on your com
 ## Prerequisites
 
 ### System Requirements
-- Python 3.10 or higher
+- Python 3.11 or higher (3.11 and 3.13 are tested)
 - Windows, macOS, or Linux
 - At least 2GB RAM (4GB recommended)
 - Internet connection for plugin downloads
 
 ### Required Software
-- Python 3.10+
+- Python 3.11+
 - pip (Python package manager)
 - Git (for plugin management)
 

docs/FONT_MANAGER.md

@@ -13,10 +13,9 @@
 BDF fonts in `assets/fonts/`, registers fonts that plugins ship, and records
 which plugin uses which font so the web UI can show it.
 
-Several methods are deprecated and will be removed in LEDMatrix 3.7.0; they
-log a warning on first call. They are listed in
-[Deprecated methods](#deprecated-methods) below, and the full set is pinned in
-[`test/test_deprecation.py`](../test/test_deprecation.py).
+Several methods were removed in LEDMatrix 3.8.0 after a release of
+deprecation warnings; [Removed methods](#removed-methods) below lists them
+with what to use instead.
 
 ## Getting the FontManager
 
@@ -128,8 +127,8 @@ font = self.font_manager.resolve_font(
 
 `resolve_font()` still honours `config/font_overrides.json` (a map of
 element key to `family` and/or `size_px`), which is read once at start-up.
-The methods that edit it — `set_override()`, `remove_override()`,
-`get_overrides()` — are deprecated, and there is no web UI or REST endpoint
+The methods that edited it — `set_override()`, `remove_override()`,
+`get_overrides()` — were removed in 3.8.0, and there is no web UI or REST endpoint
 for overrides (the override editor and `/api/v3/fonts/overrides` were
 removed). To let users choose a font, add a field to your plugin's config
 schema.
@@ -207,9 +206,10 @@ Current methods:
 | `clear_cache()` | Drop cached fonts and metrics |
 | `font_catalog` (attribute) | Family name → file path |
 
-### Deprecated methods
+### Removed methods
 
-Removed in 3.7.0. Each logs a warning on first call.
+Removed in 3.8.0, after logging a deprecation warning on first call since
+3.5.0.
 
 | Method | Use instead |
 |---|---|

docs/GETTING_STARTED.md

@@ -15,6 +15,12 @@ This guide will help you set up your LEDMatrix display for the first time and ge
 - Power supply (5V, 4A minimum recommended)
 - MicroSD card (16GB minimum)
 
+**Software:**
+- Raspberry Pi OS Lite, Trixie (Debian 13) or Bookworm (Debian 12). Trixie
+  is the current release; Bookworm is listed as Legacy in Raspberry Pi
+  Imager. No other system is supported, and the installer says so up front.
+- The OS's own Python: 3.13 on Trixie, 3.11 on Bookworm
+
 **Network:**
 - WiFi network (or Ethernet cable)
 - Computer with web browser on same network
@@ -28,7 +34,8 @@ This guide will help you set up your LEDMatrix display for the first time and ge
 There is no prebuilt SD card image — you install LEDMatrix onto stock
 Raspberry Pi OS Lite yourself:
 
-1. Flash Raspberry Pi OS Lite to the MicroSD card (Raspberry Pi Imager)
+1. Flash Raspberry Pi OS Lite (Trixie, or Bookworm) to the MicroSD card
+   (Raspberry Pi Imager)
 2. Connect the LED matrix to your Raspberry Pi, insert the card, and
    power on
 3. SSH into the Pi and run the one-shot installer:
@@ -39,6 +46,17 @@ Raspberry Pi OS Lite yourself:
    [README Installation Steps / Quick Install](../README.md#installation-steps)
    for full details
 
+   The one-shot installer installs the newest release (the **stable** update
+   channel). To run the newest, unreleased code from `main` instead (the
+   **beta** channel), put `LEDMATRIX_CHANNEL=beta` in front of `bash`:
+   ```bash
+   curl -fsSL https://raw.githubusercontent.com/ChuckBuilds/LEDMatrix/main/scripts/install/one-shot-install.sh | LEDMATRIX_CHANNEL=beta bash
+   ```
+   A manual clone starts on `main`; add `--beta` to `first_time_install.sh`
+   to stay on it, or leave it off and the first update after the next
+   release moves the device onto releases. You can switch channels later on
+   the General tab.
+
 **Expected Behavior after install:**
 - LED matrix will light up
 - A fresh install ships only the bundled `starlark-apps` and
@@ -240,6 +258,22 @@ The fastest way to verify a plugin works without waiting for the rotation:
 - Install community plugins straight from a GitHub URL via
   **Install from GitHub** on the same tab.
 
+### Keep LEDMatrix Up to Date
+
+- **Update Code** on the **Overview** tab installs the newest version, and a
+  banner at the top of the page says when one is available.
+- **General → Automatic Updates** does it once a week, overnight, with a
+  health check that undoes an update that breaks the device.
+- **General → Update Channel** picks which version that is. **Stable** (the
+  default) installs releases, which have been tested and have release
+  notes. **Beta** installs the newest code as soon as it is written, before
+  it is released: fixes arrive sooner, and so do new problems.
+- Switching to Stable never installs an older version than the one you
+  have. If your device is already newer than the latest release (which is
+  normal if it was set up or updated from the newest code), it keeps
+  getting the newest code until the next release includes it, then follows
+  releases from there. The General tab says when this is the case.
+
 ### Enable Advanced Features
 
 **Vegas Scroll Mode:**

docs/HOW_TO_RUN_TESTS.md

@@ -170,6 +170,31 @@ pytest test/test_config_manager.py
 pytest
 ```
 
+### Web UI JavaScript Tests
+
+The suites in `test/js` need node; the DOM ones also need jsdom and a running
+web interface (details in [`test/js/README.md`](../test/js/README.md)):
+
+```bash
+npm install --no-audit --no-fund --prefix test/js   # jsdom; node_modules is gitignored
+EMULATOR=true python3 web_interface/app.py           # in another shell
+BASE=http://localhost:5000 REQUIRE_DOM=1 node test/js/run_all.js
+```
+
+`pytest test/test_js_unit_suites.py` runs just the unit suites.
+
+### Plugin Config Form Parity
+
+`test/test_field_model_parity.py` checks `build_field_model` against the
+`render_field` macro for every plugin schema it finds
+([WEB_FRONTEND_ARCHITECTURE.md](WEB_FRONTEND_ARCHITECTURE.md)). It always
+covers `plugin-repos/` and the test fixtures; point it at a checkout of the
+official plugins to cover those too:
+
+```bash
+LEDMATRIX_MONOREPO_PLUGINS=../ledmatrix-plugins/plugins pytest test/test_field_model_parity.py
+```
+
 ### Debug a Failing Test
 
 ```bash

docs/IPC_CONTROL_SOCKET.md

@@ -0,0 +1,633 @@
+# Control socket (web → display)
+
+The display process serves a Unix socket that the web interface uses to send
+it commands and get an answer back. It replaces the cache-file "mailboxes" on
+the SD card one command at a time. Stage 1 carries on-demand start, stop and
+status. Stage 2 makes those commands land within a frame on every kind of
+screen, and adds `brightness.set` and `plugin.reload`. Stage 3 adds a state
+stream (`state.get`, `state.subscribe`), so the web interface reads what the
+display is doing from the socket instead of from cache files the display
+wrote to the SD card. The file mailbox and the cache keys stay as a fallback
+for one release.
+
+| | |
+|---|---|
+| Socket | `/run/ledmatrix/control.sock` (tmpfs) |
+| Served by | the display process ([`src/ipc/server.py`](../src/ipc/server.py)), started by `DisplayController.run()` |
+| Used by | the web interface ([`src/ipc/client.py`](../src/ipc/client.py)): `POST /api/v3/display/on-demand/start` and `/stop`, `POST /api/v3/plugins/update` (reload), `POST /api/v3/config/main` (brightness); and through [`web_interface/display_state.py`](../web_interface/display_state.py) (the state stream), `GET /api/v3/display/current-status`, `/display/on-demand/status`, `/plugins/installed` (`runtime`), `/plugins/state` and the reconciliations, `/health` (`display_loop`) |
+| Contract | [`src/ipc/contract.py`](../src/ipc/contract.py): messages, versions, framing and the socket path; both sides import it |
+| Override | `LEDMATRIX_CONTROL_SOCKET=/some/path.sock` for both processes, or `=off` to disable it |
+
+## Why
+
+Before the socket, the web interface sent commands by writing a cache key
+(`display_on_demand_request`) that the display read every 0.25 s.
+
+- **No acknowledgement.** The route answered "success" once the file was
+  written, whether or not a display was running to read it.
+- **Lost requests.** The display had to read the request and then delete it.
+  A request written between those two steps could be thrown away (see
+  `_consume_on_demand_request`). The cache has no atomic claim to prevent it.
+- **Fragile.** Each channel repeated its own permission, atomic-write,
+  staleness and in-memory-cache rules. Two of them caused bugs: a `memory_ttl`
+  bug ignored every on-demand request after the first for an hour, and a
+  stopped display was still reported as "active" for two minutes.
+
+The socket answers every command, carries one request per message (so nothing
+can overwrite it), and belongs to the display process. If the display is not
+running, the socket does not exist, and the web interface knows right away.
+
+## Protocol (version 1)
+
+Stage 3 is still version 1: `state.get` and `state.subscribe` are new
+commands, and a stage-2 display answers them `unknown_command`, which the
+web interface treats as "no socket" and falls back from.
+
+
+**Framing.** One JSON object per line (newline-delimited JSON), UTF-8, at
+most 64 KiB per line (`MAX_MESSAGE_BYTES`). Senders encode with
+`ensure_ascii`, so a newline never appears inside a message. A connection
+can carry several requests. Each request gets exactly one response, in order.
+
+**Request**
+
+```json
+{"v": 1, "id": "5f0c…", "cmd": "on_demand.start",
+ "args": {"plugin_id": "clock", "mode": null, "duration": 30, "pinned": false}}
+```
+
+- `v` is the protocol version.
+- `id` is a printable string of 1-128 characters. It is echoed back in the
+  response, and for on-demand commands it is also the on-demand `request_id`.
+- `cmd` is a command name.
+- `args` is an object. It may be omitted when a command takes no arguments.
+
+**Response**
+
+```json
+{"v": 1, "id": "5f0c…", "ok": true,  "result": {"accepted": true, "request_id": "5f0c…", "queued": 1}}
+{"v": 1, "id": "5f0c…", "ok": false, "error": {"code": "busy", "message": "…"}}
+```
+
+`id` is `null` only when the request could not be parsed far enough to have
+one. Clients branch on `error.code`, never on the message text.
+
+**Commands**
+
+| `cmd` | `args` | `result` | Kind |
+|---|---|---|---|
+| `hello` | `{versions: [int], client?: str}` | `{version, versions, commands, max_message_bytes, server}` | answered directly |
+| `ping` | — | `{pong: true}` | answered directly |
+| `on_demand.start` | `{plugin_id?, mode?, duration?, pinned?}` (at least one of `plugin_id` and `mode`) | ack | queued |
+| `on_demand.stop` | — | ack | queued |
+| `on_demand.status` | — | `{on_demand: {...}, current_mode, display_active}` | answered directly |
+| `brightness.set` | `{brightness: int 0-100}` | `{brightness, panel_brightness, dimmed, display_active}` | queued, awaited (2 s) |
+| `plugin.reload` | `{plugin_id}` | `{plugin_id, reloaded: true, version, modes}` | queued, awaited (10 s) |
+| `state.get` | `{since?, epoch?}` | a state snapshot (see "The state stream") | answered directly |
+| `state.subscribe` | — | a state snapshot, then pushed `state` / `tick` events | answered directly, then a stream |
+
+`duration` is a number of seconds, or a numeric string. `0`, `null` or `""`
+mean "until stopped". `pinned` must be a real boolean: the REST route has
+already converted strings like `"false"` before it sends the command. The
+`on_demand` object in `on_demand.status` is the same dict the display
+publishes to `display_on_demand_state`.
+
+`brightness.set` sets the panel's normal brightness. It is transient: it
+writes nothing to `config.json`, and the next config the display's watcher
+loads (or a restart) puts the configured value back. The web interface
+sends it after it has saved the setting, so the two agree. The dim schedule
+still applies on top, so `panel_brightness` is the dim level while the
+schedule dims. While the schedule has the display off, the new level is
+kept for when it comes back on.
+
+`plugin.reload` loads a plugin the display is running again from disk,
+manifest included: the steps of disabling it live and enabling it again,
+with its modes kept in their place in the rotation. Only a running plugin
+can be reloaded (`not_loaded` otherwise), so the id never makes the display
+import anything new. A plugin loaded only for an on-demand session gets
+`busy`. A new version that fails to load gets `failed` and stays out of the
+rotation, as it would after a restart. The load runs off the render thread,
+so the panel keeps scrolling while it happens (see below).
+
+**Acknowledgements.** A queued on-demand command is *accepted*, not *done*.
+`{"accepted": true, "request_id": …}` means the command is waiting in the
+render thread's queue. Since stage 2 the render thread waits on that queue
+instead of sleeping, so it applies the command within one frame on every
+kind of screen (see below). Any outcome is published as before
+(`display_on_demand_state`, and `status`/`error` for a bad plugin or mode),
+and it can be read with `on_demand.status`.
+
+**Awaited commands.** `brightness.set` and `plugin.reload` are answered only
+once the render thread has applied them, with their result or their error.
+The connection thread waits for that (2 s and 10 s, `AWAIT_SECONDS` in the
+contract); the render thread never waits for a client. When the render thread
+has not got to the command in time, the answer is `pending`: the command
+stays queued and is still applied, so a client treats `pending` as "not known
+to be done", not as a refusal. The client's own timeout is one second longer
+than the display's wait, so `pending` arrives before the client gives up.
+
+**Versions.** Every request carries `v`. For any command except `hello`, a
+`v` the display does not speak gets `unsupported_version`. `hello` is checked
+by its `versions` list instead, and its result names the highest version both
+sides share, so a client can find out what a display supports before it
+relies on anything newer. The client sends `v: 1` and falls back to the
+mailbox when the display refuses it. It does not send `hello` first, which
+saves a round trip.
+
+New commands are added within a version, so stage 2 is still version 1. A
+display that does not know a command answers `unknown_command`, which the
+web interface treats like any other socket failure and falls back from, and
+`hello` lists the commands a display knows. The version changes only when the
+envelope or the meaning of an existing command changes.
+
+**Events.** `state.subscribe` is the one command with more than one message
+in reply. After its response, the display pushes events on the same
+connection until either side hangs up:
+
+```json
+{"v": 1, "id": "<the subscribe id>", "event": "state", "result": {...a state snapshot...}}
+{"v": 1, "id": "<the subscribe id>", "event": "tick",  "result": {"version": 7, "epoch": "…", "pid": 812, "served_at": 1790000000.1, "changed": false, "loop": {...}, "volatile": {"display": {"last_updated": 1790000000.0}, "...": "..."}}}
+```
+
+An event has `event` where a response has `ok`, which is how a reader tells
+them apart. The client sends nothing after the subscribe; anything it does
+send is ignored.
+
+**Error codes:** `bad_json`, `bad_request`, `message_too_large`,
+`unsupported_version`, `unknown_command`, `invalid_args`, `busy` (queue full,
+or too many connections), `forbidden` (peer credentials refused), `internal`.
+Stage 2 adds `pending` (accepted, not applied in time, still queued),
+`not_loaded` (`plugin.reload` of a plugin the display is not running) and
+`failed` (the render thread tried, and it did not work).
+
+Try it on a device:
+
+```bash
+python3 - <<'EOF'
+from src.ipc import client          # run from the project directory
+print(client.on_demand_status())
+print(client.brightness_set(60))
+EOF
+```
+
+## The state stream (stage 3)
+
+Before stage 3 the web interface learned what the display was doing by
+reading files the display kept writing:
+
+| What | Written by the display | How often | Medium |
+|---|---|---|---|
+| current mode, plugin, `is_display_active`, `on_demand_active` | `display_current_state` | every mode change, every flag change, and every 30 s | cache (SD card) |
+| on-demand session | `display_on_demand_state` | on each on-demand event | cache (SD card) |
+| plugin runtime snapshot (#690) | `plugin_runtime_snapshot` | on a change (at most every 10 s), else every 60 s | cache (SD card) |
+| render-loop liveness (#687) | `display-heartbeat.json` | every 5 s | tmpfs |
+
+Now the display also keeps the same state in memory and serves it on the
+socket.
+
+**The snapshot.** `state.get` and `state.subscribe` answer with one object:
+
+```json
+{"schema": 1, "version": 42, "epoch": "3f9c0d1e2a4b5c6d", "pid": 812,
+ "served_at": 1790000000.1, "changed": true,
+ "loop": {"heartbeat_age_seconds": 1.8, "armed": true, "stale_after": 60.0},
+ "state": {
+   "display":    {"mode": "nfl_live", "plugin_id": "football-scoreboard", "mode_index": 3,
+                  "total_modes": 9, "on_demand_active": false, "is_display_active": true,
+                  "last_updated": 1790000000.0},
+   "on_demand":  {"active": false, "status": "idle", "...": "as display_on_demand_state"},
+   "brightness": {"brightness": 80, "panel_brightness": 40, "dimmed": true},
+   "plugins":    {"schema": 1, "running": true, "published_at": 1789999998.5, "...": "as plugin_runtime_snapshot"},
+   "loop":       {"heartbeat_age_seconds": 1.8, "armed": true, "stale_after": 60.0}
+ }}
+```
+
+- `display` and `on_demand` are the dicts the cache keys hold, `plugins` is
+  the runtime snapshot (`build_runtime_snapshot`), and `brightness` is the
+  configured level, what the panel shows now, and whether the dim schedule
+  has it dimmed. A section not published yet is `null`.
+- `loop` is not published: the display measures it when it answers, from
+  the render thread's last beat in memory (`RenderWatchdog.liveness()`),
+  the same beat that writes the heartbeat file. So it keeps ageing while the
+  render thread is stuck, and the socket's connection threads still answer.
+  `heartbeat_age_seconds` is `null` until the loop has drawn its first frame.
+- `version` goes up whenever a section changes, ignoring the timestamps that
+  move on every publish (`last_updated`, `remaining`, `published_at`). It
+  counts within an `epoch`, one run of the display process, so a reader that
+  sees a new `epoch` has a restarted display.
+- `state.get` with `since` and `epoch` from an earlier answer gets just
+  `{changed: false, version, epoch, pid, served_at, loop, volatile}` while
+  nothing has changed. `volatile` is `{section: {key: value}}`: the current
+  values of those ignored timestamps, which the reader merges into the copy
+  it has. They don't make a new version, but they are still news:
+  `display.last_updated` is how a reader knows the render thread is still
+  publishing, and `plugins.published_at` the runtime publisher. Without
+  them a reader's copy kept the timestamps of the last real change, so a
+  mode on screen for over 120 s read as unknown.
+- A snapshot that would not fit in a message (hundreds of plugins) is sent
+  without `plugins`, and `truncated: ["plugins"]` says so. Readers then use
+  the cache for that section only.
+
+**The stream.** `state.subscribe` answers with the snapshot, then:
+
+- a `state` event (a full snapshot) whenever the version changes, and
+- a `tick` at least every 5 s (`SUBSCRIBE_KEEPALIVE_SECONDS`) when nothing
+  changed. It is the short `changed: false` answer, so it carries `loop`
+  (a stalled render loop shows up within one tick) and `volatile` (the
+  timestamps stay as fresh as the writers keep them), and it tells the
+  reader the connection is alive.
+
+A slow reader is never sent a backlog: each event is the latest version, so
+one that falls behind skips the versions in between. A reader that has heard
+nothing for 15 s (three keepalives) stops trusting its copy.
+
+**Who publishes, and when.** All of it is in memory, with no disk writes:
+
+- the render thread, at the places it already published the cache keys:
+  `display` and `brightness` on every pass of
+  `_publish_current_mode_state_if_changed()` (every loop pass, and every
+  `_service_pending_changes()` in a dwell, a scrolling screen or Vegas), and
+  `on_demand` in `_publish_on_demand_state()`. Every pass refreshes
+  `display.last_updated`, so a reader can tell when the render thread has
+  stopped publishing, just as the cache key's 120 s `max_age` does.
+- the plugin runtime publisher's thread, on every 5 s tick: the snapshot is
+  rebuilt when the state machine changed, otherwise only its `published_at`
+  moves. A change reaches subscribers within a tick, without the cache's
+  10 s throttle.
+
+Publishing is a hand-off, as the command queue is in the other direction.
+The hub (`StateHub` in [`src/ipc/server.py`](../src/ipc/server.py)) holds a
+lock only to swap a dict reference, compare it with the last one and bump the
+version. Every socket write happens on the subscriber's own connection
+thread. The render thread never waits for a reader.
+
+### Readers in the web interface
+
+[`web_interface/display_state.py`](../web_interface/display_state.py) holds
+one `state.subscribe` connection per web process
+(`src.ipc.client.StateSubscription`, a daemon thread, started on the first
+read and reconnecting with a backoff of 1 s up to 30 s). A route answers
+from the latest pushed snapshot in memory. Before the subscription has one,
+the route asks once with `state.get` (0.5 s timeout). When neither works, it
+reads the cache keys and the heartbeat file as before:
+
+| Route | From the socket | Fallback |
+|---|---|---|
+| `GET /api/v3/display/current-status` | `state.display` | `display_current_state` |
+| `GET /api/v3/display/on-demand/status` | `state.on_demand`, with `remaining` worked out from `expires_at` now | `display_on_demand_state` |
+| `GET /api/v3/plugins/installed` (`runtime`), `/plugins/state`, `POST /plugins/state/reconcile` and the startup reconciliation | `state.plugins` + `state.loop` | `plugin_runtime_snapshot` + `display-heartbeat.json` |
+| `GET /api/v3/health` (`checks.display_loop`) | `state.loop` | `display-heartbeat.json` |
+
+Each answer says where it came from: `source: "socket" | "cache"` (or
+`"heartbeat_file"` for the health check).
+
+The SSE display stream (`/api/v3/stream/display`) reads the preview frame
+file, not a cache key, so it does not change.
+
+**The same verdicts either way.** The socket's answers are judged by the
+rules the cache readers apply (#726):
+
+- the runtime view is `stalled` when the render loop's heartbeat age is at
+  least `HEARTBEAT_STALE_SECONDS` (60 s, the health check's threshold), and
+  then reports no per-plugin facts;
+- it is `stale` when the snapshot is older than its `stale_after` (the
+  publisher thread stopped);
+- with no beat yet, the snapshot is judged on its own;
+- there is no pid check, because the display that answered is alive;
+- a `display` section the render thread has not refreshed for 120 s reads
+  as unknown, as the cache key does once it ages out.
+
+The age a reader uses is the age the display measured, plus the time since
+the snapshot arrived.
+
+### Fewer SD writes
+
+The cache keys are still written, for one release, as the fallback. While
+the socket serves the readers, the display writes two of them less often.
+"Serves the readers" means a subscriber is connected, or a `state.get` came
+within the last 60 s (`StateHub.readers_active()`):
+
+- `display_current_state` is no longer written on every mode change: once
+  every 60 s (`CURRENT_STATE_RELAXED_REFRESH_SECONDS`, inside the readers'
+  120 s `max_age`), and at once when `is_display_active` or
+  `on_demand_active` changes.
+- `plugin_runtime_snapshot`'s refresh goes from 60 s to 120 s
+  (`RELAXED_REFRESH_INTERVAL`), and the snapshot says so in its own
+  `refresh_interval` and `stale_after` (360 s). Changes are still written at
+  once, at most every 10 s.
+
+`display_on_demand_state` is written only on events, so it is unchanged.
+The heartbeat file is on tmpfs, so it costs no SD writes, and it stays: the
+automatic update's health check reads it.
+
+This is safe because the relaxed rate only applies while readers are using
+the socket. If they stop (the web interface loses the socket, or is stopped),
+the next publish after the reader window writes a changed mode at once, and
+the runtime refresh goes back to 60 s. A fallback reader in that window sees
+a mode up to 60 s old, never one older than its `max_age`.
+
+Measured with fake clocks (`test_cache_writes_per_minute_with_and_without_socket_readers`
+in `test/test_state_stream_readers.py`), for a rotation of 15 s screens:
+
+| Key | Writes/min, no socket readers | Writes/min, socket readers |
+|---|---|---|
+| `display_current_state` | 4.0 | 1.0 |
+| `plugin_runtime_snapshot` | 1.0 | 0.5 |
+| Total | 5.0 | 1.5 |
+
+That is 70% fewer writes for these keys: about 2,200 a day instead of 7,200.
+Shorter screens save more, because the old rate followed the mode changes.
+A display that rarely changes mode (one plugin, a long live game) saves less. Plugin
+data caches, the error snapshot and font usage are written by other code
+and are not affected.
+
+## How the display applies a command
+
+The server's threads never touch rendering. A connection thread parses the
+request, validates it against the contract, and then does one of two things:
+
+- For a command that changes the panel, it puts a `QueuedCommand` on a
+  bounded queue (16 entries) and answers with the ack, or, for an awaited
+  command, with the outcome the render thread reports back through the
+  command's `CommandOutcome`.
+- For a query, it answers from a status snapshot the display provides
+  (`DisplayController._control_status`). The snapshot only reads attributes.
+
+The render thread drains the queue in `_poll_on_demand_requests()`, the same
+place it reads the mailbox:
+
+- An on-demand command goes to `_handle_on_demand_request()`, which is the
+  mailbox's own handler. The two paths share all of their code: activation,
+  the processed-id guard, error publishing, and resuming the rotation
+  afterwards.
+- `brightness.set` is applied there and then (`_apply_control_brightness`),
+  and the current frame is pushed again so the panel shows it.
+- `plugin.reload` starts at the top of the next loop pass, the place where
+  plugins are enabled and disabled live, because there no `display()` and no
+  Vegas iteration is on the stack (`_apply_pending_plugin_reloads`). Until
+  then the current screen ends early, as it does for a WiFi notice: the
+  frame loops, the dwell and Vegas's interrupt check all treat a pending
+  reload as a reason to stop (`_screen_preempted`).
+- Only the quick half of the reload runs on the render thread
+  (`_start_plugin_reload`): the plugin's modes leave the rotation, its
+  config subscription is dropped, and `PluginManager.detach_plugin` takes
+  the instance out of `plugins`. After that nothing new calls the old
+  instance: no `update()`, and no Vegas fetch. The rotation then advances
+  (Vegas resumes its strip), and frames keep coming.
+- The slow half runs on a `plugin-reload-<id>` thread (`_PluginReloadJob`).
+  It waits for the plugin's lock, then tears the old instance down
+  (`unload_detached_plugin`) and loads the new one (`reload_plugin`). The
+  lock can be held for seconds by a Vegas render of the old instance. On
+  ledpi the render thread used to wait for it here, and a football reload
+  froze the panel for 3.0 s.
+- The new instance joins the rotation between two frames
+  (`_finish_plugin_reloads`, from `_service_pending_changes` or the top of
+  the loop). Its modes go back to their old places, Vegas is told to fetch
+  it again, and the command is answered.
+- While the plugin reloads, it is out of the rotation. Vegas scrolls what
+  its strip already holds of it. An on-demand request for it gets
+  `plugin-reloading`. A config reconcile neither loads it a second time nor
+  unloads it mid-load; a disable saved meanwhile is applied once the
+  reload is done. A second reload of the same plugin runs after the first.
+
+The 0.25 s floor on the mailbox read does not apply to the queue, because
+draining it costs no disk read. A queued command also lets
+`_service_pending_changes()` skip its own floor.
+
+### Waking the render thread (stage 2)
+
+Stage 1 made the socket answer, but not land sooner: a queued command waited
+for the same polls the mailbox does. Measured on ledpi (Pi 4, 24 fps Vegas),
+a start took 1.02 s on a static screen and about 0.4 s in Vegas either way.
+Now the queue wakes the render thread:
+
+- **The waits.** The server sets a `threading.Event` whenever it queues a
+  command. The render thread waits on it (`ControlServer.wait_for_command`)
+  where it used to sleep: the static screen's 1 s frame sleep
+  (`_wait_frame_interval`) and the dwell's 0.25 s ticks
+  (`_sleep_with_plugin_updates`, which also covers scheduled-off and the
+  empty-rotation pause). On a wake it applies the command at once. A command
+  that does not end the screen, such as a brightness, does not cut the frame
+  short: the wait carries on to the end of the interval, so the plugin is
+  still drawn once a second.
+- **Vegas.** The coordinator still runs its interrupt check every 10 frames,
+  and now also at any frame where `urgent()` is true. The display passes
+  "a control socket command is queued", which is one `Event.is_set()` per
+  frame.
+- **Scrolling screens** already service pending changes every frame.
+
+So a command lands within a millisecond or so on a static screen and in a
+dwell, and within one frame in Vegas and on a scrolling screen. The mailbox
+keeps its old delays. Commands still run only on the render thread: the
+connection threads only queue them and set the event. The one exception is
+the slow half of `plugin.reload` (tearing down and loading the plugin),
+which runs on its own thread. Every change to the display's state still
+happens on the render thread.
+
+The waits are timed `Event.wait()` calls: no polling, and no more wake-ups
+than the sleeps they replace when nothing arrives. Measured under WSL
+(Python 3.12, 20 s runs in the order before, after, after, before, with the
+socket's accept thread up), the idle process used 0.015–0.018% of a core
+before and 0.019–0.021% after on a static screen, and 0.035–0.037% before and
+0.047% after in a dwell: about 25 µs more per wait, from `Event.wait`'s own
+bookkeeping. A client's send to the render thread waking took 0.72 ms median
+(1.04 ms max), and a whole `brightness.set` round trip 0.64 ms median.
+
+Without a socket (Windows, `LEDMATRIX_CONTROL_SOCKET=off`) the waits are the
+plain sleeps they were.
+
+**Exactly once.** A command and a mailbox write for the same request share
+one `request_id`. If the client times out after the display queued the
+command and then also writes the mailbox, the display processes the request
+once. The existing `on_demand_request_id` and processed-id checks drop the
+second copy.
+
+## Robustness
+
+All of this runs inside the display process, so nothing a client does may
+block the render loop or crash it:
+
+- **Bounded connections.** Each connection gets its own daemon thread, with
+  at most 8 at once. One more is answered `busy` and closed.
+- **Timeouts.** Each read and write times out after 2 s. A message must
+  arrive whole within 5 s of its first byte. An idle connection is closed
+  after 10 s. A slow or stuck client costs one thread for a few seconds.
+- **Malformed input.** A line that is not JSON gets `bad_json`, and the
+  connection carries on. A line longer than 64 KiB gets `message_too_large`,
+  and the connection is closed, because the next message boundary cannot be
+  found. A client that disconnects mid-message is dropped silently. No
+  exception from a handler leaves the connection thread.
+- **Full queue.** When the queue is full, the client gets `busy` and falls
+  back to the mailbox. A full queue means the render thread is stuck, and the
+  systemd watchdog deals with that.
+- **Awaited commands.** The wait for an awaited command's outcome happens on
+  its connection thread and is bounded (`AWAIT_SECONDS`), so a stuck render
+  thread costs that client `pending` and one connection slot for at most
+  10 s. The render thread settles an outcome without blocking; one nobody is
+  waiting for any more is simply dropped.
+- **Startup.** The server binds under a temporary name, sets the mode and the
+  group, then renames the socket into place, so it never appears with the
+  umask's permissions. It removes a stale socket (a file that nothing is
+  listening on). It never removes a live socket or a file that is not a
+  socket. `close()` removes the socket only if it is still the one this
+  process created.
+- **Never fatal.** If the server cannot start (Windows, no `AF_UNIX`, a bind
+  failure, `LEDMATRIX_CONTROL_SOCKET=off`), it logs that and the display runs
+  as before. The web interface then uses the mailbox, and reads the cache
+  keys and the heartbeat file.
+- **Subscribers (stage 3).** A `state.subscribe` connection gives its request
+  slot back and takes one of 4 subscriber slots (`MAX_SUBSCRIBERS`). A fifth
+  gets `busy`. So a few browsers' web processes holding streams can never
+  use up the 8 slots that commands need. Each subscriber has its own thread.
+  A send that cannot finish within the 2 s IO timeout (a reader that stopped
+  reading) drops that subscriber. Nothing else waits for it, and the render
+  thread only publishes to the hub. `close()` wakes every subscriber, so
+  they end at once.
+
+## Security model
+
+The display runs as root and the web interface as the installing user (see
+[PERMISSIONS.md](PERMISSIONS.md)). The socket admits exactly those two, plus
+anything else in the group they share:
+
+1. **The directory.** `/run/ledmatrix` is created by `RuntimeDirectory=ledmatrix`
+   in `ledmatrix.service` (#687): root-owned, `0755`, on tmpfs, and removed
+   when the display stops. Under an older unit, the display creates the
+   directory itself as root, as it does for the heartbeat. No installer
+   change is needed.
+2. **The socket file.** The file is `root:<shared group>` with mode `0660`,
+   and the kernel refuses `connect()` to anyone without write permission on
+   it. The shared group is the cache directory's group whenever that
+   directory is group-writable. That is `ledmatrix` on an installed device
+   (`/var/cache/ledmatrix` is `root:ledmatrix 2775`), and it is the same rule
+   DiskCache uses for every file the two services share. Otherwise the group
+   is the project directory's (`get_shared_group_gid()`, which config files
+   use). With neither, the mode is `0600` and only root can connect.
+3. **Peer credentials.** Where the kernel reports them (`SO_PEERCRED`, on
+   Linux), the server checks every connection again. It accepts root, the
+   display's own user, or a member of the shared group: the peer's primary
+   gid, or a supplementary group read from `/proc/<pid>/status`. If `/proc`
+   is unreadable, it uses the group database. Any other peer gets `forbidden`
+   and is disconnected. This covers a socket mode that someone loosened by
+   hand.
+
+The commands are deliberately narrow. They start or stop on-demand display,
+read its state, set the brightness, and reload a plugin the display is
+already running, all of which anyone who can reach the web UI can already do
+(the last by restarting the display). Nothing on the socket runs a shell,
+writes a file, or names a path, and `plugin.reload` cannot make the display
+import a plugin it was not running. Stages 2 and 3 changed none of the
+access rules above. The state stream carries what the cache keys already
+held, and those are readable by the same group. A subscriber goes through
+the same connect-time and peer-credential checks as any other connection.
+
+**Development.** A display that is not root and cannot write to
+`/run/ledmatrix`, such as `python3 run.py -e` from a checkout, serves the
+socket at `$TMPDIR/ledmatrix-<uid>/control.sock`. That directory is private
+(`0700`), and the server refuses it if another user owns it. The web
+interface, run by the same user, looks there after `/run/ledmatrix`. The test
+suite sets `LEDMATRIX_CONTROL_SOCKET=off` (`test/conftest.py`), so a run on a
+device never touches the live display.
+
+## Stage plan
+
+1. **On-demand, with acks (done, #706).** Contract, server, client.
+   `on_demand.start`/`stop`/`status`, `hello`, `ping`. The REST routes try the
+   socket first and report `transport: "socket" | "mailbox"` (plus
+   `socket_error` on fallback). The mailbox is unchanged, and the plugins that
+   write it directly (birdnet-go, mqtt-notifications, on-air, pomodoro-timer)
+   keep working.
+2. **Commands that were restarts or polls (done).**
+   - The render thread waits on the queue instead of sleeping, and Vegas
+     checks it every frame, so a command lands within a frame on every kind
+     of screen (see "Waking the render thread").
+   - `brightness.set`, transient and with no `config.json` write. `POST
+     /api/v3/config/main` sends it after saving a brightness and reports
+     `brightness_transport`; without the socket the config watcher applies
+     the saved value, as before.
+   - `plugin.reload`, which replaces the `restart_required` answer from #688
+     for a store update of an enabled plugin. `POST /api/v3/plugins/update`
+     answers `restart_required: false, reloaded: true` once the new code
+     runs, and falls back to the restart banner (with `reload_error`)
+     otherwise.
+   - `config.reload` was left out. Its only gain over the config watcher
+     would be skipping the watcher's 2 s mtime poll, and the one setting
+     where those seconds show, brightness, now has its own command. Plugin
+     settings already reach the running plugin through the watcher, and the
+     "which sections changed" ack had no reader: the web interface knows
+     what it saved. A reload from the socket thread would also run every
+     config subscriber on a second thread beside the watcher's.
+3. **A state stream (done).** `state.get` (a versioned snapshot) and
+   `state.subscribe` (the snapshot, then pushed changes and keepalive ticks)
+   carry the current mode, the on-demand state (including the outcome of an
+   acked on-demand command), the brightness, the plugin runtime snapshot and
+   the render loop's liveness, all served from memory (see "The state
+   stream"). The web interface's readers use it and fall back to the cache
+   keys and the heartbeat file. `display_current_state` and
+   `plugin_runtime_snapshot` are written less often while it serves them.
+   The keys remain for one release.
+   - Left for later: the outcome of a `plugin.reload` that answered
+     `pending` is visible only as the plugin's new `loaded_version` in
+     `state.plugins`, not as an event of its own.
+   - Left for later: the SSE display stream reads the preview frame, not
+     state, so nothing relays the stream to the browser yet. A browser still
+     polls the REST routes, which now answer from memory.
+   - Left for later: the store's install of an already-enabled plugin, and
+     an uninstall that keeps its config, still answer `restart_required`.
+     They can now use a load/unload command and report the result the same
+     way the update route does.
+4. **Retire the mailboxes.** After a release in which every device has had the
+   socket, the web interface stops writing `display_on_demand_request`, and
+   the display stops polling it, logging the plugins that still write it so
+   they can move to an in-process `request_display()`. The other cache keys
+   used as messages (`plugin_error_clear_request` and the remaining
+   `display_*` keys) move to the socket or to tmpfs. The display also stops
+   writing `display_current_state`, `display_on_demand_state` and
+   `plugin_runtime_snapshot` once the web interface no longer falls back to
+   them.
+
+## Checking it on a device
+
+```bash
+ls -l /run/ledmatrix/control.sock                 # srw-rw---- root ledmatrix
+sudo journalctl -u ledmatrix | grep "Control socket"
+curl -s -X POST localhost:5000/api/v3/display/on-demand/start \
+  -H 'Content-Type: application/json' -d '{"plugin_id":"clock","duration":20}'
+# ... "transport": "socket"
+```
+
+If the response says `"transport": "mailbox"`, `socket_error` gives the
+reason. `no_socket` means the display is stopped or predates the socket.
+`refused` usually means the web user is not in the socket's group, which
+takes effect when the web service restarts after the user is added.
+
+Brightness and a plugin reload:
+
+```bash
+curl -s -X POST localhost:5000/api/v3/config/main \
+  -H 'Content-Type: application/json' -d '{"brightness":40}'
+# ... "brightness_transport": "socket"
+curl -s -X POST localhost:5000/api/v3/plugins/update \
+  -H 'Content-Type: application/json' -d '{"plugin_id":"clock-simple"}'
+# after a real update of an enabled plugin: "restart_required": false, "reloaded": true
+sudo journalctl -u ledmatrix | grep -E "Brightness set|Reload(ing|ed) plugin"
+```
+
+`unknown_command` in `brightness_socket_error` or `reload_error` means the
+display runs a stage-1 build: restart it once to pick up this one.
+
+The state stream:
+
+```bash
+curl -s localhost:5000/api/v3/display/current-status    # ... "source": "socket"
+curl -s localhost:5000/api/v3/health | python3 -m json.tool | grep -A3 display_loop
+python3 - <<'EOF'
+from src.ipc import client          # run from the project directory
+snap = client.state_get()
+print(snap['version'], snap['epoch'], snap['loop'], snap['state']['display'])
+EOF
+```
+
+`"source": "cache"` means the web interface could not use the socket: the
+display is stopped, predates stage 3, or the web user is not in the
+socket's group.

docs/OFFSCREEN_RENDERING.md

@@ -1,9 +1,10 @@
 # Offscreen Rendering
 
-**Status (2026-09-24):** step 1, offscreen rendering, is implemented
+**Status (2026-09-30):** offscreen rendering is implemented
 (`DisplayManager.offscreen()`, the adapter on the prefetch thread, the plugin
-lock). Steps 2 and 3 are proposed. When all three land, this file becomes the
-reference for how plugin content is rendered off the render thread.
+lock), and so are live elements, which grew out of steps 2 and 3 below: see
+*Live elements*. The segment strip proposed as step 2 was not needed; *Why not
+a SegmentStrip* says why.
 
 First soak of step 1 on hdpi (50 px/s, `pwm_bits` 7, preview open, 8-minute
 runs, A/B/B/A):
@@ -153,136 +154,101 @@ particular keeps presenting while a plugin draws elsewhere.
   fetch left is the inline fallback when no prepared group is ready, which in
   practice is the first extension. Prefetching at start removes that too.
 
-## Keeping live content fresh
+## Live elements: content that changes while it scrolls
 
-Offscreen rendering is also what makes fresh sports scores possible. Today a
-plugin's segment is drawn when its group is prefetched, and the strip carries
-7,000–10,000 px of content ahead of the viewport (hdpi logs: "7153px still
-ahead", "9842px ahead"). At ~100 px/s, a score drawn now reaches the screen
-70–100 seconds later. When a plugin reports new data, Vegas only drops its
-cache (`invalidate_pending_updates`), so the change is drawn on the plugin's
-*next* turn, several minutes later. A segment already in the strip scrolls by
-with the data it was drawn with.
+Offscreen rendering is also what makes fresh content possible. A plugin's
+segment is drawn when its group is prefetched, and the strip carries
+7,000-10,000 px of content ahead of the viewport, so at ~100 px/s a score drawn
+then reaches the screen 70-100 seconds later -- and once in the strip it never
+changed: when a plugin reported new data, Vegas only dropped its caches, so the
+change appeared on the plugin's *next* turn, minutes later.
 
-That was the right trade while every redraw of a canvas-bound plugin stalled
-the scroll. Off the render thread a redraw costs the scroll nothing, so the
-strip can afford three things.
+A plugin can now hand Vegas **live elements** instead of pictures
+(`BasePlugin.get_vegas_elements()`, see "Live Vegas elements" in
+[PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md#live-vegas-elements)):
+named, fixed-width pieces of content -- one per game card, one for a map. Vegas
+records where each lands in the strip and, when the plugin's data changes,
+redraws just the changed ones off the render thread and copies their pixels
+over the old ones between two frames. A card already crossing the panel
+changes; nothing next to it moves.
 
-### 1. Refresh at the gate
+### Why not redraw every frame
 
-Before a segment enters the viewport, check whether its plugin has updated
-since the segment was drawn. If it has, redraw it offscreen and replace it
-while it is still out of sight. Width changes are fine here, because
-everything from that segment onward is still invisible.
+On a Pi the render thread has about 4 ms of slack per refresh at 512x64 after
+the ~6 ms blit, and a scoreboard card is ~29 ms of Pillow work that holds the
+GIL. Drawing on the render thread is out of the question at any rate, so the
+render thread only ever *copies* pixels that are already drawn. Measured on a
+Pi 4 (ledpi): writing a 35 KB card into a 20,000 px strip takes 8.5 µs, a
+101 KB map 17 µs, four cards (the per-frame cap) 34 µs -- against 124 µs for
+the viewport slice every frame already does.
 
-The gate sits `lead` pixels ahead of the viewport's right edge:
-`lead = max(one screen, speed × (render time + margin))`. The render time is
-the plugin's own, measured on each render (sports cards take the longest,
-hundreds of ms up to seconds per the prefetch notes). A plugin whose render
-does not finish before its segment reaches the viewport keeps the old segment.
-The scroll never waits for it.
+### How an update reaches the screen
 
-Content is then at most `lead / speed` seconds old when it appears, a few
-seconds instead of minutes, without changing how far ahead the rotation
-fetches.
+1. A plugin's `update()` completes. The update worker calls
+   `PluginManager._note_update_completed`, which calls the update listeners
+   (`add_update_listener`) there and then, with the plugin's lock still held.
+   Vegas's listener moves the plugin's **epoch** on
+   (`src/vegas_mode/elements.py`, `LiveEpochs`) and wakes the live worker.
+2. The **live worker** (`src/vegas_mode/live_worker.py`), the one background
+   thread that draws for the strip once it holds a live element, finds the
+   plugin's elements whose recorded epoch is older than its current one,
+   nearest the screen first, and calls `get_vegas_elements()` under the
+   plugin's lock (0.25 s wait, then a 1 s backoff). Elements whose `version`
+   is unchanged cost nothing; the rest are pinned and checksummed, and each
+   whose pixels changed becomes a patch in a one-per-element slot (the latest
+   wins).
+3. Between two frames the render thread
+   (`RenderPipeline.apply_live_patches`, from `coordinator.run_frame`) pops at
+   most four patches or two screens of bytes and copies each into the strip
+   with `ScrollHelper.patch_columns`. It takes no lock and draws nothing. A
+   patch made for an older strip, for an element trimmed away or already
+   behind the screen, or from older data than the strip shows, is dropped.
 
-### 2. Replace ahead of the screen
+End to end, a new score reaches a card already on screen within one poll of
+the data source (30 s for live games) plus about a second: the listener is
+immediate, and while live elements exist the update tick that schedules
+plugins runs every second instead of every four.
 
-When a plugin reports new data (the Vegas update tick already names them), any
-of its segments that are **anywhere ahead of the viewport** are redrawn and
-replaced straight away, not only at the gate. That covers the long stretch of
-strip between prefetch and the gate.
+Elements that change with **time** rather than data (an aircraft moving
+between position reports) ask for `refresh_hz`; the worker calls
+`redraw_vegas_element()` -- without the plugin's lock, from state the plugin
+publishes in one assignment -- that often while the element is on or within
+`live_lead_screens` of the screen, capped by `live_max_hz` (5), at 1 Hz
+without the render gate, and halved for an element whose redraws average over
+50 ms.
 
-### 3. Update on screen
+### Geometry
 
-A segment that is already **visible** is patched in place when the redrawn
-version has the same geometry: the same total width, and the same width for
-each card (a sports plugin returns one image per game, joined with
-`intra_plugin_gap`). Scoreboard cards keep a fixed layout, so a score change
-patches in and the digits update as the card scrolls past. The patch is a
-pixel copy of one card (a 150×64 card is ~29 KB) applied by the render thread
-between frames, so a frame never shows half of a patch.
+A live element is never trimmed to its ink: the adapter pads it with
+`content_padding` black columns either side and pins its width, and a redraw
+at any other width is refused (it shows the next time the plugin comes round).
+Records keep **absolute** strip columns -- the strip column plus everything
+trimmed off the front since the strip was composed -- so a trim moves one
+origin rather than every record. Nothing on screen is ever moved, inserted or
+resized; a game added to a slate appears on the plugin's next turn.
 
-When the geometry differs (a game added or dropped, a card that grew), the
-visible part cannot change without a jump. Only the cards not yet on screen
-are replaced, and only if the geometry up to that point is unchanged. Otherwise
-the segment keeps its snapshot until it has scrolled off.
+### Why not a SegmentStrip
 
-### Avoiding wasted work
+The proposal here was to replace the single strip with a list of segments.
+In-place patching of the single strip meets every goal without that: the
+patch is O(element) and the strip layout never changes. What a segment list
+would still buy is cheaper extensions, and most of that came from making the
+strip's PIL copy lazy instead (`ScrollHelper.cached_image`: an extension used
+to rebuild it twice, 1.7-3.8 ms each on a Pi 4). The `extend` row of
+`frame_soak.py`'s "after work" table says whether the rest is worth it.
 
-- **Change detection.** `run_scheduled_updates_with_changes()` names a plugin
-  whenever its `update()` ran, not when its data changed. On hdpi
-  `clock-simple` and `ledmatrix-music` are named on every 4-second tick. A
-  redraw whose pixels hash the same as the segment's is discarded without a
-  swap.
-- **Redraw on real updates only.** Vegas makes no API calls. Each plugin
-  fetches on its own schedule, and a redraw is triggered only when the
-  plugin's `update()` has run since its segment was drawn. On hdpi live
-  football, baseball and hockey poll every 30 s (live odds every 60 s,
-  everything else hourly), so a live sports card is redrawn once per poll.
-- **Floor.** A plugin is redrawn at most once per
-  `vegas_scroll.refresh_min_interval` (proposed 10 s), and never while its
-  previous redraw is still running. The floor never holds back a sports card
-  polling every 30 s. It exists for chatty plugins: `clock-simple` updates
-  every second and `ledmatrix-music` polls every 2 s.
-- **One worker.** Redraws go through the same background worker as prefetch,
-  one plugin at a time at `nice 10`, under the plugin's lock.
+### When it is off
 
-Data freshness is still bounded by each plugin's own fetch interval (how often
-it polls live scores). Drawing faster cannot beat the data source.
-
-### The strip becomes a list of segments
-
-All three need the strip to be replaceable by segment. Today it is one
-image (`ScrollHelper.cached_array`, 8,000–20,000 px wide, 1.5–3.8 MB), and
-`append_content()` rebuilds the whole thing on the render thread for every
-appended block. That is also a pause source.
-
-Proposed `SegmentStrip`, used by Vegas in place of the single image:
-
-- an ordered list of segments: plugin id, card boundaries, a pixel array, the
-  render time, and the plugin data version it was drawn from, plus its
-  x-offset in the strip;
-- `visible(x, width)` assembles the viewport by slicing across at most a few
-  segments: the same ~100 KB copy per frame that slicing the single image
-  costs today;
-- append and trim become O(block) list operations, not a copy of the strip;
-- replace swaps one list entry and shifts the offsets of the segments after it
-  (dozens at most). A same-geometry patch copies pixels into the existing array.
-
-Every mutation is prepared off the render thread and applied by the render
-thread at a frame boundary, so the strip the render loop reads is never
-half-changed.
-
-### Multi-display sync
-
-The follower renders from its own copy of the strip, offset from the leader's
-scroll position. Today the leader sends that copy whole, and only in
-`start_new_cycle()` (`send_scroll_image`), plus the scroll position every
-frame. Continuous scroll, the default, extends and trims the strip without
-starting a new cycle, and nothing sends those changes. From reading the code,
-the follower therefore probably falls out of step after the first extension
-already, before any of this design. That is untested; it needs a two-Pi rig.
-
-With a segment strip, keeping the follower identical becomes **replaying the
-leader's operations**:
-
-- Every strip mutation (append, trim, replace, patch) is one operation in
-  strip coordinates. The leader applies it and sends the same operation to the
-  follower over the existing TCP channel. Segments are small: a card is ~29 KB
-  raw and compresses well.
-- Operations on off-screen segments apply on arrival. A patch to a segment
-  that is on either panel carries an *apply at scroll position X* stamp a
-  couple of hundred milliseconds ahead. Both sides apply it when their scroll
-  position passes X, so both panels change on the same frame, within the
-  existing position-sync jitter.
-- Each operation carries a sequence number. A follower that sees a gap (a
-  reconnect, a dropped message) asks for a full snapshot, which is today's
-  `send_scroll_image` path.
-
-That also fixes the probable continuous-mode gap as a side effect, since
-appends and trims become operations too. Until it is in place, fresh-content
-updates are disabled while sync is active.
+- `display.vegas_scroll.live_refresh: false` (the kill switch; also in the
+  web UI), or `vegas_live: false` in one plugin's section.
+- Always under multi-display sync: the follower mirrors whole strips only, so
+  a patch would never reach it. (Continuous-mode sync has a separate problem:
+  the follower is not sent extensions or trims at all.)
+- In swap mode (`continuous_scroll: false`) and with `offscreen_prefetch:
+  false`.
+- For plugins without the hook, which are drawn and placed exactly as before,
+  and on the paths that fetch without the plugin's lock (the first strip of a
+  run, the render thread's fallback fetch), which use `get_vegas_content()`.
 
 ## Risks, and what was checked
 
@@ -328,11 +294,10 @@ updates are disabled while sync is active.
   source of the single-refresh late frames. Holding frames for two refreshes
   (≈50 px/s) doubles the budget. Cutting the blit itself is the native-presenter
   step.
-- **Live refreshes pushed from `update()`.** Some sports plugins call
-  `display()` and `update_display()` from inside `update()`, which runs on the
-  update worker and can push to the panel mid-Vegas. That is a separate
-  hazard. `offscreen()` gives a tool for it (run the update worker offscreen
-  while Vegas owns the panel), but it is out of scope here.
+- **Multi-display sync in continuous mode.** The follower is sent the whole
+  strip only at a new cycle and on connect, never the extensions and trims of
+  continuous mode, so it drifts from the leader after the first extension.
+  Live elements stay off under sync for that reason.
 
 ## Test plan
 
@@ -348,14 +313,15 @@ updates are disabled while sync is active.
 - **Emulator integration:** a stub canvas-bound plugin whose `display()` sleeps
   300 ms. The Vegas render loop never goes a frame without presenting (frame
   timing recorder: zero freezes).
-- **Unit, `SegmentStrip`:** the viewport assembled across segment boundaries
-  matches slicing one concatenated image, pixel for pixel. Append, trim,
-  replace-ahead and same-geometry patch each leave every other column
-  unchanged. A geometry-changing patch of a visible segment is refused.
-- **Freshness:** a stub sports plugin whose score changes every second. The
-  score on screen is never older than `lead / speed` plus the plugin's fetch
-  interval. A visible card's digits change without the frame-timing recorder
-  seeing a late frame. An unchanged redraw is discarded.
+- **Live elements** (`test/test_vegas_live_*.py`,
+  `test/test_vegas_elements_*.py`, `test/test_scroll_helper_patch.py`): every
+  record points at exactly its element's pixels through any sequence of
+  compose, extend and trim; a patch changes only its element's columns (a
+  property test against a twin strip that is never patched); the render
+  thread's apply takes no lock and draws nothing; the worker's priorities,
+  floors, backoff and hand-over; and, end to end on the emulator with the stub
+  plugin (`test/fixtures/plugins/vegas-live-stub`), an update changes a card
+  already in the strip and an animated element moves with no update at all.
 - **Hardware:** an hdpi soak, A/B against the #628 build, alternating order.
   Targets: no freezes, an empty 6+ bucket, the 3–5 bucket near zero, and the late
   rate below 0.66%. Plus, for freshness: log each segment's age when it enters
@@ -363,26 +329,26 @@ updates are disabled while sync is active.
 
 ## Rollout
 
-Three changes, each soaked on hdpi before the next:
+1. **Offscreen rendering** (shipped): `offscreen()`, the adapter on the
+   prefetch thread, and the plugin lock. Removed the render-thread pauses.
+2. **Measurement and the lazy strip image:** late frames attributed to the
+   render-thread work before them (`FrameTimingRecorder.note_op`, the "after
+   work" table), and extensions no longer rebuilding the strip's PIL copy.
+3. **Live elements:** the plugin API, the records, the worker and in-place
+   patches, with the sports scoreboards and the flight map adopting it.
+4. **Live games in the ticker by default:** `live_in_ticker` true, so a live
+   game's cards update in the marquee instead of the full-screen scoreboard
+   replacing it; existing configs are switched once (`ConfigManager`).
 
-1. **Offscreen rendering:** `offscreen()`, the adapter on the prefetch thread,
-   and the plugin lock. Removes the render-thread pauses.
-2. **`SegmentStrip`:** Vegas's strip becomes a list of segments. Removes the
-   whole-strip copy on append. No visible behaviour change.
-3. **Fresh content:** refresh at the gate, replace ahead, patch on screen,
-   with change detection and the rate limit.
-
-`display.vegas_scroll.offscreen_prefetch` (default `true`) restores today's
+`display.vegas_scroll.offscreen_prefetch` (default `true`) restores the
 deferred path when `false`, and `display.vegas_scroll.live_refresh` (default
-`true`) turns off step 3. Keep both for one release, then delete the old paths.
+`true`) turns live elements off. Keep both for one release, then delete the
+old paths.
 
 ## Open questions
 
-1. Keep the kill switch, or ship without one?
-2. Plugin lock timeout: skip the plugin and keep its cached segment (proposed),
-   or wait longer?
-3. `refresh_min_interval`: 10 s proposed. It only limits chatty plugins;
-   live sports are redrawn once per 30 s poll regardless.
-4. Multi-display sync: is there a two-Pi rig to test on? Operation replay is
-   proposed as part of the segment strip (step 2), with fresh content
-   disabled under sync until it has been verified on real hardware.
+1. Multi-display sync: is there a two-Pi rig to test on? Replaying strip
+   operations to the follower (append, trim, patch, in absolute columns) would
+   fix continuous-mode sync and let live elements run under it.
+2. Is the `extend` cost worth a segment list after the lazy image? The soak's
+   "after work" table answers it per rig.

docs/PERMISSIONS.md

@@ -29,8 +29,13 @@ in again (services pick them up on restart).
 | `assets/` | web user | dirs `755`, files `644` | Root writes downloaded logos regardless |
 | `/var/cache/ledmatrix/` | `root:ledmatrix` | `2775` (setgid) | Shared cache: see below |
 | Cache files | creator : `ledmatrix` | `660` | |
+| `/run/ledmatrix/` | `root` | `755` | tmpfs; `RuntimeDirectory=` in `ledmatrix.service`, removed when the display stops |
+| `/run/ledmatrix/control.sock` | `root` : cache directory's group (`ledmatrix`) | `660` | The display's control socket; only root and that group can connect. See [IPC_CONTROL_SOCKET.md](IPC_CONTROL_SOCKET.md#security-model) |
 | `scripts/fix_perms/safe_plugin_rm.sh`, `safe_pip_install.sh` | `root:root` | `755` | Run as root through sudo, so the web user must not be able to edit them |
 | `/etc/sudoers.d/ledmatrix_web`, `ledmatrix_wifi` | `root` | `440` | |
+| `/usr/local/sbin/ledmatrix-refresh-units` | `root:root` | `755` | Copy of `scripts/install/ledmatrix_refresh_units.py`, installed by `install_service.sh`. Outside the project so the web user cannot edit what sudo runs |
+| `/var/lib/ledmatrix/unit-backup/` | `root` | `700` | The units the last refresh replaced, for the automatic update's rollback |
+| `/etc/systemd/system/ledmatrix*.service`, `.path` | `root:root` | `644` | Readable so the web interface can compare them with the templates after an update |
 
 What keeps it that way at runtime:
 
@@ -84,6 +89,20 @@ password:
 - `journalctl -u ledmatrix.service *`, `-u ledmatrix *`, `-t ledmatrix *`,
   tagged `NOEXEC`: journalctl opens a pager on a terminal, and a shell
   escape from that pager would be a root shell
+- `/usr/local/sbin/ledmatrix-refresh-units ""` and
+  `/usr/local/sbin/ledmatrix-refresh-units --restore` — exactly these two
+  command lines (`""` means "no arguments"). After an update the first
+  installs the systemd units whose templates changed and runs
+  `systemctl daemon-reload`; the automatic update's rollback runs the second
+  to put the previous units back. The helper takes nothing from the caller:
+  the project folder and the web user come from the installed, root-owned
+  `ledmatrix.service` and `ledmatrix-web.service`. It only replaces the four
+  units `install_service.sh` installs, only if they are already installed,
+  and refuses a template that would change a unit's `User=` (root for the
+  display, the web user for the rest) or `WorkingDirectory=`, or that is a
+  symlink, not a regular file, or over 64 KB. It grants nothing new: the
+  templates are files the web user can edit, but so is `run.py`, which the
+  display service already runs as root.
 
 ### `/etc/sudoers.d/ledmatrix_wifi`
 
@@ -134,7 +153,9 @@ directory.
 | `safe_plugin_rm.sh`, `safe_pip_install.sh` | — | Called by the web interface through sudo | Not for manual use |
 
 To reinstall the sudoers rules, run
-`./scripts/install/configure_web_sudo.sh` (web rules) or
+`./scripts/install/configure_web_sudo.sh` (web rules; the
+`ledmatrix-refresh-units` rules also need the helper itself, which
+`sudo ./scripts/install/install_service.sh` installs) or
 `./scripts/install/configure_wifi_permissions.sh` (WiFi rules and polkit) as
 the web user, not with `sudo`.
 

docs/PLUGIN_API_REFERENCE.md

@@ -14,6 +14,7 @@ Complete API reference for plugin developers. This document describes all method
 - [Display Manager](#display-manager)
 - [Cache Manager](#cache-manager)
 - [Plugin Manager](#plugin-manager)
+- [Fetching data](#fetching-data)
 - [Deprecated APIs](#deprecated-apis)
 
 ---
@@ -149,15 +150,27 @@ Clean up resources when plugin is unloaded. Override to close connections, stop
 
 #### `on_config_change(new_config: Dict[str, Any]) -> None`
 
-Called after plugin configuration is updated via web API.
+Called after the plugin's section of `config.json` changes -- a save in the
+web UI, say. Every lifecycle hook runs in the display process, which is the
+only process that runs plugins: the web interface writes `config.json`, and
+the display's config watcher calls this with the prepared section. See
+[ARCHITECTURE.md](ARCHITECTURE.md#web-and-display-processes-who-runs-plugins).
+
+In the display service it runs on the config watcher thread while holding
+the plugin's lock, so it never overlaps your `update()` or `display()`. If
+the plugin stays busy for more than 5 seconds, the change is applied later
+from the update thread: as soon as the plugin is free, and before its next
+`update()` at the latest.
 
 #### `on_enable() -> None`
 
-Called when plugin is enabled.
+Called when the display loads the plugin enabled: at startup, or when it is
+switched on in the web UI.
 
 #### `on_disable() -> None`
 
-Called when plugin is disabled.
+Called when the display unloads the plugin, e.g. when it is switched off in
+the web UI.
 
 #### `get_update_interval() -> Optional[float]`
 
@@ -296,9 +309,9 @@ the core then falls back to its own live-content check — so a plugin whose
 weight calculation is broken still gets `live_weight` for a game that really
 is live, rather than being demoted to 1.
 
-Only consulted when the user has set `vegas_scroll.live_in_ticker`. With the
-default (`false`) live content preempts Vegas entirely and there is no ticker
-to be weighted within. See
+Only consulted while `vegas_scroll.live_in_ticker` is on (the default since
+3.8.0). With it off live content preempts Vegas entirely and there is no
+ticker to be weighted within. See
 [ADVANCED_FEATURES.md](ADVANCED_FEATURES.md#live-content-in-the-ticker).
 
 ### Vegas scroll hooks
@@ -308,6 +321,58 @@ rotating one at a time. Plugins control how their content appears via
 these hooks. See [ADVANCED_FEATURES.md](ADVANCED_FEATURES.md) for the user
 side of Vegas mode.
 
+#### Vegas participation
+
+Each plugin takes part in Vegas mode in one of three ways:
+
+| Participation | What Vegas does |
+|---|---|
+| `'scroll'` | The plugin's content (`get_vegas_content()`) scrolls by with everything else |
+| `'pause'` | The scroll stops when the plugin's turn comes round; its `display()` draws it full screen for `get_display_duration()` seconds, then the scroll resumes |
+| `'exclude'` | The plugin is left out of Vegas mode |
+
+Declare the plugin's default in `manifest.json`:
+
+```json
+{
+  "id": "my-alerts",
+  "vegas_participation": "pause"
+}
+```
+
+The user can override it per plugin with `vegas_participation` in that
+plugin's config section (it is one of the core-owned properties, see
+[PLUGIN_CONFIG_CORE_PROPERTIES.md](PLUGIN_CONFIG_CORE_PROPERTIES.md)).
+Vegas resolves it in this order:
+
+1. the user's `vegas_participation` config value;
+2. the plugin's `get_vegas_participation()` — the default implementation
+   reads the manifest's `vegas_participation`, then derives a value from
+   the legacy hooks below;
+3. derived from the legacy hooks: `get_vegas_display_mode()` returning
+   `VegasDisplayMode.STATIC` → `'pause'`; otherwise
+   `get_vegas_content_type()` returning `'none'` → `'exclude'`; everything
+   else → `'scroll'`.
+
+Step 3 is exactly what Vegas did before participation existed, so a plugin
+that declares nothing behaves as it always has. Manifest
+`vegas_participation` is new in core 3.8.0; older cores ignore it and use
+the legacy hooks.
+
+#### `get_vegas_participation() -> str`
+
+Returns `'scroll'`, `'pause'` or `'exclude'`. Override it only when the
+answer depends on state — pause only while an alert is live, exclude while
+there is nothing to show; for a fixed answer use the manifest. Vegas applies
+the user's config value before calling an override, so an override does not
+need to check it. A value that is not one of the three is ignored with a log
+line and the legacy hooks decide.
+
+```python
+def get_vegas_participation(self):
+    return 'pause' if self._alert_is_live() else 'scroll'
+```
+
 #### `get_vegas_content() -> Optional[PIL.Image | List[PIL.Image] | None]`
 
 Return content to inject into the scroll. Multi-item plugins (sports,
@@ -315,26 +380,113 @@ odds, news) should return a *list* of PIL Images so each item scrolls
 independently. Static plugins (clock, weather) can return a single image.
 Returning `None` falls back to capturing whatever `display()` produces.
 
-#### `get_vegas_content_type() -> str`
+#### `get_vegas_render_width() -> int`
 
-`'multi'`, `'static'`, or `'none'`. Affects how Vegas mode treats the
-plugin. Default `'static'`.
+The width Vegas wants this plugin's content to occupy, from the plugin's
+`vegas_width_pct` config value or the global
+`display.vegas_scroll.render_width_pct`. Vegas also narrows
+`display_manager` while it asks for content, so a plugin that sizes itself
+from `display_manager.width` does not need to read this.
 
-#### `get_vegas_display_mode() -> VegasDisplayMode`
+#### Live Vegas elements
 
-Returns one of `VegasDisplayMode.SCROLL`, `FIXED_SEGMENT`, or `STATIC`.
-Read from `config["vegas_mode"]` or override directly.
+*New in core 3.8.0.* Content from `get_vegas_content()` is baked into the
+ticker's strip when the plugin's turn is prefetched, so a score drawn then
+scrolls past with that score however many goals are scored while it crosses
+the panel. A plugin that returns **live elements** instead gets them updated
+in place: after its `update()` the ticker asks again, compares each element
+with what the strip holds, and swaps the changed ones in between two frames
+-- on screen included -- without anything next to them moving.
 
-#### `get_supported_vegas_modes() -> List[VegasDisplayMode]`
+```python
+try:
+    from src.plugin_system.vegas_elements import VegasElement
+except ImportError:          # core older than 3.8.0: the hook is never called
+    VegasElement = None
 
-The set of Vegas modes this plugin can render. Used by the UI to populate
-the mode selector for this plugin.
+class MyScoreboard(BasePlugin):
+    def get_vegas_elements(self):
+        if VegasElement is None:
+            return None
+        return [VegasElement(key=f"game:{g['id']}",
+                             image=self._card(g),           # cache by fingerprint
+                             version=self._fingerprint(g))  # changes iff pixels would
+                for g in self.games]
+```
 
-#### `get_vegas_segment_width() -> Optional[int]`
+`VegasElement(key, image, version=None, live=True, refresh_hz=0.0)`:
 
-For `FIXED_SEGMENT` plugins, the number of *panels* the segment
-occupies in the scroll (pixel width = panels × `single_panel_width`,
-from `display.hardware.cols`). `None` uses the default of 1 panel.
+| Field | Meaning |
+|---|---|
+| `key` | Names the element across redraws; unique in the list, stable for the same logical item (`"game:nfl:401547417"`, `"map"`). |
+| `image` | The element now, at the display's height. A live element's **width must not depend on its data**: a redraw at another width is never swapped in (it appears the next time the plugin comes round), because nothing on screen may move. |
+| `version` | Anything hashable that changes exactly when the pixels would. Handed back with the **same image object** as last time, it lets the ticker skip converting the element; a new image is always converted and compared by its pixels, so a redraw for new settings is never missed. `None` means "compare pixels". |
+| `live` | `False` places it as plain content (trimmed, never refreshed): separators, decoration. |
+| `refresh_hz` | For content that changes with **time** rather than data (an aircraft moving between position reports): the ticker calls `redraw_vegas_element()` about this often while the element is on or near the screen, capped by `vegas_scroll.live_max_hz` and at 1 Hz without the rebuilt rgbmatrix binding. |
+
+**`get_vegas_elements() -> Optional[List[VegasElement]]`** — called on the
+ticker's background thread under the plugin's lock (never while `update()`
+runs), on a canvas of its own and told its render width, exactly like
+`get_vegas_content()`. It is called after every `update()` while any of the
+plugin's elements is on or ahead of the screen, so it must be cheap when
+nothing changed (cache images by version), idempotent, and must not fetch.
+Return `None` to use `get_vegas_content()`, which a plugin must keep working
+for older cores and for the paths that do not ask for elements (the ticker's
+first strip, multi-display sync, the `live_refresh` switch).
+
+**`redraw_vegas_element(key, width, height, at) -> Optional[PIL.Image]`** —
+only for elements with `refresh_hz`. Called **without** the plugin's lock,
+possibly while `update()` runs, so read only state `update()` replaces in one
+assignment (an immutable snapshot), never state it mutates in place. `at` is
+the `time.monotonic()` the pixels are expected on the panel: draw the element
+as it should look then. Return exactly `width` x `height`, or `None` to skip
+the tick.
+
+**`notify_vegas_data_changed()`** — data that arrives outside `update()` (a
+background thread, a push callback) calls this so the ticker redraws without
+waiting for the next `update()`. Safe from any thread.
+
+Live elements are never trimmed to their ink: the ticker pads each with
+`content_padding` black columns either side, the margin trimming would have
+left. A single element wider than the plugin's width budget
+(`vegas_max_width_screens`, not counting that padding) is cropped like any
+other content and scrolls by as plain, no longer live. The user can turn them off per plugin with `vegas_live: false` (a
+core-owned property) or for the whole ticker with
+`display.vegas_scroll.live_refresh: false`; they are always off under
+multi-display sync.
+
+`scripts/check_plugin.py` checks the contract for any plugin that implements
+the hook (unique keys, height, width stable with no new data, redraw size,
+slow calls) and prints a `vegas elements` row; the checks are in
+`src/plugin_system/testing/vegas.py`. `test/fixtures/plugins/vegas-live-stub`
+is a small working example.
+
+#### Legacy: `get_vegas_content_type()` and `get_vegas_display_mode()`
+
+Superseded by participation, and still read to derive it when neither the
+user nor the manifest declares one (step 3 above). Only two answers ever
+mattered: `get_vegas_content_type()` returning `'none'`, and
+`get_vegas_display_mode()` returning `VegasDisplayMode.STATIC`.
+
+- `get_vegas_content_type()` returns `'multi'`, `'static'` or `'none'`
+  (default `'static'`).
+- `get_vegas_display_mode()` returns a `VegasDisplayMode` member (not a
+  string — the string `'static'` never paused anything). The default reads
+  the plugin's `vegas_mode` config value (`"scroll"`, `"fixed"` or
+  `"static"`), else maps content type `'multi'` to `SCROLL` and anything
+  else to `FIXED_SEGMENT`.
+
+`SCROLL` and `FIXED_SEGMENT` (and `vegas_mode` `"scroll"` and `"fixed"`)
+have always behaved identically: both scroll. The distinction is deprecated
+and goes away in 3.9.0 — see [Deprecated APIs](#deprecated-apis).
+
+#### Deprecated: `get_supported_vegas_modes()` and `get_vegas_segment_width()`
+
+Never read by core, and removed in 3.9.0: calling the `BasePlugin`
+implementation logs a deprecation warning. A plugin's own override keeps
+working for the plugin itself. `get_vegas_segment_width()` read the
+`vegas_panel_count` config value, which has never affected Vegas — a card's
+width comes from `get_vegas_content()` and `vegas_width_pct`.
 
 > The full source for `BasePlugin` lives in
 > `src/plugin_system/base_plugin.py`. If a method here disagrees with the
@@ -477,18 +629,6 @@ self.display_manager.update_display()
 
 This is the canonical way to render arbitrary images.
 
-### Weather Icons (deprecated)
-
-> Deprecated, removed in 3.7.0 — draw your own icons (the weather plugin
-> ships `WeatherIcons`). See [Deprecated APIs](#deprecated-apis).
-
-- `draw_weather_icon(condition, x, y, size=16)` — icon for a condition
-  string such as `"clear"`, `"clouds"`, `"rain"`, `"snow"`, `"storm"`
-- `draw_sun(x, y, size=16)`, `draw_cloud(x, y, size=16, color=(200, 200, 200))`,
-  `draw_rain(x, y, size=16)`, `draw_snow(x, y, size=16)`
-- `draw_text_with_icons(text, icons=None, x=None, y=None, color=(255, 255, 255))`
-  — text plus a list of `(icon_type, x, y)` icons; calls `update_display()`
-
 ### Scrolling State Management
 
 For plugins that implement scrolling content, use these methods to coordinate with the display system.
@@ -579,20 +719,6 @@ Process any deferred updates if not currently scrolling. Called automatically by
 
 **Note**: Plugins typically don't need to call this directly.
 
-#### `get_scrolling_stats() -> dict`
-
-> Deprecated, removed in 3.7.0. See [Deprecated APIs](#deprecated-apis).
-
-Get current scrolling statistics for debugging.
-
-**Returns**: Dictionary with scrolling state information
-
-**Example**:
-```python
-stats = self.display_manager.get_scrolling_stats()
-self.logger.debug(f"Scrolling: {stats['is_scrolling']}, Deferred: {stats['deferred_count']}")
-```
-
 ### Available Fonts
 
 The Display Manager provides several pre-loaded fonts:
@@ -722,27 +848,6 @@ Get data with automatic strategy detection from cache key.
 data = self.cache_manager.get_with_auto_strategy("nhl_live_scores")
 ```
 
-#### `get_background_cached_data(key: str, sport_key: Optional[str] = None) -> Optional[Dict[str, Any]]`
-
-> Deprecated, removed in 3.7.0 — use `get()`. See [Deprecated APIs](#deprecated-apis).
-
-Get background service cached data with sport-specific intervals.
-
-**Parameters**:
-- `key` (str): Cache key
-- `sport_key` (str, optional): Sport identifier (e.g., 'nhl', 'nba') for live interval lookup
-
-**Returns**: Cached data, or `None` if not found or stale
-
-**Example**:
-```python
-# Uses sport-specific live_update_interval from config
-games = self.cache_manager.get_background_cached_data(
-    "nhl_games",
-    sport_key="nhl"
-)
-```
-
 ### Strategy Methods
 
 #### `get_cache_strategy(data_type: str, sport_key: Optional[str] = None) -> Dict[str, Any]`
@@ -761,23 +866,6 @@ strategy = self.cache_manager.get_cache_strategy("sports_live", sport_key="nhl")
 max_age = strategy['max_age']  # Get configured max age
 ```
 
-#### `get_sport_live_interval(sport_key: str) -> int`
-
-> Deprecated, removed in 3.7.0. See [Deprecated APIs](#deprecated-apis).
-
-Get the live_update_interval for a specific sport from config.
-
-**Parameters**:
-- `sport_key` (str): Sport identifier (e.g., 'nhl', 'nba')
-
-**Returns**: Live update interval in seconds
-
-**Example**:
-```python
-interval = self.cache_manager.get_sport_live_interval("nhl")
-# Returns configured live_update_interval for NHL
-```
-
 #### `get_data_type_from_key(key: str) -> str`
 
 Extract data type from cache key to determine appropriate cache strategy.
@@ -787,17 +875,6 @@ Extract data type from cache key to determine appropriate cache strategy.
 
 **Returns**: Inferred data type string
 
-#### `get_sport_key_from_cache_key(key: str) -> Optional[str]`
-
-> Deprecated, removed in 3.7.0. See [Deprecated APIs](#deprecated-apis).
-
-Extract sport key from cache key for sport-specific strategies.
-
-**Parameters**:
-- `key` (str): Cache key
-
-**Returns**: Sport identifier, or `None` if not found
-
 ### Utility Methods
 
 #### `clear_cache(key: Optional[str] = None) -> None`
@@ -835,30 +912,6 @@ for file_info in files:
     self.logger.info(f"Cache: {file_info['key']}, Age: {file_info['age_display']}")
 ```
 
-### Metrics Methods (deprecated)
-
-#### `get_cache_metrics() -> Dict[str, Any]`
-
-> Deprecated, removed in 3.7.0. See [Deprecated APIs](#deprecated-apis).
-
-Get cache performance metrics.
-
-**Returns**: Dictionary with cache statistics (`total_requests`, `cache_hit_rate`, `background_hit_rate`, `api_calls_saved`, `average_fetch_time`, etc.)
-
-**Example**:
-```python
-metrics = self.cache_manager.get_cache_metrics()
-self.logger.info(f"Cache hit rate: {metrics['cache_hit_rate']:.2%}")
-```
-
-#### `get_memory_cache_stats() -> Dict[str, Any]`
-
-> Deprecated, removed in 3.7.0. See [Deprecated APIs](#deprecated-apis).
-
-Get memory cache statistics.
-
-**Returns**: Dictionary with memory cache stats (size, max_size, etc.)
-
 ---
 
 ## Plugin Manager
@@ -897,14 +950,6 @@ for plugin_id, plugin in all_plugins.items():
     self.logger.info(f"Plugin {plugin_id} is loaded")
 ```
 
-#### `get_enabled_plugins() -> List[str]`
-
-> Deprecated, removed in 3.7.0 — check `enabled` on the instances in `plugin_manager.plugins`. See [Deprecated APIs](#deprecated-apis).
-
-Get list of enabled plugin IDs.
-
-**Returns**: List of plugin identifier strings
-
 #### `get_plugin_info(plugin_id: str) -> Optional[Dict[str, Any]]`
 
 Get plugin information including manifest and runtime info.
@@ -986,6 +1031,103 @@ if weather is not None and weather.enabled:
 
 ---
 
+## Fetching data
+
+Use the core helpers for HTTP rather than a `requests.Session` of your own:
+`APIHelper` (`from src.common import APIHelper`) for JSON APIs, and
+`fetch_espn_scoreboard()` (`src.common.espn_dates`) or
+`BackgroundDataService` for ESPN scoreboards. Since the release after 3.7.0
+these go through the core **fetch service** (`src/common/fetch_service.py`),
+so a plugin that uses them gets the following with no code change. Return
+values, exceptions and retries are what they were.
+
+- **Shared connections.** Core sessions with the same retry policy share one
+  connection pool per host, instead of one pool per helper.
+- **Merged requests.** Identical GETs in flight at the same time (same URL
+  and query, headers, timeout and retry policy) go to the network once, and
+  every caller gets its own copy of the response, or the same exception.
+- **Host budgets.** A host can have a token-bucket budget. A request past it
+  waits for a token, but never longer than `max_wait_seconds` (2 s by
+  default). Only ESPN hosts have one by default (20 requests a second, burst
+  200), which normal use never reaches.
+- **Conditional GET.** When a server sends `ETag` or `Last-Modified`, the
+  next identical request revalidates, and a `304 Not Modified` comes back to
+  your code as the original `200` with its body. ESPN currently sends
+  neither, so this does nothing there.
+- **Response cache.** A response whose server says `Cache-Control:
+  max-age=N` answers an identical GET for those N seconds without a
+  request (ESPN sends 1 to ~500 s). It never hands you a response older
+  than you accept: pass `cache_max_age=<your TTL>` to `fetch_get()` or
+  `fetch_espn_scoreboard()` (0 always asks the network); without it a
+  response is reused for at most 30 seconds.
+- **Counters.** Requests, merged requests, bytes, 304s, errors and time spent
+  waiting, and requests answered without the network (`memo_hits` from the
+  response cache, `cache_hits` from a shared scoreboard cache entry), are
+  counted per plugin and per host, and published for the web UI
+  at `GET /api/v3/plugins/fetch-stats` (see
+  [REST_API_REFERENCE.md](REST_API_REFERENCE.md#get-fetch-statistics)). A
+  request is counted against your plugin when it runs inside your
+  `update()`/`display()`, your constructor or `on_enable()`, or anywhere in
+  code under your plugin's directory, including threads you start.
+
+What is not covered yet: requests a plugin makes with its own `requests.get()`
+or `Session.get()` calls. They work as before but are invisible to the
+budgets and counters.
+
+### One cache key per ESPN scoreboard
+
+Cache an ESPN scoreboard under `espn_scoreboard_cache_key(sport, league,
+dates)` (`src.common.espn_dates`), not a key of your own, so every plugin
+showing that league shares one fetch and one cached copy. `sport` and
+`league` are ESPN's path segments (`football`, `college-football`), and
+`dates` is what you send as `dates=` (`"20261004"`, `"202610"`,
+`"20260925-20261016"`, a `date`, or `None` for the undated scoreboard).
+
+```python
+from src.common.espn_dates import get_espn_scoreboard
+
+data = get_espn_scoreboard(
+    self.session, "football", "nfl", "20261004",
+    cache_manager=self.cache_manager,
+    max_age=300,                       # your TTL: nothing older comes back
+    legacy_keys=["my_old_key_20261004"],  # read once while upgrading
+)
+```
+
+`get_espn_scoreboard` returns a cached copy at most `max_age` seconds old,
+whoever wrote it, and otherwise fetches with `fetch_espn_scoreboard`
+(`limit=500`, ranges split the way ESPN requires) and caches the result
+without a ttl, so each reader applies its own age limit. `max_age=0` always
+fetches but still leaves the copy for others. For a two-step read, use
+`read_espn_scoreboard_cache()` and `store_espn_scoreboard_cache()` around
+your own fetch. Scoreboards built on `SportsFetchMixin` get
+`_schedule_cache_key(datestring)` and `_cached_schedule(key, legacy_keys)`
+for their schedule windows. All of this is in the core release after 3.8.0.
+
+The settings live in `config.json` under `fetch_service`, read when the
+display starts and on a config reload:
+
+```json
+"fetch_service": {
+    "enabled": true,
+    "max_wait_seconds": 2,
+    "rate_limits": {
+        "*.espn.com": {"per_second": 20, "burst": 200},
+        "api.example.com": {"per_second": 1, "burst": 5}
+    }
+}
+```
+
+`rate_limits` keys are a host or a `*.domain` pattern (which also matches
+the bare domain); `"per_second": 0` removes a budget. `"enabled": false`
+turns the whole service into a plain `session.get()`. Two further switches,
+`"single_flight": false` and `"conditional_get": false`, turn off merging and
+revalidation. `"response_cache": {"enabled": false}` turns off the response
+cache; its `default_max_age` (30) is the limit for callers that pass no
+`cache_max_age`.
+
+---
+
 ## Best Practices
 
 ### Caching
@@ -1070,10 +1212,19 @@ if weather is not None and weather.enabled:
 
 ## Deprecated APIs
 
-These still work in 3.6 but log a warning the first time they are called
-(`journalctl -u ledmatrix` shows which one), and are **removed in 3.7.0**.
-Nothing in core, the official plugins or the third-party plugins in the
-registry calls them.
+A deprecated method still works but logs a warning the first time it is
+called (`journalctl -u ledmatrix` shows which one), until the release that
+removes it. [DEPRECATIONS_3.8.md](DEPRECATIONS_3.8.md) is the usage scan
+behind each removal: which of the deprecated methods the official plugins,
+the registry's third-party plugins and core still call or override. Only
+methods that scan reports unused are removed; the rest stay until their
+callers migrate.
+
+### Removed in 3.8.0
+
+Deprecated in 3.5.0 with a warning on first call, and gone in 3.8.0:
+the scan found no caller in any official or third-party plugin. Calling one
+now raises `AttributeError`.
 
 | Object | Methods | Instead |
 |---|---|---|
@@ -1086,3 +1237,17 @@ registry calls them.
 | `font_manager` | `set_override`, `remove_override`, `get_overrides`, `add_font`, `remove_font`, `validate_font`, `get_size_tokens`, `get_performance_stats`, `get_manager_fonts`, `get_detected_fonts`, `get_plugin_fonts`, `unregister_plugin_fonts` | no replacement |
 | `plugin_manager` | `get_enabled_plugins` | check `enabled` on the entries in `plugin_manager.plugins` |
 
+### Removed in 3.9.0
+
+The Vegas APIs that described a fixed-width segment, which Vegas never
+implemented. Vegas participation (`'scroll'`, `'pause'`, `'exclude'`, see
+[Vegas scroll hooks](#vegas-scroll-hooks)) replaces them. Calling one of the
+methods, or setting `vegas_panel_count`, logs a warning once per process.
+No official plugin calls them; calendar, olympics and blackjack override
+`get_supported_vegas_modes()`, which keeps working for the plugin itself.
+
+| What | Instead |
+|---|---|
+| `BasePlugin.get_supported_vegas_modes()` | declare `vegas_participation` in the manifest |
+| `BasePlugin.get_vegas_segment_width()` and the `vegas_panel_count` config key | nothing: a card's width comes from `get_vegas_content()` and `vegas_width_pct` |
+| `VegasDisplayMode.SCROLL` vs `FIXED_SEGMENT` (`vegas_mode` `"scroll"` vs `"fixed"`) | `'scroll'` participation; the two always behaved the same |

docs/PLUGIN_CONFIG_CORE_PROPERTIES.md

@@ -33,6 +33,31 @@ is `CORE_PLUGIN_PROPERTIES` in `src/plugin_system/schema_manager.py`):
    - Read by `src/vegas_mode/plugin_adapter.py` and `BasePlugin`, which
      validate the values themselves and ignore a bad one with a log line
 
+5. **`vegas_participation`** (string enum: `"scroll"`, `"pause"`,
+   `"exclude"`; no default)
+   - Description: how this plugin takes part in Vegas mode — its content
+     scrolls by, the scroll pauses for its turn and shows it full screen, or
+     it is left out
+   - Overrides the plugin's own default (its manifest's
+     `vegas_participation`, else what its legacy Vegas hooks say); unset
+     means "use the plugin's default"
+   - Deliberately has no default: one would be written into every plugin's
+     config and override what each plugin declares
+   - Read by `resolve_vegas_participation()` in
+     `src/plugin_system/base_plugin.py`; see
+     [PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md#vegas-participation)
+
+6. **`vegas_live`** (boolean; no default, unset means on)
+   - Description: for a plugin with live Vegas elements (it implements
+     `get_vegas_elements()`), whether the ticker changes what is already
+     scrolling when the plugin's data changes. `false` shows each card as it
+     was when drawn, as before live elements existed
+   - Ignored by plugins without live elements, and whenever live elements
+     are off for the whole ticker (`display.vegas_scroll.live_refresh`)
+   - Read by `PluginAdapter.is_live_capable()` in
+     `src/vegas_mode/plugin_adapter.py`; see
+     [PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md#live-vegas-elements)
+
 `skin` and `skin_options` were core properties until the skin system was
 removed. A plugin config saved with them still loads and saves; the keys are
 dropped on the next save (see `RETIRED_PLUGIN_KEYS` in `schema_manager.py`).

docs/PLUGIN_DEVELOPMENT_GUIDE.md

@@ -519,15 +519,12 @@ When developing plugins, you'll need to use the APIs provided by the LEDMatrix s
 - `draw_text()` - Text rendering. For images, paste directly onto
   `display_manager.image` (a PIL Image) and call `update_display()`;
   there is no `draw_image()` helper method.
-- `draw_weather_icon()`, `draw_sun()`, `draw_cloud()` - Weather icons
-  (deprecated, removed in 3.7.0 — draw your own icons)
 - `get_text_width()`, `get_font_height()` - Text utilities
 - `set_scrolling_state()`, `defer_update()` - Scrolling state management
 
 **Cache Manager** (`self.cache_manager`):
 - `get()`, `set()`, `delete()` - Basic caching
 - `get_cached_data_with_strategy()` - Advanced caching with strategies
-- `get_background_cached_data()` - deprecated, removed in 3.7.0 — use `get()`
 
 **Plugin Manager** (`self.plugin_manager`):
 - `get_plugin()`, `get_all_plugins()` - Access other plugins
@@ -535,7 +532,7 @@ When developing plugins, you'll need to use the APIs provided by the LEDMatrix s
 
 See [PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md) for complete
 documentation, and its [Deprecated APIs](PLUGIN_API_REFERENCE.md#deprecated-apis)
-table for everything removed in 3.7.0.
+table for everything removed in 3.8.0.
 
 ## 3rd Party Plugin Development
 

docs/README.md

@@ -72,6 +72,8 @@ Going deeper:
 ## Contributing to LEDMatrix itself
 
 - [ARCHITECTURE.md](ARCHITECTURE.md) — processes, display loop, plugin system, web UI; where to start reading
+- [WEB_FRONTEND_ARCHITECTURE.md](WEB_FRONTEND_ARCHITECTURE.md) — the web UI's ES modules, page lifecycle and form model, and the page-by-page migration to them
+- [IPC_CONTROL_SOCKET.md](IPC_CONTROL_SOCKET.md) — the display's control socket: protocol, security model, stage plan
 - [DEVELOPMENT.md](DEVELOPMENT.md) — environment setup
 - [HOW_TO_RUN_TESTS.md](HOW_TO_RUN_TESTS.md) — running the test suite
 - [MULTI_ROOT_WORKSPACE_SETUP.md](MULTI_ROOT_WORKSPACE_SETUP.md) — multi-repo workspace

docs/REST_API_REFERENCE.md

@@ -18,6 +18,39 @@ top level instead of under `data` (install-from-url, registry-from-url, the
 auth endpoints, upload endpoints, `system/git-info`, `system/check-update`),
 the entry below says so.
 
+**Cross-site requests are refused.** A `POST`, `PUT`, `PATCH` or `DELETE`
+carrying an `Origin` header (or, without one, a `Referer`) that is not the
+host the request was sent to gets `403` with `"error_code":
+"CROSS_SITE_REQUEST"`; so does `Origin: null`. This stops other websites from
+driving the Pi through a LAN user's browser. Scripts, curl, Home Assistant and
+the MQTT bridge send neither header and are unaffected. A browser page on
+another origin (a dashboard you host elsewhere, say) can no longer call the
+API; call it server-side instead. Behind a reverse proxy, pass the original
+`Host` through, port included (nginx: `proxy_set_header Host $http_host;`;
+`$host` drops the port) -- `X-Forwarded-Host` is not read.
+
+**Authentication (optional, off by default).** With no web password set,
+nothing below needs credentials. Once one is set (General > Security, or
+[`POST /auth/password`](#web-login-and-api-tokens)), every route needs a login
+session or an API token:
+
+```bash
+curl -H "Authorization: Bearer lmx_..." http://your-pi-ip:5000/api/v3/display/current
+```
+
+Without either, an API route answers `401` with
+`{"status": "error", "error_code": "AUTH_REQUIRED", "message": ...}`, a
+`WWW-Authenticate: Bearer realm="LEDMatrix"` header and the login page's URL
+in `X-LEDMatrix-Login`; an unknown or revoked token gets `"error_code":
+"INVALID_TOKEN"`. Browser page loads are redirected to `/login` instead, and
+HTMX requests get `401` with `HX-Redirect: /login?...`. Never asked for
+credentials: requests from the Pi itself (loopback, with no `X-Forwarded-For`,
+`X-Real-IP`, `Forwarded` or `X-Forwarded-Host` header), `/static/*`, the
+captive-portal probe URLs, `/login`, `/api/v3/health` (status only, see
+[Health Check](#health-check)), and -- only while the Pi is in access-point
+mode -- `/setup`, `GET /wifi/status`, `GET /wifi/scan` and
+`POST /wifi/connect`.
+
 ## Table of Contents
 
 - [Configuration](#configuration)
@@ -35,6 +68,7 @@ the entry below says so.
 - [Health and Status](#health-and-status)
 - [Schedule (dim/power)](#schedule-dimpower)
 - [Integrations](#integrations)
+- [Web login and API tokens](#web-login-and-api-tokens)
 - [Plugin-specific endpoints](#plugin-specific-endpoints)
 - [Starlark Apps](#starlark-apps)
 
@@ -120,10 +154,25 @@ there an unchecked checkbox — which the browser omits — is saved as
 ```json
 {
   "status": "success",
-  "message": "Configuration saved successfully"
+  "message": "Configuration saved successfully",
+  "restart_required": true
 }
 ```
 
+`restart_required` is always true here: display hardware, rotation,
+durations and general settings take effect when the display restarts, and
+the web UI shows its restart banner on the flag. (Plugin sections saved
+through this route reach the running plugin live, like
+`POST /plugins/config`.)
+
+A saved `brightness` is the exception: it reaches the panel without a
+restart. The route also sends it to the running display over the control
+socket (`brightness.set`), which puts it on the panel at once, and the
+response adds `"brightness_transport": "socket"`. Otherwise it is
+`"config"`, with `brightness_socket_error` giving the reason, and the
+display's config watcher applies the saved value within a few seconds, as
+before.
+
 Invalid values (e.g. an out-of-range `target_fps`, a hardware option the
 Raspberry Pi 5 driver cannot use) are rejected with `400` and nothing is
 saved.
@@ -213,7 +262,10 @@ times `07:00`-`23:00`. At least one day must be enabled.
 
 Retrieve `config/config_secrets.json` with every set value replaced by eight
 bullet characters (`"••••••••"`). Empty values and `YOUR_*` placeholders
-are returned as-is, so a client can tell "set" from "not set".
+are returned as-is, so a client can tell "set" from "not set". The
+`web_auth` section (the web login's password hash, API-token hashes and
+cookie key) is left out entirely; [Get Main Configuration](#get-main-configuration)
+leaves it out too.
 
 **Response**:
 ```json
@@ -238,7 +290,8 @@ Replace `config/config.json` with the JSON body (advanced use only).
 Save the secrets file (advanced use only). Masked values (`"••••••••"`)
 and blank strings in the body are dropped, and the rest is merged onto the
 stored secrets, so posting back the GET response unchanged changes nothing.
-A secret cannot be cleared by blanking it here.
+A secret cannot be cleared by blanking it here. A `web_auth` key in the body
+is ignored; the stored login settings are kept.
 
 ---
 
@@ -278,12 +331,19 @@ by the display process (stale after 120 seconds).
   "data": {
     "mode": "nfl_live",
     "plugin_id": "football-scoreboard",
-    "last_updated": 1234567890.123
+    "last_updated": 1234567890.123,
+    "source": "socket"
   }
 }
 ```
 
-When nothing has been published, every field is `null`.
+When nothing has been published, every field is `null`. `source` is
+`socket` when the answer came from the display's state stream over the
+control socket ([IPC_CONTROL_SOCKET.md](IPC_CONTROL_SOCKET.md)), and `cache`
+when it came from the `display_current_state` cache key (no socket: the
+display is stopped or older, or this is Windows). A display whose render
+loop has not refreshed its state for 120 seconds is reported with every
+field `null`, either way.
 
 ### List Display Modes
 
@@ -360,11 +420,16 @@ Get the current on-demand display state.
       "returncode": 0,
       "stdout": "active",
       "stderr": ""
-    }
+    },
+    "source": "socket"
   }
 }
 ```
 
+`source` is `socket` (the display's state stream, with `remaining` worked
+out at the time of the request) or `cache` (the `display_on_demand_state`
+cache key).
+
 With no on-demand request, `state` is
 `{"active": false, "status": "idle", "last_updated": null}`.
 
@@ -390,7 +455,7 @@ Request a specific plugin to display on-demand.
 - `mode` (string, optional): Display mode name (plugin_id inferred if not provided)
 - `duration` (number, optional): Duration in seconds (0 = until stopped)
 - `pinned` (boolean, optional): Pin display (pause rotation)
-- `start_service` (boolean, optional): (Re)start the display service so it picks the request up (default: true)
+- `start_service` (boolean, optional): Start the display service if it is not running (default: true). A running service is never restarted: it picks the request up within about a quarter of a second. When false and the service is stopped, the route returns 400.
 
 **Response**:
 ```json
@@ -402,13 +467,24 @@ Request a specific plugin to display on-demand.
     "mode": "nfl_live",
     "duration": 45,
     "pinned": true,
-    "service": { "active": true, "returncode": 0, "stdout": "", "stderr": "" }
+    "service": { "active": true, "returncode": 0, "stdout": "", "stderr": "" },
+    "transport": "socket"
   }
 }
 ```
 
 `service` is `null` when `start_service` is false.
 
+`transport` says how the request reached the display: `"socket"` means the
+display's control socket acknowledged it (it is queued for the render thread,
+which wakes for it and applies it within a frame; see
+[IPC_CONTROL_SOCKET.md](IPC_CONTROL_SOCKET.md)), `"mailbox"` means it was
+written to the cache mailbox the display polls, as before the socket existed.
+With `"mailbox"`, `socket_error` gives the reason the socket was not used
+(`no_socket` when the display is stopped or predates the socket, `timeout`,
+`refused`, `busy`, ...). Either way the request is applied the same way;
+`request_id` is the same id in both.
+
 ### Stop On-Demand Display
 
 **POST** `/api/v3/display/on-demand/stop`
@@ -431,11 +507,14 @@ Stop the current on-demand display.
   "status": "success",
   "data": {
     "request_id": "uuid-here",
-    "service": null
+    "service": null,
+    "transport": "socket"
   }
 }
 ```
 
+`transport` and `socket_error` are as for start.
+
 ---
 
 ## Plugins
@@ -465,21 +544,75 @@ List all installed plugins with their status and metadata.
         "enabled": true,
         "verified": true,
         "loaded": true,
-        "state": "loaded",
+        "state": "enabled",
         "error_info": null,
+        "loaded_version": "1.2.3",
+        "loaded_at": 1790000000.0,
         "last_updated": "2025-01-15T10:30:00Z",
         "last_commit": "abc1234",
         "last_commit_message": "feat: Add live game updates",
         "branch": "main",
         "web_ui_actions": [],
         "vegas_mode": null,
-        "vegas_content_type": null
+        "vegas_content_type": null,
+        "vegas_participation": "scroll",
+        "vegas_participation_source": "manifest"
       }
-    ]
+    ],
+    "runtime": {
+      "status": "live",
+      "published_at": 1790000030.0,
+      "age_seconds": 12.4,
+      "stale_after": 180.0,
+      "heartbeat_age_seconds": 2.1,
+      "source": "socket"
+    }
   }
 }
 ```
 
+Metadata comes from each plugin's files on disk; `enabled` is the plugin's
+`enabled` flag in `config.json` (missing means disabled, as the display
+reads it). `vegas_mode` is the plugin's configured `vegas_mode`, or `null`.
+
+`loaded`, `state`, `error_info`, `loaded_version` and `loaded_at` come from
+the runtime snapshot the display publishes (the web process runs no plugin
+code). `state` is the display's lifecycle state (`loaded` while loading,
+`enabled`, `disabled`, `error`, `unloaded`); `error_info` is `null` or
+`{"type", "message", "at", "recoverable"}`, with the message redacted and at
+most 200 characters (the full error is at `/errors/*`). `loaded_version` is
+the version the display loaded, which differs from `version` after an update
+until the display restarts. A plugin a live snapshot does not list is
+`loaded: false`, `state: "unloaded"`.
+
+`runtime.status` says whether to believe them: `live` (fresh snapshot from
+a running display), `stalled` (fresh snapshot, but the same process's
+render-loop heartbeat is 60 s or older -- the render loop is hung, as
+[`/health`](#health-check)'s `display_loop: stalled` says), `stale` (not refreshed
+within `stale_after` seconds, or the process that wrote it no longer exists:
+the display is hung or died), `stopped` (the display shut down) or `unknown`
+(nothing published yet). Unless it is `live`, every one of those fields is
+`null`. `heartbeat_age_seconds` is the heartbeat's age when it was taken into
+account, `null` otherwise (no heartbeat, as on the dev server, or one from
+another process). `runtime.source` is `socket` when the snapshot and the
+heartbeat age came from the display's state stream over the control socket,
+and `cache` when they came from the `plugin_runtime_snapshot` cache key and
+the heartbeat file; the rules above are the same for both. Health and metrics are at [`/plugins/health`](#get-plugin-health)
+and `/plugins/metrics`.
+
+`vegas_participation` is what Vegas mode does with the plugin: `"scroll"`,
+`"pause"` or `"exclude"` (see
+[PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md#vegas-participation)),
+and `vegas_participation_source` says where it came from. The web reads it
+the way the display resolves it, as far as files can tell: the user's own
+`vegas_participation` setting (`"config"`), else the manifest's declared
+`vegas_participation` (`"manifest"`). Past those the display derives it from
+the plugin's code -- a `get_vegas_participation()` override or the legacy
+Vegas hooks -- which the web process never runs, so `vegas_participation`
+is `null` and the source is `"runtime"`. A plugin that overrides
+`get_vegas_participation()` decides at run time and can differ from its
+manifest's declaration. `vegas_content_type` is always `null`.
+
 ### Get Plugin Configuration
 
 **GET** `/api/v3/plugins/config?plugin_id=<plugin_id>`
@@ -639,7 +772,19 @@ Install a plugin from the plugin store.
 ```
 
 When the operation queue is unavailable the install runs synchronously and
-the response has only a `message`.
+the response has only a `message` and the restart fields below.
+
+The finished operation's `result` (from `/plugins/operation/<operation_id>`)
+carries `restart_required`: true when the plugin is already enabled in
+`config.json`, because the running display does not load newly installed
+files by itself; `restart_message` then holds the restart banner's wording.
+A plugin that is not enabled needs no restart: enabling it loads it.
+
+A plugin whose registry entry (or downloaded manifest) needs a newer
+LEDMatrix is refused: the synchronous install answers `409` with a message
+such as `Failed to install plugin x: X requires LEDMatrix 3.8.0 or newer…`,
+and a queued one fails with that message. Nothing already installed is
+changed.
 
 ### Uninstall Plugin
 
@@ -664,6 +809,11 @@ Remove an installed plugin.
 }
 ```
 
+The finished operation's `result` carries `restart_required`. Removing the
+plugin's config (the default) lets the display unload it by itself, so it is
+false; with `preserve_config: true` an enabled plugin keeps running until
+the display restarts, and it is true.
+
 ### Update Plugin
 
 **POST** `/api/v3/plugins/update`
@@ -684,11 +834,42 @@ Update a plugin to the latest version. Runs synchronously.
   "message": "Plugin football-scoreboard updated ...",
   "data": {
     "last_updated": "2025-01-15T10:30:00Z",
-    "commit": "abc1234..."
-  }
+    "commit": "abc1234...",
+    "update_status": "updated"
+  },
+  "restart_required": true,
+  "restart_message": "Plugin updated — restart the display to run the new version"
 }
 ```
 
+`update_status` is `updated`, `up_to_date` or `local_only`.
+
+When the plugin changed and is enabled, the route asks the running display
+to reload it over the control socket (`plugin.reload`, see
+[IPC_CONTROL_SOCKET.md](IPC_CONTROL_SOCKET.md)). Once the new code is
+running, the answer is:
+
+```json
+{
+  "status": "success",
+  "message": "Plugin football-scoreboard updated to version 2.1.0; the display is running the new version",
+  "restart_required": false,
+  "reloaded": true,
+  "reloaded_version": "2.1.0"
+}
+```
+
+If the display could not reload it, `restart_required` is true (the running
+display keeps the code it loaded until it restarts) and `reload_error` says
+why: `no_socket` (the display is stopped or predates the socket),
+`unknown_command` (a display older than this command), `not_loaded`,
+`failed` (the new version did not load; it is out of the rotation),
+`pending` (not done within 10 s; it will still be reloaded), or another
+transport reason.
+
+An update this core cannot run answers `409` with `Plugin update refused:`
+and the reason; the installed version is left as it was.
+
 ### Install Plugin from URL
 
 **POST** `/api/v3/plugins/install-from-url`
@@ -717,10 +898,13 @@ Install a plugin directly from a GitHub repository URL. Runs synchronously.
   "message": "Plugin my-plugin installed successfully",
   "plugin_id": "my-plugin",
   "name": "My Plugin",
-  "branch": "main"
+  "branch": "main",
+  "restart_required": false
 }
 ```
 
+`restart_required` follows the same rule as `/plugins/install`.
+
 ### Load Registry from URL
 
 **POST** `/api/v3/plugins/registry-from-url`
@@ -848,6 +1032,76 @@ Metrics for one plugin; `data` has the same fields as one entry above.
 
 Reset metrics for a plugin.
 
+### Get Fetch Statistics
+
+**GET** `/api/v3/plugins/fetch-stats`
+
+Network requests made through the core fetch service
+(`src/common/fetch_service.py`), per plugin and per host, cumulative since
+the display started. Read-only. The display publishes the counters at most
+once a minute when they change (every 10 minutes otherwise), so they can be
+up to a minute old. Requests a plugin makes with its own `requests` calls,
+outside `APIHelper`, `espn_dates`, `BackgroundDataService` and
+`BaseOddsManager`, are not counted yet.
+
+`data.status` is `live`, `stale` (no publish for longer than
+`stale_after`), `stopped` (the display exited; the last counters are kept)
+or `unknown` (nothing published; `data.data` is `null`).
+
+**Response**:
+```json
+{
+  "status": "success",
+  "data": {
+    "status": "live",
+    "age_seconds": 12.4,
+    "data": {
+      "schema": 1,
+      "running": true,
+      "published_at": 1790000000.0,
+      "stale_after": 720.0,
+      "since": 1789990000.0,
+      "totals": {"requests": 412, "merged": 3, "not_modified": 0,
+                 "errors": 1, "http_errors": 2, "retries": 0,
+                 "throttled": 0, "overruns": 0, "bytes": 18234011,
+                 "wait_seconds": 0.0, "memo_hits": 21, "cache_hits": 40,
+                 "legacy_cache_hits": 2},
+      "plugins": {
+        "football-scoreboard": {"requests": 240, "merged": 2, "bytes": 9120330,
+                                "hosts": {"site.api.espn.com": 180,
+                                          "sports.core.api.espn.com": 62},
+                                "...": "the other counters, as in totals"}
+      },
+      "hosts": {
+        "site.api.espn.com": {"requests": 301, "...": "as in totals"}
+      },
+      "validators": {"entries": 0, "bytes": 0},
+      "response_cache": {"entries": 3, "bytes": 412004},
+      "config": {"enabled": true, "single_flight": true,
+                 "conditional_get": true, "max_wait_seconds": 2.0,
+                 "rate_limits": {"*.espn.com": {"per_second": 20.0, "burst": 200.0}},
+                 "response_cache": true, "default_max_age": 30.0}
+    }
+  }
+}
+```
+
+`requests` counts round trips sent (retries inside the HTTP adapter are in
+`retries`), `merged` requests answered by an identical one already in
+flight, `not_modified` 304s served from the stored body, `errors` transport
+failures and `http_errors` responses with status 400 or above. `bytes` is the
+decoded body size. `core` is everything no plugin made.
+
+Three counters are requests that never reached the network: `memo_hits`
+were answered from the short response cache (a response still inside the
+`Cache-Control: max-age` its server gave it), and `cache_hits` were
+scoreboard fetches answered from a shared ESPN scoreboard cache entry
+(`espn_scoreboard_cache_key`). `legacy_cache_hits` counts reads served from a
+key that predates the shared one; it should fall to zero within a day of an
+upgrade. A plugin's `hosts` counts are requests plus merged requests,
+`memo_hits` and `cache_hits`: everything it asked for.
+`response_cache` is the size of the response cache now.
+
 ### Get/Set Plugin Limits
 
 **GET** `/api/v3/plugins/limits/<plugin_id>`
@@ -892,8 +1146,11 @@ copy, not the display service's in-memory state.
 
 **GET** `/api/v3/plugins/state`
 
-Get the state manager's record for every plugin, keyed by plugin id. Pass
-`?plugin_id=<id>` for one plugin (`data` is then that record).
+Every plugin that is installed or configured, keyed by plugin id: desired
+state from `config.json` and the plugins directory, observed state from the
+display's runtime snapshot. Built per request; there is no state file.
+Pass `?plugin_id=<id>` for one plugin (`data` is then that record; 404 if
+it is neither installed nor configured).
 
 **Response**:
 ```json
@@ -902,23 +1159,41 @@ Get the state manager's record for every plugin, keyed by plugin id. Pass
   "data": {
     "football-scoreboard": {
       "plugin_id": "football-scoreboard",
-      "status": "loaded",
+      "status": "enabled",
+      "installed": true,
+      "in_config": true,
       "enabled": true,
       "version": "1.2.3",
+      "loaded": true,
+      "state": "enabled",
+      "error_info": null,
+      "loaded_version": "1.2.3",
+      "loaded_at": 1790000000.0,
       "installed_at": "2025-01-15T10:30:00",
-      "last_updated": "2025-01-15T10:30:00",
-      "config_version": 1,
-      "metadata": {}
+      "last_updated": "2025-01-15T10:30:00"
     }
-  }
+  },
+  "runtime": {"status": "live", "published_at": 1790000030.0, "age_seconds": 12.4, "stale_after": 180.0, "heartbeat_age_seconds": 2.1}
 }
 ```
 
+`status` is `enabled` / `disabled` for an installed plugin, `unknown` for
+one that is configured but not installed, and `error` when the display
+reports its state as `error`. `installed_at` and `last_updated` are the
+newest successful install, and install or update, in the operation history
+(`null` when it has none). The runtime fields follow the same rule as
+[`/plugins/installed`](#get-installed-plugins): `null` unless
+`runtime.status` is `live`.
+
 ### Reconcile Plugin State
 
 **POST** `/api/v3/plugins/state/reconcile`
 
-Reconcile plugin state across config, disk and the state manager.
+Reconcile desired state (`config.json` plus the plugins on disk) with the
+display's runtime snapshot. Desired-state gaps are fixed (a plugin on disk
+with no config section is added disabled); observed-state gaps -- enabled
+but not loaded, loaded at an older version than is installed -- are
+reported with `fix_action: "no_action"`.
 
 **Request Body** (optional):
 ```json
@@ -1189,13 +1464,22 @@ searches.
         "version": "1.2.3",
         "branch": "main",
         "default_branch": "main",
-        "plugin_path": "plugins/football-scoreboard"
+        "plugin_path": "plugins/football-scoreboard",
+        "commit": "843588025a81197056f8d96779ccb2be19337ab8",
+        "ledmatrix_min_version": "3.7.0",
+        "aliases": [],
+        "incompatible_reason": null
       }
     ]
   }
 }
 ```
 
+`commit` (the monorepo commit that introduced `version`),
+`ledmatrix_min_version` and `aliases` come from the registry entry and are
+`null` / `[]` when an older registry lacks them. `incompatible_reason` is the
+message an install would be refused with on this core, or `null`.
+
 ### Get GitHub Status
 
 **GET** `/api/v3/plugins/store/github-status`
@@ -1336,20 +1620,59 @@ Get LEDMatrix repository version.
 
 **GET** `/api/v3/system/check-update`
 
-Whether `origin/main` has commits the checkout lacks. Cached briefly.
-Fields at the top level (no envelope):
+Whether newer code is available on this device's update channel. On
+`stable` that is a newer release tag than the checkout (`target_version`
+names it); on `beta`, and on `stable` while it waits on a branch for a
+release that contains the current commit, it is commits on `origin/main`
+the checkout lacks. A detached checkout newer than the newest release is
+never offered an update: Update Code leaves it where it is until a release
+includes it, and `channel_message` says so in the General tab's words.
+Cached briefly. Fields at the top level (no envelope):
 
 ```json
 {
   "update_available": true,
   "remote_sha": "abc123...",
-  "commits_behind": 3
+  "commits_behind": 3,
+  "target_version": "v3.8.0",
+  "channel": "stable",
+  "configured_channel": "stable",
+  "waiting": false,
+  "newest_release": "v3.8.0",
+  "current_release": null,
+  "channel_message": "Stable: release v3.8.0 is available."
 }
 ```
 
 When git cannot run the check, the response also carries
 `"check_failed": true` and an `error` explaining why.
 
+### Update Channel
+
+**GET** `/api/v3/system/update-channel`
+
+The update channel and what the next Update Code or weekly update would do
+(in `data`): `configured` (`"stable"`, `"beta"` or `null` for a config from
+before channels), `channel` (the one in effect), `waiting` (stable, but the
+device is newer than the newest release, so it follows `main` for now),
+`action` (`none`, `checkout_tag`, `pull` or `switch_to_beta`),
+`newest_release`, `current_release`, `branch` (`""` when on a release tag),
+`message`. Reads local refs; `?fetch=1` fetches from origin first.
+
+**POST** `/api/v3/system/update-channel`
+
+```json
+{
+  "channel": "beta"
+}
+```
+
+Saves `auto_update.channel`. The next update applies it; switching to
+`stable` never installs an older version than the one running, and the
+`message` says when the device keeps following `main` until a newer release.
+400 for anything but `stable` or `beta`. The General tab form also accepts
+`auto_update_channel` on `POST /api/v3/config/main`.
+
 ### Automatic Update Status
 
 **GET** `/api/v3/system/auto-update`
@@ -1375,7 +1698,9 @@ Hide the current automatic-update alert until a new one replaces it.
 
 Branch, dirty state, recent commits and remote for the Tools tab. Fields at
 the top level: `branch`, `dirty`, `status`, `recent_commits`, `remote_url`
-(credentials scrubbed), `upstream`, `can_pull`.
+(credentials scrubbed), `upstream`, `can_pull`, and for the update channel
+`detached`, `version` (`git describe`), `current_release` (the release tag
+HEAD is exactly on, else `null`) and `channel_message` (detached only).
 
 ### Git Branches
 
@@ -1388,7 +1713,10 @@ Fetches `origin` and lists branches to switch to: `current`, `upstream`,
 
 **POST** `/api/v3/system/action`
 
-Execute system-level actions. JSON or form data.
+Execute system-level actions. Send JSON (`Content-Type: application/json`).
+A form-encoded or `text/plain` body is accepted only with an `HX-Request`
+header (HTMX sends it; a cross-site HTML form cannot) and is otherwise
+refused with `415`.
 
 **Request Body**:
 ```json
@@ -1949,6 +2277,21 @@ Health of the web interface, display service, config file, plugin system and
 display snapshot. `data.status` is `healthy` or `degraded`, with
 `data.services` and `data.checks`.
 
+`data.checks.display_loop` is the display's render-loop heartbeat: `running`
+(with `heartbeat_age_seconds`), `stalled` (no heartbeat for 60s: the panel is
+frozen even if the service is active; the status turns `degraded`), or
+`not_reported` when the display writes none (not started yet, the dev server,
+Windows), which does not affect the status. Its `source` is `socket` when the
+age came from the display's state stream over the control socket (measured
+in memory by the display) and `heartbeat_file` when it came from
+`/run/ledmatrix/display-heartbeat.json`.
+
+Open even when the web login is on, for uptime monitors; a caller that is not
+logged in (and has no token) then gets only `{"status": "success", "data":
+{"status": "healthy" | "degraded"}}`. A stalled render loop still shows there
+as `degraded`; the `checks` detail is only for logged-in callers, tokens and
+requests from the Pi itself.
+
 ### Hardware Status
 
 **GET** `/api/v3/hardware/status`
@@ -2014,20 +2357,100 @@ enabled.
 
 Home Assistant MQTT bridge service state and settings: `data.service`,
 `data.config_exists`, `data.config_path`, `data.config` (password
-omitted), `data.password_set`, `data.env_override_prefix`.
+omitted), `data.password_set`, `data.api_token_set`, `data.env_override_prefix`.
 
 **PUT** `/api/v3/integrations/mqtt-bridge/config`
 
 Write `integrations/mqtt_bridge/bridge_config.json`. Only the keys you send
 change. The password is write-only: omit `mqtt_password` to keep it, send a
-value to replace it, or send `"clear_password": true`. A password with
+value to replace it, or send `"clear_password": true`. The web-login API token
+the bridge sends (`ledmatrix_api_token`, needed only when login is on and the
+bridge runs on another machine) is write-only the same way, cleared with
+`"clear_api_token": true`. A password with
 `mqtt_tls` off is refused unless `allow_insecure_mqtt` is true. Returns
-`data.password_set` and `data.restart_required` (the bridge must be
-restarted to pick up changes). See
+`data.password_set`, `data.api_token_set` and `data.restart_required` (the
+bridge must be restarted to pick up changes). See
 [integrations/mqtt_bridge/README.md](../integrations/mqtt_bridge/README.md).
 
 ---
 
+## Web login and API tokens
+
+The optional password and API tokens (`web_auth` in
+`config/config_secrets.json`, `web_interface/auth.py`). No route here returns
+the password hash, a token hash or the cookie key. A request authenticated by
+an API token gets `403` `TOKEN_NOT_ALLOWED` from every route in this section:
+tokens are for integrations, not for changing who can log in. Wrong current
+passwords (`403` `WRONG_PASSWORD`) count against the same per-address limit as
+the login page: 5 a minute, 30 an hour, then `429`.
+
+Lost password: run `sudo python3 scripts/reset_web_password.py` on the Pi.
+
+### Login status
+
+**GET** `/api/v3/auth/status`
+
+```json
+{
+  "status": "success",
+  "data": {
+    "enabled": true,
+    "signed_in": true,
+    "access": "session",
+    "min_password_length": 8,
+    "tokens": [
+      {"id": "3f9c1a2b4d5e6f70", "name": "Home Assistant", "prefix": "lmx_Ab3d",
+       "created_at": "2026-09-29T20:14:03+00:00"}
+    ]
+  }
+}
+```
+
+`access` is how this request got in: `open` (login off), `session`,
+`localhost`, `ap-setup` or `token`.
+
+### Set or change the password
+
+**POST** `/api/v3/auth/password`
+
+Body: `{"new_password": "...", "current_password": "..."}`.
+`current_password` is required once login is on. At least 8 characters, no
+leading or trailing space (`400` `WEAK_PASSWORD`). Setting the first password
+turns login on. Every existing login session ends; the caller's own browser
+is signed in again with the answer.
+
+### Turn login off
+
+**POST** `/api/v3/auth/disable`
+
+Body: `{"current_password": "..."}`. Removes the password; API tokens are
+kept (and are needed again if login is turned back on).
+
+### API tokens
+
+**GET** `/api/v3/auth/tokens` — `data.tokens`, as in the status answer.
+
+**POST** `/api/v3/auth/tokens` — body `{"name": "Home Assistant"}` (1-60
+characters). Answers `201` with `data.token`, the token itself (`lmx_` plus 43
+characters), and `data.record`. **The token is never shown again**; only its
+SHA-256 is stored. At most 50 tokens.
+
+**DELETE** `/api/v3/auth/tokens/<id>` — revoke; it stops working on the next
+request. `404` for an unknown id.
+
+Send a token as `Authorization: Bearer <token>`.
+
+### Login page
+
+`GET /login` shows the login form (and redirects home when login is off or
+this browser is already signed in); `POST /login` with a form field `password`
+(and optional `next`, a path on this server) signs in and redirects to `next`,
+or answers `401` with the form again. `POST /logout` ends the session. Both
+are outside `/api/v3` and go through the cross-site check like every other
+`POST`.
+
+---
+
 ## Plugin-specific endpoints
 
 A handful of endpoints belong to individual plugins. The music plugin's

docs/RUN_LOOP_REDESIGN.md

@@ -0,0 +1,346 @@
+# Restructuring `DisplayController.run()`
+
+`run()` in [`src/display_controller.py`](../src/display_controller.py) decides
+what the panel shows and runs it. This document is the plan for turning it
+from one long loop into three parts with clear jobs: an **Arbiter** that
+decides, a **ScreenRunner** that runs one screen, and **Sources** that each
+know about one kind of content. It covers the target design, the stages that
+get there, and how each stage is checked.
+
+The goal is to change how the control flow is organised, not to move code
+into more files. Each stage ships as its own PR, and none of them changes
+what the panel shows unless that PR says so and updates the golden traces
+on purpose.
+
+## Why
+
+- **The priority order is written in branch order, twice.** It is
+  Follower, on-demand, WiFi notice, live priority, Vegas, rotation. In
+  `run()` that order exists only as the order of `if` blocks. Vegas
+  repeats part of it in its interrupt callback (`_check_vegas_interrupt`).
+- **Preemption is found by re-checking.** A screen ends early when
+  something else changed `current_display_mode` or `is_display_active`
+  underneath it. `run()` notices with five separate
+  `current_display_mode != active_mode` checks: after an empty pass, in each
+  of the two frame loops, after the frame loops, and before rotating.
+- **Most recent fixes were ordering bugs** between these branches (#618,
+  #644, #649, #652): a lost mode switch, rotating past an on-demand request,
+  spinning when every mode is empty.
+- **It could not be tested** without threads, real sleeps and stopping the
+  loop by raising from a patched method.
+
+## What `run()` does today
+
+Each pass, in order:
+
+1. `loop_pass()` (watchdog). Apply a pending plugin enable/disable, then
+   any plugin reloads the control socket asked for
+   (`_apply_pending_plugin_reloads`; a pending reload ends the screen
+   before it, like a WiFi notice, through `_screen_preempted`). The static
+   screen's frame sleep and the dwell wait on the socket's queue instead of
+   sleeping (`_wait_frame_interval`, `_sleep_with_plugin_updates`); without
+   a socket, as in the golden traces, they are the plain sleeps.
+2. With no modes: dwell 1 s, next pass.
+3. Poll on-demand requests and expiry, release plugins loaded only for
+   on-demand, tick plugin updates, drop an expired WiFi notice, evaluate
+   the schedule (an on-demand session overrides scheduled-off), apply the
+   brightness target. Then gather the Arbiter's inputs
+   (`_arbiter_inputs`) and call `Arbiter.decide()`, which picks one of
+   steps 4-6 or returns `LEGACY` for steps 7-9 (stage 2).
+4. **Scheduled off:** blank, dwell up to 60 s. `_blank_while_scheduled_off`
+5. **Follower:** render one frame from the leader. `_run_follower_frame`
+6. **WiFi notice** (unless on-demand): draw it, dwell 0.5 s. `_show_wifi_notice`.
+   It is also polled mid-screen (`_wifi_notice_pending`): the frame loops,
+   the dwell sleep and an interrupted Vegas iteration end within about a
+   second when one arrives, and a screen cut short resumes after it.
+7. **Live priority** (unless on-demand, or Vegas keeps live content in the
+   ticker): switch to the next live mode, or resume the rotation. A game
+   that goes live during a screen is caught sooner, by
+   `_check_live_takeover` in the frame loops and the dwell sleep (at most
+   once a second, and not while a live mode is showing).
+8. **Vegas** (unless on-demand, or live content preempts it): run one
+   iteration of up to `max_cycle_duration`. A completed iteration ends the
+   pass, and so does one that yielded for a WiFi notice or the schedule.
+   Any other interrupted one falls through to step 9 in the same pass.
+9. **One screen:** pick the mode (`_resolve_active_mode`), the plugin
+   (`_plugin_for_mode`), draw the first frame through the executor
+   (`_dispatch_first_frame`). On no content, rotate at once
+   (`_note_empty_pass`, `_skip_failed_plugin_modes`). Otherwise work out the
+   bounds (`_track_dynamic_cycle`, `_resolve_durations`,
+   `_clamp_to_on_demand`) and the frame rate (`_needs_high_fps`), run the
+   125 Hz or 1 Hz frame loop, make up the minimum duration, then pick the
+   next mode (`_advance_after_screen`).
+
+The helpers named above were extracted in stage 1 without changing
+behaviour. Since stage 2 the choice between steps 4, 5, 6 and the rest is
+made by `Arbiter.decide()` in `src/display_arbiter.py`. The frame loops, the
+Vegas branch and every early exit are still inline in `run()`.
+
+## Target design
+
+```python
+def run(self):
+    while True:
+        inputs = self._drain_inputs()                 # requests, schedule, config, sync
+        plan = self.arbiter.decide(self.state, inputs, clock.now())
+        outcome = self.runner.run(plan)               # ExitReason + elapsed
+        self.state = self.state.after(plan, outcome)  # rotation, on-demand index, live resume
+```
+
+### Sources
+
+Each kind of content is a Source. A Source looks at the state and the
+inputs and either offers a screen or passes. The Arbiter asks them in this
+order:
+
+| Order | Source | Offers a screen when | Today |
+|---|---|---|---|
+| gate | ScheduledOff | the schedule is off and no on-demand session overrides it | step 4 |
+| 1 | Follower | a sync leader is driving this panel | step 5 |
+| 2 | OnDemand | a session is active (its mode list, index, expiry and pin) | `_resolve_active_mode` |
+| 3 | Wifi | a status message is pending and on-demand is not active | step 6 |
+| 4 | Live | a live-priority plugin has live content (round-robin across several) | step 7 |
+| 5 | Vegas | Vegas is enabled and nothing above wants the panel | step 8 |
+| 6 | Rotation | always: `available_modes[current_mode_index]` | step 9 |
+
+ScheduledOff is a gate in front of the Sources because that is how it works
+today: a scheduled-off panel stays blank even for a follower, and only an
+on-demand session overrides it.
+
+### Arbiter
+
+```python
+Arbiter.decide(state, inputs, now) -> ScreenPlan
+```
+
+`decide` is a pure function: it does no I/O, takes no locks and does not
+sleep. It can be tested with plain tables of (state, inputs, now) mapped to
+an expected plan. It returns a `ScreenPlan`:
+
+| Field | Meaning |
+|---|---|
+| `source` | which Source won |
+| `mode`, `plugin` | what to draw (None for a blank or follower plan) |
+| `min_duration`, `max_duration` | from `_resolve_durations` and `_clamp_to_on_demand` |
+| `dynamic` | run until the plugin's cycle completes, between min and max |
+| `frame_policy` | today `_needs_high_fps` (125 Hz or 1 Hz); see stage 5 |
+| `preemptible_by` | the Sources allowed to interrupt this plan mid-screen |
+
+### ScreenRunner
+
+```python
+ScreenRunner(clock: FrameClock).run(plan) -> Outcome(exit_reason, elapsed)
+```
+
+The ScreenRunner draws the first frame (`_dispatch_first_frame`), runs the
+frame loop that the plan's frame policy selects, services pending changes
+between frames, and returns one `ExitReason`:
+
+| ExitReason | Today's equivalent (golden-trace exit) |
+|---|---|
+| `DURATION` | target duration reached (`duration`) |
+| `CYCLE_COMPLETE` | dynamic plugin finished after its minimum (`cycle-complete`) |
+| `EMPTY` | first frame returned False (`empty`; `raised` when display() raised inside the executor) |
+| `ERROR` | the dispatch itself raised (`error`) |
+| `DISPLAY_FALSE` | a later frame returned False (`display-false`) |
+| `PREEMPTED` | another Source took the panel (`on-demand-*`, `schedule-off`, `vegas-interrupt`, ...) |
+
+`PREEMPTED` replaces the five `current_display_mode != active_mode` checks.
+The runner asks the Arbiter, at the throttled service points it already has,
+whether a Source in `plan.preemptible_by` now wants the panel.
+
+`FrameClock` provides `now()` and `sleep()`. In production it is
+`time.monotonic`/`time.sleep`. In the golden traces it is the fake clock
+that the harness patches in today.
+
+## Stages
+
+| Stage | Change | Behaviour change | Verified by |
+|---|---|---|---|
+| 1 | Golden traces; extract helpers from `run()` | none | traces generated on main pass unchanged; mutation check |
+| 2 | Arbiter with Follower and Wifi Sources | none | traces unchanged; Arbiter unit tables; ledpi smoke |
+| 3 | ScreenRunner, FrameClock, ExitReason, `PREEMPTED`; OnDemand, Live, Rotation Sources | none | traces unchanged; ledpi frame soak A/B |
+| 4 | Vegas as a Source driven by `run_frame()` | none intended | traces against the real coordinator; ledpi Vegas soak A/B |
+| 5 | Plugins declare `frame_policy` | DEBUG instead of INFO for the FPS line | traces; soak on a static-heavy rotation |
+
+### Stage 1 (#704)
+
+- `test/_run_loop_harness.py` builds a real `DisplayController` through
+  `__init__` on in-memory fakes (plugins, cache, config service, plugin
+  manager, sync manager, display manager). It swaps the module's `time` and
+  `datetime` for one fake clock and runs the real `run()` until a horizon.
+  The first frame of each screen still goes through the real
+  `PluginExecutor` and the per-plugin locks.
+- `test/test_run_loop_golden.py` has 15 scenarios, each compared with
+  `test/fixtures/run_loop_golden/<scenario>.json`:
+  - plain rotation (display_durations override, a high-FPS scroller, a
+    plugin whose `display()` takes no `display_mode`)
+  - empty modes and a mode with no plugin; an all-empty rotation (the 1 s
+    pause)
+  - plugin errors and the circuit breaker
+  - dynamic duration (cycle complete, plugin cap, global cap)
+  - live priority taking over and handing back; live round-robin
+  - on-demand start/stop/expiry; pinned on-demand; a session resumed after
+    a restart
+  - schedule off and dim, with an on-demand override during downtime
+  - WiFi notice; sync follower
+  - Vegas, with and without `live_in_ticker`
+- Each trace row is `[start, mode, duration, exit_reason, frames,
+  force_clear]`. The exit reason is the event that decided what came next.
+- All 16 tests run in under a second. The goldens were generated from
+  main's `run()` before any code moved.
+- Vegas uses `FakeVegas`, which implements only the contract the controller
+  depends on: `run_iteration()` returns True after its duration and False
+  when the interrupt or live check asks it to yield, checking at the real
+  coordinator's cadence. Running the real coordinator on the fake clock
+  belongs to stage 4.
+- Twelve helpers were extracted from `run()` (listed under "What `run()`
+  does today"). Breaking any one of them fails at least one golden trace.
+
+### Stage 2: Arbiter, starting with Follower and Wifi (done)
+
+1. Add `ScreenPlan` and an `Arbiter` with the ScheduledOff gate, Follower
+   and Wifi. Every other case returns a `LEGACY` plan, which means "carry on
+   with the existing code" (steps 7-9).
+2. `run()` calls `decide()` after the bookkeeping in step 3 and dispatches
+   on `plan.source`: blank, `_run_follower_frame()`, the WiFi notice, or the
+   existing path. Inputs that Sources read (follower active, the pending
+   WiFi message, schedule state) are collected first, so `decide()` stays
+   pure.
+3. Unit-test `decide()` with tables. The golden traces must not change.
+   The Wifi Source must keep the mid-screen preemption described in step 6
+   of "What `run()` does today".
+
+Follower and Wifi go first because each is one self-contained branch that
+ends the pass. They prove the plumbing without touching the frame loops.
+
+What shipped:
+
+- `src/display_arbiter.py` (on the mypy ratchet) holds `Source`
+  (`SCHEDULED_OFF`, `FOLLOWER`, `WIFI`, `LEGACY`), `ArbiterInputs`,
+  `ArbiterState`, `WifiNotice`, `ScreenPlan` and `Arbiter.decide`.
+  `ScreenPlan` has only the fields stage 2 uses: `source`, `max_duration`
+  (60 s for the blank, 0.5 s for the notice, the constants `run()` used to
+  hard-code) and `notice`. `mode`, `plugin`, the other durations,
+  `frame_policy` and `preemptible_by` arrive with the Sources that need them.
+- `ArbiterState` is empty: no stage-2 Source remembers anything between
+  passes. `now` is passed but not read, because the top-of-pass WiFi check
+  never compared the expiry and must not start (the table pins this).
+- `ArbiterInputs` holds `schedule_on`, `on_demand_active`,
+  `follower_active` and `wifi_notice`. `_arbiter_inputs` derives
+  `schedule_on` as `is_display_active and not on_demand_schedule_override`,
+  so the gate (blank when the schedule is off and no on-demand session
+  overrides it) blanks exactly when `is_display_active` is False, as before,
+  including #714's on-demand ending in off hours. It reads the WiFi notice
+  only when the notice could win, because `_check_wifi_status_message` has
+  side effects (its 1 Hz throttle, deleting an expired file) that those
+  passes never had.
+- The mid-screen rule is `wifi_notice_preempts(notice, on_demand, now)`,
+  which `_wifi_notice_pending` calls; it does compare the expiry.
+- `run()` still calls `_publish_current_mode_state_if_changed`,
+  `_apply_pending_vegas_init` and `process_deferred_updates` at the same
+  points relative to the branches, so the order of side effects in a pass
+  is unchanged.
+- `test/test_display_arbiter.py`: the 16-row table (every combination of
+  the four inputs, written out), the mid-screen table, purity checks (no
+  clock reads, nothing mutated, no I/O imports), and the controller's
+  snapshot through an on-demand session that overrides the schedule and
+  ends. A mutation run broke 23 pieces once each (the gate, the order, each
+  Source, the dwells, the expiry comparison, the snapshot's reads, each
+  dispatch in `run()`); every one failed a test.
+
+### Stage 3: ScreenRunner and `PREEMPTED`
+
+Move the two frame loops, the make-up dwell and the dynamic-duration exit
+into `ScreenRunner.run(plan)` with an injected `FrameClock`. Replace the
+five re-checks with `PREEMPTED`. Add the OnDemand, Live and Rotation Sources
+so `LEGACY` is left meaning only Vegas.
+
+Concretely, from where stage 2 left off:
+
+1. `ArbiterState` gains the rotation index, the on-demand mode list, index,
+   expiry and pin, and the live resume point (today `current_mode_index`,
+   `on_demand_*` and the live-priority stash). `ArbiterInputs` gains the
+   live modes (`_collect_live_modes`) and whether Vegas is enabled and keeps
+   live content in the ticker.
+2. OnDemand returns its current mode with `_clamp_to_on_demand`'s bound,
+   reading `now` for the expiry. Live returns the next live mode
+   (round-robin). Rotation returns `available_modes[current_mode_index]`.
+   `ScreenPlan` gains `mode`, `plugin`, `min_duration`, `max_duration`,
+   `dynamic`, `frame_policy` and `preemptible_by`.
+3. `ScreenRunner.run(plan)` returns an `ExitReason`; `state.after(plan,
+   outcome)` replaces `_advance_after_screen` and the live-resume
+   bookkeeping. Each mid-screen check asks `decide()` whether a Source in
+   `plan.preemptible_by` now wins, so `_screen_preempted`,
+   `_check_live_takeover` and `_wifi_notice_pending` become one call.
+4. The control socket (`_drain_control_commands`, `_wait_for_control`) and
+   state publishing stay where they are; the runner calls them at its
+   service points.
+
+This stage touches frame pacing (the 8 ms deadline sleep, the 1 ms yield),
+so it needs a frame soak on ledpi, A/B against main. Coordinate with
+whoever owns scroll performance (`docs/SCROLL_PERFORMANCE.md`).
+
+### Stage 4: Vegas as a Source
+
+The controller calls `coordinator.run_frame()` once per frame from the
+ScreenRunner instead of handing over to `run_iteration()` for up to
+`max_cycle_duration`. The interrupt callback and the second copy of the
+priority order go away, because preemption becomes `PREEMPTED`. The
+`vegas-plugin-tick` thread that is spawned every 4 s becomes the
+controller's normal update tick. Extend the harness to drive the real
+coordinator on the fake clock, which means patching its `time` and running
+its prefetch inline. Verify with a Vegas soak on ledpi, A/B.
+
+### Stage 5: `frame_policy`
+
+Plugins declare `frame_policy` (STATIC, PERIODIC(hz), ANIMATED(fps),
+SCROLL). `_needs_high_fps` becomes the mapping for legacy plugins
+(`needs_high_fps`, the `static-image` special case, `enable_scrolling`),
+and its per-screen INFO line drops to DEBUG. It is already read twice per
+screen: once quietly before the first frame, so `_dispatch_first_frame` can
+end the previous scroll for a screen that runs the 1 Hz loop
+(`_start_screen_handover`), and once after it to pick the loop. A declared
+policy answers both.
+
+## How each stage is verified
+
+- **Golden traces.** Run `python -m pytest test/test_run_loop_golden.py`;
+  it takes about a second. A refactoring stage must leave every trace
+  unchanged. A deliberate behaviour change regenerates them with
+  `LEDMATRIX_REGEN_GOLDEN=1` in its own commit, and the commit message
+  explains each changed row. A new scenario's golden is generated against
+  main's `run()` first, then checked against the branch.
+- **Mutation check.** Break each moved or new piece once, for example take
+  `max` of the caps instead of `min`, or skip the live hold. At least one
+  trace must fail each time. Stage 1 did this for all twelve helpers.
+- **Full suite.** Diff the FAILED/ERROR ids against a baseline run of main
+  in a separate worktree. The Windows host has a stable set of
+  pre-existing failures, so never compare against zero.
+- **ledpi soak** (stages 2-5). With the service running the branch:
+  `python3 scripts/frame_soak.py --preview` for 10 minutes on a scrolling
+  rotation, and on Vegas for stages 3-4. Alternate which build goes first.
+  Compare late-frame rate and freezes with main. Also check by hand that
+  on-demand start, stop and expiry, a live game taking over and handing
+  back, and the schedule turning the panel off and on all behave as before.
+
+## Behaviour the traces pin down that may be wrong
+
+Stage 1 recorded six behaviours as they were, each to be fixed in its own
+PR that updates the affected trace and explains why. All six are fixed:
+
+- A WiFi notice was only checked between screens, and Vegas yielded to one
+  and then showed a rotation screen instead. Notices now preempt within
+  about a second, and Vegas yields straight to them (#712; `wifi_notice`,
+  `vegas`).
+- A live game only took over between screens, and Vegas yielded to one and
+  then showed a rotation screen first. Games now take over within about a
+  second, and Vegas yields straight to them (#713; `live_priority`,
+  `vegas`).
+- An on-demand session that ended during scheduled-off kept the panel on
+  until the next minute, and a schedule window's end minute counted as on
+  only sometimes. Windows are now half-open `[start, end)`, and the panel
+  blanks as soon as on-demand ends in off hours (#714; `schedule`).
+
+A new one found later goes the same way: record it here with the trace that
+shows it, then fix it in its own PR, not inside a restructure stage.

docs/SCROLL_PERFORMANCE.md

@@ -73,6 +73,10 @@ Sample ladder for a 100 Hz panel:
  100.0 px/s  (1px every 1 refresh  = 100.0 fps, smooth)
 ```
 
+The Vegas **Scroll Speed** slider in the web UI shows the same thing live: a
+line under it says what your speed will run as on this panel, and links to the
+nearest smooth speeds.
+
 ### How a slow speed stays crisp
 
 `SwapOnVSync(canvas, framerate_fraction)` holds each frame for N panel
@@ -242,8 +246,16 @@ mean exactly 10 ms, so a ticker stalling on half its frames still averages to a
 healthy 100 fps. The stats line reports the tail for that reason — read the
 percentiles, not the fps.
 
-Every scroller emits one line every 5 seconds covering *every* frame in that
-window, tagged with the plugin it came from:
+Every scroller summarises each 5-second window, covering *every* frame in it,
+in one line tagged with the plugin it came from. At the default log level the
+line reaches the journal only when it is worth reading: a **degraded** window
+(frame rate below 90% of the rate the window was locked to, i.e. 1 / its own
+median -- the same 0.9 Vegas's `Vegas FPS` line uses -- or more than 1% of its
+frames stalled), the first window after one (the recovery), and otherwise once
+every 5 minutes per scroller as a heartbeat, so silence means stopped rather
+than fine. Every window is logged at DEBUG: to see them all, run the display
+with `-d` or `LEDMATRIX_DEBUG=true` (see
+[CONFIG_DEBUGGING.md](CONFIG_DEBUGGING.md#enable-debug-logging)).
 
 ```bash
 journalctl -u ledmatrix --since "-10min" --no-pager | grep "Scroll frame stats"
@@ -282,6 +294,10 @@ journalctl -u ledmatrix --since "-3h" --no-pager | grep "Scroll frame stats" \
   | sort -k7 -rn
 ```
 
+At the default log level that ranks the windows the journal kept -- the
+degraded ones, recoveries and heartbeats -- so it over-weights bad windows;
+rank a debug run for an unbiased average, or soak the rig (below).
+
 The `$2 < 1000` guard drops windows whose median is a whole second or more.
 Those are not frames. Until the idle-gap fix in `log_frame_rate()`, the first
 frame of every scroll was timed against the end of the *previous* scroll, so
@@ -331,17 +347,24 @@ python3 scripts/frame_soak.py --json a.json   # keep the report to compare later
 It runs as any user next to the display service and stops nothing. It needs
 something to *scroll* during the run: a live game holding a static scoreboard
 on screen gives no verdict. `--preview` keeps the web preview's viewer marker
-fresh, which puts the preview's PNG encoding at full rate -- run it as the web
-service's user.
+fresh, which puts the preview's PNG encoding at the viewer rate, as an open
+preview does -- run it as the web service's user. That rate is at most one
+frame a second. Through 3.8.0 it was up to five, so a `--preview` soak taken
+before that change is not comparable with one taken after it (the hdpi
+results below are from before it): take both sides of an A/B pair on
+the same side of it.
 
 | line | what it tells you |
 |---|---|
 | **Late frames** | Frames presented one or more refreshes after they were due: the panel showed the previous frame again, a visible hitch. **The pass/fail number**, 0.1% by default (`--max-late-pct`). Only intervals between two scrolling frames count, and a frame held for `frame_hold` refreshes is due `frame_hold` refreshes after the last. |
-| **Freezes** | Gaps of 250 ms or more inside a scroll: recomposes, plugin handovers, blocking calls on the render thread. Reported but not failed on, because some are handovers between plugins rather than faults. A gap still counts when the display's scroll state went missing for one frame across it, as long as scrolling resumes within 1 s: both of that frame's intervals count. Two static frames in a row end the scroll. (The state expires after 2 s without scroll activity, and plugins can clear it from their own `display()`.) The late and early rates are over frames judged against a known refresh period, which the recorder adopts once two windows in a row agree on it. |
+| **Freezes** | Gaps of 250 ms or more inside a scroll: recomposes, plugin handovers the display controller does not tag (see *Handover gaps*), blocking calls on the render thread. Reported but not failed on, because some are handovers between plugins rather than faults. A gap still counts when the display's scroll state went missing for one frame across it, as long as scrolling resumes within 1 s: both of that frame's intervals count. Two static frames in a row end the scroll. (The state expires after 2 s without scroll activity, and plugins can clear it from their own `display()`.) The late and early rates are over frames judged against a known refresh period, which the recorder adopts once two windows in a row agree on it. Handovers to a static screen no longer show up here: the display controller ends the scroll state after a static screen's first frame, where it used to linger for 2 s and turn the 1 Hz loop's second frame into a ~1 s "freeze" (17 of 31 `Render stall over` lines on ledpi, 2026-09-15 to 10-01). **Freeze counts from before and after that change are not comparable.** |
+| **Handover gaps** | Gaps of 250 ms or more from a scroll's last frame to the next screen's first: the next plugin drawing, not a scroll stalling. The display controller tags that first frame `handover`, and these gaps are counted here instead of under Freezes (`handover_freezes` in the stats; the `handover` row under *after work* counts the same ones in its freezes column). Every turn's first frame is tagged, also when the rotation comes back to the same mode (a one-mode rotation, a pinned on-demand mode, live priority holding a screen), so a scroller rebuilding its content at the start of a turn is counted here; measure work on that rebuild with this line, not Freezes. Missing from stats written by an older service, whose freezes include them. |
 | **blit** | Copying the frame into the matrix canvas (`SetImage`). It grows with width × height × `pwm_bits`: ~5.5 ms at 512×64 with 8 bits on a Pi 4. It is the biggest fixed cost, and it sets the refresh rates a rig can hold one pixel per refresh at. |
 | **wait** | Time blocked in `SwapOnVSync`, i.e. the slack left in each refresh. A p50 near zero means the rig has no headroom and anything extra lands a frame late. |
 | **work** | Everything else between two frames: drawing, scrolling, and waiting for the GIL. A wide gap between its p50 and p99 is another thread getting in the way. |
+| **Garbage collection** | Python's cyclic collector stops every thread while it runs. Collections per generation in the run and the time they took, how many took 20 ms or more, and the longest since the service started. A long one tags the next frame `gc` (see *after work*), and a `Render stall` dump says when one ran inside the stall. Diagnostic only: nothing tunes the collector. Missing from stats written by an older service. |
 | **Binding** | `STOCK` means the rgbmatrix binding holds the GIL through the vsync wait, which starves every other thread. See *Rebuilding the binding*. |
+| **after work** | Frames presented straight after tagged render-thread work, with their own late rate: `extend` and `compose` (Vegas building its strip), `patch` (live elements, once they land), `handover` (a new screen's first frame), `gc` (a garbage collection of 20 ms or more ran since the frame before). A kind whose late rate sits well above the overall one is the work making frames late. Shown only when something tagged its work. |
 
 The refresh rate is estimated from the frames themselves (swaps that block on
 vsync can only land on refresh boundaries). Cross-check it with
@@ -355,10 +378,13 @@ A/B two of them. A live-API workload drifts over time.
 The soak says how often; the service's log says why. A scroll that presents no
 frame for 250 ms logs `Render stall:` with the stack of the render thread and
 the top of every other thread's, and whether the whole interpreter was blocked
-(C code holding the GIL) rather than one thread. To see what is behind the
-shorter hitches, run the service with `LEDMATRIX_STALL_WATCHDOG_MS=30`, which
-dumps at three refreshes late instead: its extra polling costs a little GIL
-time of its own, so do that on a diagnostic run, not a soak you are grading.
+(C code holding the GIL) rather than one thread. A stall while the next
+screen's first `display()` is still drawing says `in a handover gap` instead of
+`mid-scroll`; that call runs on a thread named `display-<plugin id>`. To see
+what is behind the shorter hitches, run the service with
+`LEDMATRIX_STALL_WATCHDOG_MS=30`, which dumps at three refreshes late instead:
+its extra polling costs a little GIL time of its own, so do that on a
+diagnostic run, not a soak you are grading.
 `LEDMATRIX_STALL_WATCHDOG=0` turns it off.
 
 ### Results: hdpi, 2026-09-24
@@ -406,6 +432,10 @@ sudo python3 scripts/render_bench.py --speed 50      # a held (frame_hold 2) spe
 sudo python3 scripts/render_bench.py --busy 2        # with threads imitating plugin updates
 sudo python3 scripts/render_bench.py --json /tmp/pi4-512x64.json
 
+# render-thread strip work, each tagged so the report gives it a late rate:
+sudo python3 scripts/render_bench.py --patch-bytes 101376 --patch-every 25  # a live map patch
+sudo python3 scripts/render_bench.py --strip-screens 30 --extend-every-screens 6  # Vegas extensions
+
 sudo systemctl start ledmatrix
 ```
 
@@ -468,6 +498,8 @@ refreshes" comes from.
 | `duplicate` | frames that advanced no pixels. A crisp fixed-step scroll should show none; any at all means the loop is presenting faster than the strip is moving. |
 | `blank` | frames with no visible slice to draw: the helper had no content. Should be zero. |
 | `restarts` | how many times the strip was scrolled through end to end. Informational: the bench restarts the strip where a plugin would hand over to the next one. |
+| `patches` | `--patch-bytes N --patch-every K`: N bytes of columns written into the strip in place every K frames, on screen or (`--patch-where ahead`) just past it -- what a live element update costs the render thread. Their frames are the `patch` row under *after work*. |
+| `extensions` | `--extend-every-screens N`: a block appended and the scrolled-past columns trimmed every N screens, as continuous Vegas does. The cost is a copy of the whole strip, so size it like Vegas's with `--strip-screens` (8,000-20,000px). Their frames are the `extend` row. |
 
 `--json` writes the full report plus the panel geometry, the solved speed and
 these counters, so two rigs (or one rig before and after a change) can be
@@ -510,19 +542,43 @@ On the 2×128×64 chain above, which refreshes at about 130 Hz flat out
 
 ### What the display does about it
 
-At one pixel per refresh, the fastest crisp speed, the step is exactly one
-refresh's worth of motion, so it can be cancelled: show one half of the panel
+The step is the motion of one refresh, so it can be cancelled: show one half of the panel
 a refresh behind the other -- the half whose row at the seam lights at the
 start of each refresh. The two rows either side of the seam then show the same
 moment again. What is left is a
 lean of one pixel per half from top to bottom, continuous across the panel,
 which reads as nothing where the step read as a tear. `DisplayManager` does
-this while something scrolls at one frame per refresh
+this while something scrolls
 (`display.scan_order_compensation`, `"auto"` by default, `"off"` to disable;
 the geometry is in `src/scan_order.py`). The lagging rows come from the
 previous frame the display presented, so it works for Vegas and every plugin
 ticker without knowing how they scroll.
 
+A frame held for several refreshes (any crisp speed below the panel's full
+refresh rate, e.g. 60 px/s at 120 Hz) is presented as two swaps instead of one:
+the lagging half shows the previous frame for the first refresh and the new one
+for the rest, so it steps one refresh after the rest rather than one frame.
+That costs a second blit inside the refresh after the first swap, so it is
+skipped when a blit takes more than half a refresh.
+
+A plugin screen that runs the 1 Hz loop after a scroll is not composed: the
+display controller calls `DisplayManager.end_scroll_for_static_screen()` before
+its first `display()`, so the frames that call presents go out as drawn, in one
+swap each, instead of with the lagging half taken from the scroller's last
+frame.
+
+The controller's own screens -- the blank shown when the schedule turns the
+panel off, and the WiFi status message -- end the scroll state before they are
+drawn, so they go out as drawn and are timed as static frames, not as freezes
+of the old scroll. A scroller that resumes after a WiFi notice sets the state
+again on its next frame.
+
+One screen that follows a scroll is still composed while the scroll state lasts
+(it expires 2 s after the scroller's last frame): a screen that runs the
+high-FPS loop without scrolling (an older `static-image`, which is forced into
+it). Its first frame takes its lagging half from the scroller's last frame, for
+one refresh after a held scroll and otherwise until its next frame.
+
 Checked on hdpi (4×128×64 on one chain, rotated 180, 2026-09-24) before it was
 written: `scan_mode: 1` (interlaced) made the step vanish but turned moving
 edges grainy, and halving the speed halved it, so it is the scan and not a torn
@@ -530,9 +586,6 @@ frame. With the compensation the step is gone at 90 px/s.
 
 It is left off where the row order is unknown or the maths does not hold:
 
-- **Slower speeds**, where each frame is held for two or more refreshes. The
-  offset there is half a pixel or less, and cancelling it would need a lag of
-  a fraction of a frame.
 - **Other layouts:** pixel mappers other than a 0 or 180 degree rotation
   (U-mapper, 90/270), non-zero `multiplexing`, interlaced `scan_mode`, and a
   canvas remapped to another height (double-sided mode).

docs/SPORTS_UNIFICATION.md

@@ -35,10 +35,11 @@ defaults, or as capabilities they opt into.
 
 ### Reusability — write once, nine plugins benefit
 
-Only code that is **identical in intent across all nine** moves into the base
-class. That set is small and knowable — it is exactly the methods present in every
-copy today (phase B1 below). Everything else stays where it is until it earns
-promotion.
+Only code that is **identical across every plugin that carries it** moves into
+core. Stages 0–3 moved the copies that already were; what is left has drifted,
+and earns promotion by being reconciled first — made identical in all nine
+plugins, one method family per release, with every visible difference decided
+rather than averaged away. See [Roadmap](#roadmap).
 
 ### Modularity — a change to one feature cannot reach a plugin that doesn't use it
 
@@ -83,6 +84,13 @@ more. Shared sports code lives in `src/common`:
 | `espn_dates.py` | 3.5.0 | ESPN date-range and `limit` workarounds |
 | `favorite_team_check.py` | 3.6.0 | `FavoriteTeamCheck` — logs why a favourite team code shows nothing |
 | `sports_timezone.py` | 3.6.0 | Which timezone start times are drawn in (`resolve_timezone_name`) |
+| `sports_celebration.py` | 3.7.0 | `SportsCelebrationMixin` — draws the score/win takeover; colour helpers |
+| `sports_fetch.py` | 3.7.0 | `SportsFetchMixin` — season fetch, live lookback and live-odds decisions |
+| `sports_card_wrappers.py` | 3.7.0 | `SportsCardWrappersMixin` — the game renderer's `sports_card` delegations |
+| `sports_plugin_host.py` | next release | `SportsPluginHostMixin` — the plugin class's (`manager.py`) identical helpers: Vegas weight, off-thread switch refresh |
+| `sports_live_scroll.py` | next release | `SportsLiveScrollMixin` — rebuild a live scroll strip mid-cycle, keeping the marquee's place |
+| `sports_display_rules.py` | next release | `SportsCardOptionsMixin`, `SportsGameRulesMixin` — scorebug date options, the no-favourites filter, non-favourite live dwell |
+| `sports_font_path.py` | next release | `resolve_font_path` — what the plugins' `_resolve_font_path` copies return |
 
 Each is described in [src/common/README.md](../src/common/README.md).
 
@@ -94,9 +102,10 @@ modules taken from the plugin copies, each a **new module** rather than growth
 on an existing one: a plugin that deletes a method copy and relies on an older
 module having gained it fails at runtime with an `AttributeError`, while a
 missing module fails at load, where the version checks can see it.
-`sports_helpers.py` is the newest (it holds `_favorite_key`, the override point
-listed below, for later phases); its parity test compares every body against
-the plugin copies when `LEDMATRIX_PLUGINS` points at a checkout, and
+`sports_helpers.py` holds `_favorite_key`, the override point listed below.
+Each promoted module has a parity test that compares its bodies against the
+plugin copies when `LEDMATRIX_PLUGINS` points at a checkout
+(`test_sports_helpers.py`, `test_sports_stage3_parity.py`), and
 `test/test_common_is_hardware_free.py` keeps `src/common` free of
 `rgbmatrix`, `src.display_manager` and `src.plugin_system`. How a plugin adopts a
 module and drops its copy is documented in the plugins repo's
@@ -168,6 +177,15 @@ Mix it in **before** the mode class — `class SoccerLive(CelebrationMixin,
 SportsLive)` — so the celebration `display()` runs first and falls through to
 the scorebug via `super()`.
 
+What shipped is narrower. `src/common/sports_celebration.py`
+(`SportsCelebrationMixin`) holds only the drawing, which is identical in the
+five scoreboards that celebrate (afl, football, hockey, nrl, soccer — hockey
+grew celebrations after this was written). Arming a celebration stays in each
+plugin: the trigger bodies differ (nrl matches favourites by team id, football
+folds a touchdown's extra point into one celebration and picks scenery by
+points), and so does `display()`. The seams above were not needed to move the
+drawing, so none was added.
+
 **Rotation strategies.** The three "dialects" turned out to be one algorithm
 (Smooth Weighted Round-Robin) in two shapes: an incremental picker holding state
 across calls (afl/nrl/soccer) and a precomputed per-cycle list
@@ -223,12 +241,284 @@ legacy compatibility rather than the mechanism.
 > (`display_manager.refresh_hz`), and speed comes from
 > `scroll_settings.scroll_speed` alone. See `docs/SCROLL_PERFORMANCE.md`.
 
-## Phases
+## Roadmap
 
-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.
+### Done: stages 0–3
+
+The second project, after the B phases below: move what the nine `sports.py`
+copies (and their support files) carried byte-identically into `src/common`,
+one new module per stage, and delete the copies once the plugins floor on the
+release that ships it.
+
+| Stage | Core | Plugins (ledmatrix-plugins) | What moved |
+|---|---|---|---|
+| 0 | none needed; found #662 (odds `no_odds` marker) and #663 (a reloaded plugin's dir goes first on `sys.path`) | #562 | Deleted the bundled copies nothing could reach (`base_odds_manager`, `logo_downloader`, three unused data sources, ~4.2k lines); three UFC fixes |
+| 1 | 3.5.0: `sports_helpers` (#583), `espn_dates`, `json_body` | #563 (1a, the eight team scoreboards), #564 (1b, ufc); floor 3.5.0 | The identical helpers and ESPN date-range handling; ufc also adopted the `sports_shared` mixins |
+| 2 | 3.6.0: `favorite_team_check`, `sports_timezone`; fixes in 3.6.1 (#667) and 3.6.2 (#670) | #565 (guarded adoption), #567 (f1), #570 (sunset, floor 3.6.1), #571 (soccer, 3.6.2) | The favourite-team check (seven copies) and the timezone resolver (ten); each plugin keeps a thin timezone binding |
+| 3 | 3.7.0 (#672): `sports_celebration`, `sports_fetch`, `sports_card_wrappers` | #572 (goldens first), #574 (floor 3.7.0, copies deleted) | Celebration drawing (five plugins), four fetch methods (nine), seventeen card delegations (eight renderers) |
+
+Stage 3 was re-checked independently when this roadmap was written: #574's
+parent and #574 itself, rendered through the core harness against core 3.7.0,
+gave pixel-identical output for all 399 frames (192 harness screens across the
+nine plugins at the eight default sizes, 72 scroll/Vegas cards, 135
+celebration frames), with a parent-vs-parent rerun as the determinism control.
+
+### Stage 4: the identical sweep (core done; adoption waits for a release)
+
+Re-measured on ledmatrix-plugins `56c4f15` (2026-09-30) the report still
+lists 58 families identical in every copy. Stage 4 moves the ones that are
+identical across the nine, or across eight with the ninth lacking the
+method, into four new modules: `sports_plugin_host` (ten `manager.py`
+helpers, all nine), `sports_live_scroll` (eight `manager.py` methods, every
+plugin with a live strip, so not ufc), `sports_display_rules` (four
+`sports.py` methods, in two mixins because their carriers differ) and
+`sports_font_path`. The parity test (`test/test_sports_stage4_parity.py`)
+compares each with every plugin copy using this report's own normalisation,
+plus decorators and constant values, which the normalisation drops.
+
+`_resolve_font_path` was meant to be replaced by
+`font_layout.resolve_asset_path`, but that never looks in the cwd, and the
+plugins' copy does first, so the swap would change which font a process
+started from another checkout loads. `resolve_font_path` is the copy's
+behaviour on a core that ships it, checked path for path against all 17
+copies (`test/test_sports_font_path.py`).
+
+Left in the plugins, though identical:
+
+- `_get_timezone`, `_extract_game_details`, `_fetch_data` (nine): a
+  per-plugin import and the abstract contract, as in stage 3.
+- `_schema_font_size`, `_resolve_font_size` (eight renderers): they read the
+  plugin's own `_SCHEMA_PATH`, as in stage 3.
+- The 29 families carried by seven plugins or fewer: the afl/nrl/soccer
+  lineage's own helpers (`_swrr_advance`, `_refresh_switch_mode_managers`,
+  `_initialize_logo_dir`, ...), the multi-league helpers
+  (`_resolve_managers_for_mode`, `_extract_mode_type`, ...), and eleven
+  two-plugin helpers. Each is one lineage's code; most go when
+  family 13 or 14 reconciles the code around them. `_odds_color` (seven
+  renderers) is already core's, in `SportsHelpersMixin`; a renderer that
+  wants it can inherit that.
+
+### Why the method changes
+
+Byte-identical promotion has nearly run dry. Measured on ledmatrix-plugins
+`4327c2e` (2026-09-29, after stage 3) with `scripts/sports_drift_report.py`:
+
+| File | Method families | In all nine | Method lines | Identical copies beyond the first | Drifted families |
+|---|---:|---:|---:|---:|---:|
+| `sports.py` | 94 | 30 | 30,976 | 1,479 lines | 19 |
+| `manager.py` | 114 | 36 | 27,137 | 3,198 lines | 38 |
+| `game_renderer.py` (8 plugins) | 89 | — | 6,830 | 546 lines | 11 |
+
+"Drifted" means in at least seven plugins with at least three different
+bodies. Everything still identical adds up to about 5,200 duplicated lines;
+the rest of the ~65,000 method lines is drifted, one outlier away from
+identical, or unique to one plugin. Drifted code cannot move unchanged, so
+consolidation stalls unless the copies are made identical first.
+`manager.py`, the largest copy of all and the layer the display controller and
+Vegas talk to, was in no plan before this one.
+
+### The method: reconcile, then promote
+
+**Owner decision (2026-09-29):** each release, pick one drifted method family,
+make all nine copies identical, then promote it to core. A *family* here is a
+set of methods that share state and ship together (the rankings methods, the
+game-over check); the report measures each method in it. The procedure:
+
+1. **Measure.** `python scripts/sports_drift_report.py --family sports.py::<name> --diff`
+   lists which plugins share each body and diffs every variant against the
+   most common one. Put the grouping in the PR.
+2. **Classify every difference**, and say which class in the PR:
+   - *A fix one copy has and the others lack* (a lock, a guard, a correct
+     season year). Port it. It is a behaviour change, so it gets a CHANGELOG
+     line in each plugin.
+   - *A per-sport fact* (hockey ends in period 3; a soccer clock counts up).
+     Make it a declared class constant or override point with a default, as
+     `FINAL_PERIOD`, `CLOCK_COUNTS_DOWN`, `COALESCE_SCORING_SEQUENCE` and
+     `_favorite_key` are, and add it to the tables above. Never a sport-name
+     branch: core must not learn sport names.
+   - *A product difference*: anything a user can see (which games show, a
+     colour, a date, a badge, how long a screen stays). The owner picks the
+     behaviour before the code changes; the decision goes in the PR and in a
+     test that pins it (as `test/test_sports_twins.py` pins the twins).
+   - *Noise*: comments, log wording, dead branches. Pick one.
+3. **Pin the output first.** Before touching the family, its output must be
+   covered: the harness goldens (`test/golden`), the scroll cards
+   (`golden-cards`) and celebrations (`golden-celebration`) for drawing
+   families; for logic families, a table-driven test over the nine plugins'
+   fixture games. Missing coverage lands in its own PR first, as #572 did for
+   stage 3.
+4. **Reconcile in the plugins** (a monorepo PR). The report must show one
+   variant per class for the family. Render every touched plugin before and
+   after through the harness and diff pixels, not hashes. Every differing
+   frame must match a recorded product decision; any other difference is a
+   bug. Bump each plugin's `version`, add a `versions[]` entry and a CHANGELOG
+   entry, and run `update_registry.py`.
+5. **Promote in core**: a new `src/common` module per family (a new module, not
+   growth on an old one, for the reason under Converging on `src/common`), a
+   parity test against the plugin copies, and a CHANGELOG module entry naming
+   the release that ships it.
+6. **Adopt** once that release is out: each plugin floors on it, inherits the
+   mixin, deletes its copy, gains a sunset guard (like the monorepo's
+   `scripts/test_stage3_mixin_copies.py`), and is pixel-diffed again; the
+   expected difference is zero.
+7. **Re-measure** and update the numbers here.
+
+A family is only reconciled when *all nine* agree. Leaving one plugin behind
+recreates the drift the report exists to measure.
+
+Soaks: pixel diffs prove the drawing, not the timing. A family that changes
+when data arrives or which games are live (5, 7, 9, 13 and 14 below) needs a
+live-game soak on a rig, and out-of-season sports wait for their season.
+Before a soak, check the rig's `*_display_mode`: a board in `switch` mode tells
+you nothing about the scroll path.
+
+### Order
+
+One family per release, in this order. Variant counts are from the report
+above (per method: distinct bodies across the plugins that carry it, counted
+per class role). Stage 4 needs no reconciliation and can ride along with any
+release.
+
+| # | Family | Methods (variants) | Why here |
+|---|---|---|---|
+| 4 | Identical sweep | `manager.py`: `_dispatch_switch_refresh`, `_favorite_team_is_live`, `get_vegas_priority_weight`, `_game_involves`, `_favorite_scan_targets`, `_favorite_scan_games`, `_get_total_games_for_manager` (all nine, 1); the live-scroll helpers `_preserving_scroll_position`, `_refresh_live_scroll_managers`, `_live_scroll_managers`, `_note_live_scroll_built`, `_live_scroll_needs_rebuild`, `_live_scroll_fields` (eight, 1). `sports.py`: `_card_option`, `_filtered_or_all`, `_effective_live_duration`, `_recent_date_text` (eight, 1). 58 identical families in all | Nothing to decide; brings `manager.py` into core as a `SportsPluginHostMixin`. `_resolve_font_path` (identical in nine `sports.py` and eight renderers) becomes `sports_font_path.resolve_font_path`, not `font_layout.resolve_asset_path`, which skips the cwd. Core side done; see [Stage 4](#stage-4-the-identical-sweep-core-done-adoption-waits-for-a-release) |
+| 5 | Game-over check | `SportsLive._is_game_really_over` (5) | Pure logic, no pixels; its seams (`FINAL_PERIOD`, `CLOCK_COUNTS_DOWN`) were designed in B1. The pilot for the procedure |
+| 6 | Favourite matching | `_is_favorite_game` (7 across three classes), `_select_games_for_display` (2: nrl), `_select_recent_games_for_display` (3) | Everything that asks "is this a favourite" goes through the 3.5.0 `_favorite_key` seam |
+| 7 | Other-games rotation | `_by_importance`, `_other_games_window`, `_advance_other_games_if_due` (2 each: football), `_rotate_other_games_on_display` (2: ufc) | One outlier each; football carries two fixes the other eight lack |
+| 8 | Rankings | `_fetch_team_rankings` (3), `_choose_poll` (3), `_load_division_team_ids`, `_passes_other_filters`, `_best_rank`, `_is_ranked_game` (2 each: football) | Needs 7; the rank badge and the "ranked only" filter read it |
+| 9 | Live fetch and odds | `_fetch_todays_games` (5), `_fetch_odds` (3), `_attach_odds_to_rotated_games` (3) | The prerequisite for one shared ESPN poller across plugins |
+| 10 | View model | `_extract_game_details_common` (9 of 9) | Every renderer reads it; its keys are additive-only, so reconcile to the superset and leave sport extras in `_extract_game_details` |
+| 11 | Switch scorebug | `_load_fonts` (4), `_load_custom_font_from_element_config` (6), `_get_layout_offset` (5), `_fit_score_font` (2: football), `_load_and_resize_logo` (9), `_draw_dynamic_odds` (9), then `_draw_scorebug_layout` (20: Upcoming 9, Recent 8, Live 2, ufc's Core 1) | Needs 10 and the twin decisions below. Several releases: fonts and offsets, logos, odds, then one mode's layout per release |
+| 12 | Scroll/Vegas card | `game_renderer.py`: `render_game_card` (6), `_load_and_resize_logo` (8), `_load_custom_font`, `preload_logos`, `__init__` (7 each), `_draw_records_or_rankings` (6), `_load_fonts`, `_draw_dynamic_odds`, `_draw_live_game_status`, `_draw_recent_game_status`, `_get_team_display_text` (5 each), `_draw_text_with_outline` (2: football) | Same decisions as 11; sequence after the scroll-performance work on pre-rendered strips lands |
+| 13 | Mode lifecycle | `sports.py`: `update` (23), `__init__` (16), `display` (13), `_advance_live_game_if_due` (6) | Where per-sport behaviour lives; last in `sports.py`. Each difference becomes a seam or a strategy chosen by name (live rotation already has three) |
+| 14 | `manager.py` host | Nine different bodies in nine plugins: `__init__`, `display`, `update`, `has_live_content`, `get_live_modes`, `get_vegas_content`, `on_config_change`, `_initialize_managers`, `_get_available_modes`, `_get_current_manager`, `_adapt_config_for_manager`. Dynamic duration: `_evaluate_dynamic_cycle_completion` (9), `_record_dynamic_progress` (8), `get_cycle_duration` (8), `get_dynamic_duration_cap` (6), `supports_dynamic_duration`, `is_cycle_complete` (5 each), `reset_cycle_state` (4). Scroll: `_display_scroll_mode` (8), `_ensure_scroll_content_for_vegas` (8), `_collect_games_for_scroll` (7), `_should_use_scroll_mode`, `_has_any_scroll_mode` (6 each) | See below |
+
+**`manager.py`.** Reconciling it body by body would take a release per
+method. The plan is a host class in core, `SportsScoreboardPlugin(BasePlugin)`,
+that takes the plugin's leagues as data (key, label, ESPN path, Live, Recent
+and Upcoming classes: basketball's `manager.py` already describes its leagues
+as such a table) and a typed mode key instead of the mode-name string parsing
+(`endswith('_live')`, `split('_')`) every copy repeats. Order within it:
+stage 4's identical helpers first; then dynamic duration, then live priority (`has_live_content`,
+`get_live_modes`, `has_live_priority`), then Vegas content, then mode
+resolution, then the lifecycle methods. Pilot the whole host on nrl or afl,
+the smallest copies (about 1,850 lines each), with a frame soak and a
+live-game soak before a second plugin moves. `get_vegas_content` is also being
+changed by the scroll-performance work: coordinate before touching it.
+
+**Held:** `data_sources.py` (nine copies; soccer's matches core's) and
+`dynamic_team_resolver.py` (eight true forks, a different constructor from
+core's). Effort on data fetching is better spent on the shared poller that
+family 9 prepares.
+
+### Product decisions each family needs
+
+Owner calls to make before (or while) reconciling. Items marked *verify* are
+suspected behaviour that needs a payload or a rig to confirm first.
+
+- **5, game-over check.** Which rule each sport gets: the clock never ends a
+  game in afl, nrl and soccer (`CLOCK_COUNTS_DOWN = False`); hockey ends at
+  0:00 from period 3, basketball, football and lacrosse from period 4.
+  baseball and ufc share a copy that reads a missing clock as "0:00": dormant
+  in baseball (its games carry no `period`), and not triggered by ufc's round
+  breaks either. ESPN sends a break as `STATUS_END_OF_ROUND` with displayClock
+  `-`, not `0:00` (verified against recorded payloads; ledmatrix-plugins#580
+  pins it). Whatever rule ufc gets must not read `-` as `0:00`. Decide ufc's
+  rule: no clock rule (ESPN's `STATUS_FINAL` is the only end signal it needs;
+  this also closes a ~1 s window at the horn when the ticking clock reads
+  `0:00`), or its own final period.
+- **6, favourite matching.** NRL keeps matching favourites by team id
+  (abbreviations collide: NEW, CAN), through `_favorite_key` rather than its
+  own copies of the selection methods. Six plugins log the recent-games
+  selection at INFO; baseball, football and ufc do not.
+- **7, other-games rotation.** football advances the rotation window under
+  `_games_lock` (update() and display() both advance it; interleaved, a
+  window of games is skipped) and fixes a favourites-only pool that recomposed
+  the list on every frame. Port both. ufc does not attach odds to fights
+  rotated in: decide whether rotated fights show odds.
+- **8, rankings.** (a) afl, basketball, nrl and soccer turn a *standings*
+  payload into ranks (a pro league's standings position becomes the rank
+  badge); baseball, hockey, lacrosse, ufc and football do not. Which is
+  right is visible on every pro-league card with "show ranking" on.
+  (b) football also keys ranks by team id, so two schools sharing an
+  abbreviation across divisions cannot be confused: adopt for all.
+  (c) football asks for the division roster of the *season* year (July
+  onward is this year's season), which is right for football and wrong for
+  college basketball, hockey and lacrosse, whose ESPN season is the year it
+  ends: a per-sport seam, not football's constant. (d) baseball's
+  `_choose_poll` calls `dynamic_team_resolver.choose_top_division_poll`, the
+  others inline it: one home, in core.
+- **9, live fetch and odds.** (a) afl, basketball, nrl and soccer cache the
+  live scoreboard for 30 s under `<sport_key>_scoreboard_current`; the others
+  do not (the harness fixtures seed that key, so the change shows up there).
+  (b) basketball fetches college games with no `dates` parameter, citing a
+  404 (*verify* now that `espn_dates` handles ranges). (c) odds are fetched
+  three ways: blocking (hockey, lacrosse), a thread waited on for 1.5–2 s
+  (six plugins), or fire-and-forget for upcoming games (basketball). This
+  sets how long `update()` takes and when an odds line appears. (d) nrl
+  guards on a missing odds manager; port it.
+- **10, view model.** Per key, whether every sport emits it. Additive only:
+  no key is renamed or removed.
+- **11 and 12, the scorebug and the card.** The pinned divergences in
+  `test/test_sports_twins.py`, where switch mode and scroll mode draw the
+  same game differently:
+  - weekday timezone: the card reads only `config["timezone"]` and falls back
+    to UTC, so a board with only the global zone labels an evening kickoff
+    with the next day. **Decided 2026-09-24: use the plugin's timezone
+    (fix); not yet implemented;**
+  - an out-of-range start time: the scorebug drops the weekday, the card
+    raises;
+  - favourite result on a nested payload, which score wins when flat and
+    nested disagree, and where the favourites come from (the manager's list
+    vs the game's stamped list plus config);
+  - the element vocabulary (`team_text` vs `team_name`; rank and odds in one
+    map, not the other), and its consequences: a `team_name` colour reaching
+    one team face and not the other, and the odds face shared with the score
+    face in scroll mode only;
+  - per-mode colour overrides, which apply in switch mode only;
+  - by design, kept unless the owner says otherwise: the date format
+    (`switch_date_format` "numeric" vs the card's "abbrev") and the upcoming
+    centre (`switch_upcoming_center` "date_time" vs "vs"), both with an
+    "inherit" opt-in; and the two schema-font caches (per class vs per path).
+
+  Also: football's `_fit_score_font` swaps to the narrow score face at any
+  panel height when the score overflows, where the other seven keep the
+  design face at or below the design height (a 64x32 board shows the
+  difference); and whether switch mode and the card become one renderer drawn
+  at two sizes.
+- **13, mode lifecycle.** The live-rotation dialect per sport (incremental
+  SWRR in afl, nrl and soccer; a precomputed schedule elsewhere); which sports
+  arm celebrations and on what (stays in each plugin, as in stage 3).
+- **14, `manager.py`.** Dynamic-duration semantics (what completes a cycle,
+  the floor and cap per mode), what counts as live content for live priority
+  (favourites only or any live game), and the order of Vegas content.
+
+### Measuring progress
+
+`scripts/sports_drift_report.py` prints the numbers above for any
+ledmatrix-plugins checkout (`--plugins <path>` or `LEDMATRIX_PLUGINS`). CI runs
+it on every push and PR against the monorepo's main (the "Sports drift report"
+job in `.github/workflows/test.yml`): report only, never failing, with the
+tables in the job summary and the full JSON as an artifact. The monorepo's
+`scripts/check_sports_drift.py` is the gate: it fails when a function that
+agrees across the plugins starts to differ. A stage is done when its family
+shows one variant per class here and its copies are gone.
+
+```
+python scripts/sports_drift_report.py --plugins ../ledmatrix-plugins
+python scripts/sports_drift_report.py --family sports.py::_is_game_really_over --diff
+```
+
+## Phases B0–B6 (history)
+
+The first project: it moved the scroll orchestration into core and proved the
+upgrade path (floors, the store's compatibility gate, the sunset). All seven
+phases are done. They are kept because the reasoning in B4–B6 is what every
+later stage relies on; the plan from here is [Roadmap](#roadmap).
+
+B0–B3 shipped in core 3.2.0. The rollout after them split into three phases
+with very different risk profiles, because one of them cannot break a user on
+an old core and the other can.
 
 | Phase | Scope | Status | Gate |
 |---|---|---|---|
@@ -263,8 +553,12 @@ a floor can be trusted against, and today it is not:
   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
+  (the registry then carried no floor field, so the incoming floor was
+  unknowable before it) and undone with `git reset --hard` to the pre-pull
+  commit. The registry now publishes `ledmatrix_min_version`, and install and
+  update refuse on it before downloading or pulling; both post-download gates
+  remain as the fallback for older registries, other branches and
+  `compatible_versions`. 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
@@ -427,10 +721,13 @@ deprecated `ledmatrix_min`). See
 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.
+**The modules held back then** (`data_sources.py`, `game_renderer.py`,
+`base_odds_manager.py`) have since gone different ways: the eight team
+scoreboards import core's `base_odds_manager` (ufc keeps an MMA fork), the
+game renderers inherit core's `SportsCardWrappersMixin` (3.7.0) but keep their
+drawing, and `data_sources.py` is still copied. Their status is under
+[Roadmap](#roadmap). B5's lesson applies to all of them: build the object and
+diff rendered output rather than trust a static check.
 
 ### B5 retrospective — what the adoption actually cost
 
@@ -473,40 +770,12 @@ and its one delivered user-visible gain was that adopted plugins honoured the
 global `target_fps` instead of hardcoding ~100 FPS (since withdrawn: see the
 note under the B3 design above).
 
-### Decision: stop adopting further modules until B6 closes
+### Decision: stop adopting further modules until B6 closes (lifted)
 
-`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
-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. **Soak the adoptions on hardware.** football and hockey have been run on a
-   live rig through real games; baseball was watched through one earlier. The
-   rest are proven by harness, unit tests and pixel comparison. Out-of-season
-   sports cannot be soaked until their season starts. When you do, **check the
-   rig's `*_display_mode` first** — a board in `switch` mode will happily load a
-   sunset plugin and tell you nothing about the scroll code the sunset changed.
-2. **Cut 3.3.0.** Not required by B6 — its floors are 3.2.0, which is released —
-   but `calendar` 1.2.3 floors at 3.3.0 for the device-authorization endpoints
-   that landed after 3.2.0, so it is un-installable until the release exists.
-3. **Reconsider the held modules** (`data_sources.py`, `game_renderer.py`,
-   `base_odds_manager.py`) now that the sunset has closed. `game_renderer.py` is
-   the largest single duplication left: ~11,500 lines across eight plugins, with
-   ~36,500 more in the eight `sports.py`. The `src/base_classes/sports/`
-   package promoted in B1/B2 was never imported by a plugin and has been
-   removed, so the plugin copies are the only starting point.
+Held from B5 until B6 ran on 2026-09-01: each adoption added a second copy to
+keep in step against a payoff that depended on the sunset. Once the store
+refused a too-new plugin on every route, adopting and sunsetting in one stage
+became safe, and stages 0–3 under [Roadmap](#roadmap) did exactly that.
 
 ## How to keep this project healthy
 
@@ -533,7 +802,9 @@ Lessons this migration paid for, worth applying beyond it:
 ## Rules for contributors
 
 - **Promote on evidence, not intuition.** A method moves to core when every copy
-  has it and they agree on intent. Otherwise it stays in the plugins.
+  that has it is identical. Drifted copies are reconciled first, one family
+  per release, with each visible difference an owner decision (see
+  [Roadmap](#roadmap)); until then they stay in the plugins.
 - **Never add a sport name to core.** If core needs to know which sport it is,
   the design is wrong — add an override point instead.
 - **A capability that is not opted into must not execute.** If you find yourself

docs/TROUBLESHOOTING.md

@@ -84,6 +84,43 @@ python3 web_interface/start.py
 
 ### Installation & Build Issues
 
+#### "This version of Raspberry Pi OS is not supported"
+
+LEDMatrix installs on Raspberry Pi OS Lite **Trixie** (Debian 13, Python
+3.13) or **Bookworm** (Debian 12, Python 3.11). The installer checks
+`/etc/os-release` before it changes anything and stops on anything else.
+
+**Check what you have:**
+```bash
+grep -E '^(PRETTY_NAME|VERSION_ID)=' /etc/os-release
+python3 --version
+```
+
+**Solutions:**
+- `VERSION_ID="11"` (Bullseye) or older: flash a new card with Raspberry Pi
+  Imager, choosing Raspberry Pi OS Lite (64-bit). Trixie is recommended;
+  Bookworm (Legacy) also works. An in-place upgrade from Bullseye is not
+  supported by Raspberry Pi and is not worth the risk.
+- "Desktop environment detected": use the Lite image, not the desktop one.
+- "python3 is Python 3.x; LEDMatrix needs Python 3.11 or newer": something
+  has replaced the system `python3`. Point it back at the OS's own Python
+  (`/usr/bin/python3` should be 3.11 on Bookworm, 3.13 on Trixie).
+- `sudo bash scripts/check_system_compatibility.sh` runs the same checks
+  without installing anything.
+
+#### "This Pi manages its network with dhcpcd, not NetworkManager"
+
+A warning, not an error: the install carries on and the display works. But
+choosing a WiFi network from the web page and the `LEDMatrix-Setup` hotspot
+both need NetworkManager, the default on Bookworm and Trixie. It appears
+when dhcpcd was selected in `raspi-config`. Switch back with a keyboard and
+screen attached (or over Ethernet), since the WiFi connection drops briefly:
+
+```bash
+sudo raspi-config   # Advanced Options -> Network Config -> NetworkManager
+sudo reboot
+```
+
 #### Step 6 fails: "Failed building wheel for rgbmatrix"
 
 **Symptoms:**
@@ -295,6 +332,85 @@ sudo systemctl cat ledmatrix-web | grep User
 
 ---
 
+#### Issue: Updates and the update channel
+
+**Symptoms:**
+- The General tab says "Stable: this device runs code newer than the newest
+  release ... keeps following main"
+- Tools shows a version such as `v3.8.0` instead of a branch name, or `git
+  status` over SSH says `HEAD detached at v3.8.0`
+- Update Code says "already up to date" while GitHub's `main` has newer commits
+
+**Explanation:** these are the Stable update channel working as intended
+(`auto_update.channel`, General → Update Channel). Stable installs the
+newest release tag, which git checks out without a branch ("detached
+HEAD"); that is normal and every update path handles it. Stable never
+installs an older version than the one running, so a device that is ahead of
+the newest release keeps following `main` until a release includes its
+commit, then switches to releases on its own.
+
+**Solutions:**
+
+1. **Want the newest code instead?** Set Update Channel to **Beta** and click
+   Update Code. The device leaves the release for `main` and pulls it.
+   Or from SSH:
+   ```bash
+   curl -X POST http://localhost:5000/api/v3/system/update-channel \
+        -H 'Content-Type: application/json' -d '{"channel": "beta"}'
+   ```
+2. **See what the next update will do:**
+   ```bash
+   curl 'http://localhost:5000/api/v3/system/update-channel?fetch=1'
+   ```
+3. **Local changes after a channel switch:** edits that no longer fit the new
+   version are kept in the git stash rather than lost; `git stash list`
+   shows them as "LEDMatrix autostash before update".
+4. **A new install is on a release, not `main`.** The one-shot installer
+   checks out the newest release. For the newest code instead, install with
+   `LEDMATRIX_CHANNEL=beta`:
+   ```bash
+   curl -fsSL https://raw.githubusercontent.com/ChuckBuilds/LEDMatrix/main/scripts/install/one-shot-install.sh | LEDMATRIX_CHANNEL=beta bash
+   ```
+
+---
+
+#### Issue: "service settings ... are not applied yet" after an update
+
+**Symptoms:**
+- Update Code's message, or the web interface log, says an update changes
+  service settings that are not applied yet, and to run the installer
+- The display logs `ledmatrix.service differs from systemd/ledmatrix.service`
+  at startup
+
+**Explanation:** updates install the systemd units a new version changes
+through the root helper `/usr/local/sbin/ledmatrix-refresh-units`, which the
+installer sets up and grants to the web user in
+`/etc/sudoers.d/ledmatrix_web`. A device installed before that has neither,
+so the new unit settings (for example the display's watchdog) wait for a
+reinstall. The update itself is fine.
+
+**Solution:** re-run the installer once, as root:
+```bash
+cd ~/LEDMatrix
+sudo ./first_time_install.sh
+# or, lighter: install the units and helper, then the sudo rules
+sudo ./scripts/install/install_service.sh
+./scripts/install/configure_web_sudo.sh
+```
+Check it worked:
+```bash
+ls -l /usr/local/sbin/ledmatrix-refresh-units   # root root, rwxr-xr-x
+sudo -l | grep ledmatrix-refresh-units           # the two rules
+```
+A message that the helper **refused** a unit (`refusing to install it`)
+means a template in `systemd/` was edited so that it would run as another
+account or from another folder. The message names the template. Look at
+what changed with `git diff -- systemd/`, save any edit you want to keep,
+then restore only that file, for example
+`git checkout -- systemd/ledmatrix-web.service`.
+
+---
+
 ### WiFi & AP Mode Issues
 
 #### AP Mode Not Activating
@@ -328,9 +444,16 @@ sudo systemctl cat ledmatrix-web | grep User
 
 5. **Check required services:**
    ```bash
+   systemctl is-active NetworkManager   # must say "active"
    sudo systemctl status hostapd
    sudo systemctl status dnsmasq
    ```
+   On a fresh install `hostapd` shows as **masked**. That is expected, on
+   Bookworm and Trixie alike: Debian's hostapd package masks the service
+   when it is installed without a configuration, so the hotspot is brought
+   up through NetworkManager instead (look for `nmcli hotspot fallback` in
+   `journalctl -u ledmatrix-wifi-monitor`). If NetworkManager is not
+   active, see "This Pi manages its network with dhcpcd" above.
 
 6. **Manually enable AP mode:**
    ```bash
@@ -516,6 +639,65 @@ sudo systemctl cat ledmatrix-web | grep User
    python3 scripts/check_plugin.py --plugin plugin-id
    ```
 
+#### Panel Frozen, or the Display Restarts Every Few Minutes
+
+**Symptoms:**
+- The panel stops changing while `systemctl status ledmatrix` says `active`
+- The display restarts on its own, a couple of minutes after it froze
+- `/api/v3/health` shows `checks.display_loop.status` as `stalled`
+
+The display's render loop checks in with systemd every few seconds
+(`WatchdogSec=120` in `ledmatrix.service`) and writes a heartbeat to
+`/run/ledmatrix/display-heartbeat.json`. When the loop gets stuck -- almost
+always inside one plugin's `display()` -- the check-ins stop, and after two
+minutes systemd kills and restarts the display. The kill dumps every thread's
+stack into the log, so it says which plugin was stuck.
+
+**Solutions:**
+
+1. **Find the stuck plugin.** Look for the watchdog kill and the stack dump
+   after it. The render loop is the thread whose stack runs through
+   `display_controller.py` in `run` (usually the `Current thread` block);
+   the first `plugin-repos/...` file in it is the plugin:
+   ```bash
+   sudo journalctl -u ledmatrix --since "1 hour ago" | grep -A40 "Watchdog timeout"
+   ```
+
+2. **Check the heartbeat by hand.** Its age should stay under about ten
+   seconds while the display runs:
+   ```bash
+   cat /run/ledmatrix/display-heartbeat.json
+   curl -s http://localhost:5000/api/v3/health | python3 -m json.tool | grep -A3 display_loop
+   ```
+   `not_reported` means the display writes no heartbeat: it has not drawn
+   its first frame yet, or it runs an older version.
+
+3. **Disable the plugin** in the web UI and report it to its author with the
+   stack dump. Restarts that repeat back off from 10 seconds to two minutes
+   apart, so a plugin that hangs on every start does not restart the display
+   hundreds of times an hour.
+
+4. **Is the watchdog installed?** Updates install new unit settings once the
+   installer has set up `ledmatrix-refresh-units`; installs from before that
+   keep their old unit until the installer is re-run (a startup warning says
+   the unit differs from its template):
+   ```bash
+   systemctl show -p WatchdogUSec ledmatrix   # 2min once running; 0 = not installed
+   sudo ./scripts/install/install_service.sh
+   ```
+   `WatchdogUSec` reads `15min` for the first minutes after a start: that is
+   the start-up allowance, narrowed to two minutes once the first frame is on
+   the panel.
+
+5. **A plugin that legitimately blocks longer** than two minutes (it should
+   not; `display()` runs on the render thread) can be given more time with a
+   drop-in, `sudo systemctl edit ledmatrix`:
+   ```ini
+   [Service]
+   WatchdogSec=300
+   ```
+   `WatchdogSec=0` turns the watchdog off.
+
 #### Stale Cache Data
 
 **Symptoms:**
@@ -952,6 +1134,11 @@ git reset --hard HEAD~1
 # Or rollback to specific commit
 git reset --hard <commit-hash>
 
+# On the Stable update channel HEAD is a release tag, not a branch:
+# go back to an earlier release instead (the next update moves forward again)
+git tag --list 'v*' --sort=-v:refname | head
+git checkout --detach v3.7.0
+
 # Restart all services
 sudo systemctl restart ledmatrix
 sudo systemctl restart ledmatrix-web

docs/WEB_FRONTEND_ARCHITECTURE.md

@@ -0,0 +1,309 @@
+# Web frontend architecture
+
+This page covers where the web UI's JavaScript is going and how it gets
+there one page at a time. The UI is Flask + HTMX + Alpine.js. Templates
+live in `web_interface/templates/v3/` and static files in
+`web_interface/static/v3/`.
+
+Two rules hold at every step:
+
+- **The Pi never builds anything.** It serves the files that are committed.
+  CI builds the generated CSS (`scripts/build_css.py`, see #685) and checks
+  it. The JavaScript needs no build at all: it is native ES modules that the
+  browser loads as they are.
+- **Every page keeps working, and so does every plugin.** Third-party plugin
+  forms, `x-widget` scripts and plugin web UIs use the existing `window.*`
+  names. Each name keeps working as an alias until a release announces that
+  it will be removed.
+
+## Where it started
+
+- About 195 `window.*` globals. Their load order is held together by comments
+  repeated in the headers of `app-early.js`, `app-shell.js` and
+  `plugins_manager.js`.
+- About 5,700 lines of inline `<script>` in the tab partials.
+  `js/htmx-config.js` re-runs every one of them after every htmx swap, so
+  each partial's code had to cope with running twice.
+- The installed-plugin list is kept in four places.
+- Plugin config forms are drawn by the `render_field` macro in
+  `partials/plugin_config.html`, which is about 1,100 lines of Jinja. It
+  duplicates the JS widgets. The server then needs about 430 lines to
+  rebuild JSON from the flat dotted keys the form posts. The soccer form
+  renders to 1.2 MB of HTML.
+- `plugins_manager.js` is 3,800 lines. The owner decided that it needs a
+  namespace refactor before it is split, which is what this plan provides.
+
+## Target
+
+```
+static/v3/js/
+  core/                 ES modules ("type": "module" in core/package.json)
+    boot.js             entry point; base.html loads it with <script type="module">
+    registry.js         page lifecycle: init/destroy on htmx swaps
+    api.js              fetch wrapper for /api/v3 (JSON envelope, login redirect)
+    facade.js           window.LEDMatrix and deprecated aliases
+    (later) escape.js, notify.js, dialog.js, streams.js, visibility.js,
+            store.js (the one installed-plugin store), form/renderer.js
+  pages/                one module per tab partial
+    cache.js            export init(root, ctx), destroy(root, ctx)
+    durations.js, operation-history.js, raw-json.js, backup-restore.js
+    ...
+```
+
+### The page lifecycle
+
+A converted partial has no `<script>`. Its root element names its page:
+
+```html
+<div class="..." data-page="cache"> ... </div>
+```
+
+`core/boot.js` lists each page with a loader,
+`'cache': page(function() { return import('../pages/cache.js'); })`, and
+registers them all. A page's module is fetched only when its partial first
+appears. `page()` remembers the module once loaded, so the alias of an old
+synchronous global (`validateJSON` returns a boolean) still answers
+synchronously while its page is on screen.
+
+The conventions the converted pages share:
+
+- **Buttons name an action.** A partial's buttons carry `data-action` (and
+  any argument as another `data-*` attribute) instead of an `onclick` that
+  names a global. One delegated listener on the page root handles them all,
+  including rows drawn later.
+- **Server data is drawn with `textContent`**, never a markup string.
+- **Reads are cancelled, writes are not.** Loads pass `ctx.signal`, so a swap
+  cancels them. Saves, deletes, exports and restores do not: the server
+  finishes them anyway, so the page still reports the result in a
+  notification but draws nothing into a page that has gone.
+- **Old globals become aliases.** Each `window.*` name a page used to define
+  is made in `boot.js` with `alias(page, name, replacement)`, which forwards
+  to the module's export of the same name and warns once.
+- **Timers are cleared in `destroy()`**, the one thing `ctx.signal` cannot
+  undo by itself.
+
+`core/registry.js` handles the rest:
+
+| Event | What the registry does |
+|---|---|
+| `htmx:beforeSwap` (on `document`, so it runs after the body-level handlers that can veto a swap) | If `detail.shouldSwap` is still true, destroys every mounted page inside the swap target |
+| `htmx:afterSwap` | Destroys any mounted page whose root has left the document, then mounts every `data-page` root not mounted yet |
+| `LEDMatrix.pages.refresh()` | Same as afterSwap. `loadPartialDirect` (the no-htmx fallback in `base.html`) calls it |
+| `start()` | Mounts whatever is already on the page. Module scripts run deferred, so a partial may arrive first |
+
+Mounting is idempotent: a root is never initialised twice.
+
+Each mount gets a `ctx` object:
+
+| Field | Contents |
+|---|---|
+| `ctx.root` | The page's root element |
+| `ctx.name` | The page name |
+| `ctx.signal` | An `AbortSignal` that is aborted after `destroy()` |
+| `ctx.state` | A per-mount object for the page's own state |
+| `ctx.api` | Shared service from `boot.js` |
+| `ctx.notify` | Shared service from `boot.js` |
+
+A page that passes `{ signal: ctx.signal }` to `addEventListener` and
+`fetch` needs no teardown code. Its listeners and in-flight requests go
+away when the partial is swapped out. `pages/cache.js` is the worked
+example: its delete buttons use one delegated listener, rows are built with
+`textContent` rather than markup strings, and a newer load supersedes an
+older one.
+
+### One facade
+
+`window.LEDMatrix` is the only global the module code adds:
+
+| Member | What it is |
+|---|---|
+| `api` | `core/api.js`: `get`/`post`/`put`/`del`. Resolves to the JSON body, rejects with an `ApiError` |
+| `pages` | `register`, `refresh`, `list` |
+| `notify(message, type)` | Calls `window.showNotification`, looked up at call time |
+| `escape` | Read-through to `window.LEDEscape` |
+| `widgets` | Read-through to `window.LEDMatrixWidgets` |
+| `deprecate(name, target, replacement)` | Keeps an old `window.*` name working. It warns once in the console, then forwards |
+
+`ApiError` carries `status`, `body`, `network` and `loginRequired`.
+
+`escape`, `widgets` and `notify` are read at call time. The classic scripts
+that define them are deferred, and a plugin may replace them.
+
+Login: `base.html` wraps `window.fetch` before any other script runs, and
+the wrapper sends a 401 with `X-LEDMatrix-Login` to the login page (#683).
+`api.js` calls `window.fetch` at call time, so its requests get the same
+redirect. It also rejects that answer quietly with `loginRequired`, so no
+error message flashes up while the page navigates away.
+
+### Serving modules from the Pi
+
+- **MIME type.** A browser runs a module only when it is served with a
+  JavaScript MIME type. `app.py` pins `.js` and `.mjs` to `text/javascript`
+  rather than trusting the host's mimetypes table, and
+  `test/web_interface/test_es_modules.py` checks it.
+- **Caching.** `url_for` adds `?v=<mtime>` to the entry script, but modules
+  import each other by plain relative URL, without the version. A static
+  `.js` request without `v` is therefore served `Cache-Control: no-cache`
+  (revalidated, so 304 when unchanged) instead of being cached as immutable
+  for a year. Versioned URLs keep the long cache. A later optimisation is an
+  import map that maps each module to its versioned URL.
+- **Load order.** `boot.js` loads after every classic script. Modules are
+  deferred and run in document order with the deferred classic scripts.
+  Nothing classic may depend on a module at load time. A classic script that
+  needs a module service calls `window.LEDMatrix` at run time.
+
+### One form model
+
+`src/plugin_system/field_model.py` provides
+`build_field_model(schema, config, plugin_id)`. It walks a plugin's schema
+once and returns a JSON tree with these keys for each field:
+
+- path, label, help, widget
+- starting value, default
+- constraints, options, secret flag
+- the exact form controls the macro posts today (`inputs`)
+- the JS widget it mounts (`mount`)
+
+`test/test_field_model_parity.py` renders the real macro for every schema it
+can find and checks that the model names the same controls, with the same
+starting values, in the same order, and the same widget mounts. The schemas
+come from `plugin-repos/`, `test/fixtures/plugins/`, the ledmatrix-plugins
+monorepo when a checkout is present, and a synthetic schema that reaches
+every branch of the macro. The test was mutation-checked when it was
+written. Each of these deliberate model bugs makes it fail:
+
+- dropping the checkbox-group sentinel
+- dropping a table's `00:00` time default
+- picking the first matching `<select>` option instead of the last
+- dropping the `None` quirk
+- missing all-hidden objects
+
+The model mirrors the macro's quirks on purpose. The parity run surfaced
+these:
+
+- 83 number fields whose schema default is `null` render `value="None"`.
+- Four array fields name an `x-widget` the core does not ship (`color`,
+  `tag-input`) and fall back to a comma-separated text box.
+- A list-typed `type` uses its first entry, so `["null", "string"]` draws a
+  text box.
+- Eleven objects with no properties and no widget render nothing.
+
+These get fixed once, in the renderer, after the switch below.
+
+## Switching forms to the model, behind a flag
+
+Stage 1 (this change) only proves the model is complete. Rendering does not
+change. The switch is staged so either path can be turned back on at any
+point:
+
+1. **Model endpoint.** `GET /api/v3/plugins/config/model?plugin_id=<id>`
+   returns `build_field_model(schema, prepared_masked_config)`. It uses the
+   same preparation as the partial: defaults merged, secrets masked.
+2. **Renderer module.** `core/form/renderer.js` walks the model. It draws
+   plain fields itself and hands every widget to `LEDMatrixWidgets` through
+   one `mount(el, field)` adapter. The adapter keeps plugin widgets' existing
+   `render(container, config, value, options)` signature (the hard
+   constraint in PRODUCT.md). `getValue()` results are assembled into one
+   JSON object.
+3. **Flag.** `plugin_config.html` renders the macro unless the form-model
+   flag is on. The flag is a `web_interface.form_model` setting in
+   `config.json` (default off), plus a per-browser override
+   (`localStorage.ledmatrixFormModel`) so a tester can compare both paths on
+   one device. With the flag on, the partial renders only a
+   `<div data-page="plugin-config" data-plugin-id="...">` root, and
+   `pages/plugin-config.js` fetches the model and renders it.
+4. **JSON submit.** With the flag on, Save posts
+   `Content-Type: application/json` to the existing
+   `POST /api/v3/plugins/config` JSON path (`plugin_config.py`, `is_json`).
+   That path already validates against the schema and keeps secrets. No
+   dotted keys, no `__rendered_section`, no checkbox reconstruction.
+5. **Save parity test.** This gates turning the flag on by default. For every
+   schema, posting the macro form's data and posting the renderer's JSON
+   must store the same config.
+6. **Retire.** Once the flag has been on by default for a release with no
+   regressions, the macro shrinks to a no-JS fallback for plain fields, and
+   the form-encoded reconstruction (`_parse_form_value_with_schema`,
+   `_set_nested_value`, `_set_missing_booleans_to_false` and friends in
+   `api_v3/__init__.py`) is deleted. The settings search index is then built
+   from the model instead of from rendered HTML.
+
+## Migration order
+
+Smallest and most isolated first. `plugins_manager.js` goes last. Line counts
+are the inline script in each partial today.
+
+| # | Page | Inline JS | Why it is here |
+|---|---|---|---|
+| 1 | Cache (`cache.html`) | 163 lines, now 0 | **Done in stage 1.** One endpoint pair, no globals other pages use. The reference conversion |
+| 2 | Rotation (`durations.html`) | 29 lines, now 0 | **Done in stage 2.** The form stays plain htmx; the page starts the shared rotation-order widget, whose plugin-list request now takes `ctx.signal`. Its `hx-on` and `onsubmit` attributes call shared globals (`showSaveResult`, `fixInvalidNumberInputs`) and move with step 6 |
+| 3 | Operation History | 293 lines, now 0 | **Done in stage 2.** Read-only list; rows drawn with `textContent`, the search debounce cleared on destroy. The "Showing x to y" counters now also reset when nothing matches |
+| 4 | Config Editor (`raw_json.html`) | 212 lines, now 0 | **Done in stage 2.** Plain textareas (no CodeMirror on this page). It defined 5 globals after all (`formatJson`, `manualValidateJson`, `validateJSON`, `saveMainConfig`, `saveSecretsConfig`); nothing else used them, and they are deprecated aliases now. The live "Invalid JSON" line no longer puts the parser's message into `innerHTML` |
+| 5 | Backup & Restore | 232 lines, now 0 | **Done in stage 2.** Its 5 globals (`exportBackup`, `loadBackupList`, `validateRestoreFile`, `clearRestore`, `runRestore`) are deprecated aliases; the buttons are delegated `data-action`s. Uploads go through `ctx.api.request(..., { body: formData })` (`api.js` gained a raw `body` option) |
+| 6 | Schedule | 193 | 2 globals used as `hx-on` response handlers. Moves `hx-on` handlers into page listeners |
+| 7 | General | 147 | `webLogin` global and the security section. The first page that touches login |
+| 8 | Display | 231 | First page with `LEDVisibility` timers: those move to a `ctx.visibility` service that stops on destroy |
+| 9 | Overview | 410 (4 scripts) | First-run surface: Getting Started, update banner, live preview. Five globals |
+| 10 | WiFi | 364 | `x-data="wifiSetup()"` is defined by its own script. Moves to `Alpine.data()` registered from the module. AP-mode first screen, so it needs the AP-mode test on a real device |
+| 11 | Fonts | 681 | Large, but self-contained (6 globals) |
+| 12 | Logs | 801 | 14 globals, a stream and timers. Uses the visibility service from step 8 |
+| 13 | Tools | 1,022 | 21 globals, MQTT bridge, Pixlet editor, diagnostics polling |
+| 14 | Starlark app config, plugin config (`plugin_config.html`) | 123 + 294 | Plugin panels sit inside an Alpine `x-if` that removes them without an htmx swap. The registry's sweep covers that on the next swap; this step adds a MutationObserver or an `x-if` hook. Then the form-model flag (above) |
+| 15 | Plugin Manager (`plugins.html` + `plugins_manager.js`) | 3,836-line file | Last. Split along the seams that already exist (installed grid, store, registries, Starlark section, on-demand) into `pages/plugins/*.js`. Its 42 globals become aliases. The four installed-plugin stores merge into one `core/store.js`, and `window.installedPlugins` becomes a getter over it |
+
+The shell moves in parallel, a service at a time, with no page depending on
+the order:
+
+| Service | Current home | New module |
+|---|---|---|
+| `showNotification` | 4 versions | `core/notify.js` |
+| The modal helper | `utils/dialog.js` | `core/dialog.js` |
+| SSE streams | `app-shell.js` | `core/streams.js` |
+| `LEDVisibility` | `app-shell.js` | `core/visibility.js` |
+
+Each move leaves the old global as an alias. When the last inline script is
+gone, the script re-execution in `htmx-config.js` and the "HTMX never
+loaded" fallbacks in `base.html` can go too (keep the captive-page path).
+
+## How the tests cover each step
+
+The JS suites live in `test/js` (see `test/js/README.md` and
+`docs/HOW_TO_RUN_TESTS.md`). In CI, the **Web UI JS tests** job installs
+jsdom, starts the web interface and runs `node test/js/run_all.js` with
+`REQUIRE_DOM=1`, so a skipped DOM suite fails the job.
+`test/test_js_unit_suites.py` also runs every unit suite under pytest.
+
+Unit suites need only node. They import the shipped modules directly:
+`core/package.json` and `pages/package.json` mark those directories
+`"type": "module"`.
+
+| Suite | Kind | What it covers |
+|---|---|---|
+| `unit/test_page_registry.js` | Unit, minimal DOM shim | The lifecycle: one init per root, destroy on swap, a veto keeps the page, swaps elsewhere leave it alone, the sweep, lazy loading, a destroy while loading, error containment |
+| `unit/test_core_modules.js` | Unit | `api.js` (envelope, errors, abort, login redirect, path check) and `facade.js` (facade, aliases) |
+| `dom/test_cache_page.js` | DOM: real partial, real API shape | No inline script; one request per swap and per Refresh after five swaps; a cancelled request draws nothing; hostile keys stay text; delete, empty, error, network and login states |
+| `dom/test_durations_page.js` | DOM: real partial, real widget, real API shape | One plugin-list request per swap; Move down moves one place after five swaps; the swap cancels a request in flight; a late-loading widget is waited for, and a page swapped away while waiting starts nothing; hostile names stay text |
+| `dom/test_operation_history_page.js` | DOM: real partial, real API shape | One history request per swap and per Refresh; the plugin filter filled once (from `PluginAPI`'s cache when loaded); paging, filters, debounced search, Clear (one DELETE), error/network/login states, cancel on swap; hostile ids, users and errors stay text |
+| `dom/test_raw_json_page.js` | DOM: real partial, real config | One POST per Save after five swaps, to the right file; Format and Validate act once; invalid JSON never sent and its message stays text; a save survives a swap and is still reported; the old globals' entry points |
+| `dom/test_backup_restore_page.js` | DOM: real partial, real API shape | One request per Refresh, Delete, Export (busy button ignores a second click), Inspect and Restore after five swaps; the upload's fields and the six restore options; reads cancelled by a swap, writes not; hostile file and host names stay text; the old globals' entry points |
+| `test/web_interface/test_es_modules.py` | pytest | MIME type; `no-cache` without `?v` and immutable with it; `boot.js` loads last; every import resolves inside `core/` and `pages/`; the converted pages are exactly the registered ones, each with its module, `init`, and one root in the rendered partial; a converted partial has no `<script>` and no `onclick`; every moved global is aliased in `boot.js` and exported by its module, and no template defines it any more |
+| `test/test_field_model_parity.py` | pytest | The model against the macro for every available schema |
+
+What each future step adds:
+
+- **A page conversion** adds `dom/test_<page>_page.js`, built like the cache
+  suite: the real partial from the server, the real API's payload shape, N
+  swaps followed by one action that must make exactly one request, the
+  destroy and cancel behaviour, and escaping. `test_es_modules.py` picks up
+  the new page automatically. A unit suite that today slices a function out
+  of a template or `plugins_manager.js` and `eval`s it is rewritten to
+  import the module once that code moves (stage C of the plan).
+- **A shell service move** adds a unit suite for the module and an alias
+  test showing the old global still works.
+- **The form switch** adds the save parity test (macro form data and
+  renderer JSON store the same config, for every schema) and a DOM suite
+  for `pages/plugin-config.js`. Both run with the flag on and off.
+- **`plugins_manager.js`.** The existing DOM suites (`test_installed_dom.js`,
+  `test_store_dom.js`, `test_no_double_fetch.js`) already test the real
+  Plugin Manager in jsdom. They stay green throughout the split and are the
+  gate for it, alongside the unit suites that pin its card rendering and
+  escaping.

docs/WEB_INTERFACE_GUIDE.md

@@ -78,7 +78,9 @@ The Overview tab provides at-a-glance information and quick actions:
 - **Start Display** / **Stop Display** — control the display service
 - **Restart Display Service** — apply configuration changes
 - **Restart Web Service** — restart the web UI itself
-- **Update Code** — `git pull` the latest version (stashes local changes)
+- **Update Code** — update to the newest version on the update channel (the
+  newest release on Stable, the newest code on `main` on Beta; stashes local
+  changes). The channel is set on the General tab.
 - **Reboot System** / **Shutdown System** — confirm-gated power controls
 
 **Display Preview:**
@@ -90,6 +92,11 @@ The Overview tab provides at-a-glance information and quick actions:
 
 Configure basic system settings:
 
+- **Automatic Updates** — weekly updates with a health check and rollback
+- **Update Channel** — **Stable** (default) installs releases; **Beta**
+  installs the newest code on `main` before it is released. Switching to
+  Stable never installs an older version: a device ahead of the newest
+  release keeps following `main` until a release includes it
 - **Timezone** — used by all time/date displays
 - **Location** — city/state/country for weather and other location-aware
   plugins
@@ -130,6 +137,34 @@ Configure basic system settings:
 Click **Save** to write changes to `config/config.json`. Most changes
 require a display service restart from **Overview**.
 
+Below the settings, the **Security** section (its own buttons, not the Save
+button) controls the optional login:
+
+- **Web interface password** — off by default. Setting one turns login on:
+  browsers on your network then see a login page, and stay logged in for 30
+  days (across restarts). The browser you set it from stays logged in.
+  Changing the password logs every other browser out. **Turn login off**
+  needs the current password. A **Log out** button appears in the header
+  while you are logged in. Five wrong passwords in a minute (or 30 in an
+  hour) from one address make it wait.
+- **API tokens** — for Home Assistant, scripts, or the MQTT bridge on another
+  machine. Give it a name, click **Create token**, and copy the token right
+  away: it is shown once. Revoke it here when it is no longer needed.
+- Never asked for a password: a browser on the Pi itself, and the Wi-Fi setup
+  page while the Pi is in access-point mode (so you can always get it back on
+  a network).
+
+**Forgot the password?** SSH into the Pi and run:
+
+```bash
+sudo python3 ~/LEDMatrix/scripts/reset_web_password.py
+```
+
+(use the folder LEDMatrix is installed in). Login is off again right away,
+no restart needed, and you can set a new password. API tokens are kept; add
+`--revoke-tokens` to delete them too. Alternatively, open
+`http://localhost:5000` in a browser on the Pi itself.
+
 ### Display Tab
 
 Configure your LED matrix hardware:
@@ -346,6 +381,14 @@ The API blueprint (`web_interface/blueprints/api_v3/`) is registered at
 - `POST /api/v3/plugins/install` — Install a plugin from the store
 - `POST /api/v3/plugins/install-from-url` — Install a plugin from a GitHub URL
 
+If the optional login is on, send an API token (General > Security):
+
+```bash
+curl -H "Authorization: Bearer lmx_..." http://your-pi-ip:5000/api/v3/display/current
+```
+
+Scripts running on the Pi itself need no token.
+
 **Note:** See [REST_API_REFERENCE.md](REST_API_REFERENCE.md) for complete API documentation.
 
 ---
@@ -408,9 +451,27 @@ The API blueprint (`web_interface/blueprints/api_v3/`) is registered at
 ## Security Considerations
 
 **Network Access:**
-- The interface is accessible to anyone on your local network
-- No authentication is currently implemented
-- Recommended for trusted networks only
+- By default the interface is accessible to anyone on your local network
+- An optional password (General > Security) makes every page and API call
+  need a login or an API token; see [General Tab](#general-tab). Requests
+  from the Pi itself and the Wi-Fi setup flow in access-point mode stay open,
+  and `/api/v3/health` answers only its overall status without a login
+- The interface speaks plain HTTP, so the password and tokens cross your
+  network unencrypted: still recommended for trusted networks only
+- Behind a reverse proxy **on the Pi**, make it send `X-Forwarded-For`
+  (nginx: `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;`).
+  Without it every proxied request looks like it comes from the Pi itself,
+  which is never asked to log in
+
+**Other websites:**
+- A web page you open elsewhere could otherwise make your browser send
+  commands to the Pi (reboot, update, config changes). The interface refuses
+  any change request whose `Origin`/`Referer` header names a different site
+  (403 `CROSS_SITE_REQUEST`), so use the interface from its own address.
+- Scripts, curl, Home Assistant and the MQTT bridge send no such header and
+  keep working. Behind a reverse proxy, forward the original `Host` header
+  with its port (nginx: `proxy_set_header Host $http_host;` -- `$host`
+  drops the port).
 
 **Best Practices:**
 1. Run on a private network (not exposed to internet)
@@ -428,7 +489,9 @@ The web interface uses modern web technologies:
 
 - **Backend:** Flask with Blueprint-based modular design
 - **Frontend:** HTMX for dynamic content, Alpine.js for reactive components
-- **Styling:** Tailwind CSS for responsive design
+- **Styling:** Tailwind CSS utilities, generated at development time and
+  committed (the Pi never builds CSS; see
+  [`web_interface/README.md`](../web_interface/README.md#styling-tailwind-css))
 - **Real-Time:** Server-Sent Events (SSE) for live updates
 
 ### File Locations

first_time_install.sh

@@ -47,38 +47,51 @@ if echo "${DEVICE_MODEL:-}" | grep -qi "Raspberry Pi 5"; then
     echo "Raspberry Pi 5 detected — will verify RP1 library support."
 fi
 
-# Check OS version - must be Raspberry Pi OS Lite (Trixie)
+# Check OS version - must be Raspberry Pi OS Lite, Bookworm or Trixie.
+# The rules live in scripts/install/lib_os.sh, shared with
+# scripts/check_system_compatibility.sh.
 echo ""
 echo "Checking operating system requirements..."
 echo "----------------------------------------"
 OS_CHECK_FAILED=0
+OS_RELEASE=""
 
-if [ -f /etc/os-release ]; then
-    . /etc/os-release
-    echo "Detected OS: $PRETTY_NAME"
-    echo "Version ID: ${VERSION_ID:-unknown}"
-    
-    # Check if it's Raspberry Pi OS or Debian
-    if [[ "$ID" != "raspbian" ]] && [[ "$ID" != "debian" ]]; then
-        echo "✗ ERROR: This script requires Raspberry Pi OS (raspbian/debian)"
-        echo "  Detected OS ID: $ID"
-        OS_CHECK_FAILED=1
-    fi
-    
-    # Check if it's Debian 13 (Trixie)
-    if [ "${VERSION_ID:-0}" != "13" ]; then
-        echo "✗ ERROR: This script requires Raspberry Pi OS Lite (Trixie) - Debian 13"
-        echo "  Detected version: ${VERSION_ID:-unknown}"
-        echo "  Please upgrade to Raspberry Pi OS Lite (Trixie) before continuing"
-        OS_CHECK_FAILED=1
+OS_LIB="$(cd "$(dirname "$0")" && pwd)/scripts/install/lib_os.sh"
+if [ ! -f "$OS_LIB" ]; then
+    echo "✗ ERROR: $OS_LIB is missing, so the operating system cannot be checked."
+    echo "  Your LEDMatrix download is incomplete. Download it again and re-run this script:"
+    echo "    git clone https://github.com/ChuckBuilds/LEDMatrix.git"
+    exit 1
+fi
+# shellcheck source=scripts/install/lib_os.sh
+. "$OS_LIB"
+
+if [ -r "$LM_OS_RELEASE_FILE" ]; then
+    echo "Detected OS: $(lm_os_field PRETTY_NAME)"
+    OS_VERSION_ID=$(lm_os_field VERSION_ID)
+    echo "Version ID: ${OS_VERSION_ID:-unknown}"
+
+    if OS_RELEASE=$(lm_os_release); then
+        echo "✓ $(lm_release_label "$OS_RELEASE") detected"
     else
-        echo "✓ Debian 13 (Trixie) detected"
+        OS_ID=$(lm_os_field ID)
+        if [[ "$OS_ID" != "raspbian" ]] && [[ "$OS_ID" != "debian" ]]; then
+            echo "✗ ERROR: This script requires Raspberry Pi OS (raspbian/debian)"
+            echo "  Detected OS ID: ${OS_ID:-unknown}"
+        else
+            echo "✗ ERROR: This version of Raspberry Pi OS is not supported"
+            echo "  Detected version: ${OS_VERSION_ID:-unknown}"
+            echo "  Supported: Trixie (Debian 13) and Bookworm (Debian 12)"
+        fi
+        OS_CHECK_FAILED=1
     fi
-    
+
     # Check if it's the Lite version (no desktop environment)
     # Check for desktop packages or desktop services
     DESKTOP_DETECTED=0
-    if dpkg -l | grep -qE "^ii.*raspberrypi-ui-mods|^ii.*lxde|^ii.*xfce|^ii.*gnome|^ii.*kde"; then
+    # grep without -q: -q exits at the first match, dpkg then dies of SIGPIPE,
+    # and pipefail turns a found desktop into "not found".
+    if dpkg -l | grep -E "^ii.*raspberrypi-ui-mods|^ii.*lxde|^ii.*xfce|^ii.*gnome|^ii.*kde" >/dev/null; then
         DESKTOP_DETECTED=1
     fi
     if systemctl list-units --type=service --state=running 2>/dev/null | grep -qE "lightdm|gdm3|sddm|lxdm"; then
@@ -96,23 +109,52 @@ if [ -f /etc/os-release ]; then
         echo "✓ Lite version confirmed (no desktop environment)"
     fi
 else
-    echo "✗ ERROR: Could not detect OS version (/etc/os-release not found)"
+    echo "✗ ERROR: Could not detect OS version ($LM_OS_RELEASE_FILE not found)"
     OS_CHECK_FAILED=1
 fi
 
+# Python: whatever python3 the release ships (3.11 on Bookworm, 3.13 on
+# Trixie). Checked only when python3 is already there -- Step 1 installs it
+# otherwise, and on a supported release that brings the release's own version.
+if [ "$OS_CHECK_FAILED" -eq 0 ]; then
+    if PYTHON3_VERSION=$(lm_python_version); then
+        case "$(lm_python_check "$PYTHON3_VERSION")" in
+            ok)
+                echo "✓ Python $PYTHON3_VERSION detected"
+                ;;
+            too-old)
+                echo "✗ ERROR: python3 is Python $PYTHON3_VERSION; LEDMatrix needs Python 3.$LM_PYTHON_MIN_MINOR or newer"
+                echo "  $(lm_release_label "$OS_RELEASE") ships Python $(lm_release_python "$OS_RELEASE"). Something on this"
+                echo "  system has changed which Python 'python3' runs; point it back at the system Python."
+                OS_CHECK_FAILED=1
+                ;;
+            *)
+                echo "⚠ python3 is Python $PYTHON3_VERSION, which LEDMatrix has not been tested with"
+                echo "  (tested: 3.$LM_PYTHON_MIN_MINOR to 3.$LM_PYTHON_MAX_MINOR). Continuing anyway."
+                ;;
+        esac
+    else
+        echo "python3 not found yet; Step 1 installs it."
+    fi
+fi
+
 if [ "$OS_CHECK_FAILED" -eq 1 ]; then
     echo ""
-    echo "Installation cannot continue. Please install Raspberry Pi OS Lite (Trixie) and try again."
-    echo ""
-    echo "To install Raspberry Pi OS Lite (Trixie):"
-    echo "  1. Download from: https://www.raspberrypi.com/software/operating-systems/"
-    echo "  2. Select 'Raspberry Pi OS Lite (64-bit)' with Debian 13 (Trixie)"
-    echo "  3. Flash to SD card using Raspberry Pi Imager"
-    echo "  4. Boot and run this script again"
+    echo "Installation cannot continue."
+    lm_print_supported_os_help
     exit 1
 fi
 
 echo "✓ OS requirements met"
+
+# WiFi setup (the web page's WiFi tab and the LEDMatrix-Setup hotspot) needs
+# NetworkManager. Both releases use it by default; say so plainly if this Pi
+# does not, but carry on -- the display itself does not depend on it.
+case "$(lm_network_stack)" in
+    networkmanager) echo "✓ NetworkManager is managing the network" ;;
+    dhcpcd) lm_print_dhcpcd_advice ;;
+    *) echo "⚠ Could not tell which service manages the network; WiFi setup from the web page needs NetworkManager" ;;
+esac
 echo ""
 
 # The user who ran the installer: SUDO_USER once we are running under sudo
@@ -190,6 +232,51 @@ _sync_rgb_submodule() {
     fi
     return 0
 }
+
+# LEDMatrix's own changes to the library live in patches/rpi-rgb-led-matrix/ and
+# are applied only for the build: _apply_rgb_patches before it, _revert_rgb_patches
+# after it, success or not. The checkout is left exactly as it was, so `git pull`
+# and _sync_rgb_submodule never meet local modifications in the submodule.
+# A patch that no longer applies (a submodule bump, a hand-edited checkout) is
+# reported and skipped -- the unpatched library still builds and works, so it is
+# never fatal. One that is already applied is left alone and not reverted.
+_RGB_APPLIED_PATCHES=()
+
+_apply_rgb_patches() {
+    local sub="$PROJECT_ROOT_DIR/rpi-rgb-led-matrix-master"
+    local dir="$PROJECT_ROOT_DIR/patches/rpi-rgb-led-matrix" patch name
+    _RGB_APPLIED_PATCHES=()
+    [ -d "$dir" ] || return 0
+    for patch in "$dir"/*.patch; do
+        [ -f "$patch" ] || continue
+        name=$(basename "$patch")
+        if _git_as_repo_owner -C "$sub" apply --check "$patch" >/dev/null 2>&1; then
+            if _git_as_repo_owner -C "$sub" apply "$patch"; then
+                _RGB_APPLIED_PATCHES+=("$patch")
+                echo "Applied library patch $name"
+            else
+                echo "⚠ Could not apply library patch $name; building without it"
+            fi
+        elif _git_as_repo_owner -C "$sub" apply --reverse --check "$patch" >/dev/null 2>&1; then
+            echo "Library patch $name is already applied"
+        else
+            echo "⚠ Library patch $name does not apply to this checkout; building without it"
+        fi
+    done
+    return 0
+}
+
+_revert_rgb_patches() {
+    local sub="$PROJECT_ROOT_DIR/rpi-rgb-led-matrix-master" i
+    # Last applied first, in case two patches touch the same file.
+    for ((i = ${#_RGB_APPLIED_PATCHES[@]} - 1; i >= 0; i--)); do
+        if ! _git_as_repo_owner -C "$sub" apply --reverse "${_RGB_APPLIED_PATCHES[i]}"; then
+            echo "⚠ Could not revert $(basename "${_RGB_APPLIED_PATCHES[i]}"); restore the checkout with: git -C $sub checkout -- ."
+        fi
+    done
+    _RGB_APPLIED_PATCHES=()
+    return 0
+}
 # --- end rpi-rgb-led-matrix checkout helpers ---------------------------------
 
 # Determine the Project Root Directory (where this script is located)
@@ -223,6 +310,8 @@ SKIP_SWAP=${LEDMATRIX_SKIP_SWAP:-0}
 BUILD_JOBS_OVERRIDE=${LEDMATRIX_BUILD_JOBS:-}
 # Weekly automatic updates: 1 on, 0 off, empty = ask (interactive) or leave as is.
 AUTO_UPDATE=${LEDMATRIX_AUTO_UPDATE:-}
+# Update channel written to config.json: stable, beta, or empty = leave as is.
+UPDATE_CHANNEL=$(printf '%s' "${LEDMATRIX_CHANNEL:-}" | tr '[:upper:]' '[:lower:]')
 
 usage() {
     cat <<USAGE
@@ -240,12 +329,18 @@ Options:
       --enable-auto-update  Turn on weekly automatic updates (with health
                             check and automatic rollback)
       --no-auto-update      Leave weekly automatic updates off
+      --beta                Follow main, the newest code (the beta update
+                            channel). Without it, updates follow releases
+                            (stable). It sets the channel; it does not move
+                            this checkout -- the one-shot installer picks the
+                            version, and so does the next update.
   -h, --help                Show this help message and exit
 
 Environment variables (same effect as flags):
   LEDMATRIX_ASSUME_YES=1, RPI_RGB_FORCE_REBUILD=1, LEDMATRIX_SKIP_SOUND=1,
   LEDMATRIX_SKIP_PERF=1, LEDMATRIX_SKIP_REBOOT_PROMPT=1,
-  LEDMATRIX_SKIP_SWAP=1, LEDMATRIX_BUILD_JOBS=N, LEDMATRIX_AUTO_UPDATE=1|0
+  LEDMATRIX_SKIP_SWAP=1, LEDMATRIX_BUILD_JOBS=N, LEDMATRIX_AUTO_UPDATE=1|0,
+  LEDMATRIX_CHANNEL=stable|beta
 
 Low-memory devices:
   On a Pi with under 2GB of RAM the C++ build is limited to fewer parallel
@@ -265,6 +360,7 @@ while [ $# -gt 0 ]; do
         --skip-swap) SKIP_SWAP=1 ;;
         --enable-auto-update) AUTO_UPDATE=1 ;;
         --no-auto-update) AUTO_UPDATE=0 ;;
+        --beta) UPDATE_CHANNEL=beta ;;
         --build-jobs)
             shift
             if [ $# -eq 0 ]; then echo "--build-jobs requires a number"; usage; exit 1; fi
@@ -291,10 +387,12 @@ else
     lm_remove_build_swap() { return 0; }
 fi
 
-# Remove the temporary build swapfile no matter how the script ends. Step 6
-# tears it down itself; this is the backstop for the error path, since
-# on_error ends in `exit` and EXIT traps still run.
-trap 'lm_remove_build_swap' EXIT
+# Remove the temporary build swapfile, and take any library patches back out
+# of the submodule, no matter how the script ends. Step 6 does both itself;
+# this is the backstop for the error path (on_error ends in `exit` and EXIT
+# traps still run) and for an interrupted build. _revert_rgb_patches only
+# touches patches it applied, so running it twice is harmless.
+trap 'lm_remove_build_swap; _revert_rgb_patches' EXIT
 
 # Helpers
 retry() {
@@ -835,6 +933,10 @@ if [ ! -f "$PROJECT_ROOT_DIR/config/config.json" ]; then
         cat > "$PROJECT_ROOT_DIR/config/config.json" <<'EOF'
 {
     "web_display_autostart": true,
+    "auto_update": {
+        "enabled": false,
+        "channel": "stable"
+    },
     "timezone": "America/Chicago",
     "display": {
         "hardware": {
@@ -869,15 +971,25 @@ if [ -z "$AUTO_UPDATE" ] && [ "$ASSUME_YES" != "1" ] && [ -t 0 ]; then
     echo
     if [[ $REPLY =~ ^[Yy]$ ]]; then AUTO_UPDATE=1; else AUTO_UPDATE=0; fi
 fi
-if [ "$AUTO_UPDATE" = "1" ] || [ "$AUTO_UPDATE" = "0" ]; then
-    if python3 - "$PROJECT_ROOT_DIR/config/config.json" "$AUTO_UPDATE" <<'PY'
+case "$UPDATE_CHANNEL" in
+    stable|beta|"") ;;
+    *) echo "⚠ LEDMATRIX_CHANNEL=$UPDATE_CHANNEL is not stable or beta; leaving the update channel as it is"
+       UPDATE_CHANNEL="" ;;
+esac
+# The update channel, likewise only when asked for (--beta / LEDMATRIX_CHANNEL).
+if [ "$AUTO_UPDATE" = "1" ] || [ "$AUTO_UPDATE" = "0" ] || [ -n "$UPDATE_CHANNEL" ]; then
+    if python3 - "$PROJECT_ROOT_DIR/config/config.json" "$AUTO_UPDATE" "$UPDATE_CHANNEL" <<'PY'
 import json, os, sys, tempfile
-path, enabled = sys.argv[1], sys.argv[2] == "1"
+path, enabled = sys.argv[1], sys.argv[2]
+channel = sys.argv[3] if len(sys.argv) > 3 else ""
 with open(path, encoding="utf-8") as f:
     config = json.load(f)
 if not isinstance(config.get("auto_update"), dict):
     config["auto_update"] = {}
-config["auto_update"]["enabled"] = enabled
+if enabled in ("0", "1"):
+    config["auto_update"]["enabled"] = enabled == "1"
+if channel:
+    config["auto_update"]["channel"] = channel
 # Written beside the original and swapped in whole: the display service's
 # config watcher may be running and must never read a half-written file.
 original = os.stat(path)
@@ -898,9 +1010,11 @@ except BaseException:
     raise
 PY
     then
-        if [ "$AUTO_UPDATE" = "1" ]; then echo "✓ Weekly automatic updates enabled"; else echo "✓ Weekly automatic updates off"; fi
+        if [ "$AUTO_UPDATE" = "1" ]; then echo "✓ Weekly automatic updates enabled"
+        elif [ "$AUTO_UPDATE" = "0" ]; then echo "✓ Weekly automatic updates off"; fi
+        if [ -n "$UPDATE_CHANNEL" ]; then echo "✓ Update channel: $UPDATE_CHANNEL"; fi
     else
-        echo "⚠ Could not set auto_update in config/config.json; turn it on from the General tab instead"
+        echo "⚠ Could not set auto_update in config/config.json; set it from the General tab instead"
     fi
 fi
 
@@ -1222,9 +1336,11 @@ else
         fi
         BUILD_OUTPUT=$(mktemp)
         BUILD_SUCCESS=false
+        _apply_rgb_patches
         if run_rgbmatrix_build "$BUILD_JOBS" "$BUILD_OUTPUT"; then
             BUILD_SUCCESS=true
         fi
+        _revert_rgb_patches
         cat "$BUILD_OUTPUT" >> "$LOG_FILE"
         if [ "$BUILD_SUCCESS" != true ]; then
             print_rgbmatrix_build_failure "$BUILD_OUTPUT"
@@ -1345,15 +1461,16 @@ if ! command -v setcap >/dev/null 2>&1; then
     echo "⚠ setcap not found, skipping capability configuration"
     echo "  Install libcap2-bin if you need hardware timing capabilities"
 else
-    # Find the Python binary and resolve symlinks to get the real binary
+    # The binary the services run (ExecStart=/usr/bin/python3), symlinks
+    # resolved: python3.11 on Bookworm, python3.13 on Trixie. This used to
+    # prefer /usr/bin/python3.13 whenever it existed, which would set the
+    # capability on an interpreter the services never run if python3 pointed
+    # elsewhere.
     PYTHON_BIN=""
     PYTHON_VER=""
-    if [ -f "/usr/bin/python3.13" ]; then
-        PYTHON_BIN=$(readlink -f /usr/bin/python3.13)
-        PYTHON_VER="3.13"
-    elif [ -f "/usr/bin/python3" ]; then
+    if [ -f "/usr/bin/python3" ]; then
         PYTHON_BIN=$(readlink -f /usr/bin/python3)
-        PYTHON_VER=$(python3 --version 2>&1 | grep -oP '(?<=Python )\d+\.\d+' || echo "unknown")
+        PYTHON_VER=$(lm_python_version /usr/bin/python3) || PYTHON_VER="unknown"
     fi
 
     if [ -n "$PYTHON_BIN" ] && [ -f "$PYTHON_BIN" ]; then

integrations/mqtt_bridge/README.md

@@ -96,6 +96,13 @@ environment as `LEDMATRIX_MQTT_<KEY>` (`LEDMATRIX_MQTT_MQTT_PASSWORD`, say),
 which keeps a broker password out of a file on disk — put it in a systemd
 drop-in with `Environment=` or `EnvironmentFile=` instead.
 
+**Web login.** If the web interface's optional login is on (General >
+Security), a bridge running on the Pi itself still needs nothing: requests from
+the Pi are never asked to log in. A bridge on another machine needs an API
+token: create one under General > Security and set `"ledmatrix_api_token"`
+(or `LEDMATRIX_MQTT_LEDMATRIX_API_TOKEN`, or the token field in the Tools tab's
+bridge settings). It is sent as `Authorization: Bearer <token>`.
+
 Set `mqtt_tls: true` for a broker with TLS. `mqtt_tls_insecure` skips
 certificate verification and exists only for a self-signed broker on a
 trusted LAN; it logs a warning when used.

integrations/mqtt_bridge/ledmatrix_mqtt_bridge.py

@@ -66,6 +66,10 @@ DEFAULTS = {
     "mqtt_tls": False,
     "mqtt_tls_insecure": False,
     "ledmatrix_api_base": "http://localhost:5000",
+    # Only needed when the web interface's optional login is on AND the bridge
+    # reaches it from another machine: requests from the Pi itself never need
+    # one. Create it under General > Security; sent as a Bearer token.
+    "ledmatrix_api_token": None,
     "request_timeout": 15,
     "on_demand_duration": None,
     "log_level": "INFO",
@@ -125,10 +129,13 @@ class LEDMatrixClient:
     """
 
     def __init__(self, api_base: str, timeout: int = 15,
-                 session: Optional[requests.Session] = None):
+                 session: Optional[requests.Session] = None,
+                 api_token: Optional[str] = None):
         self.api_base = api_base.rstrip("/")
         self.timeout = timeout
         self.session = session or requests.Session()
+        if api_token:
+            self.session.headers["Authorization"] = f"Bearer {api_token}"
 
     def _call(self, method: str, path: str, **kwargs) -> Dict[str, Any]:
         url = f"{self.api_base}/api/v3{path}"
@@ -403,7 +410,8 @@ class Bridge:
         self.status_topic = f"{self.command_topic}/status"
         self.state_topic = f"{self.command_topic}/state"
         self.availability_topic = f"{self.command_topic}/availability"
-        self.client = LEDMatrixClient(config["ledmatrix_api_base"], config["request_timeout"])
+        self.client = LEDMatrixClient(config["ledmatrix_api_base"], config["request_timeout"],
+                                      api_token=config.get("ledmatrix_api_token") or None)
         self.handler = CommandHandler(self.client, config.get("on_demand_duration"))
         self._stop = threading.Event()
         self._mqtt = None

mypy-clean.txt

@@ -22,6 +22,7 @@ src/common/api_helper.py
 src/common/bdf_font.py
 src/common/espn_dates.py
 src/common/favorite_team_check.py
+src/common/fetch_service.py
 src/common/font_layout.py
 src/common/frame_timing.py
 src/common/json_body.py
@@ -32,29 +33,45 @@ src/common/render_gate.py
 src/common/scroll_config.py
 src/common/snapshot_policy.py
 src/common/sports_card.py
+src/common/sports_card_wrappers.py
+src/common/sports_celebration.py
+src/common/sports_display_rules.py
+src/common/sports_fetch.py
+src/common/sports_font_path.py
+src/common/sports_live_scroll.py
+src/common/sports_plugin_host.py
 src/common/sports_scroll.py
 src/common/sports_timezone.py
+src/common/sports_vegas.py
 src/config_service.py
 src/core_config_keys.py
 src/deprecation.py
 src/device_location.py
+src/display_arbiter.py
 src/display_geometry.py
 src/dynamic_team_resolver.py
 src/exceptions.py
 src/font_usage.py
+src/ipc/__init__.py
+src/ipc/client.py
+src/ipc/contract.py
+src/ipc/server.py
 src/logging_config.py
 src/logo_downloader.py
 src/matrix_support.py
 src/pi5_matrix_support.py
 src/plugin_system/__init__.py
 src/plugin_system/compatibility.py
+src/plugin_system/field_model.py
 src/plugin_system/operation_history.py
 src/plugin_system/operation_queue.py
 src/plugin_system/operation_types.py
+src/plugin_system/plugin_catalog.py
 src/plugin_system/plugin_dirs.py
 src/plugin_system/plugin_executor.py
 src/plugin_system/plugin_health.py
 src/plugin_system/plugin_loader.py
+src/plugin_system/plugin_runtime.py
 src/plugin_system/plugin_state.py
 src/plugin_system/repo_urls.py
 src/plugin_system/resource_monitor.py
@@ -67,13 +84,17 @@ src/plugin_system/testing/loading.py
 src/plugin_system/testing/mocks.py
 src/plugin_system/testing/plugin_test_base.py
 src/plugin_system/testing/sizes.py
+src/plugin_system/testing/vegas.py
+src/plugin_system/vegas_elements.py
 src/redaction.py
 src/scan_order.py
 src/startup_validator.py
 src/vegas_mode/__init__.py
 src/vegas_mode/config.py
 src/vegas_mode/coordinator.py
+src/vegas_mode/elements.py
 src/vegas_mode/geometry.py
+src/vegas_mode/live_worker.py
 src/vegas_mode/stream_manager.py
 src/web_interface/api_helpers.py
 src/web_interface/config_arrays.py

mypy.ini

@@ -6,8 +6,9 @@
 files = src
 exclude = (^|/)(test|__pycache__)/
 
-# Python version
-python_version = 3.10
+# Python version: the oldest the installer supports (Raspberry Pi OS
+# Bookworm ships 3.11; Trixie ships 3.13).
+python_version = 3.11
 
 # Platform (Linux/Raspberry Pi)
 platform = linux
@@ -103,8 +104,8 @@ ignore_missing_imports = True
 
 
 # numpy's own stubs (numpy>=2.3) use Python 3.12 `type` statements, which mypy
-# refuses to parse under python_version = 3.10 -- and 3.10 is the floor this
-# code has to run on, so it stays. Treat numpy as Any instead: skip it, and
+# refuses to parse under python_version = 3.11 -- and 3.11 (Bookworm) is the
+# floor this code has to run on, so it stays. Treat numpy as Any instead: skip it, and
 # follow_imports_for_stubs makes the skip apply to its .pyi files too.
 [mypy-numpy.*]
 follow_imports = skip

patches/rpi-rgb-led-matrix/0001-bulk-setimage.patch

@@ -0,0 +1,174 @@
+Faster SetImage for rpi-rgb-led-matrix (applied by first_time_install.sh at build
+time; the submodule itself stays at its pinned commit).
+
+Copying a frame into the panel buffer was the biggest CPU cost LEDMatrix owns on
+large panels: the binding's SetPixelsPillow walked the image column by column
+and called SetPixel per pixel, and each SetPixel read-modify-writes one word per
+PWM bit plane, 2KB apart, so consecutive pixels were a whole double-row apart and
+almost every write missed the cache. This patch:
+
+ * FrameCanvas gets its own SetPixelsPillow: row by row, one bulk SetPixels call
+   per row;
+ * Framebuffer::SetPixels clips once, looks colours up once per pixel, walks each
+   row's designators in order and writes the bit planes branch-free;
+ * the base Canvas.SetPixelsPillow loop (RGBMatrix.SetImage) is row-major.
+
+The bit-plane buffer is byte-identical to the old code's (882 memcmp checks over
+noise/gradient/solid/low-value/sparse images, clipped offsets, pwm 7/8/11,
+brightness 1/50/90/100, inverse colours, luminance correction off and a pixel
+mapper). Measured on a Pi 4 at 512x64: 6.0-6.3 ms -> 1.8 ms per frame through
+the Python binding; on hdpi (Pi 4, 4x128x64) frame copy 6.57 -> 2.21 ms and the
+display process 139% -> 103% of a core.
+
+LEDMatrix always draws into the canvas that is not on screen and swaps it in
+(DisplayManager.update_display), so the write order cannot show as tearing.
+
+Against hzeller/rpi-rgb-led-matrix 1ee4f76.
+
+diff --git a/bindings/python/rgbmatrix/core.pyx b/bindings/python/rgbmatrix/core.pyx
+index 230d87f..babc3bb 100644
+--- a/bindings/python/rgbmatrix/core.pyx
++++ b/bindings/python/rgbmatrix/core.pyx
+@@ -2,6 +2,7 @@
+ 
+ from libcpp cimport bool
+ from libc.stdint cimport uint8_t, uint32_t, uintptr_t
++from libc.stdlib cimport malloc, free
+ import cython
+ 
+ cdef extern from "Python.h":
+@@ -59,8 +60,9 @@ cdef class Canvas:
+ 
+         buffer = get_pillow_buffer(image_capsule)
+ 
+-        for col in range(max(0, -xstart), min(width, frame_width - xstart)):
+-            for row in range(max(0, -ystart), min(height, frame_height - ystart)):
++        # Row-major: walks both the image and the bitplane buffer sequentially.
++        for row in range(max(0, -ystart), min(height, frame_height - ystart)):
++            for col in range(max(0, -xstart), min(width, frame_width - xstart)):
+                 pixel = buffer[row][col]
+                 r = (pixel ) & 0xFF
+                 g = (pixel >> 8) & 0xFF
+@@ -86,6 +88,41 @@ cdef class FrameCanvas(Canvas):
+     def SetPixel(self, int x, int y, uint8_t red, uint8_t green, uint8_t blue):
+         (<cppinc.FrameCanvas*>self._getCanvas()).SetPixel(x, y, red, green, blue)
+ 
++    @cython.boundscheck(False)
++    @cython.wraparound(False)
++    def SetPixelsPillow(self, int xstart, int ystart, int width, int height, object image_capsule):
++        # Same result as Canvas.SetPixelsPillow(), but hands each image row
++        # to the C++ bulk FrameCanvas::SetPixels() instead of calling the
++        # virtual SetPixel() once per pixel.
++        cdef cppinc.FrameCanvas* my_canvas = <cppinc.FrameCanvas*>self._getCanvas()
++        cdef int col_start = max(0, -xstart)
++        cdef int col_end = min(width, my_canvas.width() - xstart)
++        cdef int row_start = max(0, -ystart)
++        cdef int row_end = min(height, my_canvas.height() - ystart)
++        cdef int row, col, pixel
++        cdef int *src
++        cdef cppinc.Color *line
++        cdef int **buffer
++
++        if col_end <= col_start or row_end <= row_start:
++            return
++        buffer = get_pillow_buffer(image_capsule)
++        line = <cppinc.Color*>malloc((col_end - col_start) * sizeof(cppinc.Color))
++        if line == NULL:
++            raise MemoryError()
++        try:
++            for row in range(row_start, row_end):
++                src = buffer[row]
++                for col in range(col_start, col_end):
++                    pixel = src[col]
++                    line[col - col_start].r = pixel & 0xFF
++                    line[col - col_start].g = (pixel >> 8) & 0xFF
++                    line[col - col_start].b = (pixel >> 16) & 0xFF
++                my_canvas.SetPixels(xstart + col_start, ystart + row,
++                                    col_end - col_start, 1, line)
++        finally:
++            free(line)
++
+ 
+     property width:
+         def __get__(self): return (<cppinc.FrameCanvas*>self._getCanvas()).width()
+diff --git a/bindings/python/rgbmatrix/cppinc.pxd b/bindings/python/rgbmatrix/cppinc.pxd
+index 8bec241..314332d 100644
+--- a/bindings/python/rgbmatrix/cppinc.pxd
++++ b/bindings/python/rgbmatrix/cppinc.pxd
+@@ -25,6 +25,7 @@ cdef extern from "led-matrix.h" namespace "rgb_matrix":
+         FrameCanvas *SwapOnVSync(FrameCanvas*, uint8_t)
+ 
+     cdef cppclass FrameCanvas(Canvas):
++        void SetPixels(int, int, int, int, Color*) nogil
+         bool SetPWMBits(uint8_t)
+         uint8_t pwmbits()
+         void SetBrightness(uint8_t)
+diff --git a/lib/framebuffer.cc b/lib/framebuffer.cc
+index 36d138b..aee62ca 100644
+--- a/lib/framebuffer.cc
++++ b/lib/framebuffer.cc
+@@ -807,11 +807,60 @@ void Framebuffer::SetPixel(int x, int y, uint8_t r, uint8_t g, uint8_t b) {
+   }
+ }
+ 
++// Bulk version of SetPixel(); produces exactly the same bitplane content.
++// Faster because it hoists the per-pixel work out of the loop: the color
++// mapping becomes one 256-entry table built per call (each channel maps
++// independently through the same function), the pixel designators of a row
++// are contiguous in the PixelDesignatorMap, and the bit-plane loop is
++// branchless (the color bits are effectively random, so the branches in
++// SetPixel() mispredict a lot).
+ void Framebuffer::SetPixels(int x, int y, int width, int height, Color *colors) {
+-  for (int iy = 0; iy < height; ++iy) {
+-    for (int ix = 0; ix < width; ++ix) {
+-      SetPixel(x + ix, y + iy, colors->r, colors->g, colors->b);
+-      ++colors;
++  PixelDesignatorMap *const mapper = *shared_mapper_;
++  const int ix_start = std::max(0, -x);
++  const int ix_end = std::min(width, mapper->width() - x);
++  const int iy_start = std::max(0, -y);
++  const int iy_end = std::min(height, mapper->height() - y);
++  if (ix_start >= ix_end || iy_start >= iy_end) return;
++
++  // Common case (luminance correction, no inversion): use the precomputed
++  // table directly; otherwise build one. Cheap enough to do per call, which
++  // matters for callers that send one row at a time.
++  uint16_t local_map[256];
++  const uint16_t *color_map;
++  if (do_luminance_correct_ && !inverse_color_) {
++    color_map = ColorLookupTable::GetLookup(brightness_).color;
++  } else {
++    for (int c = 0; c < 256; ++c) {
++      uint16_t unused1, unused2;
++      MapColors(c, 0, 0, &local_map[c], &unused1, &unused2);
++    }
++    color_map = local_map;
++  }
++
++  const int min_bit_plane = kBitPlanes - pwm_bits_;
++  gpio_bits_t *const plane_start = bitplane_buffer_ + columns_ * min_bit_plane;
++  for (int iy = iy_start; iy < iy_end; ++iy) {
++    const Color *c = colors + iy * width + ix_start;
++    const PixelDesignator *designator = mapper->get(x + ix_start, y + iy);
++    for (int ix = ix_start; ix < ix_end; ++ix, ++c, ++designator) {
++      const long pos = designator->gpio_word;
++      if (pos < 0) continue;  // non-used pixel marker.
++      const uint16_t red = color_map[c->r];
++      const uint16_t green = color_map[c->g];
++      const uint16_t blue = color_map[c->b];
++      const gpio_bits_t r_bits = designator->r_bit;
++      const gpio_bits_t g_bits = designator->g_bit;
++      const gpio_bits_t b_bits = designator->b_bit;
++      const gpio_bits_t designator_mask = designator->mask;
++      gpio_bits_t *bits = plane_start + pos;
++      for (int plane = min_bit_plane; plane < kBitPlanes; ++plane) {
++        const gpio_bits_t color_bits =
++          (r_bits & -(gpio_bits_t)((red >> plane) & 1))
++          | (g_bits & -(gpio_bits_t)((green >> plane) & 1))
++          | (b_bits & -(gpio_bits_t)((blue >> plane) & 1));
++        *bits = (*bits & designator_mask) | color_bits;
++        bits += columns_;
++      }
+     }
+   }
+ }

requirements.txt

@@ -1,5 +1,5 @@
 # LEDMatrix Core Dependencies
-# Compatible with Python 3.10, 3.11, 3.12, and 3.13
+# Compatible with Python 3.11, 3.12 and 3.13; CI tests 3.11 and 3.13
 # Tested on Raspbian OS 12 (Bookworm) and 13 (Trixie)
 
 # Image processing

run.py

@@ -14,6 +14,14 @@ project_dir = os.path.dirname(os.path.abspath(__file__))
 if project_dir not in sys.path:
     sys.path.insert(0, project_dir)
 
+# Under systemd the watchdog clock is already running, and start-up (plugin
+# loads, initial updates) takes far longer than the render loop's limit. Widen
+# it before anything slow is imported; the render loop narrows it again once
+# its first frame is on the panel. A no-op outside systemd. Standard library
+# only -- see src/display_watchdog.py.
+from src import display_watchdog
+display_watchdog.watchdog.begin_startup()
+
 # Parse command-line arguments BEFORE any imports
 parser = argparse.ArgumentParser(description='LEDMatrix Display Controller')
 parser.add_argument('-e', '--emulator', action='store_true',

schema/manifest_schema.json

@@ -149,6 +149,11 @@
       },
       "description": "Array of display mode names this plugin provides"
     },
+    "vegas_participation": {
+      "type": "string",
+      "enum": ["scroll", "pause", "exclude"],
+      "description": "How this plugin takes part in Vegas mode by default: 'scroll' (its content scrolls by), 'pause' (the scroll stops for its turn and display() draws it full screen) or 'exclude' (left out). A user's per-plugin vegas_participation setting overrides it. Omit it to derive the participation from get_vegas_display_mode() / get_vegas_content_type(). Cores before 3.8.0 ignore it."
+    },
     "api_requirements": {
       "type": "array",
       "items": {

scripts/README.md

@@ -34,11 +34,14 @@ display; **diagnostic** — run by hand on a Pi when something is wrong.
 | `frame_soak.py` | diagnostic | Soaks a running display and reports how often frames reached the panel late (docs/SCROLL_PERFORMANCE.md) |
 | `install_dependencies_apt.py` | keep | Dependency installer that tries apt packages first, then pip (installer Step 7, plugin loader) |
 | `install_plugin_dependencies.sh` | diagnostic | Installs plugin requirements by hand when the automatic install fails |
+| `plugin_api_usage.py` | dev-only | Scans core, the plugin monorepo and the registry's third-party plugins for callers of every `@deprecated` core method; its output is [docs/DEPRECATIONS_3.8.md](../docs/DEPRECATIONS_3.8.md) |
 | `prove_security.py` | keep | Security property checks run by pre-commit |
 | `render_bench.py` | diagnostic | Benchmarks the render loop against the panel's real refresh rate on a synthetic strip |
 | `render_plugin.py` | dev-only | Runs a plugin's `update()` + `display()` and saves the frame as a PNG |
+| `reset_web_password.py` | keep | Turns the optional web login off when the password is lost (`sudo python3 scripts/reset_web_password.py`; docs/WEB_INTERFACE_GUIDE.md) |
 | `run_plugin_tests.py` | dev-only | Discovers and runs plugin test suites |
 | `scroll_speeds.py` | keep | Shows and tries the scroll speeds your panel can display cleanly |
+| `sports_drift_report.py` | keep | Counts the different bodies of each method across the nine scoreboards in a `ledmatrix-plugins` checkout (report-only CI job; docs/SPORTS_UNIFICATION.md) |
 | `troubleshoot_captive_portal.sh` | diagnostic | Troubleshoots captive-portal WiFi setup after you can SSH back in |
 | `update_plugin_repos.py` | dev-only | Pulls the latest `ledmatrix-plugins` monorepo |
 | `verify_installation.sh` | diagnostic | Checks that an installation completed correctly |

scripts/build_css.py

@@ -0,0 +1,239 @@
+#!/usr/bin/env python3
+"""Build the web UI's Tailwind CSS with the pinned standalone Tailwind CLI.
+
+The generated files are committed, so the Pi never builds anything. Run this
+on a dev machine (or let CI run it) after changing a template, a static JS
+file, or anything under ``web_interface/tailwind/``:
+
+    python3 scripts/build_css.py            # rebuild the committed CSS
+    python3 scripts/build_css.py --check    # exit 1 if the committed CSS is stale
+
+No Node or npm: the script downloads Tailwind's standalone CLI (a single
+executable) for this OS and CPU from the Tailwind GitHub release, checks it
+against the SHA-256 pinned below, and caches it outside the repo
+(``$LEDMATRIX_TAILWIND_CACHE``, else the per-user cache directory).
+
+Outputs (see ``BUILDS``):
+
+- ``web_interface/static/v3/tailwind.css``: the utilities the templates and
+  static JS use. Linked before ``app.css`` in ``base.html``.
+- ``web_interface/static/v3/plugin-frame.css``: preflight plus a broad set of
+  common utilities, for plugin ``web_ui/`` fragments served in an iframe.
+  Their markup lives in plugin repos, so it can't be scanned; the safelist in
+  ``plugin-frame.config.js`` stands in for it.
+
+To move to a new Tailwind v3 release, change ``TAILWIND_VERSION`` and every
+hash in ``TAILWIND_ASSETS`` (the release's ``sha256sums.txt``, or the digests
+from ``gh api repos/tailwindlabs/tailwindcss/releases/tags/<tag>``), rebuild,
+and review the diff of the generated CSS.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import os
+import platform
+import shutil
+import stat
+import subprocess  # nosec B404 - list-form argv only, no shell  # nosemgrep
+import sys
+import tempfile
+import urllib.request
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+TAILWIND_DIR = PROJECT_ROOT / "web_interface" / "tailwind"
+STATIC_V3 = PROJECT_ROOT / "web_interface" / "static" / "v3"
+
+TAILWIND_VERSION = "3.4.19"
+
+# asset name -> SHA-256, from the v3.4.19 release.
+TAILWIND_ASSETS = {
+    "tailwindcss-linux-arm64": "e5b2d27694daa80cc52ec29553ba2c6bd43d86bd51a9d633ed24058b9c05a676",
+    "tailwindcss-linux-armv7": "e3610b109a64720295e1c00a18dd2d6d79d3cddc618219aa0830de97a55429a4",
+    "tailwindcss-linux-x64": "4af3198c015616ea7d6617974ec3d70d987ecc00c1ca8463b0a30fd65cc7c06e",
+    "tailwindcss-macos-arm64": "7fdeb00818b6214a337383063282b2361ecb08bbc08f8c8a7ba97ee1e2eaa4fe",
+    "tailwindcss-macos-x64": "a597f407e0f1f03535731f5b42f1576a8152cb5fffc2f38e754722bc0c280045",
+    "tailwindcss-windows-arm64.exe": "f2b6b999747aa0ae31999d59db117b1ba1e4e15e17675d7108e30aac4b680686",
+    "tailwindcss-windows-x64.exe": "a15158c4c5e0e7a75f7229bfe4986fe7710d2edc468b6f96c8981f78ab211347",
+}
+
+DOWNLOAD_URL = (
+    "https://github.com/tailwindlabs/tailwindcss/releases/download/v{version}/{asset}"
+)
+
+# (input CSS, config, output) -- all relative to the project root.
+BUILDS = (
+    (
+        "web_interface/tailwind/app.input.css",
+        "web_interface/tailwind/tailwind.config.js",
+        "web_interface/static/v3/tailwind.css",
+    ),
+    (
+        "web_interface/tailwind/plugin-frame.input.css",
+        "web_interface/tailwind/plugin-frame.config.js",
+        "web_interface/static/v3/plugin-frame.css",
+    ),
+)
+
+
+def asset_name() -> str:
+    """The release asset for this OS and CPU."""
+    system = platform.system()
+    machine = platform.machine().lower()
+    if machine in ("x86_64", "amd64"):
+        arch = "x64"
+    elif machine in ("aarch64", "arm64"):
+        arch = "arm64"
+    elif machine.startswith("armv7") or machine == "armv8l":
+        arch = "armv7"
+    else:
+        raise SystemExit(f"No standalone Tailwind CLI for CPU {machine!r}.")
+
+    if system == "Linux":
+        name = f"tailwindcss-linux-{arch}"
+    elif system == "Darwin":
+        name = f"tailwindcss-macos-{arch}"
+    elif system == "Windows":
+        name = f"tailwindcss-windows-{arch}.exe"
+    else:
+        raise SystemExit(f"No standalone Tailwind CLI for {system!r}.")
+    if name not in TAILWIND_ASSETS:
+        raise SystemExit(f"No standalone Tailwind CLI for {system} {machine}.")
+    return name
+
+
+def cache_dir() -> Path:
+    override = os.environ.get("LEDMATRIX_TAILWIND_CACHE")
+    if override:
+        return Path(override)
+    if platform.system() == "Windows":
+        base = Path(os.environ.get("LOCALAPPDATA", Path.home() / "AppData" / "Local"))
+    elif platform.system() == "Darwin":
+        base = Path.home() / "Library" / "Caches"
+    else:
+        base = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache"))
+    return base / "ledmatrix" / "tailwindcss"
+
+
+def sha256_of(path: Path) -> str:
+    digest = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(1 << 20), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def ensure_cli() -> Path:
+    """Path to the verified CLI, downloading it on first use."""
+    name = asset_name()
+    expected = TAILWIND_ASSETS[name]
+    target = cache_dir() / f"v{TAILWIND_VERSION}" / name
+
+    if target.is_file():
+        if sha256_of(target) == expected:
+            return target
+        print(f"Cached {target} fails its SHA-256 check; downloading it again.")
+        target.unlink()
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    url = DOWNLOAD_URL.format(version=TAILWIND_VERSION, asset=name)
+    if not url.startswith("https://"):
+        raise SystemExit(f"Refusing to download the Tailwind CLI over a non-https URL: {url}")
+    print(f"Downloading Tailwind CLI v{TAILWIND_VERSION} ({name})...")
+    fd, tmp_name = tempfile.mkstemp(dir=target.parent, prefix=".download-")
+    tmp = Path(tmp_name)
+    try:
+        with os.fdopen(fd, "wb") as out, urllib.request.urlopen(url, timeout=120) as resp:  # nosec B310 - https only, checked above
+            shutil.copyfileobj(resp, out)
+        actual = sha256_of(tmp)
+        if actual != expected:
+            raise SystemExit(
+                f"SHA-256 mismatch for {url}\n  expected {expected}\n  got      {actual}"
+            )
+        tmp.chmod(tmp.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+        os.replace(tmp, target)
+    finally:
+        if tmp.exists():
+            tmp.unlink()
+    return target
+
+
+def run_build(
+    cli: Path, input_css: str, config: str, output: Path, work_dir: Path
+) -> None:
+    # The minifier's rule merging depends on the input file's line endings,
+    # so a Windows checkout (core.autocrlf, CRLF) would build different bytes
+    # than CI's Linux one and --check would fail. Feed the CLI an LF copy.
+    # (Content files' line endings don't matter; @import isn't used, so the
+    # copy's location doesn't either.)
+    lf_input = work_dir / (Path(input_css).name)
+    lf_input.write_bytes(
+        (PROJECT_ROOT / input_css).read_bytes().replace(b"\r\n", b"\n")
+    )
+    cmd = [
+        str(cli),
+        "--input", str(lf_input),
+        "--config", str(PROJECT_ROOT / config),
+        "--output", str(output),
+        "--minify",
+    ]
+    # NODE_ENV=production and no browserslist lookup keep the output the
+    # same on every machine.
+    env = dict(os.environ, NODE_ENV="production", BROWSERSLIST_IGNORE_OLD_DATA="1")
+    # The CLI path is computed here (cache dir + pinned asset name) and the
+    # binary was SHA-256-verified by ensure_cli(); env is os.environ plus two
+    # fixed values.
+    result = subprocess.run(cmd, cwd=PROJECT_ROOT, env=env, capture_output=True, text=True)  # nosec B603 - list-form argv, no shell  # nosemgrep
+    if result.returncode != 0:
+        sys.stderr.write(result.stdout + result.stderr)
+        raise SystemExit(f"Tailwind build failed for {input_css}")
+    # The CLI writes without a trailing newline; add one so the committed
+    # file is a well-formed text file and editors leave it alone.
+    text = output.read_text(encoding="utf-8").replace("\r\n", "\n")
+    if not text.endswith("\n"):
+        text += "\n"
+    output.write_bytes(text.encode("utf-8"))
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="build to a temp dir and fail if the committed CSS differs",
+    )
+    args = parser.parse_args(argv)
+
+    cli = ensure_cli()
+    stale = []
+    with tempfile.TemporaryDirectory(prefix="ledmatrix-css-") as tmp:
+        for input_css, config, output in BUILDS:
+            committed = PROJECT_ROOT / output
+            built = Path(tmp) / Path(output).name if args.check else committed
+            run_build(cli, input_css, config, built, Path(tmp))
+            if args.check:
+                old = (
+                    committed.read_bytes().replace(b"\r\n", b"\n")
+                    if committed.is_file()
+                    else None
+                )
+                if old != built.read_bytes():
+                    stale.append(output)
+            else:
+                print(f"Wrote {output} ({committed.stat().st_size:,} bytes)")
+
+    if stale:
+        print(
+            "The committed CSS is out of date: " + ", ".join(stale) + "\n"
+            "Run `python3 scripts/build_css.py` and commit the result."
+        )
+        return 1
+    if args.check:
+        print("Committed CSS is up to date.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/check_plugin.py

@@ -72,6 +72,7 @@ from src.plugin_system.testing.harness import (  # noqa: E402
 from src.plugin_system.testing.sizes import (  # noqa: E402
     parse_size_token, resolve_test_sizes, safe_mode_filename, size_label,
 )
+from src.plugin_system.testing.vegas import check_plugin_vegas_elements  # noqa: E402
 
 logger = get_logger("[Check Plugin]")
 
@@ -193,6 +194,24 @@ def check_one(plugin_id: str, search_dirs: List[str], sizes, mock_data: Dict,
 
         all_run_results.extend(results)
 
+    # Live Vegas elements, for a plugin that has them: checked once, at the
+    # first size, with the base config.
+    width, height = effective_sizes[0]
+    try:
+        vegas = check_plugin_vegas_elements(
+            plugin_id, plugin_dir, full_config, effective_mock_data, width, height,
+            run_update=effective_run_update)
+    except Exception as exc:  # noqa: BLE001 - one plugin must not end an --all run
+        all_run_results.append(RenderResult(
+            plugin_id, width, height, "vegas elements",
+            error=f"the element check itself failed: {exc!r}"))
+        return all_run_results
+    if vegas.implemented:
+        all_run_results.append(RenderResult(
+            plugin_id, width, height, "vegas elements",
+            error="; ".join(vegas.errors) or None,
+            notes=[f"{vegas.elements} element(s), {vegas.live} live"] + vegas.warnings))
+
     return all_run_results
 
 
@@ -236,6 +255,8 @@ def print_report(all_results: Dict[str, List[RenderResult]]) -> bool:
                               f" controller skips the mode")
                 else:
                     status, detail = "FAIL", ""
+            if r.notes:
+                detail += f" ({'; '.join(r.notes)})"
             print(f"  [{status}] {r.size_label:>7}  {r.mode}{detail}")
     print()
     return everything_ok

scripts/check_system_compatibility.sh

@@ -53,26 +53,35 @@ else
 fi
 echo ""
 
-# Check OS version
+# Check OS version. The supported releases come from the same library the
+# installer uses, so the two cannot disagree.
 echo "2. Checking Operating System Version..."
 echo "---------------------------------------"
-if [ -f /etc/os-release ]; then
-    . /etc/os-release
-    echo "OS: $PRETTY_NAME"
-    echo "Version ID: ${VERSION_ID:-unknown}"
-    
-    # first_time_install.sh refuses anything but Raspberry Pi OS / Debian 13
-    # (Trixie), so anything else is an error here too, not a warning.
-    if [[ "$ID" == "raspbian" ]] || [[ "$ID" == "debian" ]]; then
-        if [ "${VERSION_ID:-0}" = "13" ]; then
-            print_success "Detected Debian 13 Trixie - supported"
-        elif [ "${VERSION_ID:-0}" = "12" ]; then
-            print_error "Debian 12 Bookworm is not supported - the installer requires Raspberry Pi OS Lite (Trixie), Debian 13"
-        else
-            print_error "Debian/Raspbian ${VERSION_ID:-unknown} is not supported - the installer requires Raspberry Pi OS Lite (Trixie), Debian 13"
-        fi
+OS_LIB="$(cd "$(dirname "$0")" && pwd)/install/lib_os.sh"
+OS_LIB_LOADED=0
+OS_RELEASE=""
+if [ -f "$OS_LIB" ]; then
+    # shellcheck source=scripts/install/lib_os.sh
+    . "$OS_LIB"
+    OS_LIB_LOADED=1
+fi
+
+if [ "$OS_LIB_LOADED" = "0" ]; then
+    print_error "$OS_LIB is missing - download LEDMatrix again"
+elif [ -r "$LM_OS_RELEASE_FILE" ]; then
+    OS_ID=$(lm_os_field ID)
+    OS_VERSION_ID=$(lm_os_field VERSION_ID)
+    echo "OS: $(lm_os_field PRETTY_NAME)"
+    echo "Version ID: ${OS_VERSION_ID:-unknown}"
+
+    # first_time_install.sh refuses anything else, so this is an error here
+    # too, not a warning.
+    if OS_RELEASE=$(lm_os_release); then
+        print_success "Detected $(lm_release_label "$OS_RELEASE") - supported"
+    elif [[ "$OS_ID" == "raspbian" ]] || [[ "$OS_ID" == "debian" ]]; then
+        print_error "Debian/Raspbian ${OS_VERSION_ID:-unknown} is not supported - the installer requires Raspberry Pi OS Lite, Trixie (Debian 13) or Bookworm (Debian 12)"
     else
-        print_error "${ID:-unknown} is not supported - the installer requires Raspberry Pi OS Lite (Trixie), Debian 13"
+        print_error "${OS_ID:-unknown} is not supported - the installer requires Raspberry Pi OS Lite, Trixie (Debian 13) or Bookworm (Debian 12)"
     fi
 else
     print_error "Could not detect OS version"
@@ -92,7 +101,7 @@ if [ "$KERNEL_MAJOR" -ge "6" ]; then
     print_success "Kernel version is compatible (6.x or newer)"
     
     if [ "$KERNEL_MAJOR" -eq "6" ] && [ "$KERNEL_MINOR" -ge "12" ]; then
-        print_success "Running latest Trixie kernel (6.12 LTS)"
+        print_success "Running a 6.12 LTS or newer kernel"
     fi
 elif [ "$KERNEL_MAJOR" -eq "5" ] && [ "$KERNEL_MINOR" -ge "10" ]; then
     print_success "Kernel version is compatible (5.10+)"
@@ -104,25 +113,34 @@ echo ""
 # Check Python version
 echo "4. Checking Python Version..."
 echo "-----------------------------"
-if command -v python3 >/dev/null 2>&1; then
-    PYTHON_VERSION=$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}")')
-    PYTHON_MAJOR=$(python3 -c 'import sys; print(sys.version_info.major)')
-    PYTHON_MINOR=$(python3 -c 'import sys; print(sys.version_info.minor)')
-    
+if [ "$OS_LIB_LOADED" = "1" ] && command -v python3 >/dev/null 2>&1; then
+    PYTHON_VERSION=$(python3 -c 'import sys; print("%d.%d.%d" % sys.version_info[:3])')
+    PYTHON_MINOR_VERSION=$(lm_python_version) || PYTHON_MINOR_VERSION=""
+    PYTHON_RANGE="3.${LM_PYTHON_MIN_MINOR}-3.${LM_PYTHON_MAX_MINOR}"
+
     echo "Python: $PYTHON_VERSION"
-    
-    if [ "$PYTHON_MAJOR" -eq "3" ]; then
-        if [ "$PYTHON_MINOR" -ge "10" ] && [ "$PYTHON_MINOR" -le "13" ]; then
-            print_success "Python version is supported (3.10-3.13)"
-        elif [ "$PYTHON_MINOR" -ge "14" ]; then
-            print_warning "Python 3.${PYTHON_MINOR} is very new - some packages may not be compatible yet"
-        else
-            # Pillow 12 and the pinned test tools need 3.10+, so this won't install.
-            print_error "Python 3.${PYTHON_MINOR} is too old - Python 3.10+ is required"
-        fi
-    else
-        print_error "Python 2.x detected - Python 3.10+ is required"
+
+    case "$(lm_python_check "$PYTHON_MINOR_VERSION")" in
+        ok)
+            print_success "Python version is supported ($PYTHON_RANGE)"
+            ;;
+        too-old)
+            # The rgbmatrix bindings declare requires-python >=3.11, so the
+            # display cannot be built on anything older.
+            print_error "Python $PYTHON_MINOR_VERSION is too old - Python 3.${LM_PYTHON_MIN_MINOR}+ is required"
+            ;;
+        too-new)
+            print_warning "Python $PYTHON_MINOR_VERSION is newer than LEDMatrix has been tested with ($PYTHON_RANGE)"
+            ;;
+        *)
+            print_warning "Could not read the Python version"
+            ;;
+    esac
+    if [ -n "$OS_RELEASE" ] && [ "$PYTHON_MINOR_VERSION" != "$(lm_release_python "$OS_RELEASE")" ]; then
+        print_warning "$(lm_release_label "$OS_RELEASE") ships Python $(lm_release_python "$OS_RELEASE"), but python3 runs $PYTHON_MINOR_VERSION"
     fi
+elif command -v python3 >/dev/null 2>&1; then
+    print_warning "Cannot check the Python version without $OS_LIB"
 else
     print_error "Python 3 not found - installation required"
 fi
@@ -268,6 +286,22 @@ if command -v ping >/dev/null 2>&1; then
 else
     print_warning "Ping command not available - cannot verify network"
 fi
+
+# WiFi setup from the web page and the LEDMatrix-Setup hotspot drive
+# NetworkManager, the default on both Bookworm and Trixie.
+if [ "$OS_LIB_LOADED" = "1" ]; then
+    case "$(lm_network_stack)" in
+        networkmanager)
+            print_success "NetworkManager manages the network (needed for WiFi setup)"
+            ;;
+        dhcpcd)
+            print_warning "dhcpcd manages the network - WiFi setup from the web page and the setup hotspot need NetworkManager (sudo raspi-config -> Advanced Options -> Network Config)"
+            ;;
+        *)
+            print_warning "Could not tell which service manages the network - WiFi setup from the web page needs NetworkManager"
+            ;;
+    esac
+fi
 echo ""
 
 # Print summary

scripts/dev_server.py

@@ -200,12 +200,21 @@ def api_plugin_defaults(plugin_id):
     return jsonify({'defaults': defaults})
 
 
+#: /api/render "vegas" values: the plugin's block of the Vegas strip, built
+#: from its live elements (falling back to its Vegas content, as the ticker
+#: does) or from its ordinary Vegas content only.
+VEGAS_VIEWS = ('live', 'plain')
+
+
 def _render_once(plugin_id, plugin_dir, manifest, config, mock_data, width, height,
-                 skip_update):
+                 skip_update, vegas=None):
     """Render one plugin at one size. Returns the /api/render response dict.
 
     A fresh plugin instance per call, mirroring the safety harness, so sizes
-    never share state.
+    never share state. With ``vegas`` set ('live' or 'plain') the image is the
+    plugin's block of the Vegas strip instead of its display(), laid out by
+    the ticker's own code (src/plugin_system/testing/vegas.py), and the
+    response lists where each live element sits in it.
     """
     from src.plugin_system.testing import VisualTestDisplayManager, MockCacheManager, MockPluginManager
     from src.plugin_system.plugin_loader import PluginLoader
@@ -243,6 +252,10 @@ def _render_once(plugin_id, plugin_dir, manifest, config, mock_data, width, heig
             logger.warning("update() raised for plugin %s", plugin_id, exc_info=True)
             warnings.append(f"update() raised: {type(e).__name__} — see server log")
 
+    if vegas:
+        return _vegas_response(plugin_id, plugin_instance, display_manager, vegas,
+                               start_time, errors, warnings)
+
     # Run display()
     try:
         plugin_instance.display(force_clear=True)
@@ -262,6 +275,40 @@ def _render_once(plugin_id, plugin_dir, manifest, config, mock_data, width, heig
     }
 
 
+def _vegas_response(plugin_id, plugin_instance, display_manager, vegas, start_time,
+                    errors, warnings):
+    """The /api/render response for the Vegas strip view."""
+    import base64
+    import io
+
+    from src.plugin_system.testing.vegas import render_vegas_strip
+
+    block, layout = None, []
+    try:
+        block, layout = render_vegas_strip(plugin_instance, plugin_id, display_manager,
+                                           live=(vegas == 'live'))
+    except Exception as e:
+        logger.warning("Vegas render raised for plugin %s", plugin_id, exc_info=True)
+        errors.append(f"Vegas render raised: {type(e).__name__} — see server log")
+    if block is None:
+        if not errors:
+            errors.append("The plugin has no Vegas content")
+        block = display_manager.image
+    elif vegas == 'live' and not layout:
+        warnings.append("No live elements: this is the plugin's ordinary Vegas content")
+    buffer = io.BytesIO()
+    block.convert('RGB').save(buffer, format='PNG')
+    return {
+        'image': 'data:image/png;base64,' + base64.b64encode(buffer.getvalue()).decode('ascii'),
+        'width': block.width,
+        'height': block.height,
+        'render_time_ms': round((time.time() - start_time) * 1000, 1),
+        'errors': errors,
+        'warnings': warnings,
+        'live_elements': [{'key': key, 'x': x, 'width': width} for x, key, width in layout],
+    }
+
+
 def _trusted_plugin_dir(plugin_dir: Path) -> Optional[Path]:
     """Re-derive a plugin directory from the search dirs' own listings.
 
@@ -333,6 +380,10 @@ def api_render():
     if not (MIN_HEIGHT <= height <= MAX_HEIGHT):
         return jsonify({'error': f'height must be between {MIN_HEIGHT} and {MAX_HEIGHT}'}), 400
 
+    vegas = data.get('vegas') or None
+    if vegas is not None and vegas not in VEGAS_VIEWS:
+        return jsonify({'error': f'vegas must be one of {", ".join(VEGAS_VIEWS)}'}), 400
+
     try:
         plugin_dir, manifest, config, mock_data, skip_update = _parse_render_request(data)
     except LookupError:
@@ -345,7 +396,7 @@ def api_render():
 
     try:
         result = _render_once(data['plugin_id'], plugin_dir, manifest, config,
-                              mock_data, width, height, skip_update)
+                              mock_data, width, height, skip_update, vegas=vegas)
     except Exception:
         app.logger.exception('plugin load failed during render')
         return jsonify({'error': 'Failed to load plugin; see server log'}), 500

scripts/frame_soak.py

@@ -9,7 +9,10 @@ reports the difference. Nothing is stopped, restarted or drawn.
     python3 scripts/frame_soak.py
 
     # the same with the web preview open (the preview's PNG encodes are one of
-    # the things that used to make the render loop miss refreshes)
+    # the things that used to make the render loop miss refreshes). An open
+    # preview is encoded at most once a second; through 3.8.0 it was up to
+    # five times, so a --preview run from before that change is not comparable
+    # with one from after it
     python3 scripts/frame_soak.py --preview
 
     # quick look at the totals since the service started
@@ -27,14 +30,24 @@ What the numbers mean
 late frames     frames that reached the panel one or more refreshes after they
                 were due -- the panel showed the previous frame again, which on
                 a moving strip is a visible hitch. This is the pass/fail number.
-freezes         gaps of 250ms+ inside a scroll: recomposes, plugin handovers,
+freezes         gaps of 250ms+ inside a scroll: recomposes, plugin handovers
+                the display controller does not tag (see handover gaps),
                 blocking calls on the render thread. Reported, not failed on,
                 since some are handovers between plugins rather than faults.
+handover gaps   the same length of gap where the display controller had just
+                started a screen's turn (also the same mode's again): its
+                first display() drawing. Counted here instead of under
+                freezes. Stats from a service older than this count have no
+                such line, and their freezes include these, so do not
+                compare freeze counts across that change.
 blit            copying the frame into the matrix canvas (rgbmatrix SetImage).
                 Grows with width x height x pwm_bits.
 wait            blocked in SwapOnVSync, i.e. slack before the refresh.
 work            everything else between two frames: drawing, scrolling, and
                 waiting for the GIL.
+after work      frames presented straight after tagged render-thread work
+                (Vegas strip extensions, live-element patches), with their own
+                late rate. Shown only when something tagged its work.
 """
 from __future__ import annotations
 
@@ -55,7 +68,8 @@ from src.common.frame_timing import (  # noqa: E402
 )
 
 #: Touched by the web UI while someone has the preview open; a fresh marker
-#: puts the display service's snapshot writer at full rate. Same path as
+#: puts the display service's snapshot writer at the viewer rate
+#: (snapshot_policy.VIEWER_INTERVAL). Same path as
 #: DisplayManager._viewer_marker_path.
 VIEWER_MARKER = "/tmp/led_matrix_preview_viewer"  # nosec B108 - fixed path shared with the service
 
@@ -126,6 +140,56 @@ def _edge(index: int, bucket_ms: float):
     return round((index + 1) * bucket_ms, 2)
 
 
+def op_rows(totals: Dict[str, Any]) -> Dict[str, Dict[str, Any]]:
+    """Per kind of noted render-thread work: how often its frame was late.
+
+    A kind's frames are the ones presented straight after that work ran (see
+    "Operations" in src/common/frame_timing.py). Stats from a recorder that
+    predates the counters have none, and give an empty table.
+    """
+    frames = totals.get("op_frames") or {}
+    late = totals.get("late_op_frames") or {}
+    freezes = totals.get("op_freezes") or {}
+    moved = totals.get("op_bytes") or {}
+    rows = {}
+    for kind in sorted(set(frames) | set(freezes)):
+        count = frames.get(kind, 0)
+        if not count and not freezes.get(kind, 0):
+            continue
+        rows[kind] = {
+            "frames": count,
+            "late": late.get(kind, 0),
+            "late_pct": (round(100.0 * late.get(kind, 0) / count, 3)
+                         if count else None),
+            "freezes": freezes.get(kind, 0),
+            "bytes": moved.get(kind, 0),
+        }
+    return rows
+
+
+def gc_window(before: Dict[str, Any], after: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """Garbage collection over the run, or None from a service without the
+    monitor. The counters are cumulative since the service started, so they
+    are differenced like the totals; the longest is since the start."""
+    ga = after.get("gc")
+    if not ga:
+        return None
+    gb = before.get("gc") or {}
+    def minus(key):
+        return [a - b for a, b in zip(ga.get(key, []),
+                                      gb.get(key) or [0] * len(ga.get(key, [])))]
+    seconds = minus("seconds")
+    return {
+        "collections": minus("collections"),
+        "ms": [round(x * 1000.0, 1) for x in seconds],
+        "long_pauses": ga.get("long_pauses", 0) - gb.get("long_pauses", 0),
+        "long_ms": round((ga.get("long_seconds", 0.0)
+                          - gb.get("long_seconds", 0.0)) * 1000.0, 1),
+        "threshold_ms": ga.get("threshold_ms"),
+        "max_ms_since_start": ga.get("max_ms"),
+    }
+
+
 def build_report(before, after, preview: bool) -> Dict[str, Any]:
     delta = diff(before, after)
     totals = delta["totals"]
@@ -155,10 +219,15 @@ def build_report(before, after, preview: bool) -> Dict[str, Any]:
         "freezes": totals["freezes"],
         "freezes_per_hour": round(totals["freezes"] / hours, 1) if hours else None,
         "freeze_seconds": round(totals["freeze_seconds"], 2),
+        # None from a service that predates the count: its handovers are
+        # among the freezes above.
+        "handover_freezes": totals.get("handover_freezes"),
         "worst_interval_ms": (round(totals["worst_interval_ms"], 1)
                               if totals["worst_interval_ms"] else None),
         "timing_ms": {name: percentiles(h, bucket_ms)
                       for name, h in delta["histograms"].items()},
+        "ops": op_rows(totals),
+        "gc": gc_window(before, after),
     }
     # The rate the panel held while rendering: the typical frame's interval
     # per refresh held. A few percent under the idle rate is normal (the Pi is
@@ -209,6 +278,16 @@ def print_report(report: Dict[str, Any], limit: float) -> None:
     if report["freezes"]:
         print("                   by length: " + ", ".join(
             f"{k}: {v}" for k, v in report["freeze_by"].items()))
+    if report.get("handover_freezes") is not None:
+        print(f"Handover gaps      {report['handover_freezes']}"
+              "  >=250ms before a new screen's first frame; not in the freezes")
+    gc_stats = report.get("gc")
+    if gc_stats:
+        counts, ms = gc_stats["collections"], gc_stats["ms"]
+        print(f"Garbage collection gen0/1/2 {counts[0]}/{counts[1]}/{counts[2]}"
+              f" ({ms[0]}/{ms[1]}/{ms[2]} ms)  >={gc_stats['threshold_ms']:g}ms: "
+              f"{gc_stats['long_pauses']} ({gc_stats['long_ms']} ms)"
+              f"  longest since start {gc_stats['max_ms_since_start']} ms")
     print()
     print(f"{'ms':<18}{'p50':>8}{'p95':>8}{'p99':>8}{'max':>8}")
     for name in ("blit", "wait", "work", "interval_per_hold"):
@@ -216,6 +295,17 @@ def print_report(report: Dict[str, Any], limit: float) -> None:
         print(f"{name:<18}" + "".join(f"{str(row.get(k, '-')):>8}"
                                         for k in ("p50", "p95", "p99", "max")))
     print()
+    ops = report.get("ops") or {}
+    if ops:
+        # Frames presented straight after render-thread work of each kind. A
+        # late rate well above the overall one points at that work.
+        print(f"{'after work':<18}{'frames':>8}{'late':>8}{'late %':>8}"
+              f"{'freezes':>9}{'MB moved':>10}")
+        for kind, row in ops.items():
+            pct = "-" if row["late_pct"] is None else f"{row['late_pct']:g}"
+            print(f"{kind:<18}{row['frames']:>8}{row['late']:>8}{pct:>8}"
+                  f"{row['freezes']:>9}{row['bytes'] / 1e6:>10.2f}")
+        print()
     if report["late_pct"] is None:
         print("RESULT  nothing scrolled - no verdict")
     elif not locked(report, limit):

scripts/install/README.md

@@ -5,11 +5,18 @@ This directory contains scripts for installing and configuring the LEDMatrix sys
 ## Scripts
 
 - **`one-shot-install.sh`** - Single-command installer; clones the
-  repo, checks prerequisites, then runs `first_time_install.sh`.
-  Invoked via `curl ... | bash` from the project root README.
+  repo, checks out the newest release (or `main` with
+  `LEDMATRIX_CHANNEL=beta`), checks prerequisites, then runs
+  `first_time_install.sh`. Invoked via `curl ... | bash` from the project
+  root README. Re-running it never moves a checkout to an older version.
 - **`install_service.sh`** - Installs, enables and starts the display
   service (`ledmatrix.service`), the web interface service
-  (`ledmatrix-web.service`) and the update-verify units (systemd)
+  (`ledmatrix-web.service`) and the update-verify units (systemd), and
+  installs `/usr/local/sbin/ledmatrix-refresh-units`
+- **`ledmatrix_refresh_units.py`** - Not run from here: `install_service.sh`
+  installs a root-owned copy as `/usr/local/sbin/ledmatrix-refresh-units`,
+  which updates run through sudo to install changed units (and the
+  automatic update's rollback, with `--restore`, to put them back)
 - **`install_web_service.sh`** - Installs only the web interface service
   and the update-verify units (systemd)
 - **`install_wifi_monitor.sh`** - Installs the WiFi monitor daemon service
@@ -34,6 +41,9 @@ Libraries (sourced, not run):
   script that renders a unit from `systemd/*.service`
 - **`lib_lowmem.sh`** - Build-job sizing and temporary swap for the C++
   build on low-memory Pis (`first_time_install.sh` Step 6)
+- **`lib_os.sh`** - Which releases (Bookworm, Trixie) and Python versions
+  (3.11-3.13) the installer accepts, and which service runs the network;
+  shared by `first_time_install.sh` and `scripts/check_system_compatibility.sh`
 
 ## Usage
 

scripts/install/configure_web_sudo.sh

@@ -138,6 +138,8 @@ echo "- View system logs via journalctl"
 echo "- Reboot and shutdown the system"
 echo "- Remove plugin directories (for update/uninstall when root-owned files block deletion)"
 echo "- Install plugin/base requirements.txt as root (so ledmatrix.service can see them)"
+echo "- Install the LEDMatrix systemd units an update changed, and restore them on rollback"
+echo "  (/usr/local/sbin/ledmatrix-refresh-units, installed by install_service.sh)"
 echo ""
 
 # Ask for confirmation

scripts/install/install_service.sh

@@ -143,6 +143,30 @@ for VERIFY_UNIT in ledmatrix-update-verify.service ledmatrix-update-verify.path;
     fi
 done
 
+# The helper updates run (through sudo, see lib_sudoers.sh) to install these
+# same units when a new version changes their templates, and to put the old
+# ones back if the automatic update rolls back. Root-owned and outside the
+# checkout, so the web user who owns the checkout cannot change what sudo runs.
+# Not fatal: without it, updates leave the units for the next reinstall.
+REFRESH_UNITS_SRC="$PROJECT_ROOT_DIR/scripts/install/ledmatrix_refresh_units.py"
+REFRESH_UNITS_DEST=/usr/local/sbin/ledmatrix-refresh-units
+if [ -f "$REFRESH_UNITS_SRC" ]; then
+    if sudo install -D -o root -g root -m 0755 "$REFRESH_UNITS_SRC" "$REFRESH_UNITS_DEST"; then
+        echo "Installed $REFRESH_UNITS_DEST (lets updates refresh these units)"
+    else
+        echo "WARNING: could not install $REFRESH_UNITS_DEST; updates will not refresh the systemd units" >&2
+    fi
+fi
+# The units above are copied from mktemp files, which are 0600. 0644 is what
+# first_time_install.sh (Step 8.1) sets, and lets the web interface compare
+# them with the templates after an update without root.
+for INSTALLED_UNIT in ledmatrix.service ledmatrix-web.service \
+        ledmatrix-update-verify.service ledmatrix-update-verify.path; do
+    if [ -f "/etc/systemd/system/$INSTALLED_UNIT" ]; then
+        sudo chmod 644 "/etc/systemd/system/$INSTALLED_UNIT" || true
+    fi
+done
+
 echo "Reloading systemd daemon for web service..."
 sudo systemctl daemon-reload
 

scripts/install/ledmatrix_refresh_units.py

@@ -0,0 +1,451 @@
+#!/usr/bin/python3 -I
+"""Refresh the installed LEDMatrix systemd units from the checkout's templates.
+
+Installed by scripts/install/install_service.sh as a root-owned copy,
+/usr/local/sbin/ledmatrix-refresh-units, and granted to the web interface's
+user by /etc/sudoers.d/ledmatrix_web (scripts/install/lib_sudoers.sh) with
+exactly two command lines:
+
+    ledmatrix-refresh-units              (no arguments)
+    ledmatrix-refresh-units --restore
+
+An update (Update Code, or the weekly automatic update) pulls new unit
+templates into systemd/, but the units systemd runs are the copies in
+/etc/systemd/system, which only the installer used to write. So a setting
+added to a template -- the render-loop watchdog, a memory limit -- never
+reached a device that was already installed. After an update the web
+interface runs this, and the next restart picks the new units up.
+
+* **No arguments:** render each installed unit from systemd/<unit> exactly as
+  install_service.sh does (__PROJECT_ROOT_DIR__ and __USER__ replaced
+  literally), and install the ones whose content differs (comments and blank
+  lines aside, as src/startup_validator.py compares them), then
+  ``systemctl daemon-reload``. The units replaced are saved first, so the
+  automatic update's rollback can put them back.
+* ``--restore``: put back the units the last refresh replaced, and
+  daemon-reload. Nothing saved means nothing to do.
+* ``--check``: print the units that would change, one per line. Needs no
+  root and changes nothing.
+
+What it trusts, and why. It takes no other input: the project directory and
+the web interface's user come from the installed, root-owned
+ledmatrix.service and ledmatrix-web.service, not from the caller, and sudo
+strips the caller's environment (``-I`` ignores the PYTHON* variables too).
+It only replaces units that are already installed, only the four
+install_service.sh installs, and only with a rendering that keeps each unit's
+User= (root for the display, the web user for the others) and
+WorkingDirectory=. The templates are files the web user can edit -- but so is
+run.py, which ledmatrix.service already runs as root, so a template grants
+nothing that user did not have; the checks keep a damaged or hostile template
+from changing who a unit runs as, and keep this from reading anything but a
+regular file under the checkout's systemd/ folder.
+
+Standard library only, and no imports from the checkout: the installed copy
+must not run code the web user can change.
+"""
+import json
+import os
+import re
+import stat
+import subprocess  # nosec B404 - fixed argv, no shell  # nosemgrep
+import sys
+import tempfile
+
+SYSTEMD_DIR = '/etc/systemd/system'
+#: Root-only: the units the last refresh replaced, for --restore.
+BACKUP_DIR = '/var/lib/ledmatrix/unit-backup'
+MANIFEST = 'manifest.json'
+INSTALLED_PATH = '/usr/local/sbin/ledmatrix-refresh-units'
+
+DISPLAY_UNIT = 'ledmatrix.service'
+WEB_UNIT = 'ledmatrix-web.service'
+VERIFY_SERVICE = 'ledmatrix-update-verify.service'
+VERIFY_PATH = 'ledmatrix-update-verify.path'
+#: What install_service.sh installs, in its order. Nothing else is touched.
+UNITS = (DISPLAY_UNIT, WEB_UNIT, VERIFY_SERVICE, VERIFY_PATH)
+
+MAX_TEMPLATE_BYTES = 64 * 1024
+_USER_RE = re.compile(r'^[a-z_][a-z0-9_-]{0,31}$')
+#: systemd expands % specifiers, and a quote, backslash or line break would
+#: be reinterpreted in a unit file (src/auto_update_setup.py refuses the same).
+#: (On Windows, where the tests also run, a backslash is the path separator.)
+_UNSAFE_PATH_CHARS = set('%"') | ({'\\'} if os.sep == '/' else set())
+
+EXIT_OK = 0
+EXIT_FAILED = 1
+EXIT_USAGE = 2
+
+
+class RefreshError(Exception):
+    """Why the units were left alone, in words for the web interface's log."""
+
+
+class UnitsUnreadable(RefreshError):
+    """An installed unit is not readable by this (unprivileged) user.
+
+    install_service.sh used to leave units mode 0600 (first_time_install.sh's
+    Step 8.1 makes them 0644), so ``--check`` as the web user cannot always
+    tell; the root helper itself can.
+    """
+
+
+def directive_values(text, key):
+    """Every value of ``key=`` in a unit's text, in order (systemd allows spaces around ``=``)."""
+    return [m.group(1).strip() for m in re.finditer(rf'^[ \t]*{key}[ \t]*=(.*)$', text or '', re.M)]
+
+
+def layout_problem(text, section, keys):
+    """What would make ``directive_values`` misread the unit as systemd reads it, or None.
+
+    A ``User=`` inside a backslash-continued line is part of the line before,
+    and one under [Unit] is ignored, so either could pass a check that systemd
+    then does not apply. Neither appears in the shipped templates.
+    """
+    current = None
+    for raw in (text or '').splitlines():
+        line = raw.strip()
+        if not line or line.startswith(('#', ';')):
+            continue
+        if line.endswith('\\'):
+            return 'continues a line with a backslash'
+        if line.startswith('[') and line.endswith(']'):
+            current = line[1:-1]
+            continue
+        key = line.split('=', 1)[0].strip()
+        if key in keys and current != section:
+            return f'sets {key}= outside [{section}]'
+    return None
+
+
+def unit_body(text):
+    """A unit's meaningful lines in order: no comments, no blank lines.
+
+    The same comparison src/startup_validator.py uses for its drift warning,
+    so what this refreshes is exactly what that warns about.
+    """
+    lines = []
+    for line in (text or '').splitlines():
+        line = line.strip()
+        if line and not line.startswith('#'):
+            lines.append(line)
+    return '\n'.join(lines)
+
+
+def render(template, project_root, user):
+    """install_service.sh's ``sed "s|__PROJECT_ROOT_DIR__|...|g; s|__USER__|...|g"``."""
+    return template.replace('__PROJECT_ROOT_DIR__', project_root).replace('__USER__', user)
+
+
+def _read_regular(path, limit=MAX_TEMPLATE_BYTES, dir_fd=None):
+    """A regular file's text, never through a symlink, a FIFO or a device."""
+    flags = os.O_RDONLY | getattr(os, 'O_NOFOLLOW', 0) | getattr(os, 'O_NONBLOCK', 0)
+    kwargs = {'dir_fd': dir_fd} if dir_fd is not None else {}
+    fd = os.open(path, flags, **kwargs)
+    try:
+        info = os.fstat(fd)
+        if not stat.S_ISREG(info.st_mode):
+            raise RefreshError(f'{path} is not a regular file')
+        if info.st_size > limit:
+            raise RefreshError(f'{path} is larger than {limit} bytes')
+        data = b''
+        while True:
+            chunk = os.read(fd, limit + 1 - len(data))
+            if not chunk:
+                break
+            data += chunk
+            if len(data) > limit:
+                raise RefreshError(f'{path} is larger than {limit} bytes')
+    finally:
+        os.close(fd)
+    if b'\0' in data:
+        raise RefreshError(f'{path} is not a text file')
+    try:
+        return data.decode('utf-8')
+    except UnicodeDecodeError as e:
+        raise RefreshError(f'{path} is not UTF-8') from e
+
+
+def _read_installed(systemd_dir, name):
+    path = os.path.join(systemd_dir, name)
+    try:
+        with open(path, 'r', encoding='utf-8') as f:
+            return f.read()
+    except FileNotFoundError:
+        return None
+    except PermissionError as e:
+        raise UnitsUnreadable(f'cannot read the installed {name}: {e}') from e
+    except (OSError, UnicodeDecodeError) as e:
+        raise RefreshError(f'cannot read the installed {name}: {e}') from e
+
+
+def _lookup_user(user):
+    try:
+        import pwd
+    except ImportError:  # not a POSIX host (the tests on Windows)
+        return True
+    try:
+        pwd.getpwnam(user)
+        return True
+    except KeyError:
+        return False
+
+
+class Refresher:
+    def __init__(self, systemd_dir=SYSTEMD_DIR, backup_dir=BACKUP_DIR, run=subprocess.run,
+                 is_root=None, user_exists=_lookup_user, log=None):
+        self.systemd_dir = systemd_dir
+        self.backup_dir = backup_dir
+        self.run = run
+        self.is_root = is_root or (lambda: hasattr(os, 'geteuid') and os.geteuid() == 0)
+        self.user_exists = user_exists
+        self.log = log or (lambda msg: print(msg, flush=True))
+
+    # -- what the installed units say -------------------------------------
+
+    def context(self, installed):
+        """(project root, web user) from the installed, root-owned units."""
+        display = installed.get(DISPLAY_UNIT)
+        if display is None:
+            raise RefreshError(f'{DISPLAY_UNIT} is not installed; run scripts/install/install_service.sh')
+        roots = directive_values(display, 'WorkingDirectory')
+        if len(roots) != 1:
+            raise RefreshError(f'the installed {DISPLAY_UNIT} does not name one WorkingDirectory')
+        root = roots[0]
+        if (not os.path.isabs(root) or any(ch in _UNSAFE_PATH_CHARS or ord(ch) < 32 for ch in root)
+                or os.path.normpath(root) != root):
+            raise RefreshError(f'the installed {DISPLAY_UNIT} runs from {root!r}, which cannot be used')
+        if not os.path.isdir(root):
+            raise RefreshError(f'{root} (the installed {DISPLAY_UNIT} WorkingDirectory) does not exist')
+
+        user = None
+        web = installed.get(WEB_UNIT)
+        if web is not None:
+            users = directive_values(web, 'User')
+            user = users[0] if len(users) == 1 else ('root' if not users else None)
+            if user is None or not _USER_RE.match(user) or not self.user_exists(user):
+                raise RefreshError(f'the installed {WEB_UNIT} runs as an account that cannot be used')
+            if directive_values(web, 'WorkingDirectory') != [root]:
+                raise RefreshError(f'the installed {WEB_UNIT} and {DISPLAY_UNIT} run from different folders')
+        return root, user
+
+    @staticmethod
+    def expected_user(name, web_user):
+        return 'root' if name == DISPLAY_UNIT else web_user
+
+    def _template(self, root, name):
+        """systemd/<name> under the checkout, as a regular file, never via a symlink."""
+        dir_flags = os.O_RDONLY | getattr(os, 'O_DIRECTORY', 0) | getattr(os, 'O_NOFOLLOW', 0)
+        if os.open in getattr(os, 'supports_dir_fd', set()):
+            try:
+                dfd = os.open(os.path.join(root, 'systemd'), dir_flags)
+            except OSError as e:
+                raise RefreshError(f'cannot open {root}/systemd: {e}') from e
+            try:
+                return _read_regular(name, dir_fd=dfd)
+            except FileNotFoundError:
+                return None
+            except OSError as e:
+                raise RefreshError(f'cannot read systemd/{name}: {e}') from e
+            finally:
+                os.close(dfd)
+        path = os.path.join(root, 'systemd', name)
+        if os.path.islink(os.path.join(root, 'systemd')):
+            raise RefreshError(f'{root}/systemd is a symlink')
+        try:
+            return _read_regular(path)
+        except FileNotFoundError:
+            return None
+        except OSError as e:
+            raise RefreshError(f'cannot read systemd/{name}: {e}') from e
+
+    def _validate(self, name, rendered, root, user):
+        problem = layout_problem(rendered, 'Service', ('User', 'WorkingDirectory'))
+        if problem:
+            raise RefreshError(f'systemd/{name} {problem}; refusing to install it')
+        if directive_values(rendered, 'User') != [user]:
+            raise RefreshError(f'systemd/{name} would not run as {user}; refusing to install it')
+        if directive_values(rendered, 'WorkingDirectory') != [root]:
+            raise RefreshError(f'systemd/{name} would not run from {root}; refusing to install it')
+
+    def plan(self):
+        """{unit: (installed text, new text)} for every installed unit that would change.
+
+        Raises RefreshError, and so changes nothing, if any unit cannot be
+        rendered safely: four units refreshed as a set or not at all.
+        """
+        installed = {name: _read_installed(self.systemd_dir, name) for name in UNITS}
+        root, web_user = self.context(installed)
+        changes = {}
+        for name in UNITS:
+            current = installed[name]
+            if current is None:
+                continue  # never installed here: installing is the installer's job
+            user = self.expected_user(name, web_user)
+            if user is None:
+                continue  # the web unit is not installed, so neither is its user
+            template = self._template(root, name)
+            if template is None:
+                continue  # a version without this unit leaves the installed one alone
+            rendered = render(template, root, user)
+            # A path unit runs nothing itself; what matters is what it starts.
+            if name.endswith('.service'):
+                self._validate(name, rendered, root, user)
+            else:
+                self._validate_path(name, rendered)
+            if unit_body(rendered) != unit_body(current):
+                changes[name] = (current, rendered)
+        return changes
+
+    def _validate_path(self, name, rendered):
+        problem = layout_problem(rendered, 'Path', ('Unit',))
+        if problem:
+            raise RefreshError(f'systemd/{name} {problem}; refusing to install it')
+        if directive_values(rendered, 'Unit') != [VERIFY_SERVICE]:
+            raise RefreshError(f'systemd/{name} does not start {VERIFY_SERVICE}; refusing to install it')
+        if directive_values(rendered, 'User'):
+            raise RefreshError(f'systemd/{name} sets User=; refusing to install it')
+
+    # -- writing ------------------------------------------------------------
+
+    def _write_unit(self, name, text):
+        fd, tmp = tempfile.mkstemp(dir=self.systemd_dir, prefix=f'.{name}.')
+        try:
+            with os.fdopen(fd, 'w', encoding='utf-8', newline='\n') as f:
+                f.write(text)
+            os.chmod(tmp, 0o644)
+            os.replace(tmp, os.path.join(self.systemd_dir, name))
+        except BaseException:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+            raise
+
+    def _backup_dir(self):
+        """The backup folder, created root-only; refused if it is not a plain folder."""
+        os.makedirs(os.path.dirname(self.backup_dir), mode=0o755, exist_ok=True)
+        try:
+            os.mkdir(self.backup_dir, 0o700)
+        except FileExistsError:
+            pass
+        info = os.lstat(self.backup_dir)
+        if not stat.S_ISDIR(info.st_mode):
+            raise RefreshError(f'{self.backup_dir} is not a folder')
+        if hasattr(os, 'geteuid') and info.st_uid != os.geteuid():
+            raise RefreshError(f'{self.backup_dir} is not owned by root')
+        return self.backup_dir
+
+    def _clear_backup(self, folder):
+        for entry in os.listdir(folder):
+            path = os.path.join(folder, entry)
+            if os.path.isfile(path) or os.path.islink(path):
+                os.unlink(path)
+
+    def _systemctl(self, *args):
+        result = self.run(['systemctl', *args], capture_output=True, text=True, timeout=60)
+        if result.returncode != 0:
+            raise RefreshError(f'"systemctl {" ".join(args)}" failed: '
+                               f'{(result.stderr or result.stdout or "").strip()}')
+
+    def _restart_path_unit_if_active(self, names):
+        """A rewritten path unit watches the old path until it is restarted."""
+        if VERIFY_PATH not in names:
+            return
+        state = self.run(['systemctl', 'is-active', VERIFY_PATH], capture_output=True, text=True, timeout=30)
+        if (state.stdout or '').strip() == 'active':
+            self._systemctl('restart', VERIFY_PATH)
+
+    def refresh(self):
+        if not self.is_root():
+            raise RefreshError('must run as root (sudo)')
+        changes = self.plan()
+        folder = self._backup_dir()
+        # Always reset: the backup belongs to this refresh, so a --restore
+        # after an update that changed nothing restores nothing.
+        self._clear_backup(folder)
+        if not changes:
+            self.log('units: up to date')
+            return []
+        for name, (current, _) in changes.items():
+            with open(os.path.join(folder, name), 'w', encoding='utf-8', newline='\n') as f:
+                f.write(current)
+        with open(os.path.join(folder, MANIFEST), 'w', encoding='utf-8') as f:
+            json.dump({'units': sorted(changes)}, f)
+        try:
+            for name, (_, rendered) in changes.items():
+                self._write_unit(name, rendered)
+            self._systemctl('daemon-reload')
+        except BaseException:
+            # A failed refresh is reported as a failure, so the update records
+            # no units_refreshed and a rollback would not --restore. Put the
+            # replaced units back now, rather than leave a half-written set
+            # under the old code.
+            self._undo(changes, folder)
+            raise
+        self._restart_path_unit_if_active(changes)
+        self.log('units refreshed: ' + ' '.join(sorted(changes)))
+        return sorted(changes)
+
+    def _undo(self, changes, folder):
+        """Best effort: reinstall the units a failed refresh replaced."""
+        undone = True
+        for name, (current, _) in changes.items():
+            try:
+                self._write_unit(name, current)
+            except OSError as e:
+                undone = False
+                self.log(f'units: could not put back {name}: {e}')
+        try:
+            self.run(['systemctl', 'daemon-reload'], capture_output=True, text=True, timeout=60)
+        except (OSError, subprocess.SubprocessError) as e:
+            self.log(f'units: daemon-reload after putting units back failed: {e}')
+        if undone:
+            # Nothing is left to restore; keep the backup only if a unit could
+            # not be put back, so a manual --restore still can.
+            self._clear_backup(folder)
+
+    def restore(self):
+        if not self.is_root():
+            raise RefreshError('must run as root (sudo)')
+        folder = self._backup_dir()
+        try:
+            manifest = json.loads(_read_regular(os.path.join(folder, MANIFEST)))
+        except FileNotFoundError:
+            self.log('units: nothing to restore')
+            return []
+        names = [n for n in (manifest or {}).get('units', []) if n in UNITS]
+        for name in names:
+            self._write_unit(name, _read_regular(os.path.join(folder, name)))
+        self._systemctl('daemon-reload')
+        self._restart_path_unit_if_active(names)
+        self._clear_backup(folder)
+        self.log('units restored: ' + ' '.join(names))
+        return names
+
+
+def main(argv, refresher=None):
+    args = argv[1:]
+    if args not in ([], ['--restore'], ['--check']):
+        print('usage: ledmatrix-refresh-units [--restore | --check]', file=sys.stderr)
+        return EXIT_USAGE
+    refresher = refresher or Refresher()
+    try:
+        if args == ['--check']:
+            for name in sorted(refresher.plan()):
+                print(name)
+        elif args == ['--restore']:
+            refresher.restore()
+        else:
+            refresher.refresh()
+    except (RefreshError, OSError, subprocess.SubprocessError, ValueError) as e:
+        print(f'ledmatrix-refresh-units: {e}', file=sys.stderr)
+        return EXIT_FAILED
+    return EXIT_OK
+
+
+if __name__ == '__main__':
+    # Only as the installed program: sudo already sets a secure PATH, and
+    # this pins the one systemctl comes from. (Not in main(), which the
+    # tests call in-process.)
+    os.environ['PATH'] = '/usr/sbin:/usr/bin:/sbin:/bin'
+    sys.exit(main(sys.argv))

scripts/install/lib_os.sh

@@ -0,0 +1,138 @@
+#!/bin/bash
+# Which operating systems and Python versions LEDMatrix installs on.
+#
+# Sourced by first_time_install.sh and scripts/check_system_compatibility.sh,
+# so the installer and the compatibility checker cannot disagree about what
+# is supported. Pure functions: nothing here installs, changes or exits --
+# the callers decide what to do with the answers.
+#
+# Supported (Lite, no desktop):
+#   Raspberry Pi OS / Debian 12 "Bookworm" -- Python 3.11
+#   Raspberry Pi OS / Debian 13 "Trixie"   -- Python 3.13
+#
+# Everything the installer asks apt for (python3-pip, python3-venv,
+# python-dev-is-python3, python3-pil, python3-pil.imagetk, build-essential,
+# python3-setuptools, python3-wheel, cmake, ninja-build, git, curl, wget,
+# unzip, and hostapd, dnsmasq, network-manager for WiFi setup) has the same
+# name on both releases. Both ship a pip (23.0.1 and 25.1.1) that is PEP 668
+# "externally managed" and accepts --break-system-packages, and a cmake (3.25
+# and 3.31) new enough for the rgbmatrix build (3.22). So no step needs a
+# per-release branch today; if one ever does, the release name comes from
+# lm_os_release below.
+
+# Test hook: the os-release file to read.
+LM_OS_RELEASE_FILE="${LM_OS_RELEASE_FILE:-/etc/os-release}"
+
+# Oldest and newest python3 minor versions the installer accepts. 3.11 is
+# Bookworm's, and also the floor of the rgbmatrix bindings (requires-python
+# >=3.11 in rpi-rgb-led-matrix-master/pyproject.toml); 3.13 is Trixie's.
+LM_PYTHON_MIN_MINOR=11
+LM_PYTHON_MAX_MINOR=13
+
+# lm_os_field KEY -- one value from os-release with its quotes removed; empty
+# when the key or the file is missing. Parsed rather than sourced so that
+# os-release's ID, VERSION and friends do not land in the caller's variables.
+lm_os_field() {
+    [ -r "$LM_OS_RELEASE_FILE" ] || return 0
+    sed -n "/^$1=/{s/^$1=//;s/^[\"']//;s/[\"']\$//;p;q;}" "$LM_OS_RELEASE_FILE"
+}
+
+# lm_os_release -- print "bookworm" or "trixie" and succeed on a supported
+# release; print nothing and fail on anything else. VERSION_ID decides; the
+# codename is used only when VERSION_ID is missing.
+lm_os_release() {
+    local id version
+    id=$(lm_os_field ID)
+    version=$(lm_os_field VERSION_ID)
+    [ -n "$version" ] || version=$(lm_os_field VERSION_CODENAME)
+    case "$id" in
+        raspbian|debian) ;;
+        *) return 1 ;;
+    esac
+    case "$version" in
+        12|bookworm) echo bookworm ;;
+        13|trixie) echo trixie ;;
+        *) return 1 ;;
+    esac
+}
+
+# lm_release_label RELEASE -- how to name a release to a person.
+lm_release_label() {
+    case "$1" in
+        bookworm) echo "Debian 12 (Bookworm)" ;;
+        trixie) echo "Debian 13 (Trixie)" ;;
+        *) echo "$1" ;;
+    esac
+}
+
+# lm_release_python RELEASE -- the python3 version a release ships, e.g. 3.11.
+lm_release_python() {
+    case "$1" in
+        bookworm) echo 3.11 ;;
+        trixie) echo 3.13 ;;
+        *) return 1 ;;
+    esac
+}
+
+# lm_python_version [PYTHON] -- "3.11" and so on for python3 (or PYTHON);
+# prints nothing and fails when it cannot be run.
+lm_python_version() {
+    "${1:-python3}" -c 'import sys; print("%d.%d" % sys.version_info[:2])' 2>/dev/null
+}
+
+# lm_python_check VERSION -- print "ok", "too-old", "too-new" or "unknown"
+# for a version such as 3.11. Always succeeds, so it is safe under set -e.
+lm_python_check() {
+    local major minor
+    major=${1%%.*}
+    minor=${1#*.}
+    minor=${minor%%.*}
+    case "$major:$minor" in
+        *[!0-9:]*|:*|*:) echo unknown; return 0 ;;
+    esac
+    if [ "$major" -lt 3 ] || { [ "$major" -eq 3 ] && [ "$minor" -lt "$LM_PYTHON_MIN_MINOR" ]; }; then
+        echo too-old
+    elif [ "$major" -gt 3 ] || [ "$minor" -gt "$LM_PYTHON_MAX_MINOR" ]; then
+        echo too-new
+    else
+        echo ok
+    fi
+}
+
+# lm_network_stack -- which service runs the network: "networkmanager",
+# "dhcpcd" or "unknown". Raspberry Pi OS uses NetworkManager on both Bookworm
+# and Trixie; dhcpcd appears when someone switched back to it in raspi-config.
+lm_network_stack() {
+    if systemctl is-active --quiet NetworkManager 2>/dev/null; then
+        echo networkmanager
+    elif systemctl is-active --quiet dhcpcd 2>/dev/null; then
+        echo dhcpcd
+    else
+        echo unknown
+    fi
+}
+
+# lm_print_dhcpcd_advice -- the explanation for a Pi running dhcpcd. WiFi
+# setup from the web page and the LEDMatrix-Setup hotspot both drive
+# NetworkManager (nmcli). The installer does not switch the network stack
+# itself: doing that over SSH can cut the connection it is running on.
+lm_print_dhcpcd_advice() {
+    echo "⚠ This Pi manages its network with dhcpcd, not NetworkManager."
+    echo "  LEDMatrix installs and the display works, but choosing a WiFi network"
+    echo "  from the web page and the LEDMatrix-Setup hotspot both need NetworkManager."
+    echo "  To switch (with a keyboard and screen attached, or over Ethernet):"
+    echo "    sudo raspi-config  ->  Advanced Options  ->  Network Config  ->  NetworkManager"
+    echo "  then reboot."
+}
+
+# lm_print_supported_os_help -- what to do on an unsupported system.
+lm_print_supported_os_help() {
+    echo "LEDMatrix needs Raspberry Pi OS Lite: Trixie (Debian 13) or Bookworm (Debian 12)."
+    echo ""
+    echo "To install Raspberry Pi OS Lite:"
+    echo "  1. Download Raspberry Pi Imager from: https://www.raspberrypi.com/software/"
+    echo "  2. Choose 'Raspberry Pi OS Lite (64-bit)'. Trixie is the current version and"
+    echo "     is recommended; Bookworm (listed as Legacy) also works"
+    echo "  3. Flash it to the SD card"
+    echo "  4. Boot the Pi and run this script again"
+}

scripts/install/lib_sudoers.sh

@@ -10,6 +10,11 @@
 #
 # Add or remove a grant here and nowhere else.
 
+# Root-owned copy of scripts/install/ledmatrix_refresh_units.py, installed by
+# install_service.sh. Outside the checkout on purpose: the web user owns the
+# checkout, so a granted file inside it could be rewritten and run as root.
+LEDMATRIX_REFRESH_UNITS_PATH=/usr/local/sbin/ledmatrix-refresh-units
+
 # web_sudoers_rules WEB_USER PROJECT_ROOT SYSTEMCTL_PATH BASH_PATH REBOOT_PATH POWEROFF_PATH JOURNALCTL_PATH
 #
 # Print the ledmatrix_web sudoers rules to stdout.
@@ -58,6 +63,10 @@ $WEB_USER ALL=(ALL) NOPASSWD: $BASH_PATH $PROJECT_ROOT/scripts/fix_perms/safe_pl
 # Install a requirements.txt as root via vetted helper, so packages are visible
 # to root-run ledmatrix.service (not just the web interface's own user).
 $WEB_USER ALL=(ALL) NOPASSWD: $BASH_PATH $PROJECT_ROOT/scripts/fix_perms/safe_pip_install.sh *
+# After an update, install the new systemd units (no arguments: "" allows none)
+# and, on the automatic update's rollback, put the previous ones back.
+$WEB_USER ALL=(ALL) NOPASSWD: $LEDMATRIX_REFRESH_UNITS_PATH ""
+$WEB_USER ALL=(ALL) NOPASSWD: $LEDMATRIX_REFRESH_UNITS_PATH --restore
 EOF
     if [ -n "$JOURNALCTL_PATH" ]; then
         cat << EOF

scripts/install/one-shot-install.sh

@@ -3,6 +3,10 @@
 # LED Matrix One-Shot Installation Script
 # This script provides a single-command installation experience
 # Usage: curl -fsSL https://raw.githubusercontent.com/ChuckBuilds/LEDMatrix/main/scripts/install/one-shot-install.sh | bash
+#
+# A new install runs the newest release (the stable update channel). For the
+# newest code from main instead (the beta channel), set LEDMATRIX_CHANNEL=beta:
+#   curl -fsSL https://raw.githubusercontent.com/ChuckBuilds/LEDMatrix/main/scripts/install/one-shot-install.sh | LEDMATRIX_CHANNEL=beta bash
 
 set -Eeuo pipefail
 
@@ -205,6 +209,114 @@ check_sudo() {
     print_success "Sudo access confirmed"
 }
 
+# --- release checkout helpers ------------------------------------------------
+# Which version an install runs. The rules are web_interface/update_channel.py's,
+# so the installer and the web interface's updates agree:
+#   stable (default)  the newest vX.Y.Z tag by semantic version; pre-releases
+#                     (v3.8.0-rc1), leading zeros and other tags are ignored
+#   beta              main, the newest code
+# Never backwards: an existing checkout moves to a release only when that
+# release contains its current commit (git merge-base --is-ancestor).
+# Never fatal: whatever goes wrong, the install carries on with the checkout
+# as it is.
+
+# Print "stable" or "beta": LEDMATRIX_CHANNEL when it is set, else the
+# existing install's auto_update.channel (CONFIG_FILE), else stable.
+_lm_channel() {
+    local config_file="${1:-}" value
+    value=$(printf '%s' "${LEDMATRIX_CHANNEL:-}" | tr '[:upper:]' '[:lower:]' | tr -d '[:space:]')
+    case "$value" in
+        stable|beta) printf '%s\n' "$value"; return 0 ;;
+        "") ;;
+        *) print_warning "LEDMATRIX_CHANNEL=${LEDMATRIX_CHANNEL} is not stable or beta; using stable" >&2
+           printf 'stable\n'; return 0 ;;
+    esac
+    if [ -n "$config_file" ] && [ -f "$config_file" ] && command -v python3 >/dev/null 2>&1; then
+        value=$(python3 - "$config_file" 2>/dev/null <<'PY' || true
+import json, sys
+try:
+    with open(sys.argv[1], encoding="utf-8") as f:
+        section = json.load(f).get("auto_update")
+    value = section.get("channel") if isinstance(section, dict) else None
+    print(value.strip().lower() if isinstance(value, str) else "")
+except Exception:
+    print("")
+PY
+)
+        if [ "$value" = "beta" ]; then
+            printf 'beta\n'
+            return 0
+        fi
+    fi
+    printf 'stable\n'
+}
+
+# Print the newest release tag of the repository in the current directory,
+# or nothing when it has none.
+_lm_newest_release_tag() {
+    git tag --list 'v*' 2>/dev/null \
+        | grep -E '^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$' \
+        | sort -t. -k1.2,1n -k2,2n -k3,3n \
+        | tail -n 1 || true
+}
+
+# A fresh clone (on main): move to the newest release unless beta was asked for.
+_lm_checkout_release_after_clone() {
+    local channel tag
+    channel=$(_lm_channel "")
+    if [ "$channel" = "beta" ]; then
+        print_success "Beta channel: installing the newest code from main"
+        return 0
+    fi
+    tag=$(_lm_newest_release_tag)
+    if [ -z "$tag" ]; then
+        print_warning "No release found; installing the newest code from main"
+        return 0
+    fi
+    if git -c advice.detachedHead=false checkout --quiet --detach "${tag}^{commit}"; then
+        print_success "Installing release $tag (stable channel)"
+    else
+        print_warning "Could not check out release $tag; installing the newest code from main"
+    fi
+    return 0
+}
+
+# An existing checkout: move it forward along its channel, never backwards.
+# Returns 1 when it should be updated the way it always was (a fast-forward
+# pull of its branch): beta, or stable on a branch newer than every release.
+_lm_update_existing_checkout() {
+    local channel tag head tag_sha
+    channel=$(_lm_channel "config/config.json")
+    if [ "$channel" = "beta" ]; then
+        return 1
+    fi
+    if ! git fetch --quiet --tags --force origin >/dev/null 2>&1; then
+        print_warning "Could not fetch release tags; keeping the current version"
+        return 0
+    fi
+    tag=$(_lm_newest_release_tag)
+    head=$(git rev-parse --verify --quiet HEAD 2>/dev/null || true)
+    if [ -n "$tag" ] && [ -n "$head" ] && git merge-base --is-ancestor "$head" "$tag" 2>/dev/null; then
+        tag_sha=$(git rev-parse --verify --quiet "${tag}^{commit}" 2>/dev/null || true)
+        if [ "$head" = "$tag_sha" ]; then
+            print_success "Already on the newest release, $tag"
+        elif git -c advice.detachedHead=false checkout --quiet --detach "${tag}^{commit}"; then
+            print_success "Updated to release $tag (stable channel)"
+        else
+            print_warning "Could not move to release $tag (local changes?); keeping the current version"
+        fi
+        return 0
+    fi
+    if git symbolic-ref --quiet HEAD >/dev/null 2>&1; then
+        # Newer than the newest release (or no release yet): follow the branch
+        # until a release includes this version, as updates do.
+        return 1
+    fi
+    print_success "This checkout is newer than the newest release${tag:+ ($tag)}; leaving it as it is"
+    return 0
+}
+# --- end release checkout helpers --------------------------------------------
+
 # Main installation function
 main() {
     print_step "LED Matrix One-Shot Installation"
@@ -292,7 +404,10 @@ main() {
             
             # Try to safely update current branch first (fast-forward only to avoid unintended merges)
             PULL_SUCCESS=false
-            if git pull --ff-only origin "$CURRENT_BRANCH" >/dev/null 2>&1; then
+            # Stable: the newest release, if it contains this version.
+            if _lm_update_existing_checkout; then
+                PULL_SUCCESS=true
+            elif git pull --ff-only origin "$CURRENT_BRANCH" >/dev/null 2>&1; then
                 print_success "Repository updated successfully (branch: $CURRENT_BRANCH)"
                 PULL_SUCCESS=true
             else
@@ -323,10 +438,12 @@ main() {
             rm -rf "$REPO_DIR"
             print_success "Cloning repository..."
             retry git clone "$REPO_URL" "$REPO_DIR"
+            (cd "$REPO_DIR" && _lm_checkout_release_after_clone) || print_warning "Could not choose a release; installing the newest code from main"
         fi
     else
         print_success "Cloning repository to $REPO_DIR..."
         retry git clone "$REPO_URL" "$REPO_DIR"
+        (cd "$REPO_DIR" && _lm_checkout_release_after_clone) || print_warning "Could not choose a release; installing the newest code from main"
     fi
     
     # Verify repository is accessible
@@ -397,6 +514,7 @@ main() {
         sudo -E env TMPDIR=/tmp LEDMATRIX_ASSUME_YES=1 \
             LEDMATRIX_APT_UPDATED="${LEDMATRIX_APT_UPDATED:-0}" \
             LEDMATRIX_AUTO_UPDATE="${LEDMATRIX_AUTO_UPDATE:-}" \
+            LEDMATRIX_CHANNEL="${LEDMATRIX_CHANNEL:-}" \
             bash ./first_time_install.sh -y </dev/null
     fi
     INSTALL_EXIT_CODE=$?

scripts/install_dependencies_apt.py

@@ -4,13 +4,14 @@ Alternative dependency installer that tries apt packages first,
 then falls back to pip with --break-system-packages
 """
 
+import re
 import subprocess
 import sys
 import tempfile
 import warnings
 from collections import deque
 from pathlib import Path
-from typing import List, Tuple
+from typing import Dict, List, Tuple
 
 # How many trailing lines of a failed command's output to keep for the
 # end-of-run failure summary. Keeps the root cause near the end of the log,
@@ -81,6 +82,8 @@ def install_via_pip(package_name: str) -> Tuple[bool, str]:
 
     Returns (success, output).
     """
+    # pip knows PIL as Pillow; the others are asked for by their own name.
+    package_name = _dist_name(package_name)
     print(f"Installing {package_name} via pip...")
     success, output = _run([
         sys.executable, '-m', 'pip', 'install',
@@ -99,26 +102,66 @@ IMPORT_NAME_MAP = {
     'freetype-py': 'freetype',
 }
 
-# Minimum versions that must be met for an already-installed package to count
-# as satisfied. Debian Bookworm's python3-freetype is 2.3.0, below the
-# freetype-py>=2.5.1 pin in requirements.txt, so an import-only check would
-# wrongly skip the pip upgrade.
-MIN_VERSIONS = {
-    'freetype-py': (2, 5, 1),
+# The packages above are keyed by what main() lists; these are the ones whose
+# pip distribution name differs from that key.
+DIST_NAME_MAP = {
+    'PIL': 'Pillow',
 }
 
+REQUIREMENTS_FILE = Path(__file__).resolve().parent.parent / 'web_interface' / 'requirements.txt'
+
+
+def _version_tuple(text: str) -> tuple:
+    parts = []
+    for part in text.split('.'):
+        digits = ''.join(ch for ch in part if ch.isdigit())
+        if not digits:
+            break
+        parts.append(int(digits))
+    return tuple(parts)
+
+
+def _requirement_floors(path: Path = REQUIREMENTS_FILE) -> Dict[str, tuple]:
+    """``>=`` floors from a requirements file, keyed by lower-cased name.
+
+    The apt copies of these packages are older than the pins on both
+    supported releases -- Bookworm ships Flask and Werkzeug 2.2.2, Pillow 9.4,
+    requests 2.28, psutil 5.9, pytz 2022.7 and freetype-py 2.3; Trixie ships
+    Flask 3.1.1, Werkzeug 3.1.3, Pillow 11.1 and requests 2.32 --
+    so a package that merely imports is not enough. Read from the file rather
+    than copied here so the two cannot drift.
+    """
+    floors: Dict[str, tuple] = {}
+    try:
+        lines = path.read_text(encoding='utf-8').splitlines()
+    except OSError:
+        return floors
+    for line in lines:
+        match = re.match(r'\s*([A-Za-z0-9][A-Za-z0-9._-]*)[^#]*?>=\s*([0-9][0-9.]*)', line)
+        if match:
+            floors[match.group(1).lower()] = _version_tuple(match.group(2))
+    return floors
+
+
+def _dist_name(package_name: str) -> str:
+    return DIST_NAME_MAP.get(package_name, package_name)
+
+
+def _minimum_version(package_name: str) -> tuple:
+    """The required floor for ``package_name``, or () when there is none."""
+    return MIN_VERSIONS.get(_dist_name(package_name).lower(), ())
+
+
+# Minimum versions that must be met for an already-installed package to count
+# as satisfied.
+MIN_VERSIONS = _requirement_floors()
+
 
 def _installed_version_tuple(dist_name: str) -> tuple:
     """Return the installed distribution version as an int tuple, or () if unknown."""
     try:
         from importlib.metadata import version
-        parts = []
-        for part in version(dist_name).split('.'):
-            digits = ''.join(ch for ch in part if ch.isdigit())
-            if not digits:
-                break
-            parts.append(int(digits))
-        return tuple(parts)
+        return _version_tuple(version(dist_name))
     except Exception:
         return ()
 
@@ -134,9 +177,9 @@ def check_package_installed(package_name: str) -> bool:
             __import__(import_name)
         except ImportError:
             return False
-    minimum = MIN_VERSIONS.get(package_name)
+    minimum = _minimum_version(package_name)
     if minimum:
-        installed = _installed_version_tuple(package_name)
+        installed = _installed_version_tuple(_dist_name(package_name))
         if not installed or installed < minimum:
             print(f"{package_name} is installed but below the required "
                   f"{'.'.join(map(str, minimum))}; will upgrade via pip")
@@ -188,10 +231,11 @@ def main():
             continue
 
         # Try apt first, then pip. An apt install only counts if it also
-        # satisfies any minimum version (Debian's python3-freetype can be
-        # older than the freetype-py pin), otherwise fall through to pip.
+        # satisfies the requirements floor (the apt copies of most of these
+        # are older than the pins on both Bookworm and Trixie), otherwise
+        # fall through to pip.
         ok, apt_output = install_via_apt(package)
-        if ok and package in MIN_VERSIONS and not check_package_installed(package):
+        if ok and _minimum_version(package) and not check_package_installed(package):
             ok = False
             apt_output = f"apt version of {package} is below the required minimum"
         if not ok:

scripts/plugin_api_usage.py

@@ -0,0 +1,778 @@
+#!/usr/bin/env python3
+"""Who still calls or overrides the core methods marked ``@deprecated``?
+
+A deprecated plugin-facing method may only be removed once nothing uses it,
+and plugins live in other repositories. This script answers the question for
+every method ``src/deprecation.py``'s decorator marks in core:
+
+1. it lists the markers by parsing ``src/`` (so the list can never drift from
+   the code);
+2. it scans, with the ``ast`` module, core itself (``src/``,
+   ``web_interface/``, ``scripts/``, the top-level ``*.py``; ``test/``
+   separately), the official monorepo's ``plugins/`` directory, and every
+   third-party plugin the monorepo's ``plugins.json`` lists with its own repo
+   URL (shallow-cloned read-only into a cache directory);
+3. it reports, per method and per plugin, the calls and overrides it found,
+   and a verdict: unused (safe to remove in the marker's release), still used
+   (keep or migrate those plugins first), or needs review.
+
+Matching is by method name, so it has to separate real uses from unrelated
+methods that happen to share the name (the weather plugin's own ``draw_sun``,
+say). Each hit is classified by what it is attached to:
+
+* **call** -- ``<receiver>.name`` where the receiver is named like the owning
+  object (``self.cache_manager``, ``display_manager``, ``plugin_manager`` ...,
+  or a local alias assigned from one), or ``self``/``super()`` inside a class
+  that subclasses the owner. Attribute references that are not called
+  (``callback=cm.get_cache_metrics``) count too.
+* **override** -- ``def name`` in a class that subclasses the owner.
+* **review** -- ``<receiver>.name`` where the receiver says nothing about its
+  type, or ``getattr(obj, "name")``. Possibly a real use; read the listed line.
+* **unrelated** -- ``self.name`` inside a class that defines ``name`` itself
+  and does not subclass the owner, ``Klass.name`` where the same tree defines
+  ``Klass.name``, or ``def name`` in such a class: a name collision, not a use.
+* **internal** -- a hit inside the body of another deprecated core method
+  (``draw_rain`` calling ``draw_cloud``): it keeps the method only as long as
+  that caller is kept.
+
+Only calls and overrides make a method "still used"; review hits make it
+"needs review"; hits in test files are listed but never block removal (a test
+that mocks a method does not need it to exist).
+
+    python3 scripts/plugin_api_usage.py                      # clone everything, print Markdown
+    python3 scripts/plugin_api_usage.py --monorepo ../ledmatrix-plugins
+    python3 scripts/plugin_api_usage.py --output docs/DEPRECATIONS_3.8.md
+    python3 scripts/plugin_api_usage.py --format json
+
+Nothing is ever written to the repositories it scans: the monorepo path is only
+read, and clones live in ``--cache-dir``.
+"""
+from __future__ import annotations
+
+import argparse
+import ast
+import json
+import os
+import re
+import subprocess  # nosec B404 - list-form argv only, no shell  # nosemgrep
+import sys
+import tempfile
+from collections import defaultdict
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, Iterable, Iterator, List, Optional, Set, Tuple
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+MONOREPO_URL = "https://github.com/ChuckBuilds/ledmatrix-plugins"
+MONOREPO_SLUG = "chuckbuilds/ledmatrix-plugins"
+
+#: Receiver names that mean "this is the owning core object". Compared against
+#: the last name in the receiver (``self.plugin_manager.cache_manager`` ->
+#: ``cache_manager``), lower-cased with leading underscores stripped.
+OWNER_RECEIVERS: Dict[str, Tuple[str, ...]] = {
+    "CacheManager": ("cache_manager", "cache_mgr", "cachemanager", "cache", "cm"),
+    "DisplayManager": ("display_manager", "display_mgr", "displaymanager", "display", "dm"),
+    "FontManager": ("font_manager", "font_mgr", "fontmanager", "fonts", "fm"),
+    "PluginManager": ("plugin_manager", "plugin_mgr", "pluginmanager", "pm"),
+}
+
+#: Directories never scanned (vendored environments, VCS metadata, caches).
+SKIP_DIRS = {".git", "__pycache__", "node_modules", ".venv", "venv", "env",
+             "site-packages", ".tox", ".mypy_cache", ".pytest_cache"}
+
+CORE_DIRS = ("src", "web_interface", "scripts")
+CORE_TEST_DIRS = ("test",)
+
+
+# --------------------------------------------------------------------------
+# Markers
+
+
+@dataclass
+class Marker:
+    owner: str          # class name, e.g. "CacheManager"
+    method: str
+    removal: str
+    alternative: Optional[str]
+    module: str         # e.g. "src.cache_manager"
+    line: int
+
+    @property
+    def key(self) -> str:
+        return f"{self.owner}.{self.method}"
+
+
+def _decorator_name(node: ast.expr) -> Optional[str]:
+    target = node.func if isinstance(node, ast.Call) else node
+    if isinstance(target, ast.Name):
+        return target.id
+    if isinstance(target, ast.Attribute):
+        return target.attr
+    return None
+
+
+def find_markers(core_root: Path) -> List[Marker]:
+    """Every ``@deprecated(...)`` method under ``core_root/src``."""
+    markers: List[Marker] = []
+    for path in sorted((core_root / "src").rglob("*.py")):
+        if path.name == "deprecation.py":
+            continue
+        tree = _parse(path)
+        if tree is None:
+            continue
+        module = ".".join(path.relative_to(core_root).with_suffix("").parts)
+        for cls in (n for n in ast.walk(tree) if isinstance(n, ast.ClassDef)):
+            for fn in cls.body:
+                if not isinstance(fn, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    continue
+                for dec in fn.decorator_list:
+                    if _decorator_name(dec) != "deprecated" or not isinstance(dec, ast.Call):
+                        continue
+                    args = [a.value if isinstance(a, ast.Constant) else None for a in dec.args]
+                    kw = {k.arg: k.value.value for k in dec.keywords
+                          if isinstance(k.value, ast.Constant)}
+                    removal = args[0] if args else kw.get("removal")
+                    alternative = args[1] if len(args) > 1 else kw.get("alternative")
+                    markers.append(Marker(cls.name, fn.name, str(removal), alternative,
+                                          module, fn.lineno))
+    return markers
+
+
+# --------------------------------------------------------------------------
+# Scanning
+
+
+@dataclass
+class Hit:
+    kind: str           # call | override | review | unrelated | internal
+    path: str
+    line: int
+    code: str
+    test: bool
+    via: Optional[str] = None   # internal: the deprecated core method it sits in
+
+
+@dataclass
+class Source:
+    """One plugin (or core) tree to scan."""
+    name: str
+    group: str          # core | core-tests | monorepo | third-party
+    root: Optional[Path]
+    error: Optional[str] = None
+    hits: Dict[str, List[Hit]] = field(default_factory=lambda: defaultdict(list))
+    files: int = 0      # Python files scanned
+
+
+def _parse(path: Path) -> Optional[ast.AST]:
+    try:
+        return ast.parse(path.read_text(encoding="utf-8", errors="replace"), str(path))
+    except (SyntaxError, ValueError):
+        return None
+
+
+def _iter_py(root: Path) -> Iterator[Path]:
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+        for name in filenames:
+            if name.endswith(".py"):
+                yield Path(dirpath) / name
+
+
+def _is_test_path(rel: Path) -> bool:
+    parts = [p.lower() for p in rel.parts]
+    return (any(p in ("test", "tests") for p in parts[:-1])
+            or parts[-1].startswith("test_") or parts[-1].endswith("_test.py")
+            or parts[-1] == "conftest.py")
+
+
+def _terminal(node: ast.expr) -> Optional[str]:
+    """The last name in a receiver expression, or None if it has none."""
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return node.attr
+    if isinstance(node, ast.Call):
+        return _terminal(node.func)
+    if isinstance(node, ast.Subscript):
+        return _terminal(node.value)
+    return None
+
+
+def _norm(name: Optional[str]) -> str:
+    return (name or "").lstrip("_").lower()
+
+
+def _base_names(cls: ast.ClassDef) -> List[str]:
+    return [t for t in (_terminal(b) for b in cls.bases) if t]
+
+
+class _Scanner(ast.NodeVisitor):
+    """Collect hits for every marked method name in one file."""
+
+    def __init__(self, markers: Dict[str, List[Marker]], lines: List[str],
+                 rel: str, test: bool, core_modules: Dict[str, str], module: Optional[str],
+                 local_definers: Dict[str, Set[str]], built: Dict[str, str]):
+        self.markers = markers              # method name -> markers with that name
+        self.local_definers = local_definers  # method name -> this tree's own classes/modules defining it
+        self.built = built                  # ``x``/``self.x`` -> class it was built from in this file
+        self.lines = lines
+        self.rel = rel
+        self.test = test
+        self.core_modules = core_modules    # owner class -> defining module (core only)
+        self.module = module                # this file's module when scanning core
+        self.classes: List[ast.ClassDef] = []
+        self.scope: List[ast.AST] = []      # enclosing classes and functions
+        self.aliases: List[Dict[str, str]] = [{}]   # local name -> owner class
+        self.out: Dict[str, List[Hit]] = defaultdict(list)
+
+    # -- helpers
+    def _code(self, node: ast.AST) -> str:
+        line = self.lines[node.lineno - 1] if 0 < node.lineno <= len(self.lines) else ""
+        return line.strip()[:160]
+
+    def _add(self, marker: Marker, kind: str, node: ast.AST) -> None:
+        via = self._inside_deprecated()
+        if via and kind != "unrelated":
+            # Only reached through another deprecated method: goes when that does.
+            kind = "internal"
+        self.out[marker.key].append(Hit(kind, self.rel, node.lineno, self._code(node),
+                                        self.test, via if kind == "internal" else None))
+
+    def _inside_deprecated(self) -> Optional[str]:
+        """``Owner.method`` when this node sits in a deprecated core method's body."""
+        for i in range(len(self.scope) - 2, -1, -1):
+            cls, fn = self.scope[i], self.scope[i + 1]
+            if isinstance(cls, ast.ClassDef):
+                if isinstance(fn, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    for m in self.markers.get(fn.name, ()):
+                        if self._is_owner_class(cls, m.owner):
+                            return m.key
+                return None
+        return None
+
+    def _owner_for_receiver(self, name: Optional[str]) -> Optional[str]:
+        n = _norm(name)
+        for scope in reversed(self.aliases):
+            if name in scope:
+                return scope[name]
+        for owner, receivers in OWNER_RECEIVERS.items():
+            if n in receivers:
+                return owner
+        return None
+
+    def _is_owner_class(self, cls: ast.ClassDef, owner: str) -> bool:
+        """True for the real core class (only when scanning its own module)."""
+        return (self.module is not None and cls.name == owner
+                and self.core_modules.get(owner) == self.module)
+
+    def _subclasses(self, cls: ast.ClassDef, owner: str) -> bool:
+        return owner in _base_names(cls)
+
+    def _class_defines(self, cls: ast.ClassDef, name: str) -> bool:
+        return any(isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef)) and n.name == name
+                   for n in cls.body)
+
+    # -- scopes
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        for fn in node.body:
+            if isinstance(fn, (ast.FunctionDef, ast.AsyncFunctionDef)) and fn.name in self.markers:
+                for m in self.markers[fn.name]:
+                    if self._is_owner_class(node, m.owner):
+                        continue                      # the definition itself
+                    kind = "override" if self._subclasses(node, m.owner) else "unrelated"
+                    self._add(m, kind, fn)
+        self.classes.append(node)
+        self.scope.append(node)
+        self.generic_visit(node)
+        self.scope.pop()
+        self.classes.pop()
+
+    def _visit_function(self, node) -> None:
+        self.aliases.append({})
+        self.scope.append(node)
+        self.generic_visit(node)
+        self.scope.pop()
+        self.aliases.pop()
+
+    visit_FunctionDef = _visit_function
+    visit_AsyncFunctionDef = _visit_function
+
+    def visit_Assign(self, node: ast.Assign) -> None:
+        # ``dm = self.display_manager`` makes ``dm.draw_sun()`` a call.
+        owner = self._owner_for_receiver(_terminal(node.value))
+        for target in node.targets:
+            if isinstance(target, ast.Name) and owner:
+                self.aliases[-1][target.id] = owner
+        self.generic_visit(node)
+
+    # -- uses
+    def visit_Attribute(self, node: ast.Attribute) -> None:
+        if node.attr in self.markers:
+            for m in self.markers[node.attr]:
+                self._add(m, self._classify(node, m), node)
+        self.generic_visit(node)
+
+    def _classify(self, node: ast.Attribute, m: Marker) -> str:
+        recv = node.value
+        cls = self.classes[-1] if self.classes else None
+        is_self = isinstance(recv, ast.Name) and recv.id in ("self", "cls")
+        is_super = (isinstance(recv, ast.Call) and isinstance(recv.func, ast.Name)
+                    and recv.func.id == "super")
+        if is_self or is_super:
+            if cls is not None and (self._is_owner_class(cls, m.owner) or self._subclasses(cls, m.owner)):
+                return "call"
+            if cls is not None and self._class_defines(cls, m.method):
+                return "unrelated"
+            return "review"
+        name = _terminal(recv)
+        if self._owner_for_receiver(name) == m.owner:
+            return "call"
+        definers = self.local_definers.get(m.method, ())
+        if name in definers or self.built.get(name or "") in definers:
+            # e.g. the weather plugin's WeatherIcons.draw_sun, or
+            # self._strategy_component = CacheStrategy(); ...get_sport_live_interval()
+            return "unrelated"
+        return "review"
+
+    def visit_Call(self, node: ast.Call) -> None:
+        func = node.func
+        if (isinstance(func, ast.Name) and func.id in ("getattr", "hasattr", "setattr", "delattr")
+                and len(node.args) >= 2 and isinstance(node.args[1], ast.Constant)
+                and node.args[1].value in self.markers):
+            for m in self.markers[node.args[1].value]:
+                owner = self._owner_for_receiver(_terminal(node.args[0]))
+                self._add(m, "call" if owner == m.owner else "review", node)
+        self.generic_visit(node)
+
+
+def _built_from(tree: ast.AST) -> Dict[str, str]:
+    """``{name: Class}`` for every ``name = Class(...)`` / ``self.name = Class(...)``."""
+    built: Dict[str, str] = {}
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Assign) and isinstance(node.value, ast.Call):
+            cls = _terminal(node.value.func)
+            for target in node.targets:
+                name = _terminal(target) if isinstance(target, (ast.Name, ast.Attribute)) else None
+                if name and cls:
+                    built[name] = cls
+    return built
+
+
+def scan_tree(source: Source, roots: Iterable[Path], base: Path, markers: List[Marker],
+              core: bool, test_override: Optional[bool] = None,
+              definer_roots: Iterable[Path] = ()) -> None:
+    by_name: Dict[str, List[Marker]] = defaultdict(list)
+    for m in markers:
+        by_name[m.method].append(m)
+    core_modules = {m.owner: m.module for m in markers}
+    owners = {m.owner for m in markers}
+    files: List[Tuple[Path, str, Optional[ast.AST]]] = []
+    for root in roots:
+        if not root.exists():
+            continue
+        for path in ([root] if root.is_file() else sorted(_iter_py(root))):
+            source.files += 1
+            text = path.read_text(encoding="utf-8", errors="replace")
+            if any(name in text for name in by_name):
+                files.append((path, text, _parse(path)))
+
+    # Classes (and modules) in this tree with their own method of a marked
+    # name, so ``WeatherIcons.draw_sun()`` is recognised as theirs.
+    local_definers: Dict[str, Set[str]] = defaultdict(set)
+    definer_files = list(files)
+    for root in definer_roots:
+        for path in (sorted(_iter_py(root)) if root.is_dir() else ()):
+            text = path.read_text(encoding="utf-8", errors="replace")
+            if any(name in text for name in by_name):
+                definer_files.append((path, text, _parse(path)))
+    for path, _, tree in definer_files:
+        for node in (tree.body if tree is not None else ()):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node.name in by_name:
+                local_definers[node.name].add(path.stem)
+        for cls in (n for n in ast.walk(tree) if isinstance(n, ast.ClassDef)) if tree else ():
+            if cls.name in owners and core:
+                continue
+            if owners & set(_base_names(cls)):
+                continue
+            for fn in cls.body:
+                if isinstance(fn, (ast.FunctionDef, ast.AsyncFunctionDef)) and fn.name in by_name:
+                    local_definers[fn.name].add(cls.name)
+
+    for path, text, tree in files:
+        rel = path.relative_to(base)
+        test = _is_test_path(rel) if test_override is None else test_override
+        if tree is None:
+            # Unparseable (Python 2, a template ...): fall back to text, as review.
+            for no, line in enumerate(text.splitlines(), 1):
+                for name in by_name:
+                    if re.search(rf"{re.escape(name)}", line):
+                        for m in by_name[name]:
+                            source.hits[m.key].append(
+                                Hit("review", rel.as_posix(), no, line.strip()[:160], test))
+            continue
+        module = ".".join(rel.with_suffix("").parts) if core else None
+        scanner = _Scanner(by_name, text.splitlines(), rel.as_posix(), test,
+                           core_modules, module, local_definers, _built_from(tree))
+        scanner.visit(tree)
+        for key, hits in scanner.out.items():
+            source.hits[key].extend(hits)
+
+
+# --------------------------------------------------------------------------
+# Fetching plugin trees (read-only)
+
+
+def _git(*args: str, cwd: Optional[Path] = None) -> subprocess.CompletedProcess:
+    # Never stop to ask for credentials: a deleted or private plugin repo
+    # should be reported as not scanned, not hang the scan.
+    env = {**os.environ, "GIT_TERMINAL_PROMPT": "0"}
+    return subprocess.run(  # nosec B603 B607 - list-form git argv, no shell; URLs follow "--"  # nosemgrep
+        ["git", *args], cwd=cwd, capture_output=True, text=True,
+        encoding="utf-8", errors="replace", timeout=300, env=env)
+
+
+def _rmtree(path: Path) -> None:
+    """Delete a clone; git marks pack files read-only, which Windows refuses to delete."""
+    import shutil
+    import stat
+
+    def retry(func, target, _exc):
+        os.chmod(target, stat.S_IWRITE)
+        func(target)
+
+    if sys.version_info >= (3, 12):
+        shutil.rmtree(path, onexc=retry)
+    else:
+        shutil.rmtree(path, onerror=retry)
+
+
+def shallow_clone(url: str, branch: Optional[str], dest: Path, reuse: bool) -> Optional[str]:
+    """Clone ``url`` into ``dest`` (depth 1), replacing any earlier clone.
+
+    Returns an error string, or None on success.
+    """
+    if reuse and (dest / ".git").exists():
+        return None
+    if dest.exists():
+        _rmtree(dest)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    args = ["-c", "core.longpaths=true", "clone", "--quiet", "--depth", "1"]
+    if branch:
+        args += ["--branch", branch]
+    # "--" ends option parsing: a registry URL starting with "-" (for example
+    # "--upload-pack=...") is then only ever a repository argument.
+    result = _git(*args, "--", url, str(dest))
+    if result.returncode != 0 and branch:
+        result = _git("-c", "core.longpaths=true", "clone", "--quiet", "--depth", "1",
+                      "--", url, str(dest))
+    if result.returncode != 0:
+        lines = (result.stderr or result.stdout).strip().splitlines()
+        return lines[-1] if lines else "git clone failed"
+    return None
+
+
+def _head(path: Path, branch: bool = True) -> str:
+    """Commit (and branch) of a checkout, via read-only git calls."""
+    rev = _git("--no-optional-locks", "rev-parse", "--short=8", "HEAD", cwd=path)
+    if rev.returncode != 0:
+        return "unknown revision"
+    if not branch:
+        return rev.stdout.strip()
+    ref = _git("--no-optional-locks", "rev-parse", "--abbrev-ref", "HEAD", cwd=path)
+    return f"{ref.stdout.strip()} @ {rev.stdout.strip()}"
+
+
+def _plugin_id(plugin_dir: Path) -> str:
+    try:
+        return json.loads((plugin_dir / "manifest.json").read_text(encoding="utf-8"))["id"]
+    except (OSError, ValueError, KeyError, TypeError):
+        return plugin_dir.name
+
+
+def _is_monorepo(url: str) -> bool:
+    return MONOREPO_SLUG in url.lower().rstrip("/").removesuffix(".git")
+
+
+# --------------------------------------------------------------------------
+# Report
+
+
+def verdicts(markers: List[Marker], sources: List[Source]) -> Dict[str, Tuple[str, str]]:
+    """``{Owner.method: (status, text)}`` across every source.
+
+    An *internal* hit (a call from inside another deprecated method) keeps a
+    method only while that caller is itself kept, so statuses are resolved
+    until they stop changing.
+    """
+    failed = [s.name for s in sources if s.error]
+    status: Dict[str, Tuple[str, str]] = {}
+    for _ in range(len(markers) + 1):
+        changed = False
+        for m in markers:
+            used, review = [], []
+            for s in sources:
+                live = [h for h in s.hits.get(m.key, []) if not h.test]
+                if any(h.kind in ("call", "override") for h in live) or any(
+                        h.kind == "internal" and status.get(h.via, ("",))[0] == "used"
+                        for h in live):
+                    used.append(s.name)
+                elif any(h.kind == "review" for h in live) or any(
+                        h.kind == "internal" and status.get(h.via, ("",))[0] == "review"
+                        for h in live):
+                    review.append(s.name)
+            if used:
+                new = ("used", f"still used by {', '.join(used)} — keep or migrate first")
+            elif review:
+                new = ("review", f"needs review: possible use in {', '.join(review)}")
+            elif failed:
+                new = ("unknown", f"not proven unused: {len(failed)} plugin(s) could not be scanned")
+            else:
+                new = ("unused", f"unused — safe to remove in {m.removal}")
+            if status.get(m.key) != new:
+                status[m.key] = new
+                changed = True
+        if not changed:
+            break
+    return status
+
+
+def _counts(hits: List[Hit]) -> Dict[str, int]:
+    c: Dict[str, int] = defaultdict(int)
+    for h in hits:
+        c[("test " if h.test else "") + h.kind] += 1
+    return c
+
+
+def _usage_cell(marker: Marker, sources: List[Source], kinds: Tuple[str, ...]) -> str:
+    parts = []
+    for s in sources:
+        c = _counts(s.hits.get(marker.key, []))
+        bits = [f"{c[k]} {k}{'s' if c[k] != 1 else ''}" for k in kinds if c[k]]
+        if bits:
+            parts.append(f"{s.name} ({', '.join(bits)})")
+    return "; ".join(parts) or "—"
+
+
+def render_markdown(markers: List[Marker], sources: List[Source], meta: Dict[str, str]) -> str:
+    out: List[str] = []
+    w = out.append
+    w("# Deprecated plugin APIs: usage scan")
+    w("")
+    w("Generated by `scripts/plugin_api_usage.py` — do not edit by hand; re-run it "
+      "(see [How to re-run](#how-to-re-run)).")
+    w("")
+    w(f"- Scanned: {meta['date']}, core {meta['core_version']}")
+    w(f"- Monorepo: {meta['monorepo']}")
+    w(f"- Third-party plugins: {meta['third_party']}")
+    failed = [s for s in sources if s.error]
+    if failed:
+        w("- **Not scanned:** " + "; ".join(f"{s.name} ({s.error})" for s in failed))
+    w("")
+    status = verdicts(markers, sources)
+    tally: Dict[str, int] = defaultdict(int)
+    for st, _ in status.values():
+        tally[st] += 1
+    w(f"**{len(markers)} deprecated methods: {tally['unused']} unused, "
+      f"{tally['used']} still used, {tally['review']} need review"
+      + (f", {tally['unknown']} not proven" if tally["unknown"] else "") + ".**")
+    w("")
+    w("Counted per plugin: a *call* is `<receiver>.method` on an object named like "
+      "the owner (`cache_manager`, `display_manager`, `font_manager`, `plugin_manager`), "
+      "or on `self`/`super()` in a subclass; an *override* is `def method` in a subclass "
+      "of the owner. *Review* hits are `.method` on a receiver whose type the scan cannot "
+      "tell. *Internal* hits sit inside another deprecated core method and go with it. "
+      "*Unrelated* hits are a different class's own method with the same name "
+      "(a name collision), and never block removal; neither do hits in test files.")
+    w("")
+    w("| Method | Removal | Core | Plugins (calls / overrides) | Name collisions & tests | Verdict |")
+    w("|---|---|---|---|---|---|")
+    core_sources = [s for s in sources if s.group in ("core", "core-tests")]
+    plugin_sources = [s for s in sources if s.group not in ("core", "core-tests")]
+    for m in markers:
+        core = _usage_cell(m, core_sources, ("call", "override", "review", "internal",
+                                             "test call", "test override", "test review",
+                                             "test internal"))
+        plugins = _usage_cell(m, plugin_sources, ("call", "override", "review"))
+        other = _usage_cell(m, plugin_sources, ("unrelated", "test call", "test override",
+                                                "test review", "test unrelated"))
+        w(f"| `{m.key}` | {m.removal} | {core} | {plugins} | {other} | {status[m.key][1]} |")
+    w("")
+
+    groups = [("unused", "Unused — safe to remove"), ("used", "Still used — keep or migrate first"),
+              ("review", "Needs review"), ("unknown", "Not proven unused")]
+    for st, title in groups:
+        names = [m.key for m in markers if status[m.key][0] == st]
+        if names:
+            w(f"## {title} ({len(names)})")
+            w("")
+            w(", ".join(f"`{n}`" for n in names))
+            w("")
+
+    detail = [(m, s, h) for m in markers for s in sources
+              for h in s.hits.get(m.key, []) if h.kind != "unrelated" or not h.test]
+    if detail:
+        w("## Every hit")
+        w("")
+        w("File paths are relative to the plugin's directory (core: the repo root).")
+        w("")
+        w("| Method | Where | File:line | Kind | Code |")
+        w("|---|---|---|---|---|")
+        for m, s, h in detail:
+            kind = ("test " if h.test else "") + h.kind
+            if h.via:
+                kind += f" (in `{h.via}`)"
+            code = h.code.replace("|", "\\|").replace("`", "'")
+            w(f"| `{m.key}` | {s.name} | {h.path}:{h.line} | {kind} | `{code}` |")
+        w("")
+
+    w("## Sources scanned")
+    w("")
+    w("| Source | Group | Python files | Hits |")
+    w("|---|---|---|---|")
+    for s in sources:
+        n = sum(len(v) for v in s.hits.values())
+        files = f"not scanned: {s.error}" if s.error else str(s.files)
+        w(f"| {s.name} | {s.group} | {files} | {n} |")
+    w("")
+
+    w("## How to re-run")
+    w("")
+    w("```bash")
+    w("# Clones the monorepo and each third-party plugin (depth 1) into a temp cache:")
+    w("python3 scripts/plugin_api_usage.py --output docs/DEPRECATIONS_3.8.md")
+    w("# Or scan a local monorepo checkout (read only) instead of cloning it:")
+    w("python3 scripts/plugin_api_usage.py --monorepo ../ledmatrix-plugins")
+    w("```")
+    w("")
+    w("Before removing a method in its release, re-run the scan against the current "
+      "monorepo and registry: a plugin added since this file was generated may have "
+      "started calling it. Remove only methods the fresh scan reports unused; move "
+      "the rest to a later release (the test in `test/test_deprecation.py` fails "
+      "while a marker names a release at or below `src.__version__`).")
+    w("")
+    return "\n".join(out)
+
+
+def render_json(markers: List[Marker], sources: List[Source], meta: Dict[str, str]) -> str:
+    data = {"meta": meta, "sources": [{"name": s.name, "group": s.group, "error": s.error}
+                                      for s in sources], "methods": []}
+    status = verdicts(markers, sources)
+    for m in markers:
+        st, text = status[m.key]
+        data["methods"].append({
+            "method": m.key, "module": m.module, "removal": m.removal,
+            "alternative": m.alternative, "status": st, "verdict": text,
+            "hits": [{"source": s.name, **h.__dict__} for s in sources
+                     for h in s.hits.get(m.key, [])],
+        })
+    return json.dumps(data, indent=2)
+
+
+# --------------------------------------------------------------------------
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    parser.add_argument("--monorepo", type=Path,
+                        help="local ledmatrix-plugins checkout to scan (read only); "
+                             "default: shallow-clone its main branch")
+    parser.add_argument("--registry", type=Path,
+                        help="plugins.json to read third-party plugins from "
+                             "(default: the monorepo's)")
+    parser.add_argument("--cache-dir", type=Path,
+                        default=Path(tempfile.gettempdir()) / "ledmatrix-plugin-api-usage",
+                        help="where clones go (default: %(default)s)")
+    parser.add_argument("--reuse-cache", action="store_true",
+                        help="scan clones already in --cache-dir instead of re-cloning "
+                             "(offline re-runs; the report may then be stale)")
+    parser.add_argument("--no-third-party", action="store_true",
+                        help="skip third-party plugins (the report then cannot prove anything unused)")
+    parser.add_argument("--format", choices=("md", "json"), default="md")
+    parser.add_argument("--output", type=Path, help="write the report here instead of stdout")
+    args = parser.parse_args(argv)
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+
+    markers = find_markers(REPO_ROOT)
+    if not markers:
+        print("No @deprecated markers found in src/.", file=sys.stderr)
+        return 0
+
+    sys.path.insert(0, str(REPO_ROOT))
+    try:
+        from src import __version__ as core_version
+    except Exception:  # noqa: BLE001 -- reporting only
+        core_version = "unknown"
+
+    sources: List[Source] = []
+    core = Source("core", "core", REPO_ROOT)
+    scan_tree(core, [REPO_ROOT / d for d in CORE_DIRS] + sorted(REPO_ROOT.glob("*.py")),
+              REPO_ROOT, markers, core=True)
+    core_tests = Source("core tests", "core-tests", REPO_ROOT)
+    scan_tree(core_tests, [REPO_ROOT / d for d in CORE_TEST_DIRS], REPO_ROOT, markers,
+              core=True, test_override=True,
+              definer_roots=[REPO_ROOT / d for d in CORE_DIRS])
+    sources += [core, core_tests]
+
+    # Monorepo
+    if args.monorepo:
+        mono = args.monorepo.resolve()
+        mono_desc = f"local checkout `{mono.name}` ({_head(mono)})"
+    else:
+        mono = args.cache_dir / "ledmatrix-plugins"
+        err = shallow_clone(MONOREPO_URL, "main", mono, args.reuse_cache)
+        if err:
+            print(f"Could not clone the monorepo: {err}", file=sys.stderr)
+            return 1
+        mono_desc = f"[ChuckBuilds/ledmatrix-plugins]({MONOREPO_URL}) ({_head(mono)})"
+    plugins_dir = mono / "plugins"
+    mono_dirs = sorted(p for p in plugins_dir.iterdir() if p.is_dir()) if plugins_dir.is_dir() else []
+    for d in mono_dirs:
+        s = Source(_plugin_id(d), "monorepo", d)
+        scan_tree(s, [d], d, markers, core=False)
+        sources.append(s)
+    mono_desc += f", {len(mono_dirs)} plugins"
+
+    # Third-party plugins from the registry
+    registry = args.registry or (mono / "plugins.json")
+    third: List[dict] = []
+    try:
+        reg = json.loads(registry.read_text(encoding="utf-8"))
+        entries = reg["plugins"] if isinstance(reg, dict) else reg
+        third = [e for e in entries if e.get("repo") and not _is_monorepo(e["repo"])]
+    except (OSError, ValueError, KeyError) as exc:
+        print(f"Could not read {registry}: {exc}", file=sys.stderr)
+        return 1
+    if args.no_third_party:
+        tp_desc = "skipped (--no-third-party)"
+    else:
+        for e in third:
+            dest = args.cache_dir / "third-party" / re.sub(r"[^\w.-]", "_", e["id"])
+            err = shallow_clone(e["repo"], e.get("branch") or None, dest, args.reuse_cache)
+            root = dest / e["plugin_path"] if e.get("plugin_path") else dest
+            s = Source(e["id"], "third-party", root, error=err)
+            if not err:
+                scan_tree(s, [root], root, markers, core=False)
+            sources.append(s)
+        tp_desc = (f"{len(third)} with their own repo in `plugins.json` "
+                   f"({', '.join(e['id'] for e in third)})")
+
+    meta = {
+        "date": datetime.now(timezone.utc).strftime("%Y-%m-%d"),
+        "core_version": core_version,
+        "core_rev": _head(REPO_ROOT, branch=False),
+        "monorepo": mono_desc,
+        "third_party": tp_desc,
+    }
+    report = (render_json if args.format == "json" else render_markdown)(markers, sources, meta)
+    if args.output:
+        args.output.write_text(report, encoding="utf-8", newline="\n")
+        print(f"Wrote {args.output}", file=sys.stderr)
+    else:
+        sys.stdout.write(report)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/render_bench.py

@@ -25,6 +25,14 @@ against another) and for A/B testing a change to the render path.
     sudo python3 scripts/render_bench.py --busy 2           # with background load
     sudo python3 scripts/render_bench.py --json /tmp/pi4.json
 
+    # the cost of changing pixels under a moving strip (Vegas live elements):
+    # a 101KB write into the visible columns every 25 frames
+    sudo python3 scripts/render_bench.py --patch-bytes 101376 --patch-every 25
+
+    # the cost of extending a Vegas-sized strip on the render thread: a 30-screen
+    # strip, extended by 6 screens (and trimmed) every 6 screens scrolled
+    sudo python3 scripts/render_bench.py --strip-screens 30 --extend-every-screens 6
+
     sudo systemctl start ledmatrix
 
 Like scripts/scroll_speeds.py, this never starts or stops the service itself,
@@ -92,13 +100,17 @@ def load_config() -> dict:
     return config
 
 
-def build_strip(width: int, height: int, label: str):
-    """A marquee strip a few screens wide, with text and colour.
+def build_strip(width: int, height: int, label: str, screens: float = 4.0):
+    """A marquee strip about ``screens`` screens wide, with text and colour.
 
     Deliberately not plain white text on black: how long ``SetImage`` takes
     depends on how many subpixels are lit, so a strip that is mostly dark
     flatters the panel and hides exactly the regression this benchmark exists
     to catch.
+
+    The width matters to the extension mode, whose cost is a copy of the whole
+    strip: Vegas carries 8,000-20,000 columns, so measure extension against a
+    strip that wide (``--strip-screens``), not the four-screen default.
     """
     from PIL import Image, ImageDraw, ImageFont
 
@@ -123,7 +135,7 @@ def build_strip(width: int, height: int, label: str):
     text_width = max(1, box[2] - box[0])
     text_height = box[3] - box[1]
 
-    reps = max(2, (width * 4) // text_width + 1)
+    reps = max(2, int(width * screens) // text_width + 1)
     strip = Image.new("RGB", (text_width * reps, height), (0, 0, 0))
     draw = ImageDraw.Draw(strip)
     draw.fontmode = "1"  # the panel has no partial brightness; see DisplayManager
@@ -179,6 +191,119 @@ class BackgroundLoad:
             zlib.compress(image.tobytes(), 1)
 
 
+class StripWork:
+    """Render-thread work a Vegas strip does between frames, on a schedule.
+
+    Patching writes a block of columns into the strip in place, as a live
+    element update does. Extending appends a block and trims what has scrolled
+    past, as continuous Vegas does (render_pipeline.extend_scroll_content).
+    Both run where Vegas runs them -- on the frame loop, before the next frame
+    is drawn -- and are tagged with ``FrameTimingRecorder.note_op``, so the
+    report shows how often the frame straight after each one was late.
+
+    The content comes from the benchmark's own strip, prepared before the run:
+    in Vegas it is drawn off the render thread, so drawing it here would time
+    work the render thread never does.
+    """
+
+    def __init__(self, helper, recorder, source, *, patch_bytes: int = 0,
+                 patch_every: int = 25, patch_where: str = "visible",
+                 extend_every_screens: float = 0.0, extend_width: int = 0,
+                 separator: int = 32) -> None:
+        import numpy as np
+        from PIL import Image
+
+        self.helper = helper
+        self.recorder = recorder
+        self.width = helper.display_width
+        self.height = helper.display_height
+        self.patch_every = max(1, int(patch_every))
+        self.patch_where = patch_where
+        self.separator = max(0, int(separator))
+        self.patches = 0
+        self.patched_bytes = 0
+        self.extensions = 0
+        self._frames = 0
+        self._position_at_extend = 0.0
+
+        pixels = np.asarray(source.convert("RGB"))
+        source_width = pixels.shape[1]
+
+        def columns(count: int, offset: int):
+            # Wraps around the source, so any width can be cut from it.
+            return np.ascontiguousarray(
+                pixels[:, (np.arange(count) + offset) % source_width])
+
+        # Two versions to alternate between, so every patch changes pixels.
+        self._patches = []
+        if patch_bytes > 0:
+            count = max(1, int(patch_bytes) // (self.height * 3))
+            self._patches = [columns(count, 0), columns(count, count)]
+
+        self.extend_every = (int(extend_every_screens * self.width)
+                             if extend_every_screens > 0 else 0)
+        self._blocks = []
+        if self.extend_every:
+            # By default each append (block plus its separator) replaces
+            # exactly what scrolled past since the last one, so the strip
+            # holds its width, as Vegas's does in the steady state.
+            count = int(extend_width) or max(1, self.extend_every - self.separator)
+            self._blocks = [Image.fromarray(columns(count, 0)),
+                            Image.fromarray(columns(count, count))]
+
+    def reset(self) -> None:
+        """The strip was restarted from the beginning."""
+        self._position_at_extend = self.helper.scroll_position
+
+    def before_frame(self) -> None:
+        """Do whatever work is due before the next frame is drawn."""
+        if self._blocks:
+            self._extend_if_due()
+        if self._patches:
+            self._frames += 1
+            if self._frames % self.patch_every == 0:
+                self._patch()
+
+    def _extend_if_due(self) -> None:
+        helper = self.helper
+        if helper.scroll_position < self._position_at_extend:
+            self._position_at_extend = helper.scroll_position
+        # Due on a fixed cadence rather than N screens after the last one ran,
+        # which would drift by the overshoot of a multi-pixel step each time.
+        due_at = self._position_at_extend + self.extend_every
+        if helper.scroll_position < due_at:
+            return
+        block = self._blocks[self.extensions % 2]
+        helper.append_content([block], item_gap=self.separator, element_gap=0)
+        moved = helper.cached_array.nbytes
+        # One screen kept behind the viewport, as Vegas does. The trim shifts
+        # every strip coordinate, the cadence's included.
+        cut = helper.drop_scrolled_prefix(keep_before=self.width)
+        if cut:
+            moved += helper.cached_array.nbytes
+        self._position_at_extend = due_at - cut
+        self.extensions += 1
+        self.recorder.note_op("extend", moved)
+
+    def _patch(self) -> None:
+        patch = self._patches[self.patches % 2]
+        strip = self.helper.cached_array
+        count = patch.shape[1]
+        if strip is None or count > strip.shape[1]:
+            return
+        start = int(self.helper.scroll_position)
+        if self.patch_where == "visible":
+            x = start + max(0, (self.width - count) // 2)
+        else:
+            # Just past the right edge: a change to content not yet on screen.
+            x = start + self.width + 16
+        x = max(0, min(x, strip.shape[1] - count))
+        strip[:, x:x + count] = patch
+        self.patches += 1
+        self.patched_bytes += patch.nbytes
+        self.recorder.note_op("patch", patch.nbytes)
+
+
 
 def main(argv=None) -> int:
     parser = argparse.ArgumentParser(
@@ -202,8 +327,36 @@ def main(argv=None) -> int:
                         help="also write the report as JSON, for comparing rigs")
     parser.add_argument("--label", default=None,
                         help="name for this run in the JSON report (default: hostname)")
+    parser.add_argument("--strip-screens", type=float, default=4.0, metavar="S",
+                        help="strip width in screens (default 4). Vegas strips are "
+                             "8,000-20,000px; the extension cost scales with it")
+    parser.add_argument("--patch-bytes", type=int, default=0, metavar="N",
+                        help="write N bytes of columns into the strip in place "
+                             "every --patch-every frames, as a Vegas live element "
+                             "update does (a 150x64 card is ~29KB, a 512x64 map "
+                             "~100KB)")
+    parser.add_argument("--patch-every", type=int, default=25, metavar="K",
+                        help="frames between patches (default 25; 1 = every frame)")
+    parser.add_argument("--patch-where", choices=("visible", "ahead"),
+                        default="visible",
+                        help="patch the columns on screen, or just past its right "
+                             "edge (default visible)")
+    parser.add_argument("--extend-every-screens", type=float, default=0.0,
+                        metavar="N",
+                        help="append a block and trim the strip every N screens "
+                             "scrolled, as continuous Vegas does")
+    parser.add_argument("--extend-width", type=int, default=0, metavar="W",
+                        help="width of each appended block in px (default: N "
+                             "screens less the separator, so the strip holds its "
+                             "width)")
     args = parser.parse_args(argv)
 
+    if args.extend_every_screens > 0 and args.strip_screens < args.extend_every_screens + 3:
+        # The strip must stay ahead of the viewport between extensions.
+        args.strip_screens = args.extend_every_screens + 3
+        print(f"strip widened to {args.strip_screens:g} screens so extensions "
+              "keep ahead of the viewport")
+
     # Everything the display service logs would otherwise land in the middle of
     # the report; the benchmark's own output is the point. The stall watchdog
     # is the exception: a stack dump naming what held a frame up belongs here.
@@ -272,8 +425,9 @@ def main(argv=None) -> int:
     print(f"asked for {requested:.1f} px/s -> {choice.describe()}")
 
     helper.set_sub_pixel_scrolling(False)
-    helper.set_scrolling_image(
-        build_strip(width, height, f"{choice.pixels_per_second:.0f} px/s"))
+    strip = build_strip(width, height, f"{choice.pixels_per_second:.0f} px/s",
+                        screens=args.strip_screens)
+    helper.set_scrolling_image(strip)
 
     # The display service's own recorder, owned outright here: never flushed to
     # the service's stats file, drained exactly at the start and end of the
@@ -284,12 +438,28 @@ def main(argv=None) -> int:
         flush_interval=float("inf"),
         info=display._frame_timing_info(),  # pylint: disable=protected-access
         refresh_hz=idle_hz,
+        gc_monitor=frame_timing.install_gc_monitor(),
     )
     recorder.scrolling_now = display._scrolling_now  # pylint: disable=protected-access
     display.frame_timing = recorder
 
-    print(f"scrolling {width}x{height} for {args.seconds:.0f}s"
-          + (f" with {args.busy} background worker(s)" if args.busy else "")
+    work = StripWork(helper, recorder, strip,
+                     patch_bytes=args.patch_bytes, patch_every=args.patch_every,
+                     patch_where=args.patch_where,
+                     extend_every_screens=args.extend_every_screens,
+                     extend_width=args.extend_width)
+
+    doing = []
+    if args.busy:
+        doing.append(f"{args.busy} background worker(s)")
+    if args.patch_bytes > 0:
+        doing.append(f"a {args.patch_bytes}B {args.patch_where} patch every "
+                     f"{args.patch_every} frame(s)")
+    if work.extend_every:
+        doing.append(f"an extension every {args.extend_every_screens:g} screens")
+    print(f"scrolling {width}x{height} ({helper.cached_array.shape[1]}px strip) "
+          f"for {args.seconds:.0f}s"
+          + (" with " + ", ".join(doing) if doing else "")
           + " ...", flush=True)
 
     frames = 0
@@ -309,8 +479,11 @@ def main(argv=None) -> int:
                     before = recorder.snapshot()
                     run_started = now
                     frames = duplicates = blanks = restarts = 0
+                    work.patches = work.patched_bytes = work.extensions = 0
                 if run_started is not None and now - run_started >= args.seconds:
                     break
+                # Where Vegas does its strip work: before the frame is drawn.
+                work.before_frame()
                 helper.update_scroll_position()
                 if helper.is_scroll_complete():
                     # The helper parks at the end of the strip and stops
@@ -320,6 +493,7 @@ def main(argv=None) -> int:
                     # the benchmark measures a still image for the rest of the
                     # run and reports a smoothness it never demonstrated.
                     helper.reset_scroll()
+                    work.reset()
                     restarts += 1
                 visible = helper.get_visible_portion()
                 column = int(helper.scroll_position)
@@ -375,6 +549,11 @@ def main(argv=None) -> int:
     if restarts:
         print(f"restarts    {restarts} (the strip was scrolled through "
               f"{restarts} time{'s' if restarts != 1 else ''})")
+    if work.patches:
+        print(f"patches     {work.patches} ({work.patched_bytes / 1e6:.1f} MB "
+              "written into the strip)")
+    if work.extensions:
+        print(f"extensions  {work.extensions}")
 
     if args.json_path:
         report.update({
@@ -388,6 +567,13 @@ def main(argv=None) -> int:
             "duplicate_frames": duplicates,
             "blank_frames": blanks,
             "strip_restarts": restarts,
+            "strip_screens": args.strip_screens,
+            "patch_bytes": args.patch_bytes,
+            "patch_every": args.patch_every,
+            "patch_where": args.patch_where,
+            "patches": work.patches,
+            "extend_every_screens": args.extend_every_screens,
+            "extensions": work.extensions,
             "max_late_pct": args.max_late_pct,
             "passed": frame_soak.passed(report, args.max_late_pct),
         })

scripts/render_plugin.py

@@ -56,9 +56,33 @@ def main() -> int:
                         help='Display mode to render, for plugins that declare '
                              'more than one in their manifest (e.g. nrl_live). '
                              'Omitted, the plugin picks its own default.')
+    parser.add_argument('--vegas', action='store_true',
+                        help="Render the plugin's block of the Vegas ticker strip "
+                             "instead of display(): its live elements if it has "
+                             "them, else its Vegas content, laid out as the "
+                             "ticker lays them out. Also writes the live "
+                             "elements' keys and columns to <output>.json")
+    parser.add_argument('--no-live', action='store_true',
+                        help="With --vegas: ignore live elements and render the "
+                             "plugin's ordinary Vegas content (for before/after)")
+    parser.add_argument('--timeline', type=int, default=0, metavar='ROWS',
+                        help="With --vegas: render ROWS rows, each the block a "
+                             "--timeline-step later as the ticker would update it "
+                             "in place (animated elements redrawn for that moment)")
+    parser.add_argument('--timeline-step', type=float, default=0.25, metavar='SECONDS',
+                        help="Seconds between --timeline rows (default 0.25)")
+    parser.add_argument('--timeline-update', action='store_true',
+                        help="With --timeline: run update() before each row and "
+                             "redraw every live element from the new data")
 
     args = parser.parse_args()
 
+    if args.timeline > 1 and args.no_live:
+        # A timeline shows live elements changing; plain content never does.
+        parser.error("--timeline shows live elements; it cannot be combined with --no-live")
+    if (args.timeline or args.no_live) and not args.vegas:
+        parser.error("--timeline and --no-live need --vegas")
+
     if not (MIN_DIMENSION <= args.width <= MAX_DIMENSION):
         print(f"Error: --width must be between {MIN_DIMENSION} and {MAX_DIMENSION} (got {args.width})")
         raise SystemExit(1)
@@ -145,6 +169,39 @@ def main() -> int:
         except Exception as e:
             logger.warning("update() raised: %s — continuing to display()", e)
 
+    if args.vegas:
+        Path(args.output).parent.mkdir(parents=True, exist_ok=True)
+
+    if args.vegas and args.timeline > 1:
+        from src.plugin_system.testing.vegas import render_vegas_timeline
+        image, rows = render_vegas_timeline(
+            plugin_instance, args.plugin, display_manager, steps=args.timeline,
+            step_seconds=args.timeline_step, run_update=args.timeline_update)
+        if image is None:
+            logger.error("Plugin '%s' has no Vegas content", args.plugin)
+            return 1
+        image.save(args.output)
+        logger.info("Saved a %d-row Vegas timeline (%dx%d) to %s",
+                    rows, image.width, image.height, args.output)
+        return 0
+
+    if args.vegas:
+        from src.plugin_system.testing.vegas import render_vegas_strip
+        block, layout = render_vegas_strip(
+            plugin_instance, args.plugin, display_manager, live=not args.no_live)
+        if block is None:
+            logger.error("Plugin '%s' has no Vegas content", args.plugin)
+            return 1
+        block.save(args.output)
+        sidecar = Path(args.output).with_suffix('.json')
+        sidecar.write_text(json.dumps(
+            {"width": block.width, "height": block.height,
+             "live_elements": [{"key": k, "x": x, "width": w} for x, k, w in layout]},
+            indent=2) + "\n", encoding="utf-8")
+        logger.info("Saved Vegas strip %dx%d (%d live element(s)) to %s and %s",
+                    block.width, block.height, len(layout), args.output, sidecar)
+        return 0
+
     # A plugin that declares several display modes usually renders nothing
     # useful without being told which one to draw: the scoreboards keep their
     # state on per-mode sub-managers and their no-argument path returns False.

scripts/reset_web_password.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""
+Turn the web interface's optional login off, for when the password is lost.
+
+Removes the password (and the key that signs login cookies) from the
+``web_auth`` section of ``config/config_secrets.json``. The interface is then
+open again, as it is before a password is ever set, and a new password can be
+set under General > Security. API tokens are kept unless ``--revoke-tokens``
+is given. Nothing else in the secrets file is touched, and the web service
+does not need a restart: it notices the change on the next request.
+
+Run it on the Pi, from any directory:
+
+    sudo python3 ~/LEDMatrix/scripts/reset_web_password.py
+
+``sudo`` because the secrets file is not readable by every user. The file
+keeps its owner and permissions.
+
+Another way in without the password: open the interface from the Pi itself
+(http://localhost:5000). Requests from the Pi are never asked to log in.
+"""
+import argparse
+import json
+import sys
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(PROJECT_ROOT))
+
+from src.config_manager_atomic import atomic_write_json  # noqa: E402
+
+SECTION = 'web_auth'   # web_interface/auth.py; not imported to keep Flask out
+LOGIN_KEYS = ('password_hash', 'session_secret', 'password_set_at')
+
+
+def reset(settings_file: Path, revoke_tokens: bool = False) -> str:
+    """Clear the login from ``settings_file`` (config_secrets.json).
+
+    Returns what was done. The message names the file and counts tokens; it
+    never includes anything read from the file.
+    """
+    if not settings_file.exists():
+        return f'{settings_file} does not exist, so no password is set. Nothing to do.'
+    with open(settings_file, 'r', encoding='utf-8') as fh:
+        data = json.load(fh)
+    if not isinstance(data, dict):
+        raise ValueError(f'{settings_file} does not hold a JSON object')
+
+    section = data.get(SECTION)
+    if not isinstance(section, dict):
+        return 'No web login password is set. Nothing to do.'
+
+    had_password = bool(section.get('password_hash'))
+    token_count = len(section.get('tokens') or [])
+    for key in LOGIN_KEYS:
+        section.pop(key, None)
+    if revoke_tokens:
+        section.pop('tokens', None)
+    if section:
+        data[SECTION] = section
+    else:
+        data.pop(SECTION, None)
+
+    if not had_password and not (revoke_tokens and token_count):
+        return 'No web login password is set. Nothing to do.'
+    atomic_write_json(settings_file, data)
+
+    done = []
+    if had_password:
+        done.append('Web login is off: the interface opens without a password. '
+                    'Set a new one under General > Security.')
+    if revoke_tokens and token_count:
+        done.append(f'Revoked {token_count} API token(s).')
+    elif token_count:
+        done.append(f'{token_count} API token(s) kept (use --revoke-tokens to remove them).')
+    return ' '.join(done)
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        description='Turn the LEDMatrix web login off (lost password recovery).')
+    parser.add_argument('--secrets', dest='settings_file', type=Path,
+                        default=PROJECT_ROOT / 'config' / 'config_secrets.json',
+                        help='secrets file (default: config/config_secrets.json '
+                             'in this LEDMatrix checkout)')
+    parser.add_argument('--revoke-tokens', action='store_true',
+                        help='also delete every API token')
+    args = parser.parse_args(argv)
+    settings_file = args.settings_file
+    try:
+        outcome = reset(settings_file, revoke_tokens=args.revoke_tokens)
+    except PermissionError:
+        print(f'Permission denied reading or writing {settings_file}. Run it with sudo.',
+              file=sys.stderr)
+        return 1
+    except (OSError, ValueError) as err:
+        print(f'Could not reset the web login: {err}', file=sys.stderr)
+        return 1
+    print(outcome)
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

scripts/sports_drift_report.py

@@ -0,0 +1,492 @@
+#!/usr/bin/env python3
+"""Report how far apart the nine scoreboards' copies of each method are.
+
+The sports consolidation (docs/SPORTS_UNIFICATION.md) moves shared code from
+the scoreboard plugins into ``src/common``. Byte-identical copies have mostly
+been moved; what is left has drifted, and is promoted one *method family* at a
+time by first making every copy identical ("reconcile, then promote"). This
+report is the progress measure for that: for every method in the tracked
+files it counts the copies and the distinct bodies among them, so a stage can
+say "``_is_game_really_over``: 5 variants -> 1" instead of remembering it.
+
+It reads a ledmatrix-plugins checkout and never fails a build: it is a report,
+not a gate. The monorepo's own ``scripts/check_sports_drift.py`` is the gate
+(it fails when a function that agrees across the plugins starts to differ).
+
+Definitions
+-----------
+family
+    One method name in one tracked file, across every class that defines it
+    and every plugin. ``sports.py::update`` covers ``SportsLive.update``,
+    ``SportsRecent.update`` and ``SportsUpcoming.update`` in all nine plugins.
+    Module-level functions are families too.
+copies
+    How many definitions the family has (plugin x class).
+plugins
+    How many of the nine plugins define it at least once.
+variants
+    Distinct bodies among the copies, compared as ASTs with docstrings,
+    comments, formatting, decorators and annotations ignored. A family is
+    reconciled when every class in it is down to one variant.
+per-class variants
+    The same count within one class role (``SportsLive.update`` across the
+    plugins). Class names are folded the way the plugins name them
+    (``SoccerScoreboardPlugin`` and ``UFCScoreboardPlugin`` are both
+    ``SScoreboardPlugin``), so manager.py lines up across sports.
+folded
+    Variants left after sport and league names are folded to a placeholder
+    (``self.nfl_live`` == ``self.nhl_live``, ``"NFL"`` == ``"NHL"``). The gap
+    between ``variants`` and ``folded`` is drift that is only naming.
+
+Usage
+-----
+    python scripts/sports_drift_report.py --plugins ../ledmatrix-plugins
+    python scripts/sports_drift_report.py --markdown        # for a CI summary
+    python scripts/sports_drift_report.py --json out.json   # machine-readable
+    python scripts/sports_drift_report.py --family sports.py::update
+
+``--plugins`` defaults to ``$LEDMATRIX_PLUGINS`` (a checkout root or its
+``plugins/`` directory, the same variable the core parity tests read). With no
+checkout it says so and exits 0.
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import collections
+import difflib
+import hashlib
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Dict, Iterable, List, Optional, Tuple
+
+#: The nine scoreboards the consolidation covers, by directory prefix.
+SPORTS = ("afl", "baseball", "basketball", "football", "hockey", "lacrosse",
+          "nrl", "soccer", "ufc")
+
+#: Files every scoreboard carries a copy of. sports.py and game_renderer.py
+#: are the consolidation's subject; manager.py (the BasePlugin host, the
+#: largest copy of all) joined the plan with the reconcile-then-promote
+#: method. ufc has no game_renderer.py (it draws fights in fight_renderer.py).
+DEFAULT_FILES = ("sports.py", "manager.py", "game_renderer.py")
+
+#: A family is "drifted" when it is widespread and has several bodies. The
+#: defaults match the review that introduced this report (at least 7 plugins,
+#: at least 3 variants).
+DEFAULT_MIN_PLUGINS = 7
+DEFAULT_MIN_VARIANTS = 3
+
+#: Sport, league and competition names that legitimately differ between the
+#: plugins. Only used for the ``folded`` column.
+SPORT_TOKENS = (
+    "afl", "nrl", "baseball", "basketball", "football", "hockey", "soccer",
+    "lacrosse", "ufc", "mma", "mlb", "milb", "nhl", "nfl", "nba", "wnba",
+    "ncaa", "ncaafb", "ncaam", "ncaaw", "ncaa_fb", "ncaa_baseball",
+    "ncaa_basketball", "ncaam_hockey", "ncaaw_hockey", "ncaam_lacrosse",
+    "ncaaw_lacrosse", "ncaam_basketball", "ncaaw_basketball", "epl",
+    "uefa", "mls", "laliga", "bundesliga", "seriea", "ligue1",
+)
+_TOKEN_RE = re.compile(
+    r"(?<![A-Za-z0-9])(" + "|".join(sorted(SPORT_TOKENS, key=len, reverse=True))
+    + r")(?![A-Za-z0-9])", re.IGNORECASE)
+_TOKEN_SET = {t.lower() for t in SPORT_TOKENS}
+_CAMEL_RE = re.compile(r"[A-Z]+(?![a-z])|[A-Z][a-z0-9]*|[a-z0-9]+|_")
+
+
+def fold(name: str) -> str:
+    """Replace sport and league names in an identifier or string with ``S``.
+
+    Both spellings the plugins use: snake_case (``nfl_live`` -> ``S_live``)
+    and CamelCase (``UFCScoreboardPlugin`` -> ``SScoreboardPlugin``).
+    """
+    name = _TOKEN_RE.sub("S", name)
+    # sub, not findall + join: characters between words (spaces, dots,
+    # braces in a log string) must survive, or distinct text folds together.
+    return _CAMEL_RE.sub(
+        lambda m: "S" if m.group(0).lower() in _TOKEN_SET else m.group(0), name)
+
+
+def _strip_docstring(body: List[ast.stmt]) -> List[ast.stmt]:
+    if (body and isinstance(body[0], ast.Expr)
+            and isinstance(body[0].value, ast.Constant)
+            and isinstance(body[0].value.value, str)):
+        return body[1:] or [ast.Pass()]
+    return body
+
+
+class _Canonical(ast.NodeTransformer):
+    """Drop what is not behaviour: docstrings, decorators, annotations."""
+
+    def _func(self, node):
+        self.generic_visit(node)
+        node.body = _strip_docstring(node.body)
+        node.decorator_list = []
+        node.returns = None
+        return node
+
+    visit_FunctionDef = _func
+    visit_AsyncFunctionDef = _func
+
+    def visit_ClassDef(self, node):
+        self.generic_visit(node)
+        node.body = _strip_docstring(node.body)
+        return node
+
+    def visit_arg(self, node):
+        node.annotation = None
+        return node
+
+    def visit_AnnAssign(self, node):
+        # ``x: T = v`` is ``x = v``; a bare ``x: T`` does nothing at runtime.
+        self.generic_visit(node)
+        if node.value is None:
+            return None
+        return ast.copy_location(
+            ast.Assign(targets=[node.target], value=node.value), node)
+
+
+class _Folded(_Canonical):
+    """Canonical, plus sport names folded out of identifiers and strings."""
+
+    def visit_Name(self, node):
+        node.id = fold(node.id)
+        return node
+
+    def visit_Attribute(self, node):
+        self.generic_visit(node)
+        node.attr = fold(node.attr)
+        return node
+
+    def visit_arg(self, node):
+        node = super().visit_arg(node)
+        node.arg = fold(node.arg)
+        return node
+
+    def visit_keyword(self, node):
+        self.generic_visit(node)
+        if node.arg:
+            node.arg = fold(node.arg)
+        return node
+
+    def visit_Constant(self, node):
+        if isinstance(node.value, str):
+            node.value = fold(node.value)
+        return node
+
+    def _func(self, node):
+        node = super()._func(node)
+        node.name = fold(node.name)
+        return node
+
+    visit_FunctionDef = _func
+    visit_AsyncFunctionDef = _func
+
+
+def _digest(node: ast.AST, transformer: ast.NodeTransformer) -> str:
+    # Re-parse a copy so the transformers never mutate the tree being walked.
+    clone = ast.parse(ast.unparse(node)).body[0]
+    clone = transformer.visit(clone)
+    # The function's own name is the family key, not part of its body.
+    if isinstance(clone, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        clone.name = "_"
+    return hashlib.sha256(ast.dump(clone).encode()).hexdigest()[:12]
+
+
+class Copy:
+    """One definition of a method (or module-level function) in one plugin."""
+
+    __slots__ = ("plugin", "cls", "name", "lines", "exact", "folded", "source")
+
+    def __init__(self, plugin, cls, name, lines, exact, folded, source=""):
+        self.plugin = plugin
+        self.cls = cls
+        self.name = name
+        self.lines = lines
+        self.exact = exact
+        self.folded = folded
+        self.source = source
+
+
+def collect_file(path: Path, plugin: str) -> List[Copy]:
+    """Every top-level function and class method in one file."""
+    text = path.read_text(encoding="utf-8", errors="replace")
+    try:
+        tree = ast.parse(text)
+    except SyntaxError as exc:
+        print(f"  ! {path}: {exc}", file=sys.stderr)
+        return []
+    out = []
+
+    def add(node, cls):
+        out.append(Copy(plugin, cls, node.name,
+                        node.end_lineno - node.lineno + 1,
+                        _digest(node, _Canonical()), _digest(node, _Folded()),
+                        ast.get_source_segment(text, node) or ""))
+
+    for node in tree.body:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            add(node, "<module>")
+        elif isinstance(node, ast.ClassDef):
+            for child in node.body:
+                if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    add(child, fold(node.name))
+    return out
+
+
+def resolve_plugins_dir(raw: Optional[str]) -> Optional[Path]:
+    """A checkout root or its plugins/ directory; None when there is neither."""
+    if not raw:
+        return None
+    root = Path(raw)
+    if (root / "plugins").is_dir():
+        root = root / "plugins"
+    if not any((root / f"{s}-scoreboard").is_dir() for s in SPORTS):
+        return None
+    return root
+
+
+def build(plugins_dir: Path, files: Iterable[str]) -> Dict[Tuple[str, str], List[Copy]]:
+    """{(file, method name): [Copy, ...]} across the nine scoreboards."""
+    families: Dict[Tuple[str, str], List[Copy]] = collections.defaultdict(list)
+    for fname in files:
+        for sport in SPORTS:
+            path = plugins_dir / f"{sport}-scoreboard" / fname
+            if path.is_file():
+                for copy in collect_file(path, sport):
+                    families[(fname, copy.name)].append(copy)
+    return families
+
+
+def summarise(key: Tuple[str, str], copies: List[Copy]) -> dict:
+    """The numbers for one family."""
+    per_class = collections.defaultdict(list)
+    for c in copies:
+        per_class[c.cls].append(c)
+    classes = []
+    for cls, members in sorted(per_class.items()):
+        groups = collections.defaultdict(list)
+        for c in members:
+            groups[c.exact].append(c.plugin)
+        classes.append({
+            "class": cls,
+            "copies": len(members),
+            "variants": len(groups),
+            "folded": len({c.folded for c in members}),
+            "groups": sorted((sorted(p) for p in groups.values()),
+                             key=lambda g: (-len(g), g)),
+        })
+    total_lines = sum(c.lines for c in copies)
+    # What promotion would remove: every copy but one per class role.
+    one_each = sum(max(c.lines for c in members) for members in per_class.values())
+    return {
+        "file": key[0],
+        "family": key[1],
+        "plugins": len({c.plugin for c in copies}),
+        "copies": len(copies),
+        "variants": len({(c.cls, c.exact) for c in copies}),
+        "folded": len({(c.cls, c.folded) for c in copies}),
+        "worst_class_variants": max(k["variants"] for k in classes),
+        "lines": total_lines,
+        "duplicated_lines": total_lines - one_each,
+        "classes": classes,
+    }
+
+
+def report(families, min_plugins: int, min_variants: int) -> dict:
+    rows = [summarise(k, v) for k, v in families.items()]
+    by_file = collections.defaultdict(list)
+    for r in rows:
+        by_file[r["file"]].append(r)
+    files = {}
+    for fname, frows in sorted(by_file.items()):
+        files[fname] = {
+            "families": len(frows),
+            "in_all_plugins": sum(1 for r in frows if r["plugins"] == len(SPORTS)),
+            "lines": sum(r["lines"] for r in frows),
+            "identical_duplicated_lines": sum(
+                r["duplicated_lines"] for r in frows if r["worst_class_variants"] == 1),
+        }
+    drifted = sorted(
+        (r for r in rows
+         if r["plugins"] >= min_plugins and r["variants"] >= min_variants),
+        key=lambda r: (-r["variants"], -r["lines"], r["file"], r["family"]))
+    identical = sorted(
+        (r for r in rows if r["copies"] >= 2 and r["worst_class_variants"] == 1),
+        key=lambda r: (-r["duplicated_lines"], r["file"], r["family"]))
+    # One body shared by every plugin but one: the cheapest reconciliations.
+    # "One" across the whole family: a class role whose odd one out is a
+    # different plugin from another role's is two outliers, not one.
+    one_outlier = sorted(
+        (r for r in rows
+         if r["plugins"] >= min_plugins and r["worst_class_variants"] == 2
+         and all(len(k["groups"]) < 2 or len(k["groups"][1]) == 1
+                 for k in r["classes"])
+         and len(_minorities(r)) == 1),
+        key=lambda r: (-r["duplicated_lines"], r["file"], r["family"]))
+    return {"files": files, "drifted": drifted, "identical": identical,
+            "one_outlier": one_outlier,
+            "rows": rows, "thresholds": {"min_plugins": min_plugins,
+                                         "min_variants": min_variants}}
+
+
+def _minorities(r) -> set:
+    """Every plugin in a minority body, across the family's class roles."""
+    return {p for k in r["classes"] for g in k["groups"][1:] for p in g}
+
+
+def _outlier(r) -> str:
+    """The plugin whose body differs, for a one-outlier family."""
+    return ", ".join(sorted(_minorities(r)))
+
+
+def _text(rep, top_identical: int) -> str:
+    out = []
+    out.append("Per file (all methods and module functions):")
+    for fname, f in rep["files"].items():
+        out.append(f"  {fname:<18} {f['families']:>4} families, "
+                   f"{f['in_all_plugins']:>3} in all {len(SPORTS)} plugins, "
+                   f"{f['lines']:>6} lines; identical copies beyond the first: "
+                   f"{f['identical_duplicated_lines']} lines")
+    t = rep["thresholds"]
+    out.append("")
+    out.append(f"Drifted families (in >= {t['min_plugins']} plugins, "
+               f">= {t['min_variants']} variants): {len(rep['drifted'])}")
+    out.append(f"  {'file::family':<58} {'plug':>4} {'copies':>6} {'var':>4} "
+               f"{'fold':>4} {'worst':>5} {'lines':>6}")
+    for r in rep["drifted"]:
+        name = f"{r['file']}::{r['family']}"
+        out.append(f"  {name:<58} {r['plugins']:>4} {r['copies']:>6} "
+                   f"{r['variants']:>4} {r['folded']:>4} "
+                   f"{r['worst_class_variants']:>5} {r['lines']:>6}")
+    out.append("")
+    out.append(f"One outlier (in >= {t['min_plugins']} plugins, every plugin but "
+               f"one agrees): {len(rep['one_outlier'])}")
+    for r in rep["one_outlier"]:
+        name = f"{r['file']}::{r['family']}"
+        out.append(f"  {name:<58} {r['plugins']:>4} plugins, differs in "
+                   f"{_outlier(r)}; {r['lines']} lines")
+    out.append("")
+    out.append(f"Identical in every copy (promote as-is), top {top_identical} "
+               f"by duplicated lines, of {len(rep['identical'])}:")
+    for r in rep["identical"][:top_identical]:
+        name = f"{r['file']}::{r['family']}"
+        out.append(f"  {name:<58} {r['plugins']:>4} plugins "
+                   f"{r['duplicated_lines']:>5} duplicated lines")
+    return "\n".join(out)
+
+
+def _markdown(rep, top_identical: int, source: str) -> str:
+    t = rep["thresholds"]
+    out = ["## Sports drift report", "",
+           f"Scoreboard copies read from `{source}`. Report only: this never fails "
+           "the build. See docs/SPORTS_UNIFICATION.md.", "",
+           "| File | Families | In all 9 | Lines | Identical duplicated lines |",
+           "|---|---:|---:|---:|---:|"]
+    for fname, f in rep["files"].items():
+        out.append(f"| `{fname}` | {f['families']} | {f['in_all_plugins']} | "
+                   f"{f['lines']} | {f['identical_duplicated_lines']} |")
+    out += ["", f"### Drifted families (in >= {t['min_plugins']} plugins, "
+            f">= {t['min_variants']} variants): {len(rep['drifted'])}", "",
+            "| Family | Plugins | Copies | Variants | Folded | Worst class | Lines |",
+            "|---|---:|---:|---:|---:|---:|---:|"]
+    for r in rep["drifted"]:
+        out.append(f"| `{r['file']}::{r['family']}` | {r['plugins']} | {r['copies']} | "
+                   f"{r['variants']} | {r['folded']} | {r['worst_class_variants']} | "
+                   f"{r['lines']} |")
+    out += ["", f"### One outlier (every plugin but one agrees): "
+            f"{len(rep['one_outlier'])}", "",
+            "| Family | Plugins | Differs in | Lines |", "|---|---:|---|---:|"]
+    for r in rep["one_outlier"]:
+        out.append(f"| `{r['file']}::{r['family']}` | {r['plugins']} | "
+                   f"{_outlier(r)} | {r['lines']} |")
+    out += ["", f"### Identical in every copy: {len(rep['identical'])} "
+            f"(top {top_identical} by duplicated lines)", "",
+            "| Family | Plugins | Duplicated lines |", "|---|---:|---:|"]
+    for r in rep["identical"][:top_identical]:
+        out.append(f"| `{r['file']}::{r['family']}` | {r['plugins']} | "
+                   f"{r['duplicated_lines']} |")
+    return "\n".join(out) + "\n"
+
+
+def _family_detail(rep, families, wanted: str, show_diff: bool) -> str:
+    """Which plugins share each body of one family; optionally the diffs.
+
+    The diff is against the body most plugins share (the first group), which
+    is where a reconciliation usually starts.
+    """
+    fname, _, family = wanted.partition("::")
+    for r in rep["rows"]:
+        if r["file"] == fname and r["family"] == family:
+            out = [f"{wanted}: {r['plugins']} plugins, {r['copies']} copies, "
+                   f"{r['variants']} variants ({r['folded']} after folding sport "
+                   f"names), {r['lines']} lines"]
+            copies = families[(fname, family)]
+            for k in r["classes"]:
+                out.append(f"  {k['class']}: {k['variants']} variant(s) "
+                           f"({k['folded']} folded)")
+                for g in k["groups"]:
+                    out.append(f"      {', '.join(g)}")
+                if not show_diff or len(k["groups"]) < 2:
+                    continue
+                by_plugin = {c.plugin: c for c in copies if c.cls == k["class"]}
+                base = by_plugin[k["groups"][0][0]]
+                for g in k["groups"][1:]:
+                    other = by_plugin[g[0]]
+                    out.extend(difflib.unified_diff(
+                        base.source.splitlines(), other.source.splitlines(),
+                        f"{base.plugin}-scoreboard/{fname}",
+                        f"{other.plugin}-scoreboard/{fname}", lineterm="", n=2))
+            return "\n".join(out)
+    return f"{wanted}: no such family"
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    ap.add_argument("--plugins", default=os.environ.get("LEDMATRIX_PLUGINS"),
+                    help="ledmatrix-plugins checkout (default: $LEDMATRIX_PLUGINS)")
+    ap.add_argument("--files", default=",".join(DEFAULT_FILES),
+                    help="comma-separated files to compare (default: %(default)s)")
+    ap.add_argument("--min-plugins", type=int, default=DEFAULT_MIN_PLUGINS)
+    ap.add_argument("--min-variants", type=int, default=DEFAULT_MIN_VARIANTS)
+    ap.add_argument("--top-identical", type=int, default=15)
+    ap.add_argument("--markdown", action="store_true",
+                    help="print a Markdown summary (for $GITHUB_STEP_SUMMARY)")
+    ap.add_argument("--json", metavar="PATH",
+                    help="also write the full report as JSON")
+    ap.add_argument("--family", action="append", default=[],
+                    help="show which plugins share each body, e.g. sports.py::update")
+    ap.add_argument("--diff", action="store_true",
+                    help="with --family, also diff each variant against the most common one")
+    args = ap.parse_args(argv)
+
+    plugins_dir = resolve_plugins_dir(args.plugins)
+    if plugins_dir is None:
+        msg = ("No ledmatrix-plugins checkout: pass --plugins or set "
+               "LEDMATRIX_PLUGINS. Nothing to report.")
+        print(f"_{msg}_\n" if args.markdown else msg)
+        return 0
+
+    files = [f.strip() for f in args.files.split(",") if f.strip()]
+    families = build(plugins_dir, files)
+    rep = report(families, args.min_plugins, args.min_variants)
+
+    if args.json:
+        with open(args.json, "w", encoding="utf-8") as fh:
+            json.dump(rep, fh, indent=2)
+            fh.write("\n")
+    if args.markdown:
+        print(_markdown(rep, args.top_identical, str(plugins_dir)), end="")
+    else:
+        print(_text(rep, args.top_identical))
+    for wanted in args.family:
+        print()
+        print(_family_detail(rep, families, wanted, args.diff))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/templates/dev_preview.html

@@ -247,6 +247,19 @@
                 </div>
             </details>
 
+            <!-- What to render: the plugin's screen, or its block of the Vegas strip -->
+            <div class="flex items-center gap-2">
+                <label for="viewSelect" class="text-xs whitespace-nowrap" style="color: var(--text-secondary);">View</label>
+                <select id="viewSelect" onchange="onConfigChange()"
+                        class="flex-1 px-2 py-1.5 rounded-lg text-xs"
+                        style="background: var(--bg-primary); color: var(--text-primary); border: 1px solid var(--border-color);"
+                        title="Vegas strip: the plugin's block of the Vegas ticker, laid out as the ticker lays it out">
+                    <option value="">Display</option>
+                    <option value="live">Vegas strip (live elements)</option>
+                    <option value="plain">Vegas strip (plain Vegas content)</option>
+                </select>
+            </div>
+
             <!-- Render buttons -->
             <div class="flex gap-2">
                 <button onclick="renderPlugin()" id="renderBtn"
@@ -489,6 +502,7 @@
                         width: width,
                         height: height,
                         mock_data: mockData,
+                        vegas: document.getElementById('viewSelect').value || null,
                     }),
                 });
 
@@ -510,8 +524,11 @@
                 updateZoom();
 
                 // Show render time
+                const live = data.live_elements;
                 document.getElementById('renderTimeText').textContent =
-                    `${data.render_time_ms}ms`;
+                    `${data.render_time_ms}ms` + (live ? ` · ${data.width}px strip, ` +
+                    `${live.length} live element(s)` +
+                    (live.length ? `: ${live.map(e => e.key).join(', ')}` : '') : '');
 
                 // Show warnings/errors
                 showMessages(data.errors || [], data.warnings || []);

scripts/utils/auto_update_verify.py

@@ -14,12 +14,21 @@ the same reason: the rollback cannot depend on packages the update changed.
 The updater leaves data/auto_update_pending.json:
 
     {"status": "pending", "old_head": ..., "new_head": ...,
-     "display_was_active": bool, "dependency_failures": [...], "created_at": ...}
+     "old_ref": "main" | "" (detached) | absent (older updaters),
+     "display_was_active": bool, "dependency_failures": [...],
+     "units_refreshed": bool (absent from older updaters), "created_at": ...}
 
 This moves its status to "verifying" and then to one of "success",
 "rolled_back" or "rollback_failed", with "reason" and "detail" saying why.
 The web interface reports that outcome and raises a banner for anything but
 success.
+
+"The display service is active" does not mean the panel is drawing: a render
+loop stuck inside a plugin leaves the service active and the panel frozen.
+Where the display writes a heartbeat (/run/ledmatrix, see
+src/display_watchdog.py), the display also has to keep it fresh, from the
+restarted process, to count as healthy. Where it never wrote one -- the code
+being updated predates it -- the check is what it always was.
 """
 import json
 import os
@@ -36,6 +45,14 @@ from pathlib import Path
 PENDING_NAME = 'auto_update_pending.json'
 REQUIREMENT_FILES = ('requirements.txt', 'web_interface/requirements.txt')
 WEB_HEALTH_URL = 'http://127.0.0.1:5000/api/v3/system/version'
+#: Written by the display's render loop every few seconds. A copy of
+#: src/display_watchdog.HEARTBEAT_PATH, not an import: this file runs as a
+#: copy made before the update and must not depend on the code it checks.
+HEARTBEAT_PATH = '/run/ledmatrix/display-heartbeat.json'
+#: How old the heartbeat may be. Well under STABLE_SECONDS: a display that
+#: draws its first frame and then freezes must go stale inside the window it
+#: has to stay healthy for, or the check would pass it.
+HEARTBEAT_FRESH_SECONDS = 30
 #: How long the services get to come up after a restart...
 HEALTH_TIMEOUT_SECONDS = 180
 #: ...and how long they must then stay up. Restart=on-failure makes a crash
@@ -58,6 +75,10 @@ BASH_CANDIDATES = ('/usr/bin/bash', '/bin/bash')
 #: ...and, like it, moves to the next one only when sudo refused the command
 #: line (permission_utils.SUDO_REFUSAL_PHRASES), never after pip itself ran.
 SUDO_REFUSAL_PHRASES = ('a password is required', 'is not allowed to run', 'no tty present')
+#: The root-owned helper that installed the update's systemd units
+#: (web_interface/unit_refresh.py); ``--restore`` puts the previous ones back.
+REFRESH_UNITS_PATH = '/usr/local/sbin/ledmatrix-refresh-units'
+UNIT_RESTORE_TIMEOUT_SECONDS = 90
 
 #: The longest one health check can take: restart and wait, roll back
 #: (diff, reset, reinstalls), restart and wait again. A wait's last poll can
@@ -65,7 +86,8 @@ SUDO_REFUSAL_PHRASES = ('a password is required', 'is not allowed to run', 'no t
 _WAIT_WORST_SECONDS = (HEALTH_TIMEOUT_SECONDS + STABLE_SECONDS + WEB_CHECK_TIMEOUT_SECONDS
                        + 2 * SYSTEMCTL_QUERY_TIMEOUT_SECONDS + POLL_SECONDS)
 WORST_CASE_SECONDS = (2 * (2 * RESTART_TIMEOUT_SECONDS + _WAIT_WORST_SECONDS)
-                      + GIT_TIMEOUT_SECONDS + GIT_RESET_TIMEOUT_SECONDS + PIP_BUDGET_SECONDS)
+                      + GIT_TIMEOUT_SECONDS + GIT_RESET_TIMEOUT_SECONDS + UNIT_RESTORE_TIMEOUT_SECONDS
+                      + PIP_BUDGET_SECONDS)
 
 #: What a command that could not run at all reports: its callers only read
 #: these three fields, the same ones a completed subprocess has.
@@ -113,16 +135,35 @@ def _short(sha):
     return (sha or 'unknown')[:7]
 
 
+def _read_heartbeat(path=HEARTBEAT_PATH):
+    """The display's heartbeat, or None when there is none (or it is unreadable)."""
+    try:
+        with open(path, 'r', encoding='utf-8') as f:
+            data = json.load(f)
+    except (OSError, ValueError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
 class Verifier:
     def __init__(self, project_root, run=subprocess.run, sleep=time.sleep,
-                 clock=time.monotonic, web_responds=_web_responds, log=None):
+                 clock=time.monotonic, web_responds=_web_responds, log=None,
+                 read_heartbeat=_read_heartbeat):
         self.project_root = Path(project_root)
         self.pending_file = pending_path(project_root)
         self.run = run
         self.sleep = sleep
+        # Monotonic, and compared with the heartbeat's own monotonic stamp:
+        # CLOCK_MONOTONIC is one clock for every process on the machine.
         self.clock = clock
         self.web_responds = web_responds
         self.log = log or (lambda msg: print(f'[auto-update-verify] {msg}', flush=True))
+        self.read_heartbeat = read_heartbeat
+        #: Whether the display was writing a heartbeat before the update.
+        self.expect_heartbeat = False
+        #: When the display was last restarted; an older heartbeat is the
+        #: previous process's, not proof the new one draws.
+        self.display_restarted_at = None
 
     def _run(self, args, timeout=GIT_TIMEOUT_SECONDS):
         try:
@@ -154,18 +195,32 @@ class Verifier:
         ok = True
         # A display the user had stopped stays stopped.
         if display:
+            self.display_restarted_at = self.clock()
             ok = self.restart('ledmatrix') and ok
         return self.restart('ledmatrix-web') and ok
 
+    def display_drawing(self):
+        """True while the restarted display keeps its heartbeat fresh."""
+        data = self.read_heartbeat()
+        mono = data.get('mono') if data else None
+        if not isinstance(mono, (int, float)) or isinstance(mono, bool):
+            return False
+        if self.display_restarted_at is not None and mono < self.display_restarted_at:
+            return False  # still the process from before the restart
+        return self.clock() - mono <= HEARTBEAT_FRESH_SECONDS
+
     def wait_healthy(self, display):
         """None once the services are up and stay up, else what went wrong."""
         deadline = self.clock() + HEALTH_TIMEOUT_SECONDS + STABLE_SECONDS
         healthy_since = baseline = None
         web = disp = False
+        active = drawing = True
         count_known = True
         while self.clock() < deadline:
             web = self.web_responds()
-            disp = self.service_active('ledmatrix') if display else True
+            active = self.service_active('ledmatrix') if display else True
+            drawing = self.display_drawing() if (display and self.expect_heartbeat) else True
+            disp = active and drawing
             restarts = self.restart_count('ledmatrix') if display else None
             # Without a restart count a crash loop looks healthy between
             # attempts, so an unreadable count never counts as stable.
@@ -181,8 +236,11 @@ class Verifier:
         problems = []
         if not web:
             problems.append('the web interface did not respond')
-        if not disp:
+        if not active:
             problems.append('the display service did not stay running')
+        elif not drawing:
+            problems.append('the display service is running but its panel is not '
+                            'being drawn (no fresh heartbeat)')
         if web and disp and not count_known:
             problems.append("the display service's restart count could not be read")
         return '; '.join(problems) or 'the display service kept restarting'
@@ -225,6 +283,20 @@ class Verifier:
         if not old:
             return False, 'the commit to roll back to is unknown'
         requirements = self.changed_requirements(old, new) if new else list(REQUIREMENT_FILES)
+        # An update may have moved HEAD between main and a detached release
+        # tag (the stable/beta channels). Go back to where HEAD was -- the
+        # branch, or detached -- before resetting, or resetting would drag
+        # the wrong ref: main onto a release commit, or leave a device that
+        # was following main stuck on a detached one. No old_ref (an older
+        # updater wrote this file) means HEAD never moved between refs.
+        old_ref = pending.get('old_ref')
+        if old_ref is not None:
+            move = (['git', 'checkout', '--quiet', '--force', old_ref] if old_ref
+                    else ['git', 'checkout', '--quiet', '--force', '--detach', old])
+            result = self._run(move, timeout=GIT_RESET_TIMEOUT_SECONDS)
+            if result.returncode != 0:
+                return False, (f'"{" ".join(move)}" failed: '
+                               f'{(result.stderr or result.stdout or "").strip()}')
         # --hard: the updater refuses to run with local edits to tracked core
         # files (web_interface/auto_update.local_changes), so outside the
         # plugin folders the only thing this discards is the update. Edits
@@ -234,12 +306,26 @@ class Verifier:
         if result.returncode != 0:
             return False, (f'"git reset --hard {old}" failed: '
                            f'{(result.stderr or result.stdout or "").strip()}')
+        notes = []
+        # The update also installed its own systemd units: put the previous
+        # ones back before anything restarts onto the rolled-back code.
+        if pending.get('units_refreshed') and not self.restore_units():
+            notes.append('restoring the previous service settings failed; run '
+                         '"sudo ./scripts/install/install_service.sh" in the LEDMatrix folder')
         deadline = self.clock() + PIP_BUDGET_SECONDS
         failed = [rel for rel in requirements if not self.install_requirements(rel, deadline)]
         if failed:
-            return True, ('reinstalling the previous dependencies from ' + ', '.join(failed)
-                          + ' failed; run Install Base Requirements from the Tools tab')
-        return True, ''
+            notes.append('reinstalling the previous dependencies from ' + ', '.join(failed)
+                         + ' failed; run Install Base Requirements from the Tools tab')
+        return True, '; '.join(notes)
+
+    def restore_units(self):
+        """Reinstall the systemd units the update replaced. True on success."""
+        result = self._run(['sudo', '-n', REFRESH_UNITS_PATH, '--restore'],
+                           timeout=UNIT_RESTORE_TIMEOUT_SECONDS)
+        if result.returncode != 0:
+            self.log(f'restoring the previous systemd units failed: {(result.stderr or "").strip()}')
+        return result.returncode == 0
 
     # -- the check itself -------------------------------------------------
 
@@ -258,6 +344,10 @@ class Verifier:
         write_pending(self.pending_file, pending)
 
         display = bool(pending.get('display_was_active'))
+        # Read before anything restarts: the display still running is the
+        # pre-update code, and whether it writes a heartbeat decides whether
+        # the updated one must.
+        self.expect_heartbeat = display and self.read_heartbeat() is not None
         dependency_failures = pending.get('dependency_failures') or []
         if dependency_failures:
             # Never restart onto code whose packages did not install.

src/__init__.py

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

src/adaptive_layout.py

@@ -28,6 +28,7 @@ freetype.Face, so it drops straight into DisplayManager.draw_text().
 """
 
 import logging
+import weakref
 from collections import OrderedDict
 from dataclasses import dataclass
 from typing import Any, Dict, List, Optional, Sequence, Tuple, Union
@@ -332,9 +333,10 @@ class LayoutContext:
         # a plugin fitting changing text (a live game clock, a ticker) on a
         # 24/7 service would otherwise grow this without bound.
         self._fit_cache: "OrderedDict[Any, FitResult]" = OrderedDict()
-        # LRU-bounded (images are big). Entries hold a strong reference to
-        # the source image when keyed by id() so the id can't be recycled
-        # out from under the cache.
+        # LRU-bounded (images are big). An id()-keyed entry watches its
+        # source image through a weak reference and is dropped when the
+        # source is freed (see fit_image), so the id can't be recycled out
+        # from under the cache and the cache never keeps the source alive.
         self._image_cache: "OrderedDict[Any, Tuple[Any, Any]]" = OrderedDict()
 
     _IMAGE_CACHE_MAX = 64
@@ -536,8 +538,15 @@ class LayoutContext:
         cached per (image, box size, options) for this panel size.
 
         Prefer a stable ``cache_key`` (e.g. "logo:KC") for images that get
-        reloaded — the default id()-based key is safe (the entry pins the
-        source image) but misses across reloads of the same content.
+        reloaded — the default id()-based key misses across reloads of the
+        same content.
+
+        An id()-keyed entry lives only as long as its source image: it holds
+        a weak reference and is dropped when the source is freed. It used to
+        pin the source instead, so a plugin passing a freshly loaded image
+        each frame (``draw_image(Image.open(path), box)``, the documented
+        one-liner) never hit and kept the last 64 sources alive — ~64MB for
+        500x500 RGBA team logos, the median size under assets/sports.
         """
         from src.adaptive_images import fit_image as _fit_image
 
@@ -547,18 +556,31 @@ class LayoutContext:
         key = ("image", identity, img.size, box_w, box_h, mode,
                crop_to_ink, anchor, resample_name, upscale)
 
-        cached = self._image_cache.get(key)
-        if cached is not None:
-            self._image_cache.move_to_end(key)
+        cache = self._image_cache
+        cached = cache.get(key)
+        # An id()-keyed hit must still be this very image; the callback below
+        # normally removes a dead source's entry before its id can recur.
+        if cached is not None and (cache_key is not None or cached[1]() is img):
+            cache.move_to_end(key)
             return cached[0]
 
         result = _fit_image(img, (box_w, box_h), mode=mode,
                             crop_to_ink=crop_to_ink, anchor=anchor,
                             resample=resample, upscale=upscale)
-        # Pin the source only for id()-keyed entries (see docstring).
-        self._image_cache[key] = (result, img if cache_key is None else None)
-        while len(self._image_cache) > self._IMAGE_CACHE_MAX:
-            self._image_cache.popitem(last=False)
+        source = None
+        if cache_key is None:
+            def _forget(ref: Any, key: Any = key) -> None:
+                entry = cache.get(key)
+                if entry is not None and entry[1] is ref:
+                    cache.pop(key, None)
+            try:
+                source = weakref.ref(img, _forget)
+            except TypeError:
+                # Not weak-referenceable: pin it, as before.
+                source = lambda img=img: img  # noqa: E731
+        cache[key] = (result, source)
+        while len(cache) > self._IMAGE_CACHE_MAX:
+            cache.popitem(last=False)
         return result
 
     # ---- text utilities ------------------------------------------------

src/background_data_service.py

@@ -27,6 +27,14 @@ from concurrent.futures import ThreadPoolExecutor
 import pytz
 from src.cache_manager import CacheManager
 from src.common.json_body import response_json
+from src.common.fetch_service import (
+    current_plugin_id,
+    fetch_get,
+    get_fetch_service,
+    plugin_scope,
+    share_connection_pool,
+)
+from src.common.espn_payload import is_espn_scoreboard_url, slim_scoreboard_payload
 from src.common.espn_dates import (
     RANGE_RETRY_SECONDS,
     _note_range_rejected,
@@ -76,8 +84,15 @@ class FetchRequest:
     # the cache with the callbacks suppressed -- joiners waiting forever for a
     # fetch that did, in fact, succeed.
     commit_claimed: bool = False
+    # Trim an ESPN scoreboard response before it is cached and delivered
+    # (src/common/espn_payload.py). Set by whoever created the request; a
+    # submitter that joins the fetch gets the same payload.
+    slim_payload: bool = True
     result: Optional[Any] = None
     error: Optional[str] = None
+    # The plugin that submitted the request, so the fetch service counts the
+    # worker's requests against it (fetch_service, caller identity).
+    owner: Optional[str] = None
 
 @dataclass
 class FetchResult:
@@ -119,6 +134,12 @@ class _ConnectionRetryingSession:
     def __init__(self, session):
         self._session = session
 
+    @property
+    def fetch_identity_session(self):
+        """The wrapped Session, whose headers and adapter the fetch service
+        reads to key this request (src/common/fetch_service.py)."""
+        return self._session
+
     def get(self, *args, **kwargs):
         for attempt in range(self.ATTEMPTS):
             try:
@@ -196,9 +217,12 @@ class BackgroundDataService:
         # connection errors three times, a dead network cost up to 16
         # connection attempts per request and held one of the few worker
         # threads for all of them.
+        #
+        # The adapter is the fetch service's shared no-retry one: the same
+        # max_retries=0, with the connection pool shared with the other core
+        # sessions that do not retry (the odds managers).
         self.session = requests.Session()
-        self.session.mount('http://', requests.adapters.HTTPAdapter(max_retries=0))
-        self.session.mount('https://', requests.adapters.HTTPAdapter(max_retries=0))
+        share_connection_pool(self.session, max_retries=0)
         
         # Default headers: core's shared set (real User-Agent, no hand-set
         # Accept-Encoding) -- see src/common/api_helper.py.
@@ -230,7 +254,8 @@ class BackgroundDataService:
                            timeout: Optional[int] = None,
                            max_retries: int = 3,
                            priority: int = 1,
-                           callback: Optional[Callable] = None) -> str:
+                           callback: Optional[Callable] = None,
+                           slim_payload: bool = True) -> str:
         """
         Submit a background fetch request.
         
@@ -246,6 +271,11 @@ class BackgroundDataService:
             priority: Accepted for compatibility and ignored; requests run in
                 submission order.
             callback: Optional callback function when request completes
+            slim_payload: Drop the parts of an ESPN scoreboard response no
+                scoreboard reads (stat leaders, athlete cards, links,
+                headlines, highlights) before caching it; see
+                src/common/espn_payload.py. Only ESPN /scoreboard URLs are
+                touched. Pass False to cache the response whole.
             
         Returns:
             Request ID for tracking the fetch operation
@@ -299,6 +329,10 @@ class BackgroundDataService:
         if url.split('?', 1)[0].rstrip('/').endswith('/scoreboard'):
             params = clamp_espn_limit(params)
 
+        # Who asked, resolved on the submitting thread: the worker thread
+        # runs no plugin code, so it could not tell (fetch_service).
+        owner = current_plugin_id()
+
         # Create fetch request
         request = FetchRequest(
             id=request_id,
@@ -311,7 +345,9 @@ class BackgroundDataService:
             timeout=timeout or self.request_timeout,
             max_retries=max_retries,
             priority=priority,
-            callback=callback
+            callback=callback,
+            owner=owner,
+            slim_payload=slim_payload,
         )
         
         with self._lock:
@@ -330,6 +366,7 @@ class BackgroundDataService:
                 self.stats['deduplicated_requests'] = (
                     self.stats.get('deduplicated_requests', 0) + 1
                 )
+                get_fetch_service().note_merged(url, owner)
                 logger.info(
                     "Joined in-flight fetch %s for %s (cache_key=%s) instead of "
                     "starting a duplicate", existing_id, sport, cache_key
@@ -357,6 +394,11 @@ class BackgroundDataService:
         Returns:
             Fetch result with data or error information
         """
+        with plugin_scope(request.owner):
+            return self._fetch_data_worker_scoped(request)
+
+    def _fetch_data_worker_scoped(self, request: FetchRequest) -> FetchResult:
+        """_fetch_data_worker's body, run with the submitter as the caller."""
         start_time = time.time()
         result = FetchResult(request_id=request.id, success=False, retry_count=request.retry_count)
         
@@ -467,6 +509,13 @@ class BackgroundDataService:
                 )
                 return result
 
+            # Most of an ESPN scoreboard response is never drawn, and the
+            # cached copy stays parsed in the memory tier while it is fresh.
+            # Trimmed before the write so the cache, request.result and the
+            # callbacks all see the same payload. See src/common/espn_payload.py.
+            if request.slim_payload and is_espn_scoreboard_url(request.url):
+                slim_scoreboard_payload(data)
+
             # Cache the data
             self.cache_manager.set(request.cache_key, data)
             
@@ -621,8 +670,14 @@ class BackgroundDataService:
         
         for attempt in range(request.max_retries + 1):
             try:
-                response = self.session.get(
+                # Not shared with an identical request in flight: this
+                # service cancels and replaces fetches, and a replacement
+                # must not join the one it replaced. Its own cache_key
+                # dedup already merges what should be merged.
+                response = fetch_get(
+                    self.session,
                     request.url,
+                    share_in_flight=False,
                     params=request.params,
                     headers=request.headers,
                     timeout=request.timeout

src/backup_manager.py

@@ -88,7 +88,6 @@ _WIFI_REL = Path("config/wifi_config.json")
 _YTM_REL = Path("config/ytm_auth.json")
 _FONTS_REL = Path("assets/fonts")
 _PLUGIN_UPLOADS_REL = Path("assets/plugins")
-_STATE_REL = Path("data/plugin_state.json")
 
 #: The sections that are one file each: (section name, path, the
 #: RestoreOptions flag that restores it). create, preview, validate and
@@ -179,20 +178,27 @@ def _build_manifest(contents: List[str]) -> Dict[str, Any]:
 # ---------------------------------------------------------------------------
 
 
-def _plugins_directory(project_root: Path) -> Path:
-    """The plugin install directory: ``plugin_system.plugins_directory`` from
-    config/config.json (relative to ``project_root`` unless absolute), or
-    ``plugin-repos`` when the config does not say or cannot be read."""
-    configured: Any = None
+def _read_config(project_root: Path) -> Dict[str, Any]:
+    """config/config.json as a dict; empty when missing or unreadable."""
     try:
         with (project_root / _CONFIG_REL).open("r", encoding="utf-8") as f:
             config = json.load(f)
-        if isinstance(config, dict):
-            plugin_system = config.get("plugin_system")
-            if isinstance(plugin_system, dict):
-                configured = plugin_system.get("plugins_directory")
     except (OSError, json.JSONDecodeError):
-        pass
+        return {}
+    return config if isinstance(config, dict) else {}
+
+
+def _plugins_directory(project_root: Path,
+                       config: Optional[Dict[str, Any]] = None) -> Path:
+    """The plugin install directory: ``plugin_system.plugins_directory`` from
+    config/config.json (relative to ``project_root`` unless absolute), or
+    ``plugin-repos`` when the config does not say or cannot be read."""
+    if config is None:
+        config = _read_config(project_root)
+    configured: Any = None
+    plugin_system = config.get("plugin_system")
+    if isinstance(plugin_system, dict):
+        configured = plugin_system.get("plugins_directory")
     if not isinstance(configured, str) or not configured.strip():
         configured = "plugin-repos"
     path = Path(configured)
@@ -202,33 +208,23 @@ def _plugins_directory(project_root: Path) -> Path:
 def list_installed_plugins(project_root: Path) -> List[Dict[str, Any]]:
     """
     Return a list of currently-installed plugins suitable for the backup
-    manifest. Each entry has ``plugin_id`` and ``version``.
+    manifest. Each entry has ``plugin_id``, ``version`` and ``enabled``.
 
-    Reads ``data/plugin_state.json`` if present, then adds any plugin it
-    does not list from the ``manifest.json`` files in the configured plugin
-    directory (see :func:`_plugins_directory`).
+    The plugins are the ``manifest.json`` files in the configured plugin
+    directory (see :func:`_plugins_directory`), with the manifest's version;
+    ``enabled`` is config.json's flag by the display's rule (a missing flag
+    is disabled). A restore reinstalls every listed plugin and takes enabled
+    state from the restored config.json, so ``enabled`` is informational.
+
+    ``data/plugin_state.json`` is not read: it only ever repeated config's
+    enabled flags and the manifests' versions, and is retired (nothing
+    writes it any more). An old backup that listed a plugin only from that
+    file still restores it, since restore reads ``plugins.json`` as written.
     """
     plugins: Dict[str, Dict[str, Any]] = {}
+    config = _read_config(project_root)
 
-    state_file = project_root / _STATE_REL
-    if state_file.exists():
-        try:
-            with state_file.open("r", encoding="utf-8") as f:
-                state = json.load(f)
-            raw_plugins = state.get("states", {}) if isinstance(state, dict) else {}
-            if isinstance(raw_plugins, dict):
-                for plugin_id, info in raw_plugins.items():
-                    if not isinstance(info, dict):
-                        continue
-                    plugins[plugin_id] = {
-                        "plugin_id": plugin_id,
-                        "version": info.get("version") or "",
-                        "enabled": bool(info.get("enabled", True)),
-                    }
-        except (OSError, json.JSONDecodeError) as e:
-            logger.warning("Could not read plugin_state.json: %s", e)
-
-    plugins_root = _plugins_directory(project_root)
+    plugins_root = _plugins_directory(project_root, config)
     if plugins_root.exists():
         for entry in sorted(plugins_root.iterdir()):
             if not entry.is_dir():
@@ -247,10 +243,11 @@ def list_installed_plugins(project_root: Path) -> List[Dict[str, Any]]:
                 continue
             plugin_id = data.get("id") or entry.name
             if plugin_id not in plugins:
+                section = config.get(plugin_id)
                 plugins[plugin_id] = {
                     "plugin_id": plugin_id,
                     "version": data.get("version", ""),
-                    "enabled": True,
+                    "enabled": isinstance(section, dict) and bool(section.get("enabled", False)),
                 }
 
     return sorted(plugins.values(), key=lambda p: p["plugin_id"])

src/base_odds_manager.py

@@ -19,6 +19,8 @@ import json
 from typing import Dict, Any, Optional, List, cast
 
 from src.common.api_helper import DEFAULT_HTTP_HEADERS
+from src.common.fetch_service import fetch_get, share_connection_pool
+from src.common.json_body import response_json
 
 
 
@@ -59,7 +61,13 @@ class BaseOddsManager:
         # Deliberately no retry adapter, unlike api_helper: retries multiply
         # request_timeout, which is set to 5s precisely to stay inside that
         # budget. One try, then the cooldown below.
+        #
+        # Every scoreboard league manager builds one of these, so the session
+        # mounts the fetch service's shared no-retry adapter: the same single
+        # try, over one connection pool per host for all of them instead of
+        # one pool per instance.
         self.session = requests.Session()
+        share_connection_pool(self.session, max_retries=0)
         self.session.headers.update(DEFAULT_HTTP_HEADERS)
         
         # Configuration with defaults
@@ -139,7 +147,7 @@ class BaseOddsManager:
             if _is_no_odds_marker(cached_data):
                 self.logger.debug("Cached no-odds marker for %s", cache_key)
                 return None
-            self.logger.debug(f"Using cached odds from ESPN for {cache_key}")
+            self.logger.debug("Using cached odds from ESPN for %s", cache_key)
             return cached_data
 
         if time.monotonic() < self._skip_network_until:
@@ -152,7 +160,7 @@ class BaseOddsManager:
                 self._skip_network_until - time.monotonic())
             return None
 
-        self.logger.debug(f"Cache miss - fetching fresh odds from ESPN for {cache_key}")
+        self.logger.debug("Cache miss - fetching fresh odds from ESPN for %s", cache_key)
 
         try:
             # Map league names to ESPN API format
@@ -166,23 +174,30 @@ class BaseOddsManager:
             
             espn_league = league_mapping.get(league, league)
             url = f"{self.base_url}/{sport}/leagues/{espn_league}/events/{event_id}/competitions/{event_id}/odds"
-            self.logger.debug(f"Requesting odds from URL: {url}")
+            self.logger.debug("Requesting odds from URL: %s", url)
             
-            response = self.session.get(url, timeout=self.request_timeout)
+            # The response cache may answer only inside this caller's own
+            # interval, the age at which its cached odds expire anyway.
+            response = fetch_get(self.session, url, timeout=self.request_timeout,
+                                 cache_max_age=interval)
             response.raise_for_status()
-            raw_data = response.json()
+            raw_data = response_json(response)
 
             self._skip_network_until = 0.0   # reachable again
 
-            self.logger.debug(f"Received raw odds data from ESPN: {json.dumps(raw_data, indent=2)}")
+            # Guarded, not just %-style: the json.dumps argument would still be
+            # built for every response with DEBUG off.
+            if self.logger.isEnabledFor(logging.DEBUG):
+                self.logger.debug("Received raw odds data from ESPN: %s",
+                                  json.dumps(raw_data, indent=2))
             
             odds_data = self._extract_espn_data(raw_data)
             if odds_data:
-                self.logger.debug(f"Successfully extracted odds data: {odds_data}")
+                self.logger.debug("Successfully extracted odds data: %s", odds_data)
                 self.cache_manager.set(cache_key, odds_data, ttl=interval)
-                self.logger.debug(f"Saved odds data to cache for {cache_key} with TTL {interval}s")
+                self.logger.debug("Saved odds data to cache for %s with TTL %ss", cache_key, interval)
             else:
-                self.logger.debug(f"No odds data available for {cache_key}")
+                self.logger.debug("No odds data available for %s", cache_key)
                 # Cache the absence too, so the game is not re-requested
                 # on every update until the interval passes.
                 self.cache_manager.set(cache_key, {"no_odds": True}, ttl=interval)
@@ -216,12 +231,12 @@ class BaseOddsManager:
         Returns:
             Formatted odds data dictionary or None
         """
-        self.logger.debug(f"Extracting ESPN odds data. Data keys: {list(data.keys())}")
+        self.logger.debug("Extracting ESPN odds data. Data keys: %s", list(data.keys()))
         
         if "items" in data and data["items"]:
-            self.logger.debug(f"Found {len(data['items'])} items in odds data")
+            self.logger.debug("Found %d items in odds data", len(data['items']))
             item = data["items"][0]
-            self.logger.debug(f"First item keys: {list(item.keys())}")
+            self.logger.debug("First item keys: %s", list(item.keys()))
             
             # The ESPN API returns odds data directly in the item, not in a
             # providers array. ESPN sends explicit JSON nulls for absent
@@ -244,13 +259,17 @@ class BaseOddsManager:
                                     .get("pointSpread") or {}).get("value")
                 }
             }
-            self.logger.debug(f"Returning extracted odds data: {json.dumps(extracted_data, indent=2)}")
+            if self.logger.isEnabledFor(logging.DEBUG):
+                self.logger.debug("Returning extracted odds data: %s",
+                                  json.dumps(extracted_data, indent=2))
             return extracted_data
         
         # Check if this is a valid empty response or an unexpected structure
         if "count" in data and data["count"] == 0 and "items" in data and data["items"] == []:
             # This is a valid empty response - no odds available for this game
-            self.logger.debug(f"No odds available for this game. Response: {json.dumps(data, indent=2)}")
+            if self.logger.isEnabledFor(logging.DEBUG):
+                self.logger.debug("No odds available for this game. Response: %s",
+                                  json.dumps(data, indent=2))
             return None
         else:
             # This is an unexpected response structure

src/cache/disk_cache.py

@@ -4,6 +4,7 @@ Disk Cache
 Handles persistent disk-based caching with atomic writes and error recovery.
 """
 
+import hashlib
 import json
 import math
 import os
@@ -14,7 +15,7 @@ import tempfile
 import logging
 import threading
 import zlib
-from typing import Dict, Any, Optional, Protocol
+from typing import Dict, Any, Optional, Protocol, Tuple
 from datetime import datetime
 
 from src.common.path_safety import safe_path_component
@@ -31,6 +32,35 @@ except ImportError:  # pragma: no cover - exercised on hosts without the wheel
 # useful, and a half-written file was never useful.
 _ORPHAN_TEMP_MAX_AGE_SECONDS = 3600
 
+# Longest key, in UTF-8 bytes, used verbatim as a filename stem. ext4 caps a
+# name at 255 bytes and set()'s temp file is ".<stem>.json.<8 random>", 15
+# bytes longer than the stem, so anything near the cap could never be written:
+# the calendar plugin's key joins every calendar id and passed 300 bytes on a
+# real install, failing every write with ENAMETOOLONG. Longer keys keep this
+# many bytes as a readable prefix and end in a hash of the whole key.
+_MAX_KEY_FILENAME_BYTES = 200
+_KEY_HASH_CHARS = 16
+
+
+def _filename_stem(key: str) -> str:
+    """The filename stem for a key that is already a safe path component.
+
+    Short keys are used as they are, so every file already on disk keeps its
+    name. A long one becomes its first bytes plus a hash of the full key: the
+    prefix keeps the stem recognisable (and keeps the data-type words that
+    cleanup's retention lookup reads from it), the hash keeps two keys that
+    share a long prefix apart. The result is itself short, so a stem read back
+    from a filename -- which is how the web UI names a key it deletes -- maps to
+    the same file.
+    """
+    encoded = key.encode('utf-8')
+    if len(encoded) <= _MAX_KEY_FILENAME_BYTES:
+        return key
+    digest = hashlib.sha256(encoded).hexdigest()[:_KEY_HASH_CHARS]
+    keep = _MAX_KEY_FILENAME_BYTES - _KEY_HASH_CHARS - 1
+    prefix = encoded[:keep].decode('utf-8', errors='ignore')
+    return f"{prefix}-{digest}"
+
 
 
 class CacheStrategyProtocol(Protocol):
@@ -111,18 +141,91 @@ _HEAD_RE = re.compile(
 )
 
 
-def _stale_from_head(head: bytes, max_age: Optional[int], now: float) -> bool:
+# UNCHANGED RE-SAVES: THE FILE'S MTIME CARRIES THE NEWER TIMESTAMP
+# ----------------------------------------------------------------
+# Plugins re-save unchanged API data every update cycle, and every one of
+# those saves was a full rewrite on the SD card. DiskCache.set skips the write
+# when the payload matches the last one it wrote for the key -- but
+# CacheManager.set stamps each record with time.time(), so for set() the
+# payload never matched and the skip never fired.
+#
+# The digest now leaves out a header-first record's timestamp, so an unchanged
+# set() is skipped. What the skip must not do is make the record look older
+# than it is: the timestamp inside the file is from the last real write, and
+# a reader in another process (the web interface, with memory_ttl=0) or after
+# a restart would call fresh data stale. So the newer timestamp goes where it
+# costs no data write -- the file's mtime -- and readers take a record's age
+# from the newer of the two. The invariant that makes that safe:
+#
+#   a file's mtime is the timestamp of the newest record saved for its key
+#
+#   real write  mtime is set to the record's own timestamp, so a record saved
+#               with an old timestamp (data as of some earlier time) cannot
+#               borrow freshness from the moment it hit the disk
+#   skip        mtime is set to the skipped record's timestamp -- exactly what
+#               a rewrite would have stored, without the rewrite
+#
+# Readers of the on-disk timestamp, all of which go through _effective_timestamp:
+# DiskCache.get (the header check and the full parse; it also returns the
+# record with 'timestamp' set to the effective value, so CacheManager.get's
+# max_age path, the memory tier hydrated from disk, and any plugin reading
+# record['timestamp'] all see it). Readers that use mtime alone already see the
+# newer value: the retention sweep below, CacheManager.list_cache_files (the
+# web UI's cache list). Nothing else opens cache files: web_interface and
+# scripts reach them only through CacheManager.
+#
+# Something other than this class can also move an mtime forward -- a copy
+# without -p, an rsync without -t, a `touch`. (backup_manager.py does not
+# back up or restore the cache directory, so the in-tree restore cannot.) That
+# must not make old data fresh, so the lift is bounded: a reader never takes
+# the mtime as more than _MAX_TIMESTAMP_LIFT past the embedded timestamp, and
+# set() rewrites the file for real once a skip would need more than that, so
+# an honest lift never reaches the bound. A file copied a day after it was
+# written therefore reads at most an hour fresher than its contents say, and a
+# 30-second live-score record from yesterday stays stale. CacheManager.set
+# records written before this change have mtime == write time == embedded
+# timestamp, give or take the write itself, and read exactly as before; a
+# file an older version wrote or touched later than its embedded timestamp
+# says reads at most the same hour fresher, once, until it is next saved.
+
+#: Longest a skipped write may stand in for a real one, and so the furthest a
+#: file's mtime is ever trusted past the record's own timestamp. Unchanged data
+#: is rewritten at least this often, at most once an hour per key instead of
+#: once per update cycle.
+_MAX_TIMESTAMP_LIFT = 3600.0
+
+
+def _record_timestamp(value: Any) -> Optional[float]:
+    """A record's timestamp as a finite float, or None if it has no usable one."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    value = float(value)
+    return value if math.isfinite(value) else None
+
+
+def _effective_timestamp(embedded: float, mtime: Optional[float]) -> float:
+    """When a record was last saved: its timestamp, or the file's mtime if a
+    later unchanged save moved that forward -- never by more than
+    _MAX_TIMESTAMP_LIFT. See "UNCHANGED RE-SAVES" above."""
+    if mtime is None:
+        return embedded
+    return max(embedded, min(mtime, embedded + _MAX_TIMESTAMP_LIFT))
+
+
+def _stale_from_head(head: bytes, max_age: Optional[int], now: float,
+                     mtime: Optional[float] = None) -> bool:
     """True when a record's header alone shows it has expired.
 
     Mirrors the expiry rule in DiskCache.get: a per-entry ttl wins over the
     caller's max_age, and no limit at all means never stale. False whenever the
-    header cannot be read, so the full parse decides as it always did.
+    header cannot be read, so the full parse decides as it always did. ``mtime``
+    is the file's, which may carry a newer save than the header does.
     """
     match = _HEAD_RE.match(head)
     if not match:
         return False
     try:
-        timestamp = float(match.group(1))
+        timestamp = _effective_timestamp(float(match.group(1)), mtime)
         limit = max_age
         if match.group(2) is not None:
             ttl = float(match.group(2))
@@ -179,7 +282,7 @@ else:
 # --------------------------------------------
 # The display service runs as root and the web interface as the installing
 # user, and the web interface reads records only the display writes
-# (display_current_state, display_on_demand_state, plugin_metrics:*). Files are
+# (display_current_state, display_on_demand_state, plugin_metrics_snapshot). Files are
 # written 0660, so the web interface can read one only through its group.
 #
 # The installers rely on the directory's setgid bit to set that group. That is
@@ -248,11 +351,14 @@ class DiskCache:
         self.cache_dir = cache_dir
         self.logger = logger or logging.getLogger(__name__)
         self._lock = threading.Lock()
-        # key -> adler32 of the last payload successfully written to the
-        # primary cache path; lets set() skip rewriting identical data
-        # (per-process only — worst case another process rewrites, never
-        # a missed write). Guarded by _lock.
-        self._write_digests: Dict[str, int] = {}
+        # key -> what set() last put at the primary cache path: the adler32 of
+        # the payload (less a header-first timestamp), the timestamp the file
+        # holds (None for records without one), and the file's inode and size.
+        # Lets set() skip rewriting identical data. Per-process only, and the
+        # inode/size check means another process's write is never mistaken
+        # for ours -- worst case a redundant write, never a missed one.
+        # Guarded by _lock.
+        self._write_digests: Dict[str, Tuple[int, Optional[float], int, int]] = {}
     
     def get_cache_path(self, key: str) -> Optional[str]:
         """
@@ -267,6 +373,8 @@ class DiskCache:
         derives them), so rejecting anything with a path component turns
         away only inputs that could never have been written here.
 
+        A key too long to be a filename is shortened by _filename_stem.
+
         Args:
             key: Cache key
 
@@ -280,7 +388,7 @@ class DiskCache:
         if safe_key is None:
             self.logger.warning("Rejected unsafe cache key %r", key)
             return None
-        return os.path.join(self.cache_dir, f"{safe_key}.json")
+        return os.path.join(self.cache_dir, f"{_filename_stem(safe_key)}.json")
     
     def get(self, key: str, max_age: Optional[int] = 300) -> Optional[Dict[str, Any]]:
         """
@@ -301,32 +409,41 @@ class DiskCache:
         try:
             with self._lock:
                 with open(cache_path, 'rb') as f:
+                    # The open file's mtime, not the path's: the file a skipped
+                    # write touched is the one being read.
+                    mtime = os.fstat(f.fileno()).st_mtime
                     # Decide staleness from the header before paying for the
                     # parse. A stale read is the common case for the biggest
                     # records (a season schedule is re-fetched when its cache
                     # expires), and parsing 53MB to throw it away held the GIL
                     # for ~1.8s -- a visible freeze on the panel.
-                    if _stale_from_head(f.read(_HEAD_BYTES), max_age, time.time()):
+                    if _stale_from_head(f.read(_HEAD_BYTES), max_age, time.time(), mtime):
                         return None
                     f.seek(0)
                     record = _loads(f.read())
-            
-            # Determine record timestamp (prefer embedded, else file mtime)
+
+            # Determine record timestamp: the embedded one, moved forward by a
+            # later unchanged save if there was one (see "UNCHANGED RE-SAVES"),
+            # else the file mtime.
             record_ts = None
             if isinstance(record, dict):
                 record_ts = record.get('timestamp')
             if record_ts is None:
-                try:
-                    record_ts = os.path.getmtime(cache_path)
-                except OSError:
-                    record_ts = None
-            
-            if record_ts is not None:
-                try:
-                    record_ts = float(record_ts)
-                except (TypeError, ValueError):
-                    record_ts = None
-            
+                record_ts = mtime
+            else:
+                embedded_ts = _record_timestamp(record_ts)
+                if embedded_ts is None:
+                    try:
+                        record_ts = float(record_ts)
+                    except (TypeError, ValueError):
+                        record_ts = None
+                else:
+                    record_ts = _effective_timestamp(embedded_ts, mtime)
+                    if record_ts != embedded_ts:
+                        # Hand the record back as a rewrite would have left it,
+                        # so callers that age it themselves agree with us.
+                        record['timestamp'] = record_ts
+
             now = time.time()
 
             # An explicit per-entry ttl wins over the caller's max_age. The
@@ -403,7 +520,12 @@ class DiskCache:
             self.logger.warning("Cache data for key '%s' not serializable: %s", key, e)
             return
 
-        digest = zlib.adler32(payload)
+        timestamp = _record_timestamp(data.get('timestamp')) if isinstance(data, dict) else None
+        # A header-first record (CacheManager.set's layout) is compared without
+        # its timestamp, which differs on every save; see "UNCHANGED RE-SAVES".
+        # Any other layout is compared whole, as before.
+        head = _HEAD_RE.match(payload) if timestamp is not None else None
+        digest = zlib.adler32(memoryview(payload)[head.end(1):] if head else payload)
 
         try:
             # Atomic write to avoid partial/corrupt files
@@ -411,16 +533,10 @@ class DiskCache:
                 # Skip the disk entirely when this exact payload was already
                 # written for this key (plugins re-save unchanged API data
                 # every update cycle — each write is real SD-card wear).
-                # Refresh the file mtime so records that rely on it for TTL
-                # (no embedded 'timestamp') don't expire early; a metadata
-                # touch is journal-cheap compared to rewriting the data.
-                if self._write_digests.get(key) == digest:
-                    try:
-                        os.utime(cache_path, None)
-                        return
-                    except OSError:
-                        # File vanished or perms changed — fall through and write
-                        self._write_digests.pop(key, None)
+                # A metadata touch is journal-cheap compared to rewriting
+                # the data.
+                if self._skip_unchanged(key, cache_path, digest, timestamp):
+                    return
 
                 tmp_dir = os.path.dirname(cache_path)
                 # Try to create temp file in cache directory first
@@ -458,7 +574,7 @@ class DiskCache:
                                 # opened it in between was refused.
                                 _share_open_file(tmp_file.fileno(), _shared_group(tmp_dir))
                             os.replace(tmp_path, cache_path)
-                            self._write_digests[key] = digest
+                            self._remember_write(key, cache_path, digest, timestamp)
                         finally:
                             if os.path.exists(tmp_path):
                                 try:
@@ -471,13 +587,13 @@ class DiskCache:
                             with open(cache_path, 'wb') as cache_file:
                                 cache_file.write(payload)
                                 _share_open_file(cache_file.fileno(), _shared_group(tmp_dir))
-                            self._write_digests[key] = digest
+                            self._remember_write(key, cache_path, digest, timestamp)
                             self.logger.debug("Wrote cache for %s directly (non-atomic)", key)
                         except (IOError, OSError, PermissionError) as write_error:
                             # If direct write also fails, try fallback location
                             self.logger.warning("Direct write failed for key '%s' to %s: %s", key, cache_path, write_error)
                             raise  # Re-raise to trigger fallback logic
-                except (IOError, OSError, PermissionError):
+                except (IOError, OSError, PermissionError) as primary_error:
                     # Attempt one-time fallback write to user's home cache directory
                     try:
                         # Try user's home cache directory as fallback
@@ -503,11 +619,14 @@ class DiskCache:
                         self.logger.debug("Fallback cache write also failed for key '%s': %s", key, e2)
                     
                     # If all write attempts failed, log warning but don't raise exception
-                    # Cache is a performance optimization, not critical for operation
+                    # Cache is a performance optimization, not critical for operation.
+                    # Name the real error: this used to say "permission denied"
+                    # whatever happened, which sent a too-long filename off to
+                    # be debugged as a directory-ownership problem.
                     self.logger.warning(
-                        "Could not write cache for key '%s' to %s (permission denied). "
+                        "Could not write cache for key '%s' to %s (%s). "
                         "Cache will be unavailable for this key, but application will continue.",
-                        key, cache_path
+                        key, cache_path, primary_error.strerror or primary_error
                     )
                     return  # Exit gracefully without raising exception
         
@@ -520,6 +639,66 @@ class DiskCache:
             )
             return  # Exit gracefully without raising exception
     
+    def _skip_unchanged(self, key: str, cache_path: str, digest: int,
+                        timestamp: Optional[float]) -> bool:
+        """Stand in for a write of an unchanged record by touching the file.
+
+        True when the file already holds this record bar its timestamp and the
+        touch landed; False means write it. The touch sets mtime to the
+        record's timestamp -- what a rewrite would have stored -- or to now
+        for a record without one, whose age readers already take from mtime.
+        Caller holds _lock.
+        """
+        last = self._write_digests.get(key)
+        if last is None or last[0] != digest:
+            return False
+        _, written_ts, ino, size = last
+        if (timestamp is None) != (written_ts is None):
+            return False
+        if timestamp is not None and written_ts is not None:
+            # Never backwards (a rewrite would make the record older), and
+            # never further than readers will trust the mtime: past that the
+            # record is rewritten, so its own timestamp catches up.
+            if not written_ts <= timestamp <= written_ts + _MAX_TIMESTAMP_LIFT:
+                return False
+        try:
+            st = os.stat(cache_path)
+            if (st.st_ino, st.st_size) != (ino, size):
+                # Replaced since our write (another process, a restore):
+                # its contents are not the ones the digest describes.
+                self._write_digests.pop(key, None)
+                return False
+            # Setting an explicit time needs the file's owner; a file someone
+            # else wrote fails here and is rewritten (as our own file) instead.
+            os.utime(cache_path, None if timestamp is None else (timestamp, timestamp))
+            return True
+        except OSError:
+            # File vanished or perms changed — fall through and write
+            self._write_digests.pop(key, None)
+            return False
+
+    def _remember_write(self, key: str, cache_path: str, digest: int,
+                        timestamp: Optional[float]) -> None:
+        """After a real write: pin mtime to the record's timestamp and note
+        what was written, so the next unchanged save can be skipped.
+
+        Pinning keeps a record saved with an older timestamp from looking as
+        fresh as the moment it was written (see "UNCHANGED RE-SAVES"); for
+        CacheManager.set's records the two differ only by the write itself.
+        A timestamp in the future is left alone, mtime already being older.
+        Never raises: the data is on disk, and anything failing here only
+        costs the next save its skip. Caller holds _lock.
+        """
+        self._write_digests.pop(key, None)
+        try:
+            if timestamp is not None and timestamp <= time.time():
+                os.utime(cache_path, (timestamp, timestamp))
+            st = os.stat(cache_path)
+        except OSError as e:
+            self.logger.debug("Could not pin mtime of %s: %s", cache_path, e)
+            return
+        self._write_digests[key] = (digest, timestamp, st.st_ino, st.st_size)
+
     def clear(self, key: Optional[str] = None) -> None:
         """
         Clear cache entry or all entries.

src/cache_manager.py

@@ -37,13 +37,41 @@ from src.cache.disk_cache import DiskCache
 from src.cache.cache_strategy import CacheStrategy
 from src.cache.cache_metrics import CacheMetrics
 from src.logging_config import get_logger
-from src.deprecation import deprecated
 
 # Canonical implementation lives in src.cache.disk_cache; re-exported here
 # because this module's docstring documents it and external code may import
 # it from either path.
 from src.cache.disk_cache import DateTimeEncoder  # noqa: F401 - deliberate re-export
 
+# CacheManager.config_manager not built yet (None means "not available").
+_UNSET: Any = object()
+
+
+def _outlived(record: Any, max_age: Optional[float], now: float) -> bool:
+    """Whether a record's own timestamp puts it past max_age.
+
+    The memory tier times an entry from when it was put there, and a record
+    loaded from disk is put there when it is read, not when it was written: a
+    record 290 s old, read after a restart, could be served for another
+    max_age from memory. This is the age check DiskCache.get makes, with the
+    same rule that a stored ttl wins over the caller's max_age. A record that
+    carries no timestamp is left to the memory tier's own clock.
+    """
+    if not isinstance(record, dict):
+        return False
+    stored_ttl = record.get('ttl')
+    if isinstance(stored_ttl, (int, float)) and not isinstance(stored_ttl, bool) \
+            and stored_ttl >= 0:
+        max_age = stored_ttl
+    stamp = record.get('timestamp')
+    if max_age is None or stamp is None or isinstance(stamp, bool):
+        return False
+    try:
+        return now - float(stamp) > max_age
+    except (TypeError, ValueError):
+        return False
+
+
 class CacheManager:
     """Manages caching of API responses to reduce API calls."""
 
@@ -74,21 +102,19 @@ class CacheManager:
             self.logger.error("Could not find or create a writable cache directory. Caching will be disabled.")
             self.cache_dir = None
 
-        # Initialize config manager for sport-specific intervals
-        try:
-            from src.config_manager import ConfigManager
-            self.config_manager: Optional[Any] = ConfigManager()
-            self.config_manager.load_config()
-        except ImportError:
-            self.config_manager: Optional[Any] = None
-            self.logger.warning("ConfigManager not available, using default cache intervals")
-        
+        # The config manager is built on first use of self.config_manager; see
+        # the property. Nothing in the cache reads it any more.
+        self._config_manager: Any = _UNSET
+        self._config_manager_lock = threading.Lock()
+
         # Initialize cache components using composition
         self._memory_cache_component = MemoryCache(
             max_size=default_max_size(), cleanup_interval=300.0
         )
         self._disk_cache_component = DiskCache(cache_dir=self.cache_dir, logger=self.logger)
-        self._strategy_component = CacheStrategy(config_manager=self.config_manager, logger=self.logger)
+        # No config manager: CacheStrategy keeps the parameter for callers but
+        # reads nothing from it, and passing ours would build it eagerly.
+        self._strategy_component = CacheStrategy(logger=self.logger)
         self._metrics_component = CacheMetrics(logger=self.logger)
         
         # Disk cleanup configuration
@@ -116,6 +142,44 @@ class CacheManager:
         if self.cache_dir:
             self.start_cleanup_thread()
 
+    @property
+    def config_manager(self) -> Optional[Any]:
+        """A loaded ConfigManager, built the first time it is asked for.
+
+        Every CacheManager used to build one and load the whole config in
+        __init__, for a cache strategy that stopped reading it -- startup paid
+        a config load (and the web interface another) per manager for nothing.
+        It is still public: the sports plugins resolve the global timezone and
+        display settings through ``cache_manager.config_manager``, and they get
+        the same object they always did, on first access instead of at
+        construction. None when ConfigManager cannot be imported, as before.
+        Assigning replaces it, as assigning the attribute always did.
+        """
+        # getattr: a manager made with __new__ (some tests) has no slot yet.
+        value = getattr(self, '_config_manager', _UNSET)
+        if value is not _UNSET:
+            return value
+        lock = getattr(self, '_config_manager_lock', None) or threading.Lock()
+        with lock:
+            value = getattr(self, '_config_manager', _UNSET)
+            if value is _UNSET:
+                try:
+                    from src.config_manager import ConfigManager
+                except ImportError:
+                    self.logger.warning("ConfigManager not available, using default cache intervals")
+                    value = None
+                else:
+                    value = ConfigManager()
+                    # Raises as it did from __init__; nothing is kept, so the
+                    # next access tries again.
+                    value.load_config()
+                self._config_manager = value
+        return value
+
+    @config_manager.setter
+    def config_manager(self, value: Optional[Any]) -> None:
+        self._config_manager = value
+
     def _get_writable_cache_dir(self) -> Optional[str]:
         """Tries to find or create a writable cache directory, preferring a system path when available."""
         # Attempt 1: System-wide persistent cache directory (preferred for services)
@@ -246,7 +310,11 @@ class CacheManager:
         # 1) Memory cache
         cached = self._memory_cache_component.get(key, max_age=in_memory_ttl)
         if cached is not None:
-            return cached
+            if not _outlived(cached, max_age, time.time()):
+                return cached
+            # Too old for this reader. Disk may hold a newer write (from the
+            # other process), and if it does not, the miss is the right answer.
+            self._memory_cache_component.clear(key)
 
         # 2) Disk cache
         record = self._disk_cache_component.get(key, max_age=max_age)
@@ -280,7 +348,9 @@ class CacheManager:
         # Check memory cache first (1 minute TTL)
         cached = self._memory_cache_component.get(key, max_age=60)
         if cached is not None:
-            return cached
+            if not _outlived(cached, 3600, time.time()):
+                return cached
+            self._memory_cache_component.clear(key)
         
         # Check disk cache
         data = self._disk_cache_component.get(key, max_age=3600)  # 1 hour for load_cache
@@ -408,122 +478,6 @@ class CacheManager:
         """Get the cache directory path."""
         return self.cache_dir
 
-    @deprecated("3.7.0")
-    def has_data_changed(self, data_type: str, new_data: Dict[str, Any]) -> bool:
-        """Check if data has changed from cached version."""
-        cached_data = self.load_cache(data_type)
-        if not cached_data:
-            return True
-
-        if data_type == 'weather':
-            return self._has_weather_changed(cached_data, new_data)
-        elif data_type == 'stocks':
-            return self._has_stocks_changed(cached_data, new_data)
-        elif data_type == 'stock_news':
-            return self._has_news_changed(cached_data, new_data)
-        elif data_type == 'nhl':
-            return self._has_nhl_changed(cached_data, new_data)
-        elif data_type == 'mlb':
-            return self._has_mlb_changed(cached_data, new_data)
-        
-        return True
-
-    def _has_weather_changed(self, cached: Dict[str, Any], new: Dict[str, Any]) -> bool:
-        """Check if weather data has changed."""
-        # Handle new cache structure where data is nested under 'data' key
-        if 'data' in cached:
-            cached = cached['data']
-        
-        # Handle case where cached data might be the weather data directly
-        if 'current' in cached:
-            # This is the new structure with 'current' and 'forecast' keys
-            current_weather = cached.get('current', {})
-            if current_weather and 'main' in current_weather and 'weather' in current_weather:
-                cached_temp = round(current_weather['main']['temp'])
-                cached_condition = current_weather['weather'][0]['main']
-                return (cached_temp != new.get('temp') or 
-                        cached_condition != new.get('condition'))
-        
-        # Handle old structure where temp and condition are directly accessible
-        return (cached.get('temp') != new.get('temp') or 
-                cached.get('condition') != new.get('condition'))
-
-    def _has_stocks_changed(self, cached: Dict[str, Any], new: Dict[str, Any]) -> bool:
-        """Check if stock data has changed."""
-        if not self._is_market_open():
-            return False
-        return cached.get('price') != new.get('price')
-
-    def _has_news_changed(self, cached: Dict[str, Any], new: Dict[str, Any]) -> bool:
-        """Check if news data has changed."""
-        # Handle both dictionary and list formats
-        if isinstance(new, list):
-            # If new data is a list, cached data should also be a list
-            if not isinstance(cached, list):
-                return True
-            # Compare lengths and content
-            if len(cached) != len(new):
-                return True
-            # Compare titles since they're unique enough for our purposes
-            cached_titles = set(item.get('title', '') for item in cached)
-            new_titles = set(item.get('title', '') for item in new)
-            return cached_titles != new_titles
-        else:
-            # Original dictionary format handling
-            cached_headlines = set(h.get('id') for h in cached.get('headlines', []))
-            new_headlines = set(h.get('id') for h in new.get('headlines', []))
-            return not cached_headlines.issuperset(new_headlines)
-
-    def _has_nhl_changed(self, cached: Dict[str, Any], new: Dict[str, Any]) -> bool:
-        """Check if NHL data has changed."""
-        return (cached.get('game_status') != new.get('game_status') or
-                cached.get('score') != new.get('score'))
-
-    def _has_mlb_changed(self, cached: Dict[str, Any], new: Dict[str, Any]) -> bool:
-        """Check if MLB game data has changed."""
-        if not cached or not new:
-            return True
-            
-        # Check if any games have changed status or score
-        for game_id, new_game in new.items():
-            cached_game = cached.get(game_id)
-            if not cached_game:
-                return True
-                
-            # Check for score changes
-            if (new_game['away_score'] != cached_game['away_score'] or 
-                new_game['home_score'] != cached_game['home_score']):
-                return True
-                
-            # Check for status changes
-            if new_game['status'] != cached_game['status']:
-                return True
-                
-            # For live games, check inning and count
-            if new_game['status'] == 'in':
-                if (new_game['inning'] != cached_game['inning'] or 
-                    new_game['inning_half'] != cached_game['inning_half'] or
-                    new_game['balls'] != cached_game['balls'] or 
-                    new_game['strikes'] != cached_game['strikes'] or
-                    new_game['bases_occupied'] != cached_game['bases_occupied']):
-                    return True
-                    
-        return False
-
-    def _is_market_open(self) -> bool:
-        """Check if the US stock market is currently open."""
-        return self._strategy_component.is_market_open()
-
-    @deprecated("3.7.0", "use set()")
-    def update_cache(self, data_type: str, data: Dict[str, Any]) -> bool:
-        """Update cache with new data."""
-        cache_data = {
-            # Header first; see DiskCache's stale check.
-            'timestamp': time.time(),
-            'data': data,
-        }
-        return self.save_cache(data_type, cache_data)
-
     def get(self, key: str, max_age: Optional[int] = 300,
             memory_ttl: Optional[int] = None) -> Optional[Dict[str, Any]]:
         """Get data from cache if it exists and is not stale.
@@ -564,42 +518,6 @@ class CacheManager:
         cache_data['data'] = data
         self.save_cache(key, cache_data)
 
-    @deprecated("3.7.0")
-    def setup_persistent_cache(self) -> bool:
-        """
-        Set up a persistent cache directory with proper permissions.
-        This should be run once with sudo to create the directory.
-        """
-        try:
-            # Try to create /var/cache/ledmatrix with proper permissions
-            from pathlib import Path
-            from src.common.permission_utils import (
-                ensure_directory_permissions,
-                get_cache_dir_mode
-            )
-            cache_dir = '/var/cache/ledmatrix'
-            cache_dir_path = Path(cache_dir)
-            ensure_directory_permissions(cache_dir_path, get_cache_dir_mode())
-            
-            # Set ownership to the real user (not root)
-            real_user = os.environ.get('SUDO_USER')
-            if real_user:
-                import pwd
-                try:
-                    uid = pwd.getpwnam(real_user).pw_uid
-                    gid = pwd.getpwnam(real_user).pw_gid
-                    os.chown(cache_dir, uid, gid)
-                    self.logger.info(f"Set ownership of {cache_dir} to {real_user}")
-                except (OSError, KeyError) as e:
-                    self.logger.warning(f"Could not set ownership for {cache_dir}: {e}", exc_info=True)
-            
-            self.logger.info(f"Successfully set up persistent cache directory: {cache_dir}")
-            return True
-            
-        except (OSError, IOError, PermissionError) as e:
-            self.logger.error(f"Failed to set up persistent cache directory {cache_dir}: {e}", exc_info=True)
-            return False
-    
     def cleanup_disk_cache(self, force: bool = False) -> Dict[str, Any]:
         """
         Clean up expired disk cache files based on retention policies.
@@ -776,14 +694,6 @@ class CacheManager:
         else:
             self.logger.info("Disk cache cleanup thread stopped successfully") 
 
-    @deprecated("3.7.0")
-    def get_sport_live_interval(self, sport_key: str) -> int:
-        """
-        Get the live_update_interval for a specific sport from config.
-        Falls back to default values if config is not available.
-        """
-        return self._strategy_component.get_sport_live_interval(sport_key)
-
     def get_cache_strategy(self, data_type: str, sport_key: Optional[str] = None) -> Dict[str, Any]:
         """
         Get cache strategy for different data types.
@@ -798,13 +708,6 @@ class CacheManager:
         """
         return self._strategy_component.get_data_type_from_key(key)
 
-    @deprecated("3.7.0")
-    def get_sport_key_from_cache_key(self, key: str) -> Optional[str]:
-        """
-        Extract sport key from cache key to determine appropriate live_update_interval.
-        """
-        return self._strategy_component.get_sport_key_from_cache_key(key)
-
     def get_cached_data_with_strategy(self, key: str, data_type: str = 'default') -> Optional[Dict[str, Any]]:
         """
         Get data from cache using data-type-specific strategy.
@@ -838,58 +741,6 @@ class CacheManager:
         data_type = self.get_data_type_from_key(key)
         return self.get_cached_data_with_strategy(key, data_type)
 
-    @deprecated("3.7.0", "use get()")
-    def get_background_cached_data(self, key: str, sport_key: Optional[str] = None) -> Optional[Dict[str, Any]]:
-        """
-        Get data from background service cache with appropriate strategy.
-        This method is specifically designed for Recent/Upcoming managers
-        to use data cached by the background service.
-        
-        Args:
-            key: Cache key to retrieve
-            sport_key: Sport key for determining appropriate cache strategy
-            
-        Returns:
-            Cached data if available and fresh, None otherwise
-        """
-        # Determine the appropriate cache strategy
-        data_type = self.get_data_type_from_key(key)
-        strategy = self.get_cache_strategy(data_type, sport_key)
-        
-        # For Recent/Upcoming managers, we want to use the background service cache
-        # which should have longer TTLs than the individual manager caches
-        max_age = strategy['max_age']
-        memory_ttl = strategy.get('memory_ttl', max_age)
-        
-        # Get the cached data
-        cached_data = self.get_cached_data(key, max_age, memory_ttl)
-        
-        if cached_data:
-            # Record cache hit for performance monitoring
-            self.record_cache_hit('background')
-            # Unwrap if stored in { 'data': ..., 'timestamp': ... } format
-            if isinstance(cached_data, dict) and 'data' in cached_data:
-                return cached_data['data']
-            return cached_data
-        
-        # Record cache miss for performance monitoring
-        self.record_cache_miss('background')
-        return None
-
-    @deprecated("3.7.0", "use get()")
-    def is_background_data_available(self, key: str, sport_key: Optional[str] = None) -> bool:
-        """
-        Check if background service has fresh data available.
-        This helps Recent/Upcoming managers determine if they should
-        wait for background data or fetch immediately.
-        """
-        data_type = self.get_data_type_from_key(key)
-        strategy = self.get_cache_strategy(data_type, sport_key)
-        
-        # Check if we have data that's still fresh according to background service TTL
-        cached_data = self.get_cached_data(key, strategy['max_age'])
-        return cached_data is not None
-
     def generate_sport_cache_key(self, sport: str, date_str: Optional[str] = None) -> str:
         """
         Centralized cache key generation for sports data.
@@ -906,44 +757,9 @@ class CacheManager:
             date_str = datetime.now(pytz.utc).strftime('%Y%m%d')
         return f"{sport}_{date_str}"
 
-    @deprecated("3.7.0")
-    def record_cache_hit(self, cache_type: str = 'regular') -> None:
-        """Record a cache hit for performance monitoring."""
-        self._metrics_component.record_hit(cache_type)
-
-    @deprecated("3.7.0")
-    def record_cache_miss(self, cache_type: str = 'regular') -> None:
-        """Record a cache miss for performance monitoring."""
-        self._metrics_component.record_miss(cache_type)
-
-    @deprecated("3.7.0")
-    def record_fetch_time(self, duration: float) -> None:
-        """Record fetch operation duration for performance monitoring."""
-        self._metrics_component.record_fetch_time(duration)
-
-    @deprecated("3.7.0")
-    def get_cache_metrics(self) -> Dict[str, Any]:
-        """Get current cache performance metrics."""
-        return self._metrics_component.get_metrics()
-
-    @deprecated("3.7.0")
-    def log_cache_metrics(self) -> None:
-        """Log current cache performance metrics."""
-        self._metrics_component.log_metrics()
-    
-    @deprecated("3.7.0")
-    def get_memory_cache_stats(self) -> Dict[str, Any]:
-        """
-        Get statistics about the memory cache.
-        
-        Returns:
-            Dictionary with memory cache statistics
-        """
-        return self._memory_cache_component.get_stats()
-    
     def log_memory_cache_stats(self) -> None:
         """Log current memory cache statistics."""
-        stats = self.get_memory_cache_stats()
+        stats = self._memory_cache_component.get_stats()
         self.logger.info(f"Memory Cache - Size: {stats['size']}/{stats['max_size']} "
                         f"({stats['usage_percent']:.1f}%), "
                         f"Last cleanup: {time.time() - stats['last_cleanup']:.1f}s ago")

src/common/README.md

@@ -17,7 +17,9 @@ Rules for the package:
 - `from src.common import ...` re-exports `APIHelper`, `ScrollHelper`,
   `LogoHelper`, `TextHelper`, `scroll_config` (plus `ScrollSettings`,
   `configure_scroll`, `resolve_scroll_settings`, `refresh_hz_from_config`) and
-  the adaptive layout names below ([`__init__.py`](__init__.py)).
+  the adaptive layout names below ([`__init__.py`](__init__.py)). Each is
+  imported on first use, so `import src.common` or a submodule import stays
+  cheap; add a new re-export to `_LAZY` there as well as `__all__`.
 
 ## Summary
 
@@ -27,6 +29,7 @@ Rules for the package:
 | [`bdf_font`](#bdf_font) | Load and draw BDF bitmap fonts | Yes, if drawing BDF text directly | 3.5.0 |
 | [`espn_dates`](#espn_dates) | Fetch ESPN scoreboards across a date range | Yes (scoreboards) | 3.5.0 |
 | [`favorite_team_check`](#favorite_team_check) | Log why a favourite team code shows nothing | Yes (scoreboards) | 3.6.0 |
+| [`fetch_service`](#fetch_service) | Pooled, merged, budgeted and counted HTTP for core fetch paths | No, core-internal (reached through `api_helper` and `espn_dates`) | n/a |
 | [`font_layout`](#font_layout) | Reproducible TrueType loading, crisp sizes | Yes | 3.4.0 |
 | [`frame_timing`](#frame_timing) | Timing of every presented frame, stall watchdog | No, core-internal | n/a |
 | [`json_body`](#json_body) | Parse a response body as JSON, with orjson if installed | Optional (large payloads) | 3.5.0 |
@@ -38,15 +41,23 @@ Rules for the package:
 | [`scroll_helper`](#scroll_helper) | Pre-rendered horizontal scrolling | Yes | — |
 | [`snapshot_policy`](#snapshot_policy) | When to write the web preview frame | No, core-internal | n/a |
 | [`sports_card`](#sports_card) | Scoreboard card settings, colours, fonts, dates | Yes (scoreboards) | 3.3.0 |
+| [`sports_card_wrappers`](#sports_card_wrappers) | The game renderer's `sports_card` delegations | Yes (scoreboards) | 3.7.0 |
+| [`sports_celebration`](#sports_celebration) | Draw a scoreboard's score/win celebration | Yes (scoreboards) | 3.7.0 |
+| [`sports_display_rules`](#sports_display_rules) | Which games a scoreboard shows, for how long, and its scorebug date line | Yes (scoreboards) | 3.8.0 |
+| [`sports_fetch`](#sports_fetch) | Scoreboard season fetch, lookback and live-odds decisions | Yes (scoreboards) | 3.7.0 |
+| [`sports_font_path`](#sports_font_path) | Find a scoreboard's bundled font whatever the cwd | Yes (scoreboards) | 3.8.0 |
 | [`sports_game_renderer`](#sports_game_renderer) | Scoreboard scroll/Vegas card geometry | Yes (scoreboards) | 3.3.0 |
 | [`sports_helpers`](#sports_helpers) | Small helpers every scoreboard `sports.py` copies | Yes (scoreboards) | 3.5.0 |
+| [`sports_live_scroll`](#sports_live_scroll) | Rebuild a live scroll strip mid-cycle without moving it | Yes (scoreboards) | 3.8.0 |
+| [`sports_plugin_host`](#sports_plugin_host) | Helpers of a scoreboard's plugin class (`manager.py`) | Yes (scoreboards) | 3.8.0 |
 | [`sports_scroll`](#sports_scroll) | Scoreboard scroll-display orchestration | Yes (scoreboards) | 3.2.0 |
 | [`sports_shared`](#sports_shared) | Sport-independent `sports.py` methods | Yes (scoreboards) | 3.3.0 |
+| [`sports_vegas`](#sports_vegas) | Live Vegas cards: keys, card cache, sticky odds, finished games | Yes (scoreboards) | 3.8.0 |
 | [`sports_timezone`](#sports_timezone) | Which timezone a scoreboard draws start times in | Yes (scoreboards) | 3.6.0 |
 | [`sync_manager`](#sync_manager) | Leader/follower sync between two displays | No, core-internal | n/a |
 | [`text_helper`](#text_helper) | Outlined text, wrapping, measurement | Yes | — |
 
-The four `sports_*` mixin and card modules hold code the scoreboard plugins
+The `sports_*` mixin and card modules hold code the scoreboard plugins
 used to carry as identical copies. Each module docstring lists what a host
 class must provide. The plan behind them is in
 [docs/SPORTS_UNIFICATION.md](../../docs/SPORTS_UNIFICATION.md).
@@ -100,7 +111,9 @@ and truncates results when `limit` is above 500. `fetch_espn_scoreboard()`
 splits a range into month and day requests ESPN accepts and merges the
 results; `espn_date_chunks()`, `fetch_espn_date_chunks()`,
 `clamp_espn_limit()` and `merge_scoreboard_payloads()` are the pieces.
-Scoreboard plugins also bundle a copy for older cores.
+Every request goes through [`fetch_service`](#fetch_service), the chunks
+counted against the plugin that asked. Scoreboard plugins also bundle a copy
+for older cores.
 
 ### favorite_team_check
 
@@ -113,6 +126,23 @@ says the league has nothing on yet; `reset()` re-arms it after a config edit.
 Diagnostics only: every failure is swallowed. Scoreboard plugins also bundle
 a copy for older cores.
 
+### fetch_service
+
+[`fetch_service.py`](fetch_service.py). Core-internal for now. Every core
+fetch path -- `APIHelper.get`/`post`, `espn_dates` (so every scoreboard's
+ESPN scoreboard fetch and `SportsFetchMixin`), `BackgroundDataService` and
+`BaseOddsManager` -- calls `fetch_get(session, url, ...)` instead of
+`session.get(url, ...)`. Same arguments, return value and exceptions; on top
+it shares one connection pool per host per retry policy
+(`share_connection_pool`), merges identical GETs in flight, applies per-host
+token buckets (`fetch_service.rate_limits` in config.json; ESPN gets 20/s,
+burst 200), revalidates with server-sent `ETag`/`Last-Modified` and counts
+requests per plugin and per host. The display publishes the counters
+(`FetchStatsPublisher`) for `GET /api/v3/plugins/fetch-stats`. Which plugin
+made a request comes from `plugin_scope()`, set by the plugin executor, or
+else from the plugin directory on the stack. See
+[docs/PLUGIN_API_REFERENCE.md](../../docs/PLUGIN_API_REFERENCE.md#fetching-data).
+
 ### font_layout
 
 [`font_layout.py`](font_layout.py). `load_truetype(path, size)` is
@@ -203,7 +233,8 @@ rather than the `set_*` methods. Vegas mode reads a plugin's
 [`snapshot_policy.py`](snapshot_policy.py). Core-internal. `decide()`
 tells `DisplayManager` whether to write `/tmp/led_matrix_preview.png`, only
 touch its mtime, or skip, based on whether a browser is watching the preview.
-The web health check reads the file's age.
+The web health check reads the file's age, and the web preview stream checks
+its mtime every `VIEWER_POLL_INTERVAL`.
 
 ### sports_card
 
@@ -216,6 +247,50 @@ dates (`format_game_date()`, `format_game_time()`, `card_tzinfo()`) and font
 sizes (`schema_font_size()`, `resolve_font_size()`). A plugin keeps its own
 method and delegates the body.
 
+### sports_card_wrappers
+
+[`sports_card_wrappers.py`](sports_card_wrappers.py).
+`SportsCardWrappersMixin`: the one-line methods a scoreboard's game renderer
+uses to call `sports_card` with its own `config` and `logger`
+(`_vs_text()`, `_element_color()`, `_format_game_date()`, ... seventeen in
+all), under their existing names. They are what `sports_game_renderer`'s
+mixin expects its host to provide. No `__init__` and no state.
+
+### sports_celebration
+
+[`sports_celebration.py`](sports_celebration.py). `SportsCelebrationMixin`
+draws the full-screen takeover a scoreboard shows when a team scores or wins
+(`_draw_celebration_layout(celebration)`): a backdrop in the scoring team's
+colours read off its crest, scenery, confetti, the headline and the score.
+The colour helpers are free functions (`logo_palette()`, `lift_color()`,
+`mix_color()`, ...). Deciding *when* to celebrate stays in the plugin, which
+builds the celebration dict the docstring describes.
+
+### sports_display_rules
+
+[`sports_display_rules.py`](sports_display_rules.py). Two `SportsCore`
+mixins: `SportsCardOptionsMixin` (`_card_option()`, which never lets the
+upcoming scorebug lose both its date and time, and `_recent_date_text()`;
+list it before `SportsCoreSharedMixin`) and `SportsGameRulesMixin`
+(`_filtered_or_all()`, the no-favourites quality filter that fails open, and
+`_effective_live_duration()`, the shorter dwell for a non-favourite live
+game).
+
+### sports_fetch
+
+[`sports_fetch.py`](sports_fetch.py). `SportsFetchMixin`: the `SportsCore`
+methods that decide which requests a scoreboard makes --
+`_fetch_season_directly()` (a season, in chunks ESPN accepts),
+`_background_fetches_espn_ranges()`, `_needs_previous_day()` (the live
+lookback) and `_wants_live_odds()` (odds only for games near the screen).
+
+### sports_font_path
+
+[`sports_font_path.py`](sports_font_path.py). `resolve_font_path(path)`: the
+path as given when it exists (relative to the cwd), else
+`font_layout.resolve_asset_path(path)`. What the scoreboards'
+`_resolve_font_path` copies return on a core that ships it.
+
 ### sports_game_renderer
 
 [`sports_game_renderer.py`](sports_game_renderer.py).
@@ -233,6 +308,25 @@ what differs.
 `_odds_color` and `_upcoming_date_and_time_text` under their existing names.
 Nothing in core uses it.
 
+### sports_live_scroll
+
+[`sports_live_scroll.py`](sports_live_scroll.py). `SportsLiveScrollMixin`:
+keeps a live scroll strip current. It fingerprints the live games (the clock
+and the display pipeline's own keys excluded, via the host's
+`LIVE_VOLATILE_FIELDS`), rebuilds when they change, rate-limited by what a
+rebuild costs, and `_preserving_scroll_position()` keeps the marquee where
+it was. Pairs with `SportsPluginHostMixin`, whose `_dispatch_switch_refresh()`
+it uses.
+
+### sports_plugin_host
+
+[`sports_plugin_host.py`](sports_plugin_host.py). `SportsPluginHostMixin`:
+helpers of a scoreboard's `BasePlugin` subclass. `get_vegas_priority_weight()`
+(more Vegas slots while a favourite plays, found across every plugin's data
+shape), `_dispatch_switch_refresh()` (a manager refresh on a daemon thread, so
+`display()` never waits on the network), `get_vegas_content_type()` and small
+dynamic-duration helpers. List it before `BasePlugin`.
+
 ### sports_scroll
 
 [`sports_scroll.py`](sports_scroll.py). `SportsScrollDisplay` and
@@ -240,6 +334,10 @@ Nothing in core uses it.
 scoreboards share (Vegas items, dynamic duration, frame loop), paced through
 `scroll_config`. Subclasses supply `prepare_scroll_content()` and set
 `SCROLL_LEAGUE_KEYS`; see the module docstring for an example.
+`prepare_and_display()` rewinds a recent or upcoming strip whose games,
+rankings, config, panel size and date are unchanged instead of calling
+`prepare_scroll_content()` again, with one display per slate (game type and
+leagues).
 
 ### sports_shared
 
@@ -250,6 +348,17 @@ fonts, colours, dates, the switch-mode upcoming card). The docstring lists
 the attributes the host class must have and the three methods deliberately
 left out.
 
+### sports_vegas
+
+[`sports_vegas.py`](sports_vegas.py). What a scoreboard needs for live Vegas
+cards (one element per game, swapped in place while it scrolls):
+`game_key()`, `game_fingerprint()`, `dedupe_games()`, `VegasCardCache` (draws
+a card only when its fingerprint changes), `StickyOdds` (keeps a card's odds
+through a live poll that left them out), and `finished_games()` /
+`with_finished_games()` (a game that just went final keeps its card, showing
+FINAL). `SportsScrollDisplay.build_vegas_elements()` in `sports_scroll` puts
+them together; a scoreboard not built on it (UFC) uses them directly.
+
 ### sports_timezone
 
 [`sports_timezone.py`](sports_timezone.py).
@@ -278,6 +387,19 @@ Created by `DisplayController`; works with any plugin.
 `get_text_dimensions()`, `center_text()`, `wrap_text()`,
 `draw_multiline_text()`, `create_text_image()`.
 
+`draw_text_outlined(draw, xy, text, font, fill, outline_color=(0, 0, 0),
+offsets=OUTLINE_SQUARE)` (Unreleased) draws the text in `outline_color` at
+each offset, then in `fill` on top: the same pixels as one `draw.text` per
+offset, but the string is rasterized once. `OUTLINE_SQUARE` is the
+eight-sided one-pixel outline the scoreboards draw, `OUTLINE_CROSS` the
+four-sided one. Fractional coordinates (a whole-pixel float such as `52.0`
+is fine), multiline text, fonts other than a plain `FreeTypeFont`, image modes
+other than RGB, RGBA and L, and a subclassed or replaced `draw.text` take
+the `draw.text` loop unchanged. `TextHelper.draw_text_with_outline()` and
+the scoreboards' `SportsCoreSharedMixin._draw_text_with_outline()` use it.
+A plugin that also runs on older cores should guard the import and keep its
+own loop as the fallback.
+
 ## Logging
 
 Modules here create their logger with `logging.getLogger(__name__)`, which is

src/common/__init__.py

@@ -6,45 +6,90 @@ This package provides reusable functionality for plugins and core modules:
 - Logo helpers
 - Text/scroll helpers
 - Adaptive layout and image helpers
+
+The names below are imported on first use (PEP 562), not when the package is
+imported. ``from src.common import ScrollHelper`` and
+``src.common.ScrollHelper`` work as before and return the same objects, but
+``import src.common`` -- or importing any submodule, such as
+``src.common.path_safety`` -- no longer loads numpy, requests and freetype
+along with every helper. The web interface imports src.common only for a few
+small modules and never needs those.
 """
 
-# Export commonly used utilities
-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
+import importlib
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple
 
-# Adaptive layout & images (canonical homes: src.adaptive_layout /
-# src.adaptive_images — re-exported here so plugin authors find them in the
-# blessed-helpers package). See docs/ADAPTIVE_LAYOUT.md.
-from src.adaptive_layout import (
-    Region,
-    LayoutContext,
-    FontStep,
-    FontLadder,
-    LADDER_GRID,
-    LADDER_ARCADE,
-    FitResult,
-    draw_fitted_text,
-    ScoreboardRegions,
-    scoreboard_regions,
-    MediaRow,
-    media_row,
-)
-from src.adaptive_images import (
-    ImageFitResult,
-    fit_image,
-    draw_fitted_image,
-    RESAMPLE_LANCZOS,
-    RESAMPLE_NEAREST,
-)
+if TYPE_CHECKING:
+    # What mypy and editors see: the real names and their types.
+    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
+
+    # Adaptive layout & images (canonical homes: src.adaptive_layout /
+    # src.adaptive_images — re-exported here so plugin authors find them in the
+    # blessed-helpers package). See docs/ADAPTIVE_LAYOUT.md.
+    from src.adaptive_layout import (
+        Region,
+        LayoutContext,
+        FontStep,
+        FontLadder,
+        LADDER_GRID,
+        LADDER_ARCADE,
+        FitResult,
+        draw_fitted_text,
+        ScoreboardRegions,
+        scoreboard_regions,
+        MediaRow,
+        media_row,
+    )
+    from src.adaptive_images import (
+        ImageFitResult,
+        fit_image,
+        draw_fitted_image,
+        RESAMPLE_LANCZOS,
+        RESAMPLE_NEAREST,
+    )
+
+#: Exported name -> (module it lives in, attribute name there). An attribute
+#: of None means the name is the module itself. Keep in step with the
+#: TYPE_CHECKING imports above and with __all__.
+_LAZY: Dict[str, Tuple[str, Optional[str]]] = {
+    'APIHelper': ('src.common.api_helper', 'APIHelper'),
+    'ScrollHelper': ('src.common.scroll_helper', 'ScrollHelper'),
+    'scroll_config': ('src.common.scroll_config', None),
+    'ScrollSettings': ('src.common.scroll_config', 'ScrollSettings'),
+    'configure_scroll': ('src.common.scroll_config', 'configure'),
+    'resolve_scroll_settings': ('src.common.scroll_config', 'resolve'),
+    'refresh_hz_from_config': ('src.common.scroll_config', 'refresh_hz_from_config'),
+    'LogoHelper': ('src.common.logo_helper', 'LogoHelper'),
+    'TextHelper': ('src.common.text_helper', 'TextHelper'),
+    # adaptive layout & images
+    'Region': ('src.adaptive_layout', 'Region'),
+    'LayoutContext': ('src.adaptive_layout', 'LayoutContext'),
+    'FontStep': ('src.adaptive_layout', 'FontStep'),
+    'FontLadder': ('src.adaptive_layout', 'FontLadder'),
+    'LADDER_GRID': ('src.adaptive_layout', 'LADDER_GRID'),
+    'LADDER_ARCADE': ('src.adaptive_layout', 'LADDER_ARCADE'),
+    'FitResult': ('src.adaptive_layout', 'FitResult'),
+    'draw_fitted_text': ('src.adaptive_layout', 'draw_fitted_text'),
+    'ScoreboardRegions': ('src.adaptive_layout', 'ScoreboardRegions'),
+    'scoreboard_regions': ('src.adaptive_layout', 'scoreboard_regions'),
+    'MediaRow': ('src.adaptive_layout', 'MediaRow'),
+    'media_row': ('src.adaptive_layout', 'media_row'),
+    'ImageFitResult': ('src.adaptive_images', 'ImageFitResult'),
+    'fit_image': ('src.adaptive_images', 'fit_image'),
+    'draw_fitted_image': ('src.adaptive_images', 'draw_fitted_image'),
+    'RESAMPLE_LANCZOS': ('src.adaptive_images', 'RESAMPLE_LANCZOS'),
+    'RESAMPLE_NEAREST': ('src.adaptive_images', 'RESAMPLE_NEAREST'),
+}
 
 __all__ = [
     'APIHelper',
@@ -75,3 +120,25 @@ __all__ = [
     'RESAMPLE_LANCZOS',
     'RESAMPLE_NEAREST',
 ]
+
+
+def __getattr__(name: str) -> Any:
+    """Import an exported name on first access (PEP 562).
+
+    Only called for names not already in the module namespace, so after the
+    first access the cached value below is returned directly. Unknown names
+    raise AttributeError, which ``from src.common import <submodule>`` relies
+    on to fall through to importing the submodule.
+    """
+    try:
+        module_name, attr = _LAZY[name]
+    except KeyError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+    module = importlib.import_module(module_name)  # nosemgrep: python.lang.security.audit.non-literal-import.non-literal-import -- module_name comes from the fixed _LAZY table
+    value = module if attr is None else getattr(module, attr)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> List[str]:
+    return sorted(set(globals()) | set(__all__))

src/common/api_helper.py

@@ -10,11 +10,17 @@ import logging
 import time
 from datetime import datetime
 from types import MappingProxyType
-from src.common.espn_dates import ESPN_MAX_LIMIT
+from src.common.espn_dates import (
+    ESPN_MAX_LIMIT,
+    espn_scoreboard_cache_key,
+    read_espn_scoreboard_cache,
+    store_espn_scoreboard_cache,
+)
+from src.common.fetch_service import fetch_get, fetch_post, share_connection_pool
+from src.common.json_body import response_json
 from typing import TYPE_CHECKING, Any, Dict, Mapping, Optional, cast
 
 import requests
-from requests.adapters import HTTPAdapter
 from urllib3.util.retry import Retry
 
 if TYPE_CHECKING:
@@ -45,7 +51,11 @@ class APIHelper:
 
     - Requests go through one ``requests.Session`` that retries GET, HEAD
       and OPTIONS on 429 and 5xx with exponential backoff, and sends
-      :data:`DEFAULT_HTTP_HEADERS`.
+      :data:`DEFAULT_HTTP_HEADERS`. Its connection pool is shared with every
+      other helper using the same retry policy, and requests go through the
+      core fetch service (``src/common/fetch_service.py``): identical GETs in
+      flight are merged, hosts with a budget are paced, and requests are
+      counted per plugin. Return values and errors are unchanged.
     - Consecutive requests from one helper are spaced at least
       ``set_rate_limit()`` seconds apart (1 second by default). A cache hit
       does not count.
@@ -81,9 +91,10 @@ class APIHelper:
             status_forcelist=[429, 500, 502, 503, 504],
             allowed_methods=["GET", "HEAD", "OPTIONS"]
         )
-        adapter = HTTPAdapter(max_retries=retry_strategy)
-        self.session.mount("https://", adapter)
-        self.session.mount("http://", adapter)
+        # The shared adapter for this retry policy: the same retries as a
+        # private HTTPAdapter(max_retries=retry_strategy), with the connection
+        # pool shared by every helper (fetch_service).
+        share_connection_pool(self.session, retry_strategy)
         
         self.session.headers.update({**DEFAULT_HTTP_HEADERS, 'Connection': 'keep-alive'})
         
@@ -112,6 +123,14 @@ class APIHelper:
         Returns:
             Response data as dictionary or None if request fails
         """
+        return self._get(url, params, headers, timeout, cache_key, cache_ttl,
+                         cache_ttl if cache_key else None)
+
+    def _get(self, url: str, params: Optional[Dict], headers: Optional[Dict],
+             timeout: Optional[int], cache_key: Optional[str], cache_ttl: int,
+             cache_max_age: Optional[float]) -> Optional[Dict]:
+        """:meth:`get`, saying how old a response the fetch service's short
+        response cache may hand back (``cache_max_age``, the caller's TTL)."""
         if cache_key and self.cache_manager:
             cached = self._get_from_cache(cache_key, cache_ttl)
             if cached is not None:
@@ -128,16 +147,18 @@ class APIHelper:
                 request_headers.update(headers)
             
             # Make request
-            response = self.session.get(
+            response = fetch_get(
+                self.session,
                 url, 
                 params=params,
                 headers=request_headers,
-                timeout=timeout or self.default_timeout
+                timeout=timeout or self.default_timeout,
+                cache_max_age=cache_max_age,
             )
             response.raise_for_status()
             
             # Parse JSON response
-            data: Dict[Any, Any] = response.json()
+            data: Dict[Any, Any] = response_json(response)
             
             # Cache response if cache key provided
             if cache_key and self.cache_manager:
@@ -161,22 +182,23 @@ class APIHelper:
             sport: Sport name (e.g., 'basketball', 'football')
             league: League name (e.g., 'nba', 'nfl')
             date: Date in YYYYMMDD format (defaults to today)
-            cache_key: Cache key for response
-            cache_ttl: Cache time-to-live in seconds
-            
+            cache_key: Cache key for response. By default the canonical
+                ``espn_scoreboard_cache_key(sport, league, date)``, shared
+                with every other consumer of this scoreboard, with the key
+                this used before (``espn_{sport}_{league}_{date}``) read as a
+                fallback for one release. An explicit key works as before.
+            cache_ttl: Cache time-to-live in seconds. A shared entry is
+                returned only while it is at most this old.
+
         Returns:
             ESPN API response data or None if request fails
         """
         if date is None:
             date = datetime.now().strftime('%Y%m%d')
-        
+
         # Build URL
         url = f"https://site.api.espn.com/apis/site/v2/sports/{sport}/{league}/scoreboard"
-        
-        # Build cache key if not provided
-        if cache_key is None:
-            cache_key = f"espn_{sport}_{league}_{date}"
-        
+
         # Set parameters
         # limit above 500 makes ESPN truncate instead of erroring: college
         # football came back with 25 of 68 games. See src/common/espn_dates.py.
@@ -184,8 +206,26 @@ class APIHelper:
             'dates': date,
             'limit': ESPN_MAX_LIMIT
         }
-        
-        return self.get(url, params=params, cache_key=cache_key, cache_ttl=cache_ttl)
+
+        if cache_key is not None:
+            return self.get(url, params=params, cache_key=cache_key, cache_ttl=cache_ttl)
+
+        legacy_key = f"espn_{sport}_{league}_{date}"
+        try:
+            shared_key = espn_scoreboard_cache_key(sport, league, date)
+        except ValueError:
+            # Not a path or date the canonical key covers: the old key.
+            return self.get(url, params=params, cache_key=legacy_key, cache_ttl=cache_ttl)
+        if self.cache_manager:
+            cached = read_espn_scoreboard_cache(
+                self.cache_manager, shared_key, cache_ttl, legacy_keys=(legacy_key,))
+            if cached is not None:
+                self.logger.debug(f"Using cached response for {shared_key}")
+                return cast(Dict[Any, Any], cached)
+        data = self._get(url, params, None, None, None, cache_ttl, cache_ttl)
+        if data is not None and self.cache_manager:
+            store_espn_scoreboard_cache(self.cache_manager, shared_key, data)
+        return data
     
     def fetch_espn_standings(self, sport: str, league: str,
                             cache_key: Optional[str] = None,
@@ -255,7 +295,8 @@ class APIHelper:
             if headers:
                 request_headers.update(headers)
             
-            response = self.session.post(
+            response = fetch_post(
+                self.session,
                 url,
                 data=data,
                 json=json_data,
@@ -264,7 +305,7 @@ class APIHelper:
             )
             response.raise_for_status()
             
-            return cast(Optional[Dict[Any, Any]], response.json())
+            return cast(Optional[Dict[Any, Any]], response_json(response))
             
         except requests.exceptions.RequestException as e:
             self.logger.error(f"POST request failed for {url}: {e}")

src/common/espn_dates.py

@@ -30,14 +30,34 @@ Once a range has been rejected, later ranges skip straight to chunks for
 ``RANGE_RETRY_SECONDS`` instead of spending a doomed request first -- live
 scoreboards ask every 30 seconds. After that the range is tried again, so the
 workaround retires itself if ESPN reverts.
+
+ONE CACHE KEY PER SCOREBOARD
+----------------------------
+The same ESPN scoreboard used to be cached under a different key by every
+consumer: odds-ticker as ``scoreboard_data_{sport}_{league}_{date}``,
+``APIHelper`` as ``espn_{sport}_{league}_{date}``, the scoreboards as
+``{sport_key}_schedule_{window}`` -- so two plugins showing the same league
+fetched and stored it twice. :func:`espn_scoreboard_cache_key` is the one
+name for "this sport/league scoreboard for these dates", and
+:func:`get_espn_scoreboard` (or :func:`read_espn_scoreboard_cache` and
+:func:`store_espn_scoreboard_cache` around :func:`fetch_espn_scoreboard`)
+is the cache-through read every consumer can share. A read never returns an
+entry older than the reader's own ``max_age``, whoever wrote it and whatever
+ttl they stored with it. Old keys are passed as ``legacy_keys`` and read
+after the canonical one, so an upgrade does not refetch everything at once;
+they can go one release after the one that added this.
 """
 
+import contextvars
+import logging
+import math
+import re
 import threading
 import time
 from concurrent.futures import ThreadPoolExecutor
-from datetime import date, timedelta
+from datetime import date, datetime, timedelta
 from functools import partial
-from typing import Any, Dict, List, Optional, Tuple, cast
+from typing import Any, Callable, Dict, Iterable, List, Optional, Tuple, cast
 
 try:
     from src.common.json_body import response_json
@@ -47,6 +67,26 @@ except ImportError:
     def response_json(response: Any) -> Any:
         return response.json()
 
+try:
+    # The core fetch service: counts, per-host budget, merging of identical
+    # requests. Same call, same result and errors as ``session.get``.
+    from src.common.fetch_service import fetch_get, get_fetch_service, pinned_caller
+    _COUNTS_FETCHES = True
+except ImportError:
+    # Bundled copies on cores without it call the session directly.
+    import contextlib
+
+    def fetch_get(session: Any, url: str, *, share_in_flight: bool = True,
+                  cache_max_age: Optional[float] = None, **kwargs: Any) -> Any:
+        return session.get(url, **kwargs)
+
+    def pinned_caller() -> Any:
+        return contextlib.nullcontext()
+
+    _COUNTS_FETCHES = False
+
+_logger = logging.getLogger(__name__)
+
 # Above this, ESPN returns a truncated list instead of an error. See module
 # docstring: 500 is the largest value measured to return complete data.
 ESPN_MAX_LIMIT = 500
@@ -73,8 +113,23 @@ __all__ = [
     "merge_scoreboard_payloads",
     "fetch_espn_date_chunks",
     "fetch_espn_scoreboard",
+    "ESPN_SCOREBOARD_URL",
+    "espn_scoreboard_url",
+    "espn_scoreboard_cache_key",
+    "espn_scoreboard_cache_key_for_url",
+    "read_espn_scoreboard_cache",
+    "store_espn_scoreboard_cache",
+    "get_espn_scoreboard",
 ]
 
+#: The site-API scoreboard every sport and league shares.
+ESPN_SCOREBOARD_URL = "https://site.api.espn.com/apis/site/v2/sports/{sport}/{league}/scoreboard"
+_ESPN_HOST_URL = "https://site.api.espn.com/"
+
+_PATH_PART = re.compile(r"^[a-z0-9][a-z0-9.\-]*$")
+_DATES = re.compile(r"^\d{4}(?:\d{2}(?:\d{2})?)?$|^\d{8}-\d{8}$")
+_SCOREBOARD_PATH = re.compile(r"/sports/([^/?#]+)/([^/?#]+)/scoreboard/?$")
+
 
 def clamp_espn_limit(params: Optional[Dict[str, Any]]) -> Dict[str, Any]:
     """Return a copy of ``params`` with any ``limit`` over 500 pulled back to 500."""
@@ -113,6 +168,12 @@ def parse_espn_date_range(dates: Any) -> Optional[Tuple[date, date]]:
     return start, end
 
 
+def _memo_kwargs(cache_max_age: Optional[float]) -> Dict[str, Any]:
+    """``cache_max_age`` for fetch_get, only when the caller gave one, so a
+    call that did not say is the call it always was."""
+    return {} if cache_max_age is None else {"cache_max_age": cache_max_age}
+
+
 def _ranges_known_rejected() -> bool:
     with _range_lock:
         return time.monotonic() < _ranges_rejected_until
@@ -188,6 +249,7 @@ def merge_scoreboard_payloads(payloads: List[Any]) -> Dict[str, Any]:
 
 def _fetch_one_chunk(
     session, url: str, params: Dict[str, Any], headers, timeout, logger, chunk: str,
+    cache_max_age: Optional[float] = None,
 ) -> Optional[Dict[str, Any]]:
     """GET a single ``dates=`` chunk, or None when it failed.
 
@@ -195,11 +257,13 @@ def _fetch_one_chunk(
     logged and swallowed here rather than raised to the gather below.
     """
     try:
-        response = session.get(
+        response = fetch_get(
+            session,
             url,
             params=dict(params, dates=chunk, limit=ESPN_MAX_LIMIT),
             headers=headers,
             timeout=timeout,
+            **_memo_kwargs(cache_max_age),
         )
         response.raise_for_status()
         return cast(Optional[Dict[str, Any]], response_json(response))
@@ -211,7 +275,7 @@ def _fetch_one_chunk(
 
 def _fetch_chunks(
     session, url: str, params: Dict[str, Any], headers, timeout, logger,
-    chunks: List[str],
+    chunks: List[str], cache_max_age: Optional[float] = None,
 ) -> List[Optional[Dict[str, Any]]]:
     """Fetch every chunk, returning payloads positionally aligned with ``chunks``.
 
@@ -220,19 +284,29 @@ def _fetch_chunks(
     callers keep ``chunks`` order from the returned list -- but it does mean
     the session is shared across threads, which is why this only ever issues
     GETs and never touches session state.
+
+    Each chunk runs in a copy of the caller's context, with the caller pinned
+    into it, so the fetch service counts the chunks against the plugin that
+    asked for the range rather than against the core.
     """
     if not chunks:
         return []
     fetch = partial(
         _fetch_one_chunk, session, url, params, headers, timeout, logger,
+        cache_max_age=cache_max_age,
     )
     if len(chunks) == 1:
         return [fetch(chunks[0])]
     workers = min(ESPN_CHUNK_WORKERS, len(chunks))
+    with pinned_caller():
+        # One copy per chunk: a Context cannot be entered by two threads.
+        contexts = [contextvars.copy_context() for _ in chunks]
     with ThreadPoolExecutor(
         max_workers=workers, thread_name_prefix="espn-chunk",
     ) as pool:
-        return list(pool.map(fetch, chunks))
+        futures = [pool.submit(context.run, fetch, chunk)
+                   for context, chunk in zip(contexts, chunks)]
+        return [future.result() for future in futures]
 
 
 def fetch_espn_date_chunks(
@@ -242,6 +316,7 @@ def fetch_espn_date_chunks(
     headers: Optional[Dict[str, str]] = None,
     timeout: int = 15,
     logger=None,
+    cache_max_age: Optional[float] = None,
 ) -> Optional[Dict[str, Any]]:
     """Fetch a ``YYYYMMDD-YYYYMMDD`` window as month and day chunks.
 
@@ -273,7 +348,7 @@ def fetch_espn_date_chunks(
         )
 
     results = _fetch_chunks(
-        session, url, params, headers, timeout, logger, chunks,
+        session, url, params, headers, timeout, logger, chunks, cache_max_age,
     )
     attempted = len(chunks)
 
@@ -305,7 +380,7 @@ def fetch_espn_date_chunks(
         days = [day for index in sorted(capped) for day in capped[index]]
         attempted += len(days)
         by_day = dict(zip(days, _fetch_chunks(
-            session, url, params, headers, timeout, logger, days,
+            session, url, params, headers, timeout, logger, days, cache_max_age,
         )))
         for index, month_days in capped.items():
             slots[index] = [by_day.get(day) for day in month_days]
@@ -338,6 +413,7 @@ def fetch_espn_scoreboard(
     headers: Optional[Dict[str, str]] = None,
     timeout: int = 15,
     logger=None,
+    cache_max_age: Optional[float] = None,
 ) -> Dict[str, Any]:
     """GET an ESPN scoreboard, re-asking in month/day chunks if a range 400s.
 
@@ -347,6 +423,10 @@ def fetch_espn_scoreboard(
     and later ranges go straight to chunks for ``RANGE_RETRY_SECONDS``. A 400 on
     a non-range request, any other error, and a range whose every chunk fails
     all raise as before.
+
+    ``cache_max_age`` is the oldest response, in seconds, the caller takes
+    from the fetch service's short response cache (its own TTL; 0 always
+    asks ESPN). None leaves it to the service default.
     """
     params = clamp_espn_limit(params)
     is_range = parse_espn_date_range(params.get("dates")) is not None
@@ -355,7 +435,7 @@ def fetch_espn_scoreboard(
     if is_range and _ranges_known_rejected():
         data = fetch_espn_date_chunks(
             session, url, params=params, headers=headers,
-            timeout=timeout, logger=logger,
+            timeout=timeout, logger=logger, cache_max_age=cache_max_age,
         )
         if data is not None:
             return data
@@ -363,7 +443,8 @@ def fetch_espn_scoreboard(
         # real error to log, without spending the chunks a second time.
         chunks_tried = True
 
-    response = session.get(url, params=params, headers=headers, timeout=timeout)
+    response = fetch_get(session, url, params=params, headers=headers, timeout=timeout,
+                         **_memo_kwargs(cache_max_age))
     if is_range and response.status_code == 400 and not chunks_tried:
         _note_range_rejected()
         if logger:
@@ -374,9 +455,225 @@ def fetch_espn_scoreboard(
             )
         data = fetch_espn_date_chunks(
             session, url, params=params, headers=headers,
-            timeout=timeout, logger=logger,
+            timeout=timeout, logger=logger, cache_max_age=cache_max_age,
         )
         if data is not None:
             return data
     response.raise_for_status()
     return cast(Dict[str, Any], response_json(response))
+
+
+# --- one cache key per scoreboard --------------------------------------------------
+
+def espn_scoreboard_url(sport: str, league: str) -> str:
+    """The site-API scoreboard URL for an ESPN ``sport`` / ``league`` path."""
+    return ESPN_SCOREBOARD_URL.format(sport=_path_part(sport, "sport"),
+                                      league=_path_part(league, "league"))
+
+
+def _path_part(value: Any, what: str) -> str:
+    text = str(value or "").strip().lower()
+    if not _PATH_PART.match(text):
+        raise ValueError(f"not an ESPN {what} path segment: {value!r}")
+    return text
+
+
+def _day(value: Any) -> str:
+    if isinstance(value, (date, datetime)):
+        return value.strftime("%Y%m%d")
+    text = str(value).strip()
+    if len(text) != 8 or not text.isdigit():
+        raise ValueError(f"not an ESPN day (YYYYMMDD): {value!r}")
+    return text
+
+
+def _dates_part(dates: Any) -> str:
+    """``dates`` as ESPN spells it, or ``current`` for no ``dates`` at all."""
+    if dates is None or dates == "":
+        return "current"
+    if isinstance(dates, (date, datetime)):
+        return _day(dates)
+    if isinstance(dates, (tuple, list)):
+        if len(dates) != 2:
+            raise ValueError(f"a date range is (start, end): {dates!r}")
+        start, end = _day(dates[0]), _day(dates[1])
+        return start if start == end else f"{start}-{end}"
+    text = str(dates).strip()
+    if isinstance(dates, bool) or not _DATES.match(text):
+        raise ValueError(
+            f"not an ESPN dates value (YYYY, YYYYMM, YYYYMMDD or "
+            f"YYYYMMDD-YYYYMMDD): {dates!r}")
+    return text
+
+
+def espn_scoreboard_cache_key(sport: str, league: str, dates: Any = None) -> str:
+    """The one cache key for an ESPN scoreboard, whoever caches it.
+
+    ``sport`` and ``league`` are ESPN's own path segments -- ``football`` /
+    ``college-football``, ``soccer`` / ``eng.1`` -- not a plugin's
+    ``sport_key``, so every plugin showing a league names it the same way.
+    ``dates`` is what the request sends as ``dates=``: ``"YYYYMMDD"``,
+    ``"YYYYMM"``, ``"YYYY"``, ``"YYYYMMDD-YYYYMMDD"``, a ``date``, or a
+    ``(start, end)`` pair of either; None is the undated "current"
+    scoreboard. Anything else raises ValueError rather than invent a key.
+
+    The key says nothing about ``limit``: a cached copy is meant to be a
+    whole one (the helpers here always ask for ``ESPN_MAX_LIMIT``).
+    """
+    return (f"espn_scoreboard_{_path_part(sport, 'sport')}_"
+            f"{_path_part(league, 'league')}_{_dates_part(dates)}")
+
+
+def espn_scoreboard_cache_key_for_url(url: str, dates: Any = None) -> Optional[str]:
+    """:func:`espn_scoreboard_cache_key` for a scoreboard URL, or None when
+    ``url`` is not ``.../sports/{sport}/{league}/scoreboard``."""
+    match = _SCOREBOARD_PATH.search(str(url or "").split("?", 1)[0])
+    if match is None:
+        return None
+    try:
+        return espn_scoreboard_cache_key(match.group(1), match.group(2), dates)
+    except ValueError:
+        return None
+
+
+def _note_cache_hit(legacy: bool, avoided_request: bool = True) -> None:
+    if not _COUNTS_FETCHES:
+        return
+    try:
+        get_fetch_service().note_cache_hit(
+            _ESPN_HOST_URL, legacy=legacy, avoided_request=avoided_request)
+    except Exception:  # noqa: BLE001 - counting never breaks a read
+        _logger.debug("could not count a scoreboard cache hit", exc_info=True)
+
+
+def _fresh_cached(cache_manager: Any, key: str, max_age: Optional[float],
+                  now: float) -> Tuple[Optional[Dict[str, Any]], Optional[float]]:
+    """The data cached under ``key`` if it is at most ``max_age`` seconds
+    old, and its age (None when the cache does not say).
+
+    The age is the stored record's own timestamp, checked here: CacheManager
+    lets a ttl stored by the writer override the reader's max_age, and its
+    memory tier times an entry from when it was loaded, not written. A key
+    shared by readers with different TTLs can rely on neither.
+    """
+    reader = getattr(cache_manager, "get_cached_data", None)
+    limit = None if max_age is None else max(1, int(math.ceil(max_age)))
+    if not callable(reader):
+        # A cache without records (a test double, a plugin's own store).
+        value = cache_manager.get(key, max_age=limit)
+        return (value if isinstance(value, dict) else None), None
+    record = reader(key, max_age=limit, memory_ttl=limit)
+    if not isinstance(record, dict):
+        return None, None
+    if "data" not in record:
+        return record, None  # unwrapped; the cache already judged it by mtime
+    stamp = record.get("timestamp")
+    age: Optional[float] = None
+    if not isinstance(stamp, bool) and isinstance(stamp, (int, float)):
+        age = max(0.0, now - float(stamp))
+    if max_age is not None and (age is None or age > max_age):
+        return None, None
+    data = record["data"]
+    return (data if isinstance(data, dict) else None), age
+
+
+def read_espn_scoreboard_cache(
+    cache_manager: Any,
+    key: str,
+    max_age: Optional[float],
+    legacy_keys: Iterable[str] = (),
+    now: Optional[float] = None,
+    accept: Optional[Callable[[Dict[str, Any], Optional[float]], bool]] = None,
+) -> Optional[Dict[str, Any]]:
+    """The cached scoreboard under ``key``, or under the first of
+    ``legacy_keys`` that has one, if it is at most ``max_age`` seconds old.
+
+    None on a miss, a stale entry, ``max_age`` of 0 or less, no cache
+    manager, or any cache error -- a read never raises. ``max_age=None``
+    takes an entry of any age. ``accept(data, age_seconds)`` can turn down
+    an entry the age alone would allow (a payload holding a live game wants
+    a shorter limit); ``age_seconds`` is None when the cache cannot say. A
+    hit is counted in the fetch statistics (``cache_hits``;
+    ``legacy_cache_hits`` too for an old key).
+    """
+    if cache_manager is None:
+        return None
+    if max_age is not None and max_age <= 0:
+        return None
+    clock = time.time() if now is None else now
+    for index, candidate in enumerate([key, *legacy_keys]):
+        if not candidate:
+            continue
+        try:
+            data, age = _fresh_cached(cache_manager, candidate, max_age, clock)
+            if data is not None and accept is not None and not accept(data, age):
+                data = None
+        except Exception:  # noqa: BLE001 - a broken cache is a miss
+            _logger.debug("scoreboard cache read failed for %s", candidate, exc_info=True)
+            continue
+        if data is not None:
+            _note_cache_hit(legacy=index > 0)
+            return data
+    return None
+
+
+def store_espn_scoreboard_cache(cache_manager: Any, key: str, data: Any) -> None:
+    """Cache a fetched scoreboard under ``key``. Never raises.
+
+    No ttl is stored: each reader applies its own ``max_age`` (a live
+    reader 30 s, a schedule reader an hour), and a stored ttl would
+    override theirs in CacheManager.
+    """
+    if cache_manager is None or data is None:
+        return
+    try:
+        cache_manager.set(key, data)
+    except Exception:  # noqa: BLE001 - the caller still has its data
+        _logger.warning("Could not cache scoreboard %s", key, exc_info=True)
+
+
+def get_espn_scoreboard(
+    session: Any,
+    sport: str,
+    league: str,
+    dates: Any = None,
+    *,
+    cache_manager: Any = None,
+    max_age: Optional[float] = 300,
+    legacy_keys: Iterable[str] = (),
+    headers: Optional[Dict[str, str]] = None,
+    timeout: int = 15,
+    logger: Any = None,
+) -> Dict[str, Any]:
+    """An ESPN scoreboard through the shared cache, fetched on a miss.
+
+    Reads :func:`espn_scoreboard_cache_key` (then ``legacy_keys``) and
+    returns an entry at most ``max_age`` seconds old. Otherwise it fetches
+    with :func:`fetch_espn_scoreboard` -- ``limit=ESPN_MAX_LIMIT``, ranges
+    split as ESPN needs -- caches the result under the canonical key and
+    returns it. ``max_age=0`` always fetches (and still caches, for other
+    readers). Errors raise exactly as :func:`fetch_espn_scoreboard` does,
+    and nothing is cached then. ``session=None`` uses the fetch service's
+    pooled session for the ESPN host.
+    """
+    key = espn_scoreboard_cache_key(sport, league, dates)
+    cached = read_espn_scoreboard_cache(cache_manager, key, max_age, legacy_keys)
+    if cached is not None:
+        return cast(Dict[str, Any], cached)
+    params: Dict[str, Any] = {"limit": ESPN_MAX_LIMIT}
+    spelled = _dates_part(dates)
+    if spelled != "current":
+        params["dates"] = spelled
+    data = fetch_espn_scoreboard(
+        session,
+        espn_scoreboard_url(sport, league),
+        params=params,
+        headers=headers,
+        timeout=timeout,
+        logger=logger,
+        # The response cache must not hand back anything older than the
+        # cache read above would have accepted.
+        cache_max_age=None if max_age is None else max(0.0, float(max_age)),
+    )
+    store_espn_scoreboard_cache(cache_manager, key, data)
+    return data

src/common/espn_payload.py

@@ -0,0 +1,97 @@
+"""Drop the parts of an ESPN scoreboard payload no scoreboard reads.
+
+The sports scoreboards cache their Recent/Upcoming window (14 days back, 7
+ahead) as the raw ESPN response, and that record stays parsed in the memory
+cache for as long as it is fresh. Most of it is never drawn. Measured on hdpi
+(2026-10-02) the MLB window was 3.35MB of JSON and 13.5MB of Python objects,
+and the five windows together ~40MB, mostly in:
+
+* ``competitors[].leaders`` / ``competitions[].leaders`` -- per-team and
+  per-game stat leaders (28% of the MLB window)
+* ``competitors[].team.links`` / ``event.links`` -- web and app URLs
+* ``status.featuredAthletes`` and ``competitors[].probables`` -- athlete
+  cards with headshots and season stats
+* ``competitions[].headlines`` / ``highlights`` -- article and video blurbs
+  (28% of the college-football window)
+* ``competitions[].geoBroadcasts``
+
+None of those keys is read by core or by any plugin in ledmatrix-plugins
+(checked 2026-10-02 across every scoreboard, the odds ticker and the
+leaderboard), while everything that is read -- odds, records, linescores,
+situation, statistics, notes, broadcasts, venue -- is kept. Dropping them
+takes the five windows from ~40MB to ~12MB of parsed objects and the files from
+10.6MB to 3.0MB, so the reads that parse an expired window on the render
+thread get 3-4x cheaper too.
+
+:func:`slim_scoreboard_payload` changes the payload in place, and only ever
+removes the keys listed here: anything it does not know about is left alone.
+"""
+
+from typing import Any, Dict
+from urllib.parse import urlsplit
+
+# Per level of the payload, the keys removed. Kept deliberately explicit:
+# adding a key here means checking that nothing reads it first.
+_EVENT_DROP = ("links",)
+_COMPETITION_DROP = ("leaders", "headlines", "highlights", "geoBroadcasts")
+_STATUS_DROP = ("featuredAthletes",)
+_COMPETITOR_DROP = ("leaders", "probables")
+_TEAM_DROP = ("links",)
+
+
+def is_espn_scoreboard_url(url: Any) -> bool:
+    """Whether ``url`` is an ESPN site-API scoreboard endpoint."""
+    if not isinstance(url, str):
+        return False
+    try:
+        parts = urlsplit(url)
+    except ValueError:
+        return False
+    host = (parts.hostname or "").lower()
+    if host != "espn.com" and not host.endswith(".espn.com"):
+        return False
+    return parts.path.rstrip("/").endswith("/scoreboard")
+
+
+def _drop(obj: Any, keys) -> None:
+    if isinstance(obj, dict):
+        for key in keys:
+            obj.pop(key, None)
+
+
+def slim_scoreboard_payload(payload: Any) -> Any:
+    """Remove the unread parts of an ESPN scoreboard payload, in place.
+
+    Returns ``payload`` for convenience. Anything that is not shaped like a
+    scoreboard (not a dict, no ``events`` list, odd entries) is passed over
+    untouched rather than raising.
+    """
+    if not isinstance(payload, dict):
+        return payload
+    events = payload.get("events")
+    if not isinstance(events, list):
+        return payload
+    for event in events:
+        if not isinstance(event, dict):
+            continue
+        _drop(event, _EVENT_DROP)
+        competitions = event.get("competitions")
+        if not isinstance(competitions, list):
+            continue
+        for competition in competitions:
+            if not isinstance(competition, dict):
+                continue
+            _drop(competition, _COMPETITION_DROP)
+            _drop(competition.get("status"), _STATUS_DROP)
+            competitors = competition.get("competitors")
+            if not isinstance(competitors, list):
+                continue
+            for competitor in competitors:
+                if not isinstance(competitor, dict):
+                    continue
+                _drop(competitor, _COMPETITOR_DROP)
+                _drop(competitor.get("team"), _TEAM_DROP)
+    return payload
+
+
+__all__ = ["is_espn_scoreboard_url", "slim_scoreboard_payload"]

src/common/favorite_team_check.py

@@ -218,6 +218,8 @@ class FavoriteTeamCheck:
                 return None  # Nothing published either way; draw no conclusion.
             if cls._moved_to_later_phase(payload):
                 return None  # e.g. postseason under way; see the method.
+            if cls._later_round_scheduled(payload, now):
+                return None  # e.g. Europa League between matchdays.
             return ("the season has finished and the next one's fixtures are "
                     "not published yet")
 
@@ -259,6 +261,44 @@ class FavoriteTeamCheck:
         known = [t for t in event_types if isinstance(t, int)]
         return bool(known) and all(t < league_type for t in known)
 
+    @classmethod
+    def _later_round_scheduled(cls, payload, now: datetime) -> bool:
+        """
+        Whether a "list" calendar has a round that has not started yet.
+
+        Competitions with a list calendar (the UEFA club competitions, the
+        World Cup, AFL, NFL) give each phase its rounds as ``entries`` with
+        start and end dates. Between matchdays the Europa League scoreboard
+        keeps showing the last one: on 2026-09-29 every event was from 17
+        September, the next matchday was only days away, and the rounds from
+        the knockout play-offs to the final were all still to come. A round
+        that starts later means the season is not over, even though the
+        date of the next fixture is not known.
+
+        Only a round's *start* counts. End dates are padded well past the
+        last game -- the World Cup's final round ran to 1 August for a 19 July
+        final -- so a future end date is also true of a finished season.
+        Rounds in an offseason phase (the college football All-Star week)
+        are not games for the favourites and do not count either.
+        """
+        league = (payload.get('leagues') or [{}])[0] or {}
+        for phase in league.get('calendar') or []:
+            if not isinstance(phase, dict) or cls._is_offseason(phase.get('label')):
+                continue
+            for entry in phase.get('entries') or []:
+                if not isinstance(entry, dict) or cls._is_offseason(entry.get('label')):
+                    continue
+                start = cls._parse_date(entry.get('startDate'))
+                if start and start > now:
+                    return True
+        return False
+
+    @staticmethod
+    def _is_offseason(label) -> bool:
+        """'Off Season', 'Offseason', 'Off-season' ..."""
+        return isinstance(label, str) and 'offseason' in re.sub(
+            r'[^a-z]', '', label.lower())
+
     @staticmethod
     def _parse_date(raw) -> Optional[datetime]:
         if not raw or not isinstance(raw, str):

src/common/frame_timing.py

@@ -19,8 +19,9 @@ Only intervals between two consecutive *scrolling* frames count: a static
 screen that changes once a second has no timing to get wrong, and the first
 frame of a scroll has no predecessor worth measuring against.
 
-"Scrolling" is DisplayManager's scroll state when the frame is presented, and
-that state can go missing in the middle of a scroll. It expires after 2s
+"Scrolling" is the scroll state ``DisplayManager.update_display`` acted on for
+the frame, sampled once before the blit and swap, and that state can go missing
+in the middle of a scroll. It expires after 2s
 without scroll activity, which a long enough stall outlasts, and any thread can
 clear it: plugins call ``set_scrolling_state(False)`` from their own
 ``display()``, and Vegas captures some of those on the render thread between
@@ -38,12 +39,20 @@ after the one before it. One that arrives a whole refresh or more after that is
 a visible hitch. ``missed_refreshes`` sums how many refreshes late.
 
 An interval of ``FREEZE_SECONDS`` or more is a **freeze** instead -- a
-recompose, a plugin handover, a blocking call on the render thread. Those are
-counted separately, both because they are a different fault and because
-folding a single 400ms handover into the late count as "40 missed refreshes"
-would drown the jitter the late count exists to measure. ``freeze_by`` splits
-them by length. Intervals of ``GAP_SECONDS`` or more are ignored as not being
-frames of one scroll at all.
+recompose, a plugin handover nobody tagged (see below), a blocking call on the
+render thread. Those are counted separately, both because they are a different
+fault and because folding a single 400ms handover into the late count as "40
+missed refreshes" would drown the jitter the late count exists to measure.
+``freeze_by`` splits them by length. Intervals of ``GAP_SECONDS`` or more are
+ignored as not being frames of one scroll at all.
+
+One kind of freeze is not a scroll stalling at all: the gap from one screen's
+last frame to the next screen's first, while the next screen draws. The
+display controller tags that frame ``handover`` (see "Operations") at the
+start of every turn, the same mode's again included, and a tagged freeze is
+counted in ``handover_freezes`` instead of ``freezes`` and ``freeze_by``.
+Stats written before that field existed have handovers among their freezes,
+so freeze counts from before and after it are not comparable.
 
 A frame that arrives a whole refresh or more *early* means the swap did not
 wait for the panel: the emulator, the fallback display, or a hold that was not
@@ -66,6 +75,35 @@ faster than the panel (every frame early) or sits at half its rate (every
 frame late), both of which look self-consistent to an estimate taken from
 their own intervals.
 
+Operations
+----------
+The late count says how often, not which work did it. Render-thread work that
+happens between two frames -- extending the Vegas strip, patching a live
+element into it -- calls :meth:`FrameTimingRecorder.note_op` first, and the
+next presented frame carries the tag: the interval that frame ends is the one
+the work landed in. ``op_frames`` counts timed frames per kind,
+``late_op_frames`` the late ones among them, ``op_freezes`` those that were a
+freeze instead, and ``op_bytes`` what the work moved. A kind whose late rate
+sits well above the overall one is the work to look at.
+
+``handover`` (:data:`HANDOVER_OP`) is noted off the render thread: the display
+controller notes it just before it starts a screen's first ``display()``,
+which presents from a thread of its own, and drops the note again with
+:meth:`FrameTimingRecorder.drop_op` once that call returns, so a first
+``display()`` that drew nothing cannot leave the tag for an unrelated frame.
+
+Garbage collection
+------------------
+
+Python's cyclic collector stops every thread while it runs. :class:`GcMonitor`
+times each collection from ``gc.callbacks``; the display manager installs one
+per process. A collection of ``GC_PAUSE_SECONDS`` or more tags the next
+presented frame ``gc`` (:data:`GC_OP`), so it shows in ``op_frames``,
+``late_op_frames`` and ``op_freezes`` like noted work, and the snapshot carries
+a ``gc`` block of cumulative counters: collections and seconds per generation,
+the longest, and the long ones. A stall dump says when a long collection ran
+inside the stall. Diagnostic only: nothing tunes or freezes the collector.
+
 Stall watchdog
 --------------
 Counting a freeze says that it happened, not why. ``StallWatchdog`` watches the
@@ -83,7 +121,9 @@ three times per threshold, so keep it to diagnostic runs, not soaks.
 
 from __future__ import annotations
 
+import atexit
 import copy
+import gc
 import json
 import logging
 import os
@@ -122,6 +162,16 @@ RESUME_SECONDS = 1.0
 FREEZE_BUCKETS = ((0.5, "<0.5s"), (1.0, "0.5-1s"), (2.0, "1-2s"),
                   (float("inf"), "2s+"))
 
+#: The op the display controller notes before a screen's first frame. A
+#: freeze it ends is a handover, counted apart from the freezes; see
+#: "What is counted".
+HANDOVER_OP = "handover"
+
+#: The op a garbage collection of ``GC_PAUSE_SECONDS`` or more tags the next
+#: frame with; see "Garbage collection".
+GC_OP = "gc"
+GC_PAUSE_SECONDS = 0.020
+
 #: A window may lower the refresh-period estimate by at most this fraction.
 MAX_REFRESH_DROP = 0.2
 
@@ -153,11 +203,128 @@ def default_stats_path() -> str:
     return os.path.join(base, STATS_FILENAME)
 
 
+class GcMonitor:
+    """Times every garbage collection, from ``gc.callbacks``.
+
+    Python's cyclic collector stops every thread for as long as a collection
+    takes, and a full one over a large heap (a season of game dicts) can take
+    longer than a frame. Nothing measured that, so a stall it caused looked
+    like any other. The callback runs inside the collection, with the GIL
+    held, and collections never overlap, so these plain counters need no
+    lock: the render thread and the stats writer only read them.
+
+    Install it once per process with :func:`install_gc_monitor`.
+
+    Collections still run while the interpreter shuts down, after module
+    globals such as ``time`` may already be torn down to ``None``. The clock
+    and ``sys.is_finalizing`` are bound here so the callback never looks a
+    global up, it does nothing once finalization has begun, and
+    :func:`install_gc_monitor` unregisters it at exit anyway.
+    """
+
+    def __init__(self, threshold: float = GC_PAUSE_SECONDS,
+                 clock: Callable[[], float] = time.perf_counter):
+        self.threshold = threshold
+        self._clock = clock
+        self._is_finalizing = sys.is_finalizing
+        self._started: Optional[float] = None
+        #: Per generation (0, 1, 2), since the monitor was installed.
+        self.collections = [0, 0, 0]
+        self.seconds = [0.0, 0.0, 0.0]
+        self.max_seconds = 0.0
+        #: Collections of ``threshold`` or more, and their total length. The
+        #: recorder compares ``long_pauses`` with the count it last saw to tag
+        #: the next frame.
+        self.long_pauses = 0
+        self.long_seconds = 0.0
+        #: ``time.perf_counter()`` at the end of the last long collection,
+        #: and its length, for the stall watchdog.
+        self.last_long: Optional[Tuple[float, float]] = None
+
+    def __call__(self, phase: str, info: Dict[str, Any]) -> None:
+        if self._is_finalizing():
+            return
+        now = self._clock()
+        if phase == "start":
+            self._started = now
+            return
+        started, self._started = self._started, None
+        if started is None:
+            return
+        took = now - started
+        generation = min(max(int(info.get("generation", 0)), 0), 2)
+        self.collections[generation] += 1
+        self.seconds[generation] += took
+        if took > self.max_seconds:
+            self.max_seconds = took
+        if took >= self.threshold:
+            self.long_seconds += took
+            self.last_long = (now, took)
+            self.long_pauses += 1
+
+    def snapshot(self) -> Dict[str, Any]:
+        """Cumulative counters for the stats file (all since installation)."""
+        return {
+            "threshold_ms": round(self.threshold * 1000.0, 3),
+            "collections": list(self.collections),
+            "seconds": [round(x, 6) for x in self.seconds],
+            "max_ms": round(self.max_seconds * 1000.0, 3),
+            "long_pauses": self.long_pauses,
+            "long_seconds": round(self.long_seconds, 6),
+        }
+
+
+_gc_monitor: Optional[GcMonitor] = None
+_gc_monitor_lock = threading.Lock()
+
+
+def install_gc_monitor() -> GcMonitor:
+    """The process's GcMonitor, installed in ``gc.callbacks`` on first call.
+
+    It is unregistered at exit (:func:`uninstall_gc_monitor`), before the
+    interpreter tears module globals down.
+    """
+    global _gc_monitor
+    with _gc_monitor_lock:
+        if _gc_monitor is None:
+            _gc_monitor = GcMonitor()
+            gc.callbacks.append(_gc_monitor)
+            atexit.register(uninstall_gc_monitor)
+        return _gc_monitor
+
+
+def uninstall_gc_monitor() -> None:
+    """Take the process's GcMonitor out of ``gc.callbacks``; safe to repeat.
+
+    A recorder that still holds the monitor keeps its counters; they just
+    stop moving. The next :func:`install_gc_monitor` installs a fresh one.
+    """
+    global _gc_monitor
+    with _gc_monitor_lock:
+        monitor, _gc_monitor = _gc_monitor, None
+        if monitor is None:
+            return
+        atexit.unregister(uninstall_gc_monitor)
+        try:
+            gc.callbacks.remove(monitor)
+        except ValueError:
+            pass
+
+
+#: One presented frame's interval: (interval, blit, wait, hold, ops), where
+#: ops is the work noted before it (kind -> bytes) or None.
+_Frame = Tuple[float, float, float, int, Optional[Dict[str, int]]]
+
+
 def _bucket(seconds: float) -> int:
     index = int(seconds * 1000.0 / BUCKET_MS)
     return min(max(index, 0), BUCKET_COUNT - 1)
 
 
+def _bump(counter: Dict[str, int], key: str, by: int = 1) -> None:
+    counter[key] = counter.get(key, 0) + by
+
+
 def binding_releases_gil() -> Optional[bool]:
     """Whether the loaded rgbmatrix binding releases the GIL, or None.
 
@@ -239,23 +406,31 @@ class FrameTimingRecorder:
         flush_interval: float = FLUSH_INTERVAL,
         info: Optional[Dict[str, Any]] = None,
         refresh_hz: Optional[float] = None,
+        gc_monitor: Optional[GcMonitor] = None,
     ):
         """
         :param refresh_hz: the panel's rate, measured independently (see the
             module docstring). Omit it to estimate from the frames alone, as
             the display service does.
+        :param gc_monitor: tags frames after a long garbage collection and
+            adds its counters to the stats (see "Garbage collection"). The
+            display manager passes the process's :func:`install_gc_monitor`.
         """
         self.path = path or default_stats_path()
         self.flush_interval = flush_interval
         self.info = dict(info or {})
 
         # Render-thread state.
-        self._pending: List[Tuple[float, float, float, int]] = []
+        self._pending: List[_Frame] = []
         self._static_frames = 0
         self._previous: Optional[Tuple[float, bool, int]] = None
         # The interval ended by a static frame that followed a scrolling one,
         # until the next frame shows whether the scroll went on.
-        self._unsure: Optional[Tuple[float, float, float, int]] = None
+        self._unsure: Optional[_Frame] = None
+        # Work noted since the last frame (kind -> bytes), for the next one.
+        self._ops: Optional[Dict[str, int]] = None
+        self.gc_monitor = gc_monitor
+        self._gc_seen = gc_monitor.long_pauses if gc_monitor is not None else 0
         self._last_flush: Optional[float] = None
         self._queue: "queue.SimpleQueue" = queue.SimpleQueue()
         self._worker: Optional[threading.Thread] = None
@@ -280,7 +455,16 @@ class FrameTimingRecorder:
             "freezes": 0,
             "freeze_seconds": 0.0,
             "freeze_by": {label: 0 for _, label in FREEZE_BUCKETS},
+            # Freezes that ended a screen handover rather than stalled a
+            # scroll: in neither of the two above. Additive; see "What is
+            # counted".
+            "handover_freezes": 0,
             "worst_interval_ms": 0.0,
+            # Per kind of noted render-thread work; see "Operations".
+            "op_frames": {},
+            "late_op_frames": {},
+            "op_freezes": {},
+            "op_bytes": {},
         }
         self.histograms: Dict[str, Dict[int, int]] = {
             "blit": {}, "wait": {}, "work": {}, "interval_per_hold": {},
@@ -305,6 +489,37 @@ class FrameTimingRecorder:
 
     # -- render thread ------------------------------------------------------
 
+    def note_op(self, kind: str, nbytes: int = 0) -> None:
+        """Tag the next presented frame with work done before it.
+
+        Render thread only, like :meth:`record`, which consumes the tag: the
+        interval the next frame ends is the one this work landed in. Several
+        notes before one frame accumulate, per kind. See "Operations" (and
+        :data:`HANDOVER_OP`, the one note made from another thread).
+
+        :param kind: a short name for the work, e.g. ``"extend"``, ``"patch"``.
+        :param nbytes: how much the work moved, summed into ``op_bytes``.
+        """
+        ops = self._ops
+        if ops is None:
+            ops = self._ops = {}
+        ops[kind] = ops.get(kind, 0) + int(nbytes)
+
+    def drop_op(self, kind: str) -> None:
+        """Forget a note of ``kind`` that no frame has carried yet.
+
+        For work that may present nothing: the display controller notes a
+        handover before a screen's first ``display()`` and drops it once that
+        returns. When the call drew a frame, the frame already took the tag
+        and this does nothing; when it drew nothing (no content), the tag
+        would otherwise land on whatever frame came next -- seconds or minutes
+        later, and nothing to do with the handover. Other kinds noted for the
+        same frame are kept.
+        """
+        ops = self._ops
+        if ops is not None:
+            ops.pop(kind, None)
+
     def record(self, blit: float, wait: float, hold: int, scrolling: bool,
                presented_at: float) -> None:
         """One frame reached the panel.
@@ -312,12 +527,24 @@ class FrameTimingRecorder:
         :param blit: seconds spent copying the frame into the canvas.
         :param wait: seconds SwapOnVSync blocked.
         :param hold: the refreshes this frame was held for.
-        :param scrolling: whether a scroll was running when it was presented.
+        :param scrolling: whether a scroll was running for this frame: the
+            scroll state ``update_display`` acted on, sampled once before the
+            blit and swap.
         :param presented_at: ``time.perf_counter()`` when the swap returned.
         """
         previous = self._previous
         self._previous = (presented_at, scrolling, hold)
         self.last_frame = (presented_at, scrolling, threading.get_ident())
+        ops, self._ops = self._ops, None
+        monitor = self.gc_monitor
+        if monitor is not None and monitor.long_pauses != self._gc_seen:
+            # A long collection ran since the last frame: the interval this
+            # frame ends is the one it landed in. Read here rather than
+            # noted, since note_op is the render thread's and a collection
+            # runs on whichever thread triggered it.
+            self._gc_seen = monitor.long_pauses
+            ops = dict(ops) if ops else {}
+            ops[GC_OP] = ops.get(GC_OP, 0)
         if not scrolling:
             self._static_frames += 1
             # The scroll ended, or its state went missing for this frame: the
@@ -325,7 +552,8 @@ class FrameTimingRecorder:
             # state, so the interval is due at the scroll's own.
             self._unsure = None
             if previous is not None and previous[1]:
-                self._unsure = (presented_at - previous[0], blit, wait, previous[2])
+                self._unsure = (presented_at - previous[0], blit, wait,
+                                previous[2], ops)
         elif self.watchdog is None and self.scrolling_now is not None \
                 and os.environ.get("LEDMATRIX_STALL_WATCHDOG", "1") != "0":
             self.watchdog = StallWatchdog(self, **watchdog_settings())
@@ -335,14 +563,14 @@ class FrameTimingRecorder:
             unsure, self._unsure = self._unsure, None
             if previous[1]:
                 if interval < GAP_SECONDS:
-                    self._pending.append((interval, blit, wait, hold))
+                    self._pending.append((interval, blit, wait, hold, ops))
             elif unsure is not None and interval < RESUME_SECONDS:
                 # One static frame between two scrolling ones: the scroll never
                 # stopped, only its state did. Both intervals were motion.
                 self._static_frames -= 1
                 if unsure[0] < GAP_SECONDS:
                     self._pending.append(unsure)
-                self._pending.append((interval, blit, wait, hold))
+                self._pending.append((interval, blit, wait, hold, ops))
 
         if self._last_flush is None:
             self._last_flush = presented_at
@@ -382,15 +610,17 @@ class FrameTimingRecorder:
             except Exception:  # never let telemetry take anything down
                 logger.debug("Frame timing flush failed", exc_info=True)
 
-    def aggregate(self, batch: List[Tuple[float, float, float, int]],
-                  static: int) -> None:
-        """Fold one window of frames into the running totals."""
+    def aggregate(self, batch: List[_Frame], static: int) -> None:
+        """Fold one window of frames into the running totals.
+
+        Each frame is ``(interval, blit, wait, hold, ops)``; ``ops`` (the work
+        noted before it, or None) may be left off.
+        """
         totals = self.totals
         totals["static_frames"] += static
 
-        per_hold = sorted(interval / max(1, hold)
-                          for interval, _, _, hold in batch
-                          if interval < FREEZE_SECONDS)
+        per_hold = sorted(frame[0] / max(1, frame[3]) for frame in batch
+                          if frame[0] < FREEZE_SECONDS)
         if len(per_hold) >= MIN_FRAMES_FOR_REFRESH:
             estimate = per_hold[len(per_hold) // 10]
             current = self.refresh_period
@@ -412,10 +642,23 @@ class FrameTimingRecorder:
         period = self.refresh_period
 
         histograms = self.histograms
-        for interval, blit, wait, hold in batch:
+        for frame in batch:
+            interval, blit, wait, hold = frame[:4]
+            ops = frame[4] if len(frame) > 4 else None
             totals["worst_interval_ms"] = max(totals["worst_interval_ms"],
                                               interval * 1000.0)
+            if ops:
+                for kind, nbytes in ops.items():
+                    _bump(totals["op_bytes"], kind, nbytes)
             if interval >= FREEZE_SECONDS:
+                for kind in ops or ():
+                    _bump(totals["op_freezes"], kind)
+                if ops and HANDOVER_OP in ops:
+                    # The next screen drawing its first frame, not a scroll
+                    # that stalled: counted apart, so the freezes keep
+                    # meaning the second. See "What is counted".
+                    totals["handover_freezes"] += 1
+                    continue
                 totals["freezes"] += 1
                 totals["freeze_seconds"] += interval
                 label = next(name for limit, name in FREEZE_BUCKETS
@@ -432,6 +675,10 @@ class FrameTimingRecorder:
             if period:
                 totals["timed_frames"] += 1
                 missed = round(interval / period) - hold
+                for kind in ops or ():
+                    _bump(totals["op_frames"], kind)
+                    if missed >= 1:
+                        _bump(totals["late_op_frames"], kind)
                 if missed >= 1:
                     totals["late_frames"] += 1
                     totals["missed_refreshes"] += missed
@@ -460,6 +707,9 @@ class FrameTimingRecorder:
             "binding_releases_gil": self._binding_gil,
             "info": info,
             "totals": copy.deepcopy(self.totals),
+            # Additive: absent from older files and when no monitor is set.
+            **({"gc": self.gc_monitor.snapshot()}
+               if self.gc_monitor is not None else {}),
             # JSON keys are strings; readers convert back.
             "histograms": {name: {str(k): v for k, v in sorted(h.items())}
                            for name, h in self.histograms.items()},
@@ -590,14 +840,28 @@ class StallWatchdog:
         return stall_from, dumped
 
     def describe(self, ident: int, age: float, late: float) -> str:
-        """The stack dump: the stalled thread in full, the rest in brief."""
+        """The stack dump: the stalled thread in full, the rest in brief.
+
+        A stall while a ``handover`` note is still waiting for its frame is
+        the next screen's first ``display()`` taking its time, not a scroll
+        that stopped, and is labelled a handover gap.
+        """
         names = {t.ident: t.name for t in threading.enumerate()}
         frames = sys._current_frames()
+        pending = getattr(self.recorder, "_ops", None)
+        where = ("in a handover gap" if pending and HANDOVER_OP in pending
+                 else "mid-scroll")
+        monitor = getattr(self.recorder, "gc_monitor", None)
+        last_long = getattr(monitor, "last_long", None)
+        gc_note = ""
+        if last_long is not None and time.perf_counter() - last_long[0] <= age:
+            gc_note = (f"; a {last_long[1] * 1000.0:.0f}ms garbage collection "
+                       "ran inside it")
         lines = [
-            f"Render stall: no frame for {age * 1000.0:.0f}ms mid-scroll "
+            f"Render stall: no frame for {age * 1000.0:.0f}ms {where} "
             f"(watchdog woke {late * 1000.0:.0f}ms late"
             + ("; the interpreter itself was blocked" if late >= age / 2 else "")
-            + ")",
+            + gc_note + ")",
             f"-- {names.get(ident, ident)} (presents frames):",
         ]
         stalled = frames.get(ident)

src/common/scroll_config.py

@@ -157,7 +157,13 @@ def crisp_ladder(
 #: 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
+_LOWISH_FPS_PENALTY = 0.16  # below 30fps, i.e. "slightly stepped"
+# Up to 30fps, matching CrispSpeed.steppiness: a measured 125.7Hz panel makes
+# 50.3px/s (2px every 5 refreshes) 25.1fps, which a 25fps cutoff let through.
+# 0.16, not less: asked for 50px/s on a 120Hz panel, 48px/s (2px every 5
+# refreshes, 24fps) costs 0.04 + 0.05 + this, and has to lose to both 60px/s
+# and 40px/s (1px, smooth, 20% off = 0.20). At 0.10 it won and shipped a
+# visibly stepped scroll to anyone asking for the default.
 
 
 def _quality_cost(candidate: "CrispSpeed", target: float) -> float:
@@ -173,7 +179,7 @@ def _quality_cost(candidate: "CrispSpeed", target: float) -> float:
     fps = candidate.frames_per_second
     if fps < 20:
         cost += _SLOW_FPS_PENALTY
-    elif fps < 25:
+    elif fps < 30:
         cost += _LOWISH_FPS_PENALTY
     return cost
 
@@ -474,3 +480,61 @@ def refresh_hz_from_config(global_config: Optional[Dict[str, Any]]) -> float:
     if not isinstance(hardware, dict):
         return DEFAULT_REFRESH_HZ
     return _coerce(hardware.get("limit_refresh_rate_hz")) or DEFAULT_REFRESH_HZ
+
+
+#: Smooth options offered next to a speed that is not one itself.
+_ADVICE_ALTERNATIVES = 2
+
+
+def speed_advice(
+    requested_pixels_per_second: float,
+    refresh_hz: float,
+    min_pixels_per_second: float = MIN_PIXELS_PER_SECOND,
+    max_pixels_per_second: float = MAX_PIXELS_PER_SECOND,
+) -> Dict[str, Any]:
+    """What the panel will do with a requested speed, for showing in a UI.
+
+    ``applied`` is what :func:`solve_crisp` picks, i.e. what really runs.
+    ``smooth`` is true when that is single-pixel-ish, 30fps-or-better motion.
+    ``alternatives`` are the smooth ladder entries nearest the request inside
+    the given range, for a click-to-apply suggestion; empty when the request
+    already is one.
+    """
+    hz = _coerce(refresh_hz) or DEFAULT_REFRESH_HZ
+    requested = max(MIN_PIXELS_PER_SECOND,
+                    min(MAX_PIXELS_PER_SECOND, _coerce(requested_pixels_per_second) or 0.0))
+    applied = solve_crisp(requested, hz)
+
+    def as_dict(c: CrispSpeed) -> Dict[str, Any]:
+        return {
+            "pixels_per_second": round(c.pixels_per_second, 1),
+            "pixels_per_frame": c.pixels_per_frame,
+            "frame_hold": c.frame_hold,
+            "frames_per_second": round(c.frames_per_second, 1),
+            "steppiness": c.steppiness,
+        }
+
+    smooth_ladder = [
+        c for c in crisp_ladder(hz)
+        if c.steppiness == "smooth"
+        and min_pixels_per_second <= c.pixels_per_second <= max_pixels_per_second
+    ]
+    # 2%: a UI hands over whole numbers, and 63 asked of a 62.9 px/s panel is
+    # as good as exact.
+    exact = abs(applied.pixels_per_second - requested) <= max(0.05, 0.02 * requested)
+    smooth = applied.steppiness == "smooth"
+    alternatives: List[CrispSpeed] = []
+    if not (exact and smooth):
+        alternatives = sorted(
+            smooth_ladder,
+            key=lambda c: abs(c.pixels_per_second - requested),
+        )[:_ADVICE_ALTERNATIVES]
+        alternatives.sort(key=lambda c: c.pixels_per_second)
+    return {
+        "requested": round(requested, 1),
+        "refresh_hz": round(hz, 1),
+        "applied": as_dict(applied),
+        "exact": exact,
+        "smooth": smooth,
+        "alternatives": [as_dict(c) for c in alternatives],
+    }

src/common/scroll_helper.py

@@ -18,7 +18,7 @@ Features:
 import logging
 import math
 import time
-from typing import Optional, Dict, Any
+from typing import Optional, Dict, Any, List, Tuple
 from PIL import Image
 import numpy as np
 
@@ -28,6 +28,39 @@ import numpy as np
 # long over one frame, so a sample this large is an idle gap between scrolls.
 FPS_LOG_INTERVAL = 5.0
 
+# The stats line goes to INFO only when a window is worth an operator's
+# attention, as Vegas's FPS line does (src/vegas_mode/coordinator.py): every
+# 5s from every scroller was most of the journal on a healthy rig. A window is
+# degraded when its frame rate falls below this fraction of the rate it was
+# locked to (1 / its own median frame time; same 0.9 as Vegas) ...
+STATS_HEALTHY_FRACTION = 0.9
+# ... or when more than this share of its frames stalled (past 1.5x the
+# median). A 1% stall rate barely moves the mean, so the fps test alone would
+# miss the judder this line exists to show.
+STATS_DEGRADED_STALL_RATE = 0.01
+# A healthy scroller still logs at INFO this often, so silence in the journal
+# means stopped rather than fine. Every window is still logged at DEBUG.
+STATS_HEARTBEAT_INTERVAL = 300.0
+
+
+def frame_stats_degraded(stats: Dict[str, Any]) -> bool:
+    """Whether one frame_stats() window is worth logging at INFO."""
+    n = stats["frames"]
+    if n == 0 or stats["median"] <= 0:
+        return False
+    locked_fps = 1.0 / stats["median"]
+    return (stats["fps"] < locked_fps * STATS_HEALTHY_FRACTION
+            or stats["stalls"] > n * STATS_DEGRADED_STALL_RATE)
+
+
+def _rgb_pixels(item) -> np.ndarray:
+    """An appended item's pixels as an RGB array, as pasting it would draw them."""
+    if isinstance(item, np.ndarray):
+        return item
+    if item.mode != 'RGB':
+        item = item.convert('RGB')
+    return np.asarray(item)
+
 
 def frame_stats(frame_times: list) -> Dict[str, Any]:
     """Summary statistics over one window of frame durations (seconds).
@@ -111,9 +144,21 @@ class ScrollHelper:
         self.total_distance_scrolled = 0.0  # Track total distance including wrap-arounds
         self.scroll_speed = 1.0
         self.scroll_delay = 0.001  # Minimal delay for high FPS (1ms)
-        self.cached_image: Optional[Image.Image] = None
+        self.cached_image = None   # see the property below
         self.cached_array: Optional[np.ndarray] = None  # Numpy array cache for fast operations
         self.total_scroll_width = 0
+        # An extended strip lives in a buffer with spare room after it, and
+        # cached_array is a view of the buffer's live columns: an append writes
+        # only the new columns, and a trim only moves the view's start. See
+        # append_content. _strip_view is the view this helper last made; a
+        # cached_array that is anything else was set from outside and is not
+        # written through.
+        self._strip_buffer: Optional[np.ndarray] = None
+        self._strip_view: Optional[np.ndarray] = None
+        self._strip_start = 0
+        #: Bytes the last append_content / drop_scrolled_prefix copied, for
+        #: frame-timing attribution (src/common/frame_timing.py note_op).
+        self.last_copy_bytes = 0
         
         # Pre-allocated buffer for output frame (reused to avoid allocations)
         self._frame_buffer: Optional[np.ndarray] = None
@@ -168,11 +213,62 @@ class ScrollHelper:
         # 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 = []
+        # INFO-level stats bookkeeping (see STATS_HEARTBEAT_INTERVAL). Kept
+        # across reset_scroll(): a heartbeat per scroll start would bring the
+        # chatter back. 0.0 so the first window after start-up is at INFO.
+        self._stats_last_info_log = 0.0
+        self._stats_was_degraded = False
         
         # Scrolling state management
         self.is_scrolling = False
         self.scroll_complete = False
-        
+
+    # -- the strip as a PIL image ---------------------------------------------
+    #
+    # Every frame is cut from cached_array; nothing on the frame path reads the
+    # PIL image's pixels. Extending and trimming a strip (append_content,
+    # drop_scrolled_prefix) used to rebuild that image in full each time
+    # anyway: Image.fromarray of a Vegas-sized strip is 1.7-3.8ms on a Pi 4,
+    # twice per extension, on the render thread. Those two now leave it to be
+    # built from the array on first read, which in Vegas means only by a
+    # multi-display sync push -- and the strip is not held twice in memory.
+    #
+    # Assigning cached_image still stores exactly what was assigned; a lazy
+    # image is only ever one the helper derived from its own array.
+
+    @property
+    def cached_image(self) -> Optional[Image.Image]:
+        """The strip as a PIL image, built from ``cached_array`` if deferred."""
+        image = self.__dict__.get('_cached_image')
+        if image is not None:
+            return image
+        source = self.__dict__.get('_image_source')
+        if source is None:
+            return None
+        # Built from the array this read started with. Another thread (the
+        # sync push) may read while the render thread extends the strip; it
+        # then gets the strip as it was, as it did when the image was built
+        # eagerly, and the stale build is not kept.
+        image = Image.fromarray(source)
+        if self.__dict__.get('_image_source') is source:
+            self._cached_image = image
+        return image
+
+    @cached_image.setter
+    def cached_image(self, image: Optional[Image.Image]) -> None:
+        self._cached_image = image
+        self._image_source = None
+
+    def _defer_image(self) -> None:
+        """The array just changed under the image: rebuild it only if read."""
+        self._cached_image = None
+        self._image_source = self.cached_array
+
+    def has_strip(self) -> bool:
+        """Whether there is a strip (an image, or one deferred), not reading it."""
+        return (self.__dict__.get('_cached_image') is not None
+                or self.__dict__.get('_image_source') is not None)
+
     def create_scrolling_image(self, content_items: list,
                              item_gap: int = 32,
                              element_gap: int = 16,
@@ -203,6 +299,7 @@ class ScrollHelper:
             self.total_scroll_width = 0
             self.cached_image = Image.new('RGB', (self.display_width, self.display_height), (0, 0, 0))
             self.cached_array = np.array(self.cached_image)
+            self._forget_strip_buffer()
             self.scroll_position = 0.0
             self.total_distance_scrolled = 0.0
             self.scroll_complete = False
@@ -238,6 +335,7 @@ class ScrollHelper:
         self.cached_image = full_image
         # Convert to numpy array for fast operations
         self.cached_array = np.array(full_image)
+        self._forget_strip_buffer()
         actual_image_width = full_image.width
         self.total_scroll_width = actual_image_width
         
@@ -283,7 +381,7 @@ class ScrollHelper:
         Otherwise the position advances by elapsed time at the configured
         speed.
         """
-        if not self.cached_image:
+        if not self.has_strip():
             return
         
         # Calculate frame time for consistent scroll speed regardless of FPS
@@ -427,7 +525,7 @@ class ScrollHelper:
         Returns:
             PIL Image showing the visible portion, or None if no cached image
         """
-        if not self.cached_image or self.cached_array is None:
+        if self.cached_array is None or not self.has_strip():
             return None
 
         start_x_int = int(self.scroll_position)
@@ -463,7 +561,7 @@ class ScrollHelper:
         width = self.display_width
         strip_width = self.cached_array.shape[1]
 
-        if start_x + width + 1 <= strip_width:
+        if 0 <= start_x and start_x + width + 1 <= strip_width:
             # Slice the backing array directly. Going via
             # _get_visible_portion_integer would build two PIL images only for
             # them to be converted straight back to arrays, which measured 15x
@@ -471,9 +569,10 @@ class ScrollHelper:
             near = self.cached_array[:, start_x:start_x + width]
             far = self.cached_array[:, start_x + 1:start_x + 1 + width]
         else:
-            # Close enough to the end that one of the slices wraps; let the
-            # integer path handle that and pay the conversion. Continuous mode
-            # extends the strip before reaching here, so this is the rare case.
+            # One of the slices wraps (close to the end, or a strip narrower
+            # than the panel); let the integer path handle that and pay the
+            # conversion. Continuous mode extends the strip before reaching
+            # here, so this is the rare case.
             near = np.asarray(
                 self._get_visible_portion_integer(start_x, start_x + width))
             far = np.asarray(
@@ -501,33 +600,35 @@ class ScrollHelper:
         slices (128×32 = 12 KB) used here.
         """
         _size = (self.display_width, self.display_height)
-        img_w = self.cached_image.width
+        img_w = self.cached_array.shape[1]
 
-        if end_x <= img_w:
-            # Normal case: single contiguous slice (fastest path)
-            frame_array = np.ascontiguousarray(self.cached_array[:, start_x:end_x])
-            return Image.frombytes('RGB', _size, frame_array.tobytes())
+        if 0 <= start_x and end_x <= img_w:
+            # Normal case: single contiguous slice (fastest path). tobytes()
+            # on the column-slice view already returns C-order bytes, so
+            # ascontiguousarray() first only added a second full-frame copy.
+            return Image.frombytes(
+                'RGB', _size,
+                self.cached_array[:, start_x:end_x].tobytes())
+
+        # Ensure frame buffer is allocated for all non-simple paths
+        if self._frame_buffer is None or self._frame_buffer.shape != (self.display_height, self.display_width, 3):
+            self._frame_buffer = np.zeros((self.display_height, self.display_width, 3), dtype=np.uint8)
+
+        if img_w == 0:
+            self._frame_buffer[:] = 0
         else:
-            # Ensure frame buffer is allocated for all non-simple paths
-            if self._frame_buffer is None or self._frame_buffer.shape != (self.display_height, self.display_width, 3):
-                self._frame_buffer = np.zeros((self.display_height, self.display_width, 3), dtype=np.uint8)
+            # The frame runs off the strip, so it carries on from the head:
+            # frame column j is strip column (start_x + j) modulo the strip's
+            # width -- the tail and then the head, and a strip narrower than
+            # the panel repeated across it. Copying the tail and then the rest
+            # of the frame from the head assumed the head was that wide, and
+            # raised at every position for a strip narrower than the panel
+            # (Vegas composes one, with no lead-in, when its content is
+            # narrower than the chain).
+            np.take(self.cached_array, np.arange(start_x, end_x), axis=1,
+                    mode='wrap', out=self._frame_buffer)
 
-            width1 = img_w - start_x
-            if width1 > 0:
-                # Wrap-around: tail of image + head of image
-                self._frame_buffer[:, :width1] = self.cached_array[:, start_x:]
-                remaining_width = self.display_width - width1
-                self._frame_buffer[:, width1:] = self.cached_array[:, :remaining_width]
-            else:
-                # Edge case: start_x at or past image end — show from beginning,
-                # clamped to available width (scroll_position should wrap before
-                # reaching this state in normal operation).
-                available = min(self.display_width, img_w)
-                self._frame_buffer[:, :available] = self.cached_array[:, :available]
-                if available < self.display_width:
-                    self._frame_buffer[:, available:] = 0
-
-            return Image.frombytes('RGB', _size, self._frame_buffer.tobytes())
+        return Image.frombytes('RGB', _size, self._frame_buffer.tobytes())
     
     def calculate_dynamic_duration(self) -> int:
         """
@@ -634,7 +735,10 @@ class ScrollHelper:
         strip also defers completion, which is the intent.
 
         Args:
-            content_items: Images to append, in order
+            content_items: Images to append, in order. An item may instead be
+                its pixels already as an RGB array (``np.asarray`` of an RGB
+                image), so a caller can do that conversion off the render
+                thread (Vegas prepares its blocks with the group).
             item_gap: Gap between appended items, and between the existing
                 content and the first appended item
             element_gap: Extra gap after each item, mirroring
@@ -646,42 +750,103 @@ class ScrollHelper:
         if not content_items:
             return False
 
-        if self.cached_image is None or self.cached_array is None:
+        if self.cached_array is None or not self.has_strip():
             # Nothing to extend yet — this is just the first build.
             self.create_scrolling_image(
-                content_items, item_gap=item_gap, element_gap=element_gap, lead_gap=0)
+                [Image.fromarray(item) if isinstance(item, np.ndarray) else item
+                 for item in content_items],
+                item_gap=item_gap, element_gap=element_gap, lead_gap=0)
             return True
 
         gap = max(0, item_gap)
-        addition_width = (
-            sum(img.width for img in content_items)
-            + gap * len(content_items)          # one leading gap per item
-            + element_gap * len(content_items)
-        )
-
-        addition = Image.new('RGB', (addition_width, self.display_height), (0, 0, 0))
+        pieces = []
         x = 0
-        for img in content_items:
+        for item in content_items:
             x += gap                            # separate from whatever precedes
-            addition.paste(img, (x, 0))
-            x += img.width + element_gap
+            pixels = _rgb_pixels(item)
+            pieces.append((x, pixels))
+            x += pixels.shape[1] + element_gap
+        addition_width = x
 
-        # numpy concatenate then one conversion back, rather than allocating a
-        # full-width PIL image and pasting twice: the strip can be tens of
-        # thousands of columns wide and this runs on the render path.
-        self.cached_array = np.concatenate(
-            (self.cached_array, np.array(addition)), axis=1)
-        self.cached_image = Image.fromarray(self.cached_array)
-        self.total_scroll_width = self.cached_image.width
+        # Each item is written straight into the spare room after the strip,
+        # when there is some: the strip can be tens of thousands of columns
+        # wide and this runs on the render thread, where copying all of it
+        # (2-3 ms at 512x64 on a Pi 4) -- or even laying the items out in an
+        # image of their own first (another 4-5 ms) -- cost the frame after
+        # every extension. The PIL image is built from the array only if
+        # something reads it (see cached_image).
+        self.cached_array = self._extended_strip(pieces, addition_width)
+        self._defer_image()
+        self.total_scroll_width = self.cached_array.shape[1]
         self.scroll_complete = False
 
-        self.logger.info(
+        # Debug: this runs on the render thread, and the caller (Vegas) logs
+        # each extension itself.
+        self.logger.debug(
             "Appended %d item(s) (%dpx) to scroll strip: now %dpx, position %.0f",
             len(content_items), addition_width, self.total_scroll_width,
             self.scroll_position
         )
         return True
 
+    #: Room an extended strip's buffer is given, as a multiple of what it
+    #: holds when (re)allocated. Trims free columns at the front and appends
+    #: use them at the back, so with 3x the buffer is reallocated -- the one
+    #: full copy -- about once every two strip-lengths scrolled.
+    STRIP_SPARE_FACTOR = 3.0
+
+    def _extended_strip(self, pieces: List[Tuple[int, np.ndarray]], added: int) -> np.ndarray:
+        """The strip with ``added`` black columns after it, ``pieces`` drawn in.
+
+        Each piece is ``(x, pixels)``, x counted from the old strip's end;
+        written in place when the buffer has the room.
+        """
+        live = self.cached_array
+        if live is None:
+            # append_content builds a first strip itself and never comes here.
+            raise RuntimeError("no strip to extend")
+        width = live.shape[1]
+        buffer = self._strip_buffer
+        if (live is self._strip_view and buffer is not None
+                and self._strip_start + width + added <= buffer.shape[1]):
+            end = self._strip_start + width
+            self.last_copy_bytes = 0
+        else:
+            total = width + added
+            buffer = np.empty((live.shape[0], max(total + 1, int(total * self.STRIP_SPARE_FACTOR)))
+                              + live.shape[2:], dtype=live.dtype)
+            buffer[:, :width] = live
+            self._strip_buffer = buffer
+            self._strip_start = 0
+            end = width
+            self.last_copy_bytes = live.nbytes
+        rows = buffer.shape[0]
+        region = buffer[:, end:end + added]
+        # Black only where no piece lands -- the gaps, and below a short
+        # piece: blanking the whole region first cost as much again as
+        # writing the pieces (1.8 ms at 512x64 on a Pi 4).
+        covered = 0
+        for x, pixels in pieces:
+            pixels = pixels[:rows]
+            cols = pixels.shape[1]
+            if x > covered:
+                region[:, covered:x] = 0
+            region[:pixels.shape[0], x:x + cols] = pixels
+            if pixels.shape[0] < rows:
+                region[pixels.shape[0]:, x:x + cols] = 0
+            covered = max(covered, x + cols)
+        if covered < added:
+            region[:, covered:] = 0
+        self.last_copy_bytes += region.nbytes
+        self._strip_view = buffer[:, self._strip_start:self._strip_start + width + added]
+        return self._strip_view
+
+    def _forget_strip_buffer(self) -> None:
+        """A new strip replaces the extended one: let its buffer go."""
+        self._strip_buffer = None
+        self._strip_view = None
+        self._strip_start = 0
+
     def drop_scrolled_prefix(self, keep_before: int = 0) -> int:
         """
         Discard columns that have already scrolled past, to bound memory.
@@ -699,14 +864,15 @@ class ScrollHelper:
         Returns:
             Number of columns actually removed
         """
-        if self.cached_image is None or self.cached_array is None:
+        if self.cached_array is None or not self.has_strip():
             return 0
+        strip_width = self.cached_array.shape[1]
 
         # While the viewport wraps, get_visible_portion fills its right-hand side
         # from the *head* of the strip, so trimming the head would change what
         # is on screen. Continuous mode extends before ever reaching that state;
         # refusing here keeps "trimming is invisible" true unconditionally.
-        if self.scroll_position + self.display_width > self.cached_image.width:
+        if self.scroll_position + self.display_width > strip_width:
             return 0
 
         cut = int(self.scroll_position) - max(0, keep_before)
@@ -714,15 +880,24 @@ class ScrollHelper:
             return 0
         # Never trim so far that the remaining strip is narrower than the
         # viewport, or get_visible_portion has nothing to slice.
-        cut = min(cut, max(0, self.cached_image.width - self.display_width))
+        cut = min(cut, max(0, strip_width - self.display_width))
         if cut <= 0:
             return 0
 
-        # .copy() so the original buffer is released rather than kept alive by
-        # a numpy view.
-        self.cached_array = self.cached_array[:, cut:].copy()
-        self.cached_image = Image.fromarray(self.cached_array)
-        self.total_scroll_width = self.cached_image.width
+        if self.cached_array is self._strip_view:
+            # Only the view's start moves; the columns behind it are reused
+            # when the buffer is next reallocated (append_content).
+            self._strip_view = self.cached_array[:, cut:]
+            self._strip_start += cut
+            self.cached_array = self._strip_view
+            self.last_copy_bytes = 0
+        else:
+            # Not a strip this helper extended: .copy() so the original
+            # buffer is released rather than kept alive by a view.
+            self.cached_array = self.cached_array[:, cut:].copy()
+            self.last_copy_bytes = self.cached_array.nbytes
+        self._defer_image()
+        self.total_scroll_width = self.cached_array.shape[1]
         self.scroll_position -= cut
         self.total_distance_scrolled = max(0.0, self.total_distance_scrolled - cut)
 
@@ -732,9 +907,46 @@ class ScrollHelper:
         )
         return cut
 
+    def patch_columns(self, x: int, pixels: np.ndarray) -> int:
+        """Overwrite the strip's columns from ``x`` with ``pixels``, in place.
+
+        What a live Vegas element update is (src/vegas_mode/elements.py): the
+        strip keeps its width, the scroll keeps its position, and only these
+        columns change. Call it between frames on the thread that draws them;
+        every frame copies its slice out of the strip (get_visible_portion),
+        so no frame already handed on can see half a patch.
+
+        Clipped to the strip at both ends. Refused (0) for an array this
+        helper may not write -- the multi-display follower adopts a read-only
+        one -- or for pixels of another height. The PIL image is deferred, so
+        a later read of cached_image shows the patch.
+
+        Args:
+            x: Strip column of the first column of ``pixels``
+            pixels: uint8 array (height, width, 3)
+
+        Returns:
+            Bytes written.
+        """
+        strip = self.cached_array
+        if strip is None or not strip.flags.writeable:
+            return 0
+        if pixels.ndim != 3 or pixels.shape[0] != strip.shape[0] \
+                or pixels.shape[2] != strip.shape[2]:
+            return 0
+        width = pixels.shape[1]
+        lo, hi = max(0, int(x)), min(strip.shape[1], int(x) + width)
+        if hi <= lo:
+            return 0
+        strip[:, lo:hi] = pixels[:, lo - int(x):hi - int(x)]
+        if self.__dict__.get('_cached_image') is not None \
+                or self.__dict__.get('_image_source') is not None:
+            self._defer_image()
+        return (hi - lo) * strip.shape[0] * strip.shape[2]
+
     def remaining_unscrolled(self) -> int:
         """Columns of strip still to the right of the viewport."""
-        if self.cached_image is None:
+        if not self.has_strip():
             return 0
         return max(0, self.total_scroll_width - int(self.scroll_position)
                    - self.display_width)
@@ -796,6 +1008,7 @@ class ScrollHelper:
         
         # Convert to numpy array for fast operations (required for get_visible_portion)
         self.cached_array = np.array(image)
+        self._forget_strip_buffer()
         
         # Update scroll width
         self.total_scroll_width = image.width
@@ -1026,10 +1239,23 @@ class ScrollHelper:
             # as an idle gap. There is nothing to report, and reporting the
             # gap itself is the bug above.
             if self._window:
-                self.logger.info(
-                    "Scroll frame stats - %s",
-                    format_frame_stats(self._window),
-                )
+                # INFO when degraded, on the window that recovers from it, and
+                # as a slow heartbeat; DEBUG otherwise.
+                degraded = frame_stats_degraded(frame_stats(self._window))
+                if (degraded or self._stats_was_degraded
+                        or current_time - self._stats_last_info_log
+                        >= STATS_HEARTBEAT_INTERVAL):
+                    self.logger.info(
+                        "Scroll frame stats - %s",
+                        format_frame_stats(self._window),
+                    )
+                    self._stats_last_info_log = current_time
+                elif self.logger.isEnabledFor(logging.DEBUG):
+                    self.logger.debug(
+                        "Scroll frame stats - %s",
+                        format_frame_stats(self._window),
+                    )
+                self._stats_was_degraded = degraded
             self.last_fps_log_time = current_time
             self.frame_count = 0
             self._window = []
@@ -1053,6 +1279,7 @@ class ScrollHelper:
         """
         self.cached_image = None
         self.cached_array = None
+        self._forget_strip_buffer()
         self.total_scroll_width = 0
         self.scroll_position = 0.0
         self.total_distance_scrolled = 0.0
@@ -1082,5 +1309,8 @@ class ScrollHelper:
             'elapsed_time': (time.time() - self.scroll_start_time)
             if self.scroll_start_time
             else None,
-            'cached_image_size': (self.cached_image.width, self.cached_image.height) if self.cached_image else None
+            # From the array: reading cached_image would build a deferred one.
+            'cached_image_size': ((self.cached_array.shape[1], self.cached_array.shape[0])
+                                  if self.cached_array is not None and self.has_strip()
+                                  else None)
         }

src/common/snapshot_policy.py

@@ -26,14 +26,33 @@ Policy:
 - Unchanged frames are never re-encoded; the mtime is touched every
   TOUCH_INTERVAL so the health check (60s threshold) never degrades.
 
+The writer and the SSE reader (web_interface/app.py) have two periods, not
+one shared value. The reader sends each write it sees, so the preview shows
+at most one frame per VIEWER_INTERVAL. (That was 0.2 s while the reader
+slept 1 s between reads, so four encodes in five were overwritten unread.)
+The reader checks the file's mtime every VIEWER_POLL_INTERVAL, which is only
+a stat, and so sends each write within that long of it landing. Equal
+periods would alias: two unsynchronised 1 s clocks leave the preview up to a
+second stale, and now and then 2 s between frames.
+
+decide() is monotone in frame_changed: SKIP for a changed frame means SKIP
+for an unchanged one. DisplayManager relies on that to skip hashing the
+frame when even a changed one would be skipped; test_snapshot_policy.py
+checks it.
+
 If any constant here changes, re-check the health threshold in
 api_v3/misc.py (get_hardware_status) — TOUCH_INTERVAL must stay well under it.
 """
 
 from enum import Enum
 
-# Snapshot cadence with a browser preview open (seconds).
-VIEWER_INTERVAL = 0.2
+# Snapshot cadence with a browser preview open (seconds): the shortest gap
+# between two preview frames.
+VIEWER_INTERVAL = 1.0
+# How often the web SSE reader checks the snapshot's mtime (seconds). Must
+# stay well under VIEWER_INTERVAL -- half of it at most -- or the two clocks
+# alias (see above).
+VIEWER_POLL_INTERVAL = 0.25
 # Snapshot cadence with no viewers — cheap freshness for page-open (seconds).
 IDLE_INTERVAL = 30.0
 # Max age of the last write/touch before bumping mtime for the health

src/common/sports_card.py

@@ -18,7 +18,7 @@ the extra guard only stops a None size raising TypeError.
 """
 
 import logging
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 from typing import Any, Dict, Optional, Tuple
 from zoneinfo import ZoneInfo
 
@@ -338,10 +338,46 @@ def format_game_date(config: Optional[Dict[str, Any]], logger, date_text: str,
     if not raw:
         return ""
     fmt = str(scroll_card_option(config, "date_format", "abbrev") or "abbrev")
-    return _format_date_as(fmt, raw, lambda: weekday_for(config, logger, game))
+    return _format_date_as(fmt, raw, lambda: weekday_for(config, logger, game),
+                           game=game)
 
 
-def _format_date_as(fmt: str, raw: str, weekday, months=MONTH_ABBR) -> str:
+def _printed_weekday(game: Optional[Dict], month: int, day: int) -> str:
+    """The weekday of the date a card prints as month/day, or '' if unknown.
+
+    The extractor prints "M/D" in the plugin's resolved zone (its own setting,
+    else the global one, else the system zone). The card cannot see that zone:
+    it is handed the plugin's config, whose ``timezone`` ships as "", so
+    card_tzinfo answers UTC and an evening kickoff in the Americas got the
+    next day's weekday ("Sat Oct 2" for a Friday game). Every zone is within
+    a day of UTC, so the printed date is the start's UTC date or a neighbour
+    of it; the one with that month and day is the date on the card.
+    """
+    if not isinstance(game, dict):
+        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"))
+        if start.utcoffset() is None:
+            return ""  # naive: no instant to place the date against
+        utc_day = start.astimezone(timezone.utc).date()
+    except (ValueError, TypeError, OverflowError):
+        return ""
+    for offset in (0, -1, 1):
+        try:
+            candidate = utc_day + timedelta(days=offset)
+        except OverflowError:
+            continue
+        if (candidate.month, candidate.day) == (month, day):
+            return WEEKDAY_ABBR[candidate.weekday()]
+    return ""
+
+
+def _format_date_as(fmt: str, raw: str, weekday, months=MONTH_ABBR,
+                    game: Optional[Dict] = None) -> str:
     """Render a stripped, non-empty "M/D" *raw* in style *fmt*.
 
     The body both date formatters share. They differ in which setting names the
@@ -349,6 +385,9 @@ def _format_date_as(fmt: str, raw: str, weekday, months=MONTH_ABBR) -> str:
     ``SportsCoreSharedMixin._format_game_date``), so those arrive as arguments:
     *weekday* is a zero-argument callable, only called for the "weekday" style.
     *months* lets the mixin keep reading its (overridable) ``_MONTH_ABBR``.
+    With *game*, the "weekday" style names the printed date's own weekday
+    (:func:`_printed_weekday`), and *weekday* is only the fallback for a
+    date its start time cannot place.
     """
     if fmt == "numeric":
         return raw
@@ -364,7 +403,7 @@ def _format_date_as(fmt: str, raw: str, weekday, months=MONTH_ABBR) -> str:
     if fmt == "day_first":
         return f"{day} {name}"
     if fmt == "weekday":
-        day_name = weekday()
+        day_name = _printed_weekday(game, month, day) or weekday()
         return f"{day_name} {name} {day}" if day_name else f"{name} {day}"
     return f"{name} {day}"
 

src/common/sports_card_wrappers.py

@@ -0,0 +1,136 @@
+"""The ``sports_card`` delegations every scoreboard's game renderer carries.
+
+After the card helpers moved to ``sports_card`` (3.3.0), each of the eight
+scoreboards with a ``game_renderer.py`` -- afl, baseball, basketball,
+football, hockey, lacrosse, nrl and soccer -- kept one-line methods that
+forward to them with its own ``config`` and ``logger``. Seventeen are
+identical in all eight (executable AST, docstrings stripped) or in all but
+football, and were copied here from ledmatrix-plugins ``30455671``
+(origin/main, 2026-09-29) under their existing names. Football's own
+``_format_game_date`` and ``_upcoming_center_mode`` (they follow the
+switch-mode settings when it draws the full-screen scorebug) stay in football
+and override these.
+
+``_schema_font_size`` and ``_resolve_font_size`` look the same in every copy
+but are not moved: they read ``_SCHEMA_PATH``, a module global that is each
+plugin's own ``config_schema.json``.
+
+These are the methods ``SportsGameRendererMixin`` (``sports_game_renderer``)
+lists among what its host must provide, so a renderer that inherits both no
+longer has to write them. Like that mixin this has no ``__init__`` and no
+state. It is a separate module rather than more methods there for the reason
+``sports_helpers`` gives: a missing module fails at load, where the version
+checks see it; a missing method fails mid-render.
+
+WHAT A HOST MUST PROVIDE
+------------------------
+Derived by walking every ``self.<attr>`` the mixin reads; the host-contract
+test in ``test/test_sports_card_wrappers.py`` fails if a read is added
+without being listed here.
+
+- ``config`` and ``logger``.
+- ``fonts``, read with ``getattr`` -- ``_font_color``.
+- ``_FONT_NAME_ALIASES`` and ``_FONT_PIXEL_GRID`` class attributes --
+  ``_crisp_size``, which passes them to ``sports_card.crisp_size`` so a
+  renderer that declares extra faces keeps them.
+
+Add it as a base of the plugin's renderer, e.g.
+``class GameRenderer(SportsCardWrappersMixin, SportsGameRendererMixin)``.
+The two define no name in common; a method on the plugin's own class still
+wins over either.
+"""
+
+import logging
+from typing import Any, ClassVar, Dict, Optional, Tuple
+
+from src.common import sports_card as _card
+
+
+class SportsCardWrappersMixin:
+    """The game renderer's ``sports_card`` delegations. See module docstring."""
+
+    # The host contract, declared for type checking only: these create no
+    # attributes, so the host's own values are what the methods read.
+    config: Dict[str, Any]
+    logger: logging.Logger
+    _FONT_NAME_ALIASES: ClassVar[Dict[str, str]]
+    _FONT_PIXEL_GRID: ClassVar[Dict[str, Any]]
+
+    # ---- fonts ---------------------------------------------------------
+
+    @classmethod
+    def _crisp_size(cls, font_file, desired):
+        """``sports_card.crisp_size`` with this renderer's font tables."""
+        return _card.crisp_size(font_file, desired,
+                                cls._FONT_NAME_ALIASES, cls._FONT_PIXEL_GRID)
+
+    def _unshare_element_fonts(self, fonts):
+        """``sports_card.unshare_element_fonts``."""
+        return _card.unshare_element_fonts(self.logger, fonts)
+
+    def _font_color(self, font, default: Tuple[int, int, int] = (255, 255, 255)):
+        """``sports_card.font_color`` for one of ``self.fonts``."""
+        return _card.font_color(self.config, getattr(self, "fonts", None), font, default)
+
+    # ---- colours and favourites ---------------------------------------
+
+    @staticmethod
+    def _coerce_rgb(value, fallback):
+        """``sports_card.coerce_rgb``."""
+        return _card.coerce_rgb(value, fallback)
+
+    @staticmethod
+    def _side_is_favorite(game: Dict[str, Any], side: str, favorites: set) -> bool:
+        """``sports_card.side_is_favorite``."""
+        return _card.side_is_favorite(game, side, favorites)
+
+    @staticmethod
+    def _side_score(game: Dict[str, Any], side: str) -> Optional[int]:
+        """``sports_card.side_score``."""
+        return _card.side_score(game, side)
+
+    def _favorite_result(self, game: Dict[str, Any]) -> Optional[str]:
+        """``sports_card.favorite_result``."""
+        return _card.favorite_result(self.config, game)
+
+    def _score_color_for(self, game: Dict[str, Any], game_type: str, default=None):
+        """``sports_card.score_color_for``."""
+        return _card.score_color_for(self.config, self.logger, game, game_type, default)
+
+    def _recent_score_color(self, game: Dict[str, Any], default):
+        """``sports_card.recent_score_color``."""
+        return _card.recent_score_color(self.config, self.logger, game, default)
+
+    def _element_color(self, element: str, default: Tuple[int, int, int] = (255, 255, 255)):
+        """``sports_card.element_color``."""
+        return _card.element_color(self.config, element, default)
+
+    # ---- card options, dates and times --------------------------------
+
+    def _scroll_card_option(self, key: str, default: Any = None) -> Any:
+        """``sports_card.scroll_card_option``."""
+        return _card.scroll_card_option(self.config, key, default)
+
+    def _upcoming_center_mode(self) -> str:
+        """``sports_card.upcoming_center_mode``."""
+        return _card.upcoming_center_mode(self.config)
+
+    def _vs_text(self) -> str:
+        """``sports_card.vs_text``."""
+        return _card.vs_text(self.config)
+
+    def _format_game_date(self, date_text: str, game: Optional[Dict] = None) -> str:
+        """``sports_card.format_game_date``."""
+        return _card.format_game_date(self.config, self.logger, date_text, game)
+
+    def _weekday_for(self, game: Optional[Dict]) -> str:
+        """``sports_card.weekday_for``."""
+        return _card.weekday_for(self.config, self.logger, game)
+
+    def _card_tzinfo(self):
+        """``sports_card.card_tzinfo``."""
+        return _card.card_tzinfo(self.config, self.logger)
+
+    def _format_game_time(self, time_text: str) -> str:
+        """``sports_card.format_game_time``."""
+        return _card.format_game_time(self.config, time_text)

src/common/sports_celebration.py

@@ -0,0 +1,780 @@
+"""How the scoreboards draw a score or win celebration.
+
+Five scoreboards -- afl, football, hockey, nrl and soccer -- take over the
+panel when a team scores or wins: a backdrop in the scoring team's colours
+read off its crest, scenery for the kind of score, confetti, the headline and
+the score with the scoring side's digits breathing. The drawing is identical
+in all five ``sports.py`` copies (executable AST, docstrings stripped), and
+so are the colour helpers it uses; they were copied here from
+ledmatrix-plugins ``30455671`` (origin/main, 2026-09-29).
+
+Only the drawing moved. What *arms* a celebration stays in each plugin,
+because it differs: which scores count (``_check_for_goal`` /
+``_check_for_score``, and nrl matches favourites by team id), the phrase and
+the scenery (``_start_celebration``), and when a win fires
+(``_check_for_win``). So does ``display()``, which decides whether the
+takeover or the scorebug is on screen. A plugin hands this mixin a
+celebration dict and it draws it.
+
+The colour helpers are public free functions here (``logo_palette``,
+``lift_color``, ``mix_color``, ...); in the plugins they were the same
+functions with a leading underscore.
+
+THE CELEBRATION DICT
+--------------------
+Built by the plugin's ``_start_celebration``. Read here: ``game`` (a
+view-model dict; ``<side>_id``, ``<side>_abbr``, ``<side>_logo_path`` and
+``<side>_logo_url`` for the crests, ``id`` for the confetti seed),
+``scored_side`` (``"away"`` or ``"home"``), ``away_score``, ``home_score``,
+``phrase``, ``started_at`` (a ``time.time()`` value) and ``motif``
+(``"score"``, ``"kick"``, ``"touchdown"``, ``"net"`` or ``"win"``; anything
+else draws the ``"score"`` diagonals). The drawing caches what it derives in
+the same dict, under ``_palette``, ``_backdrop``, ``_confetti`` and
+``_crests``, so each is worked out once per celebration.
+
+WHAT A HOST MUST PROVIDE
+------------------------
+Derived by walking every ``self.<attr>`` the mixin reads; the host-contract
+test in ``test/test_sports_celebration.py`` fails if a read is added without
+being listed here. All five scoreboards' ``SportsLive`` provide them.
+
+- ``display_manager`` -- ``image`` is replaced with the frame, then
+  ``update_display()``; ``clear()`` on ``force_clear``. Its ``matrix``
+  width and height are used when it has a matrix, else ``display_width`` /
+  ``display_height``.
+- ``fonts`` -- ``"time"`` and ``"status"`` for the headline (the first that
+  fits), ``"score"`` for the score.
+- ``logger``.
+- ``_load_and_resize_logo(team_id, abbr, logo_path, logo_url)`` -- a crest
+  as an RGBA image, or ``None``.
+- ``_draw_text_with_outline(draw, text, position, font, fill=...)`` -- on
+  ``SportsCoreSharedMixin``.
+- ``celebration_duration``, ``celebration_team_colors`` and
+  ``celebration_confetti``, read with ``getattr`` (defaults 8, on, on).
+
+Mix it in ahead of the mode classes, e.g.
+``class SportsLive(SportsCelebrationMixin, SportsLiveSharedMixin,
+SportsCore)``. It defines nothing any of them define, so the order only
+matters for a plugin that keeps its own copy of one of these methods: a
+method on the plugin's class always wins over the mixin's.
+"""
+
+import colorsys
+import logging
+import math
+import random
+import time
+from typing import Any, Callable, ClassVar, Dict, List, Optional, Sequence, Tuple
+
+from PIL import Image, ImageDraw
+
+#: A colour as the helpers return it: three 0-255 channels.
+Color = Tuple[int, ...]
+#: ``deep``, ``glow``, ``headline`` and ``accent``; see ``logo_palette``.
+Palette = Dict[str, Color]
+#: One confetti flake: column, start height, fall speed, sway phase, size
+#: in pixels, colour.
+Flake = Tuple[float, float, float, float, int, Color]
+
+# ----------------------------------------------------------------------
+# Colour helpers for the score/win celebration
+#
+# Module level rather than methods: they are pure, which is what makes the
+# palette testable without standing up a live manager, and they are shared by
+# the takeover's backdrop, confetti and text.
+# ----------------------------------------------------------------------
+
+#: The crest is sampled at this resolution. Big enough that a secondary
+#: colour survives (a helmet stripe, a trim), small enough that the whole
+#: sample is ~1600 pixels of pure-Python work, once per team.
+_PALETTE_SAMPLE_PX = 40
+#: Above this, a colour carries team identity; below it, it is a grey.
+_PALETTE_VIVID_SATURATION = 0.22
+#: Ignore pixels this dark -- crest outlines, drop shadows, anti-aliasing.
+_PALETTE_MIN_CHANNEL = 24
+#: How far apart two bins must be to count as a second, different colour.
+_PALETTE_DISTINCT_DISTANCE = 90.0
+#: Never bleed a lifted colour below this saturation; past it a hue stops
+#: being the team's colour and starts being a pastel.
+_PALETTE_MIN_SATURATION = 0.42
+#: Lift a headline colour until it is at least this luminous. Chosen so
+#: midnight navy reaches a blue that reads at 6px on a panel without
+#: becoming a different colour.
+_PALETTE_HEADLINE_LUMINANCE = 112.0
+#: A crest colour this luminous already reads on a panel, so it is preferred
+#: over a darker one that would have to be lifted to get there. Lifting is a
+#: compromise -- Green Bay's dark green only reaches legibility as a teal --
+#: and most teams whose primary is dark carry a bright second colour that is
+#: just as much theirs. This is what picks the Packers' gold over that teal.
+_PALETTE_LEGIBLE_LUMINANCE = 90.0
+#: ...but only from a colour the crest actually means. The pixels where a
+#: bright edge is anti-aliased into a dark fill are luminous too, and there is
+#: always a band of them: Kansas City's white-on-red outline leaves a pink at
+#: luminance 90 that would otherwise be preferred over the red itself. A blend
+#: is a mix, so it is markedly less saturated than either colour it sits
+#: between -- that pink is 0.48 where the red is 0.96 and the Packers' gold,
+#: which this must keep, is 0.89.
+_PALETTE_LEGIBLE_SATURATION = 0.65
+#: And it has to be a band of the crest, not a speck of one.
+_PALETTE_LEGIBLE_AREA = 0.02
+#: Cap the backdrop's luminance so the headline stays legible over it,
+#: and the scenery's so it stays behind the headline. Both are luminance and
+#: not HSV value on purpose: a silver crest -- the Raiders, or the grey
+#: placeholder a failed logo download leaves behind -- has a value of ~0.95,
+#: and capping that at 0.34 still yields a light grey card that white text
+#: then vanishes into. Scaling the channels down is also hue-exact, which is
+#: what lets this be the plain arithmetic that lifting a colour cannot be.
+_PALETTE_BACKDROP_LUMINANCE = 34.0
+_PALETTE_SCENERY_LUMINANCE = 70.0
+
+
+def rgb_luminance(color: Sequence[float]) -> float:
+    """Rec. 709 relative luminance, 0-255."""
+    return 0.2126 * color[0] + 0.7152 * color[1] + 0.0722 * color[2]
+
+
+def rgb_saturation(color: Sequence[float]) -> float:
+    """HSV saturation, 0-1."""
+    high = max(color)
+    return (high - min(color)) / high if high else 0.0
+
+
+def color_distance(a: Sequence[float], b: Sequence[float]) -> float:
+    """Euclidean distance between two colours in RGB."""
+    return math.sqrt(sum((x - y) ** 2 for x, y in zip(a, b)))
+
+
+def mix_color(a: Sequence[float], b: Sequence[float], t: float) -> Color:
+    """Blend ``a`` towards ``b``; t=0 is all a, t=1 is all b."""
+    t = min(max(t, 0.0), 1.0)
+    return tuple(int(round(a[i] + (b[i] - a[i]) * t)) for i in range(3))
+
+
+def scale_color(color: Sequence[float], factor: float) -> Color:
+    """Scale a colour's brightness, clamped to the panel's range."""
+    return tuple(min(255, max(0, int(round(c * factor)))) for c in color)
+
+
+def lift_color(color: Sequence[float], min_luminance: float = _PALETTE_HEADLINE_LUMINANCE,
+               cap_saturation: float = 0.92) -> Color:
+    """Raise a colour's brightness until it reads on a panel, keeping its hue.
+
+    Scaling the channels directly is what the obvious version of this does,
+    and it shifts hue badly on exactly the colours that need lifting: it turns
+    Baltimore's navy-purple into magenta. Working in HSV and raising only the
+    value leaves the hue where the team put it.
+    """
+    if rgb_luminance(color) >= min_luminance:
+        return tuple(int(c) for c in color)
+    hue, saturation, value = colorsys.rgb_to_hsv(*[c / 255.0 for c in color])
+    if saturation < 0.12:
+        # A grey or a silver has no hue to preserve; just make it bright.
+        lifted = colorsys.hsv_to_rgb(hue, saturation, max(value, 0.85))
+        return tuple(int(round(c * 255)) for c in lifted)
+    saturation = min(saturation, cap_saturation)
+
+    def _rgb(s: float, v: float) -> Color:
+        return tuple(int(round(c * 255)) for c in colorsys.hsv_to_rgb(hue, s, v))
+
+    out = _rgb(saturation, value)
+    while value < 1.0 and rgb_luminance(out) < min_luminance:
+        value = min(1.0, value + 0.05)
+        out = _rgb(saturation, value)
+    # Blue carries almost no luminance -- pure blue sits at 18 of 255 -- so a
+    # navy or a deep purple runs out of value long before it is legible.
+    # Bleeding saturation out of it is the only way up, and it keeps the hue
+    # (Baltimore stays purple, just a lighter one) where giving up would
+    # leave the headline unreadable. Floored so it never washes out to white.
+    while saturation > _PALETTE_MIN_SATURATION and rgb_luminance(out) < min_luminance:
+        saturation = max(_PALETTE_MIN_SATURATION, saturation - 0.05)
+        out = _rgb(saturation, value)
+    return out
+
+
+def cap_luminance(color: Sequence[float], max_luminance: float) -> Color:
+    """Darken a colour until it is no brighter than ``max_luminance``.
+
+    A straight channel scale, which is exactly hue-preserving on the way down
+    -- unlike lifting, where clamping at 255 is what bends the hue.
+    """
+    luminance = rgb_luminance(color)
+    if luminance <= max_luminance or luminance <= 0:
+        return tuple(int(c) for c in color)
+    return scale_color(color, max_luminance / luminance)
+
+
+def dim_rgba(image: Image.Image, factor: float) -> Image.Image:
+    """Scale an RGBA image's colour channels, leaving its alpha alone.
+
+    ImageEnhance.Brightness would scale the alpha band too, which fades the
+    crest out instead of dimming it and leaves its anti-aliased edge looking
+    chewed against the backdrop.
+    """
+    red, green, blue, alpha = image.split()
+    lut = [min(255, int(i * factor)) for i in range(256)]
+    return Image.merge(
+        "RGBA", (red.point(lut), green.point(lut), blue.point(lut), alpha)
+    )
+
+
+_Buckets = Dict[Tuple[int, int, int], List[int]]
+
+
+def _palette_buckets(logo: Image.Image) -> Tuple[_Buckets, _Buckets]:
+    """Bucket a crest's opaque pixels into coarse colour bins.
+
+    Returns ``(vivid, neutral)``; each maps a 3-bit-per-channel key to
+    ``[r_sum, g_sum, b_sum, count]``. Neutral holds the greys, silvers and
+    whites that carry no identity on their own but are all a monochrome crest
+    -- the Raiders' silver on black -- has to offer.
+    """
+    sample = logo.convert("RGBA")
+    sample.thumbnail((_PALETTE_SAMPLE_PX, _PALETTE_SAMPLE_PX), Image.Resampling.BOX)
+    vivid: _Buckets = {}
+    neutral: _Buckets = {}
+    # tobytes() rather than getdata(): same pixels, no per-pixel Python
+    # object, and getdata() is deprecated from Pillow 14.
+    raw = sample.tobytes()
+    for i in range(0, len(raw) - 3, 4):
+        red, green, blue, alpha = raw[i], raw[i + 1], raw[i + 2], raw[i + 3]
+        if alpha < 160:
+            continue
+        high, low = max(red, green, blue), min(red, green, blue)
+        if high < _PALETTE_MIN_CHANNEL:
+            continue
+        target = vivid if (high - low) / high >= _PALETTE_VIVID_SATURATION else neutral
+        acc = target.setdefault((red >> 5, green >> 5, blue >> 5), [0, 0, 0, 0])
+        acc[0] += red
+        acc[1] += green
+        acc[2] += blue
+        acc[3] += 1
+    return vivid, neutral
+
+
+def _bucket_mean(acc: List[int]) -> Color:
+    count = acc[3]
+    return (acc[0] // count, acc[1] // count, acc[2] // count)
+
+
+def _bucket_headline_score(acc: List[int]) -> float:
+    """How well a colour bin would serve as 6px of text on a panel.
+
+    Area alone picks the biggest block of colour, which on a lot of crests is
+    a dark navy fill -- correct as a backdrop, invisible as text. Weighting
+    area by saturation and by luminance picks the colour the team is loud in:
+    Chicago's orange over its navy, Baltimore's gold over its purple.
+    """
+    color = _bucket_mean(acc)
+    return (
+        acc[3]
+        * (0.30 + 0.70 * rgb_saturation(color))
+        * (0.20 + 0.80 * min(1.0, rgb_luminance(color) / 120.0))
+    )
+
+
+def logo_palette(logo: Image.Image) -> Optional[Palette]:
+    """Pick a celebration palette out of a team crest, or None.
+
+    Two rankings, because a crest's largest colour and its most legible one
+    are usually not the same and the takeover needs both:
+
+    * ``deep`` -- the largest vivid area, darkened into the background wash.
+      This is what the team reads as at a glance: Chicago navy, Dallas navy,
+      Baltimore purple.
+    * ``headline`` -- the vivid area that best survives being shrunk to text,
+      then lifted until it is legible: Chicago orange, Baltimore gold.
+    * ``accent`` -- the next vivid colour far enough away from the headline to
+      be told apart, for confetti. Falls back to the headline.
+
+    A crest with no vivid pixels at all falls back to its brightest neutral,
+    which for the Raiders' silver-on-black is exactly the right answer.
+    """
+    try:
+        vivid, neutral = _palette_buckets(logo)
+    except Exception:  # noqa: BLE001 - a crest is never worth the takeover
+        return None
+
+    pool = list(vivid.values())
+    if not pool and neutral:
+        pool = [
+            max(
+                neutral.values(),
+                key=lambda acc: acc[3]
+                * (0.2 + 0.8 * min(1.0, rgb_luminance(_bucket_mean(acc)) / 160.0)),
+            )
+        ]
+    if not pool:
+        return None
+
+    deep_base = _bucket_mean(max(pool, key=lambda acc: acc[3]))
+    ranked = sorted(pool, key=_bucket_headline_score, reverse=True)
+    headline_base = _bucket_mean(ranked[0])
+    vivid_pixels = sum(acc[3] for acc in pool)
+    for acc in ranked:
+        candidate = _bucket_mean(acc)
+        if (
+            rgb_luminance(candidate) >= _PALETTE_LEGIBLE_LUMINANCE
+            and rgb_saturation(candidate) >= _PALETTE_LEGIBLE_SATURATION
+            and acc[3] >= max(3, vivid_pixels * _PALETTE_LEGIBLE_AREA)
+        ):
+            headline_base = candidate
+            break
+    headline = lift_color(headline_base)
+
+    accent = headline
+    for acc in ranked[1:]:
+        candidate = _bucket_mean(acc)
+        if color_distance(candidate, headline_base) > _PALETTE_DISTINCT_DISTANCE:
+            accent = lift_color(candidate)
+            break
+
+    deep = cap_luminance(deep_base, _PALETTE_BACKDROP_LUMINANCE)
+    return {
+        "deep": deep,
+        # Scenery is the backdrop carried a little way towards the headline:
+        # tied to the team's colours, and guaranteed to be visible even when
+        # the backdrop is nearly black.
+        "glow": cap_luminance(
+            mix_color(deep, headline, 0.22), _PALETTE_SCENERY_LUMINANCE
+        ),
+        "headline": headline,
+        "accent": accent,
+    }
+
+
+class SportsCelebrationMixin:
+    """Draws a score/win celebration takeover. See the module docstring."""
+
+    # The host contract, declared for type checking only: these create no
+    # attributes, so the host's own values are what the methods read.
+    display_manager: Any
+    display_width: int
+    display_height: int
+    fonts: Dict[str, Any]
+    logger: logging.Logger
+    _load_and_resize_logo: Callable[..., Optional[Image.Image]]
+    _draw_text_with_outline: Callable[..., None]
+
+    def _fit_font(self, draw, text: str, max_width: int, fonts: list):
+        """Return the first font whose rendered ``text`` fits ``max_width``,
+        falling back to the last (smallest) font."""
+        for font in fonts:
+            if draw.textlength(text, font=font) <= max_width - 2:
+                return font
+        return fonts[-1]
+
+    # ------------------------------------------------------------------
+    # Celebration palette
+    #
+    # The takeover is drawn in the scoring team's own colours, taken from the
+    # pixels of its crest.
+    #
+    # ESPN does serve team.color / team.alternateColor, but only inside
+    # _extract_game_details_common -- a function each scoreboard lineage
+    # keeps its own copy of -- so reading it there would drag every one of
+    # them into a celebration change. The crest is already downloaded,
+    # decoded and sitting in the logo cache by the time a celebration draws,
+    # so the colours come from it instead: no extra request, no per-league
+    # colour table to maintain, and it works for any team ESPN can name --
+    # including the FCS opponents no table would list.
+    #
+    # Where a crest's colour differs from the club's published one it
+    # tends to differ usefully: a published primary is often a near-black
+    # navy, or an actual #000000, where what the crest carries is the colour
+    # that reads on an LED panel. Measured across all 32 clubs in
+    # football-scoreboard.
+    # ------------------------------------------------------------------
+
+    #: Used when the crest yields nothing (no logo on disk yet, or the grey
+    #: placeholder a failed download leaves) or team colours are switched
+    #: off -- the navy and amber the celebration wore before it had a palette.
+    _DEFAULT_CELEBRATION_PALETTE: ClassVar[Palette] = {
+        "deep": (10, 10, 40),
+        "glow": (30, 30, 86),
+        "headline": (255, 208, 56),
+        "accent": (255, 255, 255),
+    }
+
+    def _celebration_palette(self, celebration: Dict) -> Palette:
+        """The scoring team's colours, derived once per celebration."""
+        cached: Optional[Palette] = celebration.get("_palette")
+        if cached is not None:
+            return cached
+
+        palette = dict(self._DEFAULT_CELEBRATION_PALETTE)
+        if getattr(self, "celebration_team_colors", True):
+            try:
+                game = celebration["game"]
+                side = celebration.get("scored_side") or "home"
+                logo = self._load_and_resize_logo(
+                    game.get("%s_id" % side),
+                    game.get("%s_abbr" % side),
+                    game.get("%s_logo_path" % side),
+                    game.get("%s_logo_url" % side),
+                )
+                derived = logo_palette(logo) if logo is not None else None
+                if derived:
+                    palette = derived
+            except Exception as e:  # noqa: BLE001 - never lose a takeover to a crest
+                self.logger.debug(f"Celebration palette fell back to the default: {e}")
+
+        celebration["_palette"] = palette
+        return palette
+
+    # ------------------------------------------------------------------
+    # Celebration choreography
+    #
+    # Every frame is a finished card. The beats below shift the emphasis --
+    # an opening colour hit, confetti, a breathing score -- but none of them
+    # leaves the panel mid-wipe, because on a switch-mode board the core
+    # drives this plugin at 1 FPS (display_controller reserves its high-FPS
+    # loop for plugins that scroll or declare needs_high_fps), so any single
+    # frame may be the only one a viewer ever sees of it.
+    # ------------------------------------------------------------------
+
+    #: Fraction of the celebration spent on the opening colour hit.
+    _CELEBRATION_IMPACT: ClassVar[float] = 0.11
+    #: Fraction of it after which the takeover eases back down.
+    _CELEBRATION_SETTLE: ClassVar[float] = 0.80
+    #: Seconds per breath of the scoring side's digits. Deliberately a
+    #: continuous sine rather than an on/off toggle: the 4 Hz flash this
+    #: replaced was sampled once a second on a switch-mode board, which
+    #: aliases into a colour that changes at random. A ramp degrades into a
+    #: slow glow instead, and still reads as a pulse at 125 FPS.
+    _CELEBRATION_BREATH_SECONDS: ClassVar[float] = 1.7
+
+    def _celebration_backdrop(
+        self,
+        celebration: Dict,
+        width: int,
+        height: int,
+        palette: Palette,
+    ) -> Image.Image:
+        """The static half of the takeover: a team-colour gradient with the
+        scenery for this kind of score painted into it.
+
+        Built once per celebration per panel size and copied per frame, so the
+        per-pixel work never lands on the render path.
+        """
+        cached: Optional[Tuple[Tuple[int, int], Image.Image]] = celebration.get("_backdrop")
+        if cached is not None and cached[0] == (width, height):
+            return cached[1]
+
+        # One column, then stretched: filling the panel pixel by pixel would
+        # be `width` times the work for the same image.
+        column = Image.new("RGB", (1, max(height, 1)))
+        pixels: Any = column.load()
+        for y in range(height):
+            k = y / max(height - 1, 1)
+            pixels[0, y] = mix_color(palette["deep"], (0, 0, 0), 0.18 + 0.82 * k)
+        backdrop = column.resize((width, height)).convert("RGBA")
+
+        try:
+            self._draw_celebration_motif(
+                ImageDraw.Draw(backdrop),
+                celebration.get("motif") or "score",
+                width,
+                height,
+                palette,
+            )
+        except Exception as e:  # noqa: BLE001 - scenery is never worth a blank panel
+            self.logger.debug(f"Celebration motif skipped: {e}")
+
+        celebration["_backdrop"] = ((width, height), backdrop)
+        return backdrop
+
+    def _draw_celebration_motif(
+        self,
+        draw,
+        motif: str,
+        width: int,
+        height: int,
+        palette: Palette,
+    ) -> None:
+        """Paint the scenery for one kind of score, dim enough to stay behind
+        the headline and the score instead of competing with them."""
+        glow = palette["glow"]
+        if motif == "kick":
+            # The uprights a field goal or an extra point went through,
+            # spread wide enough to frame the score rather than sit beside it.
+            half = max(8, min(width // 3, height))
+            mid = width // 2
+            crossbar = int(height * 0.60)
+            draw.line([(mid - half, int(height * 0.08)), (mid - half, crossbar)], fill=glow)
+            draw.line([(mid + half, int(height * 0.08)), (mid + half, crossbar)], fill=glow)
+            draw.line([(mid - half, crossbar), (mid + half, crossbar)], fill=glow)
+            draw.line([(mid, crossbar), (mid, height - 1)], fill=glow)
+        elif motif == "touchdown":
+            # The goal line, with its hash marks.
+            line_y = int(height * 0.36)
+            draw.line([(0, line_y), (width, line_y)], fill=glow)
+            for x in range(3, width, 9):
+                draw.line([(x, line_y - 2), (x, line_y + 2)], fill=glow)
+        elif motif == "net":
+            # The goal a puck just went into: frame, posts and mesh, sized to
+            # frame the score the way the uprights do.
+            half = max(7, min(width // 4, height))
+            mid = width // 2
+            top = int(height * 0.34)
+            draw.rectangle([(mid - half, top), (mid + half, height - 1)], outline=glow)
+            step = max(3, (half * 2) // 6)
+            for x in range(mid - half + step, mid + half, step):
+                draw.line([(x, top + 1), (x, height - 2)], fill=glow)
+            for y in range(top + step, height - 1, step):
+                draw.line([(mid - half + 1, y), (mid + half - 1, y)], fill=glow)
+        elif motif == "win":
+            # A sunburst behind the winner.
+            cx, cy = width // 2, height // 2
+            reach = max(width, height)
+            for i in range(10):
+                angle = (math.pi * 2 * i / 10) + math.pi / 20
+                draw.line(
+                    [
+                        (cx, cy),
+                        (cx + math.cos(angle) * reach, cy + math.sin(angle) * reach),
+                    ],
+                    fill=glow,
+                )
+        else:
+            for x in range(-height, width + height, 11):
+                draw.line([(x, height), (x + height, 0)], fill=glow)
+
+    def _celebration_confetti(
+        self,
+        celebration: Dict,
+        width: int,
+        height: int,
+        palette: Palette,
+    ) -> List[Flake]:
+        """Seed the confetti once per celebration.
+
+        Seeded from the game rather than the clock, so the same score always
+        produces the same fall -- which is what lets a golden screen lock the
+        effect down instead of having to tolerate it.
+        """
+        cached: Optional[Tuple[Tuple[int, int], List[Flake]]] = celebration.get("_confetti")
+        if cached is not None and cached[0] == (width, height):
+            return cached[1]
+
+        # Sparse on purpose. At one flake per 170 square pixels a 128x32
+        # panel carried 24 single-pixel specks over the headline and the
+        # score, which reads as a dead-pixel problem rather than as confetti.
+        count = max(6, min(22, (width * height) // 260))
+        seed = "%s/%s" % (
+            (celebration.get("game") or {}).get("id", "?"),
+            celebration.get("phrase", ""),
+        )
+        rng = random.Random(seed)  # nosec B311 - confetti, not security
+        # Team colours, plus a pale tint of the headline rather than a flat
+        # white, so the fall still belongs to the team that scored.
+        colors = [
+            palette["headline"],
+            palette["accent"],
+            mix_color(palette["headline"], (255, 255, 255), 0.55),
+        ]
+        flakes = [
+            (
+                float(rng.randrange(max(width, 1))),  # column
+                rng.uniform(0.0, float(height)),      # start height
+                rng.uniform(0.40, 1.15),              # fall speed
+                rng.uniform(0.0, math.pi * 2),        # sway phase
+                2 if rng.random() < 0.6 else 1,       # size in pixels
+                colors[rng.randrange(len(colors))],
+            )
+            for _ in range(count)
+        ]
+        celebration["_confetti"] = ((width, height), flakes)
+        return flakes
+
+    def _draw_celebration_confetti(
+        self,
+        draw,
+        celebration: Dict,
+        width: int,
+        height: int,
+        palette: Palette,
+        elapsed: float,
+        progress: float,
+    ) -> None:
+        """Draw the confetti for this instant, thinning it out as the
+        celebration eases back towards the scorebug."""
+        flakes = self._celebration_confetti(celebration, width, height, palette)
+        fade = 1.0
+        if progress > self._CELEBRATION_SETTLE:
+            fade = max(
+                0.0,
+                1.0
+                - (progress - self._CELEBRATION_SETTLE)
+                / (1.0 - self._CELEBRATION_SETTLE),
+            )
+        if fade <= 0.02:
+            return
+        alpha = int(235 * fade)
+        for column, start, speed, phase, size, color in flakes:
+            y = (start + speed * elapsed * height * 0.42) % (height + 4) - 2
+            x = column + math.sin(elapsed * 2.1 + phase) * 2.4
+            draw.rectangle(
+                [(int(x), int(y)), (int(x) + size - 1, int(y) + size - 1)],
+                fill=tuple(color) + (alpha,),
+            )
+
+    def _celebration_crests(
+        self, celebration: Dict, height: int
+    ) -> Dict[str, Optional[Image.Image]]:
+        """The two crests for the takeover, with the side that did not score
+        dimmed so the scoring team reads at a glance."""
+        cached: Optional[Tuple[int, Dict[str, Optional[Image.Image]]]] = celebration.get("_crests")
+        if cached is not None and cached[0] == height:
+            return cached[1]
+
+        game = celebration["game"]
+        scored = celebration.get("scored_side")
+        crests: Dict[str, Optional[Image.Image]] = {}
+        for side in ("away", "home"):
+            logo = None
+            try:
+                logo = self._load_and_resize_logo(
+                    game.get("%s_id" % side),
+                    game.get("%s_abbr" % side),
+                    game.get("%s_logo_path" % side),
+                    game.get("%s_logo_url" % side),
+                )
+            except Exception as e:  # noqa: BLE001 - a crest is never worth the panel
+                self.logger.debug(f"Celebration logo load failed: {e}")
+            if logo is not None and side != scored:
+                logo = dim_rgba(logo, 0.40)
+            crests[side] = logo
+
+        celebration["_crests"] = (height, crests)
+        return crests
+
+    def _draw_celebration_layout(self, celebration: Dict, force_clear: bool = False) -> None:
+        """Render the full-screen goal/win takeover."""
+        if force_clear:
+            self.display_manager.clear()
+
+        display_width = (
+            self.display_manager.matrix.width
+            if hasattr(self.display_manager, "matrix") and self.display_manager.matrix
+            else self.display_width
+        )
+        display_height = (
+            self.display_manager.matrix.height
+            if hasattr(self.display_manager, "matrix") and self.display_manager.matrix
+            else self.display_height
+        )
+
+        elapsed = max(0.0, time.time() - celebration["started_at"])
+        # getattr throughout the render path: the golden-screen tests build a
+        # live manager through __new__ and set only what they draw with, and a
+        # celebration must never be lost to a missing knob.
+        duration = max(float(getattr(self, "celebration_duration", 8) or 8), 0.5)
+        progress = min(elapsed / duration, 1.0)
+        palette = self._celebration_palette(celebration)
+
+        main_img = self._celebration_backdrop(
+            celebration, display_width, display_height, palette
+        ).copy()
+
+        # Crests at the edges, bleeding off as the scorebug's do.
+        crests = self._celebration_crests(celebration, display_height)
+        center_y = display_height // 2
+        home_logo, away_logo = crests.get("home"), crests.get("away")
+        if home_logo is not None:
+            main_img.paste(
+                home_logo,
+                (display_width - home_logo.width + 2, center_y - home_logo.height // 2),
+                home_logo,
+            )
+        if away_logo is not None:
+            main_img.paste(away_logo, (-2, center_y - away_logo.height // 2), away_logo)
+
+        # The opening hit: the team's headline colour washes the panel and
+        # decays out of it. Held below opaque so the outlined text drawn on
+        # top still reads in whichever frame happens to catch it.
+        impact = max(0.0, 1.0 - progress / self._CELEBRATION_IMPACT)
+        if impact > 0.0:
+            # Scaled by how colourful the team is. A saturated crest gets the
+            # full hit; a silver one -- the Raiders, or the grey placeholder a
+            # failed logo download leaves -- would otherwise wash the whole
+            # panel out to the same flat grey as its own headline colour.
+            punch = 0.45 + 0.55 * rgb_saturation(palette["headline"])
+            alpha = int(140 * punch * (impact ** 1.5))
+            if alpha > 0:
+                main_img = Image.alpha_composite(
+                    main_img,
+                    Image.new(
+                        "RGBA",
+                        (display_width, display_height),
+                        tuple(palette["headline"]) + (alpha,),
+                    ),
+                )
+
+        overlay = Image.new("RGBA", (display_width, display_height), (0, 0, 0, 0))
+        draw = ImageDraw.Draw(overlay)
+
+        if getattr(self, "celebration_confetti", True):
+            try:
+                self._draw_celebration_confetti(
+                    draw,
+                    celebration,
+                    display_width,
+                    display_height,
+                    palette,
+                    elapsed,
+                    progress,
+                )
+            except Exception as e:  # noqa: BLE001
+                self.logger.debug(f"Celebration confetti skipped: {e}")
+
+        # Headline across the top, shrunk to fit the panel width, struck
+        # white on the opening hit and settling into the team's colour.
+        phrase = celebration["phrase"]
+        phrase_font = self._fit_font(
+            draw, phrase, display_width, [self.fonts["time"], self.fonts["status"]]
+        )
+        phrase_width = draw.textlength(phrase, font=phrase_font)
+        # Eased in by colour rather than by position. Sliding it down into
+        # place put the first frame at y=-3 with its top row cut off, and on a
+        # 1 FPS board that clipped frame can be the only one anyone sees.
+        self._draw_text_with_outline(
+            draw,
+            phrase,
+            ((display_width - phrase_width) // 2, 1),
+            phrase_font,
+            fill=mix_color(palette["headline"], (255, 255, 255), impact),
+        )
+
+        # Score centred low, the scoring side's digits breathing in the team's
+        # headline colour so the change reads at a glance.
+        away_text = str(celebration["away_score"])
+        home_text = str(celebration["home_score"])
+        score_font = self.fonts["score"]
+        segments = [
+            (away_text, celebration["scored_side"] == "away"),
+            ("-", False),
+            (home_text, celebration["scored_side"] == "home"),
+        ]
+        total_width = sum(draw.textlength(seg, font=score_font) for seg, _ in segments)
+        breath = 0.72 + 0.28 * (
+            0.5
+            + 0.5 * math.sin(2 * math.pi * elapsed / self._CELEBRATION_BREATH_SECONDS)
+        )
+        highlight = scale_color(palette["headline"], breath)
+        x = (display_width - total_width) // 2
+        # display_height - 14 was sized for the old fixed 8px score. #338
+        # scales the score with the panel (16px at 48 and 64 tall), which put
+        # the bottom of the digits off the panel. Lift it by the measured ink
+        # (+1 for the outline stroke) only when it would clip, so panels where
+        # it always fitted render exactly as before.
+        score_text = "".join(seg for seg, _ in segments)
+        ink_bottom = draw.textbbox((0, 0), score_text, font=score_font)[3]
+        y = min(display_height - 14, display_height - ink_bottom - 2)
+        for seg, is_highlight in segments:
+            color = highlight if is_highlight else (216, 216, 216)
+            self._draw_text_with_outline(draw, seg, (int(x), y), score_font, fill=color)
+            x += draw.textlength(seg, font=score_font)
+
+        main_img = Image.alpha_composite(main_img, overlay).convert("RGB")
+        self.display_manager.image = main_img
+        self.display_manager.update_display()

src/common/sports_display_rules.py

@@ -0,0 +1,164 @@
+"""Which games a scoreboard shows, for how long, and what its scorebug dates say.
+
+Four ``sports.py`` methods are identical (executable AST, docstrings
+stripped, decorators compared) in every scoreboard that carries them, and
+were copied here from ledmatrix-plugins ``56c4f15`` (origin/main,
+2026-09-30) under their existing names. They split into two mixins because
+their carriers differ, and a plugin should not gain an override it did not
+have:
+
+``SportsCardOptionsMixin`` -- afl, baseball, basketball, football, hockey,
+lacrosse, nrl and soccer (ufc draws no team scorebug):
+
+- ``_card_option`` -- reads one ``scroll_card`` key through
+  ``SportsCoreSharedMixin._card_option``, but never lets the upcoming
+  scorebug lose both its date and its time (the combination a settings-form
+  bug saved for a whole cohort of boards);
+- ``_recent_date_text`` -- the date line of the full-screen recent scorebug.
+
+``SportsGameRulesMixin`` -- all nine:
+
+- ``_filtered_or_all`` (all but football, which has no such method) -- the
+  quality and division filters on a board with no favourites, failing open
+  to every game rather than a blank panel;
+- ``_effective_live_duration`` (all but ufc, which has none) -- how long a
+  live game stays up: ``non_favorite_live_game_duration`` for a
+  non-favourite when favourites are set, else ``game_display_duration``.
+  afl, nrl and soccer carry it on ``SportsCore``, the other five on
+  ``SportsLive``; the bodies are the same.
+
+The plugin missing a method gains one it never calls, which changes nothing:
+nothing in that plugin, nor in core, calls it.
+
+A new module rather than more methods on ``sports_shared``, for the reason
+``sports_helpers`` gives: a missing module fails at load, where the version
+checks see it; a missing method fails mid-update.
+
+WHAT A HOST MUST PROVIDE
+------------------------
+Derived by walking every ``self.<attr>`` the mixins read; the host-contract
+test in ``test/test_sports_display_rules.py`` fails if a read is added
+without being listed here.
+
+``SportsCardOptionsMixin``:
+
+- ``SportsCoreSharedMixin`` (``src.common.sports_shared``) in the MRO
+  **after** this mixin: ``_card_option`` calls that mixin's ``_card_option``
+  and ``_switch_upcoming_center`` by name, and ``_recent_date_text`` its
+  ``_format_game_date``. List this mixin first --
+  ``class SportsCore(SportsCardOptionsMixin, SportsGameRulesMixin,
+  SportsFetchMixin, SportsCoreSharedMixin, SportsHelpersMixin, ABC)`` --
+  or ``SportsCoreSharedMixin._card_option`` wins and the rescue is lost.
+  Through it: ``config`` (the ``scroll_card`` block it reads).
+
+``SportsGameRulesMixin``:
+
+- ``_passes_other_filters(game)`` -- the plugin's own quality/division
+  filter (``_filtered_or_all``).
+- ``_check_ranking_coverage(games)`` -- from ``SportsCoreSharedMixin``.
+- ``favorite_teams``, ``game_display_duration`` and
+  ``_is_favorite_game(game)``; ``non_favorite_live_game_duration`` read with
+  ``getattr`` (``_effective_live_duration``).
+
+Neither mixin has an ``__init__`` or state. A method on the plugin's own
+class still wins over either.
+"""
+
+from typing import Any, Callable, Dict, List, Optional
+
+from src.common.sports_shared import SportsCoreSharedMixin
+
+
+class SportsCardOptionsMixin:
+    """The scorebug's ``scroll_card`` reads. See module docstring."""
+
+    # The host contract, declared for type checking only.
+    _format_game_date: Callable[..., str]
+
+    def _card_option(self, key: str, default: Any = None) -> Any:
+        """Read one scroll_card key, never blanking the upcoming scorebug.
+
+        With the middle set to "date and time" and both of those lines
+        switched off, the full-screen upcoming scorebug is two logos and
+        "Next Game" with nothing to say when the game is. Nobody picks that
+        on purpose -- "vs" and "none" are the settings for a card without the
+        stack -- yet a whole cohort of boards has it: switch_show_date/_time
+        shipped while the core's settings form still drew keys missing from
+        the saved config as unchecked boxes, so the next Save wrote both as
+        false (fixed in LEDMatrix #597). That one combination therefore reads
+        as both on. Hiding either line alone, or both under "vs" or "none",
+        is still honoured.
+        """
+        # The mixin named outright, not super(): tests lift this method onto
+        # stand-in classes that are not SportsCore subclasses.
+        base = SportsCoreSharedMixin._card_option
+        keys = ("switch_show_date", "switch_show_time")
+        value = base(self, key, default)  # type: ignore[arg-type]
+        if (key in keys and not value
+                and not any(base(self, k, True) for k in keys)  # type: ignore[arg-type]
+                and SportsCoreSharedMixin._switch_upcoming_center(self) == "date_time"):  # type: ignore[arg-type]
+            return True
+        return value
+
+    def _recent_date_text(self, game: Optional[Dict]) -> str:
+        """When a finished game was played, for the full-screen scorebug.
+
+        Formatted by switch_date_format, like the upcoming scorebug, so the
+        two dates on this display agree; its "numeric" default returns the
+        extractor's "9/23" unchanged. ``switch_recent_show_date`` (default
+        true) is the off switch.
+        """
+        if not self._card_option("switch_recent_show_date", True):
+            return ""
+        return self._format_game_date(str((game or {}).get("game_date") or ""), game)
+
+
+class SportsGameRulesMixin:
+    """Which games are worth showing, and for how long. See module docstring."""
+
+    # The host contract, declared for type checking only.
+    favorite_teams: List[str]
+    game_display_duration: float
+    _passes_other_filters: Callable[[Dict], bool]
+    _check_ranking_coverage: Callable[[List[Dict]], None]
+    _is_favorite_game: Callable[[Dict], bool]
+
+    def _filtered_or_all(self, games: List[Dict]) -> List[Dict]:
+        """The games worth watching, or all of them if that leaves none.
+
+        With no favourites configured every game selected is a non-favourite
+        game, so the quality and division settings have to apply here too. They
+        governed only the top-up slice, which this branch never uses, so a
+        board with an empty favourites list had both settings silently inert --
+        it could ask for ranked games only and still get the next N kickoffs.
+
+        Fails open as a whole, not just per check. `_passes_other_filters`
+        allows a game whose data could not be resolved, but a filter working
+        exactly as asked can still match nothing on a given day, and here there
+        is no favourite left to carry the mode -- an empty list is a blank
+        panel rather than a short one.
+        """
+        kept = [g for g in games if self._passes_other_filters(g)]
+        self._check_ranking_coverage(games)
+        return kept or games
+
+    def _effective_live_duration(self, game) -> float:
+        """How long the given live game should stay on screen before rotating.
+
+        Non-favorite live games use non_favorite_live_game_duration, but only
+        when it is set (> 0) AND favorite teams are configured. With no favorites
+        (or the knob at 0) every live game uses game_display_duration - identical
+        to the prior single-duration behavior. When show_favorite_teams_only is
+        on, non-favorite games are never shown, so this naturally never fires."""
+        non_fav = getattr(self, "non_favorite_live_game_duration", 0) or 0
+        if (
+            non_fav > 0
+            and self.favorite_teams
+            and game is not None
+            and not self._is_favorite_game(game)
+        ):
+            return non_fav
+        return self.game_display_duration
+
+
+__all__ = ["SportsCardOptionsMixin", "SportsGameRulesMixin"]

src/common/sports_fetch.py

@@ -0,0 +1,274 @@
+"""Which requests a scoreboard makes: season fetches, the lookback, live odds.
+
+Four ``SportsCore`` methods are identical (executable AST, docstrings
+stripped) in all nine scoreboards' ``sports.py`` -- afl, baseball,
+basketball, football, hockey, lacrosse, nrl, soccer and ufc -- and were
+copied here from ledmatrix-plugins ``30455671`` (origin/main, 2026-09-29)
+under their existing names:
+
+- ``_background_fetches_espn_ranges`` -- whether the core's background
+  service can fetch an ESPN date range, or the plugin must;
+- ``_fetch_season_directly`` -- fetch and cache a season in chunks ESPN
+  accepts, on the calling thread;
+- ``_needs_previous_day`` (with ``_LOOKBACK_CUTOFF_HOUR``) -- whether the
+  live fetch still has to ask for yesterday;
+- ``_wants_live_odds`` (with ``_LIVE_ODDS_LOOKAHEAD``) -- whether a live
+  game is close enough to the screen to be worth an odds request.
+
+Three other ``SportsCore`` methods are as identical and stay in the plugins,
+for the reasons ``sports_shared`` gives: ``_get_timezone`` binds each
+plugin's own ``resolve_timezone`` shim, and ``_extract_game_details`` /
+``_fetch_data`` are the abstract sport-specific contract. So does
+``SportsUpcoming.__init__``: the mixins in ``src/common`` hold no
+constructor, so the plugins' constructor signature stays theirs.
+
+A new module rather than more methods on ``sports_shared``, for the reason
+``sports_helpers`` gives: a missing module fails at load, where the version
+checks see it; a missing method fails mid-update.
+
+WHAT A HOST MUST PROVIDE
+------------------------
+Derived by walking every ``self.<attr>`` the mixin reads; the host-contract
+test in ``test/test_sports_fetch.py`` fails if a read is added without being
+listed here.
+
+- ``session``, ``headers``, ``cache_manager`` and ``logger`` --
+  ``_fetch_season_directly``.
+- ``_games_lock`` -- ``_wants_live_odds``, which also reads ``live_games``,
+  ``current_game_index`` and ``_rotation_schedule`` with ``getattr``
+  (only ``SportsLive`` has them).
+- ``live_games``, read with ``getattr`` -- ``_needs_previous_day``.
+- ``background_service``, read with ``getattr`` --
+  ``_background_fetches_espn_ranges``.
+- ``sport`` and ``league`` (ESPN's path segments, e.g. ``football`` /
+  ``nfl``) -- ``_schedule_cache_key``, and ``_fetch_season_directly`` when
+  it is given no key and cannot read one from its URL.
+
+THE SCHEDULE CACHE KEY (fetch service stage 2)
+----------------------------------------------
+``_schedule_cache_key`` names a schedule window with the canonical
+``espn_scoreboard_cache_key`` instead of a plugin-built
+``{sport_key}_schedule_{window}``, and ``_cached_schedule`` reads it with the
+old key as a fallback for one release, so an upgrade serves the copy already
+on disk instead of refetching every league at once. The canonical key
+carries the window's dates, so it moves on a day as the window slides; a
+miss on it also deletes the copy for the day before, so a league keeps one
+window file instead of a week of them.
+
+Add it as a base of the plugin's ``SportsCore``, e.g.
+``class SportsCore(SportsFetchMixin, SportsCoreSharedMixin,
+SportsHelpersMixin, ABC)``. It defines nothing those define; a method or
+constant on the plugin's own class still wins over the mixin's.
+"""
+
+import logging
+import threading
+from datetime import datetime, timedelta
+from typing import Any, ClassVar, Dict, Iterable, Optional
+
+from src.common.espn_dates import (
+    ESPN_MAX_LIMIT,
+    espn_scoreboard_cache_key,
+    espn_scoreboard_cache_key_for_url,
+    fetch_espn_scoreboard,
+    parse_espn_date_range,
+)
+from src.common.fetch_service import get_fetch_service
+
+_ESPN_SITE = "https://site.api.espn.com/"
+
+
+def _previous_window_key(cache_key: str) -> Optional[str]:
+    """The canonical key of the same window one day earlier, or None when
+    ``cache_key`` is not a canonical day-range key."""
+    head, sep, dates = cache_key.rpartition("_")
+    if not sep or not head.startswith("espn_scoreboard_"):
+        return None
+    span = parse_espn_date_range(dates)
+    if span is None:
+        return None
+    start, end = (day - timedelta(days=1) for day in span)
+    return f"{head}_{start.strftime('%Y%m%d')}-{end.strftime('%Y%m%d')}"
+
+
+class SportsFetchMixin:
+    """Season fetch, lookback and live-odds decisions. See module docstring."""
+
+    # The host contract, declared for type checking only: these create no
+    # attributes, so the host's own values are what the methods read.
+    session: Any
+    headers: Dict[str, str]
+    cache_manager: Any
+    logger: logging.Logger
+    _games_lock: threading.RLock
+    sport: str
+    league: str
+
+    #: How many games past the one on screen keep their odds warm. One is
+    #: enough for the line to be ready when the rotation advances; more just
+    #: re-creates the whole-slate fetch this replaced.
+    _LIVE_ODDS_LOOKAHEAD: ClassVar[int] = 1
+
+    def _wants_live_odds(self, game: Dict) -> bool:
+        """Whether a live game is near enough the front of the rotation to be
+        worth an odds request.
+
+        Odds used to be fetched for *every* live game in the league on every
+        update. The renderer only ever draws ``current_game``, and a full
+        rotation of a big slate takes minutes while ``live_odds_update_interval``
+        is 60s -- so all but one of those requests expired before the game they
+        belonged to came round.
+
+        Measured 2026-09-19 over a full college-football slate: 11,978 odds
+        requests in 13h on one rig, 54% of all its ESPN traffic, across only
+        ~140 distinct games. The eager loop also cost up to 2s of ``update()``
+        per live game, because ``_fetch_odds`` waits on its worker thread.
+
+        Mirrors the narrowing already applied to the upcoming path and to
+        ``_attach_odds_to_rotated_games``: only games about to be on screen are
+        asked about. ``get_odds`` still caches per game, so a game re-entering
+        the window inside its TTL costs a cache lookup, not a request.
+
+        The rotation state read here is the previous cycle's -- the new list is
+        still being built -- which is exactly the question being asked: is this
+        game at or near the position currently on the panel?
+        """
+        # Read defensively: this predicate lives on SportsCore so it sits
+        # beside _fetch_odds, but live_games/_rotation_schedule belong to
+        # SportsLive, which is the only caller.
+        with self._games_lock:
+            games = list(getattr(self, "live_games", ()) or ())
+            index = getattr(self, "current_game_index", 0)
+            schedule = list(getattr(self, "_rotation_schedule", ()) or ())
+        if not games:
+            # Cold start: nothing is on screen yet, so let the games seen on
+            # this first pass through rather than render a blank line for a
+            # whole cycle. Bounded -- the next pass has a rotation to narrow by.
+            return True
+        order = schedule or [g.get("id") for g in games]
+        if not order:
+            return True
+        start = index if 0 <= index < len(order) else 0
+        wanted = {
+            order[(start + offset) % len(order)]
+            for offset in range(self._LIVE_ODDS_LOOKAHEAD + 1)
+        }
+        return game.get("id") in wanted
+
+    #: Hour of the Eastern day past which last night's games are assumed over.
+    #:
+    #: The live fetch asks ESPN for a two-day window so a game that started
+    #: yesterday and is still running is not lost. ESPN rejects date *ranges*,
+    #: so that window is split into one request per day -- doubling every live
+    #: poll. Measured 2026-09-19: 1,858 requests per rig spent on yesterday's
+    #: date, which after breakfast holds nothing but final games.
+    #:
+    #: No sport on these boards runs six hours past midnight, and one that
+    #: somehow did is still covered: a game already being tracked keeps its own
+    #: day in the window regardless of the hour.
+    _LOOKBACK_CUTOFF_HOUR: ClassVar[int] = 6
+
+    def _needs_previous_day(self, now: datetime) -> bool:
+        """Whether the previous Eastern day can still hold a live game."""
+        if now.hour < self._LOOKBACK_CUTOFF_HOUR:
+            return True
+        previous = (now - timedelta(days=1)).strftime("%Y%m%d")
+        for game in (getattr(self, "live_games", None) or []):
+            start: Any = game.get("start_time_utc") if hasattr(game, "get") else None
+            try:
+                if start.astimezone(now.tzinfo).strftime("%Y%m%d") == previous:
+                    return True
+            except (AttributeError, ValueError, OSError, OverflowError):
+                continue
+        return False
+
+    def _background_fetches_espn_ranges(self) -> bool:
+        """Can the core's background service fetch an ESPN date range?
+
+        Cores from before the 2026-09-15 fix send a season range to ESPN as-is,
+        which now answers 400 for every sport. On those cores the managers fetch
+        the season themselves with _fetch_season_directly instead.
+        """
+        service = getattr(self, "background_service", None)
+        return bool(getattr(service, "handles_espn_date_ranges", False))
+
+    def _schedule_cache_key(self, datestring: str) -> str:
+        """The canonical cache key for this league's schedule over
+        ``datestring`` (``espn_scoreboard_cache_key``)."""
+        return espn_scoreboard_cache_key(self.sport, self.league, datestring)
+
+    def _cached_schedule(self, cache_key: str, legacy_keys: Iterable[str] = ()) -> Any:
+        """What ``self.cache_manager.get(cache_key)`` returns, falling back
+        to each of ``legacy_keys`` (the plugin's pre-canonical keys) in turn.
+
+        The same read the managers made before -- same default max age, a
+        stored ttl still wins -- so moving to the canonical key changes
+        where a schedule is cached, not for how long. A read from an old key
+        is counted (``legacy_cache_hits``) so it is visible when the
+        fallback can go. A miss on the canonical key also deletes the same
+        window's copy from the day before (see the module docstring).
+        """
+        cached = self.cache_manager.get(cache_key)
+        if cached:
+            return cached
+        self._retire_previous_window(cache_key)
+        for legacy in legacy_keys:
+            if not legacy or legacy == cache_key:
+                continue
+            cached = self.cache_manager.get(legacy)
+            if cached:
+                try:
+                    get_fetch_service().note_cache_hit(
+                        _ESPN_SITE, legacy=True, avoided_request=False)
+                except Exception:  # noqa: BLE001 - counting never breaks a read
+                    pass
+                return cached
+        return None
+
+    def _retire_previous_window(self, cache_key: str) -> None:
+        previous = _previous_window_key(cache_key)
+        delete = getattr(self.cache_manager, "delete", None)
+        if previous is None or not callable(delete):
+            return
+        try:
+            delete(previous)
+        except Exception as e:  # noqa: BLE001 - housekeeping only
+            self.logger.debug(f"Could not delete old schedule copy {previous}: {e}")
+
+    def _fetch_season_directly(
+        self,
+        url: str,
+        datestring: str,
+        cache_key: Optional[str],
+        label: str,
+        ttl: Optional[int] = None,
+    ) -> Optional[Dict]:
+        """Fetch a season schedule on this thread, in chunks ESPN accepts, and cache it.
+
+        ``label`` names the schedule in log lines, e.g. ``"2026 season"``.
+        ``cache_key=None`` caches it under the canonical key
+        (``espn_scoreboard_cache_key`` for ``url``'s sport and league).
+        """
+        if cache_key is None:
+            cache_key = (espn_scoreboard_cache_key_for_url(url, datestring)
+                         or self._schedule_cache_key(datestring))
+        try:
+            data = fetch_espn_scoreboard(
+                self.session,
+                url,
+                params={"dates": datestring, "limit": ESPN_MAX_LIMIT},
+                headers=self.headers,
+                timeout=30,
+                logger=self.logger,
+            )
+        except Exception as e:
+            self.logger.error(f"Failed to fetch {label} schedule: {e}")
+            return None
+        if ttl is None:
+            self.cache_manager.set(cache_key, data)
+        else:
+            self.cache_manager.set(cache_key, data, ttl=ttl)
+        self.logger.info(
+            f"Fetched {label} schedule: {len(data.get('events', []))} events"
+        )
+        return data

src/common/sports_font_path.py

@@ -0,0 +1,41 @@
+"""Where a scoreboard's bundled font file is, whatever the working directory.
+
+Every scoreboard's ``sports.py`` (nine) and ``game_renderer.py`` (eight)
+carries the same module-level ``_resolve_font_path``. It predates
+:func:`src.common.font_layout.resolve_asset_path`, and probes the core for
+it: the path as given when it exists (relative to the cwd), else the core's
+resolver (``FontManager._resolve_asset_path``, which delegates to
+``resolve_asset_path``), else the path joined to the install root, else the
+path unchanged so the caller's ``ImageFont.truetype`` raises and falls back
+as before.
+
+On every core this module ships in, the probe always finds the resolver, and
+the install-root join repeats what the resolver already tried. What is left
+is two steps, and :func:`resolve_font_path` is exactly those: the cwd first,
+then ``resolve_asset_path``. ``test/test_sports_font_path.py`` checks that
+against the plugins' own copies, path for path. It is the same rule as
+``sports_shared._resolve_font_path``, made public so a plugin can import it.
+
+Why not ``resolve_asset_path`` alone: it never consults the cwd, so a
+process started from another checkout would switch to the install root's
+fonts. Keeping the cwd first keeps that behaviour exactly.
+"""
+
+import os
+
+from src.common.font_layout import resolve_asset_path
+
+
+def resolve_font_path(path: str) -> str:
+    """``path`` if it exists, else :func:`resolve_asset_path` of it.
+
+    Absolute paths that exist come back untouched; a relative path is tried
+    against the cwd, then the install root; a path found nowhere comes back
+    unchanged, so the caller still raises and falls back.
+    """
+    if os.path.exists(path):
+        return path
+    return resolve_asset_path(path)
+
+
+__all__ = ["resolve_font_path"]

src/common/sports_live_scroll.py

@@ -0,0 +1,277 @@
+"""Keep a live scoreboard's scrolling strip current without restarting it.
+
+In scroll mode a scoreboard renders its games into one wide image and
+scrolls it past the panel. The strip used to be rebuilt only when a cycle
+completed, so a score changed mid-cycle stayed frozen in the pixels until the
+marquee finished. Eight scoreboards -- afl, baseball, basketball, football,
+hockey, lacrosse, nrl and soccer (ufc has no live strip) -- carry the same
+fix in their ``manager.py``: fingerprint the live games, rebuild when the
+fingerprint changes (rate-limited, and never for the clock alone), and keep
+the marquee's position across the rebuild. Its eight methods and two class
+constants are identical (executable AST, docstrings stripped, decorators
+compared) in all eight and were copied here from ledmatrix-plugins
+``56c4f15`` (origin/main, 2026-09-30) under their existing names:
+
+- ``_live_scroll_managers`` -- the live managers whose games are on the strip;
+- ``_refresh_live_scroll_managers`` -- let them refresh before they are
+  fingerprinted, off the render thread;
+- ``_live_scroll_fields``, ``_fingerprint_games`` and
+  ``_live_scroll_fingerprint`` -- what the strip was drawn from;
+- ``_live_scroll_needs_rebuild`` (with ``LIVE_SCROLL_REBUILD_MIN_SECONDS``
+  and ``LIVE_SCROLL_REBUILD_DUTY_DIVISOR``) and ``_note_live_scroll_built``
+  -- when to rebuild;
+- ``_preserving_scroll_position`` -- a context manager that keeps the marquee
+  where it was across a rebuild.
+
+``LIVE_VOLATILE_FIELDS`` stays in each plugin: afl, nrl and soccer also
+exclude ``period_text``, which embeds the clock in those sports.
+
+A separate module from ``sports_plugin_host`` because ufc has no live strip:
+it inherits that mixin and not this one, so none of this is in its MRO.
+
+WHAT A HOST MUST PROVIDE
+------------------------
+Derived by walking every ``self.<attr>`` / ``cls.<attr>`` the mixin reads;
+the host-contract test in ``test/test_sports_live_scroll.py`` fails if a read
+is added without being listed here.
+
+- ``LIVE_VOLATILE_FIELDS`` -- a class constant: the game-dict keys a rebuild
+  ignores (the clock, and what the display pipeline adds).
+- ``_live_scroll_fingerprints``, ``_live_scroll_rebuilt_at`` and
+  ``_live_scroll_rebuild_cost`` -- empty dicts the host creates in
+  ``__init__``, keyed by scroll key.
+- ``logger``.
+- ``_dispatch_switch_refresh(manager)`` -- from ``SportsPluginHostMixin``.
+- ``_league_registry`` (``{league: {"enabled": bool, "managers": {"live":
+  manager}}}``) or a ``_get_manager(mode_type)`` accessor, both read with
+  ``getattr`` -- ``_live_scroll_managers``. A host with neither gets no
+  managers, which leaves the feature inert rather than wrong.
+- ``_scroll_manager``, read with ``getattr`` --
+  ``_preserving_scroll_position`` asks it for the mode's scroll helper.
+
+Add it as a base of the plugin class beside ``SportsPluginHostMixin``, before
+``BasePlugin``: ``class SoccerScoreboardPlugin(SportsPluginHostMixin,
+SportsLiveScrollMixin, BasePlugin)``. The two define no name in common. No
+``__init__``; a method on the plugin's own class still wins over the mixin's.
+"""
+
+import logging
+import time
+from contextlib import contextmanager
+from typing import Any, Callable, ClassVar, Dict, FrozenSet, Iterator, List
+
+
+class SportsLiveScrollMixin:
+    """Mid-cycle rebuilds of a live scroll strip. See module docstring."""
+
+    # The host contract, declared for type checking only: these create no
+    # attributes, so the host's own values are what the methods read.
+    logger: logging.Logger
+    LIVE_VOLATILE_FIELDS: ClassVar[FrozenSet[str]]
+    _live_scroll_fingerprints: Dict[Any, Any]
+    _live_scroll_rebuilt_at: Dict[Any, float]
+    _live_scroll_rebuild_cost: Dict[Any, float]
+    _dispatch_switch_refresh: Callable[[Any], None]
+
+    #: Floor between mid-cycle strip rebuilds, and the duty-cycle cap that can
+    #: raise it.
+    #:
+    #: A rebuild re-renders every card into one wide image, on the render
+    #: thread, so the marquee is frozen for however long it takes. Measured on a
+    #: Pi 4: 28ms for one game, 139ms for five, 435ms for fifteen. A fixed 5s
+    #: floor is fine for one game and wrong for a full slate -- with fifteen
+    #: live games a pitch lands somewhere every second or so, the fingerprint
+    #: changes continuously, and 435ms every 5s is nearly a tenth of the time
+    #: spent not scrolling.
+    #:
+    #: So the floor also scales with what the last rebuild actually cost: never
+    #: spend more than 1/LIVE_SCROLL_REBUILD_DUTY_DIVISOR of wall time
+    #: rebuilding. Fifteen games self-limits to a rebuild every ~8.7s; one game
+    #: stays on the 5s floor. No per-sport tuning, and it adapts to slate size
+    #: and panel width on its own.
+    LIVE_SCROLL_REBUILD_MIN_SECONDS: ClassVar[float] = 5.0
+    LIVE_SCROLL_REBUILD_DUTY_DIVISOR: ClassVar[float] = 20.0
+
+    def _live_scroll_managers(self, league=None):
+        """The live managers whose games are on the strip.
+
+        Two shapes across the scoreboard lineage: a _league_registry (baseball,
+        basketball, hockey, lacrosse, soccer, football) and a _get_manager
+        accessor on the single-league plugins (afl, nrl). Anything else returns
+        nothing, which leaves this feature inert rather than wrong.
+        """
+        registry = getattr(self, "_league_registry", None)
+        if isinstance(registry, dict) and registry:
+            managers = []
+            for league_id, entry in registry.items():
+                if league is not None and league_id != league:
+                    continue
+                entry = entry or {}
+                if not entry.get("enabled", False):
+                    continue
+                manager = (entry.get("managers") or {}).get("live")
+                if manager is not None:
+                    managers.append(manager)
+            return managers
+        getter = getattr(self, "_get_manager", None)
+        if callable(getter):
+            try:
+                # pylint: disable=not-callable
+                # The lineages that lack _get_manager infer this as None, so a
+                # static checker calls it uncallable. callable() above is the
+                # runtime guard; the branch is simply dead in those plugins.
+                manager = getter("live")
+            except (AttributeError, KeyError, TypeError, ValueError, OSError):
+                return []
+            return [manager] if manager is not None else []
+        return []
+
+    def _refresh_live_scroll_managers(self, league=None) -> None:
+        """Let the live managers refresh before their games are fingerprinted.
+
+        Switch mode stays current because _try_manager_display() calls
+        _ensure_manager_updated() on every pass. Scroll mode had no equivalent:
+        its only refresh sat inside the block gated by the rebuild decision, and
+        that decision is computed from the data the refresh would replace. So
+        once the first strip was built nothing could change it, and the score on
+        the marquee stayed frozen until the process restarted.
+
+        The refresh runs off the render thread -- see _dispatch_switch_refresh().
+        This is called on every scroll frame, and a due manager.update() is a
+        network round trip: run inline, it froze the marquee for the length of
+        the ESPN request. The refreshed games land a few frames later, and the
+        fingerprint check that follows this call picks them up on the next frame
+        after they do. Dispatches for a manager are rate-limited, so the frames
+        where nothing is due cost a dict lookup and a clock read.
+
+        Deliberately NOT gated on mode_type == "live". A recent/upcoming strip
+        never rebuilds from the fingerprint (_live_scroll_needs_rebuild returns
+        early for those), so refreshing here looks like wasted work -- but with
+        live_priority the plugin only switches TO live mode once it knows live
+        games exist, and it learns that from these same managers. Refreshing
+        only while live mode is on screen would rebuild the same circularity one
+        level up, and a game that went live would wait for the background
+        plugin update -- an hour, on a rig that sets update_interval: 3600.
+        """
+        for manager in self._live_scroll_managers(league) or []:
+            try:
+                self._dispatch_switch_refresh(manager)
+            except (AttributeError, KeyError, TypeError, ValueError, OSError,
+                    RuntimeError) as exc:
+                # Narrow on purpose: the update itself runs on another thread,
+                # and _ensure_manager_updated() swallows whatever it raises, so
+                # anything arriving here is a lookup error or a thread that
+                # could not be started, not a fetch failure.
+                self.logger.debug("Live scroll refresh skipped: %s", exc)
+
+    @classmethod
+    def _live_scroll_fields(cls, game) -> tuple:
+        """One game as sorted ``(key, value)`` strings, minus the volatile keys."""
+        try:
+            items = list(game.items())
+        except AttributeError:
+            return (("<not-a-dict>", str(game)),)
+        return tuple(sorted((str(k), str(v)) for k, v in items
+                            if k not in cls.LIVE_VOLATILE_FIELDS))
+
+    @classmethod
+    def _fingerprint_games(cls, games) -> tuple:
+        """Order-independent fingerprint of a list of games."""
+        return tuple(sorted(cls._live_scroll_fields(g) for g in (games or [])))
+
+    def _live_scroll_fingerprint(self, league=None) -> tuple:
+        """Fingerprint of every live game the strip's managers hold now."""
+        games: List[Any] = []
+        for manager in self._live_scroll_managers(league):
+            games.extend(getattr(manager, "live_games", None) or [])
+        return self._fingerprint_games(games)
+
+    def _live_scroll_needs_rebuild(self, scroll_key, mode_type, league=None) -> bool:
+        """True when the live card would draw differently than the strip does.
+
+        _scroll_prepared is cleared only when the cycle *completes*, so a score
+        scored mid-cycle stayed frozen in the rendered strip until the marquee
+        finished -- minutes, for a long game list. Restarting the display forces
+        a rebuild, which is the workaround users find.
+        """
+        if mode_type != "live":
+            return False
+        known = self._live_scroll_fingerprints.get(scroll_key)
+        if known is None:
+            return False                      # nothing built yet; normal path
+        if self._live_scroll_fingerprint(league) == known:
+            return False
+        last = self._live_scroll_rebuilt_at.get(scroll_key, 0.0)
+        cost = self._live_scroll_rebuild_cost.get(scroll_key, 0.0)
+        floor = max(self.LIVE_SCROLL_REBUILD_MIN_SECONDS,
+                    cost * self.LIVE_SCROLL_REBUILD_DUTY_DIVISOR)
+        if time.time() - last < floor:
+            return False                      # deferred, not dropped
+        return True
+
+    def _note_live_scroll_built(self, scroll_key, mode_type, fingerprint=None,
+                                league=None) -> None:
+        """Record what the strip was built from.
+
+        Takes a fingerprint captured from the *managers* immediately before the
+        render, not one computed from the games handed to the renderer. Those
+        two are not comparable: _collect_games_for_scroll() decorates each game
+        with extra keys ("league", "status"), so a fingerprint taken from its
+        output can never equal one taken from the managers -- every check past
+        the rate limiter would rebuild, defeating the clock exclusion entirely.
+        That is not hypothetical; it is what the first version of this did, and
+        an end-to-end simulation caught it rebuilding on a bare clock tick.
+
+        Capturing before the render also closes the race a plain re-read would
+        open: a background update landing mid-render would otherwise be recorded
+        as though the strip already contained it.
+        """
+        if mode_type != "live":
+            return
+        self._live_scroll_fingerprints[scroll_key] = (
+            fingerprint if fingerprint is not None
+            else self._live_scroll_fingerprint(league))
+        self._live_scroll_rebuilt_at[scroll_key] = time.time()
+
+    @contextmanager
+    def _preserving_scroll_position(self, mode_type, active, scroll_key=None) -> Iterator[None]:
+        """Keep the marquee where it is across a mid-cycle rebuild.
+
+        ScrollHelper.set_scrolling_image() resets two counters and both matter:
+        scroll_position (without it the marquee snaps back to the start, which
+        looks worse than the stale score being fixed) and total_distance_scrolled
+        (without it the cycle restarts, so a game that keeps scoring could stop
+        the strip ever completing). Restored clamped to the new strip, since a
+        score gaining a digit changes its card's width by a few pixels.
+
+        A no-op unless `active` -- a first build should start at zero.
+        """
+        helper = None
+        if active and getattr(self, "_scroll_manager", None):
+            try:
+                helper = self._scroll_manager.get_scroll_display(mode_type).scroll_helper  # type: ignore[attr-defined]
+            except Exception:  # pragma: no cover - defensive
+                helper = None
+        position = getattr(helper, "scroll_position", None) if helper else None
+        distance = getattr(helper, "total_distance_scrolled", None) if helper else None
+        started = time.time()
+        try:
+            yield
+        finally:
+            # What this render cost, so the next floor can scale with it. Keyed by
+            # scroll_key, which is what _live_scroll_needs_rebuild() reads --
+            # they are only the same string in some of these plugins, and keying
+            # by mode_type made the duty cap silently inert in the rest.
+            self._live_scroll_rebuild_cost[scroll_key or mode_type] = time.time() - started
+            if helper is not None and position is not None:
+                width = max(getattr(helper, "total_scroll_width", 0) - 1, 0)
+                helper.scroll_position = min(position, width)
+                if distance is not None:
+                    helper.total_distance_scrolled = distance
+                helper.scroll_complete = False
+                self.logger.info(
+                    "[Scroll] Live card changed; rebuilt the %s strip in place "
+                    "at position %d", mode_type, int(helper.scroll_position))
+
+
+__all__ = ["SportsLiveScrollMixin"]

src/common/sports_plugin_host.py

@@ -0,0 +1,270 @@
+"""The scoreboard plugin class's helpers every ``manager.py`` copies.
+
+Each scoreboard's ``manager.py`` holds its ``BasePlugin`` subclass (the
+"host": ``SoccerScoreboardPlugin``, ``UFCScoreboardPlugin``, ...). Ten of its
+methods, and the class constant one of them reads, are identical
+(executable AST, docstrings stripped, decorators compared) in all nine
+scoreboards -- afl, baseball, basketball, football, hockey, lacrosse, nrl,
+soccer and ufc -- and were copied here from ledmatrix-plugins ``56c4f15``
+(origin/main, 2026-09-30) under their existing names:
+
+- ``_dispatch_switch_refresh`` (with ``_SWITCH_REFRESH_MIN_GAP_SECONDS``) --
+  run a manager's refresh on a daemon thread so ``display()`` never blocks
+  on the network;
+- ``get_vegas_priority_weight``, ``_favorite_team_is_live``,
+  ``_favorite_scan_targets``, ``_favorite_scan_games`` and
+  ``_game_involves`` -- how many Vegas slots the plugin asks for, and
+  whether a configured favourite is playing live;
+- ``get_vegas_content_type`` -- ``'multi'``: a scoreboard is a list of games;
+- ``_dynamic_feature_enabled``, ``_get_total_games_for_manager`` and
+  ``_build_manager_key`` -- small dynamic-duration helpers.
+
+This is stage 4 of the consolidation (docs/SPORTS_UNIFICATION.md): the
+families that needed no reconciling. The rest of ``manager.py`` has drifted
+and is reconciled one family per release before it moves.
+
+A new module rather than more methods on an existing mixin, for the reason
+``sports_helpers`` gives: a missing module fails at load, where the version
+checks see it; a missing method fails mid-frame.
+
+WHAT A HOST MUST PROVIDE
+------------------------
+Derived by walking every ``self.<attr>`` the mixin reads; the host-contract
+test in ``test/test_sports_plugin_host.py`` fails if a read is added without
+being listed here.
+
+- ``_ensure_manager_updated(manager)`` -- ``_dispatch_switch_refresh`` runs
+  it on the thread it starts. It must swallow its own errors: nothing joins
+  the thread.
+- ``global_config``, ``has_live_priority()``, ``has_live_content()`` and
+  ``supports_dynamic_duration()`` -- all on ``BasePlugin``; the scoreboards
+  override the last three.
+- ``is_enabled`` -- set by each scoreboard's ``__init__`` (``BasePlugin``
+  calls its flag ``enabled``).
+- ``_switch_refresh_threads`` and ``_switch_refresh_at``, read with
+  ``getattr`` -- ``_dispatch_switch_refresh`` creates both on first use, so
+  a host need not.
+- The live managers it scans for favourites are found through ``vars(self)``
+  (``_favorite_scan_targets``): any attribute, or value of a dict
+  attribute, with ``favorite_teams`` (or ``favorite_fighters``) and
+  ``live_games`` (or ``live_matches``, or an ``active_celebration`` dict
+  holding a ``game``).
+
+Add it as a base of the plugin class, **before** ``BasePlugin``, e.g.
+``class SoccerScoreboardPlugin(SportsPluginHostMixin, BasePlugin)``:
+``get_vegas_priority_weight`` and ``get_vegas_content_type`` override
+``BasePlugin``'s defaults. A method on the plugin's own class still wins over
+the mixin's. The mixin has no ``__init__`` and creates no class attributes
+beyond its one constant.
+"""
+
+import logging
+import threading
+import time
+from typing import Any, Callable, ClassVar, Dict, Iterator, Optional
+
+
+class SportsPluginHostMixin:
+    """The scoreboard plugin class's identical helpers. See module docstring."""
+
+    # The host contract, declared for type checking only: these create no
+    # attributes, so the host's own values are what the methods read.
+    logger: logging.Logger
+    is_enabled: bool
+    global_config: Dict[str, Any]
+    _ensure_manager_updated: Callable[[Any], Any]
+    has_live_priority: Callable[[], bool]
+    has_live_content: Callable[[], bool]
+    supports_dynamic_duration: Callable[[], bool]
+    # Created on first use by _dispatch_switch_refresh, per instance.
+    _switch_refresh_threads: Dict[int, threading.Thread]
+    _switch_refresh_at: Dict[int, float]
+
+    #: Floor between two draw-time refresh dispatches for one manager. The
+    #: manager's own update() still decides whether anything is fetched; this
+    #: only stops display() starting a thread on every frame just to be told
+    #: the interval has not elapsed.
+    _SWITCH_REFRESH_MIN_GAP_SECONDS: ClassVar[float] = 5.0
+
+    def _dispatch_switch_refresh(self, manager) -> None:
+        """Run _ensure_manager_updated(manager) on a daemon thread.
+
+        Called from display(), so it must not block: when an update is due,
+        manager.update() fetches rankings and the schedule over the network,
+        and doing that inline stalled the frame for the length of the round
+        trip. The refreshed games land in the manager a few frames later --
+        still within the manager's own interval, which is the freshness the
+        switch path was missing.
+
+        At most one refresh per manager runs at a time, and dispatches for the
+        same manager are at least _SWITCH_REFRESH_MIN_GAP_SECONDS apart. Only
+        the render thread touches the two bookkeeping dicts, so they need no
+        lock; manager.update() stamps last_update before it fetches, so a
+        concurrent background plugin.update() for the same manager returns
+        early rather than fetching twice.
+        """
+        threads: Optional[Dict[int, threading.Thread]] = getattr(self, "_switch_refresh_threads", None)
+        if threads is None:
+            threads = self._switch_refresh_threads = {}
+        stamps: Optional[Dict[int, float]] = getattr(self, "_switch_refresh_at", None)
+        if stamps is None:
+            stamps = self._switch_refresh_at = {}
+
+        key = id(manager)
+        running = threads.get(key)
+        if running is not None and running.is_alive():
+            return
+        now = time.monotonic()
+        last = stamps.get(key)
+        if last is not None and now - last < self._SWITCH_REFRESH_MIN_GAP_SECONDS:
+            return
+        stamps[key] = now
+        thread = threading.Thread(
+            target=self._ensure_manager_updated,
+            args=(manager,),
+            daemon=True,
+            name="SwitchRefresh-%s" % type(manager).__name__,
+        )
+        threads[key] = thread
+        thread.start()
+
+    # ---- Vegas weighting: is a favourite playing? -----------------------
+    #
+    # With display.vegas_scroll.live_in_ticker set, the marquee keeps running
+    # through a live game and plugins can claim more than one slot per cycle.
+    # The core already gives any plugin with live content `live_weight`; this
+    # exists for the one thing the core cannot work out for itself, which is
+    # *whose* game is live. See PLUGIN_API_REFERENCE, "Vegas scroll hooks",
+    # and ADVANCED_FEATURES, "Live content in the ticker".
+
+    def get_vegas_priority_weight(self):
+        """Slots per Vegas cycle: more when a favorite team is playing.
+
+        Returns None when nothing is live, which leaves the decision to the
+        core rather than asserting a weight of 1 -- the core may have its own
+        reason to boost this plugin later.
+        """
+        try:
+            if not (self.has_live_priority() and self.has_live_content()):
+                return None
+            vegas = (self.global_config or {}).get('display', {}).get(
+                'vegas_scroll', {})
+            if self._favorite_team_is_live():
+                return vegas.get('favorite_live_weight', 5)
+            return vegas.get('live_weight', 3)
+        except Exception:
+            # Never let a weighting question break the rotation; the core
+            # treats an exception as weight 1 anyway, and None says the same
+            # thing more cheaply.
+            return None
+
+    def _favorite_team_is_live(self):
+        """Whether any live game or fight involves a configured favorite.
+
+        The sports plugins do not share one data shape, so this enumerates the
+        real ones rather than assuming. An earlier version looked only for an
+        attribute holding `live_games` alongside `favorite_teams`, which was
+        true of five plugins and quietly false for four others -- they simply
+        never reported a favorite, and no test noticed because the tests used
+        the assumed shape rather than each plugin's own.
+
+        Handled:
+
+        * managers held directly on the plugin *and* inside a dict such as
+          ``self._managers`` (nrl, afl)
+        * ``live_games`` (most) and ``live_matches`` (cricket)
+        * ``favorite_teams`` (most) and ``favorite_fighters`` (ufc)
+        * identifiers ``home_abbr``/``away_abbr``, ``home_id``/``away_id``,
+          ``fighter1_name``/``fighter2_name``, and cricket's nested
+          ``teams: [{name, abbr, short_name}]``
+        * ``active_celebration["game"]``, a snapshot the live manager keeps
+          precisely because the game leaves ``live_games`` while the
+          celebration is still on screen
+        """
+        for holder in self._favorite_scan_targets():
+            favorites = (getattr(holder, 'favorite_teams', None)
+                         or getattr(holder, 'favorite_fighters', None))
+            if not favorites:
+                continue
+            wanted = {str(f).strip().lower() for f in favorites if f}
+            if not wanted:
+                continue
+            for game in self._favorite_scan_games(holder):
+                if self._game_involves(game, wanted):
+                    return True
+        return False
+
+    def _favorite_scan_targets(self) -> Iterator[Any]:
+        """Objects that might carry live content: attributes, and dict values.
+
+        nrl and afl keep their per-league managers in a ``self._managers``
+        dict, so walking attribute values alone finds the dict and stops.
+        """
+        for value in list(vars(self).values()):
+            yield value
+            if isinstance(value, dict):
+                for nested in list(value.values()):
+                    yield nested
+
+    @staticmethod
+    def _favorite_scan_games(holder) -> Iterator[Dict[str, Any]]:
+        """Every game/fight on a holder that a favorite could be playing in."""
+        for attr in ('live_games', 'live_matches'):
+            for game in (getattr(holder, attr, None) or []):
+                if isinstance(game, dict):
+                    yield game
+        celebration = getattr(holder, 'active_celebration', None)
+        if isinstance(celebration, dict) and isinstance(celebration.get('game'), dict):
+            yield celebration['game']
+
+    @staticmethod
+    def _game_involves(game, wanted) -> bool:
+        """Whether a game/fight involves one of the wanted names."""
+        for field in ('home_abbr', 'away_abbr', 'home_id', 'away_id',
+                      'fighter1_name', 'fighter2_name'):
+            value = game.get(field)
+            if value is not None and str(value).strip().lower() in wanted:
+                return True
+        # Cricket nests its sides and matches on any of three names, by
+        # substring -- "india" should match "India Women". Mirrors that
+        # plugin's own _match_has_team rather than inventing a second rule.
+        for team in (game.get('teams') or []):
+            if not isinstance(team, dict):
+                continue
+            hay = " ".join(str(team.get(k) or '') for k in
+                           ('name', 'abbr', 'short_name')).lower()
+            if any(name in hay for name in wanted):
+                return True
+        return False
+
+    def get_vegas_content_type(self) -> str:
+        """Plugin provides multiple scrollable items (games)."""
+        return 'multi'
+
+    # ---- dynamic duration ------------------------------------------------
+
+    def _dynamic_feature_enabled(self) -> bool:
+        """Dynamic duration applies: the plugin is enabled and supports it."""
+        if not self.is_enabled:
+            return False
+        return self.supports_dynamic_duration()
+
+    @staticmethod
+    def _get_total_games_for_manager(manager) -> int:
+        """How many games a manager holds, from the first list it carries."""
+        if manager is None:
+            return 0
+        for attr in ("live_games", "games_list", "recent_games", "upcoming_games"):
+            value = getattr(manager, attr, None)
+            if isinstance(value, list):
+                return len(value)
+        return 0
+
+    @staticmethod
+    def _build_manager_key(mode_name: str, manager) -> str:
+        """``"<mode>:<manager class>"``, the key progress is tracked under."""
+        manager_name = manager.__class__.__name__ if manager else "None"
+        return f"{mode_name}:{manager_name}"
+
+
+__all__ = ["SportsPluginHostMixin"]

src/common/sports_scroll.py

@@ -42,17 +42,22 @@ Usage::
 
 from __future__ import annotations
 
+import functools
 import logging
+import threading
 import time
-from typing import Any, Dict, List, Optional
+import weakref
+from collections import OrderedDict
+from typing import Any, Callable, Dict, List, Optional, Tuple
 
 from PIL import Image
 
-from src.common import scroll_config
+from src.common import scroll_config, sports_vegas
 from src.common.scroll_helper import ScrollHelper
 
 logger = logging.getLogger(__name__)
 
+
 #: Defaults every copy agreed on. A subclass overrides
 #: :meth:`SportsScrollDisplay.scroll_settings_defaults` to change them —
 #: the soccer lineage uses a 24px gap and min/max duration keys instead.
@@ -318,7 +323,7 @@ class SportsScrollDisplay:
         :returns: True if a frame was drawn; False when there is no content or
             the frame could not be rendered.
         """
-        if not self.scroll_helper.cached_image:
+        if not self._has_strip():
             return False
 
         try:
@@ -411,7 +416,175 @@ class SportsScrollDisplay:
 
     def has_cached_content(self) -> bool:
         """Whether content is prepared and ready to scroll."""
-        return bool(self.scroll_helper.cached_image)
+        return self._has_strip()
+
+    def _has_strip(self) -> bool:
+        """Whether the helper holds a strip, without building its PIL image.
+
+        Reading ``cached_image`` after the strip was extended or trimmed builds
+        the image from the array and keeps it, so the strip is held twice;
+        display_scroll_frame asks this every frame. ``has_strip()`` answers
+        from the helper's bookkeeping. A helper without it (a plugin's own, a
+        test double) is asked the old way.
+        """
+        helper = self.scroll_helper
+        if callable(getattr(type(helper), "has_strip", None)):
+            return bool(helper.has_strip())
+        return bool(helper.cached_image)
+
+    # ------------------------------------------------------------------
+    # Live Vegas cards
+    # ------------------------------------------------------------------
+    #
+    # One live element per game (src/plugin_system/vegas_elements.py): the
+    # ticker swaps a card in place when its game changes. A sport opts in by
+    # implementing make_vegas_renderer(); everything else is here.
+
+    def make_vegas_renderer(self, card_width: int,
+                            rankings_cache: Optional[Dict[str, int]] = None) -> Any:
+        """The renderer this sport draws one game card with, at ``card_width``.
+
+        **Override point.** Return the object whose ``render_game_card(game,
+        game_type)`` draws one card exactly ``card_width`` wide at the display's
+        height -- the one prepare_scroll_content already builds -- without the
+        black padding prepare_scroll_content adds around each card (the ticker
+        adds its own). Raising NotImplementedError, the default, keeps the
+        plugin on its ordinary Vegas content.
+        """
+        raise NotImplementedError(
+            f"{type(self).__name__} has no live Vegas cards (make_vegas_renderer)")
+
+    def _determine_game_type(self, game: Dict[str, Any]) -> str:
+        """The card a game is drawn as: 'live', 'recent' or 'upcoming'.
+
+        From the game's state; a sport whose scroll display decides it
+        differently (most define their own) overrides this.
+        """
+        return {'in': 'live', 'post': 'recent'}.get(sports_vegas._state(game), 'upcoming')
+
+    def render_vegas_card(self, renderer: Any, game: Dict[str, Any]) -> Image.Image:
+        """Draw one game's card. Override only if the renderer is called differently."""
+        card: Image.Image = renderer.render_game_card(game, self._determine_game_type(game))
+        return card
+
+    def vegas_separator(self, league: str) -> Optional[Image.Image]:
+        """The league separator shown before a league's cards, if there is an icon."""
+        icon = self._separator_icons.get(league)
+        if icon is None:
+            return None
+        gap = self._vegas_settings(league).get("gap_between_games", 48)
+        pad = max(4, int(gap) // 2)
+        image = Image.new('RGB', (icon.width + pad * 2, self.display_height), (0, 0, 0))
+        mask = icon if icon.mode == 'RGBA' else None
+        image.paste(icon, (pad, (self.display_height - icon.height) // 2), mask)
+        return image
+
+    def _vegas_memo(self) -> Dict[Any, Any]:
+        """Per-size, per-config memo for the live path; emptied when either changes."""
+        stamp = (self.display_width, self.display_height, id(self.config))
+        memo: Optional[Tuple[Any, Dict[Any, Any]]] = getattr(self, '_vegas_memo_store', None)
+        if memo is None or memo[0] != stamp:
+            memo = (stamp, {})
+            self._vegas_memo_store = memo
+        store: Dict[Any, Any] = memo[1]
+        return store
+
+    def _vegas_settings(self, league: Optional[str]) -> Dict[str, Any]:
+        """A league's scroll settings, looked up once per size and config.
+
+        The live path asks after every update; a sport's settings lookup can
+        be expensive (sizing the default card width builds probe renderers).
+        """
+        memo = self._vegas_memo()
+        key = ('settings', league)
+        if key not in memo:
+            memo[key] = dict(self._get_scroll_settings(league))
+        settings: Dict[str, Any] = memo[key]
+        return settings
+
+    def _vegas_renderer(self, card_width: int,
+                        rankings_cache: Optional[Dict[str, int]]) -> Any:
+        """The sport's renderer for one card width, built once rather than per slate.
+
+        Building one loads fonts and, for the default card width, probes the
+        layout; the scroll path pays that on every prepare, which the live
+        path would repeat on every update.
+        """
+        memo = self._vegas_memo()
+        key = ('renderer', card_width)
+        if key not in memo:
+            memo[key] = self.make_vegas_renderer(card_width, rankings_cache)
+        renderer = memo[key]
+        if hasattr(renderer, 'set_rankings_cache'):
+            # Every time, empty included: the renderer is reused across
+            # slates, and ranks cleared since must not stay drawn.
+            renderer.set_rankings_cache(rankings_cache or {})
+        return renderer
+
+    def build_vegas_elements(
+        self,
+        games: List[Dict[str, Any]],
+        leagues: List[str],
+        rankings_cache: Optional[Dict[str, int]] = None,
+        fingerprint: Optional[Callable[[Dict[str, Any]], Any]] = None,
+        now: Optional[float] = None,
+    ) -> Optional[List[Any]]:
+        """The slate as live Vegas elements: one card per game, separators between leagues.
+
+        Only cards whose fingerprint changed are drawn; the rest come from the
+        cache. ``fingerprint(game)`` should return what the card draws (the
+        plugin's own signature fields, the clock included for live games); by
+        default the whole game dict is used, which redraws on any change. The
+        teams' ranks from ``rankings_cache`` count too: the renderer draws
+        them from there, not from the game.
+
+        Raises NotImplementedError when the sport has no make_vegas_renderer.
+        """
+        from src.plugin_system.vegas_elements import VegasElement
+
+        games = sports_vegas.dedupe_games(games)
+        if not games:
+            return None
+        # Settings follow each game's own league, not the slate's first one:
+        # a card's width must not change because another league has no games
+        # today (the ticker refuses a redraw of another width).
+        first = self._vegas_settings(leagues[0] if leagues else None)
+
+        cards = getattr(self, '_vegas_cards', None)
+        if cards is None:
+            cards = self._vegas_cards = sports_vegas.VegasCardCache()
+        odds = getattr(self, '_vegas_odds', None)
+        if odds is None:
+            odds = self._vegas_odds = sports_vegas.StickyOdds()
+        fingerprint = fingerprint or sports_vegas.game_fingerprint
+
+        elements: List[Any] = []
+        keys: List[str] = []
+        current_league = None
+        separators = 0
+        for game in games:
+            league = game.get("league")
+            settings = self._vegas_settings(league) if league else first
+            card_width = int(settings.get("game_card_width", self.display_width))
+            if settings.get("show_league_separators", True) and league != current_league:
+                separator = self.vegas_separator(league) if league else None
+                if separator is not None:
+                    elements.append(VegasElement(
+                        key=f"sep:{separators}:{league}", image=separator, live=False))
+                    separators += 1
+            current_league = league
+            key = sports_vegas.game_key(game)
+            drawn = odds.apply(key, game, now)
+            ranks = (rankings_cache.get(str(drawn.get("home_abbr"))),
+                     rankings_cache.get(str(drawn.get("away_abbr")))) if rankings_cache else None
+            renderer = self._vegas_renderer(card_width, rankings_cache)
+            elements.append(cards.element(
+                key, (fingerprint(drawn), ranks, card_width, self.display_height),
+                functools.partial(self.render_vegas_card, renderer, drawn)))
+            keys.append(key)
+        cards.retain(keys)
+        odds.retain(keys)
+        return elements
 
     def get_current_game_count(self) -> int:
         return len(self._current_games)
@@ -433,16 +606,80 @@ class SportsScrollDisplay:
         return info
 
 
+class _StripSlot:
+    """One slate's display in a game type's pool, and what its strip shows.
+
+    ``key`` is None when the strip must not be reused: never built, built
+    from something that could not be fingerprinted, a build that failed, or
+    released to stay inside the memory budget.
+    """
+
+    __slots__ = ("display", "key", "built_at", "strip", "last_used", "epoch")
+
+    def __init__(self, display: SportsScrollDisplay) -> None:
+        self.display = display
+        self.key: Optional[Tuple[Any, ...]] = None
+        self.built_at = 0.0
+        #: The helper's strip array when it was built, held weakly: a strip
+        #: replaced or cleared by anything since (a Vegas build on the same
+        #: display, a plugin calling clear()) no longer matches it.
+        self.strip: Optional[Callable[[], Any]] = None
+        self.last_used = 0.0
+        #: Bumped by every forget(). A build records its key only if this is
+        #: what it was when the build started: anything that forgot the slot
+        #: meanwhile (another build on this display, which may finish first
+        #: and leave its strip in the helper) means the strip in the helper
+        #: is not known to be this build's.
+        self.epoch = 0
+
+    def forget(self) -> None:
+        self.key = None
+        self.strip = None
+        self.epoch += 1
+
+
 class SportsScrollDisplayManager:
     """One :class:`SportsScrollDisplay` per game type ('live'/'recent'/'upcoming').
 
     Subclasses set :attr:`display_class`; everything else was near-identical
     across the eight plugin copies.
+
+    A recent or upcoming strip that has not changed is reused rather than
+    redrawn when its turn comes round again -- see :meth:`prepare_and_display`.
     """
 
     #: The SportsScrollDisplay subclass to instantiate per game type.
     display_class = SportsScrollDisplay
 
+    #: Game types whose strip is reused while nothing it is drawn from has
+    #: changed. Live is left out: its games change every poll, so the check
+    #: would never pay, and sports_live_scroll rebuilds a live strip in place
+    #: mid-cycle around get_scroll_display('live'), which has to stay the one
+    #: display it always was. Vegas's 'mixed' never comes through
+    #: prepare_and_display.
+    STRIP_MEMO_GAME_TYPES = frozenset({"recent", "upcoming"})
+
+    #: Oldest a reused strip may be. Not everything a card draws is in the
+    #: game dicts -- a team logo that was missing at the first build appears
+    #: only when the card is drawn again -- so an unchanged slate is still
+    #: redrawn this often.
+    STRIP_MEMO_MAX_AGE_S = 600.0
+
+    #: Displays kept per game type, one per slate (its leagues): the one on
+    #: screen plus the most recently shown others. When all are taken, the
+    #: least recently shown one draws the new slate, as the one shared display
+    #: always did, so a rotation with more slates than this costs no more
+    #: than before.
+    STRIP_MEMO_SLATES_PER_TYPE = 4
+
+    #: Ceiling, per plugin, on the strips kept for displays not on screen, in
+    #: bytes (the strip's array and image, and its Vegas items). Seven
+    #: football games at 192x48 come to ~0.65MB, thirty at 512x64 to ~4MB.
+    #: It bounds strip pixels only: each extra display also keeps its own
+    #: logo and separator-icon caches and frame buffer, and each slot a frozen
+    #: copy of the config in its key (~50KB), none of which is counted here.
+    STRIP_MEMO_MAX_PARKED_BYTES = 6 * 1024 * 1024
+
     def __init__(
         self,
         display_manager,
@@ -460,16 +697,34 @@ class SportsScrollDisplayManager:
         # either way, but two spellings of "nothing active" across two classes
         # is a trap for anyone comparing state between them.
         self._current_game_type: str = ""
+        # Per game type, its displays by slate, least recently shown first.
+        # _scroll_displays[game_type] is always the one on screen, so every
+        # reader of it (display_frame, is_complete, the plugins' own
+        # get_dynamic_duration and has_cached_content) sees what it did when
+        # there was only one display per game type.
+        self._strip_pools: Dict[str, "OrderedDict[Tuple[str, Tuple[Any, ...]], _StripSlot]"] = {}
+        # Only the bookkeeping is under it (and creating a slate's display,
+        # the first time that slate is drawn), never a build: a display()
+        # call that outlived its timeout can still be building when the next
+        # one starts.
+        self._strip_lock = threading.RLock()
+
+    def _new_scroll_display(self) -> SportsScrollDisplay:
+        return self.display_class(
+            self.display_manager,
+            self.config,
+            self.logger,
+            global_config=self.global_config,
+        )
 
     def get_scroll_display(self, game_type: str) -> SportsScrollDisplay:
-        """The display for ``game_type``, created on first use."""
+        """The display for ``game_type``, created on first use.
+
+        For a recent or upcoming game type, the display of the slate prepared
+        last -- the strip display_frame() draws.
+        """
         if game_type not in self._scroll_displays:
-            self._scroll_displays[game_type] = self.display_class(
-                self.display_manager,
-                self.config,
-                self.logger,
-                global_config=self.global_config,
-            )
+            self._scroll_displays[game_type] = self._new_scroll_display()
         return self._scroll_displays[game_type]
 
     def prepare_and_display(
@@ -479,8 +734,63 @@ class SportsScrollDisplayManager:
         leagues: List[str],
         rankings_cache: Optional[Dict[str, int]] = None,
     ) -> bool:
-        """Build content for ``game_type`` and make it the active strip."""
-        scroll_display = self.get_scroll_display(game_type)
+        """Build content for ``game_type`` and make it the active strip.
+
+        Building a strip draws every card while the render thread waits for
+        it, with the panel frozen on its last frame: ~1.4s for seven football
+        cards at 192x48 on a Pi 4, at the start of every turn and again each
+        time the cycle completes. A recent or upcoming turn usually draws
+        exactly the strip its slate drew last time. So when nothing the strip
+        is drawn from has changed -- the games, the rankings, the config, the
+        panel size and the date -- that strip is rewound and shown again
+        instead, which leaves the plugin's prepare_scroll_content() uncalled.
+
+        Two leagues usually take turns on one game type (nfl_recent, then
+        ncaa_fb_recent), so each slate keeps its own display rather than
+        sharing one; see STRIP_MEMO_SLATES_PER_TYPE. Anything in doubt is
+        drawn again: a live strip, a turn with no games, inputs that cannot
+        be fingerprinted, a strip older than STRIP_MEMO_MAX_AGE_S, or one
+        changed since it was built.
+        """
+        keyed = self._strip_memo_key(games, game_type, leagues, rankings_cache)
+        restore: Optional[SportsScrollDisplay] = None
+        epoch = 0
+        with self._strip_lock:
+            if keyed is None:
+                self._forget_shown_strip(game_type)
+                scroll_display = self.get_scroll_display(game_type)
+            else:
+                reused = self._reuse_strip(game_type, *keyed)
+                if reused is not None:
+                    # What a fresh build leaves: the strip at its start, a new
+                    # cycle not yet complete, this game type active.
+                    reused.reset_scroll()
+                    self._current_game_type = game_type
+                    self.logger.debug(
+                        "Reusing the unchanged %s strip for %s",
+                        game_type, ", ".join(map(str, keyed[0][1])))
+                    return True
+                scroll_display, restore, epoch = self._display_to_build(
+                    game_type, keyed[0])
+            # Before the build, so data that changes during it reads as changed.
+            started = time.monotonic()
+        success = self._prepare_on(
+            scroll_display, games, game_type, leagues, rankings_cache)
+        if keyed is not None:
+            with self._strip_lock:
+                self._note_strip_built(
+                    game_type, keyed, scroll_display, restore, success, started,
+                    epoch)
+        return success
+
+    def _prepare_on(
+        self,
+        scroll_display: SportsScrollDisplay,
+        games: List[Dict],
+        game_type: str,
+        leagues: List[str],
+        rankings_cache: Optional[Dict[str, int]],
+    ) -> bool:
         try:
             success = scroll_display.prepare_scroll_content(
                 games, game_type, leagues, rankings_cache
@@ -498,6 +808,200 @@ class SportsScrollDisplayManager:
             self._current_game_type = game_type
         return success
 
+    # ------------------------------------------------------------------
+    # Reusing an unchanged strip
+    # ------------------------------------------------------------------
+
+    def _strip_memo_key(
+        self,
+        games: Any,
+        game_type: str,
+        leagues: Any,
+        rankings_cache: Any,
+    ) -> Optional[Tuple[Tuple[str, Tuple[Any, ...]], Tuple[Any, ...]]]:
+        """``(slate, key)``: which display, and everything its strip is drawn
+        from. None when this strip must be drawn regardless.
+
+        The games go through sports_vegas.game_fingerprint, the same "has
+        this card changed" the live Vegas cards are redrawn on: the whole
+        game dict, so no field a card draws can be missed. The config is
+        fingerprinted by value, not by identity, so a config edited in place
+        counts as changed.
+        """
+        if game_type not in self.STRIP_MEMO_GAME_TYPES or not games:
+            return None
+        # Iterated twice (here and by the build), so a one-shot iterable
+        # would reach the build empty.
+        if not isinstance(games, (list, tuple)) or not isinstance(leagues, (list, tuple)):
+            return None
+        try:
+            slate = (game_type, tuple(leagues))
+            hash(slate)
+            key = (
+                tuple(sports_vegas.game_fingerprint(game) for game in games),
+                sports_vegas._freeze(rankings_cache),
+                sports_vegas._freeze(self.config),
+                (getattr(self.display_manager, "width", None),
+                 getattr(self.display_manager, "height", None)),
+                # A backstop: no card reads the clock today (game dates come
+                # in the game dicts), but a strip must not outlive its day.
+                time.localtime()[:3],
+            )
+        except Exception:
+            # A game dict changing size under a background update, say. The
+            # build reads it anyway; only the reuse is given up.
+            self.logger.debug("Strip for %s not reusable this turn", game_type,
+                              exc_info=True)
+            return None
+        return slate, key
+
+    def _strip_reusable(self, slot: _StripSlot, key: Tuple[Any, ...]) -> bool:
+        if slot.key is None or slot.strip is None:
+            return False
+        if time.monotonic() - slot.built_at >= self.STRIP_MEMO_MAX_AGE_S:
+            return False
+        helper = getattr(slot.display, "scroll_helper", None)
+        array = getattr(helper, "cached_array", None)
+        if array is None or slot.strip() is not array:
+            return False
+        has_strip = getattr(helper, "has_strip", None)
+        if callable(has_strip) and not has_strip():
+            return False
+        return bool(slot.key == key)
+
+    def _reuse_strip(
+        self, game_type: str, slate: Tuple[str, Tuple[Any, ...]], key: Tuple[Any, ...],
+    ) -> Optional[SportsScrollDisplay]:
+        """The display already showing this exact strip, made the active one."""
+        pool = self._strip_pools.get(game_type)
+        slot = pool.get(slate) if pool else None
+        if pool is None or slot is None or not self._strip_reusable(slot, key):
+            return None
+        pool.move_to_end(slate)
+        slot.last_used = time.monotonic()
+        # The display this replaces keeps its slot and strip for its own next
+        # turn, within the parked-strip budget.
+        self._scroll_displays[game_type] = slot.display
+        self._trim_parked_strips()
+        return slot.display
+
+    def _display_to_build(
+        self, game_type: str, slate: Tuple[str, Tuple[Any, ...]],
+    ) -> Tuple[SportsScrollDisplay, Optional[SportsScrollDisplay], int]:
+        """The display to draw ``slate`` on, made the active one.
+
+        Returns it; when it replaced another as the active display, that
+        one, to put back if the build fails -- a failed build left the
+        previous strip showing when the game type had one display; and the
+        slot's epoch the build must still find to record its key.
+        """
+        pool = self._strip_pools.setdefault(game_type, OrderedDict())
+        active = self._scroll_displays.get(game_type)
+        slot = pool.get(slate)
+        if slot is None:
+            if active is not None and not any(s.display is active for s in pool.values()):
+                # The game type's display, holding nothing reusable: this
+                # slate is drawn on it, exactly as before slates had their own.
+                slot = _StripSlot(active)
+            elif len(pool) < max(1, self.STRIP_MEMO_SLATES_PER_TYPE):
+                slot = _StripSlot(self._new_scroll_display())
+            else:
+                # The least recently shown slate's display draws this one.
+                _, slot = pool.popitem(last=False)
+            pool[slate] = slot
+        # Whatever was reusable on it is about to be drawn over.
+        slot.forget()
+        pool.move_to_end(slate)
+        slot.last_used = time.monotonic()
+        self._scroll_displays[game_type] = slot.display
+        replaced = active if active is not None and active is not slot.display else None
+        return slot.display, replaced, slot.epoch
+
+    def _note_strip_built(
+        self,
+        game_type: str,
+        keyed: Tuple[Tuple[str, Tuple[Any, ...]], Tuple[Any, ...]],
+        scroll_display: SportsScrollDisplay,
+        restore: Optional[SportsScrollDisplay],
+        success: bool,
+        started: float,
+        epoch: int,
+    ) -> None:
+        slate, key = keyed
+        pool = self._strip_pools.get(game_type)
+        slot = pool.get(slate) if pool else None
+        if (slot is None or slot.display is not scroll_display or slot.epoch != epoch
+                or self._scroll_displays.get(game_type) is not scroll_display):
+            # Another prepare moved on while this one built, or drew on this
+            # display too. Record nothing; the strip is drawn again next time.
+            return
+        array = getattr(scroll_display.scroll_helper, "cached_array", None)
+        if success and array is not None:
+            slot.key = key
+            slot.built_at = started
+            slot.strip = weakref.ref(array)
+        elif not success and restore is not None:
+            self._scroll_displays[game_type] = restore
+        self._trim_parked_strips()
+
+    def _forget_shown_strip(self, game_type: str) -> None:
+        """A build this memo cannot key is about to draw on the active display."""
+        active = self._scroll_displays.get(game_type)
+        for slot in (self._strip_pools.get(game_type) or {}).values():
+            if slot.display is active:
+                slot.forget()
+
+    @staticmethod
+    def _strip_bytes(scroll_display: SportsScrollDisplay) -> int:
+        """What keeping this display's strip costs: the strip's array, the
+        image beside it, and its Vegas items."""
+        array = getattr(scroll_display.scroll_helper, "cached_array", None)
+        total = int(array.nbytes) * 2 if array is not None else 0
+        for item in getattr(scroll_display, "_vegas_content_items", None) or ():
+            total += item.width * item.height * len(item.getbands())
+        return total
+
+    def _trim_parked_strips(self) -> None:
+        """Release the strips of displays not on screen until they fit
+        STRIP_MEMO_MAX_PARKED_BYTES: those that can never be reused first (a
+        failed build left an older slate's strip behind), then the least
+        recently shown. The display itself is kept, so its slate's next turn
+        draws on it again."""
+        # list() first: get_scroll_display() can add a game type from another
+        # thread (Vegas's 'mixed'), and a dict must not grow mid-iteration.
+        on_screen = {id(display) for display in list(self._scroll_displays.values())}
+        parked = []
+        total = 0
+        for pool in self._strip_pools.values():
+            for slot in pool.values():
+                if id(slot.display) in on_screen:
+                    continue
+                try:
+                    size = self._strip_bytes(slot.display)
+                except Exception:
+                    # Unmeasurable: assume it does not fit.
+                    size = self.STRIP_MEMO_MAX_PARKED_BYTES + 1
+                if size:
+                    parked.append((slot.last_used, size, slot))
+                    total += size
+        parked.sort(key=lambda entry: (entry[2].key is not None, entry[0]))
+        for _, size, slot in parked:
+            if total <= self.STRIP_MEMO_MAX_PARKED_BYTES:
+                break
+            slot.forget()
+            self._release_strip(slot.display)
+            total -= size
+
+    def _release_strip(self, scroll_display: SportsScrollDisplay) -> None:
+        """Drop a display's strip without SportsScrollDisplay.clear(), which
+        also tells the display manager nothing is scrolling -- not this
+        display's to say while another one is on screen."""
+        try:
+            scroll_display.scroll_helper.clear_cache()
+            scroll_display._vegas_content_items = []
+        except Exception:
+            self.logger.debug("Could not release a parked strip", exc_info=True)
+
     def display_frame(self, game_type: Optional[str] = None) -> bool:
         """Advance the active strip (or a named one) by one frame."""
         game_type = game_type or self._current_game_type
@@ -520,11 +1024,48 @@ class SportsScrollDisplayManager:
         return scroll_display.is_scroll_complete()
 
     def clear_all(self) -> None:
-        """Clear every display and forget which one was active."""
-        for scroll_display in self._scroll_displays.values():
+        """Clear every display and forget which one was active.
+
+        The displays of slates not on screen too, and nothing cleared is
+        reused: the next prepare draws its strip again.
+        """
+        displays = list(self._scroll_displays.values())
+        with self._strip_lock:
+            for pool in self._strip_pools.values():
+                for slot in pool.values():
+                    slot.forget()
+                    if not any(slot.display is shown for shown in displays):
+                        displays.append(slot.display)
+        for scroll_display in displays:
             scroll_display.clear()
         self._current_game_type = ""
 
+    def get_vegas_elements_for(
+        self,
+        game_type: str,
+        games: List[Dict[str, Any]],
+        leagues: List[str],
+        rankings_cache: Optional[Dict[str, int]] = None,
+        fingerprint: Optional[Callable[[Dict[str, Any]], Any]] = None,
+    ) -> Optional[List[Any]]:
+        """Live Vegas cards for a slate, built on the ``game_type`` display.
+
+        None when the sport has no live cards (it does not implement
+        make_vegas_renderer) or building them failed, so the plugin's
+        get_vegas_elements() can return it and the ticker falls back to the
+        plugin's ordinary Vegas content.
+        """
+        scroll_display = self.get_scroll_display(game_type)
+        try:
+            return scroll_display.build_vegas_elements(
+                games, leagues, rankings_cache, fingerprint)
+        except NotImplementedError:
+            return None
+        except Exception:
+            # Built straight from feed data, like prepare_scroll_content.
+            self.logger.exception("Error building live Vegas cards")
+            return None
+
     def get_all_vegas_content_items(self) -> List[Image.Image]:
         """Every display's Vegas items, for splicing into the marquee."""
         items: List[Image.Image] = []

src/common/sports_shared.py

@@ -102,6 +102,7 @@ import requests
 from PIL import Image, ImageDraw
 from src.common import sports_card as _card
 from src.common.font_layout import load_truetype, resolve_asset_path
+from src.common.text_helper import OUTLINE_SQUARE, draw_text_outlined
 
 logger = logging.getLogger(__name__)
 
@@ -359,14 +360,16 @@ class SportsCoreSharedMixin:
         The formatting is sports_card's. What differs from the card's
         ``format_game_date`` is passed in: the setting (``switch_date_format``,
         see :meth:`_switch_date_format`) and the weekday, which comes from
-        :meth:`_weekday_for` and so from this plugin's resolved timezone.
+        :meth:`_weekday_for` and so from this plugin's resolved timezone
+        when the game's start cannot place the printed date. The game goes
+        in too, so both formatters name the printed date's own weekday.
         """
         raw = str(date_text or "").strip()
         if not raw:
             return raw
         return _card._format_date_as(self._switch_date_format(), raw,
                                      lambda: self._weekday_for(game),
-                                     self._MONTH_ABBR)
+                                     self._MONTH_ABBR, game=game)
 
     def _weekday_for(self, game: Optional[Dict]) -> str:
         """Weekday abbreviation from the game's start time, or ''."""
@@ -851,19 +854,12 @@ class SportsCoreSharedMixin:
         elif fill is None:
             fill = self._font_color(font)
         draw.fontmode = "1"
-        x, y = position
-        for dx, dy in [
-            (-1, -1),
-            (-1, 0),
-            (-1, 1),
-            (0, -1),
-            (0, 1),
-            (1, -1),
-            (1, 0),
-            (1, 1),
-        ]:
-            draw.text((x + dx, y + dy), text, font=font, fill=outline_color)
-        draw.text((x, y), text, font=font, fill=fill)
+        # The eight-neighbour outline, then the text on top. Rasterized once
+        # and stamped nine times rather than drawn nine times; the pixels are
+        # the same (draw_text_outlined falls back to the nine draws wherever
+        # that is not proven).
+        draw_text_outlined(draw, position, text, font, fill, outline_color,
+                           OUTLINE_SQUARE)
 
     def _should_log(self, warning_type: str, cooldown: int = 60) -> bool:
         """True at most once per ``cooldown`` seconds, for rate-limiting a
@@ -1348,6 +1344,55 @@ class SportsLiveSharedMixin:
                 or candidate < current):
             self._next_scheduled_start_ts = candidate
 
+    #: How long a game that finished live is still reported by
+    #: finished_games_snapshot(): long enough for the recent-games list, which
+    #: refreshes about hourly, to take it over well before most slates would.
+    FINISHED_GAME_TTL = 900.0
+
+    def _record_finished_game(self, details: Dict) -> None:
+        """Remember a game that was live and has just gone final (or looks over).
+
+        A finished game leaves ``live_games`` at the next poll, and the recent
+        list that will show it refreshes about hourly, so in between nothing
+        holds the game's final score -- and a live Vegas card for it would keep
+        its last live score. Call this wherever a poll drops a game as final
+        or over. Only a game this manager had as live is taken; one already
+        held takes the newer details (a game dropped by an "is it over"
+        heuristic, then marked final by the feed) but keeps its expiry, so a
+        feed that lists finals all day cannot keep one here all day.
+        """
+        game_id = details.get("id") if isinstance(details, dict) else None
+        if not game_id:
+            return
+        finished = self.__dict__.setdefault("_finished_games", {})
+        held = finished.get(game_id)
+        if held is not None:
+            finished[game_id] = (held[0], dict(details))
+            return
+        if not any(g.get("id") == game_id for g in getattr(self, "live_games", ()) or ()):
+            return
+        finished[game_id] = (time.monotonic(), dict(details))
+
+    def finished_games_snapshot(self) -> List[Dict]:
+        """Games that went final here within FINISHED_GAME_TTL, newest data first.
+
+        Copies, safe to decorate. The caller dedupes them against its other
+        lists (src/common/sports_vegas.dedupe_games keeps the liveliest copy,
+        and a final beats nothing but a live one).
+        """
+        finished = self.__dict__.get("_finished_games")
+        if not finished:
+            return []
+        now = time.monotonic()
+        # A copy first: a manager finishing its update in the background (off
+        # the plugin's lock) may record a game while the ticker reads these.
+        held = list(finished.items())
+        for game_id, (seen, _game) in held:
+            if now - seen > self.FINISHED_GAME_TTL:
+                finished.pop(game_id, None)
+        return [dict(game) for _id, (seen, game) in held
+                if now - seen <= self.FINISHED_GAME_TTL]
+
     def _note_live_fetch(self, found_live: bool) -> None:
         """Record whether a look for live games found any."""
         if found_live:

src/common/sports_vegas.py

@@ -0,0 +1,250 @@
+"""Live Vegas cards for the sports scoreboards.
+
+A scoreboard hands the Vegas ticker one card per game. As live elements
+(src/plugin_system/vegas_elements.py) those cards change on the panel while
+they scroll: a goal redraws its game's card and the ticker swaps it in place.
+This module is what every scoreboard needs for that and would otherwise write
+nine times:
+
+- :func:`game_key` -- a stable key per game, so the ticker can tell which card
+  a redraw belongs to however the slate is re-sorted.
+- :class:`VegasCardCache` -- draws a card only when what it shows changed
+  (its fingerprint), so an unchanged slate costs a dictionary lookup per game
+  and a changed one only the cards that changed.
+- :class:`StickyOdds` -- live odds are fetched only for games near the front
+  of the rotation, so a card's odds come and go between polls; this keeps the
+  last odds for a while instead of redrawing the card without them.
+- :func:`dedupe_games` -- a game present in two managers' lists (live and
+  recent, around the final whistle) appears once, its liveliest copy.
+- :func:`finished_games` / :func:`with_finished_games` -- a game that has just
+  gone final keeps its card, now showing FINAL, where its live card was,
+  until the recent list (refreshed about hourly) takes it over.
+- :func:`game_fingerprint` -- what a card is redrawn on by default: the whole
+  game dict, frozen hashable.
+
+SportsScrollDisplay.build_vegas_elements (src/common/sports_scroll.py) puts
+them together; a plugin adopts it by implementing make_vegas_renderer().
+"""
+
+from __future__ import annotations
+
+import time
+from collections import OrderedDict
+from typing import Any, Callable, Dict, Hashable, Iterable, List, Optional, Tuple
+
+from PIL import Image
+
+#: Which copy of a duplicated game wins: the liveliest.
+_STATE_PRIORITY = {'in': 3, 'post': 2, 'pre': 1}
+
+
+def _state(game: Dict[str, Any]) -> str:
+    status = game.get('status')
+    state = status.get('state') if isinstance(status, dict) else status
+    if isinstance(state, str):
+        return state
+    if game.get('is_live'):
+        return 'in'
+    if game.get('is_final'):
+        return 'post'
+    return 'pre'
+
+
+def _freeze(value: Any) -> Any:
+    """A hashable, order-stable copy of feed data."""
+    if isinstance(value, dict):
+        return tuple(sorted((str(k), _freeze(v)) for k, v in value.items()))
+    if isinstance(value, (list, tuple)):
+        return tuple(_freeze(v) for v in value)
+    if isinstance(value, (str, int, float, bool)) or value is None:
+        return value
+    return repr(value)
+
+
+def game_fingerprint(game: Dict[str, Any]) -> Hashable:
+    """Everything in a game dict, hashable: a card drawn from it changes only if this does.
+
+    The default card version. Nothing a card could draw is left out, so no
+    field is ever frozen on the panel; the cost is a redraw when a field the
+    card does not draw changes too, which feed data rarely does between polls.
+    """
+    frozen: Hashable = _freeze(game)
+    return frozen
+
+
+def game_key(game: Dict[str, Any]) -> str:
+    """A key that names this game and nothing else, across polls.
+
+    ``game:<league>:<id>`` from the feed's own id. A game without one falls
+    back to its teams and start time, which is stable for the life of a game.
+    """
+    league = game.get('league') or 'game'
+    game_id = game.get('id') or game.get('game_id')
+    if game_id not in (None, ''):
+        return f"game:{league}:{game_id}"
+    away = game.get('away_abbr') or game.get('away_team') or '?'
+    home = game.get('home_abbr') or game.get('home_team') or '?'
+    start = game.get('start_time_utc') or game.get('start_time') or ''
+    return f"game:{league}:{away}@{home}:{start}"
+
+
+def dedupe_games(games: Iterable[Dict[str, Any]],
+                 key_fn: Callable[[Dict[str, Any]], str] = game_key) -> List[Dict[str, Any]]:
+    """Each game once, in first-seen order, keeping its liveliest copy.
+
+    Around a final whistle a game can be in the live list (last poll) and the
+    recent list (next poll) at once; two cards with one key would be refused
+    by the ticker, and showing the game twice is wrong anyway.
+    """
+    chosen: "OrderedDict[str, Dict[str, Any]]" = OrderedDict()
+    for game in games:
+        key = key_fn(game)
+        current = chosen.get(key)
+        if current is None or _STATE_PRIORITY.get(_state(game), 0) > \
+                _STATE_PRIORITY.get(_state(current), 0):
+            chosen[key] = game
+    return list(chosen.values())
+
+
+def finished_games(
+        live_managers: Iterable[Tuple[str, Any]]) -> List[Dict[str, Any]]:
+    """Games that just left these live managers' lists, final ones as recent games.
+
+    ``live_managers`` pairs each league with its live manager (None is
+    skipped). Each manager reports what SportsLiveSharedMixin recorded
+    (finished_games_snapshot, copies), with its league. A final game is
+    drawn as a recent card. One a poll only judged over -- a tied end of
+    regulation looks like that too -- keeps its last live state, so its card
+    never says FINAL early; if play resumes the live list has it again, and
+    dedupe_games keeps that copy.
+    """
+    finished: List[Dict[str, Any]] = []
+    for league, manager in live_managers:
+        snapshot = getattr(manager, 'finished_games_snapshot', None)
+        if not callable(snapshot):
+            continue
+        for game in snapshot():
+            game['league'] = league
+            if game.get('is_final'):
+                status = game.get('status')
+                status = dict(status) if isinstance(status, dict) else {}
+                status['state'] = 'post'
+                game.update(status=status, is_live=False)
+            finished.append(game)
+    return finished
+
+
+def with_finished_games(
+    games: List[Dict[str, Any]], leagues: List[str],
+    finished: List[Dict[str, Any]],
+) -> Tuple[List[Dict[str, Any]], List[str]]:
+    """The slate with games that just went final where their live cards were.
+
+    A slate lists each league's games together, live ones first. Each
+    finished game goes after its league's live games, ahead of the rest; a
+    league with no games left in the slate is added at the end. A finished
+    game the slate also has (the recent list caught up) is left for
+    dedupe_games, which keeps one copy.
+    """
+    if not finished:
+        return list(games), list(leagues)
+    pending: "OrderedDict[Any, List[Dict[str, Any]]]" = OrderedDict()
+    for game in finished:
+        pending.setdefault(game.get('league'), []).append(game)
+    merged: List[Dict[str, Any]] = []
+    for index, game in enumerate(games):
+        league = game.get('league')
+        if league in pending and _state(game) != 'in':
+            merged.extend(pending.pop(league))
+        merged.append(game)
+        following = games[index + 1] if index + 1 < len(games) else None
+        if league in pending and (following is None or following.get('league') != league):
+            merged.extend(pending.pop(league))       # the league's games were all live
+    leagues = list(leagues)
+    for league, rest in pending.items():
+        merged.extend(rest)
+        if league not in leagues:
+            leagues.append(league)
+    return merged, leagues
+
+
+class VegasCardCache:
+    """Cards drawn once per fingerprint, kept for as long as their game is.
+
+    ``element(key, fingerprint, render)`` returns a VegasElement whose image is
+    ``render()``'s -- called only when the fingerprint differs from the one the
+    cached card was drawn for. The fingerprint is also the element's version,
+    so the ticker skips unchanged cards without comparing pixels.
+
+    Bounded: keys not passed to :meth:`retain` after a slate are dropped, and
+    at most ``max_entries`` are ever held (oldest first).
+    """
+
+    def __init__(self, max_entries: int = 96) -> None:
+        self.max_entries = max(1, int(max_entries))
+        self._cards: "OrderedDict[str, Tuple[Hashable, Image.Image]]" = OrderedDict()
+        self.renders = 0
+
+    def element(self, key: str, fingerprint: Hashable,
+                render: Callable[[], Image.Image], live: bool = True) -> Any:
+        from src.plugin_system.vegas_elements import VegasElement
+
+        cached = self._cards.get(key)
+        if cached is not None and cached[0] == fingerprint:
+            self._cards.move_to_end(key)
+            image = cached[1]
+        else:
+            image = render()
+            self.renders += 1
+            self._cards[key] = (fingerprint, image)
+            self._cards.move_to_end(key)
+            while len(self._cards) > self.max_entries:
+                self._cards.popitem(last=False)
+        return VegasElement(key=key, image=image, version=fingerprint, live=live)
+
+    def retain(self, keys: Iterable[str]) -> None:
+        """Forget every card whose key is not in ``keys``."""
+        keep = set(keys)
+        for key in [k for k in self._cards if k not in keep]:
+            self._cards.pop(key, None)
+
+    def clear(self) -> None:
+        self._cards.clear()
+
+    def __len__(self) -> int:
+        return len(self._cards)
+
+
+class StickyOdds:
+    """Keep a game's last odds on its card while a live poll leaves them out.
+
+    Live odds are fetched only for games near the front of the rotation
+    (src/common/sports_fetch.py), so the same game's dict has odds on one poll
+    and none on the next. Drawn as-is that redraws the card every poll with
+    the odds flickering in and out. ``apply`` returns the game with its last
+    non-empty odds put back, for up to ``ttl_s`` seconds after they were seen.
+    """
+
+    def __init__(self, ttl_s: float = 600.0) -> None:
+        self.ttl_s = float(ttl_s)
+        self._seen: Dict[str, Tuple[float, Any]] = {}
+
+    def apply(self, key: str, game: Dict[str, Any],
+              now: Optional[float] = None) -> Dict[str, Any]:
+        now = time.monotonic() if now is None else now
+        odds = game.get('odds')
+        if odds:
+            self._seen[key] = (now, odds)
+            return game
+        seen = self._seen.get(key)
+        if seen is None or now - seen[0] > self.ttl_s:
+            self._seen.pop(key, None)
+            return game
+        refilled = dict(game)
+        refilled['odds'] = seen[1]
+        return refilled
+
+    def retain(self, keys: Iterable[str]) -> None:
+        keep = set(keys)
+        for key in [k for k in self._seen if k not in keep]:
+            self._seen.pop(key, None)

src/common/sync_manager.py

@@ -29,7 +29,6 @@ import time
 import logging
 from enum import Enum
 from typing import Callable, Optional
-import numpy as np
 from PIL import Image
 
 from src.config_manager_atomic import _replace
@@ -434,6 +433,12 @@ class DisplaySyncManager:
             return
         if self._leader_state != LeaderState.CONNECTED or not self._peer_ip:
             return
+        # numpy is imported here, not at module level: the web interface
+        # imports this module for its constants (STATUS_FILE, SYNC_PORT) and
+        # would otherwise load numpy for nothing. Only a connected leader
+        # gets this far, and after the first frame the import is a
+        # sys.modules lookup.
+        import numpy as np
         try:
             arr = np.asarray(image.convert("RGB"), dtype=np.uint8)
             header = _RAW_MAGIC + _RAW_HEADER.pack(image.width, image.height)

src/common/text_helper.py

@@ -7,7 +7,7 @@ Extracted from LEDMatrix core to provide reusable functionality for plugins.
 
 import logging
 from pathlib import Path
-from typing import Dict, List, Optional, Tuple, Union
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple, Union
 
 from PIL import Image, ImageDraw, ImageFont
 from src.common.font_layout import load_truetype, resolve_asset_path
@@ -15,6 +15,174 @@ from src.common.font_layout import load_truetype, resolve_asset_path
 # Shared throwaway draw surface for measuring text without a target canvas.
 _measure_draw = ImageDraw.Draw(Image.new("RGB", (1, 1)))
 
+#: A one-pixel outline on all eight sides, in the order the scoreboards have
+#: always drawn it (dx outer, dy inner). The order can change pixels only
+#: where anti-aliased (fontmode "L") edges overlap; it is kept anyway.
+OUTLINE_SQUARE: Tuple[Tuple[int, int], ...] = (
+    (-1, -1), (-1, 0), (-1, 1), (0, -1), (0, 1), (1, -1), (1, 0), (1, 1))
+
+#: A one-pixel outline on the four edge sides only, leaving the diagonal
+#: corners open: the thinner outline ufc's fight card draws.
+OUTLINE_CROSS: Tuple[Tuple[int, int], ...] = ((-1, 0), (1, 0), (0, -1), (0, 1))
+
+# What the stamping path in draw_text_outlined is proven pixel-identical for
+# (test/test_text_helper.py compares it with the draw.text loop across every
+# combination). Anything else takes the loop. Compared with ``in`` on tuples
+# rather than sets so an unhashable fontmode falls back instead of raising.
+_STAMP_DRAW_MODES = ("RGB", "RGBA", "L")
+_STAMP_FONT_MODES = ("1", "L")
+
+# ImageDraw.text as Pillow defines it, which the stamping path stands in for.
+# A draw whose text has been replaced since -- on the class or the instance,
+# as a test recording the strings drawn does -- takes the loop, so the
+# replacement still sees every call.
+_PILLOW_DRAW_TEXT = ImageDraw.ImageDraw.text
+
+
+def draw_text_outlined(draw: ImageDraw.ImageDraw, xy: Sequence[Any], text: Any,
+                       font: Any, fill: Any,
+                       outline_color: Any = (0, 0, 0),
+                       offsets: Iterable[Sequence[Any]] = OUTLINE_SQUARE) -> None:
+    """Draw ``text`` in ``outline_color`` at each of ``offsets``, then in ``fill`` on top.
+
+    The result is pixel-identical to the loop every outlined draw used to be::
+
+        x, y = xy
+        for dx, dy in offsets:
+            draw.text((x + dx, y + dy), text, font=font, fill=outline_color)
+        draw.text((x, y), text, font=font, fill=fill)
+
+    but each ``draw.text`` rasterizes the whole string through FreeType again,
+    so the default nine draws did the same glyph work nine times, and on a
+    scoreboard card that text work is much of the render. Here the string is
+    rasterized once and the one mask is stamped at every offset, which is
+    what ``draw.text`` itself does with the mask, so the pixels are the same.
+
+    That holds only where it has been checked: a plain ``ImageDraw`` whose
+    ``text`` is Pillow's, a ``FreeTypeFont``, one line of ``str``, whole-pixel
+    ``xy`` (an int, or a float with nothing after the point, which is what
+    centring on a measured ``textlength`` with ``// 2`` gives) and int
+    offsets, and the image and font modes in ``_STAMP_DRAW_MODES`` /
+    ``_STAMP_FONT_MODES``. Fractional coordinates change the raster itself
+    (Pillow rasterizes at the sub-pixel start), and multiline text is laid
+    out line by line. Every other case, and anything
+    the stamping path cannot prepare, runs the loop above unchanged, so it
+    behaves exactly as before, errors included.
+
+    Args:
+        draw: The ``ImageDraw`` to draw on.
+        xy: Top-left (x, y) of the text, as for ``draw.text``.
+        text: The text.
+        font: The font, as for ``draw.text``.
+        fill: Colour of the text itself, drawn last.
+        outline_color: Colour of the outline.
+        offsets: (dx, dy) of each outline draw, in drawing order.
+            :data:`OUTLINE_SQUARE` (the default) or :data:`OUTLINE_CROSS`.
+    """
+    x, y = xy
+    # Read once: the loop below may have to start over after the stamping
+    # path looked at them.
+    offsets = tuple(offsets)
+    if _can_stamp(draw, x, y, text, font, offsets):
+        if _stamp_outlined(draw, int(x), int(y), text, font, fill,
+                           outline_color, offsets):
+            return
+    for dx, dy in offsets:
+        draw.text((x + dx, y + dy), text, font=font, fill=outline_color)
+    draw.text((x, y), text, font=font, fill=fill)
+
+
+def _can_stamp(draw: Any, x: Any, y: Any, text: Any, font: Any,
+               offsets: Tuple[Any, ...]) -> bool:
+    """Whether draw_text_outlined may stamp one mask instead of drawing N times.
+
+    Exact types for the draw and the font, and Pillow's own ``draw.text``: a
+    subclass may override ``text`` or ``getmask2``, or a test may replace
+    ``draw.text`` to record what is drawn, and stamping would skip either.
+    """
+    return (
+        type(draw) is ImageDraw.ImageDraw
+        and ImageDraw.ImageDraw.text is _PILLOW_DRAW_TEXT
+        and "text" not in vars(draw)
+        and type(font) is ImageFont.FreeTypeFont
+        and isinstance(text, str)
+        and "\n" not in text
+        and "\r" not in text
+        and _whole_pixel(x)
+        and _whole_pixel(y)
+        and all(isinstance(o, (tuple, list)) and len(o) == 2
+                and isinstance(o[0], int) and isinstance(o[1], int)
+                for o in offsets)
+        and draw.mode in _STAMP_DRAW_MODES
+        and draw.fontmode in _STAMP_FONT_MODES
+    )
+
+
+def _whole_pixel(v: Any) -> bool:
+    """An int, or a float on a whole pixel, as a draw.text coordinate.
+
+    For those, draw.text's ``int(x + dx)`` is ``int(x) + dx`` and its
+    sub-pixel start is 0 (or -0.0, which renders the same), so one mask fits
+    every offset. Floats are held well inside the range where ``x + dx`` is
+    exact; nothing that far out is on any canvas, so the loop the rest take
+    costs nothing that matters.
+    """
+    if isinstance(v, int):
+        return True
+    return isinstance(v, float) and v.is_integer() and -2**31 < v < 2**31
+
+
+def _text_ink(draw: ImageDraw.ImageDraw, color: Any) -> Any:
+    """The ink ``ImageDraw.text`` resolves ``color`` to (its inner getink)."""
+    ink, fill_ink = draw._getink(color)
+    return fill_ink if ink is None else ink
+
+
+def _stamp_outlined(draw: ImageDraw.ImageDraw, x: int, y: int, text: str,
+                    font: ImageFont.FreeTypeFont, fill: Any, outline_color: Any,
+                    offsets: Tuple[Sequence[Any], ...]) -> bool:
+    """Rasterize once and stamp; False, with nothing drawn, to take the loop.
+
+    Replays what ``ImageDraw.text`` does for one line at an integer position
+    (Pillow 11 and 12): ``font.getmask2`` with these arguments, then
+    ``draw.draw.draw_bitmap`` at the position plus the mask's offset.
+    ``draw.draw`` and ``draw._getink`` are Pillow internals, so everything up
+    to the first pixel is guarded: if anything fails before then, nothing has
+    been drawn and the loop runs instead, which then fails (or not) exactly
+    as it always did -- a bad fill colour still raises after the outline is
+    drawn, as it did from the last ``draw.text``.
+    """
+    try:
+        outline_ink = _text_ink(draw, outline_color)
+        text_ink = _text_ink(draw, fill)
+        # What draw.text passes for a single line with no anchor at a whole
+        # pixel position, by keyword so a getmask2 with another parameter
+        # order cannot shift them. ink only matters to an RGBA (colour-glyph)
+        # mask, which the font modes allowed here never produce.
+        mask, (ox, oy) = font.getmask2(
+            text, draw.fontmode, direction=None, features=None,
+            language=None, stroke_width=0, anchor="la", ink=text_ink,
+            start=(0.0, 0.0), stroke_filled=True)
+        draw_bitmap = draw.draw.draw_bitmap
+    except Exception:
+        return False
+    stamped = False
+    try:
+        # draw.text returns without drawing when its ink resolves to None.
+        if outline_ink is not None:
+            for dx, dy in offsets:
+                draw_bitmap((x + dx + ox, y + dy + oy), mask, outline_ink)
+                stamped = True
+        if text_ink is not None:
+            draw_bitmap((x + ox, y + oy), mask, text_ink)
+    except Exception:
+        # A rejected call draws nothing, but one that got through has: never
+        # draw the outline twice (anti-aliased edges would be blended twice).
+        if stamped:
+            raise
+        return False
+    return True
+
 
 class TextHelper:
     """
@@ -103,15 +271,15 @@ class TextHelper:
             outline_width: Width of outline in pixels
         """
         x, y = position
-        
-        # Draw outline by drawing text in outline color at offset positions
-        for dx in range(-outline_width, outline_width + 1):
-            for dy in range(-outline_width, outline_width + 1):
-                if dx != 0 or dy != 0:  # Skip center position
-                    draw.text((x + dx, y + dy), text, font=font, fill=outline_color)
-        
-        # Draw main text
-        draw.text((x, y), text, font=font, fill=fill)
+
+        # Outline: every offset up to outline_width away on each axis, centre
+        # skipped, in the order this has always drawn them (OUTLINE_SQUARE at
+        # width 1). The main text is drawn last, on top.
+        offsets = [(dx, dy)
+                   for dx in range(-outline_width, outline_width + 1)
+                   for dy in range(-outline_width, outline_width + 1)
+                   if dx != 0 or dy != 0]
+        draw_text_outlined(draw, (x, y), text, font, fill, outline_color, offsets)
     
     def get_text_width(self, text: str, font: ImageFont.ImageFont) -> int:
         """

src/config_manager.py

@@ -451,8 +451,10 @@ class ConfigManager:
                 template_config = json.load(f)
             
             # Check if migration is needed
-            if self._config_needs_migration(self.config, template_config):
-                self.logger.info("Config migration needed - adding new configuration items with defaults")
+            needs_merge = self._config_needs_migration(self.config, template_config)
+            if needs_merge or self._live_in_ticker_needs_migration():
+                if needs_merge:
+                    self.logger.info("Config migration needed - adding new configuration items with defaults")
                 
                 # Create backup of current config
                 backup_path = f"{self.config_path}.backup"
@@ -461,7 +463,9 @@ class ConfigManager:
                 self.logger.info(f"Created backup of current config at {os.path.abspath(backup_path)}")
                 
                 # Merge template defaults into current config
-                self._merge_template_defaults(self.config, template_config)
+                if needs_merge:
+                    self._merge_template_defaults(self.config, template_config)
+                self._migrate_live_in_ticker_default()
                 
                 # save_config_atomic strips the merged secrets back out and
                 # keeps the file's owner and mode.
@@ -482,6 +486,44 @@ class ConfigManager:
             self.logger.error(f"Error during config migration: {e}")
             # Don't raise - continue with current config
 
+    #: Set in display.vegas_scroll once _migrate_live_in_ticker_default() has
+    #: run. Never in the template: the template merge would add it first, and
+    #: the flip would then never run.
+    LIVE_IN_TICKER_MARKER = 'live_in_ticker_migrated'
+
+    def _vegas_scroll_section(self) -> Optional[Dict[str, Any]]:
+        display = self.config.get('display')
+        vegas = display.get('vegas_scroll') if isinstance(display, dict) else None
+        return vegas if isinstance(vegas, dict) else None
+
+    def _live_in_ticker_needs_migration(self) -> bool:
+        vegas = self._vegas_scroll_section()
+        return vegas is not None and not vegas.get(self.LIVE_IN_TICKER_MARKER)
+
+    def _migrate_live_in_ticker_default(self) -> None:
+        """Turn on live_in_ticker for a config that only ever had the old default. Once.
+
+        LEDMatrix 3.8.0 makes ``display.vegas_scroll.live_in_ticker`` true:
+        live games stay in the Vegas ticker, their cards updating while they
+        scroll, instead of the ticker giving way to the full-screen
+        scoreboard. Every existing config holds an explicit ``false`` copied
+        from the template -- there was no control for it -- and the template
+        merge only adds missing keys, so the new default would reach nobody.
+        This rewrites that ``false`` once and marks the config, so a
+        ``false`` chosen afterwards (the Vegas checkbox, or by hand) stays.
+        """
+        vegas = self._vegas_scroll_section()
+        if vegas is None or vegas.get(self.LIVE_IN_TICKER_MARKER):
+            return
+        vegas[self.LIVE_IN_TICKER_MARKER] = True
+        if vegas.get('live_in_ticker') is False:
+            vegas['live_in_ticker'] = True
+            self.logger.info(
+                "Vegas mode now keeps live games in the ticker (the new default): "
+                "display.vegas_scroll.live_in_ticker turned on, once. Untick "
+                "\"Keep live games in the ticker\" under Vegas mode for the "
+                "full-screen scoreboard.")
+
     def _config_needs_migration(self, current_config: Dict[str, Any], template_config: Dict[str, Any]) -> bool:
         """Check if config needs migration by comparing with template."""
         return self._has_new_keys(current_config, template_config)

src/config_service.py

@@ -14,7 +14,7 @@ import json
 import time
 import threading
 from pathlib import Path
-from typing import Dict, Any, Optional, List, Callable
+from typing import Dict, Any, Optional, List, Callable, Tuple
 from collections import defaultdict
 import logging
 import hashlib
@@ -52,7 +52,18 @@ class ConfigService:
         
         # Thread safety
         self._lock: threading.RLock = threading.RLock()
-        
+        # Held across a whole reload -- read, swap, notify -- so one reload's
+        # notifications finish before the next one's start. Subscribers run
+        # under this lock and never under _lock: the display's per-plugin
+        # subscriber can wait seconds for a busy plugin, and get_config(),
+        # subscribe() and unsubscribe() -- called from the render thread --
+        # must not wait behind it.
+        self._notify_lock: threading.RLock = threading.RLock()
+        # (key, callback, thread id) of the callback a notification is running,
+        # so unsubscribe() can wait for that one call; signalled on its return.
+        self._running_callback: Optional[Tuple[str, Callable[..., None], int]] = None
+        self._callback_done = threading.Condition(self._lock)
+
         # Current configuration
         self._current_config: Dict[str, Any] = {}
         self._current_checksum: Optional[str] = None
@@ -87,32 +98,33 @@ class ConfigService:
             True if config changed, False otherwise
         """
         try:
-            new_config = self.config_manager.load_config()
-            new_checksum = self._calculate_checksum(new_config)
-            
-            with self._lock:
-                # Check if config actually changed
-                if new_checksum == self._current_checksum:
-                    self.logger.debug("Configuration unchanged, skipping reload")
-                    return False
-                
-                # Store old config for change detection
-                old_config = self._current_config.copy()
-                
-                # Update current config
-                self._current_config = new_config
-                self._current_checksum = new_checksum
-                
-                # Notify subscribers
+            with self._notify_lock:
+                new_config = self.config_manager.load_config()
+                new_checksum = self._calculate_checksum(new_config)
+
+                with self._lock:
+                    # Check if config actually changed
+                    if new_checksum == self._current_checksum:
+                        self.logger.debug("Configuration unchanged, skipping reload")
+                        return False
+
+                    # Store old config for change detection
+                    old_config = self._current_config.copy()
+
+                    # Update current config
+                    self._current_config = new_config
+                    self._current_checksum = new_checksum
+
+                # Notify subscribers, outside _lock (see _notify_lock)
                 self._notify_subscribers(old_config, new_config)
-                
+
                 self.logger.info(
                     "Configuration reloaded (checksum: %s)",
                     new_checksum[:8]
                 )
-                
+
                 return True
-                
+
         except ConfigError as e:
             self.logger.error("Error loading configuration: %s", e, exc_info=True)
             return False
@@ -127,35 +139,64 @@ class ConfigService:
         Args:
             old_config: Previous configuration
             new_config: New configuration
+
+        Called without _lock held. The subscriber lists are copied under it,
+        and each callback is checked against them again just before it runs.
         """
+        with self._lock:
+            subscribers = {key: list(callbacks) for key, callbacks in self._subscribers.items()}
+
         # Notify global subscribers (key: '*')
-        for callback in self._subscribers.get('*', []):
-            try:
-                callback(old_config, new_config)
-            except Exception as e:
-                self.logger.error("Error in global config change callback: %s", e, exc_info=True)
-        
+        for callback in subscribers.get('*', []):
+            self._call_subscriber('*', callback, old_config, new_config)
+
         # Notify plugin-specific subscribers
-        for plugin_id in self._subscribers.keys():
+        for plugin_id, callbacks in subscribers.items():
             if plugin_id == '*':
                 continue
-            
+
             old_plugin_config = old_config.get(plugin_id, {})
             new_plugin_config = new_config.get(plugin_id, {})
-            
+
             # Only notify if plugin config actually changed
             if old_plugin_config != new_plugin_config:
-                for callback in self._subscribers[plugin_id]:
-                    try:
-                        callback(old_plugin_config, new_plugin_config)
-                    except Exception as e:
-                        self.logger.error(
-                            "Error in config change callback for %s: %s",
-                            plugin_id,
-                            e,
-                            exc_info=True
-                        )
-    
+                for callback in callbacks:
+                    self._call_subscriber(plugin_id, callback,
+                                          old_plugin_config, new_plugin_config)
+
+    def _call_subscriber(
+        self,
+        key: str,
+        callback: Callable[[Dict[str, Any], Dict[str, Any]], None],
+        old_config: Dict[str, Any],
+        new_config: Dict[str, Any],
+    ) -> None:
+        """Run one callback, unless it was unsubscribed since the snapshot.
+
+        unsubscribe() promises that once it returns the callback is neither
+        running nor will run: the display unloads the plugin straight after.
+        """
+        with self._lock:
+            if callback not in self._subscribers.get(key, ()):
+                return
+            self._running_callback = (key, callback, threading.get_ident())
+        try:
+            callback(old_config, new_config)
+        except Exception as e:
+            if key == '*':
+                self.logger.error("Error in global config change callback: %s", e, exc_info=True)
+            else:
+                self.logger.error(
+                    "Error in config change callback for %s: %s",
+                    key,
+                    e,
+                    exc_info=True
+                )
+        finally:
+            with self._lock:
+                self._running_callback = None
+                self._callback_done.notify_all()
+
     def _check_file_changes(self) -> bool:
         """
         Check if configuration files have been modified.
@@ -276,6 +317,11 @@ class ConfigService:
         """
         Unsubscribe from configuration changes.
         
+        Once this returns the callback is not running and will not be called
+        again. A notification that is running this very callback is waited
+        for (unless the callback is the caller); one running any other
+        callback is not.
+
         Args:
             callback: Callback function to remove
             plugin_id: Optional plugin ID (must match subscription)
@@ -285,6 +331,10 @@ class ConfigService:
             if callback in self._subscribers[key]:
                 self._subscribers[key].remove(callback)
                 self.logger.debug("Unsubscribed from config changes for %s", key)
+            while (self._running_callback is not None
+                   and self._running_callback[:2] == (key, callback)
+                   and self._running_callback[2] != threading.get_ident()):
+                self._callback_done.wait()
     
     def shutdown(self) -> None:
         """Shutdown the configuration service."""

src/core_config_keys.py

@@ -29,6 +29,7 @@ CORE_CONFIG_KEYS = frozenset({
     'display',
     'sync',
     'plugin_system',
+    'fetch_service',
     # Older or optional core sections still found in existing config files.
     'logging',
     'network',
@@ -43,11 +44,14 @@ CORE_CONFIG_KEYS = frozenset({
 })
 
 #: Top-level keys of ``config_secrets.json`` that belong to the core rather than
-#: to a plugin: the GitHub token the Plugin Store reads, and the historical
-#: ``youtube`` section. Plugin secrets are namespaced by plugin id, so anything
-#: deciding whether a secrets section is a plugin's needs this as well as
-#: ``CORE_CONFIG_KEYS``.
+#: to a plugin: the GitHub token the Plugin Store reads, the historical
+#: ``youtube`` section, and ``web_auth`` (the optional web login's password
+#: hash and API-token hashes, web_interface/auth.py) -- which orphan-plugin
+#: cleanup would otherwise delete, logging everyone out. Plugin secrets are
+#: namespaced by plugin id, so anything deciding whether a secrets section is a
+#: plugin's needs this as well as ``CORE_CONFIG_KEYS``.
 CORE_SECRETS_KEYS = frozenset({
     'github',
     'youtube',
+    'web_auth',
 })

src/deprecation.py

@@ -6,6 +6,14 @@ still be called by a plugin nobody has checked. Such methods get
 process logs a warning naming the method and the release that removes it
 (visible in ``journalctl -u ledmatrix``), and emits a DeprecationWarning for
 tooling.
+
+Before a release removes anything, ``scripts/plugin_api_usage.py`` scans core,
+the official plugin monorepo and the registry's third-party plugins for callers
+and overriders of every marked method. Its latest output is
+``docs/DEPRECATIONS_3.8.md``; remove only what it reports unused, and move the
+rest to a later release. ``test/test_deprecation.py`` fails while any marker
+names a release at or below ``src.__version__``, so a release cannot ship with
+a removal date it has already passed.
 """
 
 import functools
@@ -45,3 +53,27 @@ def deprecated(removal: str, alternative: Optional[str] = None) -> Callable[[F],
         return wrapper  # type: ignore[return-value]
 
     return decorate
+
+
+def warn_deprecated(what: str, removal: str, alternative: Optional[str] = None,
+                    once_key: Optional[str] = None) -> bool:
+    """Warn that ``what`` will be removed in ``removal``, once per process.
+
+    For what ``@deprecated`` cannot decorate: a config key, a manifest field,
+    a value a hook returns. Same message, log line and DeprecationWarning as
+    the decorator. ``once_key`` (default: ``what``) is what "once" counts
+    against, so one deprecated key can warn once for each plugin that sets it.
+
+    Returns whether this call warned.
+    """
+    message = f"{what} is deprecated and will be removed in LEDMatrix {removal}"
+    if alternative:
+        message += f"; {alternative}"
+    key = once_key or what
+    with _warned_lock:
+        if key in _warned:
+            return False
+        _warned.add(key)
+    logger.warning(message)
+    warnings.warn(message, DeprecationWarning, stacklevel=2)
+    return True

src/display_arbiter.py

@@ -0,0 +1,185 @@
+"""What the panel shows next: the Arbiter of docs/RUN_LOOP_REDESIGN.md.
+
+``Arbiter.decide(state, inputs, now)`` takes a snapshot that
+``DisplayController.run()`` gathers once per pass and returns a
+:class:`ScreenPlan` naming the Source that gets the panel. It is a pure
+function: no I/O, no clock reads (``now`` is passed in), no locks, and it
+changes nothing it is given. That is what lets a plain table of cases test
+the priority order, which used to exist only as the order of ``if`` blocks
+in ``run()``.
+
+The full order is
+
+    ScheduledOff (a gate), Follower, OnDemand, Wifi, Live, Vegas, Rotation
+
+Stage 2 decides the gate, Follower and Wifi. Every other case returns a
+``LEGACY`` plan, meaning "carry on with run()'s existing code" (live
+priority, Vegas, then one rotation screen). OnDemand is in the order already
+because it outranks the WiFi notice: an active session is a ``LEGACY`` plan
+even when a notice is pending.
+
+The Wifi Source's mid-screen rule, :func:`wifi_notice_preempts`, lives here
+too, so both of its answers -- at the top of a pass and between frames --
+come from one module.
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional
+
+__all__ = [
+    "Arbiter",
+    "ArbiterInputs",
+    "ArbiterState",
+    "SCHEDULED_OFF_DWELL",
+    "ScreenPlan",
+    "Source",
+    "WIFI_NOTICE_DWELL",
+    "WifiNotice",
+    "wifi_notice_preempts",
+]
+
+# How long one scheduled-off pass blanks the panel. The dwell ends early when
+# on-demand starts or the schedule turns the panel back on.
+SCHEDULED_OFF_DWELL = 60.0
+
+# How long one WiFi-notice pass holds the notice before the next pass looks
+# again; the notice stays up, pass after pass, until it expires.
+WIFI_NOTICE_DWELL = 0.5
+
+
+class Source(Enum):
+    """Who gets the panel this pass."""
+
+    SCHEDULED_OFF = "scheduled-off"
+    FOLLOWER = "follower"
+    WIFI = "wifi"
+    # Not decided by the Arbiter yet: on-demand, live priority, Vegas and the
+    # rotation are still chosen by run()'s own code. Stage 3 adds the
+    # OnDemand, Live and Rotation Sources; stage 4 adds Vegas.
+    LEGACY = "legacy"
+
+
+@dataclass(frozen=True)
+class WifiNotice:
+    """A WiFi status message waiting to be drawn.
+
+    ``expires_at`` is wall-clock time (``time.time()``), as written by the
+    WiFi manager.
+    """
+
+    message: str
+    expires_at: float
+
+
+@dataclass(frozen=True)
+class ArbiterState:
+    """What the Arbiter remembers between passes.
+
+    Nothing yet: the stage-2 Sources decide from the inputs alone. The
+    on-demand index, the rotation index and the live resume point move here
+    with their Sources in stage 3.
+    """
+
+
+@dataclass(frozen=True)
+class ArbiterInputs:
+    """One pass's snapshot, gathered by run() before it calls decide().
+
+    Attributes:
+        schedule_on: The display schedule has the panel on, not counting an
+            on-demand override of a scheduled-off window.
+        on_demand_active: An on-demand session is running.
+        follower_active: A sync leader is driving this panel.
+        wifi_notice: The pending WiFi notice, or None. run() reads it only
+            when it could win (the panel is on, and neither a follower nor
+            on-demand outranks it), because reading it has side effects: a
+            1 Hz throttle and deleting an expired file.
+    """
+
+    schedule_on: bool
+    on_demand_active: bool
+    follower_active: bool
+    wifi_notice: Optional[WifiNotice] = None
+
+
+@dataclass(frozen=True)
+class ScreenPlan:
+    """The Arbiter's answer for one pass.
+
+    Attributes:
+        source: The Source that gets the panel.
+        max_duration: How long the plan holds the panel, in seconds, at most
+            (its dwell ends early when what the panel should show changes).
+            None when the Source paces itself: a follower frame, or LEGACY.
+        notice: The WiFi notice to draw, for a WIFI plan.
+    """
+
+    source: Source
+    max_duration: Optional[float] = None
+    notice: Optional[WifiNotice] = None
+
+
+SCHEDULED_OFF_PLAN = ScreenPlan(Source.SCHEDULED_OFF, max_duration=SCHEDULED_OFF_DWELL)
+FOLLOWER_PLAN = ScreenPlan(Source.FOLLOWER)
+LEGACY_PLAN = ScreenPlan(Source.LEGACY)
+
+
+class Arbiter:
+    """Decides which Source gets the panel. Stateless; see the module docstring."""
+
+    @staticmethod
+    def decide(state: ArbiterState, inputs: ArbiterInputs, now: float) -> ScreenPlan:
+        """The plan for this pass, from the Sources in priority order.
+
+        Args:
+            state: What the Arbiter remembers between passes (nothing yet).
+            inputs: This pass's snapshot.
+            now: Wall-clock time of the snapshot. No stage-2 Source reads it:
+                the top-of-pass WiFi check takes the notice as read, and only
+                the mid-screen check (:func:`wifi_notice_preempts`) compares
+                it with the expiry. It is in the signature for the Sources
+                stage 3 adds (on-demand expiry, durations).
+
+        Returns:
+            The winning Source's plan, or LEGACY_PLAN when the winner is one
+            run() still decides itself.
+        """
+        del state, now  # not read by the stage-2 Sources; see the docstring
+
+        # ScheduledOff is a gate, not a Source: a scheduled-off panel stays
+        # blank even for a follower, and only an on-demand session overrides
+        # it (#714 -- one ending in off hours blanks at the next pass).
+        if not inputs.schedule_on and not inputs.on_demand_active:
+            return SCHEDULED_OFF_PLAN
+
+        # 1. Follower: a sync leader drives this panel, ahead of on-demand.
+        if inputs.follower_active:
+            return FOLLOWER_PLAN
+
+        # 2. OnDemand: decided by run() until stage 3. It outranks the notice.
+        if inputs.on_demand_active:
+            return LEGACY_PLAN
+
+        # 3. Wifi: a pending notice, held for one short dwell per pass.
+        if inputs.wifi_notice is not None:
+            return ScreenPlan(Source.WIFI, max_duration=WIFI_NOTICE_DWELL,
+                              notice=inputs.wifi_notice)
+
+        # 4-6. Live, Vegas, Rotation: still run()'s own code.
+        return LEGACY_PLAN
+
+
+def wifi_notice_preempts(notice: Optional[WifiNotice], on_demand_active: bool,
+                         now: float) -> bool:
+    """Whether a WiFi notice should end the current screen early.
+
+    The Wifi Source's mid-screen rule, polled between frames, during dwells
+    and when a Vegas iteration yields. On-demand outranks the notice, as in
+    :meth:`Arbiter.decide`. Unlike the top-of-pass check it also compares
+    ``now`` with the expiry, because the 1 Hz read throttle can hand back a
+    notice that has expired since it was read.
+    """
+    if on_demand_active or notice is None:
+        return False
+    return now < notice.expires_at