Merge main into claude/on-demand-error-clears-session

CodeQL had ~40 open py/stack-trace-exposure alerts on main. Almost all
flowed through describe_exception(), which returned "TypeName: message"
(redacted, capped); the rest through _run_systemctl_command's str(err),
WiFiManager's `return False, str(e)`, unit_refresh's f-strings and two
str(e)/f"{err}" messages in api_v3/__init__.py.

describe_exception() now returns a reason code -- the type, plus the
errno symbol for an OSError ("OSError:EIO", "PermissionError:EACCES") --
and logs the redacted message itself. That keeps what #538 wanted (a
failing disk still says EIO in the response) without quoting paths,
URLs or library internals, and fixes every call site at once; the
test_no_api_v3_handler_discards_its_exception policy still holds.

Service results: _get_display_service_status returns active/returncode
only, and the on-demand start/stop `service` result keeps
returncode/active/started/status but drops systemctl stdout/stderr
(logged on failure). Nothing in web_interface/static, the templates or
the MQTT bridge reads those fields. The Starlark SIGKILL-restart error
no longer returns systemctl stderr as `details`.

WiFi, unit-refresh, config-save and plugin-removal failures now say
what failed with the reason code and point at the log. display.py is
untouched (draft #773 edits it).

Tests: test_api_v3_no_exception_text.py drives one route per affected
file with a marker in the exception message and asserts it never
reaches the body; all 13 fail on origin/main, and targeted mutations
(drop the service filter, put stderr back, str(e) in WiFiManager,
{e} in unit_refresh, {install_err} in system.py, message back in
describe_exception) each fail at least one. Tests that asserted the old
message-in-details contract now assert the reason code.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

.codacy.yml

@@ -4,4 +4,3 @@ exclude_paths:
   - "plugins/**"
   - "assets/**"
   - "test/**"
-  - "scripts/debug/**"

.gitattributes

@@ -1,2 +1,15 @@
 # Auto detect text files and perform LF normalization
 * text=auto
+
+# Files the Pi executes must stay LF even in a Windows checkout with
+# core.autocrlf=true: a CRLF shebang line fails with "bad interpreter",
+# 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/claude-code-review.yml

@@ -3,21 +3,13 @@ name: Claude Code Review
 on:
   pull_request:
     types: [opened, synchronize, ready_for_review, reopened]
-    # Optional: Only run on specific file changes
-    # paths:
-    #   - "src/**/*.ts"
-    #   - "src/**/*.tsx"
-    #   - "src/**/*.js"
-    #   - "src/**/*.jsx"
 
 jobs:
   claude-review:
-    # Optional: Filter by PR author
-    # if: |
-    #   github.event.pull_request.user.login == 'external-contributor' ||
-    #   github.event.pull_request.user.login == 'new-developer' ||
-    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
-
+    # Pull requests from forks get no repository secrets, so without this
+    # guard every outside contributor's PR showed this check red for a reason
+    # they can't fix. Skipped checks don't block merging.
+    if: github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -27,13 +19,13 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
           fetch-depth: 1
 
       - name: Run Claude Code Review
         id: claude-review
-        uses: anthropics/claude-code-action@v1
+        uses: anthropics/claude-code-action@756cc22e19660d20e8cc9496b4f242475a7f7790 # v1
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           # Review PRs opened by the Claude GitHub App. Without this the action
@@ -45,6 +37,4 @@ jobs:
           plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
           plugins: 'code-review@claude-code-plugins'
           prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
-          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
-          # or https://code.claude.com/docs/en/cli-reference for available options
 

.github/workflows/claude.yml

@@ -26,13 +26,13 @@ jobs:
       actions: read # Required for Claude to read CI results on PRs
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
           fetch-depth: 1
 
       - name: Run Claude Code
         id: claude
-        uses: anthropics/claude-code-action@v1
+        uses: anthropics/claude-code-action@756cc22e19660d20e8cc9496b4f242475a7f7790 # v1
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
 
@@ -40,11 +40,3 @@ jobs:
           additional_permissions: |
             actions: read
 
-          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
-          # prompt: 'Update the pull request description to include a summary of changes.'
-
-          # Optional: Add claude_args to customize behavior and configuration
-          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
-          # or https://code.claude.com/docs/en/cli-reference for available options
-          # claude_args: '--allowed-tools Bash(gh pr *)'
-

.github/workflows/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

@@ -8,14 +8,20 @@ on:
   # needs a re-run or didn't get created.
   workflow_dispatch:
 
-# Both jobs only check out the repo and run pytest.
+# The jobs only check out the repo and run the tests.
 permissions:
   contents: read
 
 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,13 +35,13 @@ jobs:
 
       - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
         with:
-          python-version: "3.12"
+          python-version: ${{ matrix.python-version }}
           cache: pip
 
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -r requirements.txt -r requirements-test.txt
+          pip install -r requirements.txt -r web_interface/requirements.txt -r requirements-test.txt
           pip install RGBMatrixEmulator
 
       - name: Run plugin safety harness
@@ -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,13 +63,13 @@ jobs:
 
       - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
         with:
-          python-version: "3.12"
+          python-version: ${{ matrix.python-version }}
           cache: pip
 
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -r requirements.txt -r requirements-test.txt
+          pip install -r requirements.txt -r web_interface/requirements.txt -r requirements-test.txt
           pip install RGBMatrixEmulator
 
       # Run the ENTIRE test tree (except test/plugins, which the
@@ -73,3 +84,125 @@ jobs:
             --cov=src --cov=web_interface \
             --cov-report=term \
             --cov-fail-under=52
+
+  js-tests:
+    name: Web UI JS tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
+        with:
+          python-version: "3.13"
+          cache: pip
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: "22"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt -r web_interface/requirements.txt
+          npm install --no-audit --no-fund --prefix test/js
+
+      # The DOM suites test the real server-rendered pages and API, so they
+      # need the web interface running. REQUIRE_DOM turns "couldn't reach it"
+      # into a failure instead of a silent skip.
+      - name: Start the web interface
+        run: |
+          EMULATOR=true python -c "from web_interface.app import app; app.run(host='127.0.0.1', port=5000, threaded=True)" > web.log 2>&1 &
+          for i in $(seq 60); do curl -sf -o /dev/null http://127.0.0.1:5000/ && exit 0; sleep 1; done
+          cat web.log
+          exit 1
+
+      - name: Run JS suites
+        env:
+          BASE: http://127.0.0.1:5000
+          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
+    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"
+          cache: pip
+
+      # The runtime requirements are installed so mypy sees the real types of
+      # PIL, requests, psutil and friends -- missing, they'd be Any and the
+      # result would differ from a developer's machine. mypy and the stubs are
+      # pinned so a new release can't turn this red without a code change.
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt -r web_interface/requirements.txt
+          pip install mypy==1.20.2 types-requests==2.33.0.20260906 types-pytz==2026.4.0.20260926
+
+      # mypy on exactly the modules in mypy-clean.txt; fails on any error in
+      # 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

.gitignore

@@ -3,15 +3,13 @@ __pycache__/
 *.py[cod]
 *$py.class
 
-# Secrets
-config/config_secrets.json
-# Atomic writes leave these behind when a save or a test is interrupted;
-# the suite drops several per run.
-config/.config_secrets.json.tmp.*
-config/config.json
-config/config.json.backup
-config/wifi_config.json
-config/uninstalled_plugins.json
+# Secrets and per-device state. Everything the software writes into config/
+# is local to one device -- config.json, config_secrets.json, wifi_config.json,
+# ytm_auth.json (a login session), saved_repositories.json, font_overrides.json,
+# and the temp files atomic writes leave behind when interrupted -- so only
+# the templates are tracked. Listing files one by one missed several.
+config/*
+!config/*.template.json
 credentials.json
 token.pickle
 
@@ -81,10 +79,10 @@ assets/stocks/crypto_icons/
 
 # Plugin operation state written at runtime.
 #
-# web_interface/app.py writes data/plugin_operations.json, data/plugin_state.json
-# and data/operation_history.json as the web interface runs, into a directory that
-# ships tracked (data/.gitkeep) and was otherwise unignored. So every rig that ever
-# opened the web UI -- and every test run that constructs the app -- left three
+# web_interface/app.py writes data/plugin_state.json and data/operation_history.json
+# (older releases also data/plugin_operations.json) as the web interface runs, into
+# a directory that ships tracked (data/.gitkeep). Unignored, every rig that ever
+# opened the web UI -- and every test run that constructs the app -- would leave
 # untracked files behind and a permanently dirty `git status`. Same reasoning as
 # the logo rule above: a checkout that is always dirty is a checkout nobody reads.
 data/*

.pre-commit-config.yaml

@@ -37,14 +37,22 @@ repos:
         types: [python]
         pass_filenames: false
 
-  - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.8.0
+  # The mypy ratchet -- the same check as CI's "Type check (mypy ratchet)"
+  # job: mypy on exactly the modules listed in mypy-clean.txt. Run it with
+  #   pre-commit run mypy --hook-stage manual
+  # A local hook rather than mirrors-mypy so mypy sees the packages installed
+  # from requirements.txt, as CI does; an isolated hook env without them types
+  # PIL, requests and friends as Any and reports different errors. Needs
+  # mypy==1.20.2 (the version CI pins) in the environment you commit from.
+  - repo: local
     hooks:
       - id: mypy
-        additional_dependencies: [types-requests, types-pytz]
-        args: [--ignore-missing-imports, --no-error-summary]
+        name: mypy (ratchet, mypy-clean.txt)
+        entry: python scripts/check_types.py
+        language: system
         pass_filenames: false
-        files: ^src/
+        always_run: true
+        stages: [manual]
 
   - repo: https://github.com/PyCQA/bandit
     rev: 1.8.3

CLAUDE.md

@@ -13,14 +13,17 @@
   loader does NOT fall back to it — `PluginManager.discover_plugins()`
   (`src/plugin_system/plugin_manager.py`) scans only the configured
   directory. Fallbacks exist in two narrower places: store operations
-  (`StoreManager._find_plugin_path()` in `store_manager.py`) and schema
-  lookup (`SchemaManager.get_schema_path()` in `schema_manager.py`,
-  which probes `plugins/` *before* `plugin-repos/`).
+  (`PluginStoreManager._find_plugin_path()` in `store_manager.py`, which
+  searches `store_search_dirs()` from `plugin_dirs.py`) and schema lookup
+  (`SchemaManager.get_schema_path()` in `schema_manager.py`, which probes
+  `plugins/` *before* `plugin-repos/`).
+- `src/plugin_system/plugin_dirs.py` — the one resolver for "which directory
+  holds plugin X" (manifest `id` first, then `<id>` / `ledmatrix-<id>`)
 
 ## Plugin System
 - Plugins inherit from `BasePlugin` in `src/plugin_system/base_plugin.py`
 - Required abstract methods: `update()`, `display(force_clear=False)`
-- Each plugin needs: `manifest.json`, `config_schema.json`, `manager.py`, `requirements.txt`
+- Each plugin needs: `manifest.json`, `config_schema.json`, and the entry point (`manager.py` by default); `requirements.txt` if it has dependencies. Required manifest fields: `docs/PLUGIN_API_REFERENCE.md#manifest-required-fields`
 - Plugin instantiation args: `plugin_id, config, display_manager, cache_manager, plugin_manager`
 - Config schemas use JSON Schema Draft-7
 - Display dimensions: always read dynamically from `self.display_manager.width/height` — not `display_manager.matrix.width/height`, because `matrix` is `None` when hardware init fails (the properties fall back to the canvas size)
@@ -34,19 +37,21 @@
 - Browser preview without the display loop: `python3 scripts/dev_server.py` → http://localhost:5001
 - Full display in emulator mode: `python3 run.py -e` (or `EMULATOR=true python3 run.py`)
 - Validate one plugin headlessly: `python3 scripts/check_plugin.py --plugin <id>`
+- Soak a rig for frame timing (on the Pi, service running): `python3 scripts/frame_soak.py --preview` — late-frame rate across every scroller; see `docs/SCROLL_PERFORMANCE.md`
 
 ## Plugin Store Architecture
 - Official plugins live in the `ledmatrix-plugins` monorepo (not individual repos)
 - Plugin repo naming convention: `ledmatrix-<plugin-id>` (e.g., `ledmatrix-football-scoreboard`)
 - `plugins.json` registry at `https://raw.githubusercontent.com/ChuckBuilds/ledmatrix-plugins/main/plugins.json`
-- Store manager (`src/plugin_system/store_manager.py`) handles install/update/uninstall
-- Monorepo plugins are installed via ZIP extraction (no `.git` directory)
+- 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`
 
 ## Common Pitfalls
-- paho-mqtt 2.x needs `callback_api_version=mqtt.CallbackAPIVersion.VERSION1` for v1 compat
+- paho-mqtt 2.x requires a `CallbackAPIVersion` argument: `VERSION1` for code written against v1 callback signatures (the MQTT bridge uses `VERSION2`)
 - BasePlugin uses `get_logger()` from `src.logging_config`, not standard `logging.getLogger()`
 - `DisplayManager` has no `draw_image()` — paste onto the PIL image directly:
   `self.display_manager.image.paste(img, (x, y))` then `update_display()`

CODE_OF_CONDUCT.md

@@ -63,7 +63,7 @@ ChuckBuilds, and any other forums hosted by or affiliated with the project.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement on the
-[LEDMatrix Discord](https://discord.gg/uW36dVAtcT) (DM a moderator or
+[LEDMatrix Discord](https://discord.gg/RdrC37rEag) (DM a moderator or
 ChuckBuilds directly) or by opening a private GitHub Security Advisory if
 the issue involves account safety. All complaints will be reviewed and
 investigated promptly and fairly.

CONTRIBUTING.md

@@ -9,7 +9,7 @@ improvements, and code changes.
 - **Bugs / feature requests**: open an issue using one of the templates
   in [`.github/ISSUE_TEMPLATE/`](.github/ISSUE_TEMPLATE/).
 - **Real-time discussion**: the
-  [LEDMatrix Discord](https://discord.gg/uW36dVAtcT).
+  [LEDMatrix Discord](https://discord.gg/RdrC37rEag).
 - **Plugin development**:
   [`docs/PLUGIN_DEVELOPMENT_GUIDE.md`](docs/PLUGIN_DEVELOPMENT_GUIDE.md)
   and the [`ledmatrix-plugins`](https://github.com/ChuckBuilds/ledmatrix-plugins)
@@ -58,12 +58,24 @@ integration tests.
 3. **Keep PRs focused.** One conceptual change per PR. If you find
    adjacent bugs while working, fix them in a separate PR.
 4. **Follow the existing code style.** The pre-commit hooks run
-   `flake8` (E9, F63, F7, F82 plus bugbear `B` checks), `mypy` on
-   `src/`, `bandit`, and `gitleaks` — install the CLI with
+   `flake8` (E9, F63, F7, F82 plus bugbear `B` checks), `bandit`,
+   and `gitleaks` — install the CLI with
    `python -m pip install pre-commit`, then run
-   `pre-commit install` so they run on every commit; HTML/JS in
+   `pre-commit install` so they run on every commit. Type checking
+   is a ratchet while the existing mypy errors in `src/` are paid
+   down: `mypy-clean.txt` lists the modules that type-check clean, and
+   CI runs `python scripts/check_types.py` (also the manual hook
+   `pre-commit run mypy --hook-stage manual`) to keep every listed
+   module clean. When you make another module clean, add it to the
+   list (sorted); don't take one off to get CI green. Keep type fixes
+   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

@@ -33,7 +33,7 @@ I'm trying to be open to constructive criticism and support, as long as it's a r
 - Show support on Youtube: https://www.youtube.com/@ChuckBuilds
 - Check out the write-up on my website: https://www.chuck-builds.com/led-matrix/
 - Stay in touch on Instagram: https://www.instagram.com/ChuckBuilds/
-- Want to chat? Reach out on the LEDMatrix Discord: [https://discord.com/invite/uW36dVAtcT](https://discord.gg/dfFwsasa6W)
+- Want to chat? Reach out on the LEDMatrix Discord: [https://discord.gg/RdrC37rEag](https://discord.gg/RdrC37rEag)
 - Feeling Generous? Consider sponsoring this project or sending a donation (these AI credits aren't cheap!)          
 
 -----------------------------------------------------------------------------------
@@ -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" />
 
@@ -328,6 +333,7 @@ This one-shot installer will automatically:
 - Install required system packages (git, python3, build tools, etc.)
 - Clone or update the LEDMatrix repository
 - Run the complete first-time installation script
+- Print the web interface address, then **reboot the Pi automatically** (your SSH session will disconnect; give it a few minutes to come back)
 
 The installation process typically takes 10-30 minutes depending on your internet connection and Pi model. Pi 3B/3B+ and other 1GB boards land at the top of that range, because the C++ library is compiled serially to stay within available memory. All errors are reported explicitly with actionable fixes.
 
@@ -689,9 +695,10 @@ Controls how long each installed plugin stays visible in seconds before switchin
 ### Display Format Settings
 
 - **`use_short_date_format`** (boolean, default: true)
-  - Use short date format (e.g., "Jan 15") instead of long format (e.g., "January 15th")
-  - Set to `false` for longer, more readable dates
-  - Set to `true` to save space and show more information
+  - Currently has no effect. The web UI still saves it, but no core code
+    reads it. Scoreboard plugins that offer a short date format read the
+    setting from their own plugin config instead. See
+    [CONFIG_REFERENCE.md](docs/CONFIG_REFERENCE.md#display--other-keys).
 
 ### Dynamic Duration Settings (`display.dynamic_duration`)
 
@@ -779,15 +786,21 @@ Controls how long each installed plugin stays visible in seconds before switchin
 <details>
 <summary>Manual SSH Commands (for reference)</summary>
 
-The quick actions essentially just execute the following commands on the Pi.
+The web interface's quick actions (Start/Stop/Restart Display) call
+`sudo systemctl start|stop|restart ledmatrix.service` — see
+`execute_system_action()` in
+[`web_interface/blueprints/api_v3/system.py`](web_interface/blueprints/api_v3/system.py).
+The service runs [`run.py`](run.py) as root.
 
-From the project root directory (ex: /home/ledpi/LEDMatrix):
+To run the display in the foreground instead (for debugging), stop the service
+first, then from the project root (e.g. `/home/ledpi/LEDMatrix`):
 
 ```bash
-sudo python3 display_controller.py
+sudo systemctl stop ledmatrix.service
+sudo python3 run.py          # add -d for debug logging
 ```
 
-This will start the display cycle but only stays active as long as your ssh session is active.
+This only runs as long as your SSH session stays open.
 
 ### Convenience Scripts
 
@@ -940,7 +953,7 @@ sudo systemctl enable ledmatrix-web.service
 - **On-Demand Controls**: Start specific displays (weather, stocks, sports) on demand
 - **Service Management**: Start/stop the main display service
 - **System Controls**: Restart, update code, and manage the system
-- **API Metrics**: Monitor API usage and system performance
+- **System Stats**: CPU, memory and temperature on the Overview tab
 - **Logs**: View system logs in real-time
 
 ### Troubleshooting Web Interface
@@ -957,9 +970,10 @@ sudo systemctl enable ledmatrix-web.service
 3. Check if another service is using port 5000
 
 **Service Fails to Start:**
-1. Check Python dependencies are installed
-2. Verify the virtual environment is set up correctly
-3. Check file permissions and ownership
+1. Check Python dependencies are installed. The installer puts them in the
+   system Python with `pip install --break-system-packages` (there is no
+   virtual environment), so `python3 -c "import flask"` should succeed.
+2. Check file permissions and ownership
 
 </details>
 

SECURITY.md

@@ -16,7 +16,7 @@ Use one of these channels, in order of preference:
    maintainer.
    - Direct link: <https://github.com/ChuckBuilds/LEDMatrix/security/advisories/new>
 2. **Discord DM**. Send a direct message to a moderator on the
-   [LEDMatrix Discord](https://discord.gg/uW36dVAtcT). Don't post in
+   [LEDMatrix Discord](https://discord.gg/RdrC37rEag). Don't post in
    public channels.
 
 Please include:
@@ -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

display_controller.py

@@ -1,12 +1,20 @@
 #!/usr/bin/env python3
+"""Legacy entry point: runs ``run.py``, which is the one to use.
+
+``python3 run.py`` (``-e`` for the emulator, ``-d`` for debug logging) is how
+the display service and the docs start LEDMatrix. This file used to import
+``src.display_controller.main`` directly, which skipped what run.py sets up
+first -- ``sys.dont_write_bytecode`` (root-owned ``__pycache__`` in plugin
+directories blocks the web service from updating them), the ``-e``/``-d``
+flags, and the logging configuration. It now runs run.py exactly as
+``python3 run.py`` would, with the same arguments.
+"""
 
 import os
-import sys
-
-# Add the project root directory to Python path
-sys.path.append(os.path.dirname(os.path.abspath(__file__)))
-
-from src.display_controller import main
+import runpy
 
 if __name__ == "__main__":
-    main() 
+    runpy.run_path(
+        os.path.join(os.path.dirname(os.path.abspath(__file__)), "run.py"),
+        run_name="__main__",
+    )

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,81 +193,80 @@ 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. The reference is
+[PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md#vegas-scroll-hooks).
+
 **1. Implement Content Method:**
 
 ```python
 def get_vegas_content(self):
-    """
-    Return PIL Image or list of Images for Vegas mode.
-
-    Returns:
-        PIL.Image or list[PIL.Image]: Content to display
-        - Single image: fixed-width content
-        - List of images: multiple segments
-        - None: skip this cycle
-    """
-    # Example: Return single wide image
-    img = Image.new('RGB', (256, 32))
-    # ... render your content ...
-    return img
-
-    # Example: Return multiple segments
-    return [image1, image2, image3]
+    # Return a PIL Image, a list of Images, or None.
+    # A single image is one block; a list becomes one item per image.
+    return [self._render_game(game) for game in self.games]
 ```
 
-**2. Specify Content Type:**
+If it returns `None` (the default), Vegas falls back to the plugin's
+`scroll_helper` image, then to capturing `display()` output
+(`PluginAdapter.get_content()` in
+[`src/vegas_mode/plugin_adapter.py`](../src/vegas_mode/plugin_adapter.py)).
+
+**2. Declare how the plugin takes part:**
+
+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"
+}
+```
+
+The user's own `vegas_participation` setting overrides the manifest. When
+the answer depends on state, override the method instead:
 
 ```python
-def get_vegas_content_type(self):
-    """
-    Specify how content should be handled.
-
-    Returns:
-        str: 'multi' | 'static' | 'none'
-    """
-    return 'multi'  # Default for most plugins
+def get_vegas_participation(self):
+    # 'scroll' | 'pause' | 'exclude'
+    return 'pause' if self._alert_is_live() else 'scroll'
 ```
 
-**3. Optionally Specify Display Mode:**
-
-```python
-def get_vegas_display_mode(self):
-    """
-    Preferred display mode for this plugin.
-
-    Returns:
-        str: 'scroll' | 'fixed' | 'static'
-    """
-    return 'scroll'
-
-def get_supported_vegas_modes(self):
-    """
-    List of supported modes.
-
-    Returns:
-        list: ['scroll', 'fixed', 'static']
-    """
-    return ['scroll', 'static']
-```
+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
@@ -299,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:
@@ -392,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
 
@@ -401,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
@@ -518,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.
 
@@ -643,7 +649,9 @@ When nothing is running on demand, `data.state` is
 > on-demand machinery is internal — drive it through the REST endpoints
 > above (or the web UI buttons). The API handlers
 > (`start_on_demand_display()` / `stop_on_demand_display()` in
-> `web_interface/blueprints/api_v3/display.py`) write a request into the cache
+> `web_interface/blueprints/api_v3/display.py`) send the request over the
+> display's control socket ([IPC_CONTROL_SOCKET.md](IPC_CONTROL_SOCKET.md)).
+> Only when the socket cannot carry it do they write it into the cache
 > manager under the `display_on_demand_request` key, which
 > `DisplayController._poll_on_demand_requests()`
 > (`src/display_controller.py`) picks up. A separate
@@ -741,8 +749,14 @@ keys helps troubleshoot stuck states.
   "timestamp": 1234567890.123
 }
 ```
-**Purpose:** Communication from web interface to display controller
-**When Set:** API endpoint receives request
+**Purpose:** Communication from web interface to display controller, as the
+fallback when the control socket cannot carry the request (deprecated; it
+will be removed in a later release)
+**When Set:** API endpoint receives a request and the display's control
+socket is unavailable (display stopped, or older than the socket or the
+command); some plugins also write it directly
+**Read:** once a second while the display serves the control socket (0.25 s
+without it), and only when the file changed since the last look
 **Auto-Cleared:** After processing or 1 hour TTL
 
 **2. display_on_demand_config** (No TTL)
@@ -966,11 +980,16 @@ from src.cache_manager import CacheManager
 
 service = get_background_service(CacheManager())
 stats = service.get_statistics()
-print(f"Active tasks: {stats['active_tasks']}")
-print(f"Completed: {stats['completed']}")
-print(f"Failed: {stats['failed']}")
+print(f"Active: {stats['active_requests']}")
+print(f"Completed: {stats['completed_requests']}")
+print(f"Failed: {stats['failed_requests']}")
 ```
 
+Other keys: `total_requests`, `cached_hits`, `cache_misses`,
+`average_fetch_time`, `completed_requests_count` (results currently held in
+memory) — see `BackgroundDataService.get_statistics()` in
+[`src/background_data_service.py`](../src/background_data_service.py).
+
 **Enable Debug Logging:**
 ```python
 import logging
@@ -981,6 +1000,10 @@ logging.getLogger('src.background_data_service').setLevel(logging.DEBUG)
 
 ## 5. Permission Management
 
+Ownership, modes, sudo rules and the repair scripts are listed in
+[PERMISSIONS.md](PERMISSIONS.md). This section covers the helpers code uses
+to keep files shareable.
+
 ### Overview
 
 LEDMatrix uses a dual-user architecture: the display service runs as root (hardware access), while the web interface runs as a non-privileged user. Centralized permission management ensures both can access necessary files.
@@ -1044,7 +1067,7 @@ ensure_file_permissions(config_path, get_config_file_mode(config_path))
 | Config (secrets) | `rw-r-----` | `0o640` | Owner write, group read |
 | Assets | `rw-rw-r--` | `0o664` | Owner/group write, all read |
 | Plugins | `rw-rw-r--` | `0o664` | Owner/group write, all read |
-| Cache files | `rw-rw-r--` | `0o664` | Owner/group write, all read |
+| Cache files | `rw-rw----` | `0o660` | Owner/group write, no world access (`_CACHE_FILE_MODE` in `src/cache/disk_cache.py`) |
 
 **Directory Permissions:**
 
@@ -1115,40 +1138,22 @@ These core utilities **already handle permissions** - you don't need to call per
 
 ### Manual Fixes
 
-If you encounter permission issues:
+[PERMISSIONS.md](PERMISSIONS.md) lists who owns what on an installed system,
+the expected modes, and which `scripts/fix_perms/` script to run as which
+user. In short:
 
-```bash
-# Targeted permission fixes (see scripts/fix_perms/README.md)
-sudo ./scripts/fix_perms/fix_assets_permissions.sh   # assets/ tree (logos, fonts)
-sudo ./scripts/fix_perms/fix_cache_permissions.sh    # all cache directories
-sudo ./scripts/fix_perms/fix_plugin_permissions.sh   # plugin directories
-sudo ./scripts/fix_perms/fix_web_permissions.sh      # web interface files
+- `fix_assets_permissions.sh`, `fix_cache_permissions.sh` and
+  `fix_plugin_permissions.sh` are run with `sudo`.
+- `fix_web_permissions.sh` is run as the web interface user, without
+  `sudo` (it refuses to run as root and calls `sudo` itself where needed).
+  It resets project file ownership for that user, then makes the two
+  helper scripts the web user may run as root (`safe_plugin_rm.sh`,
+  `safe_pip_install.sh`) root-owned again and restores `config_secrets.json`
+  to its owner, the `ledmatrix` group and mode `640`. It does not write
+  sudoers rules; `scripts/install/configure_web_sudo.sh` does that.
 
-# Fix specific directory
-sudo chown -R ledpi:ledpi /home/ledpi/LEDMatrix/config
-sudo chmod -R 2775 /home/ledpi/LEDMatrix/config
-sudo find /home/ledpi/LEDMatrix/config -type f -exec chmod 664 {} \;
-
-# Verify permissions
-ls -la config/
-ls -la assets/
-```
-
-### Verification
-
-```bash
-# Check directory has setgid bit
-ls -ld assets/
-# Should show: drwxrwsr-x (note the 's')
-
-# Check file has correct group
-ls -l assets/logo.png
-# Should show group 'ledpi'
-
-# Check file permissions
-stat -c "%a %n" config/config.json
-# Should show: 644 config/config.json
-```
+Do not `chmod` the whole `config/` directory: `config_secrets.json` must stay
+`640`.
 
 ---
 

docs/ADVANCED_PLUGIN_DEVELOPMENT.md

@@ -13,7 +13,7 @@ Advanced patterns, examples, and best practices for developing LEDMatrix plugins
 - [Using Weather Icons](#using-weather-icons)
 - [Implementing Scrolling with Deferred Updates](#implementing-scrolling-with-deferred-updates)
 - [Cache Strategy Patterns](#cache-strategy-patterns)
-- [Font Management and Overrides](#font-management-and-overrides)
+- [Font Management](#font-management)
 - [Error Handling Best Practices](#error-handling-best-practices)
 - [Performance Optimization](#performance-optimization)
 - [Testing Plugins with Mocks](#testing-plugins-with-mocks)
@@ -25,69 +25,12 @@ Advanced patterns, examples, and best practices for developing LEDMatrix plugins
 
 ## Using Weather Icons
 
-The Display Manager provides built-in weather icon drawing methods for easy visual representation of weather conditions.
-
-### Basic Weather Icon Usage
-
-```python
-def display(self, force_clear=False):
-    if force_clear:
-        self.display_manager.clear()
-    
-    # Draw weather icon based on condition
-    condition = self.data.get('condition', 'clear')
-    self.display_manager.draw_weather_icon(condition, x=5, y=5, size=16)
-    
-    # Draw temperature next to icon
-    temp = self.data.get('temp', 72)
-    self.display_manager.draw_text(
-        f"{temp}°F",
-        x=25, y=10,
-        color=(255, 255, 255)
-    )
-    
-    self.display_manager.update_display()
-```
-
-### Supported Weather Conditions
-
-The `draw_weather_icon()` method automatically maps condition strings to appropriate icons:
-
-- `"clear"`, `"sunny"` → Sun icon
-- `"clouds"`, `"cloudy"`, `"partly cloudy"` → Cloud icon
-- `"rain"`, `"drizzle"`, `"shower"` → Rain icon
-- `"snow"`, `"sleet"`, `"hail"` → Snow icon
-- `"thunderstorm"`, `"storm"` → Storm icon
-
-### Custom Weather Icons
-
-For more control, use individual icon methods:
-
-```python
-# Draw specific icons
-self.display_manager.draw_sun(x=10, y=10, size=16)
-self.display_manager.draw_cloud(x=10, y=10, size=16, color=(150, 150, 150))
-self.display_manager.draw_rain(x=10, y=10, size=16)
-self.display_manager.draw_snow(x=10, y=10, size=16)
-```
-
-### Text with Weather Icons
-
-Use `draw_text_with_icons()` to combine text and icons:
-
-```python
-icons = [
-    ("sun", 5, 5),      # Sun icon at (5, 5)
-    ("cloud", 100, 5)   # Cloud icon at (100, 5)
-]
-
-self.display_manager.draw_text_with_icons(
-    "Weather: Sunny, Cloudy",
-    icons=icons,
-    x=10, y=20,
-    color=(255, 255, 255)
-)
-```
+The Display Manager's icon methods — `draw_weather_icon()`, `draw_sun()`,
+`draw_cloud()`, `draw_rain()`, `draw_snow()` and `draw_text_with_icons()` —
+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).
 
 ---
 
@@ -251,11 +194,8 @@ def update(self):
     sport_key = "nhl"
     cache_key = f"{self.plugin_id}_{sport_key}_games"
     
-    # Uses sport-specific live_update_interval from config
-    cached = self.cache_manager.get_background_cached_data(
-        cache_key,
-        sport_key=sport_key
-    )
+    # get_background_cached_data() was removed in 3.8.0 — use get()
+    cached = self.cache_manager.get(cache_key, max_age=60)
     
     if cached:
         self.games = cached
@@ -282,9 +222,9 @@ def on_config_change(self, new_config):
 
 ---
 
-## Font Management and Overrides
+## Font Management
 
-Use the Font Manager for advanced font handling and user customization.
+The display manager's built-in fonts and text measurement. For fonts shipped with a plugin, see [FONT_MANAGER.md](FONT_MANAGER.md).
 
 ### Using Different Fonts
 
@@ -656,14 +596,12 @@ def update(self):
 
 ```python
 def update(self):
-    # Check if another plugin is enabled
-    enabled_plugins = self.plugin_manager.get_enabled_plugins()
-    if "weather" in enabled_plugins:
-        # Weather plugin is available
-        weather_plugin = self.plugin_manager.get_plugin("weather")
-        if weather_plugin:
-            # Use weather data
-            pass
+    # 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
+        pass
 ```
 
 ### Sharing Data Between Plugins

docs/ARCHITECTURE.md

@@ -0,0 +1,416 @@
+# Architecture
+
+A map of the codebase for a new contributor: which process does what, how
+they talk to each other, and where to start reading for common changes.
+
+## Processes
+
+| systemd unit | Runs as | Runs | Installed by |
+|---|---|---|---|
+| `ledmatrix.service` | root | [`run.py`](../run.py) → `DisplayController` | [`install_service.sh`](../scripts/install/install_service.sh) |
+| `ledmatrix-web.service` | the installing user | [`start_web_conditionally.py`](../scripts/utils/start_web_conditionally.py) → [`web_interface/start.py`](../web_interface/start.py) (Flask, port 5000) | `install_service.sh`, [`install_web_service.sh`](../scripts/install/install_web_service.sh) |
+| `ledmatrix-update-verify.path` / `.service` | the web user | Health check after an automatic update | the same installers, or [`src/auto_update_setup.py`](../src/auto_update_setup.py) at runtime |
+| `ledmatrix-wifi-monitor.service` | root | [`wifi_monitor_daemon.py`](../scripts/utils/wifi_monitor_daemon.py) | [`install_wifi_monitor.sh`](../scripts/install/install_wifi_monitor.sh) |
+| `ledmatrix-mqtt-bridge.service` | root | [MQTT bridge](../integrations/mqtt_bridge/README.md) (optional) | [`install_mqtt_bridge.sh`](../scripts/install/install_mqtt_bridge.sh) |
+| `ledmatrix-dns-fix.service` | root | DNS workaround (optional) | [`install_dns_fix.sh`](../scripts/install/install_dns_fix.sh) |
+
+Unit templates are in [`systemd/`](../systemd/README.md). The display runs as
+root because the LED matrix library needs direct GPIO access. The web
+interface runs unprivileged and uses a fixed list of `sudo` rules for the
+few privileged things it does; see [PERMISSIONS.md](PERMISSIONS.md).
+
+`start_web_conditionally.py` exits without starting Flask when
+`web_display_autostart` is explicitly false in `config.json`.
+
+## How the two main processes share state
+
+The display and the web interface are separate processes that never call
+each other. They share three things:
+
+1. **`config/config.json` and `config/config_secrets.json`.** The web
+   interface writes them through `ConfigManager`
+   ([`src/config_manager.py`](../src/config_manager.py)); the display
+   notices through `ConfigService` (below).
+2. **The disk cache**, `/var/cache/ledmatrix` (owned `root:ledmatrix`,
+   setgid, files `0660`), read and written through `CacheManager`
+   ([`src/cache_manager.py`](../src/cache_manager.py),
+   [`src/cache/disk_cache.py`](../src/cache/disk_cache.py)). Readers in the
+   other process pass `memory_ttl=0` so they do not serve a stale in-memory
+   copy.
+3. **A few files in `/tmp`.**
+
+| State | Where | Written by | Read by |
+|---|---|---|---|
+| 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, only when the socket could not carry the request (`should_fall_back`); four plugins write it directly | display: `_poll_on_demand_requests()`, a `stat()` every 1 s while the socket is up (0.25 s without), read only when the file changed |
+| 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 | control socket `errors.clear`; cache `plugin_error_clear_request` as the fallback | web: `POST /api/v3/errors/clear` | display: applied before the socket answers; the mailbox on the error publisher's 5 s tick, read only when the file changed |
+| 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` |
+| 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 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; only when
+the socket could not carry it (a stopped display, one older than the socket
+or the command) do they write the mailbox instead. A display that had the
+request and refused it is answered with the error, not posted a mailbox
+copy. The display looks at the mailbox every
+`MAILBOX_POLL_INTERVAL_WITH_SOCKET` (1 s) while it serves the socket, and
+every `ON_DEMAND_POLL_INTERVAL` (0.25 s) without one, from its dwell sleep,
+its render loops and Vegas's interrupt check as well as the main loop; a
+look is one `stat()` unless the file changed. 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
+-- manifests and directories through `PluginCatalog`
+([`src/plugin_system/plugin_catalog.py`](../src/plugin_system/plugin_catalog.py)),
+config schemas through `SchemaManager`, and each plugin's section of
+`config.json` through `ConfigManager`. 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`, `loaded_at` and `modes` (the display modes `DisplayController`
+registered -- `plugin.modes` when the plugin computes them, else the
+manifest's), 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.
+`PluginCatalog.get_plugin_display_modes` and `find_plugin_for_mode` prefer a
+live view's `modes` to the manifest's `display_modes`, so `/display/modes`
+and on-demand see modes a plugin generates from its config (#668).
+
+**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
+
+[`src/display_controller.py`](../src/display_controller.py), class
+`DisplayController`. `__init__` loads config, starts the cache and the
+error-snapshot publisher, runs the startup validator, creates the
+`DisplayManager` ([`src/display_manager.py`](../src/display_manager.py)),
+`FontManager` and `PluginManager`, loads the enabled plugins in parallel,
+runs an initial `update()` pass within a 20-second budget
+(`_INITIAL_UPDATE_BUDGET_SECONDS`; a plugin that misses it is deferred to
+the scheduler), and sets up Vegas mode.
+
+`run()` is the main loop. Each pass, in order: apply a pending plugin
+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. [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.
+  `_apply_plugin_rotation_order()` applies `display.plugin_rotation_order`.
+- **Durations.** `_get_display_duration()`: `display.display_durations[mode]`,
+  else the plugin's `get_display_duration()`, else 30 s. Plugins that
+  support dynamic duration run until `is_cycle_complete()`, capped by
+  `display.dynamic_duration.max_duration_seconds` (default 180 s).
+- **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. 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, 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
+  screen to end.
+- **Config hot reload.** `ConfigService`
+  ([`src/config_service.py`](../src/config_service.py)) polls the config and
+  secrets files' mtimes every 2 s and notifies subscribers when the content
+  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, 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()`
+  ([`coordinator.py`](../src/vegas_mode/coordinator.py)) when
+  `display.vegas_scroll.enabled` is set. `PluginAdapter` gets each plugin's
+  content (`get_vegas_content()`, else its `scroll_helper` image, else a
+  capture of `display()`), `StreamManager` orders it and `RenderPipeline`
+  scrolls it. See [ADVANCED_FEATURES.md](ADVANCED_FEATURES.md).
+- **Multi-display sync.** `DisplaySyncManager`
+  ([`src/common/sync_manager.py`](../src/common/sync_manager.py)), enabled by
+  `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/):
+
+| Area | Where |
+|---|---|
+| 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 (display process) | [`plugin_manager.py`](../src/plugin_system/plugin_manager.py) (`PluginManager`) |
+| Manifest 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) |
+| Resource metrics | [`resource_monitor.py`](../src/plugin_system/resource_monitor.py) |
+| Config schemas and defaults | [`schema_manager.py`](../src/plugin_system/schema_manager.py) |
+| Install, update, uninstall | [`store_manager.py`](../src/plugin_system/store_manager.py) (`PluginStoreManager`), with its methods split across [`store_registry.py`](../src/plugin_system/store_registry.py) (registry, GitHub), [`store_install.py`](../src/plugin_system/store_install.py) and [`store_update.py`](../src/plugin_system/store_update.py) |
+| Core-version gate | [`compatibility.py`](../src/plugin_system/compatibility.py) |
+
+Discovery scans only `plugin_system.plugins_directory` (default
+`plugin-repos/`). Scheduled `update()` calls run on one background worker
+thread; a per-plugin lock keeps `display()` from running during an update.
+
+**Store flow.** `install_plugin()` renames any existing copy aside
+(`<id>.standalone-backup-preinstall`), installs the new one, and puts the old
+copy back if the install fails. Monorepo plugins come from the GitHub Trees
+API, falling back to the repository ZIP; other plugins by `git clone` or
+download. The manifest is checked (see
+[required fields](PLUGIN_API_REFERENCE.md#manifest-required-fields)), the core
+version gate runs, then dependencies are installed as root through
+`scripts/fix_perms/safe_pip_install.sh`. `update_plugin()` pulls git
+installs, undoing a pull whose new version is incompatible, and reinstalls
+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 -- 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
+  `web_interface/templates/v3/partials/`). Plugin configuration tabs are
+  rendered from the plugin's schema by `plugin_config.html`.
+- **API.** [`blueprints/api_v3/`](../web_interface/blueprints/api_v3/) is one
+  blueprint at `/api/v3`, split by area: `backup.py`, `config.py`,
+  `display.py`, `fonts.py`, `misc.py` (health, logs, errors, cache, sync),
+  `starlark.py`, `system.py` (service actions, updates, git), `wifi.py`, and
+  the plugin routes: `plugins.py` (installed list, enable/disable, plugin
+  actions), `plugin_store.py` (install, update, uninstall, store),
+  `plugin_config.py` (config, schema, reset), `plugin_assets.py` (uploads,
+  plugin static files), `plugin_health.py` (health, metrics, limits),
+  `plugin_operations.py` (operation history, state reconciliation) and
+  `plugin_calendar.py`. `__init__.py` defines the blueprint and shared helpers and
+  imports the modules so their routes register. Endpoints are listed in
+  [REST_API_REFERENCE.md](REST_API_REFERENCE.md).
+- **Front end.** HTMX loads each tab's partial on first open
+  (`hx-trigger="loadtab"`); Alpine.js holds page state. Scripts are in
+  `web_interface/static/v3/js/`; form widgets are bundled from
+  [`js/widgets/`](../web_interface/static/v3/js/widgets/README.md).
+- **Server-sent events** (`app.py`): `/api/v3/stream/stats` (CPU, memory,
+  temperature, service state, every 10 s), `/api/v3/stream/display` (preview
+  frames when the PNG changes) and `/api/v3/stream/logs` (journal of both
+  services). One generator thread per stream is shared by all clients.
+
+## Updates
+
+- **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):
+  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
+  weekly between 02:00 and 05:00. Before pulling it copies
+  [`scripts/utils/auto_update_verify.py`](../scripts/utils/auto_update_verify.py)
+  to `data/auto_update_verifier.py`, then writes
+  `data/auto_update_verify.request`. That file triggers
+  `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, 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`
+  ([`src/startup_validator.py`](../src/startup_validator.py)) runs twice in
+  `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. 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
+
+| Task | Start with |
+|---|---|
+| Change rotation, durations or priorities | `DisplayController.run()` and `_get_display_duration()` in [`display_controller.py`](../src/display_controller.py) |
+| Add a config key | [CONFIG_REFERENCE.md](CONFIG_REFERENCE.md), [`config/config.template.json`](../config/config.template.json), the tab's partial and `api_v3/config.py` |
+| Change drawing or fonts | [`display_manager.py`](../src/display_manager.py), [`font_manager.py`](../src/font_manager.py), [`src/common/bdf_font.py`](../src/common/bdf_font.py) |
+| Add a plugin-facing API | [`base_plugin.py`](../src/plugin_system/base_plugin.py) or [`src/common/`](../src/common/README.md); document it in [PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md) |
+| Plugin install/update bugs | `PluginStoreManager` in [`store_manager.py`](../src/plugin_system/store_manager.py) |
+| A plugin that won't load | `PluginManager.load_plugin()` and `PluginLoader.load_plugin()`; `python3 scripts/check_plugin.py --plugin <id>` |
+| Add an API endpoint | the matching module in [`api_v3/`](../web_interface/blueprints/api_v3/) |
+| Add a web UI tab or control | `templates/v3/base.html`, the tab's partial, `pages_v3.py` |
+| Vegas scroll | [`src/vegas_mode/coordinator.py`](../src/vegas_mode/coordinator.py) |
+| Installer or permissions | [`first_time_install.sh`](../first_time_install.sh), [`scripts/install/`](../scripts/install/), [PERMISSIONS.md](PERMISSIONS.md) |
+| Work without a Pi | [DEV_PREVIEW.md](DEV_PREVIEW.md), [EMULATOR_SETUP_GUIDE.md](EMULATOR_SETUP_GUIDE.md), [HOW_TO_RUN_TESTS.md](HOW_TO_RUN_TESTS.md) |

docs/CONFIG_DEBUGGING.md

@@ -172,10 +172,14 @@ ERROR - Plugin football-scoreboard configuration validation failed: 'api_key' is
 
 ### Enable Debug Logging
 
-Set environment variable:
+Run the display in the foreground with `-d`, or set `LEDMATRIX_DEBUG=true`
+(the value must be `true`; `1` is ignored — see `setup_logging()` in
+[`src/logging_config.py`](../src/logging_config.py)):
 ```bash
-export LEDMATRIX_DEBUG=1
-python run.py
+sudo systemctl stop ledmatrix.service
+sudo python3 run.py -d
+# or
+sudo LEDMATRIX_DEBUG=true python3 run.py
 ```
 
 ### Check Merged Configuration
@@ -321,8 +325,10 @@ cp config/backups/config.json.backup.20240115_120000_000000 config/config.json
 
 ## Getting Help
 
-1. Check logs: `tail -f logs/ledmatrix.log`
-2. Enable debug: `LEDMATRIX_DEBUG=1`
+1. Check logs. Both services log to journald, not to a file:
+   `sudo journalctl -u ledmatrix.service -f` (display) and
+   `sudo journalctl -u ledmatrix-web.service -f` (web interface)
+2. Enable debug: `LEDMATRIX_DEBUG=true` or `python3 run.py -d`
 3. Check error dashboard: `/api/v3/errors/summary`
 4. Validate JSON: https://jsonlint.com/
 5. File an issue: https://github.com/ChuckBuilds/LEDMatrix/issues

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
 
@@ -105,6 +115,7 @@ logical image to multiple chained physical panels.
 | `display_durations` | object, `{}` | Per-plugin display duration in seconds, keyed by plugin id (e.g. `"clock": 15`) | `DisplayController._get_display_duration()` (`src/display_controller.py`) |
 | `plugin_rotation_order` | array, `[]` | Explicit rotation order of plugin ids; empty = all enabled plugins in discovery order | `DisplayController._apply_plugin_rotation_order()` (`src/display_controller.py`) |
 | `use_short_date_format` | bool, `true` | Compact date rendering in sports scoreboards | Nothing since `src/base_classes` was removed; scoreboards read `display.use_short_date_format` from their own plugin config |
+| `scan_order_compensation` | string, `"auto"` | `"auto"` shows one half of each panel a refresh behind while something scrolls at one frame per refresh, which removes the 1px step a 1:N-scan panel shows across its middle; `"off"` disables it. Applies only to layouts whose row order is known: plain or parallel chains, 0 or 180 degree orientation, `multiplexing` 0, `scan_mode` 0, and not in the emulator | `DisplayManager._setup_scan_order_compensation()` (`src/display_manager.py`, `src/scan_order.py`) |
 | `dynamic_duration.max_duration_seconds` | int, optional | Cap for plugins that request dynamic display time | `DisplayController._get_global_dynamic_cap()` (`src/display_controller.py`) |
 
 ## `display.vegas_scroll` — continuous scroll mode
@@ -127,7 +138,15 @@ Read by `src/vegas_mode/config.py` (`VegasScrollConfig.from_config`). See
 | `min_content_separation` | int, `24` |
 | `min_cut_gap` | int, `6` |
 | `continuous_scroll` | bool, `true` |
-| `smooth_scroll` | bool, `true` |
+| `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` |
 | `auto_trim` | bool, `true` |
 | `trim_threshold` | int, `10` |
@@ -142,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 |
 
@@ -175,5 +194,5 @@ See [PLUGIN_CONFIG_CORE_PROPERTIES.md](PLUGIN_CONFIG_CORE_PROPERTIES.md).
 
 | Key | Meaning |
 |---|---|
-| `github.api_token` | Optional GitHub token the Plugin Store uses to avoid API rate limits (`src/plugin_system/store_manager.py`) |
+| `github.api_token` | Optional GitHub token the Plugin Store uses to avoid API rate limits (`src/plugin_system/store_registry.py`) |
 | `<plugin-id>.*` | Secrets a plugin declares with `"x-secret": true` in its config schema; merged into that plugin's config at load time |

docs/DEPRECATIONS_3.8.md

@@ -0,0 +1,347 @@
+# 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-05, core 3.8.2
+- Monorepo: [ChuckBuilds/ledmatrix-plugins](https://github.com/ChuckBuilds/ledmatrix-plugins) (main @ 662fb86f), 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)
+
+**45 deprecated methods: 31 unused, 3 still used, 11 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 |
+|---|---|---|---|---|---|
+| `BackgroundDataService.get_result` | 3.10.0 | core tests (15 test reviews) | — | — | unused — safe to remove in 3.10.0 |
+| `BackgroundDataService.is_request_complete` | 3.10.0 | core tests (11 test reviews) | — | — | unused — safe to remove in 3.10.0 |
+| `BackgroundDataService.get_request_status` | 3.10.0 | core tests (2 test reviews) | — | — | unused — safe to remove in 3.10.0 |
+| `BaseOddsManager.get_odds_for_games` | 3.10.0 | core tests (3 test reviews) | — | — | unused — safe to remove in 3.10.0 |
+| `BaseOddsManager.format_odds_summary` | 3.10.0 | core tests (5 test reviews) | — | — | unused — safe to remove in 3.10.0 |
+| `CacheManager.load_cache` | 3.10.0 | core tests (1 test review) | — | — | unused — safe to remove in 3.10.0 |
+| `CacheManager.generate_sport_cache_key` | 3.10.0 | core tests (2 test calls, 1 test review) | — | — | unused — safe to remove in 3.10.0 |
+| `APIHelper.fetch_espn_scoreboard` | 3.10.0 | core tests (1 test call, 4 test reviews) | — | football-scoreboard (1 test review); hockey-scoreboard (1 test review); ufc-scoreboard (3 test reviews) | unused — safe to remove in 3.10.0 |
+| `APIHelper.fetch_espn_standings` | 3.10.0 | core tests (1 test review) | — | — | unused — safe to remove in 3.10.0 |
+| `APIHelper.fetch_espn_rankings` | 3.10.0 | core tests (1 test review) | — | — | unused — safe to remove in 3.10.0 |
+| `APIHelper.set_cache` | 3.10.0 | core tests (1 test call, 1 test review) | — | — | unused — safe to remove in 3.10.0 |
+| `APIHelper.get_cache` | 3.10.0 | core tests (1 test call) | — | — | unused — safe to remove in 3.10.0 |
+| `APIHelper.set_rate_limit` | 3.10.0 | core tests (10 test calls, 3 test reviews) | — | — | unused — safe to remove in 3.10.0 |
+| `APIHelper.get_request_stats` | 3.10.0 | — | — | — | unused — safe to remove in 3.10.0 |
+| `ConfigManager.rollback_config` | 3.10.0 | core (1 internal); core tests (1 test review) | — | — | unused — safe to remove in 3.10.0 |
+| `ConfigManager.list_backups` | 3.10.0 | core (1 internal); core tests (1 test review) | — | — | unused — safe to remove in 3.10.0 |
+| `ConfigManager.validate_config_file` | 3.10.0 | core (1 internal) | — | — | unused — safe to remove in 3.10.0 |
+| `ConfigManager.get_secret` | 3.10.0 | core tests (5 test calls, 1 test review) | — | — | unused — safe to remove in 3.10.0 |
+| `ConfigManager.cleanup_orphaned_plugin_configs` | 3.10.0 | core tests (2 test calls, 1 test review) | — | — | unused — safe to remove in 3.10.0 |
+| `ConfigManager.validate_all_plugin_configs` | 3.10.0 | core tests (1 test call, 1 test review) | — | — | unused — safe to remove in 3.10.0 |
+| `DynamicTeamResolver.get_available_dynamic_teams` | 3.10.0 | — | — | — | unused — safe to remove in 3.10.0 |
+| `DynamicTeamResolver.is_dynamic_team` | 3.10.0 | — | — | — | unused — safe to remove in 3.10.0 |
+| `FontManager.get_native_bdf_size` | 3.10.0 | core tests (3 test calls) | — | — | unused — safe to remove in 3.10.0 |
+| `FontManager.measure_text` | 3.10.0 | core tests (5 test calls) | — | — | unused — safe to remove in 3.10.0 |
+| `LogoDownloader.fetch_teams_data` | 3.10.0 | core (2 internals) | — | — | still used by core — keep or migrate first |
+| `LogoDownloader.extract_teams_from_data` | 3.10.0 | core (2 internals) | — | — | still used by core — keep or migrate first |
+| `LogoDownloader.download_missing_logos_for_league` | 3.10.0 | core (1 call, 1 internal); core tests (2 test calls) | — | — | still used by core — keep or migrate first |
+| `LogoDownloader.download_all_ncaa_football_logos` | 3.10.0 | core tests (2 test calls) | — | — | unused — safe to remove in 3.10.0 |
+| `LogoDownloader.download_all_missing_logos` | 3.10.0 | — | — | — | unused — safe to remove in 3.10.0 |
+| `LogoDownloader.convert_image_to_rgba` | 3.10.0 | core (1 internal) | — | — | unused — safe to remove in 3.10.0 |
+| `LogoDownloader.convert_all_logos_to_rgba` | 3.10.0 | — | — | — | unused — safe to remove in 3.10.0 |
+| `BasePlugin.get_supported_vegas_modes` | 3.9.0 | core tests (2 test reviews) | — | — | unused — safe to remove in 3.9.0 |
+| `BasePlugin.get_vegas_segment_width` | 3.9.0 | core tests (1 test review) | — | — | unused — safe to remove in 3.9.0 |
+| `PluginManager.get_all_plugins` | 3.10.0 | — | football-scoreboard (1 review) | football-scoreboard (2 test reviews); hockey-scoreboard (1 test review) | needs review: possible use in football-scoreboard |
+| `PluginManager.get_plugin_info` | 3.10.0 | core (12 reviews, 1 internal); core tests (6 test calls, 9 test reviews) | — | — | needs review: possible use in core |
+| `PluginManager.get_all_plugin_info` | 3.10.0 | core (3 reviews); core tests (2 test calls, 11 test reviews) | — | — | needs review: possible use in core |
+| `PluginManager.get_plugin_display_modes` | 3.10.0 | core (4 reviews); core tests (3 test calls, 5 test reviews) | — | — | needs review: possible use in core |
+| `PluginManager.find_plugin_for_mode` | 3.10.0 | core (2 reviews) | — | — | needs review: possible use in core |
+| `PluginStateManager.is_loaded` | 3.10.0 | core (1 internal) | — | — | needs review: possible use in core |
+| `PluginStateManager.is_running` | 3.10.0 | core (1 internal) | — | — | needs review: possible use in core |
+| `PluginStateManager.is_error` | 3.10.0 | core (1 internal) | — | — | needs review: possible use in core |
+| `PluginStateManager.get_error_info` | 3.10.0 | core (1 internal); core tests (4 test calls) | — | — | needs review: possible use in core |
+| `PluginStateManager.get_last_update` | 3.10.0 | core (1 internal) | — | — | needs review: possible use in core |
+| `PluginStateManager.get_state_info` | 3.10.0 | core (1 internal); core tests (7 test reviews) | — | — | needs review: possible use in core |
+| `PluginTestCase.setUp` | 3.10.0 | — | — | basketball-scoreboard (2 test unrelateds); cricket-scoreboard (1 test unrelated); hockey-scoreboard (1 test unrelated); nrl-scoreboard (1 test unrelated) | unused — safe to remove in 3.10.0 |
+
+## Unused — safe to remove (31)
+
+`BackgroundDataService.get_result`, `BackgroundDataService.is_request_complete`, `BackgroundDataService.get_request_status`, `BaseOddsManager.get_odds_for_games`, `BaseOddsManager.format_odds_summary`, `CacheManager.load_cache`, `CacheManager.generate_sport_cache_key`, `APIHelper.fetch_espn_scoreboard`, `APIHelper.fetch_espn_standings`, `APIHelper.fetch_espn_rankings`, `APIHelper.set_cache`, `APIHelper.get_cache`, `APIHelper.set_rate_limit`, `APIHelper.get_request_stats`, `ConfigManager.rollback_config`, `ConfigManager.list_backups`, `ConfigManager.validate_config_file`, `ConfigManager.get_secret`, `ConfigManager.cleanup_orphaned_plugin_configs`, `ConfigManager.validate_all_plugin_configs`, `DynamicTeamResolver.get_available_dynamic_teams`, `DynamicTeamResolver.is_dynamic_team`, `FontManager.get_native_bdf_size`, `FontManager.measure_text`, `LogoDownloader.download_all_ncaa_football_logos`, `LogoDownloader.download_all_missing_logos`, `LogoDownloader.convert_image_to_rgba`, `LogoDownloader.convert_all_logos_to_rgba`, `BasePlugin.get_supported_vegas_modes`, `BasePlugin.get_vegas_segment_width`, `PluginTestCase.setUp`
+
+## Still used — keep or migrate first (3)
+
+`LogoDownloader.fetch_teams_data`, `LogoDownloader.extract_teams_from_data`, `LogoDownloader.download_missing_logos_for_league`
+
+## Needs review (11)
+
+`PluginManager.get_all_plugins`, `PluginManager.get_plugin_info`, `PluginManager.get_all_plugin_info`, `PluginManager.get_plugin_display_modes`, `PluginManager.find_plugin_for_mode`, `PluginStateManager.is_loaded`, `PluginStateManager.is_running`, `PluginStateManager.is_error`, `PluginStateManager.get_error_info`, `PluginStateManager.get_last_update`, `PluginStateManager.get_state_info`
+
+## Every hit
+
+File paths are relative to the plugin's directory (core: the repo root).
+
+| Method | Where | File:line | Kind | Code |
+|---|---|---|---|---|
+| `BackgroundDataService.get_result` | core tests | test/test_background_data_service.py:85 | test review | `result = service.get_result(req_id)` |
+| `BackgroundDataService.get_result` | core tests | test/test_background_data_service.py:107 | test review | `seen["filed"] = service.get_result(result.request_id) is result` |
+| `BackgroundDataService.get_result` | core tests | test/test_background_data_service.py:148 | test review | `result = service.get_result(req_id)` |
+| `BackgroundDataService.get_result` | core tests | test/test_background_data_service.py:165 | test review | `result = service.get_result(req_id)` |
+| `BackgroundDataService.get_result` | core tests | test/test_background_data_service.py:254 | test review | `assert service.get_result("unknown") is None` |
+| `BackgroundDataService.get_result` | core tests | test/test_background_data_service.py:391 | test review | `assert service.get_result(rid).cached is True` |
+| `BackgroundDataService.get_result` | core tests | test/test_background_fetch_dedupe.py:198 | test review | `assert service.get_result(req).success is True` |
+| `BackgroundDataService.get_result` | core tests | test/test_background_payload_release.py:85 | test review | `result = service.get_result(req_id)` |
+| `BackgroundDataService.get_result` | core tests | test/test_background_payload_release.py:117 | test review | `stored = service.get_result(req_id)` |
+| `BackgroundDataService.get_result` | core tests | test/test_background_payload_release.py:144 | test review | `assert service.get_result(req_id).data == PAYLOAD` |
+| `BackgroundDataService.get_result` | core tests | test/test_background_payload_release.py:154 | test review | `stored = service.get_result(req_id)` |
+| `BackgroundDataService.get_result` | core tests | test/test_background_payload_release.py:171 | test review | `assert service.get_result(req_id).data is None` |
+| `BackgroundDataService.get_result` | core tests | test/test_background_payload_release.py:193 | test review | `assert service.get_result(req_id).data == PAYLOAD` |
+| `BackgroundDataService.get_result` | core tests | test/test_background_payload_release.py:278 | test review | `stored = service.get_result(first)` |
+| `BackgroundDataService.get_result` | core tests | test/test_fetch_service.py:703 | test review | `assert bds.get_result(request_id).success` |
+| `BackgroundDataService.is_request_complete` | core tests | test/test_background_data_service.py:145 | test review | `while not service.is_request_complete(req_id) and time.time() < deadline:` |
+| `BackgroundDataService.is_request_complete` | core tests | test/test_background_data_service.py:162 | test review | `while not service.is_request_complete(req_id) and time.time() < deadline:` |
+| `BackgroundDataService.is_request_complete` | core tests | test/test_background_data_service.py:194 | test review | `while not service.is_request_complete(req_id) and time.time() < deadline:` |
+| `BackgroundDataService.is_request_complete` | core tests | test/test_background_data_service.py:211 | test review | `while not service.is_request_complete(req_id) and time.time() < deadline:` |
+| `BackgroundDataService.is_request_complete` | core tests | test/test_background_data_service.py:246 | test review | `assert service.is_request_complete("r2") is False` |
+| `BackgroundDataService.is_request_complete` | core tests | test/test_background_data_service.py:251 | test review | `assert service.is_request_complete("r3") is True` |
+| `BackgroundDataService.is_request_complete` | core tests | test/test_background_data_service_espn_ranges.py:91 | test review | `while not service.is_request_complete(request_id) and time.time() < deadline:` |
+| `BackgroundDataService.is_request_complete` | core tests | test/test_background_data_service_espn_ranges.py:154 | test review | `while not service.is_request_complete(request_id) and time.time() < deadline:` |
+| `BackgroundDataService.is_request_complete` | core tests | test/test_background_fetch_dedupe.py:55 | test review | `while not service.is_request_complete(req_id) and time.time() < deadline:` |
+| `BackgroundDataService.is_request_complete` | core tests | test/test_background_payload_release.py:67 | test review | `while not service.is_request_complete(req_id) and time.time() < deadline:` |
+| `BackgroundDataService.is_request_complete` | core tests | test/test_fetch_service.py:701 | test review | `while not bds.is_request_complete(request_id) and time.monotonic() < deadline:` |
+| `BackgroundDataService.get_request_status` | core tests | test/test_background_data_service.py:223 | test review | `assert service.get_request_status("nonexistent") is None` |
+| `BackgroundDataService.get_request_status` | core tests | test/test_background_fetch_dedupe.py:448 | test review | `assert service.get_request_status(rid) is FetchStatus.CANCELLED, (` |
+| `BaseOddsManager.get_odds_for_games` | core tests | test/test_base_odds_manager.py:356 | test review | `result = manager.get_odds_for_games(games)` |
+| `BaseOddsManager.get_odds_for_games` | core tests | test/test_base_odds_manager.py:374 | test review | `result = manager.get_odds_for_games(games)` |
+| `BaseOddsManager.get_odds_for_games` | core tests | test/test_base_odds_manager.py:385 | test review | `result = manager.get_odds_for_games([game])` |
+| `BaseOddsManager.format_odds_summary` | core tests | test/test_base_odds_manager.py:322 | test review | `result = manager.format_odds_summary({` |
+| `BaseOddsManager.format_odds_summary` | core tests | test/test_base_odds_manager.py:329 | test review | `result = manager.format_odds_summary(FULL_EXTRACTED)` |
+| `BaseOddsManager.format_odds_summary` | core tests | test/test_base_odds_manager.py:333 | test review | `assert manager.format_odds_summary(None) == 'No odds available'` |
+| `BaseOddsManager.format_odds_summary` | core tests | test/test_base_odds_manager.py:336 | test review | `assert manager.format_odds_summary({}) == 'No odds available'` |
+| `BaseOddsManager.format_odds_summary` | core tests | test/test_base_odds_manager.py:339 | test review | `assert manager.format_odds_summary(` |
+| `CacheManager.load_cache` | core tests | test/conftest.py:219 | test review | `mock.load_cache = Mock(side_effect=mock_get)` |
+| `CacheManager.generate_sport_cache_key` | core tests | test/test_background_data_service.py:42 | test review | `m.generate_sport_cache_key.return_value = "test_key"` |
+| `CacheManager.generate_sport_cache_key` | core tests | test/test_background_data_service.py:356 | test call | `expected = CacheManager.generate_sport_cache_key(None, sport, date_str)` |
+| `CacheManager.generate_sport_cache_key` | core tests | test/test_background_data_service.py:367 | test call | `theirs = cm_module.CacheManager.generate_sport_cache_key(None, "nba")` |
+| `APIHelper.fetch_espn_scoreboard` | core tests | test/test_api_helper.py:214 | test review | `result = helper.fetch_espn_scoreboard('football', 'nfl')` |
+| `APIHelper.fetch_espn_scoreboard` | core tests | test/test_api_helper.py:230 | test review | `helper.fetch_espn_scoreboard('basketball', 'nba', date='20250115')` |
+| `APIHelper.fetch_espn_scoreboard` | core tests | test/test_api_helper.py:239 | test review | `helper.fetch_espn_scoreboard('basketball', 'nba', date='20250115', cache_key='mine')` |
+| `APIHelper.fetch_espn_scoreboard` | core tests | test/test_api_helper.py:251 | test review | `assert helper.fetch_espn_scoreboard('basketball', 'nba', date='20250115') == {` |
+| `APIHelper.fetch_espn_scoreboard` | core tests | test/test_espn_scoreboard_cache.py:199 | test call | `helper.fetch_espn_scoreboard("football", "nfl", date=self.DAY)` |
+| `APIHelper.fetch_espn_scoreboard` | football-scoreboard | test_espn_date_ranges.py:119 | test review | `helper = sys.modules[sports.fetch_espn_scoreboard.__module__]` |
+| `APIHelper.fetch_espn_scoreboard` | hockey-scoreboard | test_espn_date_ranges.py:106 | test review | `helper = sys.modules[sports.fetch_espn_scoreboard.__module__]` |
+| `APIHelper.fetch_espn_scoreboard` | ufc-scoreboard | test_every_bout_is_its_own_fight.py:103 | test review | `_real_fetch = sports.fetch_espn_scoreboard` |
+| `APIHelper.fetch_espn_scoreboard` | ufc-scoreboard | test_every_bout_is_its_own_fight.py:108 | test review | `sports.fetch_espn_scoreboard = lambda *a, **k: board(name)` |
+| `APIHelper.fetch_espn_scoreboard` | ufc-scoreboard | test_every_bout_is_its_own_fight.py:113 | test review | `sports.fetch_espn_scoreboard = _real_fetch` |
+| `APIHelper.fetch_espn_standings` | core tests | test/test_api_helper.py:258 | test review | `helper.fetch_espn_standings('football', 'nfl')` |
+| `APIHelper.fetch_espn_rankings` | core tests | test/test_api_helper.py:269 | test review | `helper.fetch_espn_rankings('football', 'college-football')` |
+| `APIHelper.set_cache` | core tests | test/test_api_helper.py:128 | test review | `helper.set_cache('k', {'a': 1}, ttl=42)` |
+| `APIHelper.set_cache` | core tests | test/test_api_helper.py:350 | test call | `assert helper.set_cache('k', {'a': 1}) is None` |
+| `APIHelper.get_cache` | core tests | test/test_api_helper.py:348 | test call | `assert helper.get_cache('k') is None` |
+| `APIHelper.set_rate_limit` | core tests | test/test_api_helper.py:42 | test call | `helper.set_rate_limit(0)` |
+| `APIHelper.set_rate_limit` | core tests | test/test_api_helper.py:57 | test review | `helper.set_rate_limit(5)` |
+| `APIHelper.set_rate_limit` | core tests | test/test_api_helper.py:72 | test review | `helper.set_rate_limit(5)` |
+| `APIHelper.set_rate_limit` | core tests | test/test_api_helper.py:91 | test review | `helper.set_rate_limit(5)` |
+| `APIHelper.set_rate_limit` | core tests | test/test_api_helper.py:150 | test call | `helper.set_rate_limit(0)` |
+| `APIHelper.set_rate_limit` | core tests | test/test_api_helper.py:305 | test call | `helper.set_rate_limit(0)` |
+| `APIHelper.set_rate_limit` | core tests | test/test_api_helper.py:313 | test call | `helper.set_rate_limit(0)` |
+| `APIHelper.set_rate_limit` | core tests | test/test_api_helper.py:326 | test call | `helper.set_rate_limit(0)` |
+| `APIHelper.set_rate_limit` | core tests | test/test_api_helper.py:334 | test call | `helper.set_rate_limit(0)` |
+| `APIHelper.set_rate_limit` | core tests | test/test_api_helper.py:346 | test call | `helper.set_rate_limit(0)` |
+| `APIHelper.set_rate_limit` | core tests | test/test_espn_scoreboard_cache.py:197 | test call | `helper.set_rate_limit(0)` |
+| `APIHelper.set_rate_limit` | core tests | test/test_fetch_service.py:726 | test call | `helper.set_rate_limit(0)` |
+| `APIHelper.set_rate_limit` | core tests | test/test_fetch_service.py:1143 | test call | `helper.set_rate_limit(0)` |
+| `ConfigManager.rollback_config` | core | src/config_manager.py:191 | internal (in `ConfigManager.rollback_config`) | `success = atomic_mgr.rollback_config(backup_version)` |
+| `ConfigManager.rollback_config` | core | src/config_manager_atomic.py:297 | unrelated | `def rollback_config(self, backup_version: Optional[str] = None) -> bool:` |
+| `ConfigManager.rollback_config` | core tests | test/test_config_durable_writes.py:345 | test review | `assert manager.rollback_config()` |
+| `ConfigManager.list_backups` | core | src/config_manager.py:212 | internal (in `ConfigManager.list_backups`) | `return atomic_mgr.list_backups()` |
+| `ConfigManager.list_backups` | core | src/config_manager_atomic.py:334 | unrelated | `def list_backups(self) -> List[BackupInfo]:` |
+| `ConfigManager.list_backups` | core | src/config_manager_atomic.py:309 | unrelated | `backups = self.list_backups()` |
+| `ConfigManager.list_backups` | core tests | test/test_config_durable_writes.py:323 | test review | `assert [b.path for b in manager.list_backups()] == [` |
+| `ConfigManager.validate_config_file` | core | src/config_manager.py:226 | internal (in `ConfigManager.validate_config_file`) | `return atomic_mgr.validate_config_file(config_path)` |
+| `ConfigManager.validate_config_file` | core | src/config_manager_atomic.py:426 | unrelated | `def validate_config_file(self, config_path: Optional[str] = None) -> ValidationResult:` |
+| `ConfigManager.get_secret` | core tests | test/conftest.py:246 | test review | `mock.get_secret = Mock(side_effect=mock_get_secret)` |
+| `ConfigManager.get_secret` | core tests | test/test_config_manager.py:317 | test call | `assert manager.get_secret("api_key") == "secret123"` |
+| `ConfigManager.get_secret` | core tests | test/test_config_manager.py:318 | test call | `assert manager.get_secret("token") == "token456"` |
+| `ConfigManager.get_secret` | core tests | test/test_config_manager.py:319 | test call | `assert manager.get_secret("nonexistent") is None` |
+| `ConfigManager.get_secret` | core tests | test/test_config_manager.py:325 | test call | `assert manager.get_secret("api_key") is None` |
+| `ConfigManager.get_secret` | core tests | test/test_config_manager.py:337 | test call | `assert manager.get_secret("api_key") is None` |
+| `ConfigManager.cleanup_orphaned_plugin_configs` | core tests | test/test_config_manager.py:447 | test call | `removed = manager.cleanup_orphaned_plugin_configs(["plugin1", "plugin2"])` |
+| `ConfigManager.cleanup_orphaned_plugin_configs` | core tests | test/test_core_config_key_adopters.py:80 | test review | `removed = manager.cleanup_orphaned_plugin_configs(['installed'])` |
+| `ConfigManager.cleanup_orphaned_plugin_configs` | core tests | test/test_web_auth.py:616 | test call | `config_manager.cleanup_orphaned_plugin_configs([])` |
+| `ConfigManager.validate_all_plugin_configs` | core tests | test/test_core_config_key_adopters.py:91 | test review | `results = manager.validate_all_plugin_configs(schema_manager)` |
+| `ConfigManager.validate_all_plugin_configs` | core tests | test/test_retired_plugin_config_keys.py:112 | test call | `results = config_manager.validate_all_plugin_configs(schema_manager)` |
+| `FontManager.get_native_bdf_size` | core tests | test/test_font_manager.py:104 | test call | `assert fm.get_native_bdf_size("five_by_seven") == 7` |
+| `FontManager.get_native_bdf_size` | core tests | test/test_font_manager.py:107 | test call | `assert fm.get_native_bdf_size("press_start") is None` |
+| `FontManager.get_native_bdf_size` | core tests | test/test_font_manager.py:110 | test call | `assert fm.get_native_bdf_size("no-such-family") is None` |
+| `FontManager.measure_text` | core tests | test/test_font_manager.py:116 | test call | `width, height, baseline = fm.measure_text("SCORE", font)` |
+| `FontManager.measure_text` | core tests | test/test_font_manager.py:119 | test call | `assert fm.measure_text("SCORE", font) == (width, height, baseline)` |
+| `FontManager.measure_text` | core tests | test/test_font_manager.py:124 | test call | `short, _, _ = fm.measure_text("AB", font)` |
+| `FontManager.measure_text` | core tests | test/test_font_manager.py:125 | test call | `long, _, _ = fm.measure_text("ABCD", font)` |
+| `FontManager.measure_text` | core tests | test/test_font_manager.py:132 | test call | `fm.measure_text("X", font)` |
+| `LogoDownloader.fetch_teams_data` | core | src/logo_downloader.py:639 | internal (in `LogoDownloader.download_missing_logos_for_league`) | `data = self.fetch_teams_data(league)` |
+| `LogoDownloader.fetch_teams_data` | core | src/logo_downloader.py:695 | internal (in `LogoDownloader.download_all_ncaa_football_logos`) | `data = self.fetch_teams_data(league)` |
+| `LogoDownloader.extract_teams_from_data` | core | src/logo_downloader.py:645 | internal (in `LogoDownloader.download_missing_logos_for_league`) | `teams = self.extract_teams_from_data(data, league)` |
+| `LogoDownloader.extract_teams_from_data` | core | src/logo_downloader.py:701 | internal (in `LogoDownloader.download_all_ncaa_football_logos`) | `teams = self.extract_teams_from_data(data, league)` |
+| `LogoDownloader.download_missing_logos_for_league` | core | src/logo_downloader.py:786 | internal (in `LogoDownloader.download_all_missing_logos`) | `downloaded, failed = self.download_missing_logos_for_league(league, force_download)` |
+| `LogoDownloader.download_missing_logos_for_league` | core | src/logo_downloader.py:1034 | call | `return downloader.download_missing_logos_for_league(league, force_download)` |
+| `LogoDownloader.download_missing_logos_for_league` | core tests | test/test_logo_downloader.py:292 | test call | `downloader.download_missing_logos_for_league("nfl")` |
+| `LogoDownloader.download_missing_logos_for_league` | core tests | test/test_logo_downloader.py:304 | test call | `downloader.download_missing_logos_for_league("nfl")` |
+| `LogoDownloader.download_all_ncaa_football_logos` | core tests | test/test_logo_downloader.py:319 | test call | `downloader.download_all_ncaa_football_logos()` |
+| `LogoDownloader.download_all_ncaa_football_logos` | core tests | test/test_logo_downloader.py:332 | test call | `downloader.download_all_ncaa_football_logos()` |
+| `LogoDownloader.convert_image_to_rgba` | core | src/logo_downloader.py:897 | internal (in `LogoDownloader.convert_all_logos_to_rgba`) | `if self.convert_image_to_rgba(logo_file):` |
+| `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_vegas_segment_width` | core tests | test/test_vegas_participation.py:359 | test review | `assert plugin.get_vegas_segment_width() == 2` |
+| `PluginManager.get_all_plugins` | core | src/plugin_system/testing/mocks.py:218 | unrelated | `def get_all_plugins(self) -> Dict[str, Any]:` |
+| `PluginManager.get_all_plugins` | football-scoreboard | emulator_demo.py:68 | review | `mock_plugin_manager.get_all_plugins = Mock(return_value=[])` |
+| `PluginManager.get_all_plugins` | football-scoreboard | test_dynamic_duration.py:64 | test review | `mock_plugin_manager.get_all_plugins = Mock(return_value=[])` |
+| `PluginManager.get_all_plugins` | football-scoreboard | test_football_plugin.py:74 | test review | `mock_plugin_manager.get_all_plugins = Mock(return_value=[])` |
+| `PluginManager.get_all_plugins` | hockey-scoreboard | test_hockey_emulator.py:99 | test review | `mock_plugin_manager.get_all_plugins = Mock(return_value=[])` |
+| `PluginManager.get_plugin_info` | core | src/plugin_system/plugin_catalog.py:120 | unrelated | `def get_plugin_info(self, plugin_id: str) -> Optional[Dict[str, Any]]:` |
+| `PluginManager.get_plugin_info` | core | src/plugin_system/plugin_catalog.py:133 | unrelated | `return [info for info in (self.get_plugin_info(pid) for pid in ids) if info]` |
+| `PluginManager.get_plugin_info` | core | src/plugin_system/plugin_manager.py:1001 | internal (in `PluginManager.get_all_plugin_info`) | `return [info for info in [self.get_plugin_info(pid) for pid in pids] if info]` |
+| `PluginManager.get_plugin_info` | core | src/plugin_system/store_install.py:208 | review | `plugin_info = self.get_plugin_info(plugin_id, fetch_latest_from_github=True, force_refresh=True)` |
+| `PluginManager.get_plugin_info` | core | src/plugin_system/store_registry.py:801 | unrelated | `def get_plugin_info(self, plugin_id: str, fetch_latest_from_github: bool = True, force_refresh: bool = False) -> Optional[Dict]:` |
+| `PluginManager.get_plugin_info` | core | src/plugin_system/store_update.py:357 | review | `plugin_info_remote = self.get_plugin_info(plugin_id, fetch_latest_from_github=True, force_refresh=True)` |
+| `PluginManager.get_plugin_info` | core | src/plugin_system/store_update.py:362 | review | `plugin_info_remote = self.get_plugin_info(alt_id, fetch_latest_from_github=True, force_refresh=True)` |
+| `PluginManager.get_plugin_info` | core | src/plugin_system/store_update.py:685 | review | `plugin_info_remote = self.get_plugin_info(plugin_id, fetch_latest_from_github=True, force_refresh=True)` |
+| `PluginManager.get_plugin_info` | core | src/plugin_system/store_update.py:691 | review | `plugin_info_remote = self.get_plugin_info(alt_id, fetch_latest_from_github=True, force_refresh=True)` |
+| `PluginManager.get_plugin_info` | core | src/plugin_system/testing/mocks.py:223 | unrelated | `def get_plugin_info(self, plugin_id: str) -> Optional[Dict[str, Any]]:` |
+| `PluginManager.get_plugin_info` | core | web_interface/blueprints/api_v3/plugin_store.py:216 | review | `remote_info = api_v3.plugin_store_manager.get_plugin_info(plugin_id, fetch_latest_from_github=True)` |
+| `PluginManager.get_plugin_info` | core | web_interface/blueprints/api_v3/plugin_store.py:334 | review | `plugin_info = api_v3.plugin_store_manager.get_plugin_info(plugin_id)` |
+| `PluginManager.get_plugin_info` | core | web_interface/blueprints/api_v3/plugin_store.py:545 | review | `elif not api_v3.plugin_store_manager.get_plugin_info(plugin_id):` |
+| `PluginManager.get_plugin_info` | core | web_interface/blueprints/api_v3/plugin_store.py:602 | review | `elif not api_v3.plugin_store_manager.get_plugin_info(plugin_id):` |
+| `PluginManager.get_plugin_info` | core | web_interface/blueprints/pages_v3.py:224 | review | `info = pages_v3.plugin_catalog.get_plugin_info(pid) or {}` |
+| `PluginManager.get_plugin_info` | core | web_interface/blueprints/pages_v3.py:722 | review | `plugin_info = pages_v3.plugin_catalog.get_plugin_info(plugin_id)` |
+| `PluginManager.get_plugin_info` | core | web_interface/blueprints/pages_v3.py:727 | review | `plugin_info = pages_v3.plugin_catalog.get_plugin_info(plugin_id)` |
+| `PluginManager.get_plugin_info` | core tests | test/test_api_v3_plugin_install_endpoints.py:111 | test review | `manager.get_plugin_info.return_value = None` |
+| `PluginManager.get_plugin_info` | core tests | test/test_api_v3_plugin_install_endpoints.py:119 | test review | `manager.get_plugin_info.return_value = {"id": "clock"}` |
+| `PluginManager.get_plugin_info` | core tests | test/test_pages_v3_path_guards.py:47 | test call | `plugin_manager.get_plugin_info.return_value = {"name": "Weather", "version": "1.0.0"}` |
+| `PluginManager.get_plugin_info` | core tests | test/test_registry_id_resolution.py:81 | test review | `_ids(store.get_plugin_info("ledmatrix-weather", fetch_latest_from_github=False))` |
+| `PluginManager.get_plugin_info` | core tests | test/test_store_manager_caches.py:612 | test review | `info = self.sm.get_plugin_info("foo", fetch_latest_from_github=True, force_refresh=True)` |
+| `PluginManager.get_plugin_info` | core tests | test/test_store_non_plugin_entries.py:37 | test review | `store.get_plugin_info = MagicMock(return_value=dict(SKIN))` |
+| `PluginManager.get_plugin_info` | core tests | test/test_web_plugin_dir_resolution.py:86 | test review | `api.plugin_store_manager.get_plugin_info = MagicMock(return_value=None)` |
+| `PluginManager.get_plugin_info` | core tests | test/test_web_plugin_dir_resolution.py:118 | test review | `api.plugin_store_manager.get_plugin_info = MagicMock(return_value=None)` |
+| `PluginManager.get_plugin_info` | core tests | test/test_web_plugin_dir_resolution.py:178 | test call | `plugin_manager.get_plugin_info.return_value = {"id": "weather", "name": "Weather"}` |
+| `PluginManager.get_plugin_info` | core tests | test/web_interface/test_plugin_config_form_defaults.py:119 | test call | `pm.get_plugin_info.return_value = {"name": "Demo", "version": "1.0.0"}` |
+| `PluginManager.get_plugin_info` | core tests | test/web_interface/test_plugin_config_schema_expansion.py:88 | test call | `pm.get_plugin_info.return_value = {"id": plugin_id, "name": plugin_id}` |
+| `PluginManager.get_plugin_info` | core tests | test/web_interface/test_plugin_widget_route.py:226 | test call | `pm.get_plugin_info.return_value = {"id": plugin_id, "name": plugin_id}` |
+| `PluginManager.get_plugin_info` | core tests | test/web_interface/test_plugin_widget_route.py:228 | test call | `pm.get_plugin_info.return_value["version"] = version` |
+| `PluginManager.get_plugin_info` | core tests | test/web_interface/test_update_all_plugins.py:41 | test review | `sm.get_plugin_info.return_value = None` |
+| `PluginManager.get_plugin_info` | core tests | test/web_interface/test_web_process_runs_no_plugin_code.py:132 | test review | `store.get_plugin_info.return_value = None` |
+| `PluginManager.get_all_plugin_info` | core | src/plugin_system/plugin_catalog.py:129 | unrelated | `def get_all_plugin_info(self) -> List[Dict[str, Any]]:` |
+| `PluginManager.get_all_plugin_info` | core | web_interface/blueprints/api_v3/plugins.py:68 | review | `all_plugin_info = api_v3.plugin_catalog.get_all_plugin_info()` |
+| `PluginManager.get_all_plugin_info` | core | web_interface/blueprints/pages_v3.py:209 | review | `pi.get('id') for pi in pages_v3.plugin_catalog.get_all_plugin_info()` |
+| `PluginManager.get_all_plugin_info` | core | web_interface/blueprints/pages_v3.py:559 | review | `infos = sorted(pages_v3.plugin_catalog.get_all_plugin_info(),` |
+| `PluginManager.get_all_plugin_info` | core tests | test/test_api_v3_installed_display_modes.py:30 | test review | `api.plugin_catalog.get_all_plugin_info = MagicMock(return_value=[info])` |
+| `PluginManager.get_all_plugin_info` | core tests | test/test_api_v3_installed_plugin_icon.py:24 | test review | `api.plugin_catalog.get_all_plugin_info = MagicMock(return_value=[info])` |
+| `PluginManager.get_all_plugin_info` | core tests | test/test_installed_list_registry_offline.py:71 | test review | `api.plugin_catalog.get_all_plugin_info = MagicMock(return_value=[` |
+| `PluginManager.get_all_plugin_info` | core tests | test/test_onboarding_checklist.py:68 | test review | `mock_pm.get_all_plugin_info.return_value = []` |
+| `PluginManager.get_all_plugin_info` | core tests | test/test_plugin_manager_load_failures.py:78 | test call | `infos = {i["id"]: i for i in pm.get_all_plugin_info()}` |
+| `PluginManager.get_all_plugin_info` | core tests | test/test_plugin_runtime_snapshot.py:422 | test review | `api.plugin_catalog.get_all_plugin_info = MagicMock(return_value=[` |
+| `PluginManager.get_all_plugin_info` | core tests | test/test_vegas_participation.py:447 | test review | `api.plugin_catalog.get_all_plugin_info = MagicMock(return_value=[info])` |
+| `PluginManager.get_all_plugin_info` | core tests | test/test_web_api.py:551 | test review | `mock_plugin_catalog.get_all_plugin_info.return_value = [` |
+| `PluginManager.get_all_plugin_info` | core tests | test/test_web_api.py:570 | test review | `mock_plugin_catalog.get_all_plugin_info.return_value = [` |
+| `PluginManager.get_all_plugin_info` | core tests | test/test_web_api.py:592 | test review | `mock_plugin_catalog.get_all_plugin_info.return_value = [` |
+| `PluginManager.get_all_plugin_info` | core tests | test/test_web_plugin_dir_resolution.py:61 | test review | `api.plugin_catalog.get_all_plugin_info = MagicMock(return_value=[info])` |
+| `PluginManager.get_all_plugin_info` | core tests | test/test_web_plugin_dir_resolution.py:195 | test call | `plugin_manager.get_all_plugin_info.assert_not_called()` |
+| `PluginManager.get_all_plugin_info` | core tests | test/test_web_smoke.py:95 | test review | `mock_pm.get_all_plugin_info.return_value = [` |
+| `PluginManager.get_plugin_display_modes` | core | src/plugin_system/plugin_catalog.py:175 | unrelated | `def get_plugin_display_modes(self, plugin_id: str) -> List[str]:` |
+| `PluginManager.get_plugin_display_modes` | core | web_interface/blueprints/api_v3/display.py:197 | review | `plugin_modes = api_v3.plugin_catalog.get_plugin_display_modes(plugin_id) or [plugin_id]` |
+| `PluginManager.get_plugin_display_modes` | core | web_interface/blueprints/api_v3/display.py:267 | review | `modes = api_v3.plugin_catalog.get_plugin_display_modes(resolved_plugin)` |
+| `PluginManager.get_plugin_display_modes` | core | web_interface/blueprints/api_v3/plugins.py:157 | review | `declared_modes = api_v3.plugin_catalog.get_plugin_display_modes(plugin_id)` |
+| `PluginManager.get_plugin_display_modes` | core | web_interface/blueprints/pages_v3.py:565 | review | `modes = pages_v3.plugin_catalog.get_plugin_display_modes(pid) or [pid]` |
+| `PluginManager.get_plugin_display_modes` | core tests | test/test_api_v3_display_modes.py:40 | test call | `pm.get_plugin_display_modes = MagicMock(` |
+| `PluginManager.get_plugin_display_modes` | core tests | test/test_api_v3_display_modes.py:100 | test call | `pm.get_plugin_display_modes = MagicMock(return_value=[])` |
+| `PluginManager.get_plugin_display_modes` | core tests | test/test_api_v3_display_modes.py:122 | test call | `pm.get_plugin_display_modes = MagicMock(` |
+| `PluginManager.get_plugin_display_modes` | core tests | test/test_api_v3_installed_display_modes.py:31 | test review | `api.plugin_catalog.get_plugin_display_modes = MagicMock(return_value=declared_modes)` |
+| `PluginManager.get_plugin_display_modes` | core tests | test/test_api_v3_installed_display_modes.py:39 | test review | `api.plugin_catalog.get_plugin_display_modes.assert_any_call('football-scoreboard')` |
+| `PluginManager.get_plugin_display_modes` | core tests | test/test_installed_list_registry_offline.py:75 | test review | `api.plugin_catalog.get_plugin_display_modes = MagicMock(return_value=[])` |
+| `PluginManager.get_plugin_display_modes` | core tests | test/test_onboarding_checklist.py:69 | test review | `mock_pm.get_plugin_display_modes.side_effect = lambda pid: []` |
+| `PluginManager.get_plugin_display_modes` | core tests | test/test_web_smoke.py:99 | test review | `mock_pm.get_plugin_display_modes.side_effect = (` |
+| `PluginManager.find_plugin_for_mode` | core | src/plugin_system/plugin_catalog.py:186 | unrelated | `def find_plugin_for_mode(self, mode: str) -> Optional[str]:` |
+| `PluginManager.find_plugin_for_mode` | core | web_interface/blueprints/api_v3/display.py:271 | review | `resolved_plugin = api_v3.plugin_catalog.find_plugin_for_mode(resolved_mode)` |
+| `PluginManager.find_plugin_for_mode` | core | web_interface/blueprints/api_v3/display.py:276 | review | `resolved_plugin = api_v3.plugin_catalog.find_plugin_for_mode(resolved_mode)` |
+| `PluginStateManager.is_loaded` | core | src/plugin_system/plugin_state.py:299 | internal (in `PluginStateManager.get_state_info`) | `'is_loaded': self.is_loaded(plugin_id),` |
+| `PluginStateManager.is_running` | core | src/plugin_system/plugin_state.py:301 | internal (in `PluginStateManager.get_state_info`) | `'is_running': self.is_running(plugin_id),` |
+| `PluginStateManager.is_error` | core | src/plugin_system/plugin_state.py:302 | internal (in `PluginStateManager.get_state_info`) | `'is_error': self.is_error(plugin_id),` |
+| `PluginStateManager.get_error_info` | core | src/plugin_system/plugin_state.py:305 | internal (in `PluginStateManager.get_state_info`) | `'error_info': self.get_error_info(plugin_id),` |
+| `PluginStateManager.get_error_info` | core tests | test/test_async_plugin_updates.py:236 | test call | `error = pm.state_manager.get_error_info(plugin_id)` |
+| `PluginStateManager.get_error_info` | core tests | test/test_plugin_hang_containment.py:191 | test call | `error_info = pm.state_manager.get_error_info('hung')` |
+| `PluginStateManager.get_error_info` | core tests | test/test_sports_sunset_matrix.py:212 | test call | `f"{manager.state_manager.get_error_info(plugin_id)}"` |
+| `PluginStateManager.get_error_info` | core tests | test/test_sports_sunset_matrix.py:285 | test call | `info = manager.state_manager.get_error_info(plugin_id)` |
+| `PluginStateManager.get_last_update` | core | src/plugin_system/plugin_state.py:304 | internal (in `PluginStateManager.get_state_info`) | `'last_update': self.get_last_update(plugin_id),` |
+| `PluginStateManager.get_state_info` | core | src/plugin_system/plugin_manager.py:987 | internal (in `PluginManager.get_plugin_info`) | `info['state'] = self.state_manager.get_state_info(plugin_id)` |
+| `PluginStateManager.get_state_info` | core tests | test/test_plugin_state_transition_count.py:39 | test review | `info = manager.get_state_info("clock")` |
+| `PluginStateManager.get_state_info` | core tests | test/test_plugin_state_transition_count.py:51 | test review | `info = manager.get_state_info("clock")` |
+| `PluginStateManager.get_state_info` | core tests | test/test_plugin_state_transition_count.py:62 | test review | `assert manager.get_state_info("clock")["state_history_count"] == 101` |
+| `PluginStateManager.get_state_info` | core tests | test/test_plugin_state_transition_count.py:63 | test review | `assert manager.get_state_info("weather")["state_history_count"] == 1` |
+| `PluginStateManager.get_state_info` | core tests | test/test_plugin_state_transition_count.py:74 | test review | `info = manager.get_state_info("clock")` |
+| `PluginStateManager.get_state_info` | core tests | test/test_plugin_state_transition_count.py:95 | test review | `info = m.get_state_info("clock")` |
+| `PluginStateManager.get_state_info` | core tests | test/test_plugin_state_transition_count.py:130 | test review | `info = manager.get_state_info("clock")` |
+
+## Sources scanned
+
+| Source | Group | Python files | Hits |
+|---|---|---|---|
+| core | core | 188 | 50 |
+| core tests | core-tests | 416 | 176 |
+| 7-segment-clock | monorepo | 3 | 0 |
+| afl-scoreboard | monorepo | 36 | 0 |
+| baseball-scoreboard | monorepo | 71 | 0 |
+| basketball-scoreboard | monorepo | 51 | 2 |
+| birdnet-go | monorepo | 3 | 0 |
+| blackjack | monorepo | 7 | 0 |
+| calendar | monorepo | 5 | 0 |
+| christmas-countdown | monorepo | 3 | 0 |
+| clock-simple | monorepo | 2 | 0 |
+| countdown | monorepo | 5 | 0 |
+| cricket-scoreboard | monorepo | 8 | 1 |
+| f1-scoreboard | monorepo | 15 | 0 |
+| fantasy-blitz | monorepo | 13 | 0 |
+| football-scoreboard | monorepo | 78 | 4 |
+| geochron | monorepo | 10 | 0 |
+| hello-world | monorepo | 2 | 0 |
+| hockey-scoreboard | monorepo | 57 | 3 |
+| incoming-packages | monorepo | 8 | 0 |
+| jellyfin-now-playing | monorepo | 4 | 0 |
+| lacrosse-scoreboard | monorepo | 41 | 0 |
+| ledmatrix-elections | monorepo | 12 | 0 |
+| ledmatrix-flights | monorepo | 48 | 0 |
+| ledmatrix-leaderboard | monorepo | 10 | 0 |
+| ledmatrix-music | monorepo | 12 | 0 |
+| ledmatrix-stocks | monorepo | 7 | 0 |
+| ledmatrix-weather | monorepo | 15 | 0 |
+| march-madness | monorepo | 4 | 0 |
+| masters-tournament | monorepo | 10 | 0 |
+| mqtt-notifications | monorepo | 4 | 0 |
+| news | monorepo | 7 | 0 |
+| nfl-draft | monorepo | 3 | 0 |
+| nfl-stat-leaders | monorepo | 8 | 0 |
+| nrl-scoreboard | monorepo | 31 | 1 |
+| odds-ticker | monorepo | 10 | 0 |
+| of-the-day | monorepo | 14 | 0 |
+| olympics | monorepo | 16 | 0 |
+| on-air | monorepo | 3 | 0 |
+| pomodoro-timer | monorepo | 3 | 0 |
+| soccer-scoreboard | monorepo | 50 | 0 |
+| static-image | monorepo | 4 | 0 |
+| stock-news | monorepo | 4 | 0 |
+| text-display | monorepo | 4 | 0 |
+| tide-display | monorepo | 3 | 0 |
+| ufc-scoreboard | monorepo | 40 | 3 |
+| 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
-display_manager.draw_weather_icon("rain", x=10, y=10, size=16)
+# 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)
@@ -72,20 +72,23 @@ cache_manager.delete("key")       # alias for clear_cache(key)
 
 # Advanced caching
 data = cache_manager.get_cached_data_with_strategy("key", data_type="weather")
-data = cache_manager.get_background_cached_data("key", sport_key="nhl")
 
 # Strategy
 strategy = cache_manager.get_cache_strategy("weather")
-interval = cache_manager.get_sport_live_interval("nhl")
 ```
 
+`get_background_cached_data()` (use `get()`) and `get_sport_live_interval()`
+were removed in 3.8.0. See
+[Deprecated APIs](PLUGIN_API_REFERENCE.md#deprecated-apis).
+
 ## Plugin Manager Quick Methods
 
 ```python
 # Get plugins
 plugin = plugin_manager.get_plugin("plugin-id")
 all_plugins = plugin_manager.get_all_plugins()
-enabled = plugin_manager.get_enabled_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")
@@ -168,7 +171,7 @@ def display(self, force_clear=False):
 
 - [ ] Plugin inherits from `BasePlugin`
 - [ ] Implements `update()` and `display()` methods
-- [ ] `manifest.json` with required fields
+- [ ] `manifest.json` with the [required fields](PLUGIN_API_REFERENCE.md#manifest-required-fields)
 - [ ] `config_schema.json` for web UI (recommended)
 - [ ] `README.md` with documentation
 - [ ] Error handling implemented

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.7 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.7+
+- Python 3.11+
 - pip (Python package manager)
 - Git (for plugin management)
 
@@ -50,8 +50,7 @@ pip install -r requirements-emulator.txt
 ```
 
 This installs:
-- `RGBMatrixEmulator` - The core emulation library
-- Additional dependencies for display adapters
+- `RGBMatrixEmulator` - the emulation library (and whatever it depends on)
 
 ### 3. Install Standard Dependencies
 
@@ -63,8 +62,9 @@ pip install -r requirements.txt
 
 ### 1. Emulator Configuration File
 
-The emulator uses `emulator_config.json` for configuration. Here's the
-default configuration as it ships in the repo:
+The emulator uses `emulator_config.json` for configuration. It isn't in
+the repo (it's gitignored): RGBMatrixEmulator writes it on first run.
+A typical file looks like this:
 
 ```json
 {

docs/FONT_MANAGER.md

@@ -9,12 +9,13 @@
 
 ## Overview
 
-The enhanced FontManager provides comprehensive font management for the LEDMatrix application with support for:
-- Manager font registration and detection
-- Plugin font management
-- Programmatic per-element font overrides
-- Performance monitoring and caching
-- Dynamic font discovery
+[`src/font_manager.py`](../src/font_manager.py) loads and caches the TTF and
+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 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
 
@@ -34,157 +35,60 @@ standalone FontManager when none is available (test harnesses, mocks).
 `DisplayManager` has **no** `font_manager` attribute —
 `display_manager.font_manager` raises `AttributeError`.
 
-## Architecture
-
-### Manager-Centric Design
-
-Managers define their own fonts, but the FontManager:
-1. **Loads and caches fonts** for performance
-2. **Detects font usage** for visibility
-3. **Allows manual overrides** when needed
-4. **Supports plugin fonts** with namespacing
-
-### Font Resolution Flow
-
-```
-Manager requests font → Check manual overrides → Apply manager choice → Cache & return
-```
-
-## For Manager Developers
-
-### Basic Font Usage
+## Resolving a font
 
 ```python
-from src.font_manager import FontManager
+element_key = f"{self.plugin_id}.title"
 
-class MyManager:
-    def __init__(self, config, display_manager, cache_manager, plugin_manager):
-        self.display_manager = display_manager
-        self.font_manager = plugin_manager.font_manager  # Shared FontManager
-        self.manager_id = "my_manager"
-        
-    def display(self):
-        # Define your font choices
-        element_key = "my_manager.title"
-        font_family = "press_start"
-        font_size_px = 10
-        color = (255, 255, 255)  # RGB white
-        
-        # Register your font choice (for detection and future overrides)
-        self.font_manager.register_manager_font(
-            manager_id=self.manager_id,
-            element_key=element_key,
-            family=font_family,
-            size_px=font_size_px,
-            color=color
-        )
-        
-        # Get the font (checks for manual overrides automatically)
-        font = self.font_manager.resolve_font(
-            element_key=element_key,
-            family=font_family,
-            size_px=font_size_px
-        )
-        
-        # Use the font for rendering
-        self.display_manager.draw_text(
-            "Hello World",
-            x=10, y=10,
-            color=color,
-            font=font
-        )
-```
-
-### Advanced Font Usage
-
-```python
-class AdvancedManager:
-    def __init__(self, config, display_manager, cache_manager, plugin_manager):
-        self.display_manager = display_manager
-        self.font_manager = plugin_manager.font_manager
-        self.manager_id = "advanced_manager"
-        
-        # Define your font specifications
-        self.font_specs = {
-            "title": {"family": "press_start", "size_px": 12, "color": (255, 255, 0)},
-            "body": {"family": "four_by_six", "size_px": 8, "color": (255, 255, 255)},
-            "footer": {"family": "five_by_seven", "size_px": 7, "color": (128, 128, 128)}
-        }
-        
-        # Register all font specs
-        for element_type, spec in self.font_specs.items():
-            element_key = f"{self.manager_id}.{element_type}"
-            self.font_manager.register_manager_font(
-                manager_id=self.manager_id,
-                element_key=element_key,
-                family=spec["family"],
-                size_px=spec["size_px"],
-                color=spec["color"]
-            )
-    
-    def get_font(self, element_type: str):
-        """Helper method to get fonts with override support."""
-        spec = self.font_specs[element_type]
-        element_key = f"{self.manager_id}.{element_type}"
-        
-        return self.font_manager.resolve_font(
-            element_key=element_key,
-            family=spec["family"],
-            size_px=spec["size_px"]
-        )
-    
-    def display(self):
-        # Get fonts (automatically checks for overrides)
-        title_font = self.get_font("title")
-        body_font = self.get_font("body")
-        footer_font = self.get_font("footer")
-        
-        # Render with fonts
-        self.display_manager.draw_text("Title", font=title_font, color=self.font_specs["title"]["color"])
-        self.display_manager.draw_text("Body Text", font=body_font, color=self.font_specs["body"]["color"])
-        self.display_manager.draw_text("Footer", font=footer_font, color=self.font_specs["footer"]["color"])
-```
-
-### Using Size Tokens
-
-```python
-# Get available size tokens
-tokens = self.font_manager.get_size_tokens()
-# Returns: {'xs': 6, 'sm': 8, 'md': 10, 'lg': 12, 'xl': 14, 'xxl': 16}
-
-# Use token to get size
-size_px = tokens.get('md', 10)  # 10px
-
-# Then use in font resolution
-font = self.font_manager.resolve_font(
-    element_key="my_manager.text",
+# Register the choice so the web UI's Fonts tab can list it.
+self.font_manager.register_manager_font(
+    manager_id=self.plugin_id,
+    element_key=element_key,
     family="press_start",
-    size_px=size_px
+    size_px=10,
+    color=(255, 255, 255),
 )
+
+font = self.font_manager.resolve_font(
+    element_key=element_key,
+    family="press_start",
+    size_px=10,
+)
+self.display_manager.draw_text("Hello", x=10, y=10, font=font)
 ```
 
-## For Plugin Developers
+`resolve_font()` applies any entry for `element_key` in
+`config/font_overrides.json`, maps a plugin-local family to its namespaced
+name when `plugin_id` is passed, and then calls `get_font(family, size_px)`.
+On error it returns a fallback font rather than raising.
 
-> **Note**: plugins that ship their own fonts via a `"fonts"` block
-> in `manifest.json` are registered automatically during plugin load
-> (`src/plugin_system/plugin_manager.py` calls
-> `FontManager.register_plugin_fonts()`). The `plugin://…` source
-> URIs documented below are resolved relative to the plugin's
-> install directory.
->
-> The web UI's **Fonts** tab lists, uploads, previews and deletes the
-> font files in `assets/fonts/`. Its **Used by** column shows which
-> loaded plugins registered each file through `register_manager_font()`
-> (see [Font usage in the web UI](#font-usage-in-the-web-ui)), and it
-> warns before deleting one of them. It has no override editor (the
-> override panels and `/api/v3/fonts/overrides` endpoints were removed).
-> The programmatic override workflow in
-> [Manual Font Overrides](#manual-font-overrides) below still works.
-> Let users pick fonts through your plugin's own config schema.
+`get_font(family, size_px)` looks the family up in `font_catalog` and loads
+it (cached per family and size).
 
-### Plugin Font Registration
+## Font families
 
-In your plugin's `manifest.json`:
+At start-up the FontManager scans `assets/fonts/` for `.ttf` and `.bdf`
+files. Each becomes a family named after the file, lower-cased and without
+the extension (`PressStart2P-Regular.ttf` → `pressstart2p-regular`). Four
+aliases are added on top:
+
+| Alias | File |
+|---|---|
+| `press_start` | `assets/fonts/PressStart2P-Regular.ttf` |
+| `four_by_six` | `assets/fonts/4x6-font.ttf` |
+| `five_by_seven` | `assets/fonts/5x7.bdf` |
+| `tom_thumb` | `assets/fonts/tom-thumb.bdf` |
+
+Read the catalog directly: `font_manager.font_catalog` is a dict of family
+name to file path. Files added later are picked up on the next start of the
+display service.
+
+## Plugin fonts
+
+Plugins that ship their own fonts declare them in a `"fonts"` block in
+`manifest.json`. The plugin manager calls
+`FontManager.register_plugin_fonts()` during plugin load. `plugin://…`
+sources are resolved relative to the plugin's install directory.
 
 ```json
 {
@@ -195,231 +99,126 @@ In your plugin's `manifest.json`:
       {
         "family": "custom_font",
         "source": "plugin://fonts/custom.ttf",
-        "metadata": {
-          "description": "Custom plugin font",
-          "license": "MIT"
-        }
+        "metadata": {"description": "Custom plugin font", "license": "MIT"}
       },
       {
         "family": "web_font",
         "source": "https://example.com/fonts/font.ttf",
-        "metadata": {
-          "description": "Downloaded font",
-          "checksum": "sha256:abc123..."
-        }
+        "metadata": {"checksum": "sha256:abc123..."}
       }
     ]
   }
 }
 ```
 
-### Using Plugin Fonts
+Registered families are namespaced as `<plugin_id>::<family>`. Pass
+`plugin_id` to `resolve_font()` to use the short name:
 
 ```python
-class MyPlugin(BasePlugin):
-    def __init__(self, plugin_id, config, display_manager, cache_manager, plugin_manager):
-        super().__init__(plugin_id, config, display_manager, cache_manager, plugin_manager)
-        self.font_manager = self._get_font_manager()
-        
-    def display(self):
-        # Use plugin font (automatically namespaced)
-        font = self.font_manager.resolve_font(
-            element_key=f"{self.plugin_id}.text",
-            family="custom_font",  # Will be resolved as "my-plugin::custom_font"
-            size_px=10,
-            plugin_id=self.plugin_id
-        )
-        
-        self.display_manager.draw_text("Plugin Text", font=font)
-```
-
-## Manual Font Overrides
-
-Overrides are set in code (there is no web UI or REST endpoint for them).
-They are stored in `config/font_overrides.json` and persist across restarts.
-
-### Programmatic Overrides
-
-```python
-# Set override
-font_manager.set_override(
-    element_key="nfl.live.score",
-    family="four_by_six",
-    size_px=8
+font = self.font_manager.resolve_font(
+    element_key=f"{self.plugin_id}.text",
+    family="custom_font",          # resolved as "my-plugin::custom_font"
+    size_px=10,
+    plugin_id=self.plugin_id,
 )
-
-# Remove override
-font_manager.remove_override("nfl.live.score")
-
-# Get all overrides
-overrides = font_manager.get_overrides()
 ```
 
-## Font Discovery
+## Overrides
 
-### Available Fonts
-
-The FontManager automatically scans `assets/fonts/` for TTF and BDF fonts:
-
-```python
-# Get all available fonts
-fonts = font_manager.get_available_fonts()
-# Returns: {'press_start': 'assets/fonts/PressStart2P-Regular.ttf', ...}
-
-# Check if font exists
-if "my_font" in fonts:
-    font = font_manager.get_font("my_font", 10)
-```
-
-### Adding Custom Fonts
-
-Place font files in `assets/fonts/` directory:
-- Supported formats: `.ttf`, `.bdf`
-- Font family name is derived from filename (without extension)
-- Will be automatically discovered on next initialization
+`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 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.
 
 ## Font usage in the web UI
 
-The web interface runs in its own process and has no FontManager, so the
-display service publishes which plugin uses which font
-(`src/font_usage.py`), and the Fonts tab's **Used by** column reads it:
+The web UI's **Fonts** tab lists, uploads, previews and deletes the font
+files in `assets/fonts/`. The web interface runs in its own process and has
+no FontManager, so the display service publishes which plugin uses which
+font ([`src/font_usage.py`](../src/font_usage.py)), and the tab's **Used by**
+column reads it:
 
 - **Source**: `register_manager_font()` registrations of the loaded
   plugins. `get_font()` and `resolve_font()` do not know the calling plugin
   and are not counted, and neither is a plugin that opens a font file
   directly with PIL — register the fonts your plugin draws with if you want
   them listed.
-- **Names**: a family, alias (`press_start`, `four_by_six`,
-  `five_by_seven`, `tom_thumb`) or path is resolved through
-  `font_catalog` to the file it loads and reported under that file's name
-  without extension (`PressStart2P-Regular`, `4x6-font`, `5x7`,
-  `tom-thumb`), which is how the Fonts tab keys its rows. Fonts outside
-  `assets/fonts/` (a plugin's own `plugin_id::family` fonts) and families
-  that resolve to nothing are left out.
+- **Names**: a family, alias or path is resolved through `font_catalog` to
+  the file it loads and reported under that file's name without extension
+  (`PressStart2P-Regular`, `4x6-font`, `5x7`, `tom-thumb`), which is how the
+  Fonts tab keys its rows. Fonts outside `assets/fonts/` (a plugin's own
+  `plugin_id::family` fonts) and families that resolve to nothing are left
+  out.
 - **When**: a daemon thread started once plugins have loaded checks every
   10 seconds and writes the `font_usage_snapshot` cache key only when the
   usage changed (and once a day, so the cache's cleanup never expires it).
   Unloading a plugin drops its registrations (`forget_manager_fonts`).
 - **Unknown**: until the display service has published, the column reads
   "unknown" and `GET /api/v3/fonts/catalog` returns `used_by: null`.
+- The tab warns before deleting a font that a loaded plugin registered.
 
-## Performance Monitoring
+## Text measurement
 
 ```python
-# Get performance stats
-stats = font_manager.get_performance_stats()
-
-print(f"Cache hit rate: {stats['cache_hit_rate']*100:.1f}%")
-print(f"Total fonts cached: {stats['total_fonts_cached']}")
-print(f"Failed loads: {stats['failed_loads']}")
-print(f"Manager fonts: {stats['manager_fonts']}")
-print(f"Plugin fonts: {stats['plugin_fonts']}")
-```
-
-## Text Measurement
-
-```python
-# Measure text dimensions
 width, height, baseline = font_manager.measure_text("Hello", font)
-
-# Get font height
 font_height = font_manager.get_font_height(font)
 ```
 
-## Best Practices
+## Tips
 
-### For Managers
-
-1. **Register all fonts** you use for visibility
-2. **Use consistent element keys** (e.g., `{manager_id}.{element_type}`)
-3. **Cache font references** if using same font multiple times
-4. **Use `resolve_font()`** not `get_font()` directly to support overrides
-5. **Define sensible defaults** that work well on LED matrix
-
-### For Plugins
-
-1. **Use plugin-relative paths** (`plugin://fonts/...`)
-2. **Include font metadata** (license, description)
-3. **Provide fallback** fonts if custom fonts fail to load
-4. **Test with different display sizes**
-
-### General
-
-1. **BDF fonts** are often better for small sizes on LED matrices
-2. **TTF fonts** work well for larger sizes
-3. **Monospace fonts** are easier to align
-4. **Test on actual hardware** - what looks good on screen may not work on LED matrix
-
-## Migration from Old System
-
-### Old Way (Direct Font Loading)
-```python
-self.font = ImageFont.truetype("assets/fonts/PressStart2P-Regular.ttf", 8)
-```
-
-### New Way (FontManager)
-```python
-element_key = f"{self.manager_id}.text"
-self.font_manager.register_manager_font(
-    manager_id=self.manager_id,
-    element_key=element_key,
-    family="pressstart2p-regular",
-    size_px=8
-)
-self.font = self.font_manager.resolve_font(
-    element_key=element_key,
-    family="pressstart2p-regular",
-    size_px=8
-)
-```
+- BDF fonts usually look better than TTF at small sizes on LED panels.
+- Use `{plugin_id}.{element}` element keys.
+- Register the fonts you draw with, so the Fonts tab can warn before one is
+  deleted.
+- Replace direct `ImageFont.truetype("assets/fonts/...", 8)` calls with
+  `resolve_font()`: it caches, resolves paths against the install directory,
+  and handles BDF files.
 
 ## Troubleshooting
 
-### Font Not Found
-- Check font file exists in `assets/fonts/`
-- Verify font family name matches filename (without extension, lowercase)
-- Check logs for font discovery errors
+**Font not found**
+- Check the file exists in `assets/fonts/`.
+- The family name is the filename without extension, lower-cased.
+- Check the display service log for font discovery errors.
 
-### Override Not Working
-- Verify element key matches exactly what manager registered
-- Check `config/font_overrides.json` for correct syntax
-- Restart application to ensure overrides are loaded
+**Plugin fonts not loading**
+- Check the manifest's `"fonts"` block.
+- Check the log for download or registration errors, and that font URLs are
+  reachable.
 
-### Performance Issues
-- Check cache hit rate in performance stats
-- Reduce number of unique font/size combinations
-- Clear cache if it grows too large: `font_manager.clear_cache()`
+## API reference
 
-### Plugin Fonts Not Loading
-- Verify plugin manifest syntax
-- Check plugin directory structure
-- Review logs for download/registration errors
-- Ensure font URLs are accessible
+Current methods:
 
-## API Reference
+| Method | Purpose |
+|---|---|
+| `register_manager_font(manager_id, element_key, family, size_px, color=None)` | Record a font choice (feeds the Fonts tab) |
+| `forget_manager_fonts(manager_id)` | Drop a manager's registrations (core calls it when a plugin unloads) |
+| `resolve_font(element_key, family, size_px, plugin_id=None)` | Get a font, applying overrides and plugin namespacing |
+| `get_font(family, size_px)` | Get a font directly |
+| `get_native_bdf_size(family)` | Native pixel size of a BDF family, or `None` |
+| `measure_text(text, font)` | `(width, height, baseline)` |
+| `get_font_height(font)` | Line height |
+| `register_plugin_fonts(plugin_id, font_manifest)` | Register a plugin's fonts (core calls it at load) |
+| `forget_plugin_fonts(plugin_id)` | Drop a plugin's manifest fonts and their cached objects (core calls it when a plugin unloads) |
+| `clear_cache()` | Drop cached fonts and metrics |
+| `font_catalog` (attribute) | Family name → file path |
 
-### FontManager Methods
+### Removed methods
 
-- `register_manager_font(manager_id, element_key, family, size_px, color=None)` - Register font usage
-- `forget_manager_fonts(manager_id)` - Drop a manager's registrations (core calls it when a plugin unloads)
-- `resolve_font(element_key, family, size_px, plugin_id=None)` - Get font with override support
-- `get_font(family, size_px)` - Get font directly (bypasses overrides)
-- `measure_text(text, font)` - Measure text dimensions
-- `get_font_height(font)` - Get font height
-- `set_override(element_key, family=None, size_px=None)` - Set manual override
-- `remove_override(element_key)` - Remove override
-- `get_overrides()` - Get all overrides
-- `get_detected_fonts()` - Get all detected font usage
-- `get_manager_fonts(manager_id=None)` - Get fonts by manager
-- `get_available_fonts()` - Get font catalog
-- `get_size_tokens()` - Get size token definitions
-- `get_performance_stats()` - Get performance metrics
-- `clear_cache()` - Clear font cache
-- `register_plugin_fonts(plugin_id, font_manifest)` - Register plugin fonts
-- `unregister_plugin_fonts(plugin_id)` - Unregister plugin fonts
-
-## Example: Complete Manager Implementation
-
-For a working example of the font manager API in use, see
-`src/font_manager.py` itself.
+Removed in 3.8.0, after logging a deprecation warning on first call since
+3.5.0.
 
+| Method | Use instead |
+|---|---|
+| `get_available_fonts()`, `get_font_catalog()` | read `font_catalog` |
+| `get_size_tokens()` | pass a pixel size |
+| `get_performance_stats()` | — |
+| `set_override()`, `remove_override()`, `get_overrides()` | a font field in your plugin's config schema |
+| `get_manager_fonts()`, `get_detected_fonts()` | — |
+| `get_plugin_fonts()` | — |
+| `unregister_plugin_fonts()` | `forget_plugin_fonts()` (core calls it on unload) |
+| `add_font()`, `remove_font()`, `validate_font()` | the web UI's Fonts tab |

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
@@ -116,8 +134,8 @@ weather and other location-aware plugins.
 4. Wait for installation to finish — installed plugins appear in the
    **Installed Plugins** section above and get their own tab in the second
    nav row
-5. Toggle the plugin to enabled
-6. From **Overview**, click **Restart Display Service**
+5. Toggle the plugin to enabled. The running display loads it within a
+   few seconds; no restart is needed
 
 You can also install community plugins straight from a GitHub URL using the
 **Install from GitHub** section further down the same tab — see
@@ -128,9 +146,9 @@ You can also install community plugins straight from a GitHub URL using the
 1. Each installed plugin gets its own tab in the second navigation row
 2. Open that plugin's tab to edit its settings (favorite teams, API keys,
    update intervals, etc.)
-3. Click **Save**
-4. Restart the display service from **Overview** so the new settings take
-   effect
+3. Click **Save**. The display service watches `config.json` and hands the
+   new settings to the running plugin, so no restart is needed. If a plugin
+   still shows old settings, restart the display service from **Overview**
 
 **Note:** how long each plugin stays on screen is not set in the
 plugin's own tab — use the **Rotation** tab's **Screen Durations**
@@ -197,14 +215,15 @@ The fastest way to verify a plugin works without waiting for the rotation:
 
 **Check:**
 1. Plugin is enabled (toggle on the **Plugin Manager** tab)
-2. Display service was restarted after enabling
-3. Plugin's display duration is non-zero
-4. No errors in the **Logs** tab for that plugin
+2. Plugin's display duration is non-zero
+3. No errors in the **Logs** tab for that plugin. A plugin whose
+   `validate_config()` fails is not loaded until its settings are fixed
 
 **Fix:**
 1. Enable the plugin from **Plugin Manager**
-2. Click **Restart Display Service** on **Overview**
-3. Check the **Logs** tab for plugin-specific errors
+2. Check the **Logs** tab for plugin-specific errors
+3. If it still does not appear, click **Restart Display Service** on
+   **Overview**
 
 ### Weather Plugin Shows "No Data"
 
@@ -239,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

@@ -52,10 +52,10 @@ pytest test/test_display_controller.py test/test_plugin_system.py
 
 ```bash
 # Run a specific test class
-pytest test/test_display_controller.py::TestDisplayControllerModeRotation
+pytest test/test_display_controller.py::TestDisplayControllerLivePriority
 
 # Run a specific test function
-pytest test/test_display_controller.py::TestDisplayControllerModeRotation::test_basic_rotation
+pytest test/test_display_controller.py::TestDisplayControllerSchedule::test_active_hours
 ```
 
 ### Run Tests by Marker
@@ -98,7 +98,7 @@ When you run `pytest`, you'll see:
 
 ```
 test/test_display_controller.py::TestDisplayControllerInitialization::test_init_success PASSED
-test/test_display_controller.py::TestDisplayControllerModeRotation::test_basic_rotation PASSED
+test/test_display_controller.py::TestDisplayControllerOnDemand::test_activate_on_demand PASSED
 ...
 ```
 
@@ -170,14 +170,39 @@ 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
 # Run with maximum verbosity and show print statements
-pytest -vv -s test/test_display_controller.py::TestDisplayControllerModeRotation::test_basic_rotation
+pytest -vv -s test/test_display_controller.py::TestDisplayControllerSchedule::test_active_hours
 
 # Run with Python debugger (pdb)
-pytest --pdb test/test_display_controller.py::TestDisplayControllerModeRotation::test_basic_rotation
+pytest --pdb test/test_display_controller.py::TestDisplayControllerSchedule::test_active_hours
 ```
 
 ### Run Tests in Parallel (Faster)

docs/IPC_CONTROL_SOCKET.md

@@ -0,0 +1,742 @@
+# 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. Stage 4 makes the socket the only way a command goes
+while it works: the web interface writes a mailbox only when the socket
+cannot carry the request, `errors.clear` replaces the last command that
+always went through a mailbox, and the display looks at the mailboxes once
+a second, with a `stat()`. The file mailboxes 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), `POST /api/v3/errors/clear`; 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 |
+| `errors.clear` | `{cutoff: number}` (epoch seconds, finite, ≥ 0) | `{request_id, cutoff, cleared}` | answered directly, once applied |
+
+`errors.clear` (stage 4) forgets the plugin errors the display recorded at
+or before `cutoff` and rewrites its error snapshot (`plugin_error_snapshot`)
+before it answers, so the web interface's next read already has it. The
+request `id` is the clear's id, which the snapshot reports as
+`applied_clear_id`. It is answered on the connection thread by a handler the
+display registers (`ControlServer(handlers=...)`, the contract's
+`DIRECT_COMMANDS`): the error aggregator and its publisher have their own
+locks, and nothing the render thread owns is touched. A display that has no
+handler answers `unknown_command`, as an older display does.
+
+`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 (the frame loops through the Arbiter's
+  mid-screen check, `Source.RELOAD`; the dwell through
+  `_plugin_reload_pending`).
+- 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 floor on the mailbox read (0.25 s, 1 s since stage 4) 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
+is slower on purpose (see "The mailboxes now"). 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.** Since stage 4 the web interface writes the mailbox only
+when the display never had the request (see "When the web interface falls
+back"), so a request goes one way or the other, never both. A command and a
+mailbox write for the same request still share one `request_id`, and the
+`on_demand_request_id` and processed-id checks still drop a second copy: an
+older web interface (before stage 4) wrote the mailbox after a reply timed
+out, too. The display takes such a copy out of the mailbox when it drops it.
+
+## When the web interface falls back (stage 4)
+
+The client tells a request the display never had from one it had and then
+failed. `ControlError.sent` is True once the whole request was written to a
+connected display; a refusal the display sends before reading anything
+(`forbidden`, too many connections) carries no request id, and leaves it
+False. `src.ipc.client.should_fall_back()` is the one rule every route uses:
+
+| What happened | Example reasons | Mailbox? | The route answers |
+|---|---|---|---|
+| The display never had it | `no_socket`, `refused`, `disabled`, `unsupported`, a connect or send that timed out, `forbidden` / `busy` at the door, `invalid_request` (refused by the client itself) | yes | success, `transport: "mailbox"`, `socket_error` |
+| A display too old to know it (the upgrade case) | `unknown_command`, `unsupported_version` | yes | as above |
+| The display had it and failed | `busy` (queue full), `invalid_args`, `internal`, a timeout or hang-up after the send, `bad_response` | no | `503` (`400` for `invalid_args`), `socket_error` |
+
+A display that had the request may have applied it (a reply that timed out),
+or would refuse the mailbox copy as well (bad arguments), or is stuck and
+would not read the mailbox either (a full queue). Writing the copy anyway
+only turned that into a "success". An on-demand stop with `stop_service`
+still stops the service, which ends on-demand whatever happened.
+
+Brightness and plugin reload never had a mailbox: without the socket, the
+config watcher applies the saved brightness and a reload becomes the
+restart banner, as before.
+
+### The mailboxes now
+
+| Mailbox | Written by | Read by the display | While the socket is up |
+|---|---|---|---|
+| `display_on_demand_request` | the web interface, only on fallback; plugins that predate `BasePlugin.request_on_demand()`, or run on a core without it | the render thread, `_poll_on_demand_requests()` | looked at every 1 s (`MAILBOX_POLL_INTERVAL_WITH_SOCKET`), 0.25 s without a socket |
+| `plugin_error_clear_request` | the web interface, only on fallback | the error publisher's thread, every 5 s tick | unchanged rate |
+
+A look is one `stat()` of the mailbox file (`CacheManager.file_signature`):
+`(inode, mtime, size)`, and every write renames a new file into place, so a
+new write always looks different. `MailboxWatch` reads the file only when
+that changed since the last look, so a mailbox that holds nothing new, or
+nothing at all, costs no open and no parse. A socket command never reads or
+deletes the on-demand mailbox. A start already processed is taken out of
+the mailbox instead of being re-read until it expires.
+
+A request that comes through the on-demand mailbox while the socket is up
+is logged once per writer (`came through the file mailbox although the
+control socket is up`), which names the plugins that still write it.
+
+### Plugins in the display process
+
+A plugin asks for the screen with `BasePlugin.request_on_demand()` and gives
+it back with `end_on_demand()` (see "On-demand display" in
+[PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md)). Neither goes through
+the socket or a file: `PluginManager` hands the mailbox-shaped request,
+marked `source: 'plugin'`, to `DisplayController.submit_plugin_on_demand`,
+which queues it in memory (at most `PLUGIN_ON_DEMAND_QUEUE_SIZE`, 32) from
+whatever thread the plugin called on, and wakes the render thread through
+the socket's queue flag (`ControlServer.wake()`). The render thread applies
+it in `_drain_control_commands`, after the socket's commands, through the
+same `_handle_on_demand_request`, so it lands within a frame like a socket
+command. Without a socket it lands on the next pending-changes pass (typically
+within 0.25 s). A plugin's stop ends only a session that plugin owns. The four
+plugins that wrote the mailbox (birdnet-go, mqtt-notifications, on-air,
+pomodoro-timer) use it where the core has it and write the mailbox
+otherwise.
+
+## 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 the web
+  interface answers `503` rather than write the mailbox, which the stuck
+  render thread would not read either. 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. **The mailboxes become a fallback (done).**
+   - The web interface writes a mailbox only when the socket could not carry
+     the request (`should_fall_back`); a display that had it and failed is
+     answered as that (see "When the web interface falls back").
+   - `errors.clear` replaces `plugin_error_clear_request` as the way a clear
+     reaches the display.
+   - The display looks at the on-demand mailbox once a second while the
+     socket is up, reads either mailbox only when its file changed, and logs
+     who still writes the on-demand one (see "The mailboxes now").
+   - Not changed, deliberately: config saves (the schedule, the dim
+     schedule, plugin settings) still reach the display through
+     `config.json` and its watcher, which is the setting itself rather than
+     a message; see `config.reload` under stage 2. The preview viewer marker
+     (`/tmp/led_matrix_preview_viewer`) is a presence signal the display
+     already stats at most once a second. Plugin health and metrics resets
+     write the persisted record the display publishes and do not reach the
+     running display (their routes say so); they are not mailboxes.
+5. **Remove the mailboxes (next release).** Once every device has run a
+   display with stage 4, the web interface stops writing both mailboxes and
+   the display stops reading them. The four plugins that wrote
+   `display_on_demand_request` now have an in-process way to ask for the
+   screen (`BasePlugin.request_on_demand()` / `end_on_demand()`, see
+   "Plugins in the display process"); they keep the mailbox write only as
+   their fallback on older cores. 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. A `503`
+with `"transport": "socket"` means the display had the request and did not
+take it (`busy`, `timeout`, ...): nothing was written to the mailbox.
+
+An error clear:
+
+```bash
+curl -s -X POST localhost:5000/api/v3/errors/clear \
+  -H 'Content-Type: application/json' -d '{"all":true}'
+# ... "applied": true, "transport": "socket"
+sudo journalctl -u ledmatrix | grep -E "Cleared .* plugin error|file mailbox"
+```
+
+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/MULTI_ROOT_WORKSPACE_SETUP.md

@@ -44,8 +44,8 @@ and symlink the plugin directories you are working on into LEDMatrix's
 ### 1. The plugin monorepo
 
 Clone ledmatrix-plugins into the same parent directory as LEDMatrix (the
-workspace file and `scripts/update_plugin_repos.py` look for
-`../ledmatrix-plugins` relative to the LEDMatrix root):
+workspace file looks for `../ledmatrix-plugins` relative to the LEDMatrix
+root):
 
 ```bash
 cd ~/Github
@@ -86,7 +86,7 @@ the plugin from there. See the
 
 ```bash
 cd ~/Github/LEDMatrix
-python3 scripts/update_plugin_repos.py      # git pull in ../ledmatrix-plugins
+git -C ../ledmatrix-plugins pull            # the sibling monorepo checkout
 # or
 ./scripts/dev/dev_plugin_setup.sh update    # git pull in every linked checkout
 ```

docs/OFFSCREEN_RENDERING.md

@@ -0,0 +1,354 @@
+# Offscreen Rendering
+
+**Status (2026-09-30):** offscreen rendering is implemented
+(`DisplayManager.offscreen()`, the adapter on the prefetch thread, the plugin
+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):
+
+| build | late | by 1 | 2 | 3–5 | 6+ | freezes | render-thread fetches |
+|---|---|---|---|---|---|---|---|
+| #628 | 0.53% | 82 | 2 | 3 | 2 | 3 | 6 |
+| step 1 | 0.63% | 78 | 63 | 17 | 2 | 1 | 0 |
+| step 1 | 0.42% | 77 | 23 | 10 | 0 | 0 | 0 |
+| #628 | 0.37% | 84 | 5 | 3 | 3 | 2 | 14 |
+
+It does what it was built to: no plugin is fetched on the render thread, and
+freezes fell from 5 to 1. But frames 2–5 refreshes late rose. The rendering
+moved to the prefetch thread still needs the GIL, and the render thread waits
+for it (risk 5 below). The late rate did not improve overall. The 1–2 s
+freezes appear in both builds and have a separate, not yet identified cause.
+
+The GIL fix, measured on hdpi (90 px/s, `pwm_bits` 8, preview open, 8-minute
+runs after a 2-minute warm-up, order A B C C B A, 2026-09-24). Each arm pools
+two runs, about 81,000 frames:
+
+| arm | late | by 1 | 2 | 3–5 | 6+ | 2+ late per 10k frames | freezes |
+|---|---|---|---|---|---|---|---|
+| A: step 1 as is | 0.90% | 575 | 64 | 91 | 9 | 20.1 | 0 |
+| B: `switch_interval_ms` 1 | 0.78% | 510 | 105 | 23 | 2 | 15.8 | 0 |
+| C: `prefetch_gate` | **0.60%** | 471 | 11 | 7 | 2 | **2.5** | 0 |
+
+The gate removes the frames the render thread spent waiting for the GIL, and
+it costs the prefetch nothing that shows: it parked the thread for 3–6 s per
+run, and the next group was ready at every strip extension in every arm.
+`prefetch_gate` is therefore on by default; `switch_interval_ms` stays an
+off-by-default experiment. What is left is almost all one refresh late, which
+is the per-frame budget (a 6.75 ms p50 blit in a refresh the panel holds at
+83–85 Hz while rendering), not contention.
+
+The runs restart the service, so the hourly sports refresh never fell inside
+one. That refresh is its own case: about twenty ESPN chunk-fetch threads at
+once, which the gate does not cover (it gates only the prefetch thread).
+
+## The problem
+
+Vegas mode builds its ticker from every plugin's content. Most of that work
+already happens on a background prefetch thread
+(`RenderPipeline.start_prefetch`). But any plugin whose content needs the
+**shared display canvas** is deferred to the render thread
+(`RenderPipeline.drain_deferred`), one plugin every two seconds. The code's
+own comments put each of those at 40–600 ms, and the render thread presents no
+frames while one runs.
+
+On hdpi (Pi 4, 512×64) most plugins take that path: geochron, tide-display,
+news, hockey-scoreboard, ledmatrix-stocks, incoming-packages, clock-simple,
+countdown, birdnet-go, ledmatrix-music and odds-ticker. They arrive in bursts
+("Whole group deferred; strip will extend as it drains") every minute or so,
+12 fetches in five minutes. That is the "occasional pause" a viewer sees.
+
+An 8-minute soak (`scripts/frame_soak.py --preview`) of the #628 build on
+hdpi:
+
+| late by | frames |
+|---|---|
+| 1 refresh | 238 |
+| 2 | 32 |
+| 3–5 | 30 |
+| 6+ | 5 |
+| freezes ≥ 250 ms | 2 (0.97 s total) |
+
+The 3+ rows and the freezes are the pauses. The single-refresh row is a
+separate problem: the blit is 6 ms of a 10 ms refresh, so there is little
+slack. It is covered under *What this does not fix*.
+
+## Why a plugin is canvas-bound
+
+The plugin-facing canvas is a set of shared attributes on `DisplayManager`:
+`image`, `draw`, `matrix`, and the `width`/`height` properties that read from
+`matrix`. Three adapter paths (`src/vegas_mode/plugin_adapter.py`) need them,
+and each returns `None` under `offscreen_only=True` so the plugin is queued for
+the render thread:
+
+1. **Display capture** (`_capture_display_content`): clear the canvas, call
+   `plugin.display()`, copy `display_manager.image`. Used by any plugin
+   without `get_vegas_content()` or a populated `scroll_helper`.
+2. **Scroll-content generation** (`_trigger_scroll_content_generation`): a
+   ticker plugin whose `scroll_helper.cached_image` is empty is made to build
+   it by calling `display(force_clear=True)` or `_create_scrolling_display()`.
+   Both draw on the canvas.
+3. **Narrowed rendering** (`DisplayManager.render_size`): swaps the shared
+   `matrix`, `image` and `draw` for a narrower set so the plugin lays out for
+   `render_width_pct`. The render thread would see the swap mid-frame.
+
+The render thread keeps the canvas coherent only because nothing else touches
+it at the same time. A background thread can't use it.
+
+## The design: a per-thread render target
+
+`capture_mode()` is already per-thread (#423 made its state a
+`threading.local`, so a background capture no longer suppresses the render
+loop's pushes). The same move applies to the canvas itself:
+
+```python
+with display_manager.offscreen(width=None, height=None) as surface:
+    plugin.display(force_clear=True)
+    content = surface.image.copy()
+```
+
+For the **calling thread only**, inside the block:
+
+| accessor | resolves to |
+|---|---|
+| `display_manager.image`, `.draw` | the surface's own image and draw: a fresh black canvas, `fontmode = "1"` |
+| `display_manager.matrix` | a logical proxy reporting the surface size, so `width`/`height` and plugins that read `matrix.width` follow it. Hardware calls through it (`SetImage`, `SwapOnVSync`, `Clear`, brightness writes) are inert. |
+| `update_display()`, `clear()` | canvas-only: the block implies capture mode, which is already per-thread |
+| `set_scrolling_state()`, `set_frame_hold()` | no-ops, so a plugin's `display()` cannot re-pace the live scroll. Today it can, when it is captured on the render thread. |
+
+Every other thread sees the real canvas, unchanged. The render loop in
+particular keeps presenting while a plugin draws elsewhere.
+
+### Implementation sketch
+
+- `image`, `draw` and `matrix` become properties over `_image`, `_draw` and
+  `_matrix`, plus a thread-local current surface. The getter returns the
+  surface's value when the calling thread has one, else the shared one; setters
+  mirror that. That costs about 0.1 µs per access, and `update_display()` reads
+  each a handful of times per frame. Every existing `self.image = ...` in
+  `DisplayManager` (`clear()`, setup, fallback) keeps working and becomes
+  thread-correct for free.
+- `render_size()` is rebuilt on `offscreen()`: it creates or narrows the
+  calling thread's surface instead of swapping shared state.
+- `offscreen()` nests and always restores on exit, including when the plugin
+  raises.
+- `VisualDisplayManager` (the plugin test harness) gets the same method, for
+  parity.
+
+### Adapter changes
+
+- `get_content(offscreen_only=True)` stops returning `None` for the three
+  paths above. Each runs inside `display_manager.offscreen(render_width)`.
+- `_capture_display_content` and `_trigger_scroll_content_generation` drop
+  their "copy the shared image, restore it afterwards" bookkeeping, since the
+  shared image is never touched.
+- **Take the plugin's lock.** `PluginManager.get_plugin_lock()` keeps
+  `update()` and `display()` mutually exclusive in normal rotation, but Vegas
+  never takes it, so today's render-thread captures already race
+  `update()`. Off the render thread the adapter can afford to wait: blocking
+  acquire with a timeout (proposed 2 s). On timeout it keeps the cached segment
+  and tries again next group.
+- `drain_deferred()` and the deferred queue are deleted. The only render-thread
+  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.
+
+## Live elements: content that changes while it scrolls
+
+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.
+
+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.
+
+### Why not redraw every frame
+
+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.
+
+### How an update reaches the screen
+
+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.
+
+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.
+
+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.
+
+### Geometry
+
+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.
+
+### Why not a SegmentStrip
+
+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.
+
+### When it is off
+
+- `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
+
+1. **Plugins holding their own reference to the shared `draw` or `image`.**
+   They would keep drawing into the shared canvas, and routing by thread can't
+   redirect them. A grep of the 49 plugins installed on hdpi found none storing
+   `display_manager.draw` or `.image` in an attribute (a pattern search, so
+   indirect aliasing would slip past it). A plugin that did would
+   draw into an image nobody displays, which trims to a blank segment. That is
+   not corruption, and it is no worse than today.
+2. **Plugins calling the matrix directly.** None in the audit. Inside
+   `offscreen()` the proxy makes it inert anyway.
+3. **Font thread-safety.** `FontManager` shares font objects across plugins.
+   Measured on Pillow 12.3, two threads rendering text take 1.94× as long as
+   one, so text rendering holds the GIL and FreeType is never entered
+   concurrently. Re-check if Pillow changes that.
+4. **Plugin thread-safety.** `display()` moves to the prefetch thread. The
+   plugin lock makes it exclusive with `update()`, which is more protection
+   than it has today. Threads a plugin starts itself are not covered, as today.
+5. **The GIL.** Moving 40–600 ms of plugin rendering off the render thread
+   removes the pauses, but the work still needs the GIL. Pillow drawing holds
+   it, and a waiting thread only gets it back after the switch interval
+   (default 5 ms). Expect some single-refresh late frames while a prefetch
+   runs. Measure with the soak. A render process separate from plugin work
+   is the structural answer (the "native presenter" step). Two experiments
+   get most of the way first (results under Status, above):
+   - `vegas_scroll.switch_interval_ms` lowers the switch interval for a Vegas
+     run (1 ms is the obvious try), so the render thread waits at most that
+     long behind bytecode. It does nothing for a C call that keeps the GIL.
+   - `vegas_scroll.prefetch_gate` (`src/common/render_gate.py`) lets the
+     prefetch thread run Python only while the render thread is blocked in
+     `SwapOnVSync`, up to just before the refresh the swap returns on, and
+     parks it the rest of the time. That covers C calls too, since the gate is
+     checked before each one starts. It never parks the thread while it holds
+     a lock the render thread takes, and never for more than 50 ms. It needs
+     the rebuilt binding, which releases the GIL during the swap. On by
+     default.
+
+## What this does not fix
+
+- **The blit.** Copying a 512×64 frame into the matrix (`SetImage`) is ~6 ms at
+  8 PWM bits on a Pi 4, leaving ~4 ms of slack per refresh. That is the main
+  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.
+- **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
+
+- **Unit, `DisplayManager`:** one thread inside `offscreen()` draws while
+  another reads `image`/`draw`/`matrix`/`width`/`height` and sees the real
+  canvas. Also: `update_display()` and `set_scrolling_state()` are inert inside;
+  `render_size()` narrows only the calling thread; nesting and exceptions
+  restore state.
+- **Unit, adapter:** a stub display-capture plugin and a stub scroll-helper
+  plugin both return content with `offscreen_only=True`, and nothing is queued
+  for the render thread. The plugin lock is taken, and a timeout keeps the cached
+  segment.
+- **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).
+- **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
+  the viewport, and compare the median and max before and after.
+
+## Rollout
+
+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`).
+
+`display.vegas_scroll.offscreen_prefetch` (default `true`) restores the
+deferred path when `false`, and `display.vegas_scroll.live_refresh` (default
+`true`) turns live elements off. Keep both for one release, then delete the
+old paths.
+
+## Open questions
+
+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

@@ -0,0 +1,175 @@
+# Permissions
+
+Who owns what on an installed system, which privileged commands the web
+interface may run, and how to repair ownership when it goes wrong. The
+installer, [`first_time_install.sh`](../first_time_install.sh), sets all of
+this up; this page describes the result.
+
+## Users and groups
+
+| Account | Used by | Why |
+|---|---|---|
+| `root` | `ledmatrix.service` (the display) | The LED matrix library needs direct GPIO access |
+| The installing user (e.g. `ledpi`) | `ledmatrix-web.service`, `ledmatrix-update-verify.service` | A web server should not run as root |
+| `ledmatrix` group | shared files | Members: the installing user, `root`, and `daemon` if it exists. Created by [`setup_cache.sh`](../scripts/install/setup_cache.sh) and the installer |
+
+The installer also adds the web user to `systemd-journal` and `adm` so the
+**Logs** tab can read the journal. Group changes apply after the user logs
+in again (services pick them up on restart).
+
+## Files and directories
+
+| Path | Owner | Mode | Notes |
+|---|---|---|---|
+| Project directory | web user | dirs `755`, files `644`, `*.sh` `755` | Set in the installer's "Normalize project file permissions" step |
+| `config/` | web user | `2775` | |
+| `config/config.json` | web user | `644` | Written by the web interface |
+| `config/config_secrets.json` | web user : `ledmatrix` | `640` | Owned by the web user because the web interface writes it; root reads it regardless of mode |
+| `plugin-repos/`, `plugins/` | web user | dirs `2775`, files `664` | The web interface installs and removes plugins |
+| `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:
+
+- **Config files.** Saves go through
+  [`src/config_manager_atomic.py`](../src/config_manager_atomic.py), which
+  applies `get_config_file_mode()` (`640` for secrets, `644` otherwise) and,
+  when running as root, moves the file's group to the project directory's
+  group (`ensure_shared_group_ownership()` in
+  [`src/common/permission_utils.py`](../src/common/permission_utils.py)).
+- **Cache files.** [`src/cache/disk_cache.py`](../src/cache/disk_cache.py)
+  sets every file it writes to `0660` and gives it the cache directory's
+  group, without relying on the setgid bit. So a file root writes stays
+  readable by the web user.
+- **Plugin directories.** [`run.py`](../run.py) sets
+  `sys.dont_write_bytecode`, because root-owned `__pycache__` directories
+  inside a plugin stop the web user updating or removing it.
+
+`ledmatrix-web.service` deliberately has no `CacheDirectory=`: systemd would
+re-own `/var/cache/ledmatrix` to the web user and its primary group, and the
+web interface could no longer read what the display writes (see the comment
+in [`systemd/ledmatrix-web.service`](../systemd/ledmatrix-web.service)).
+
+If `/var/cache/ledmatrix` is not usable, `CacheManager` falls back to
+`~/.ledmatrix_cache`, `/opt/ledmatrix/cache` or a temp directory
+([`src/cache_manager.py`](../src/cache_manager.py)). The two services then
+may not share a cache, and the web UI shows stale or empty display status,
+on-demand state and plugin health. Fix the directory rather than living
+with the fallback.
+
+## sudo rules
+
+### `/etc/sudoers.d/ledmatrix_web`
+
+Generated by `web_sudoers_rules()` in
+[`scripts/install/lib_sudoers.sh`](../scripts/install/lib_sudoers.sh), the
+only place these rules are defined. Installed by the installer and by
+[`configure_web_sudo.sh`](../scripts/install/configure_web_sudo.sh), both of
+which check them with `visudo -c` first. The web user may run, without a
+password:
+
+- `reboot`, `poweroff`
+- `systemctl start|stop|restart|enable|disable|status ledmatrix.service`,
+  `systemctl is-active ledmatrix[.service]`
+- `systemctl start|stop|restart ledmatrix-web.service`
+- `bash <project>/scripts/fix_perms/safe_plugin_rm.sh *` — removes a
+  directory only if it resolves to a child of `plugin-repos/` or `plugins/`
+- `bash <project>/scripts/fix_perms/safe_pip_install.sh *` — installs a
+  `requirements.txt` only if it is the project's own or one under
+  `plugin-repos/` or `plugins/`, so the root display service can import the
+  packages
+- `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`
+
+Written by
+[`scripts/install/configure_wifi_permissions.sh`](../scripts/install/configure_wifi_permissions.sh)
+(run as the web user; the installer calls it). It refuses to grant a binary
+that is not root-owned or is group/world-writable. The rules cover:
+
+- `nmcli device wifi connect|disconnect *`, `nmcli device connect|disconnect *`,
+  `nmcli radio wifi on|off`
+- `systemctl start|stop|restart hostapd`, `... dnsmasq`,
+  `systemctl restart NetworkManager`
+- `sysctl -w net.ipv4.ip_forward=0|1`
+- `nft add|delete table ip ledmatrix`
+- `rfkill unblock wifi`
+- `mkdir -p /etc/NetworkManager/dnsmasq-shared.d`
+- `cp` of `/tmp/hostapd.conf` and `/tmp/dnsmasq.conf` to their fixed
+  destinations, and `rm -f /etc/dnsmasq.d/ledmatrix-captive.conf`
+- `cp /tmp/ledmatrix-nm-dnsmasq.conf` to
+  `/etc/NetworkManager/dnsmasq-shared.d/ledmatrix-captive.conf`, and
+  `rm -f` of that file
+
+**`iptables` is deliberately not granted.** The captive portal's rules are
+built from the interface name and port, so a rule covering them would need a
+trailing wildcard, and `iptables --modprobe=<path>` runs `<path>` as root: a
+wildcard grant is a root shell for the web user. Doing it safely needs a
+wrapper script that builds the rules itself, like `safe_plugin_rm.sh`. On a
+stock Raspberry Pi OS image the default user's blanket `NOPASSWD` rule
+(`/etc/sudoers.d/010_pi-nopasswd`) hides this gap.
+
+### polkit
+
+The same script installs `/etc/polkit-1/rules.d/10-ledmatrix-wifi.rules`,
+which lets the web user perform any `org.freedesktop.NetworkManager.*`
+action without authentication.
+
+## Repair scripts
+
+In [`scripts/fix_perms/`](../scripts/fix_perms/). Run them from the project
+directory.
+
+| Script | Run as | What it does | Notes |
+|---|---|---|---|
+| `fix_plugin_permissions.sh` | `sudo` | `plugins/` and `plugin-repos/` to `root:<user>`, dirs `2775`, files `664`; makes a `700` home directory `755` so root can traverse it | Safe. Group-writable, so the web user keeps write access |
+| `fix_assets_permissions.sh` | `sudo` | `assets/` to `<user>:<group>`, mode `777` recursively | Works, but looser than the installer's `755`/`644` |
+| `fix_cache_permissions.sh` | `sudo` | Runs [`setup_cache.sh`](../scripts/install/setup_cache.sh) for `/var/cache/ledmatrix` (`root:ledmatrix`, `2775`, files `660`), then makes `~/.ledmatrix_cache` (the fallback cache) `<user>:<group>` mode `777` | Safe. The `~/.ledmatrix_cache` mode is still `777` |
+| `fix_web_permissions.sh` | the web user, **without** `sudo` | Resets project file ownership for the web user (it calls `sudo` itself), then makes `safe_plugin_rm.sh` and `safe_pip_install.sh` `root:root` `755` again and restores `config_secrets.json` to its owner, group `ledmatrix`, mode `640` | Refuses to run as root. It does not write sudoers rules |
+| `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; 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`.
+
+After any of these, restart both services:
+
+```bash
+sudo systemctl restart ledmatrix.service ledmatrix-web.service
+```
+
+## Checking
+
+```bash
+ls -ld /var/cache/ledmatrix          # drwxrwsr-x root ledmatrix
+stat -c '%U:%G %a %n' config/config.json config/config_secrets.json
+id                                   # web user should list ledmatrix
+sudo -l                              # lists the NOPASSWD rules
+```

docs/PLUGIN_API_REFERENCE.md

@@ -9,14 +9,60 @@ Complete API reference for plugin developers. This document describes all method
 
 ## Table of Contents
 
+- [Manifest Required Fields](#manifest-required-fields)
 - [BasePlugin](#baseplugin)
 - [Display Manager](#display-manager)
 - [Cache Manager](#cache-manager)
 - [Plugin Manager](#plugin-manager)
+- [Fetching data](#fetching-data)
 - [Deprecated APIs](#deprecated-apis)
 
 ---
 
+## Manifest Required Fields
+
+Three parts of core check `manifest.json`, each for a different set of
+fields:
+
+| Check | Fields | What happens when one is missing |
+|---|---|---|
+| JSON schema, [`schema/manifest_schema.json`](../schema/manifest_schema.json) | `id`, `name`, `version`, `author`, `entry_point`, `class_name`, `compatible_versions` | Install from URL logs a warning (`PluginStoreManager._validate_manifest_schema()`); nothing is refused |
+| Plugin Store install, [`src/plugin_system/store_install.py`](../src/plugin_system/store_install.py) | `id`, `name`, `class_name`, `display_modes` | Install is refused. A registry install first tries to detect a missing `class_name` from the entry-point file |
+| Plugin loader, [`src/plugin_system/plugin_loader.py`](../src/plugin_system/plugin_loader.py) | `class_name` | The plugin fails to load |
+
+Defaults and other uses:
+
+- `entry_point` defaults to `manager.py`; the store writes the default back
+  into the manifest on install.
+- `compatible_versions` (a list of semver ranges such as `">=2.0.0"`) is how
+  the store decides whether a plugin can run on this core. An install is
+  refused only when the field excludes the running version
+  (`compatibility.check()` in
+  [`src/plugin_system/compatibility.py`](../src/plugin_system/compatibility.py)).
+- `version` is compared with the registry's `latest_version` to decide
+  whether an update is available.
+- If `display_modes` is empty at load time, the display controller uses the
+  plugin id as the only mode.
+
+**Set all eight:** `id`, `name`, `version`, `author`, `entry_point`,
+`class_name`, `display_modes`, `compatible_versions`. That satisfies every
+check. The schema lists the optional fields.
+
+```json
+{
+  "id": "my-plugin",
+  "name": "My Plugin",
+  "version": "1.0.0",
+  "author": "YourName",
+  "entry_point": "manager.py",
+  "class_name": "MyPlugin",
+  "display_modes": ["my-plugin"],
+  "compatible_versions": [">=2.0.0"]
+}
+```
+
+---
+
 ## BasePlugin
 
 All plugins must inherit from `BasePlugin` and implement the required methods. The base class provides access to managers and common functionality.
@@ -104,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]`
 
@@ -251,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
@@ -263,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,
@@ -270,26 +380,185 @@ 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`.
+
+### On-demand display
+
+A plugin that reacts to something outside the rotation (an MQTT message, a
+timer, a detection) can take the screen for it, and give it back. Both
+methods are safe from any thread, including an MQTT callback: they only
+queue the request, and the display applies it on its render thread within a
+frame or so, exactly like an on-demand start or stop from the web interface.
+
+#### `request_on_demand(mode=None, duration=None, pinned=False) -> Optional[str]`
+
+Show this plugin now.
+
+- `mode`: one of the plugin's display modes; `None` for its first.
+- `duration`: seconds before the rotation resumes; `None` (or `0`) for no
+  limit, until `end_on_demand()` or the user stops it.
+- `pinned`: stay on `mode` instead of cycling through the plugin's other
+  modes.
+
+Returns the request id once the display has queued it, or `None` when
+there is no display in this process to ask (the web interface's plugin
+manager, `scripts/check_plugin.py`) or its queue is full. A bad argument
+(a `mode` that is not a string, a `duration` that is not a number) raises
+`ValueError`.
+
+#### `end_on_demand() -> Optional[str]`
+
+Give the screen back. Ends only a session this plugin owns: a session the
+user started for another plugin, or one that already ended, is left alone.
+Returns the request id once queued, or `None` as above.
+
+#### Older cores: feature detection
+
+These methods are new after core 3.8.0 (see `CHANGELOG.md`). Before them,
+plugins wrote the `display_on_demand_request` cache key (the "mailbox")
+themselves. The display reads it only once a second while the control
+socket is up, and it will be removed in a future release (see
+[IPC_CONTROL_SOCKET.md](IPC_CONTROL_SOCKET.md), stage 5). A plugin that
+must keep working on older cores checks for the method, and writes the
+mailbox only when the method is missing or answers `None`:
+
+```python
+import time, uuid
+
+def _show_alert(self):
+    if hasattr(self, "request_on_demand") and self.request_on_demand(
+            mode="my_alert", duration=15):
+        return
+    # Older core, or no display in this process: the mailbox, as before.
+    self.cache_manager.set("display_on_demand_request", {
+        "request_id": str(uuid.uuid4()), "action": "start",
+        "plugin_id": self.plugin_id, "mode": "my_alert",
+        "duration": 15, "pinned": False, "timestamp": time.time(),
+    })
+
+def _release(self):
+    if hasattr(self, "end_on_demand") and self.end_on_demand():
+        return
+    self.cache_manager.set("display_on_demand_request", {
+        "request_id": str(uuid.uuid4()), "action": "stop",
+        "plugin_id": self.plugin_id, "timestamp": time.time(),
+    })
+```
+
+Keep `ledmatrix_min_version` where it is: the fallback is what keeps the
+plugin working on older cores. A mailbox stop ends any on-demand session,
+whoever started it; `end_on_demand()` ends only the plugin's own.
+
+Both methods answer a request id only when the plugin manager returned a
+string, so a test that gives the plugin a `MagicMock()` plugin manager gets
+`None` and exercises the mailbox path. To test the new path, set
+`plugin_manager.request_on_demand.return_value = "some-id"`.
 
 > The full source for `BasePlugin` lives in
 > `src/plugin_system/base_plugin.py`. If a method here disagrees with the
@@ -432,83 +701,6 @@ self.display_manager.update_display()
 
 This is the canonical way to render arbitrary images.
 
-### Weather Icons
-
-#### `draw_weather_icon(condition: str, x: int, y: int, size: int = 16) -> None`
-
-Draw a weather icon based on the condition string.
-
-**Parameters**:
-- `condition` (str): Weather condition (e.g., "clear", "cloudy", "rain", "snow", "storm")
-- `x` (int): X position
-- `y` (int): Y position
-- `size` (int): Icon size in pixels (default: 16)
-
-**Supported Conditions**:
-- `"clear"`, `"sunny"` → Sun icon
-- `"clouds"`, `"cloudy"`, `"partly cloudy"` → Cloud icon
-- `"rain"`, `"drizzle"`, `"shower"` → Rain icon
-- `"snow"`, `"sleet"`, `"hail"` → Snow icon
-- `"thunderstorm"`, `"storm"` → Storm icon
-
-**Example**:
-```python
-self.display_manager.draw_weather_icon("rain", x=10, y=10, size=16)
-```
-
-#### `draw_sun(x: int, y: int, size: int = 16) -> None`
-
-Draw a sun icon with rays.
-
-**Parameters**:
-- `x` (int): X position
-- `y` (int): Y position
-- `size` (int): Icon size (default: 16)
-
-#### `draw_cloud(x: int, y: int, size: int = 16, color: tuple = (200, 200, 200)) -> None`
-
-Draw a cloud icon.
-
-**Parameters**:
-- `x` (int): X position
-- `y` (int): Y position
-- `size` (int): Icon size (default: 16)
-- `color` (tuple): RGB color (default: light gray)
-
-#### `draw_rain(x: int, y: int, size: int = 16) -> None`
-
-Draw rain icon with cloud and droplets.
-
-#### `draw_snow(x: int, y: int, size: int = 16) -> None`
-
-Draw snow icon with cloud and snowflakes.
-
-#### `draw_text_with_icons(text: str, icons: List[tuple] = None, x: int = None, y: int = None, color: tuple = (255, 255, 255)) -> None`
-
-Draw text with weather icons at specified positions.
-
-**Parameters**:
-- `text` (str): Text to display
-- `icons` (List[tuple], optional): List of (icon_type, x, y) tuples
-- `x` (int, optional): X position for text
-- `y` (int, optional): Y position for text
-- `color` (tuple): Text color
-
-**Note**: Automatically calls `update_display()` after drawing.
-
-**Example**:
-```python
-icons = [
-    ("sun", 5, 5),
-    ("cloud", 100, 5)
-]
-self.display_manager.draw_text_with_icons(
-    "Weather: Sunny, Cloudy",
-    icons=icons,
-    x=10, y=20
-)
-```
-
 ### Scrolling State Management
 
 For plugins that implement scrolling content, use these methods to coordinate with the display system.
@@ -599,18 +791,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`
-
-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:
@@ -740,25 +920,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]]`
-
-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]`
@@ -777,21 +938,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`
-
-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.
@@ -801,15 +947,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]`
-
-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`
@@ -847,26 +984,6 @@ for file_info in files:
     self.logger.info(f"Cache: {file_info['key']}, Age: {file_info['age_display']}")
 ```
 
-### Metrics Methods
-
-#### `get_cache_metrics() -> Dict[str, Any]`
-
-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]`
-
-Get memory cache statistics.
-
-**Returns**: Dictionary with memory cache stats (size, max_size, etc.)
-
 ---
 
 ## Plugin Manager
@@ -905,12 +1022,6 @@ for plugin_id, plugin in all_plugins.items():
     self.logger.info(f"Plugin {plugin_id} is loaded")
 ```
 
-#### `get_enabled_plugins() -> List[str]`
-
-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.
@@ -927,6 +1038,14 @@ if info:
     self.logger.info(f"Plugin: {info['name']}, Version: {info.get('version')}")
 ```
 
+#### `request_on_demand(plugin_id, mode=None, duration=None, pinned=False)` / `end_on_demand(plugin_id)`
+
+What `BasePlugin.request_on_demand()` and `end_on_demand()` call, with the
+plugin's own id. Call those instead; see
+[On-demand display](#on-demand-display). The display controller routes them
+to itself with `set_on_demand_handler()`; a plugin manager without a
+display behind it answers `None`.
+
 #### `get_all_plugin_info() -> List[Dict[str, Any]]`
 
 Get information for all plugins.
@@ -985,14 +1104,110 @@ def update(self):
 
 **Example - Checking if another plugin is enabled**:
 ```python
-enabled_plugins = self.plugin_manager.get_enabled_plugins()
-if "weather" in enabled_plugins:
-    # Weather plugin is enabled
+weather = self.plugin_manager.plugins.get("weather")
+if weather is not None and weather.enabled:
     pass
 ```
 
 ---
 
+## 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
@@ -1077,10 +1292,19 @@ if "weather" in enabled_plugins:
 
 ## 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 |
 |---|---|---|
@@ -1093,3 +1317,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_CONFIGURATION_GUIDE.md

@@ -124,6 +124,14 @@ Plugins are configured by adding their plugin ID as a top-level key in the confi
 }
 ```
 
+How often the core calls a plugin's `update()`: the plugin's
+`get_update_interval()` if it returns a number, else `update_interval` in the
+plugin's `manifest.json`, else `update_interval` in its `config.json` section
+as above, else 60 seconds. A config `update_interval` therefore only sets the
+scheduler's cadence for a plugin whose manifest does not; plugins that expose
+it in their config schema typically also honour it themselves inside
+`update()`. See [PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md#get_update_interval---optionalfloat).
+
 ### Plugin Display Durations
 
 Add plugin display modes to the `display_durations` section:
@@ -194,7 +202,7 @@ plugin-repos/
 ```
 
 The Plugin Store refuses a manifest that lacks any of `id`, `name`,
-`class_name` or `display_modes` (`store_manager.py`); the loader itself
+`class_name` or `display_modes` (`store_install.py`); the loader itself
 needs `class_name`. `version` is not required, but the store compares it
 with the registry's `latest_version` to offer updates, so set it.
 `entry_point` defaults to `manager.py` if omitted. The config schema is not

docs/PLUGIN_CONFIGURATION_TABS.md

@@ -203,7 +203,7 @@ Forms are rendered on the server, not generated in the browser:
    from the schema (widgets named by `x-widget` are rendered by the scripts in
    `web_interface/static/v3/js/widgets/`)
 4. **Save Configuration** posts the form to `/api/v3/plugins/config`
-   (`web_interface/blueprints/api_v3/plugins.py`), which validates it against
+   (`web_interface/blueprints/api_v3/plugin_config.py`), which validates it against
    the schema, writes `config.json` (secret fields go to
    `config_secrets.json`) and shows a notification
 

docs/PLUGIN_CONFIG_ARCHITECTURE.md

@@ -32,7 +32,7 @@
 │    • masks x-secret fields                                         │
 │    • renders partials/plugin_config.html (render_field macros)     │
 │                                                                    │
-│  api_v3 blueprint (blueprints/api_v3/plugins.py)                   │
+│  api_v3 blueprint (blueprints/api_v3/plugin_config.py)             │
 │   save_plugin_config()   POST /api/v3/plugins/config               │
 │   get_plugin_config()    GET  /api/v3/plugins/config               │
 │   get_plugin_schema()    GET  /api/v3/plugins/schema               │
@@ -91,7 +91,7 @@ validatePluginConfigForm() (client-side checks)
 POST /api/v3/plugins/config?plugin_id=<id>   (form data, all fields of the form)
         │
         ▼
-save_plugin_config()                          (api_v3/plugins.py)
+save_plugin_config()                          (api_v3/plugin_config.py)
         ├─→ Start from the stored config.json[<id>]
         ├─→ Apply form fields: dotted names → nested keys, "[]" checkbox
         │   groups → lists, values coerced to the schema's types
@@ -155,9 +155,9 @@ deep-merged back into the plugin's config at load time
 ### Custom input widgets
 
 Set `"x-widget": "<name>"` on a property. Core widgets are in
-`web_interface/static/v3/js/widgets/` (see its README); a plugin can ship its
-own widget script, served from `/static/plugin-widgets/<plugin_id>/<name>.js`.
-See [widget-guide.md](widget-guide.md).
+`web_interface/static/v3/js/widgets/`; a plugin can ship its own widget
+script, served from `/static/plugin-widgets/<plugin_id>/<name>.js`. See the
+[widget guide](../web_interface/static/v3/js/widgets/README.md).
 
 ### Custom actions
 
@@ -175,7 +175,7 @@ Implement `on_config_change(new_config)` in the plugin (see
 |---------|------|
 | Tab partial loader | `web_interface/blueprints/pages_v3.py` (`_load_plugin_config_partial`) |
 | Form template and field macros | `web_interface/templates/v3/partials/plugin_config.html` |
-| Save / get / schema / reset handlers | `web_interface/blueprints/api_v3/plugins.py` |
+| Save / get / schema / reset handlers | `web_interface/blueprints/api_v3/plugin_config.py` |
 | Schema loading, defaults, validation | `src/plugin_system/schema_manager.py` |
 | Secret masking and splitting | `src/web_interface/secret_helpers.py` |
 | Widgets | `web_interface/static/v3/js/widgets/` |

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_CUSTOM_ICONS.md

@@ -5,11 +5,9 @@
 A plugin can name an icon for its tab in the web interface's second nav row
 (next to **Plugin Manager**) with the `icon` field in `manifest.json`.
 
-> **Status:** the tab code honors `icon`, but `GET /api/v3/plugins/installed`
-> (`web_interface/blueprints/api_v3/plugins.py`) does not currently include
-> the manifest's `icon` in its response, so every tab shows the default
-> puzzle piece. Setting `icon` is harmless and will take effect once the API
-> passes it through again.
+`GET /api/v3/plugins/installed` passes the manifest's `icon` through (a
+non-string value comes back as `null`), and a plugin without one gets the
+default puzzle piece.
 
 ## Font Awesome classes only
 
@@ -55,8 +53,8 @@ With no `icon` (or an empty one) the tab shows `fas fa-puzzle-piece`.
    or misspelled class renders as a blank space.
 2. Include the style prefix (`fas`, `far` or `fab`) as well as the icon
    class.
-3. See the status note above: the icon is currently not passed through by
-   the API.
+3. The manifest is re-read on each plugin list load; reload the page after
+   editing `icon`.
 
 ## Related Documentation
 

docs/PLUGIN_DEPENDENCY_GUIDE.md

@@ -25,7 +25,7 @@ which runs as root.** Anything installed only into another user's
 The web interface is not root, so it installs through a narrow sudo helper:
 
 1. `PluginStoreManager._install_dependencies()`
-   (`src/plugin_system/store_manager.py`) calls
+   (`src/plugin_system/store_install.py`) calls
    `install_requirements_file()` (`src/common/permission_utils.py`).
 2. That runs `sudo -n bash scripts/fix_perms/safe_pip_install.sh <plugin>/requirements.txt`.
    The helper checks the path is the project's own `requirements.txt` or a
@@ -154,8 +154,9 @@ For more, see the [Plugin Dependency Troubleshooting Guide](PLUGIN_DEPENDENCY_TR
 ## Files to Reference
 
 - Service units: `systemd/ledmatrix.service`, `systemd/ledmatrix-web.service`
-- Store installs: `src/plugin_system/store_manager.py` (`_install_dependencies`)
+- Store installs: `src/plugin_system/store_install.py` (`_install_dependencies`)
 - Root install helper: `src/common/permission_utils.py` (`install_requirements_file`), `scripts/fix_perms/safe_pip_install.sh`
 - Load-time installs: `src/plugin_system/plugin_loader.py` (`install_dependencies`)
-- Sudo rules: `scripts/install/configure_web_sudo.sh`
+- Sudo rules: `scripts/install/lib_sudoers.sh` (written by `first_time_install.sh`
+  and `scripts/install/configure_web_sudo.sh`)
 - Manual installer: `scripts/install_plugin_dependencies.sh`

docs/PLUGIN_DEVELOPMENT_GUIDE.md

@@ -519,20 +519,20 @@ 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
 - `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()` - Background service caching
 
 **Plugin Manager** (`self.plugin_manager`):
 - `get_plugin()`, `get_all_plugins()` - Access other plugins
 - `get_plugin_info()` - Get plugin information
 
-See [PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md) for complete documentation.
+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.8.0.
 
 ## 3rd Party Plugin Development
 
@@ -577,12 +577,14 @@ Your plugin must:
            pass
    ```
 
-2. **Include manifest.json** with required fields:
+2. **Include manifest.json** with the required fields listed in
+   [PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md#manifest-required-fields):
    ```json
    {
      "id": "my-plugin",
      "name": "My Plugin",
      "version": "1.0.0",
+     "author": "YourName",
      "class_name": "MyPlugin",
      "entry_point": "manager.py",
      "display_modes": ["my_plugin"],
@@ -640,7 +642,7 @@ To have your plugin added to the official plugin store:
 
 3. **Contact maintainers** (own-repository plugins):
    - Open a GitHub issue in the [ledmatrix-plugins](https://github.com/ChuckBuilds/ledmatrix-plugins) repository
-   - Or reach out on Discord: https://discord.gg/uW36dVAtcT
+   - Or reach out on Discord: https://discord.gg/RdrC37rEag
    - Include: Repository URL, plugin description, why it's useful
 
 4. **Review process**:
@@ -658,7 +660,7 @@ For your plugin to work well in the plugin store:
   with the registry's `latest_version`; releases and tags are not read
 - **README.md**: Clear installation and configuration instructions
 - **config_schema.json**: Recommended for web UI configuration
-- **manifest.json**: Required with all required fields
+- **manifest.json**: Required, with the [required fields](PLUGIN_API_REFERENCE.md#manifest-required-fields)
 - **requirements.txt**: If your plugin has Python dependencies
 
 ### Distribution Options

docs/PLUGIN_QUICK_REFERENCE.md

@@ -45,7 +45,8 @@ LEDMatrix/
 
 ### 1. Minimal Plugin Structure
 
-**manifest.json**:
+**manifest.json** (the required fields are explained in
+[PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md#manifest-required-fields)):
 ```json
 {
   "id": "my-plugin",
@@ -54,6 +55,8 @@ LEDMatrix/
   "author": "YourName",
   "entry_point": "manager.py",
   "class_name": "MyPlugin",
+  "display_modes": ["my-plugin"],
+  "compatible_versions": [">=2.0.0"],
   "category": "custom"
 }
 ```

docs/PLUGIN_REGISTRY_SETUP_GUIDE.md

@@ -67,9 +67,9 @@ Don't edit `latest_version` or `last_updated` by hand for monorepo plugins:
 
 ## Adding or changing an official plugin
 
-1. Add or edit `plugins/<your-plugin-id>/` in the monorepo. The store refuses
-   a manifest without `id`, `name`, `class_name` and `display_modes`; also
-   set `version`.
+1. Add or edit `plugins/<your-plugin-id>/` in the monorepo, with the
+   manifest fields listed in
+   [PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md#manifest-required-fields).
 2. Bump `version` in the plugin's `manifest.json` for every change, or users
    won't be offered the update.
 3. Run `python update_registry.py` in ledmatrix-plugins and commit the

docs/README.md

@@ -11,7 +11,7 @@ the one-shot installer. The pages here go deeper.
 2. [WEB_INTERFACE_GUIDE.md](WEB_INTERFACE_GUIDE.md) — using the web UI
 3. [PLUGIN_STORE_GUIDE.md](PLUGIN_STORE_GUIDE.md) — installing and managing plugins
 4. [WIFI_NETWORK_SETUP.md](WIFI_NETWORK_SETUP.md) — WiFi and AP-mode setup
-5. [TROUBLESHOOTING.md](TROUBLESHOOTING.md) — common issues and fixes
+5. [TROUBLESHOOTING.md](TROUBLESHOOTING.md) — common issues and fixes ([PERMISSIONS.md](PERMISSIONS.md) for "Permission denied")
 6. [SSH_UNAVAILABLE_AFTER_INSTALL.md](SSH_UNAVAILABLE_AFTER_INSTALL.md) — recovering SSH after install
 7. [CONFIG_DEBUGGING.md](CONFIG_DEBUGGING.md) — diagnosing config problems
 8. [LOW_MEMORY_BOARDS.md](LOW_MEMORY_BOARDS.md) — Pi Zero 2 W / 3B+ / 1GB Pi 4 memory limits
@@ -37,7 +37,7 @@ Going deeper:
 - [PLUGIN_CUSTOM_ICONS.md](PLUGIN_CUSTOM_ICONS.md)
 - [PLUGIN_REGISTRY_SETUP_GUIDE.md](PLUGIN_REGISTRY_SETUP_GUIDE.md) (+ [registry template](plugin_registry_template.json))
 - [STARLARK_APPS_GUIDE.md](STARLARK_APPS_GUIDE.md) — Starlark-based mini-apps
-- [widget-guide.md](widget-guide.md) — widget development
+- [Widget guide](../web_interface/static/v3/js/widgets/README.md) — built-in `x-widget`s and custom widgets
 - [ADAPTIVE_LAYOUT.md](ADAPTIVE_LAYOUT.md) — render legibly on any panel size (opt-in font/layout scaling)
 - [plugin-safety-harness.md](plugin-safety-harness.md) — test a plugin across every screen and matrix size
 
@@ -56,21 +56,29 @@ Going deeper:
 - [ADVANCED_FEATURES.md](ADVANCED_FEATURES.md) — Vegas scroll, on-demand display,
   cache management, background services, permissions
 - [FONT_MANAGER.md](FONT_MANAGER.md) — font system
+- [SCROLL_PERFORMANCE.md](SCROLL_PERFORMANCE.md) — how scrolling is paced, and how to make a plugin's marquee smooth
+- [OFFSCREEN_RENDERING.md](OFFSCREEN_RENDERING.md) — rendering plugin content off the render thread
+- [PERMISSIONS.md](PERMISSIONS.md) — file ownership, sudo rules, repair scripts
+- [MQTT bridge](../integrations/mqtt_bridge/README.md) — control the display from Home Assistant over MQTT
 
 ## Reference
 
 - [CONFIG_REFERENCE.md](CONFIG_REFERENCE.md) — every key in config.json and config_secrets.json
 - [REST_API_REFERENCE.md](REST_API_REFERENCE.md) — all web-interface HTTP endpoints
 - [PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md) — Python APIs available to plugins
+- [src/common/README.md](../src/common/README.md) — shared helper modules plugins can import
 - [DEVELOPER_QUICK_REFERENCE.md](DEVELOPER_QUICK_REFERENCE.md) — common dev tasks
 
 ## 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
 - [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md) — breaking changes between releases
-- [SPORTS_UNIFICATION.md](SPORTS_UNIFICATION.md) — how the sports scoreboard base classes are organized
+- [SPORTS_UNIFICATION.md](SPORTS_UNIFICATION.md) — how shared sports scoreboard code moves into `src/common`
 
 ## Audits
 

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,18 +68,20 @@ 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)
 
 > The API blueprint is the `api_v3` package in
 > `web_interface/blueprints/api_v3/` (one module per area: `config.py`,
-> `display.py`, `plugins.py`, `system.py`, `backup.py`, `fonts.py`,
-> `misc.py`, `wifi.py`, `starlark.py`). `web_interface/app.py` registers it
+> `display.py`, `system.py`, `backup.py`, `fonts.py`, `misc.py`, `wifi.py`,
+> `starlark.py`, and `plugins.py` plus the `plugin_*.py` modules for the
+> plugin routes). `web_interface/app.py` registers it
 > at `/api/v3` (`app.register_blueprint(api_v3, url_prefix='/api/v3')`).
 > The three SSE endpoints (`/api/v3/stream/*`) are defined directly on the
 > Flask app in `app.py` (`stream_stats`, `stream_display`, `stream_logs`).
 > `test/fixtures/api_v3_url_map.json` is the canonical list of blueprint
-> routes (116 URL rules); a test fails if the code and that fixture differ.
+> routes; a test fails if the code and that fixture differ.
 
 ---
 
@@ -119,10 +154,27 @@ 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 true when the save changed a setting that takes
+effect when the display restarts: display hardware, rotation order,
+timezone, general settings and the rest. The web UI shows its restart banner
+on the flag. It is false when the save changed only what the running display
+applies by itself, or nothing: `brightness`, the per-mode durations
+(`duration__<mode>`, `display.display_durations`) and plugin sections, which
+reach the running plugin live, like `POST /plugins/config`.
+
+A saved `brightness` 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.
@@ -196,7 +248,10 @@ Replace the schedule configuration.
 ```
 
 A day whose `<day>_enabled` key is absent counts as enabled, with default
-times `07:00`-`23:00`. At least one day must be enabled.
+times `07:00`-`23:00`. An enabled schedule needs at least one day enabled; a
+disabled one (`"enabled": false`) may have every day off, as
+`config.template.json` ships it. A day that is off keeps the times sent for
+it, when they are valid `HH:MM`.
 
 **Response**:
 ```json
@@ -212,7 +267,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
@@ -237,7 +295,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.
 
 ---
 
@@ -277,12 +336,23 @@ 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. So is a stopped display: when the socket does not
+answer and the render loop's heartbeat
+(`/run/ledmatrix/display-heartbeat.json`) is absent, stale or from a process
+that is gone, the cache's last entry is not used. A display still beating
+without a socket, Windows, or a socket switched off reads the cache.
 
 ### List Display Modes
 
@@ -293,9 +363,11 @@ it. This is the list the force-display dialog offers.
 
 Send the reported `plugin_id` alongside `mode` when starting an on-demand
 display: `/display/on-demand/start` falls back to `find_plugin_for_mode` when
-`plugin_id` is omitted, and that lookup only sees modes declared in a static
-manifest — a plugin whose modes are generated (each installed Starlark app is
-one) returns 404 there.
+`plugin_id` is omitted. While the display is running, this list and that
+lookup use the modes the display registered, including ones a plugin generates
+from its config (each installed Starlark app, each soccer `custom_leagues`
+entry). With the display stopped, or for a plugin it has not loaded, both see
+only the modes its manifest declares.
 
 Triggers plugin discovery, which is otherwise lazy — so a caller that never
 opens the dashboard still gets the full list.
@@ -359,11 +431,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}`.
 
@@ -389,7 +466,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 a frame over its control socket (within about a second through the mailbox fallback). When false and the service is stopped, the route returns 400.
 
 **Response**:
 ```json
@@ -401,13 +478,33 @@ 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.
+The mailbox is used only when the socket could not carry the request. With
+`"mailbox"`, `socket_error` gives the reason (`no_socket` when the display is
+stopped or predates the socket, `refused`, a connect `timeout`,
+`unknown_command` from a display too old for the command, ...). Either way
+the request is applied the same way; `request_id` is the same id in both.
+
+When the display had the request and did not take it -- a full queue
+(`busy`), bad arguments (`invalid_args`), no answer after the request was
+sent (`timeout`, `closed`) -- the route answers `503` (`400` for
+`invalid_args`) with `status: "error"` and `data: {request_id, transport:
+"socket", socket_error}`, and writes nothing to the mailbox. The stop route
+does the same, except that with `stop_service: true` it still stops the
+service and answers success.
+
 ### Stop On-Demand Display
 
 **POST** `/api/v3/display/on-demand/stop`
@@ -430,11 +527,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
@@ -464,21 +564,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>`
@@ -638,7 +792,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
 
@@ -663,6 +829,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`
@@ -683,11 +854,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`
@@ -716,10 +918,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`
@@ -847,6 +1052,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>`
@@ -869,7 +1144,13 @@ Get a plugin's resource limits. `data` is `null` when none are configured.
 **POST** `/api/v3/plugins/limits/<plugin_id>`
 
 Set a plugin's resource limits. The body replaces all four limits: a key you
-omit is stored as no limit (`warning_threshold` defaults to `0.8`).
+omit is stored as no limit (`warning_threshold` defaults to `0.8`). Each value
+must be a non-negative number or `null`; anything else is a 400.
+
+The limits are stored in the shared cache. A display service that has already
+read limits for the plugin keeps using those until it restarts; likewise the
+health and metrics reset routes clear the stored record and the web process's
+copy, not the display service's in-memory state.
 
 **Request Body**:
 ```json
@@ -885,8 +1166,11 @@ omit is stored as no limit (`warning_threshold` defaults to `0.8`).
 
 **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
@@ -895,23 +1179,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
@@ -1182,13 +1484,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`
@@ -1329,20 +1640,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`
@@ -1368,7 +1718,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
 
@@ -1381,7 +1733,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
@@ -1904,13 +2259,11 @@ error with `"all": true` (`max_age_hours` is then ignored).
 }
 ```
 
-The clear is asynchronous. The web interface records a request
-(`plugin_error_clear_request` in the shared cache), and the display service
-applies it within about 5 seconds, rebuilding its counts from the errors it
-keeps and republishing. Reads hide the cleared errors from the moment the
-request is recorded. Until the display service applies an age-based clear,
-`recent_errors` and `active_patterns` are already filtered but the counts
-are the old ones, and `clear_pending` is `true`.
+The clear goes to the display service over its control socket
+(`errors.clear`, see [IPC_CONTROL_SOCKET.md](IPC_CONTROL_SOCKET.md)), which
+applies it, rebuilding its counts from the errors it keeps, and republishes
+before it answers: `applied` is `true`, `transport` is `"socket"`, and
+`cleared_count` is the display's own count.
 
 ```json
 {
@@ -1918,17 +2271,30 @@ are the old ones, and `clear_pending` is `true`.
   "data": {
     "cleared_count": 13,
     "clear_requested": true,
+    "applied": true,
+    "transport": "socket",
     "request_id": "5f0c1e...",
     "cutoff": "2026-09-23T09:59:02.310000"
   },
-  "message": "Clear of all errors requested; the display service applies it within about 5 seconds"
+  "message": "Cleared all errors"
 }
 ```
 
-`cleared_count` is how many of the reported errors the clear hides. It is
+When the socket cannot carry it (the display is stopped, or older than
+`errors.clear`) the clear is asynchronous, as before: the web interface
+records a request (`plugin_error_clear_request` in the shared cache),
+`applied` is `false` and `transport` is `"mailbox"`, and the display service
+applies it within about 5 seconds. Reads hide the cleared errors from the
+moment the request is recorded. Until the display service applies an
+age-based clear, `recent_errors` and `active_patterns` are already filtered
+but the counts are the old ones, and `clear_pending` is `true`. Then
+`cleared_count` is how many of the reported errors the clear hides, and
 `null` when that cannot be known before the display service applies it (an
-age-based clear over more errors than the report lists). A request that
-could not be written to the shared cache answers `500`.
+age-based clear over more errors than the report lists).
+
+A request that could not be written to the shared cache answers `500`. A
+display that had the request and failed it (`internal`, a timeout after the
+request was sent) answers `503`, with `context.socket_error`.
 
 ---
 
@@ -1942,6 +2308,25 @@ 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, or `stopped` (with `source:
+"service"`) when the display service is not active, the control socket does
+not answer and there is no live heartbeat; the status then turns
+`degraded`. A platform with no control socket (Windows) or a socket switched
+off never reports `stopped`. 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`
@@ -1994,8 +2379,9 @@ Replace the dim schedule. `dim_brightness` is 0-100 (default 30). In
 `per-day` mode the days can be sent either as the `days` object that GET
 returns, or as the web form's flat fields (`monday_enabled`,
 `monday_start`, `monday_end`, ...). A day that is not sent counts as
-enabled with default times `20:00`-`07:00`; at least one day must be
-enabled.
+enabled with default times `20:00`-`07:00`. As for the schedule above, an
+enabled dim schedule needs at least one day enabled and a disabled one may
+have every day off.
 
 ---
 
@@ -2007,20 +2393,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
@@ -2111,13 +2577,18 @@ Errors use one of two shapes. Most endpoints answer:
 }
 ```
 
-Endpoints built on the structured error helper add a code and category:
+An exception no route anticipated gets this shape too, with a 500, the
+message `An error occurred; see logs for details`, and `details` naming the
+exception type and text (credentials redacted). The api_v3 blueprint's
+error handler produces it, so it is the same for every `/api/v3` route.
+
+Endpoints built on the structured error helper add a code, and usually
+suggested fixes (the web UI's error dialog lists them):
 
 ```json
 {
   "status": "error",
   "error_code": "CONFIG_SAVE_FAILED",
-  "error_category": "configuration",
   "message": "Error description",
   "details": "optional",
   "context": { },

docs/RUN_LOOP_REDESIGN.md

@@ -0,0 +1,471 @@
+# 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, as `Source.RELOAD` at the runner's
+   service points). 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()`.
+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 also ends a running screen within about a second (the runner's
+   service points), and a screen cut short resumes after it.
+7. **The Sources below the notice:** read whether Vegas is on and make the
+   live-priority scan (`_arbiter_inputs_below_wifi`, where run() always
+   read them), and call `decide()` again. It answers OnDemand (the
+   session's current mode), Live (the next live mode, round-robin; a game
+   that goes live during a screen takes over at the next service point, at
+   most once a second), Vegas (`LEGACY`) or Rotation. `_take_plan` applies
+   the answer: a live claim or the resume when live priority ends, the
+   on-demand index.
+8. **Vegas** (`_run_vegas_iteration`): one iteration of up to
+   `max_cycle_duration`. A completed iteration ends the pass, and so does
+   one that yielded for the schedule, a reload or a WiFi notice. Any other
+   interrupted one asks `decide()` once more (`vegas_yielded`): a game that
+   stopped the ticker, or an on-demand session that started, shows next.
+9. **One screen:** pick the plugin (`_plugin_for_mode`) and hand the plan
+   to the `ScreenRunner` (`src/screen_runner.py`). It draws the first frame
+   through the executor (`_dispatch_first_frame`), has the controller fill
+   in the plugin's durations, dynamic flag and frame policy
+   (`_complete_plan`), runs the 125 Hz or 1 Hz frame loop with a service
+   point after each frame, makes up the minimum duration, and returns an
+   `Outcome`. On `PREEMPTED` the pass ends without advancing. On no
+   content, rotate at once (`_note_empty_pass`, `_skip_failed_plugin_modes`).
+   Otherwise `ArbiterState.after()` picks the next mode
+   (`_advance_after_screen`).
+
+## Design
+
+```python
+def run(self):
+    while True:
+        inputs = self._arbiter_inputs()                     # schedule, follower, notice
+        plan = Arbiter.decide(self._arbiter_state(), inputs, now)
+        ...                                                 # off / follower / notice
+        plan = self._take_plan(Arbiter.decide(state, self._arbiter_inputs_below_wifi(inputs), now))
+        if plan.source is Source.LEGACY:                    # Vegas, until stage 4
+            plan = self._run_vegas_iteration(...)
+        outcome = runner.run(plan, plugin)                  # ExitReason + elapsed
+        if outcome.exit_reason is not ExitReason.PREEMPTED:
+            self._advance_after_screen(plan, outcome)       # ArbiterState.after
+```
+
+The controller's attributes (`current_display_mode`, `current_mode_index`,
+`on_demand_*`, `_live_resume_index`) stay the record that the web UI, the
+control socket and the on-demand cache read. `_arbiter_state()` snapshots
+them into a frozen `ArbiterState`; the transitions are pure methods on it,
+and the controller writes their result back (`_adopt_state`).
+
+### 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 | Code |
+|---|---|---|---|
+| gate | ScheduledOff | the schedule is off and no on-demand session overrides it | `decide` |
+| 1 | Follower | a sync leader is driving this panel | `decide` |
+| 2 | OnDemand | a session is active (its mode list, index, expiry and pin) | `_on_demand_plan` |
+| 3 | Wifi | a status message is pending and on-demand is not active | `decide` |
+| 4 | Live | a live-priority plugin has live content (round-robin across several) | `live_pick` |
+| 5 | Vegas | Vegas is enabled and nothing above wants the panel | `LEGACY`, run by `_run_vegas_iteration` |
+| 6 | Rotation | always: the rotation's current mode | `rotation_plan` |
+
+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.
+
+The Rotation answers `state.current_mode`, not
+`available_modes[current_mode_index]`: the two agree except where something
+moved the panel off the list and the rotation carries on from there (a live
+mode no rotation entry names, or None after a session ended with no enabled
+mode to resume to), and `run()` always showed `current_display_mode`.
+
+### Arbiter
+
+```python
+Arbiter.decide(state, inputs, now, running=None) -> 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.
+
+- `ArbiterState`: the current mode; the rotation and its index; the
+  on-demand session's modes, index, expiry and pin; the live resume point;
+  whether a mid-screen takeover has not shown yet. Transitions:
+  `next_on_demand`, `showing`, `claim_live`, `release_live`, `after`.
+- `ArbiterInputs`: whether the schedule has the panel on, an on-demand
+  session, a follower, the WiFi notice, the live modes (None where no scan
+  was made), whether Vegas is on and keeps live content in its ticker,
+  whether this pass's Vegas iteration has yielded, and (mid-screen) whether
+  a plugin reload is waiting.
+- `ScreenPlan`:
+
+| Field | Meaning |
+|---|---|
+| `source` | which Source won |
+| `mode`, `plugin` | what to draw (None for a blank or follower plan); the plugin id once resolved |
+| `min_duration`, `max_duration` | from `_resolve_durations` and the on-demand bound (`on_demand_bound`), filled in after the first frame; an on-demand plan's `max_duration` is what is left of the session at `now` |
+| `dynamic` | run until the plugin's cycle completes, between min and max |
+| `frame_policy` | `HIGH_FPS` or `STATIC`, today `_needs_high_fps`; see stage 5 |
+| `preemptible_by` | the Sources allowed to interrupt this plan mid-screen |
+| `notice`, `deadline`, `ends_live` | the WiFi notice; the on-demand expiry for the bound; "live priority just ended, resume the rotation first" |
+
+`decide` cannot ask a plugin anything, so the fields a plugin answers are
+filled in by the controller after the first frame, where they were always
+read (`_complete_plan`).
+
+With `running`, `decide` answers the mid-screen question instead: `running`
+itself while the screen holds, else the plan that ends it
+(`_hold_or_preempt`), in the order the frame loops always checked:
+
+1. Live: a game went live while a non-live screen runs. It is the one
+   preemption that changes the state (the rotation moves to the live mode
+   and remembers where it was), and it is claimed even when a WiFi notice
+   is also pending; the next pass shows the notice, then the game.
+2. The panel's mode moved under the screen (on-demand started, ended or
+   changed mode; the rotation was rebuilt).
+3. The schedule turned the panel off.
+4. A WiFi notice (unless on-demand outranks it), compared with its expiry.
+5. A plugin reload is waiting (between frames only).
+
+Every screen is preemptible by the gate, OnDemand, Wifi, Live, Rotation and
+a reload (`SCREEN_PREEMPTERS`), except that a live screen leaves Live out
+(`LIVE_PREEMPTERS`): live games take turns between screens. A follower and
+Vegas are looked at only between screens.
+
+### ScreenRunner
+
+```python
+ScreenRunner(clock: FrameClock, host: ScreenHost).run(plan, plugin) -> Outcome
+```
+
+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 | Golden-trace exit |
+|---|---|
+| `DURATION` | target duration reached (`duration`) |
+| `CYCLE_COMPLETE` | dynamic plugin finished after its minimum (`cycle-complete`) |
+| `EMPTY` | first frame returned False, or no plugin (`empty`; `raised` when display() raised inside the executor; `no-plugin`, `breaker`) |
+| `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`, `live`, `wifi`, ...) |
+| `RELOAD` | a plugin reload is waiting: the screen ends early but counts as shown, and the rotation advances |
+
+`PREEMPTED` replaces the five `current_display_mode != active_mode` checks.
+The runner asks its host at named service points (`Checkpoint`): `FRAME`
+after each frame (and when a socket command wakes the 1 Hz wait),
+`AFTER_LOOP` / `AFTER_COMPLETED_LOOP` when the frame loop ends,
+`after_dwell` after the make-up dwell, and `FINAL` before the rotation
+advances. Each is one `decide(..., running=plan)` call
+(`DisplayController._screen_check`). The checkpoint says whether a pending
+reload counts there and when the WiFi notice file is read (`NoticeRead`):
+the read is throttled to once a second and deletes an expired file, so it
+happens exactly where the loop always read it.
+
+In the 125 Hz loop the live-priority scan is made before the frame's sleep
+(`_screen_service`), at the moments it always was, and weighed by the
+service point after the sleep, where the loop always decided to end the
+screen.
+
+`FrameClock` provides `time()`, `perf_counter()` and `sleep()`, the shape of
+the `time` module. In production it is `_ModuleClock`, which looks up
+`src.display_controller.time` on each call, so the golden traces' fake clock
+drives the runner as it drove the inline loops. The runner's log lines use
+the controller's logger, so they keep their source in the journal.
+
+## 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, and one that cannot resume (its plugin did not load); a
+    request naming a live mode the plugin's live check would drop
+  - 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 18 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` (done; awaiting the ledpi soak)
+
+The plan, 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. `ArbiterInputs` gains the
+   live modes and whether Vegas is enabled and keeps live content in the
+   ticker.
+2. OnDemand returns its current mode with the session's bound, reading
+   `now` for the expiry. Live returns the next live mode (round-robin).
+   Rotation returns the rotation's mode. `ScreenPlan` gains `mode`,
+   `plugin`, `min_duration`, `max_duration`, `dynamic`, `frame_policy` and
+   `preemptible_by`.
+3. `ScreenRunner.run(plan)` returns an `ExitReason`; `state.after(outcome)`
+   replaces `_advance_after_screen`'s step and the live-resume bookkeeping.
+   Each mid-screen check asks `decide()` whether a Source in
+   `plan.preemptible_by` now wins.
+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.
+
+What shipped, one commit each: the runner; then the OnDemand, Live and
+Rotation Sources; then one `decide()` call at the service points.
+
+- `src/screen_runner.py` (on the mypy ratchet): `ScreenRunner`,
+  `FrameClock`, `ExitReason`, `Outcome`, `Checkpoint`, `NoticeRead`,
+  `Screen` and the `ScreenHost` protocol, which `DisplayController`
+  implements through `_ScreenHost` (one-line forwards to its own methods).
+  The two frame loops, the make-up dwell and the dynamic-duration exit
+  moved in unchanged, pacing included.
+- `src/display_arbiter.py`: `Source` gains `ON_DEMAND`, `LIVE`, `ROTATION`
+  and `RELOAD`; `LEGACY` means only Vegas. `FramePolicy`. `ArbiterState`
+  and `ArbiterInputs` as listed under "Arbiter". The pure helpers
+  `on_demand_bound` (`_clamp_to_on_demand`), `live_pick`
+  (`_check_live_priority`'s pick), `live_takeover` (the mid-screen claim)
+  and `rotation_plan`.
+- A pass asks `decide()` twice: once with the inputs every pass reads, and
+  once, only when nothing above the notice took the panel, with the Vegas
+  check and the live scan, read where run() always read them (the scan
+  asks every live-priority plugin, and the Vegas check applies queued
+  Vegas config, so reading them earlier, on a follower or notice pass,
+  would be a change). A Vegas iteration that yields asks a third time.
+- `_resolve_active_mode`, `_clamp_to_on_demand` and `_screen_preempted` are
+  gone. `_apply_live_priority`, `_check_live_priority`,
+  `_check_live_takeover` and `_wifi_notice_pending` remain (Vegas, the
+  dwell sleep and the tests call them), built on the same pure rules.
+- `_sleep_with_plugin_updates` keeps its own break rules. It also serves
+  the blank, the notice and the idle wait, which are not screens, and its
+  rules are edge-triggered (an on-demand session starting on the mode
+  already showing ends a dwell but not a frame loop); folding them into
+  `decide()` would change behaviour.
+
+Behaviour, checked three ways:
+
+- Golden traces: unchanged, no regeneration.
+- Every harness run in the suite (67: the goldens plus the live-takeover,
+  WiFi+live, socket-wake, plugin-reload, schedule and tick tests) was
+  captured with every sleep, `display()` call, WiFi read, live scan,
+  publish, dwell and scroll-state call logged, and diffed against
+  `origin/main`. Identical, except:
+  - a Vegas pass used to scan the live plugins twice at the same instant
+    (step 7, then step 8's "is anything live?"); it scans once;
+  - `_apply_live_priority(None)` calls that changed nothing are not made;
+  - throttled WiFi reads that returned the cached answer (no side effect)
+    after a notice had already ended the screen are not made;
+  - in the 125 Hz loop the live scan still runs before the frame's sleep,
+    but the claim is made by the service point after it, so the "live"
+    state change happens 8 ms later. The screen ends at the same frame as
+    before.
+- Tables: `test/test_display_arbiter.py` (OnDemand, Live, Vegas/Rotation,
+  `after`, the 24-row mid-screen table, `live_takeover`) and
+  `test/test_screen_runner.py` (the runner on a scripted host and fake
+  clock; the controller's service point and the reads it makes). A
+  mutation run broke each moved or new piece once; see the PR.
+
+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, before it merges.
+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.
+
+Open:
+
+- Vegas stops for a sync follower (its interrupt check includes
+  `is_follower_active`), but the yield path never looks at a follower, so a
+  full rotation screen (20 s in the test) runs before the next pass hands
+  the panel to the leader. Found by stage 3's mutation run;
+  `test_screen_runner.py::TestThroughRun::test_vegas_yielding_to_a_follower_shows_a_rotation_screen_first`
+  pins it. Stage 4, which drops the interrupt callback, is the natural
+  place to fix it.

docs/SCROLL_PERFORMANCE.md

@@ -73,6 +73,35 @@ 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.
+
+### A panel that cannot reach its cap
+
+Speeds are solved against `limit_refresh_rate_hz`, the configured cap, but a
+cap is only a ceiling: a long chain, a high `pwm_bits` or a big
+`gpio_slowdown` can leave the panel below it. One Pi 4 driving 2×128×64 on
+`adafruit-hat-pwm` with `pwm_bits 9` and `gpio_slowdown 5` measured
+107.6–113.1 Hz under a 120 Hz cap. Frames still move whole pixels, but
+every scroll runs that much slower than configured (60 px/s ran at 55 px/s),
+and the smooth speeds are the cap's rather than the panel's.
+
+The display measures the real rate from its own frames. About a minute
+into scrolling, a panel more than 3% short of its cap is logged once:
+
+```
+WARNING - src.common.frame_timing - The panel refreshes at about 113 Hz, below
+the 120 Hz that scroll speeds are planned for ... Set Limit Refresh Rate to
+100 Hz (web UI, Display tab), which this panel can hold, and restart.
+```
+
+The Display tab says the same under **Limit Refresh Rate**, with a button
+that fills in the suggested cap (`GET /api/v3/config/refresh-rate`). The
+suggestion is a multiple of 10 at least 5% under the measurement, because
+an uncapped panel drifts and the measurement is the fast end of it. A cap the
+panel holds also stops the drift.
+
 ### How a slow speed stays crisp
 
 `SwapOnVSync(canvas, framerate_fraction)` holds each frame for N panel
@@ -207,7 +236,10 @@ Fixed by rebuilding the binding: `scripts/build_rgbmatrix_nogil.sh`.
 ### 3. Sub-pixel blending was wrong for this display
 
 Enabling it made things worse, not better — see the rule at the top. It is off
-by default and only Vegas mode opts in via `set_sub_pixel_scrolling(True)`.
+by default everywhere. Vegas mode used to opt in; it now scrolls in whole
+pixels locked to the refresh like the plugin tickers, and keeps the blend only
+behind `display.vegas_scroll.sub_pixel_blend` (default `false`). The blend is
+also why text looked anti-aliased in the web preview while the panel shimmered.
 
 ### 4. Frame-based stepping raced the vsync clock
 
@@ -231,13 +263,24 @@ advances by elapsed time at `scroll_speed / scroll_delay` px/s.
 
 ## Diagnosing a juddery scroller
 
+To check a whole rig rather than one scroller, soak it -- see *Soaking a rig*
+below.
+
 **An average will lie to you.** A 2 ms duplicate frame and a 21 ms double-wait
 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"
@@ -276,6 +319,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
@@ -303,6 +350,306 @@ journalctl -u ledmatrix --since "-5min" --no-pager | grep -iE "px/s|px/frame"
 If a plugin logs its scroll config **twice** with different modes, the second
 line is what is running.
 
+## Soaking a rig
+
+The per-scroller lines above tell you *which* scroller misbehaves. The soak
+answers the question a release has to answer for each rig: **over a long run,
+how often did a moving frame reach the panel late?**
+
+Every frame reaches the panel through `DisplayManager.update_display`, so it is
+timed there once, whoever drew it -- Vegas, a ticker plugin, anything. The
+render thread only appends a tuple; a worker thread aggregates and rewrites
+`/dev/shm/ledmatrix_frame_stats.json` every 10 seconds (RAM, so no SD-card
+wear). `src/common/frame_timing.py` has the details.
+
+```bash
+python3 scripts/frame_soak.py                 # 10 minutes, as the display is now
+python3 scripts/frame_soak.py --preview       # with the web preview open
+python3 scripts/frame_soak.py --show          # totals since the service started
+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 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 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
+`scroll_speeds.py --measure` if it looks wrong. It can read high on a rig where
+nothing ever presented at the full refresh rate.
+
+A soak is only meaningful against a fixed workload. Compare runs with the same
+content and `--preview` setting, and alternate which build goes first when you
+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. 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
+
+Pi 4, 4×128×64 on one chain (512×64), `gpio_slowdown` 3, cap 120 Hz, the
+GIL-releasing binding. Vegas mode with live content, 8-minute soaks with
+`--preview`, run in the order shown so each build went both first and last.
+
+| run | build | pacing | pwm_bits | refresh | late | 1 | 2 | 3–5 | 6+ | freezes |
+|---|---|---|---|---|---|---|---|---|---|---|
+| 1 | main | time-based, blended, 90 px/s | 8 | 94.5 Hz | 6.33% | 2,542 | 74 | 19 | 4 | 0 |
+| 2 | #628 | 1 px / refresh | 8 | 100.2 Hz | 0.66% | 238 | 32 | 30 | 5 | 2 |
+| 3 | #628 | 1 px / refresh | 8 | 100.3 Hz | 0.70% | 252 | 38 | 26 | 6 | 2 |
+| 4 | main | time-based, blended, 90 px/s | 8 | 94.5 Hz | 6.46% | 2,659 | 90 | 10 | 4 | 0 |
+| 5 | #628 | 1 px / 2 refreshes (53 px/s) | **7** | 107.2 Hz | 0.32% | 68 | 7 | 4 | 2 | 1 |
+
+- Blending cost the panel refresh rate as well as frames: 94.5 Hz against
+  ~100 Hz for the same hardware under whole-pixel pacing.
+- The freezes and the 3+ rows in the #628 runs line up with canvas-bound
+  plugins fetched on the render thread (`drain_deferred`): `news` took ~320 ms
+  and `hockey-scoreboard` ~660 ms there. Moving those
+  fetches off the render thread is proposed separately (offscreen rendering).
+- Run 5 changed two things at once: the speed, and `pwm_bits` (changed on the
+  rig between runs). Its lower late rate cannot be credited to either alone.
+- These soaks were taken before the recorder counted 1–2 s stalls as freezes,
+  so a stall of that length would be missing from these rows.
+
+### Without the service: `render_bench.py`
+
+The soak measures the service as it really runs: live content, plugin
+updates, the web preview. `scripts/render_bench.py` answers the narrower
+question underneath: *with nothing else in the way, can this hardware present
+every frame on time?* It scrolls a synthetic strip through the production path
+-- a real `DisplayManager`, a real `ScrollHelper`, the same `scroll_config`
+resolver every ticker uses -- on content that is identical every run, which
+makes it the tool for comparing rigs (a Pi 3 against a Pi 4, one HAT against
+another) and for A/B testing a change to the render path.
+
+```bash
+sudo systemctl stop ledmatrix          # the service owns the GPIO
+
+sudo python3 scripts/render_bench.py                 # 60s at one pixel per refresh
+sudo python3 scripts/render_bench.py --seconds 600   # the shipping gate
+sudo python3 scripts/render_bench.py --speed 50      # a held (frame_hold 2) speed
+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
+```
+
+It never starts or stops the service itself, so a crash in it cannot leave
+the panel dark. It grades with the same recorder as the soak and prints the
+same report, with the same exit status, except that **2** also means the run
+could not be set up at all (no root, no panel, a fallback display), so a rig
+that was never measured cannot pass by accident.
+
+Two differences from the soak matter:
+
+- **It measures the panel first.** Before scrolling it times bare swaps for a
+  few seconds to get the idle refresh rate, and seeds the recorder with it.
+  That is what catches a loop that never locked to the panel at all. The first
+  version of the bench announced its scrolling state once instead of every
+  frame; the state expired, the dirty-tracking skip fired mid-scroll, and the
+  loop free-ran at 827 fps. Graded against its own frames that looks perfectly
+  steady; graded against the panel's measured rate every frame is early, and
+  the run fails as NOT LOCKED. (The soak has no idle measurement, so it checks
+  the rate against `limit_refresh_rate_hz` instead: a "refresh" faster than
+  the cap cannot have been waiting for the panel.)
+- **The stall watchdog prints to the terminal.** A frame held up for more than
+  250 ms prints the stack of what held it up, in the middle of the run.
+
+Measured with the first version of the bench on hdpi (Pi 4, 512x64,
+`pwm_bits` 8), two-minute runs at one pixel per refresh: 8 of 11,449 frames
+late (0.070%), and with `--busy 2` 3 of 11,445 (0.026%). The render path and
+the hardware pass on their own. Compare the soak results above, from the same
+rig with the service running, for how much of the late rate comes from
+everything else.
+
+### The panel is slower while you are rendering into it
+
+The bench prints two refresh rates, and they differ:
+
+| | Pi 4, 512x64, `pwm_bits` 8 |
+|---|---|
+| idle, timing bare swaps | 100.4 Hz |
+| while scrolling | 96.3 Hz |
+
+Both are real. Driving an LED matrix is bit-banging on the same machine, so
+`SetImage` over a 512x64 chain contends with the refresh itself and slows it.
+The recorder therefore reads the rendering rate back from the frames: swaps
+that block on vsync can only return on a refresh boundary, so the low end of
+`interval / frame_hold` is the period. The idle figure is still printed,
+because the gap between the two is itself a measure of how expensive a frame
+is: **a rise in that gap is a render-cost regression even when nothing is
+late.**
+
+The practical consequence for config: set `limit_refresh_rate_hz` near the rate
+the panel holds *while rendering*, not the idle rate and certainly not a cap it
+can never reach. A cap well above the real rate makes `scroll_config` solve
+speeds against a refresh that does not exist, which is where "3px every 4
+refreshes" comes from.
+
+### Bench-only counters
+
+| line | meaning |
+|---|---|
+| `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
+compared without re-reading a terminal.
+
+---
+
+## A tear across the middle on fast scrolls
+
+**Symptom:** while text scrolls, the top and bottom halves of the panel look
+shifted sideways against each other along a horizontal line at mid-height, and
+the shift grows with scroll speed. It shows most in Vegas mode at high speed.
+
+**It is the panel's scan, not the software.** The measured panel, like most
+64-row panels, is multiplexed 1:32 (some panels of the same size scan
+differently, so check yours): it lights two rows at a time, one from each half
+(row 0 with row 32, row 1 with row 33, …), stepping down both halves together
+once per refresh. So row 31,
+the last row of the top half, lights almost a whole refresh period after row 32
+right below it. Your eye follows moving text, and moving content that lights at
+different times lands in different places, so the two rows meet with an offset
+of roughly
+
+```
+offset ≈ scroll speed × refresh period
+```
+
+Each frame reaches the panel whole (`SwapOnVSync` swaps complete frames between
+refreshes); the shift is created inside a single refresh. Other panel heights
+show it too, at the point where their two scan halves meet.
+
+On the 2×128×64 chain above, which refreshes at about 130 Hz flat out
+(7.7 ms per pass):
+
+| scroll speed | offset at the midline |
+|---|---|
+| 50 px/s (Vegas default) | ~0.4 px |
+| 100 px/s | ~0.8 px |
+| 150 px/s | ~1.2 px, plainly visible |
+
+### What the display does about it
+
+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
+(`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
+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:
+
+- **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).
+- **The emulator,** which has no scan order.
+
+### When it cannot apply
+
+Only a shorter scan period (a faster refresh) or a slower scroll. Measure what
+the panel actually achieves first. The library prints the rate with a carriage
+return and no newline, so read it from the raw journal:
+
+```bash
+# set display.hardware.show_refresh_rate to true (web UI, Display tab), restart, then:
+journalctl -u ledmatrix --since "-1min" --no-pager -o cat --all | grep -a -oE "[0-9.]+Hz" | tail -5
+```
+
+Turn it off again afterwards. Measured on that panel (Pi 4, single chain),
+changing one setting at a time from `pwm_bits: 7`, `gpio_slowdown: 3`:
+
+| change | refresh, uncapped | notes |
+|---|---|---|
+| none | ~130 Hz | the ceiling for this wiring |
+| `pwm_bits: 6` | ~138 Hz | barely faster, and half the colour depth |
+| `gpio_slowdown: 2` | ~130 Hz | no faster, **and visible glitching**; keep 3 |
+| `limit_refresh_rate_hz: 0` | ~130 Hz | Vegas dropped from 100 to 72–95 fps as the refresh thread took more CPU |
+
+None of these helps much, because the time goes into shifting each row's pixels
+out: a 2×128 chain pushes 256 pixels per row down one output. What does help is
+**fewer pixels per output**. On a bonnet with more than one output (the
+`regular` and `classic` mappings have 3; `adafruit-hat` has 1), put each panel
+on its own output and set `parallel` to the number of outputs used and
+`chain_length` to the panels per output, for example `parallel: 2`,
+`chain_length: 1` for two panels. Each refresh then shifts half the data, which
+should roughly double the refresh rate and halve the offset. That is a cable
+change, so measure again afterwards.
+
+Short of rewiring, keep fast scrolls moderate on those layouts: at 50 px/s the
+offset is under half a pixel.
+
 ## Rebuilding the binding
 
 ```bash

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
 
@@ -73,14 +74,27 @@ B2 below promoted code into it (`SportsCore`, the mode classes,
 capabilities sections record that design, but none of it ships in core any
 more. Shared sports code lives in `src/common`:
 
-```
-src/common/
-  sports_scroll.py       SportsScrollDisplay / …Manager — scroll orchestration
-                         (content building stays in the plugins)
-  sports_helpers.py      clamp/logo/rotation free functions + SportsHelpersMixin
-                         (3.5.0) — the helpers byte-identical in the
-                         plugins' sports.py, and the _favorite_key seam
-```
+| Module | Since | Holds |
+|---|---|---|
+| `sports_scroll.py` | 3.2.0 | `SportsScrollDisplay` / `SportsScrollDisplayManager` — scroll orchestration (content building stays in the plugins) |
+| `sports_card.py` | 3.3.0 | Free functions for card settings, colours, favourite-team rules, dates and font sizes |
+| `sports_game_renderer.py` | 3.3.0 | `SportsGameRendererMixin` — scroll/Vegas card geometry |
+| `sports_shared.py` | 3.3.0 | `SportsCoreSharedMixin`, `SportsLiveSharedMixin`, `SportsRecentSharedMixin` — the sport-independent `sports.py` methods |
+| `sports_helpers.py` | 3.5.0 | clamp/logo/rotation free functions and `SportsHelpersMixin`, plus the `_favorite_key` seam |
+| `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` | 3.8.0 | `SportsPluginHostMixin` — the plugin class's (`manager.py`) identical helpers: Vegas weight, off-thread switch refresh |
+| `sports_live_scroll.py` | 3.8.0 | `SportsLiveScrollMixin` — rebuild a live scroll strip mid-cycle, keeping the marquee's place |
+| `sports_display_rules.py` | 3.8.0 | `SportsCardOptionsMixin`, `SportsGameRulesMixin` — scorebug date options, the no-favourites filter, non-favourite live dwell |
+| `sports_font_path.py` | 3.8.0 | `resolve_font_path` — what the plugins' `_resolve_font_path` copies return |
+| `sports_game_over.py` | 3.8.1 | `SportsGameOverMixin` — `_is_game_really_over`, with the `FINAL_PERIOD` seam (family 5) |
+| `sports_favorites.py` | 3.8.2 | `SportsFavoritesMixin`, `SportsUpcomingFavoritesMixin`, `SportsRecentFavoritesMixin` — `_is_favorite_game` and the favourites-only picks, on the `_favorite_key` seam (family 6) |
+
+Each is described in [src/common/README.md](../src/common/README.md).
 
 ### Converging on `src/common`
 
@@ -90,9 +104,11 @@ 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 first (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;
+`sports_favorites.py` is what calls it.
+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
@@ -112,7 +128,7 @@ deprecation cycle.
 | `_custom_scorebug_layout(game, draw)` | Per-sport overlay on the base layout | no-op |
 | `score_phrase(points, team_abbr)` | Celebration wording (`"GOOOOAAALLL!"` vs `"TOUCHDOWN!"`). `points` is the score delta, which sports with variable-value scores use to name the play | `"<abbr> SCORES!"` — only consulted when `CelebrationMixin` is present |
 | `win_phrase(team_abbr)` | Win-celebration wording | `"<abbr> WINS!"` — mixin only |
-| `_favorite_key(game, side)` | Which view-model field identifies a team for favorites matching | `game["<side>_abbr"]` |
+| `_favorite_key(game, side)` | Which view-model field identifies a team for favorites matching. `sports_favorites` compares it, and each `favorite_teams` entry, stripped and upper-cased; a `None` matches nothing | `game["<side>_abbr"]`. nrl returns the ESPN team id, `None` when it is missing |
 | `_config_schema_path()` | Plugin's `config_schema.json` — returning it routes `_get_layout_offset` through the `src.element_style` resolver (and gives it the defaults to compare against) | `None`, i.e. the classic inline `customization.layout` read |
 | `_font_root()` | Directory to resolve `assets/fonts` against | core install root |
 
@@ -121,8 +137,7 @@ constants rather than behavior:
 
 | Attribute | Meaning | Default |
 |---|---|---|
-| `FINAL_PERIOD` | Period at/after which a zero clock can mean "over" | `4` (hockey overrides to `3`) |
-| `CLOCK_COUNTS_DOWN` | Whether `0:00` means "expired" | `True` (soccer/afl/nrl override to `False` — their clocks count up, so `0:00` is kickoff) |
+| `FINAL_PERIOD` | Period from which a 0:00 clock ends a game (`sports_game_over`) | `None`: the clock never ends a game (afl, nrl, soccer, baseball, ufc). Hockey sets `3`; basketball, football and lacrosse `4` |
 | `COALESCE_SCORING_SEQUENCE` | Fold score increments arriving during an active celebration into that one celebration | `False` (football overrides to `True` — a touchdown lands as +6, then +1 for the extra point) |
 
 ### Why these are seams and not branches
@@ -133,11 +148,14 @@ so NRL matches favorites on team ID. Flattening every plugin to abbreviations
 would silently select the wrong club for NRL users. The base declares the seam,
 NRL fills it, and core never learns the string `"nrl"`.
 
-`CLOCK_COUNTS_DOWN` exists for the same reason in the opposite direction: a
+`FINAL_PERIOD` exists for the same reason in the opposite direction: a
 soccer clock reading `0:00` means the match has not kicked off, so running the
-clock-expiry branch there would evict live games.
+clock-expiry rule there would evict live games. Those sports declare `None`,
+and so do baseball (innings, not a clock) and ufc (a bout ends only on ESPN's
+final status). One attribute covers both questions, whether the clock can end
+a game and from which period, so no separate count-down flag was added.
 
-`COALESCE_SCORING_SEQUENCE` is the third of the same kind. In football one
+`COALESCE_SCORING_SEQUENCE` is another of the same kind. In football one
 scoring play arrives as two score updates, so the follow-up must be folded into
 the first celebration; in soccer two increments a few seconds apart are two real
 goals, and folding them would swallow one. Neither default is "right" — which is
@@ -164,6 +182,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
@@ -219,12 +246,334 @@ 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.
+
+### Family 5: the game-over check (core done; adoption waits for a release)
+
+The pilot of the method below. ledmatrix-plugins `scripts/test_game_over_check.py`
+(#621) pinned 3,115 answers across the nine plugins first; the reconcile
+(ledmatrix-plugins #625) made the five bodies one and
+changed only the cells the owner's decisions under
+[Product decisions](#product-decisions-each-family-needs) explain: ufc's
+clock rule (65 cells), baseball's dormant one (53, every one a game with a
+`period` baseball's games never carry), and a level score at 0:00 (five
+cells in hockey, basketball, football and lacrosse). The harness renders
+were pixel-identical. `src/common/sports_game_over.py` holds the body;
+`test/test_sports_game_over_parity.py` compares it, and each plugin's
+`FINAL_PERIOD`, with the plugin copies.
+
+### Family 6: favourite matching (core done; adoption waits for a release)
+
+ledmatrix-plugins `scripts/test_favourite_matching.py` (#634) pinned 204 rows
+across the nine plugins first: `_is_favorite_game` on each manager role, the
+two selection methods, the real `update()` with favourites-only on and off,
+and the INFO summary; the reconcile extends it to 217 (a lower-case and a
+padded favourite through `update()`, and the live favourite boost). The reconcile (ledmatrix-plugins
+#635) made `_is_favorite_game` one body on `SportsCore`
+(afl and soccer's `SportsUpcoming` copies and five `SportsLive` copies, all
+redundant, are gone), added `_favorite_code` beside it, and gave nrl a
+`_favorite_key` override instead of its own copies. So that a lower-case
+favourite works on a favourites-only Upcoming board, the Upcoming `update()`'s
+favourites-only pre-filter and the basketball, hockey and lacrosse live boost
+now ask `_is_favorite_game` too (a one-line change each; `update()` itself is
+family 13). Of 3,897 cells only those the decisions above explain changed:
+case and spaces in eight plugins (30-40 each), the id-less duplicate fix (6-8
+each), nrl's key (6) and its "None" match (6), and the INFO line in baseball,
+football and ufc. The harness renders were byte-identical. `src/common/sports_favorites.py` holds the
+bodies, one mixin per carrying class; `test/test_sports_favorites_parity.py`
+compares them with the plugin copies and checks that only nrl overrides
+`_favorite_key`.
+
+Left for later families: the live screens' favourites-only filter
+(`_classify_live_game` and its inline copies) and favourites-first sort still
+compare abbreviations exactly, and
+`SportsCoreSharedMixin._round_robin_favorites` groups favourites by raw
+abbreviation (or by `_team_in` where a plugin has one) instead of through
+`_favorite_key`. The result-colour helpers also wait (decision above).
+
+### 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`, `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; one seam, `FINAL_PERIOD`. The pilot for the procedure. Reconciled to one body and promoted as `sports_game_over`; adoption waits for the release that ships it. See [Family 5](#family-5-the-game-over-check-core-done-adoption-waits-for-a-release) |
+| 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. Reconciled to one body each and promoted as `sports_favorites`; adoption waits for the release that ships it. See [Family 6](#family-6-favourite-matching-core-done-adoption-waits-for-a-release) |
+| 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. Decided 2026-10-05, done:** one seam,
+  `FINAL_PERIOD`: hockey 3; basketball, football and lacrosse 4; `None` (the
+  clock never ends a game) for afl, nrl and soccer (clocks that count up),
+  baseball (its games carry no `period`, so the old rule was dormant) and
+  ufc (a bout ends only on ESPN's final status, which also closes the ~1 s
+  window at the horn when the ticking clock reads `0:00`; ESPN's round-break
+  displayClock `-` was never a zero clock, ledmatrix-plugins#580). Only a
+  non-empty clock string counts (the baseball/ufc copy read a missing clock
+  as `0:00`). A score level at 0:00 is not over: the game stays live through
+  the break before overtime, and one that really ends tied ends on its final
+  status. Baseball keeps its postponed/suspended override in `BaseballLive`.
+- **6, favourite matching. Decided 2026-10-05, done:** each side of a game is
+  named by `_favorite_key` (the abbreviation; NRL overrides it with the ESPN
+  team id, and `None` for a missing id, which fixes a favourite typed "None"
+  matching every game without one) and compared with `favorite_teams`
+  stripped and upper-cased, so " bos" matches BOS. NRL's ambiguous "NEW"
+  still matches nothing and is logged; routing the result-colour helpers
+  (`side_is_favorite`, which tint both NEW clubs) through `_favorite_key` is
+  left for a later family. The recent-games selection logs at INFO in all
+  nine. ufc stays on the shared body, dormant: its favourites are fighters,
+  which its MMA managers match themselves (a follow-up). Fix ported: only a
+  game with an id can be a duplicate in the selection methods.
+- **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 |
 |---|---|---|---|
@@ -259,8 +608,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
@@ -423,10 +776,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
 
@@ -469,40 +825,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
 
@@ -529,7 +857,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/STARLARK_APPS_GUIDE.md

@@ -102,9 +102,16 @@ cd /path/to/LEDMatrix
 bash scripts/download_pixlet.sh
 ```
 
+The script downloads only the Linux ARM64 build (Raspberry Pi OS 64-bit),
+from the `tronbyt/pixlet` releases, to `bin/pixlet/pixlet-linux-arm64`. On
+any other platform (32-bit Pi OS, x86_64, macOS), put a `pixlet` binary on
+your `PATH`, or set the plugin's `pixlet_path`, or place it in `bin/pixlet/`
+under the name `_find_pixlet_binary()` looks for
+([`web_interface/blueprints/api_v3/__init__.py`](../web_interface/blueprints/api_v3/__init__.py)).
+
 Verify installation:
 ```bash
-./bin/pixlet/pixlet-linux-amd64 version
+./bin/pixlet/pixlet-linux-arm64 version
 # Pixlet 0.50.2 (or later)
 ```
 
@@ -276,10 +283,8 @@ LEDMatrix/
 │           ├── hour_hand.png
 │           └── minute_hand.png
 │
-├── bin/pixlet/                     # Pixlet binaries
-│   ├── pixlet-linux-amd64
-│   ├── pixlet-linux-arm64
-│   └── pixlet-darwin-arm64
+├── bin/pixlet/                     # Pixlet binary
+│   └── pixlet-linux-arm64          # the only one download_pixlet.sh fetches
 │
 └── scripts/
     └── download_pixlet.sh          # Pixlet installer
@@ -324,7 +329,7 @@ Many apps require API keys for external services:
 **Solutions**:
 1. Check logs: `journalctl -u ledmatrix | grep -i pixlet`
 2. Verify config: Ensure all required fields are filled
-3. Test manually: `./bin/pixlet/pixlet-linux-amd64 render starlark-apps/{app-id}/{app-id}.star`
+3. Test manually: `./bin/pixlet/pixlet-linux-arm64 render starlark-apps/{app-id}/{app-id}.star`
 4. Missing assets: Some apps need images/fonts that may fail to download
 5. API issues: Check API keys and rate limits
 

docs/TROUBLESHOOTING.md

@@ -84,6 +84,46 @@ 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.
+- "A desktop is running": use the Lite image, not the desktop one, or boot
+  to the console with `sudo systemctl set-default multi-user.target` and
+  reboot. Desktop packages that are installed but not running only produce a
+  warning, and the install continues.
+- "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:**
@@ -201,10 +241,11 @@ sudo systemctl restart ledmatrix-web
 
 **Solutions:**
 
-1. **Install dependencies:**
+1. **Install dependencies** as root, so the root display service can import
+   them:
    ```bash
-   pip3 install --break-system-packages -r requirements.txt
-   pip3 install --break-system-packages -r web_interface/requirements.txt
+   sudo python3 -m pip install --break-system-packages --no-cache-dir -r requirements.txt
+   sudo python3 -m pip install --break-system-packages --no-cache-dir -r web_interface/requirements.txt
    ```
 
 2. **Test imports step-by-step:**
@@ -250,15 +291,18 @@ sudo systemctl restart ledmatrix-web
 
 **Solutions:**
 
-```bash
-# Fix ownership of LEDMatrix directory
-sudo chown -R ledpi:ledpi /home/ledpi/LEDMatrix
+[PERMISSIONS.md](PERMISSIONS.md) lists the expected owner and mode of every
+file and directory, and which `scripts/fix_perms/` script to run as which
+user. Don't `chown -R` the whole project: the two sudo helper scripts in
+`scripts/fix_perms/` must stay owned by root.
 
-# Fix config file permissions
+```bash
+# Config files: web user owns both; secrets must stay 640
+stat -c '%U:%G %a %n' config/config.json config/config_secrets.json
 sudo chmod 644 config/config.json
 sudo chmod 640 config/config_secrets.json
 
-# Verify service runs as correct user
+# Which user the web interface runs as
 sudo systemctl cat ledmatrix-web | grep User
 ```
 
@@ -291,6 +335,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
@@ -324,9 +447,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
@@ -462,15 +592,17 @@ sudo systemctl cat ledmatrix-web | grep User
    }
    ```
 
-2. **Restart display:**
-   ```bash
-   sudo systemctl restart ledmatrix
-   ```
+   Or toggle the plugin on in the **Plugin Manager** tab, which writes the
+   same flag.
 
-3. **Verify in web interface:**
-   - Open the **Plugin Manager** tab
-   - Toggle the plugin switch to enable
-   - From **Overview**, click **Restart Display Service**
+2. **Wait a few seconds.** The display service watches `config.json` and
+   loads a newly enabled plugin without a restart
+   (`DisplayController._reconcile_enabled_plugins()` in
+   [`src/display_controller.py`](../src/display_controller.py)). This
+   needs hot reload, which is on unless `LEDMATRIX_HOT_RELOAD=false` is set.
+
+3. **If it still does not appear**, check the logs for a config validation
+   error, then restart: `sudo systemctl restart ledmatrix`
 
 #### Plugin Not Loading
 
@@ -491,10 +623,12 @@ sudo systemctl cat ledmatrix-web | grep User
    # Verify all required fields present
    ```
 
-3. **Check dependencies installed:**
+3. **Check dependencies installed.** Install them with `sudo`: the display
+   service runs as root and does not see packages pip put in your user's
+   `~/.local` (see [PLUGIN_DEPENDENCY_GUIDE.md](PLUGIN_DEPENDENCY_GUIDE.md)):
    ```bash
    if [ -f plugin-repos/plugin-id/requirements.txt ]; then
-     pip3 install --break-system-packages -r plugin-repos/plugin-id/requirements.txt
+     sudo python3 -m pip install --break-system-packages --no-cache-dir -r plugin-repos/plugin-id/requirements.txt
    fi
    ```
 
@@ -503,16 +637,70 @@ sudo systemctl cat ledmatrix-web | grep User
    sudo journalctl -u ledmatrix -f | grep plugin-id
    ```
 
-5. **Test plugin import:**
+5. **Load and render the plugin headlessly:**
    ```bash
-   python3 -c "
-   import sys
-   sys.path.insert(0, 'plugin-repos/plugin-id')
-   from manager import PluginClass
-   print('Plugin imports successfully')
-   "
+   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:**
@@ -540,10 +728,12 @@ sudo systemctl cat ledmatrix-web | grep User
    sudo systemctl restart ledmatrix
    ```
 
-2. **Check cache permissions:**
+2. **Check cache permissions.** Expected: `root:ledmatrix`, `drwxrwsr-x`.
+   `setup_cache.sh` restores that layout (see
+   [PERMISSIONS.md](PERMISSIONS.md#repair-scripts)):
    ```bash
    ls -ld /var/cache/ledmatrix
-   sudo ./scripts/fix_perms/fix_cache_permissions.sh
+   sudo bash scripts/install/setup_cache.sh
    ```
 
 ---
@@ -611,6 +801,15 @@ sudo systemctl cat ledmatrix-web | grep User
    ```
    **Note:** Minimum recommended: 300 seconds (5 minutes)
 
+   How often the core calls the plugin's `update()` comes from the plugin
+   itself first: its `get_update_interval()` if it has one, then
+   `update_interval` in its `manifest.json`. The `update_interval` in
+   `config.json` is used by the scheduler only when the manifest sets none.
+   Many plugins also read their own config `update_interval` and skip the
+   API call inside `update()` until it has elapsed, which is what makes the
+   setting above effective; check the plugin's settings form or
+   `config_schema.json` for the option it actually honours.
+
 2. **Check current rate limit usage:**
    - OpenWeatherMap free tier: 1,000 calls/day, 60 calls/minute
    - With 300s interval: 288 calls/day (well within limits)
@@ -938,6 +1137,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,353 @@
+# 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
+    visibility.js       ctx.visibility: a page's timers run only while it is on screen
+    (later) escape.js, notify.js, dialog.js, streams.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.
+- **Polling goes through `ctx.visibility`.** A refresh that repeats
+  (`ctx.visibility.every(ms, fn)`) or work that should run only while the
+  page is on screen (`ctx.visibility.whileVisible(start, stop)`) is
+  registered there, never with a bare `setInterval`. It runs only while the
+  page's tab is the active tab and the browser tab is visible, and it ends
+  when the page is destroyed, with no code in `destroy()`.
+- **A page reports its own htmx saves.** A form whose result a page module
+  shows (an `htmx:afterRequest` listener on the page root, in place of an
+  `hx-on` attribute naming a global) carries `data-reports-result`. `app.js`
+  then leaves the server's message to the page, as it does for a form with
+  an `hx-on` after-request handler, so a save shows one notification.
+- **Server data for the module goes in `data-*` attributes**, as JSON where
+  it is structured (`data-schedule-config='{{ schedule_config | tojson }}'`),
+  not templated into a script.
+
+`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` |
+| `ctx.visibility` | This page's handle on `core/visibility.js` (below), made per mount by `boot.js` through the registry's `mountContext` option |
+
+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.
+
+### Page visibility
+
+`core/visibility.js` gives each mounted page `ctx.visibility`:
+
+| Member | What it does |
+|---|---|
+| `whileVisible(start, stop)` | Runs `start()` when the page comes on screen (at once, if it mounts on screen) and `stop()` when it leaves. Returns a function that ends the registration, running `stop()` first if needed |
+| `every(ms, fn)` | `fn()` at once, then every `ms` while on screen. The interval is cleared while hidden and restarted, with an immediate `fn()`, when the page is back. Returns the same kind of end function |
+| `isVisible()` | True while the page is on screen |
+| `tab` | The tab the page belongs to: its name, or `forPage(ctx, { tab })` |
+
+"On screen" means the page's tab is the active tab and the browser tab is
+visible. Everything a page registered ends when its `ctx.signal` aborts,
+after `destroy()`, so a swapped-out partial leaves no interval behind.
+
+The answer comes from `window.LEDVisibility` (`app-shell.js`), read at call
+time, so the page modules and the classic partials that still call it
+(Overview, Logs, Tools) agree on the active tab, and the SSE streams keep
+pausing with them. Each registration takes its own `LEDVisibility` key, so
+registrations never replace each other or a classic partial's. Without
+`LEDVisibility` (a page outside `base.html`), the browser tab's visibility
+alone decides. Moving the tracker itself into the module (the shell table
+below) changes only `core/visibility.js`.
+
+### 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 lines, now 0 | **Done in stage 3.** Its 2 `hx-on` response handlers (`handleScheduleResponse`, `handleDimScheduleResponse`) are one `htmx:afterRequest` listener on the page root, and deprecated aliases. The forms are marked `data-reports-result` so `app.js` does not repeat the server's message. The saved schedules reach the module as JSON in `data-schedule-config` / `data-dim-schedule-config` instead of being templated into the script |
+| 7 | General | 153 lines, now 0 | **Done in stage 3.** The Security section's three forms and two buttons are delegated `data-action`s (one submit and one click listener); `window.webLogin` is a deprecated alias of an object with its five methods. Login requests go through `ctx.api`, so the login redirect is quiet. The settings form keeps its `hx-on` call to the shared `showSaveResult`, as Rotation's does |
+| 8 | Display | 292 lines (2 scripts), now 0 | **Done in stage 4.** The first page with a timer: the 5 s multi-display sync poll is `ctx.visibility.every(5000, ...)` (above), so it runs only while the tab is on screen and stops when the partial is swapped out. Its one global, `updateSyncUI` (the Role menu's `onchange`), is a deprecated alias; the Advanced section's `onclick` is a delegated `data-action="toggle-section"` that calls the shared `toggleSection`. The status poll and the scroll-speed hint go through `ctx.api` with `ctx.signal`, as does the Vegas order widget's plugin-list request. The settings form keeps its `hx-on` call to `showSaveResult` and its `onsubmit` call to `fixInvalidNumberInputs`, as Rotation's does |
+| 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` (the page-facing `ctx.visibility` is there since step 8; it reads the tracker from `app-shell.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, `mountContext` fields per mount |
+| `dom/test_visibility_service.js` | DOM: real `LEDVisibility` from `app-shell.js`, real registry, no server | `whileVisible` and `every` start and stop with the active tab and the browser tab's visibility; no interval runs while hidden or after a swap-out; one interval after five swaps; registrations never replace each other or a classic partial's; a destroyed page registers nothing; a throwing `start()` is contained; the no-`LEDVisibility` fallback |
+| `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_schedule_page.js` | DOM: real partial, real widget | Both pickers drawn once per swap from the saved config; after five swaps each form's answer is one notification (message, fallback, refused, non-JSON, `null`), a request from outside the forms none; the brightness label; a late widget waited for, a page swapped away while waiting draws nothing; the old globals' entry points |
+| `dom/test_display_page.js` | DOM: real partial, real widget, real `LEDVisibility`, real API shape | After five swaps one page, one sync interval, the Vegas order drawn once and each control acting once (brightness, resolution, the two show/hide toggles, the Advanced toggle, one debounced hint request); the sync poll only while on screen and never after a swap-out; sync states and hostile peer names as text, failure and login answers; a late widget waited for; `updateSyncUI`'s entry point |
+| `dom/test_general_page.js` | DOM: real partial, real widget, real API shape | The timezone picker drawn once per swap with the saved zone; the settings form left to htmx; after five swaps each Security action makes one request (create, copy, revoke and its cancel, password and its mismatch); hostile token names stay text; refused, network and login answers; a create made before a swap is still reported and draws nothing; `webLogin`'s 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:
@@ -161,7 +196,11 @@ duration, and related settings — so you can configure Vegas mode
 entirely from the web UI without hand-editing JSON. See
 [ADVANCED_FEATURES.md](ADVANCED_FEATURES.md) for what the options do.
 
-Changes require **Restart Display Service** from the Overview tab.
+Brightness and the Vegas Scroll settings apply to the running display
+within a few seconds. Matrix hardware settings (rows, columns, chain length,
+mapping, GPIO slowdown, PWM and refresh settings) are only read when the
+display starts, so those need **Restart Display Service** from the Overview
+tab.
 
 ### Plugin Manager Tab
 
@@ -248,16 +287,16 @@ View real-time system logs:
 
 1. Open the **Display** tab
 2. Adjust the **Brightness** slider (1–100)
-3. Click **Save**
-4. Click **Restart Display Service** on the **Overview** tab
+3. Click **Save**. The panel picks up the new brightness within a few
+   seconds; no restart is needed
 
 ### Installing a New Plugin
 
 1. Open the **Plugin Manager** tab
 2. Scroll to the **Plugin Store** section and browse or search
 3. Click **Install** next to the plugin
-4. Toggle the plugin on in **Installed Plugins**
-5. Click **Restart Display Service** on **Overview**
+4. Toggle the plugin on in **Installed Plugins**. The running display
+   loads it within a few seconds; no restart is needed
 
 ### Configuring a Plugin
 
@@ -342,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.
 
 ---
@@ -404,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)
@@ -424,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

docs/widget-guide.md

@@ -1,590 +1,7 @@
 # Widget Development Guide
 
-## Overview
-
-The LEDMatrix Widget Registry system allows plugins to use reusable UI components for configuration forms. This enables:
-
-- **Reusable Components**: Use existing widgets (file upload, checkboxes, etc.) without custom code
-- **Custom Widgets**: Create plugin-specific widgets without modifying the LEDMatrix codebase
-- **Backwards Compatibility**: Existing plugins continue to work without changes
-
-## Available Core Widgets
-
-### Plugin File Manager Widget (`plugin-file-manager`)
-
-Full inline file management UI for plugins that manage files via the `web_ui_actions` system. Renders a card grid, upload zone, create/delete modals, and an entry table editor — entirely inline, no iframe.
-
-`plugin_id` is **automatically injected** from template context. File operations call `/api/v3/plugins/action` immediately on user action; no Save Configuration needed.
-
-**Schema Configuration:**
-```json
-{
-  "file_manager": {
-    "type": "null",
-    "title": "Data Files",
-    "x-widget": "plugin-file-manager",
-    "x-widget-config": {
-      "actions": {
-        "list":   "list-files",
-        "get":    "get-file",
-        "save":   "save-file",
-        "upload": "upload-file",
-        "delete": "delete-file",
-        "create": "create-file",
-        "toggle": "toggle-category"
-      },
-      "upload_hint":      "JSON files with day numbers 1–365 as keys",
-      "directory_label":  "my_data/",
-      "create_fields": [
-        { "key": "category_name", "label": "Category Name",
-          "placeholder": "e.g., my_words", "pattern": "^[a-z0-9_]+$",
-          "hint": "Lowercase letters, numbers, underscores" },
-        { "key": "display_name", "label": "Display Name",
-          "placeholder": "e.g., My Words", "hint": "Optional" }
-      ]
-    }
-  }
-}
-```
-
-**`list` is required** — the widget calls it on render to populate the file grid; omitting it leaves the widget stuck in a loading state. All other actions are optional — omit any key to hide its UI element (e.g., no `create` = no New File button, no `toggle` = no enable/disable switch).
-
-The edit view auto-detects whether file content is tabular (object-of-objects with uniform keys) and shows a paginated table editor with inline cells. Otherwise falls back to a JSON textarea.
-
-**Used by:** of-the-day
-
----
-
-### Time Picker Widget (`time-picker`)
-
-Single time selection using the browser's native time input. Returns a string in `HH:MM` (24-hour) format. Generic — works in any plugin without configuration.
-
-**Schema Configuration:**
-```json
-{
-  "target_time": {
-    "type": "string",
-    "x-widget": "time-picker",
-    "default": "00:00",
-    "x-options": {
-      "placeholder": "Select time",
-      "clearable": true
-    }
-  }
-}
-```
-
-**Used by:** countdown
-
----
-
-### File Upload Single Widget (`file-upload-single`)
-
-Single-image upload for string fields. Uploads to the plugin's asset folder (`assets/plugins/<plugin_id>/uploads/`) and sets the string field value to the returned relative path. Shows a thumbnail preview and a clear button. The `plugin_id` is **automatically injected** from the template context — no need to specify it in the schema.
-
-**Schema Configuration:**
-```json
-{
-  "image_path": {
-    "type": "string",
-    "x-widget": "file-upload-single",
-    "x-upload-config": {
-      "allowed_types": ["image/png", "image/jpeg", "image/bmp", "image/gif"],
-      "max_size_mb": 5
-    }
-  }
-}
-```
-
-Note: Unlike `file-upload` (array-level), this widget is for a single `string` field. It is ideal for per-item images inside `array-table` rows.
-
-**Used by:** countdown
-
----
-
-### File Upload Widget (`file-upload`)
-
-Upload and manage image files with drag-and-drop support, preview, delete, and scheduling.
-
-**Schema Configuration:**
-```json
-{
-  "type": "array",
-  "x-widget": "file-upload",
-  "x-upload-config": {
-    "plugin_id": "my-plugin",
-    "max_files": 10,
-    "max_size_mb": 5,
-    "allowed_types": ["image/png", "image/jpeg", "image/bmp", "image/gif"]
-  }
-}
-```
-
-**Used by:** static-image, news plugins
-
-### Checkbox Group Widget (`checkbox-group`)
-
-Multi-select checkboxes for array fields with enum items.
-
-**Schema Configuration:**
-```json
-{
-  "type": "array",
-  "x-widget": "checkbox-group",
-  "items": {
-    "type": "string",
-    "enum": ["option1", "option2", "option3"]
-  },
-  "x-options": {
-    "labels": {
-      "option1": "Option 1 Label",
-      "option2": "Option 2 Label"
-    }
-  }
-}
-```
-
-**Used by:** odds-ticker, news plugins
-
-### Custom Feeds Widget (`custom-feeds`)
-
-Table-based RSS feed editor with logo uploads.
-
-**Schema Configuration:**
-```json
-{
-  "type": "array",
-  "x-widget": "custom-feeds",
-  "items": {
-    "type": "object",
-    "properties": {
-      "name": { "type": "string" },
-      "url": { "type": "string", "format": "uri" },
-      "enabled": { "type": "boolean" },
-      "logo": { "type": "object" }
-    }
-  },
-  "maxItems": 50
-}
-```
-
-**Used by:** news plugin (for custom RSS feeds)
-
-## Using Existing Widgets
-
-To use an existing widget in your plugin's `config_schema.json`, simply add the `x-widget` property:
-
-```json
-{
-  "properties": {
-    "my_images": {
-      "type": "array",
-      "x-widget": "file-upload",
-      "x-upload-config": {
-        "plugin_id": "my-plugin",
-        "max_files": 5
-      }
-    },
-    "enabled_leagues": {
-      "type": "array",
-      "x-widget": "checkbox-group",
-      "items": {
-        "type": "string",
-        "enum": ["nfl", "nba", "mlb"]
-      },
-      "x-options": {
-        "labels": {
-          "nfl": "NFL",
-          "nba": "NBA",
-          "mlb": "MLB"
-        }
-      }
-    }
-  }
-}
-```
-
-The widget will be automatically rendered when the plugin configuration form is loaded.
-
-## Labelling Enum Options (`x-options.labels`)
-
-A plain `enum` renders as a dropdown whose option text is the value with
-underscores replaced and title case applied — `day_first` becomes "Day First".
-That is fine for values that read as their own label, and wrong for values that
-do not: `vs` becomes "Vs", and `abbrev` says nothing about the `Sep 19` it
-actually produces.
-
-Supply `x-options.labels` to set the visible text. This is the same convention
-the `checkbox-group` widget uses:
-
-```json
-{
-  "date_format": {
-    "type": "string",
-    "enum": ["abbrev", "numeric", "day_first"],
-    "default": "abbrev",
-    "x-options": {
-      "labels": {
-        "abbrev": "Sep 19",
-        "numeric": "9/19",
-        "day_first": "19 Sep"
-      }
-    }
-  }
-}
-```
-
-Labels are **display only** — the stored value is still the enum value, so
-adding them never changes a saved config. The map may be partial: any value
-without a label keeps the humanised fallback. Older cores that predate this
-support ignore `x-options` and render the fallback for every option, so a
-plugin can ship labels without requiring a core upgrade.
-
-Array-table columns (`x-widget: array-table`) accept the same
-`x-options.labels` on a column definition, but their fallback is the **raw
-value** rather than the humanised one, because those columns hold values such
-as ticker symbols where `aapl` → "Aapl" would be wrong. Rows added in the
-browser use the labels too (`array-table.js`), so a column reads the same
-before and after a page reload.
-
-## Marking Fields as Advanced (`x-advanced`)
-
-Add `"x-advanced": true` to any top-level, non-object property to move it out
-of the main form and into a single collapsed **Advanced Settings** section at
-the bottom of the plugin's configuration page:
-
-```json
-{
-  "properties": {
-    "city": {
-      "type": "string",
-      "title": "City"
-    },
-    "request_timeout": {
-      "type": "integer",
-      "default": 10,
-      "description": "HTTP timeout in seconds",
-      "x-advanced": true
-    }
-  }
-}
-```
-
-Guidelines:
-
-- Use it for fine-tuning knobs most users never touch (timeouts, retry
-  behavior, cache TTLs, styling overrides). Anything a first-time user must
-  set to get the plugin working should stay basic.
-- Nothing is hidden permanently — the section expands on click, and the
-  settings search finds and auto-expands advanced fields like any others.
-- The flag is ignored on `object`-type properties (they already render as
-  their own collapsible sections) and is safely ignored by older cores, so
-  adding it never breaks compatibility.
-
-## Hiding Fields From the Form (`x-display: "hidden"`)
-
-Add `"x-display": "hidden"` to a property that must stay in the schema but
-should not appear as a control: a deprecated key kept so existing configs keep
-validating, or an internal value such as an auto-generated row id.
-
-```json
-{
-  "properties": {
-    "radar_zoom": {
-      "type": "integer",
-      "default": 6,
-      "title": "Radar Zoom Level (deprecated)",
-      "x-display": "hidden"
-    }
-  }
-}
-```
-
-What the core does with it:
-
-- **Not rendered** at any depth: top-level fields, children of an object
-  section, and properties of array-of-object items (never a table column, even
-  if `x-columns` names it, and never in the row editor). A hidden field flagged
-  `x-advanced` is not listed or counted in Advanced Settings, and an object
-  whose children are all hidden draws no empty section. Hidden fields don't
-  show up in the settings search either, since it indexes the rendered form.
-- **Stored value preserved on save.** Saving the form never changes a hidden
-  value. The unchecked-checkbox rule ignores a hidden boolean. Array rows carry
-  a hidden property's stored value through the form, so the value survives the
-  row being posted back; a new row gets no value (the plugin fills it in).
-- **The API is unaffected.** A JSON save to `POST /api/v3/plugins/config` can
-  still set a hidden field.
-
-Older cores ignore the flag and render the field as a normal control.
-
-## Creating Custom Widgets
-
-### Step 1: Create Widget File
-
-Create a JavaScript file in your plugin's `widgets/` directory, named
-`widgets/[widget-name].js`. The directory is not optional: it is the only
-place the core will serve a widget from.
-
-```javascript
-// Ensure LEDMatrixWidgets registry is available
-if (typeof window.LEDMatrixWidgets === 'undefined') {
-    console.error('LEDMatrixWidgets registry not found');
-    return;
-}
-
-// Register your widget
-window.LEDMatrixWidgets.register('my-custom-widget', {
-    name: 'My Custom Widget',
-    version: '1.0.0',
-    
-    /**
-     * Render the widget HTML
-     * @param {HTMLElement} container - Container element to render into
-     * @param {Object} config - Widget configuration from schema
-     * @param {*} value - Current value
-     * @param {Object} options - Additional options (fieldId, pluginId, etc.)
-     */
-    render: function(container, config, value, options) {
-        const fieldId = options.fieldId || container.id;
-        
-        // Always escape HTML to prevent XSS
-        const escapeHtml = (text) => {
-            const div = document.createElement('div');
-            div.textContent = text;
-            return div.innerHTML;
-        };
-        
-        container.innerHTML = `
-            <div class="my-custom-widget">
-                <input type="text" 
-                       id="${fieldId}_input" 
-                       value="${escapeHtml(value || '')}"
-                       class="w-full px-3 py-2 border border-gray-300 rounded">
-            </div>
-        `;
-        
-        // Attach event listeners
-        const input = container.querySelector('input');
-        input.addEventListener('change', (e) => {
-            this.handlers.onChange(fieldId, e.target.value);
-        });
-    },
-    
-    /**
-     * Get current value from widget
-     */
-    getValue: function(fieldId) {
-        const input = document.querySelector(`#${fieldId}_input`);
-        return input ? input.value : null;
-    },
-    
-    /**
-     * Set value programmatically
-     */
-    setValue: function(fieldId, value) {
-        const input = document.querySelector(`#${fieldId}_input`);
-        if (input) {
-            input.value = value || '';
-        }
-    },
-    
-    /**
-     * Event handlers
-     */
-    handlers: {
-        onChange: function(fieldId, value) {
-            // Trigger form change event
-            const event = new CustomEvent('widget-change', {
-                detail: { fieldId, value },
-                bubbles: true
-            });
-            document.dispatchEvent(event);
-        }
-    }
-});
-```
-
-### Step 2: Declare the Widget in `manifest.json`
-
-The manifest is the allowlist. A widget is served only if the plugin declares
-it, so shipping a file under `widgets/` does not by itself publish it:
-
-```json
-{
-  "widgets": [
-    {
-      "name": "my-custom-widget",
-      "script": "my-custom-widget.js",
-      "description": "What this widget is for"
-    }
-  ]
-}
-```
-
-`name` is what you use in `x-widget` and in the URL. `script` is optional and
-defaults to `[name].js`; it must be a plain filename directly inside
-`widgets/` (no paths). Both are validated against
-`schema/manifest_schema.json`.
-
-### Step 3: Reference Widget in Schema
-
-In your plugin's `config_schema.json`:
-
-```json
-{
-  "properties": {
-    "my_field": {
-      "type": "string",
-      "description": "My custom field",
-      "x-widget": "my-custom-widget",
-      "default": ""
-    }
-  }
-}
-```
-
-### Step 4: Widget Loading
-
-The widget is loaded on demand when the plugin's configuration form renders a
-field that references it. The system will:
-
-1. Check whether the widget is already registered in the core registry.
-2. If not, fetch it from `/static/plugin-widgets/[plugin-id]/[widget-name].js`.
-   That route serves the declared `script` from your plugin's `widgets/`
-   directory, as `text/javascript`.
-3. Render it by calling the `render` function your script registered.
-
-The fetch uses a dynamic `import()`, so the file must parse as an ES module.
-A plain IIFE does — modules are strict mode, so avoid sloppy-mode constructs.
-
-**If the widget fails to load** (not declared, file missing, script throws, or
-it never calls `register`), the field falls back to a plain text input holding
-the current value. This is deliberate: a broken widget costs the user an
-editor, not their configured value.
-
-**Limitation:** the on-demand path applies to `string`-typed fields (the
-default branch of the config-form renderer). Fields typed `object`, `array`,
-`boolean`, `integer` or `number`, and fields whose `enum` is set, are
-dispatched by the server-side template to its own built-in renderers, so a
-plugin-supplied `x-widget` on one of those is ignored today.
-
-## Widget API Reference
-
-### Widget Definition Object
-
-```javascript
-{
-    name: string,           // Human-readable widget name
-    version: string,        // Widget version
-    render: function,       // Required: Render function
-    getValue: function,     // Optional: Get current value
-    setValue: function,     // Optional: Set value programmatically
-    handlers: object        // Optional: Event handlers
-}
-```
-
-### Render Function
-
-```javascript
-render(container, config, value, options)
-```
-
-**Parameters:**
-- `container` (HTMLElement): Container element to render into
-- `config` (Object): Widget configuration from schema
-- `value` (*): Current field value
-- `options` (Object): Additional options
-  - `fieldId` (string): Field ID
-  - `pluginId` (string): Plugin ID
-  - `fullKey` (string): Full field key path
-
-### Get Value Function
-
-```javascript
-getValue(fieldId)
-```
-
-**Returns:** Current widget value
-
-### Set Value Function
-
-```javascript
-setValue(fieldId, value)
-```
-
-**Parameters:**
-- `fieldId` (string): Field ID
-- `value` (*): Value to set
-
-## Examples
-
-See [`web_interface/static/v3/js/widgets/example-color-picker.js`](../web_interface/static/v3/js/widgets/example-color-picker.js) for a complete example of a custom color picker widget.
-
-## Best Practices
-
-### Security
-
-1. **Always escape HTML**: Use `escapeHtml()` or `textContent` to prevent XSS
-2. **Validate inputs**: Validate user input before processing
-3. **Sanitize values**: Clean values before storing
-
-### Performance
-
-1. **Lazy loading**: Load widget scripts only when needed
-2. **Event delegation**: Use event delegation for dynamic content
-3. **Debounce**: Debounce frequent events (e.g., input changes)
-
-### Accessibility
-
-1. **Labels**: Always associate labels with inputs
-2. **ARIA attributes**: Use appropriate ARIA attributes
-3. **Keyboard navigation**: Ensure keyboard accessibility
-
-## Troubleshooting
-
-### Widget Not Loading
-
-1. Check browser console for errors
-2. Verify widget file path is correct
-3. Ensure `LEDMatrixWidgets.register()` is called
-4. Check that widget name matches schema `x-widget` value
-
-### Widget Not Rendering
-
-1. Verify `render` function is defined
-2. Check container element exists
-3. Ensure widget is registered before form loads
-4. Check for JavaScript errors in console
-
-### Value Not Saving
-
-1. Ensure widget triggers `widget-change` event
-2. Verify form submission includes widget value
-3. Check `getValue` function returns correct type
-4. Verify field name matches schema property
-
-## Current Implementation Status
-
-**Phase 1 Complete:**
-- ✅ Widget registry system created
-- ✅ Core widgets extracted to separate files
-- ✅ Widget handlers available globally (backwards compatible)
-- ✅ Plugin widget loading system implemented
-
-**Current Behavior:**
-- Core widgets are server-side rendered via Jinja2 templates (existing behavior preserved)
-- Widget handlers are registered and available globally
-- Custom widgets can be created, declared in `manifest.json`, and are served
-  and rendered on demand for `string`-typed fields
-- Plugin widgets on non-string fields are not dispatched yet (see Step 4)
-
-**Backwards Compatibility:**
-- All existing plugins using widgets continue to work without changes
-- Server-side rendering remains the primary method
-- Widget registry provides foundation for future enhancements
-
-## See Also
-
-- [Widget README](../web_interface/static/v3/js/widgets/README.md) - Complete widget development guide with examples
-- [Plugin Development Guide](PLUGIN_DEVELOPMENT_GUIDE.md) - General plugin development
-- [Plugin Configuration Guide](PLUGIN_CONFIGURATION_GUIDE.md) - Configuration setup
+The widget guide lives next to the widgets, in
+[web_interface/static/v3/js/widgets/README.md](../web_interface/static/v3/js/widgets/README.md).
+It lists every built-in `x-widget`, the schema keywords the config form
+understands (`x-options.labels`, `x-advanced`, `x-display: "hidden"`), and how
+to ship a custom widget with a plugin.

first_time_install.sh

@@ -18,7 +18,7 @@ on_error() {
         echo "-- Last 100 lines from log --" >&2
         tail -n 100 "$LOG_FILE" >&2 || true
     fi
-    echo "\nCommon fixes:" >&2
+    printf '\nCommon fixes:\n' >&2
     echo "- Ensure the Pi is online (try: ping -c1 8.8.8.8)." >&2
     echo "- If you saw an APT lock error: wait a minute, close other installers, then run: sudo dpkg --configure -a" >&2
     echo "- Re-run this script. It is safe to run multiple times." >&2
@@ -47,75 +47,137 @@ 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
-        DESKTOP_DETECTED=1
-    fi
-    if systemctl list-units --type=service --state=running 2>/dev/null | grep -qE "lightdm|gdm3|sddm|lxdm"; then
-        DESKTOP_DETECTED=1
+
+    # Check for a desktop. A desktop only competes with the panel for CPU while
+    # it runs, so a running display manager stops the install; desktop packages
+    # or session files on a Pi that boots to the console are only a warning.
+    DESKTOP_RUNNING=0
+    DESKTOP_INSTALLED=0
+    # display-manager is the alias every Debian display manager registers.
+    for dm in display-manager lightdm gdm gdm3 sddm lxdm; do
+        if systemctl is-active --quiet "$dm" 2>/dev/null; then
+            DESKTOP_RUNNING=1
+        fi
+    done
+    # grep without -q: -q exits at the first match, dpkg then dies of SIGPIPE,
+    # and pipefail turns a found desktop into "not found".
+    # Desktop metapackages and session managers, matched as whole installed
+    # package names: an unanchored ".*kde" matched libblockdev-* ("bloc-kde-v"),
+    # and a "gnome" prefix matched standalone parts such as gnome-keyring.
+    # Trixie replaced raspberrypi-ui-mods with the rpd-*-core metapackages.
+    DESKTOP_PACKAGES='raspberrypi-ui-mods|rpd-wayland-core|rpd-x-core'
+    DESKTOP_PACKAGES+='|lxde|lxde-core|lxsession|xfce4|xfce4-session'
+    DESKTOP_PACKAGES+='|gnome-shell|gnome-session|kde-plasma-desktop|plasma-desktop'
+    DESKTOP_PACKAGES+='|plasma-workspace|task-desktop|task-[a-z0-9]+-desktop'
+    if dpkg-query -W -f='${db:Status-Abbrev} ${binary:Package}\n' 2>/dev/null \
+            | grep -E "^ii +(${DESKTOP_PACKAGES})(:[a-z0-9]+)?$" >/dev/null; then
+        DESKTOP_INSTALLED=1
     fi
     if [ -d /usr/share/raspberrypi-ui-mods ] || [ -d /usr/share/xsessions ]; then
-        DESKTOP_DETECTED=1
+        DESKTOP_INSTALLED=1
     fi
-    
-    if [ "$DESKTOP_DETECTED" -eq 1 ]; then
-        echo "✗ ERROR: Desktop environment detected - this script requires Raspberry Pi OS Lite"
-        echo "  Please use Raspberry Pi OS Lite (not the full desktop version)"
+
+    if [ "$DESKTOP_RUNNING" -eq 1 ]; then
+        echo "✗ ERROR: A desktop is running - this script requires Raspberry Pi OS Lite"
+        echo "  Please use Raspberry Pi OS Lite (not the full desktop version), or boot"
+        echo "  to the console: sudo systemctl set-default multi-user.target && sudo reboot"
         OS_CHECK_FAILED=1
+    elif [ "$DESKTOP_INSTALLED" -eq 1 ]; then
+        echo "⚠ WARNING: Desktop packages are installed, but no desktop is running."
+        echo "  Continuing. Keep the Pi booting to the console: a running desktop"
+        echo "  competes with the LED panel for CPU and can make it flicker."
     else
         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 ""
 
-# Get the actual user who invoked sudo (set after we ensure sudo below)
+# The user who ran the installer: SUDO_USER once we are running under sudo
+# (the re-exec below guarantees that), otherwise whoever we are now.
 if [ -n "${SUDO_USER:-}" ]; then
     ACTUAL_USER="$SUDO_USER"
 else
@@ -189,6 +251,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)
@@ -202,7 +309,7 @@ echo ""
 # Check if running as root; if not, try to elevate automatically for novices
 if [ "$EUID" -ne 0 ]; then
     echo "This script needs administrator privileges. Attempting to re-run with sudo..."
-    exec sudo -E env LEDMATRIX_ELEVATED=1 bash "$0" "$@"
+    exec sudo -E bash "$0" "$@"
 fi
 echo "✓ Running as root (required for installation)"
 
@@ -222,6 +329,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
@@ -239,12 +348,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
@@ -264,6 +379,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
@@ -290,10 +406,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() {
@@ -502,6 +620,44 @@ print_rgbmatrix_build_failure() {
     fi
 }
 
+# Set WEB_SERVICE_USER to the account ledmatrix-web.service runs as, or "root"
+# when it cannot tell. Steps 3.1 and 11 choose plugin-directory ownership from
+# it. The logic was pasted three times, identically, and is kept verbatim here.
+# Note: install_web_service.sh and install_service.sh no longer contain the
+# "User=root" / "User=${ACTUAL_USER}" strings grepped for below (the units come
+# from systemd/*.service templates with User=__USER__). So once the unit is
+# installed (Step 7.5, by install_service.sh) the first branch reads its real
+# User=; before that the second branch is taken whenever
+# install_web_service.sh exists, matches neither string, and yields "root" --
+# the later branches are reached only if that script is missing.
+detect_web_service_user() {
+    WEB_SERVICE_USER="root"
+    if [ -f "/etc/systemd/system/ledmatrix-web.service" ]; then
+        # Check actual installed service file (most accurate)
+        WEB_SERVICE_USER=$(grep "^User=" /etc/systemd/system/ledmatrix-web.service | cut -d'=' -f2 || echo "root")
+    elif [ -f "$PROJECT_ROOT_DIR/scripts/install/install_web_service.sh" ]; then
+        # Check install_web_service.sh (used by first_time_install.sh)
+        if grep -q "User=root" "$PROJECT_ROOT_DIR/scripts/install/install_web_service.sh"; then
+            WEB_SERVICE_USER="root"
+        elif grep -q "User=\${ACTUAL_USER}" "$PROJECT_ROOT_DIR/scripts/install/install_web_service.sh"; then
+            WEB_SERVICE_USER="$ACTUAL_USER"
+        fi
+    elif [ -f "$PROJECT_ROOT_DIR/systemd/ledmatrix-web.service" ]; then
+        # Check template file (may have placeholder)
+        WEB_SERVICE_USER=$(grep "^User=" "$PROJECT_ROOT_DIR/systemd/ledmatrix-web.service" | cut -d'=' -f2 || echo "root")
+        # If template has placeholder, check install script
+        if [ "$WEB_SERVICE_USER" = "__USER__" ] || [ -z "$WEB_SERVICE_USER" ]; then
+            # Check install_service.sh to see what user it uses
+            if [ -f "$PROJECT_ROOT_DIR/scripts/install/install_service.sh" ] && grep -q "User=\${ACTUAL_USER}" "$PROJECT_ROOT_DIR/scripts/install/install_service.sh"; then
+                WEB_SERVICE_USER="$ACTUAL_USER"
+            fi
+        fi
+    elif [ -f "$PROJECT_ROOT_DIR/scripts/install/install_service.sh" ] && grep -q "User=\${ACTUAL_USER}" "$PROJECT_ROOT_DIR/scripts/install/install_service.sh"; then
+        # Web service will be installed by install_service.sh as ACTUAL_USER
+        WEB_SERVICE_USER="$ACTUAL_USER"
+    fi
+}
+
 echo ""
 echo "This script will perform the following steps:"
 echo "1. Check prerequisites (network, disk, memory) and install system dependencies"
@@ -634,8 +790,9 @@ else
     echo "Setting ownership of assets directory..."
     chown -R "$ACTUAL_USER:$ACTUAL_USER" "$PROJECT_ROOT_DIR/assets"
     
-    # Set permissions to allow read/write for owner, group, and others (for root service user)
-    # Note: 777 allows root (service user) to write, which is necessary when service runs as root
+    # 777: read/write for owner, group and every other account. Root (the
+    # display service) does not need it -- root ignores mode bits -- so the
+    # "other" bits only matter to accounts that are neither the owner nor root.
     echo "Setting permissions for assets directory..."
     chmod -R 777 "$PROJECT_ROOT_DIR/assets"
     
@@ -699,32 +856,7 @@ else
     fi
     
     # Determine ownership based on web service user
-    # Check if web service file exists and what user it runs as
-    WEB_SERVICE_USER="root"
-    if [ -f "/etc/systemd/system/ledmatrix-web.service" ]; then
-        # Check actual installed service file (most accurate)
-        WEB_SERVICE_USER=$(grep "^User=" /etc/systemd/system/ledmatrix-web.service | cut -d'=' -f2 || echo "root")
-    elif [ -f "$PROJECT_ROOT_DIR/scripts/install/install_web_service.sh" ]; then
-        # Check install_web_service.sh (used by first_time_install.sh)
-        if grep -q "User=root" "$PROJECT_ROOT_DIR/scripts/install/install_web_service.sh"; then
-            WEB_SERVICE_USER="root"
-        elif grep -q "User=\${ACTUAL_USER}" "$PROJECT_ROOT_DIR/scripts/install/install_web_service.sh"; then
-            WEB_SERVICE_USER="$ACTUAL_USER"
-        fi
-    elif [ -f "$PROJECT_ROOT_DIR/systemd/ledmatrix-web.service" ]; then
-        # Check template file (may have placeholder)
-        WEB_SERVICE_USER=$(grep "^User=" "$PROJECT_ROOT_DIR/systemd/ledmatrix-web.service" | cut -d'=' -f2 || echo "root")
-        # If template has placeholder, check install script
-        if [ "$WEB_SERVICE_USER" = "__USER__" ] || [ -z "$WEB_SERVICE_USER" ]; then
-            # Check install_service.sh to see what user it uses
-            if [ -f "$PROJECT_ROOT_DIR/scripts/install/install_service.sh" ] && grep -q "User=\${ACTUAL_USER}" "$PROJECT_ROOT_DIR/scripts/install/install_service.sh"; then
-                WEB_SERVICE_USER="$ACTUAL_USER"
-            fi
-        fi
-    elif [ -f "$PROJECT_ROOT_DIR/scripts/install/install_service.sh" ] && grep -q "User=\${ACTUAL_USER}" "$PROJECT_ROOT_DIR/scripts/install/install_service.sh"; then
-        # Web service will be installed by install_service.sh as ACTUAL_USER
-        WEB_SERVICE_USER="$ACTUAL_USER"
-    fi
+    detect_web_service_user
     
     # If web service runs as ACTUAL_USER (not root), set ownership to ACTUAL_USER
     # so the web service can change permissions. Root service can still access via group (775).
@@ -758,32 +890,7 @@ if [ ! -d "$PLUGIN_REPOS_DIR" ]; then
 fi
 
 # Determine ownership based on web service user
-# Check if web service file exists and what user it runs as
-WEB_SERVICE_USER="root"
-if [ -f "/etc/systemd/system/ledmatrix-web.service" ]; then
-    # Check actual installed service file (most accurate)
-    WEB_SERVICE_USER=$(grep "^User=" /etc/systemd/system/ledmatrix-web.service | cut -d'=' -f2 || echo "root")
-elif [ -f "$PROJECT_ROOT_DIR/scripts/install/install_web_service.sh" ]; then
-    # Check install_web_service.sh (used by first_time_install.sh)
-    if grep -q "User=root" "$PROJECT_ROOT_DIR/scripts/install/install_web_service.sh"; then
-        WEB_SERVICE_USER="root"
-    elif grep -q "User=\${ACTUAL_USER}" "$PROJECT_ROOT_DIR/scripts/install/install_web_service.sh"; then
-        WEB_SERVICE_USER="$ACTUAL_USER"
-    fi
-elif [ -f "$PROJECT_ROOT_DIR/systemd/ledmatrix-web.service" ]; then
-    # Check template file (may have placeholder)
-    WEB_SERVICE_USER=$(grep "^User=" "$PROJECT_ROOT_DIR/systemd/ledmatrix-web.service" | cut -d'=' -f2 || echo "root")
-    # If template has placeholder, check install script
-    if [ "$WEB_SERVICE_USER" = "__USER__" ] || [ -z "$WEB_SERVICE_USER" ]; then
-        # Check install_service.sh to see what user it uses
-        if [ -f "$PROJECT_ROOT_DIR/scripts/install/install_service.sh" ] && grep -q "User=\${ACTUAL_USER}" "$PROJECT_ROOT_DIR/scripts/install/install_service.sh"; then
-            WEB_SERVICE_USER="$ACTUAL_USER"
-        fi
-    fi
-elif [ -f "$PROJECT_ROOT_DIR/scripts/install/install_service.sh" ] && grep -q "User=\${ACTUAL_USER}" "$PROJECT_ROOT_DIR/scripts/install/install_service.sh"; then
-    # Web service will be installed by install_service.sh as ACTUAL_USER
-    WEB_SERVICE_USER="$ACTUAL_USER"
-fi
+detect_web_service_user
 
 # If web service runs as ACTUAL_USER (not root), set ownership to ACTUAL_USER
 # so the web service can change permissions. Root service can still access via group (775).
@@ -797,8 +904,8 @@ else
     chown -R root:"$ACTUAL_USER" "$PLUGIN_REPOS_DIR"
 fi
 
-# Set directory permissions (775: rwxrwxr-x)
-echo "Setting plugin-repos directory permissions to 2775 (sticky bit)..."
+# Set directory permissions (2775: rwxrwsr-x, setgid so new entries inherit the group)
+echo "Setting plugin-repos directory permissions to 2775 (setgid)..."
 find "$PLUGIN_REPOS_DIR" -type d -exec chmod 2775 {} \;
 
 # Set file permissions (664: rw-rw-r--)
@@ -845,6 +952,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": {
@@ -879,15 +990,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)
@@ -908,9 +1029,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
 
@@ -1005,9 +1128,9 @@ if [ -f "$PROJECT_ROOT_DIR/requirements.txt" ]; then
         PACKAGE_NUM=$((PACKAGE_NUM + 1))
         echo "[$PACKAGE_NUM/$TOTAL_PACKAGES] Installing: $line"
         
-        # Check if package is already installed (basic check - may not catch all cases)
-        # Try installing with verbose output and timeout (if available)
-        # Use --no-cache-dir to avoid cache issues, --verbose for diagnostics
+        # Install with a timeout where available. --verbose output goes to
+        # $INSTALL_OUTPUT (filtered below, full copy in the log); --no-cache-dir
+        # avoids pip cache issues.
         INSTALL_OUTPUT=$(mktemp)
         INSTALL_SUCCESS=false
         
@@ -1232,9 +1355,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"
@@ -1312,7 +1437,11 @@ else
             WEB_DEPS_OK=false
         fi
     else
-        echo "Web dependencies already installed from web_interface/requirements.txt in Step 5"
+        # No marker means Step 5 did not install web_interface/requirements.txt,
+        # and without the smart installer there is nothing else to try here.
+        echo "⚠ scripts/install_dependencies_apt.py not found, and Step 5 did not install"
+        echo "  web_interface/requirements.txt, so web interface dependencies may be missing."
+        WEB_DEPS_OK=false
     fi
 
     # Create the marker only when installation actually succeeded, so a
@@ -1351,15 +1480,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
@@ -1516,51 +1646,31 @@ POWEROFF_PATH=$(which poweroff)
 BASH_PATH=$(which bash)
 JOURNALCTL_PATH=$(which journalctl 2>/dev/null || true)
 
-# Create sudoers content
-cat > "$SUDOERS_TMP" << EOF
-# LED Matrix Web Interface passwordless sudo configuration
-# This allows the web interface user to run specific commands without a password
-
-# Allow $ACTUAL_USER to run specific commands without a password for the LED Matrix web interface
-$ACTUAL_USER ALL=(ALL) NOPASSWD: $REBOOT_PATH
-$ACTUAL_USER ALL=(ALL) NOPASSWD: $POWEROFF_PATH
-$ACTUAL_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH start ledmatrix.service
-$ACTUAL_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH stop ledmatrix.service
-$ACTUAL_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH restart ledmatrix.service
-$ACTUAL_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH enable ledmatrix.service
-$ACTUAL_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH disable ledmatrix.service
-$ACTUAL_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH status ledmatrix.service
-$ACTUAL_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH is-active ledmatrix
-$ACTUAL_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH is-active ledmatrix.service
-$ACTUAL_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH start ledmatrix-web.service
-$ACTUAL_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH stop ledmatrix-web.service
-$ACTUAL_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH restart ledmatrix-web.service
-$ACTUAL_USER ALL=(ALL) NOPASSWD: $BASH_PATH $PROJECT_ROOT_DIR/scripts/fix_perms/safe_plugin_rm.sh *
-# 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).
-$ACTUAL_USER ALL=(ALL) NOPASSWD: $BASH_PATH $PROJECT_ROOT_DIR/scripts/fix_perms/safe_pip_install.sh *
-EOF
-if [ -n "$JOURNALCTL_PATH" ]; then
-    cat >> "$SUDOERS_TMP" << EOF
-# NOEXEC, because these rules end in a wildcard and journalctl starts a pager
-# when its output is a terminal. From that pager (less) a "!sh" is a root
-# shell -- the standard journalctl escalation. The web interface always passes
-# --no-pager, so nothing here needs it, but the rule cannot require a flag that
-# sits in the middle of the command line. NOEXEC stops the command executing
-# another program at all, which closes the hole without depending on wildcard
-# matching subtleties.
-$ACTUAL_USER ALL=(ALL) NOPASSWD:NOEXEC: $JOURNALCTL_PATH -u ledmatrix.service *
-$ACTUAL_USER ALL=(ALL) NOPASSWD:NOEXEC: $JOURNALCTL_PATH -u ledmatrix *
-$ACTUAL_USER ALL=(ALL) NOPASSWD:NOEXEC: $JOURNALCTL_PATH -t ledmatrix *
-EOF
+# The rules themselves live in scripts/install/lib_sudoers.sh, shared with
+# scripts/install/configure_web_sudo.sh so the two cannot drift apart again.
+# If it is missing (a damaged checkout), keep whatever is already installed
+# rather than failing the whole install; the gate below skips the install.
+SUDOERS_VALID=1
+SUDOERS_LIB="$PROJECT_ROOT_DIR/scripts/install/lib_sudoers.sh"
+if [ -f "$SUDOERS_LIB" ]; then
+    # shellcheck source=scripts/install/lib_sudoers.sh
+    . "$SUDOERS_LIB"
+    web_sudoers_rules "$ACTUAL_USER" "$PROJECT_ROOT_DIR" "$SYSTEMCTL_PATH" "$BASH_PATH" \
+        "$REBOOT_PATH" "$POWEROFF_PATH" "$JOURNALCTL_PATH" > "$SUDOERS_TMP"
+else
+    SUDOERS_VALID=0
+    echo "⚠ $SUDOERS_LIB not found; cannot generate the sudoers rules." >&2
+    echo "⚠ Leaving $SUDOERS_FILE unchanged. The web interface cannot control" >&2
+    echo "  the display service until this is fixed." >&2
 fi
 
 # Never install rules we have not parsed. A malformed drop-in in
 # /etc/sudoers.d makes sudo refuse every command for every user, which on a
 # headless Pi leaves no way in at all. If the rules do not parse, say so and
 # keep whatever is already installed.
-SUDOERS_VALID=1
-if command -v visudo >/dev/null 2>&1; then
+if [ "$SUDOERS_VALID" = "0" ]; then
+    :  # nothing was generated; already reported above
+elif command -v visudo >/dev/null 2>&1; then
     if ! visudo -c -f "$SUDOERS_TMP" >/dev/null 2>&1; then
         SUDOERS_VALID=0
         echo "⚠ The generated sudoers rules did not parse:" >&2
@@ -1597,11 +1707,12 @@ echo "-----------------------------------------------------"
 if [ -f "$PROJECT_ROOT_DIR/scripts/install/configure_wifi_permissions.sh" ]; then
     echo "Configuring WiFi management permissions..."
     # Run as the actual user (not root) since the script checks for that
-    sudo -u "$ACTUAL_USER" bash "$PROJECT_ROOT_DIR/scripts/install/configure_wifi_permissions.sh" || {
+    if sudo -u "$ACTUAL_USER" bash "$PROJECT_ROOT_DIR/scripts/install/configure_wifi_permissions.sh"; then
+        echo "✓ WiFi management permissions configured"
+    else
         echo "⚠ WiFi permissions configuration failed, but continuing installation"
         echo "  You can run it manually later: ./scripts/install/configure_wifi_permissions.sh"
-    }
-    echo "✓ WiFi management permissions configured"
+    fi
 else
     echo "⚠ configure_wifi_permissions.sh not found; skipping WiFi permissions configuration"
     echo "  You can configure WiFi permissions later by running:"
@@ -1690,28 +1801,8 @@ fi
 
 # Re-apply plugin directory permissions based on web service user
 echo "Re-applying plugin directory permissions..."
-# Determine web service user (check installed service, install scripts, or template)
-WEB_SERVICE_USER="root"
-if [ -f "/etc/systemd/system/ledmatrix-web.service" ]; then
-    # Check actual installed service file (most accurate)
-    WEB_SERVICE_USER=$(grep "^User=" /etc/systemd/system/ledmatrix-web.service | cut -d'=' -f2 || echo "root")
-elif [ -f "$PROJECT_ROOT_DIR/scripts/install/install_web_service.sh" ]; then
-    # Check install_web_service.sh (used by first_time_install.sh)
-    if grep -q "User=root" "$PROJECT_ROOT_DIR/scripts/install/install_web_service.sh"; then
-        WEB_SERVICE_USER="root"
-    elif grep -q "User=\${ACTUAL_USER}" "$PROJECT_ROOT_DIR/scripts/install/install_web_service.sh"; then
-        WEB_SERVICE_USER="$ACTUAL_USER"
-    fi
-elif [ -f "$PROJECT_ROOT_DIR/systemd/ledmatrix-web.service" ]; then
-    WEB_SERVICE_USER=$(grep "^User=" "$PROJECT_ROOT_DIR/systemd/ledmatrix-web.service" | cut -d'=' -f2 || echo "root")
-    if [ "$WEB_SERVICE_USER" = "__USER__" ] || [ -z "$WEB_SERVICE_USER" ]; then
-        if [ -f "$PROJECT_ROOT_DIR/scripts/install/install_service.sh" ] && grep -q "User=\${ACTUAL_USER}" "$PROJECT_ROOT_DIR/scripts/install/install_service.sh"; then
-            WEB_SERVICE_USER="$ACTUAL_USER"
-        fi
-    fi
-elif [ -f "$PROJECT_ROOT_DIR/scripts/install/install_service.sh" ] && grep -q "User=\${ACTUAL_USER}" "$PROJECT_ROOT_DIR/scripts/install/install_service.sh"; then
-    WEB_SERVICE_USER="$ACTUAL_USER"
-fi
+# Determine ownership based on web service user
+detect_web_service_user
 
 # Set ownership based on web service user
 if [ "$WEB_SERVICE_USER" = "$ACTUAL_USER" ] || [ "$WEB_SERVICE_USER" != "root" ]; then
@@ -1791,10 +1882,11 @@ echo "-------------------------------------"
 echo "Removing potential conflicting services (bluetooth and others)..."
 if [ "$SKIP_SOUND" = "1" ]; then
     echo "Skipping sound module configuration as requested (--skip-sound)."
-elif apt_remove bluez bluez-firmware pi-bluetooth triggerhappy pigpio; then
-    echo "✓ Unnecessary services removed (or not present)"
 else
-    echo "⚠ Some packages could not be removed; continuing"
+    # apt_remove never fails (it ends in `|| true`); apt itself reports any
+    # package it could not remove.
+    apt_remove bluez bluez-firmware pi-bluetooth triggerhappy pigpio
+    echo "✓ Unnecessary services removed (or not present)"
 fi
 
 # Blacklist onboard sound module (idempotent)
@@ -2009,20 +2101,6 @@ if systemctl list-unit-files | grep -q "ledmatrix-wifi-monitor.service"; then
 fi
 
 echo ""
-if [ "$SKIP_REBOOT_PROMPT" = "1" ]; then
-    echo "Skipping reboot prompt as requested (--no-reboot-prompt)."
-elif [ "$ASSUME_YES" = "1" ]; then
-    echo "Non-interactive mode: rebooting now to apply changes..."
-    reboot
-else
-    read -p "A reboot is recommended to apply kernel and audio changes. Reboot now? (y/N): " -n 1 -r
-    echo
-    if [[ $REPLY =~ ^[Yy]$ ]]; then
-        echo "Rebooting now..."
-        reboot
-    fi
-fi
-
 echo "=========================================="
 echo "Installation Complete!"
 echo "=========================================="
@@ -2068,7 +2146,7 @@ if command -v nmcli >/dev/null 2>&1; then
     if [ -n "$WIFI_STATUS" ]; then
         echo "$WIFI_STATUS" | while IFS=':' read -r _ _ state; do
             if [ "$state" = "connected" ]; then
-                SSID=$(nmcli -t -f active,ssid device wifi 2>/dev/null | grep "^yes:" | cut -d: -f2 | head -1)
+                SSID=$(nmcli -t -f active,ssid device wifi 2>/dev/null | grep "^yes:" | cut -d: -f2 | head -1 || true)
                 if [ -n "$SSID" ]; then
                     echo "  ✓ Connected to: $SSID"
                 else
@@ -2092,7 +2170,7 @@ echo "AP Mode Status:"
 if systemctl is-active --quiet hostapd 2>/dev/null; then
     echo "  ✓ AP Mode is ACTIVE"
     echo "  → Connect to WiFi network: LEDMatrix-Setup"
-    echo "  → Password: ledmatrix123"
+    echo "  → Open network, no password"
     echo "  → Access web UI at: http://192.168.4.1:5000"
     AP_MODE_ACTIVE=true
 else
@@ -2100,7 +2178,7 @@ else
     if ip addr show wlan0 2>/dev/null | grep -q "192.168.4.1"; then
         echo "  ✓ AP Mode is ACTIVE (IP detected)"
         echo "  → Connect to WiFi network: LEDMatrix-Setup"
-        echo "  → Password: ledmatrix123"
+        echo "  → Open network, no password"
         echo "  → Access web UI at: http://192.168.4.1:5000"
         AP_MODE_ACTIVE=true
     else
@@ -2202,3 +2280,22 @@ echo "   - Main config: $PROJECT_ROOT_DIR/config/config.json"
 echo "   - Secrets: $PROJECT_ROOT_DIR/config/config_secrets.json"
 echo ""
 echo "Enjoy your LED Matrix display!"
+
+# Reboot last. It used to come before the summary above, so with -y (and
+# the one-shot installer, which always passes -y) the reboot was already
+# under way while the summary printed, and the SSH session usually dropped
+# before any of it -- the web UI address included -- could be read.
+echo ""
+if [ "$SKIP_REBOOT_PROMPT" = "1" ]; then
+    echo "Skipping reboot prompt as requested (--no-reboot-prompt)."
+elif [ "$ASSUME_YES" = "1" ]; then
+    echo "Non-interactive mode: rebooting now to apply changes..."
+    reboot
+else
+    read -p "A reboot is recommended to apply kernel and audio changes. Reboot now? (y/N): " -n 1 -r
+    echo
+    if [[ $REPLY =~ ^[Yy]$ ]]; then
+        echo "Rebooting now..."
+        reboot
+    fi
+fi

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

@@ -0,0 +1,107 @@
+# The mypy ratchet: modules that type-check clean, one path per line, sorted.
+#
+# CI ("Type check (mypy ratchet)") runs `python scripts/check_types.py`, which
+# runs mypy on exactly these files (imports followed silently, so errors in an
+# unlisted module they import don't count) and fails on any error, so a listed
+# module stays clean. Most of src/ isn't clean yet. When you make a module
+# clean, add it here. Don't take a module off to get CI green -- fix the error
+# (annotation-only where you can: hints, typing.cast, TYPE_CHECKING imports;
+# widen an annotation rather than delete a defensive runtime check).
+
+src/__init__.py
+src/adaptive_images.py
+src/auto_update_setup.py
+src/backup_manager.py
+src/base_odds_manager.py
+src/cache/__init__.py
+src/cache/cache_strategy.py
+src/cache/memory_cache.py
+src/common/__init__.py
+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
+src/common/logo_helper.py
+src/common/path_safety.py
+src/common/permission_utils.py
+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_favorites.py
+src/common/sports_fetch.py
+src/common/sports_font_path.py
+src/common/sports_game_over.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/malloc_tuning.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
+src/plugin_system/saved_repositories.py
+src/plugin_system/schema_manager.py
+src/plugin_system/state_reconciliation.py
+src/plugin_system/testing/__init__.py
+src/plugin_system/testing/bounds_display_manager.py
+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/screen_runner.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
+src/web_interface/error_handler.py
+src/web_interface/errors.py
+src/web_interface/secret_helpers.py
+src/web_interface/validators.py

mypy.ini

@@ -1,8 +1,14 @@
 [mypy]
 # Mypy configuration for LEDMatrix
 
-# Python version
-python_version = 3.10
+# What a bare `mypy` checks. ini values can't span lines or carry trailing
+# comments -- this file used to have both, so mypy refused to read it at all.
+files = src
+exclude = (^|/)(test|__pycache__)/
+
+# 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
@@ -25,11 +31,11 @@ warn_unreachable = True
 # Strict optional checking
 strict_optional = True
 
-# Disallow untyped definitions
-disallow_untyped_defs = False  # Set to True once all code is typed
+# Disallow untyped definitions (set to True once all code is typed)
+disallow_untyped_defs = False
 
-# Disallow untyped calls
-disallow_untyped_calls = False  # Set to True once all code is typed
+# Disallow untyped calls (set to True once all code is typed)
+disallow_untyped_calls = False
 
 # Check untyped definitions
 check_untyped_defs = True
@@ -96,10 +102,20 @@ ignore_missing_imports = True
 [mypy-spotipy.*]
 ignore_missing_imports = True
 
-# Exclude test files and generated files
-exclude = (?x)(
-    ^test/.*|
-    ^.*/__pycache__/.*|
-    ^.*\.pyc$
-)
 
+# numpy's own stubs (numpy>=2.3) use Python 3.12 `type` statements, which mypy
+# 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
+follow_imports_for_stubs = True
+
+# orjson is optional (see requirements.txt): the modules that use it fall back
+# to the stdlib when `import orjson` fails. Whether mypy sees its stubs would
+# otherwise depend on whether it happens to be installed -- installed, the
+# `orjson = None` fallback is a type error and the stdlib branch "unreachable";
+# not installed, silencing either is an unused ignore. Treat it as Any always.
+[mypy-orjson.*]
+follow_imports = skip
+follow_imports_for_stubs = True

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-test.txt

@@ -1,10 +1,9 @@
 # Test/dev-only dependencies (not needed on a running display).
 # Install alongside requirements.txt:  pip install -r requirements.txt -r requirements-test.txt
 pytest>=9.0.3,<10.0.0
-pytest-cov>=4.1.0,<5.0.0
-pytest-mock>=3.11.0,<4.0.0
+pytest-cov>=4.1.0,<8.0.0
 freezegun>=1.2,<2        # deterministic time for golden-image tests
-psutil>=6.0.0,<8.0.0     # optional at runtime; installed for tests so the
+psutil>=6.0.0,<7.0.0     # optional at runtime; installed for tests so the
                          # /system/status endpoint's real path is exercised
 mypy>=1.5.0,<2.0.0       # static type checking (also pinned in .pre-commit-config.yaml)
 PyYAML>=6.0.2,<7.0.0     # not a core dependency: test_starlark_pixlet_routes loads

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
@@ -7,7 +7,7 @@ Pillow>=12.2.0,<13.0.0
 numpy>=1.24.0  # For fast array operations in ScrollHelper (compatible with 2.x)
 
 # Timezone handling
-pytz>=2024.2,<2025.0  # Updated for latest timezone data
+pytz>=2024.2,<2027.0  # Updated for latest timezone data
 
 # HTTP requests
 requests>=2.33.0,<3.0.0

run.py

@@ -14,6 +14,20 @@ project_dir = os.path.dirname(os.path.abspath(__file__))
 if project_dir not in sys.path:
     sys.path.insert(0, project_dir)
 
+# Cap glibc's malloc arenas before any thread exists (arenas already made
+# stay): the in-process twin of the unit's MALLOC_ARENA_MAX=2, for units
+# installed before that line. A no-op off glibc. See src/malloc_tuning.py.
+from src import malloc_tuning
+malloc_tuning.cap_arenas()
+
+# 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',
@@ -31,8 +45,6 @@ if args.emulator:
     print("Using pygame/RGBMatrixEmulator for display")
     print("Press ESC to exit\n")
 
-# Project directory already added above
-
 # Debug output (only in debug mode or emulator mode)
 debug_mode = args.debug or args.emulator or os.environ.get('LEDMATRIX_DEBUG', '').lower() == 'true'
 if debug_mode:

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

@@ -0,0 +1,60 @@
+# Scripts
+
+Helper scripts for installing, repairing, diagnosing and developing
+LEDMatrix. Most users only ever run the one-shot installer (see the project
+README); everything else here is for troubleshooting or development.
+
+Status key: **keep** — part of install/runtime or referenced by docs, CI,
+tests or code; **dev-only** — for plugin/core development, not needed on a
+display; **diagnostic** — run by hand on a Pi when something is wrong.
+
+## Directories
+
+| Directory | Status | What it holds |
+|---|---|---|
+| [`install/`](install/README.md) | keep | The installers: one-shot, services, sudoers/WiFi permissions, cache setup, and the shared `lib_*.sh` helpers `first_time_install.sh` sources |
+| [`fix_perms/`](fix_perms/README.md) | keep | Permission repair scripts, plus the two root helpers the web interface runs through sudo (`safe_plugin_rm.sh`, `safe_pip_install.sh`) |
+| [`utils/`](utils/README.md) | keep | Scripts run by systemd units or the web interface (conditional web start, WiFi monitor, update verify, DNS fix, Pixlet config editor, cache clearing) |
+| [`dev/`](dev/README.md) | dev-only | Plugin linking, Vegas density audit, Pillow smoke test |
+| `templates/` | dev-only | `dev_preview.html`, the page `dev_server.py` serves |
+
+## Top-level scripts
+
+| Script | Status | What it does |
+|---|---|---|
+| `build_rgbmatrix_nogil.sh` | keep | Rebuilds the rgbmatrix Python binding so `SwapOnVSync` releases the GIL (docs/SCROLL_PERFORMANCE.md) |
+| `check_plugin.py` | dev-only | Renders a plugin across every mode and matrix size and fails on crashes, overflow or golden-image drift |
+| `check_release_version.py` | keep | Checks a release tag, CHANGELOG and `src.__version__` agree (release-version-check workflow) |
+| `check_system_compatibility.sh` | diagnostic | Pre-install check of hardware, OS (Trixie only), kernel, Python, packages, disk and network |
+| `dev_server.py` | dev-only | Browser preview server for plugins without the display loop (http://localhost:5001) |
+| `diagnose_dependencies.sh` | diagnostic | Investigates pip installs stuck on "Preparing metadata" |
+| `diagnose_web_interface.sh` | diagnostic | Checks why the web interface is not reachable |
+| `download_pixlet.sh` | keep | Downloads the bundled Pixlet binaries for Starlark apps (also run from the web UI) |
+| `emergency_reconnect.sh` | diagnostic | Reconnects to your WiFi network if captive-portal testing leaves the Pi offline |
+| `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 |
+| `verify_installation.sh` | diagnostic | Checks that an installation completed correctly |
+| `verify_wifi_setup.sh` | diagnostic | Health check of the WiFi management setup |
+
+## Hand-run tools nothing else references
+
+Nothing in the repo (docs, CI, tests, other scripts or code) refers to these.
+They are run by hand and were kept by owner decision (October 2026); the
+old one-off schema fixers and WiFi test scripts listed here were removed.
+
+| Script | What it does |
+|---|---|
+| `audit_plugins.py` | AST security audit of plugin code; says it is "designed to run in CI" but no workflow runs it |
+| `audit_render_path.py` | Finds blocking calls reachable from a plugin's `display()` |
+| `sports_scroll_check.py` | Drives a sports scoreboard scroll on the panel and reports its pacing |
+| `dev/test_pillow_compat.py` | Pillow API smoke test to run after upgrading Pillow |

scripts/add_defaults_to_schemas.py

@@ -1,231 +0,0 @@
-#!/usr/bin/env python3
-"""
-Script to add default values to plugin config schemas where missing.
-
-This ensures that configs never start with None values, improving user experience
-and preventing validation errors.
-"""
-
-import json
-import sys
-from pathlib import Path
-from typing import Any, Dict, List
-
-
-def get_default_for_field(prop: Dict[str, Any]) -> Any:
-    """
-    Determine a sensible default value for a field based on its type and constraints.
-    
-    Args:
-        prop: Field property schema
-        
-    Returns:
-        Default value or None if no default should be added
-    """
-    prop_type = prop.get('type')
-    
-    # Handle union types (array with multiple types)
-    if isinstance(prop_type, list):
-        # Use the first non-null type
-        prop_type = next((t for t in prop_type if t != 'null'), prop_type[0] if prop_type else 'string')
-    
-    if prop_type == 'boolean':
-        return False
-    
-    elif prop_type == 'number':
-        # For numbers, use minimum if available, or a sensible default
-        minimum = prop.get('minimum')
-        maximum = prop.get('maximum')
-        
-        if minimum is not None:
-            return minimum
-        elif maximum is not None:
-            # Use a reasonable fraction of max (like 30% or minimum 1)
-            return max(1, int(maximum * 0.3))
-        else:
-            # No constraints, use 0
-            return 0
-    
-    elif prop_type == 'integer':
-        # Similar to number
-        minimum = prop.get('minimum')
-        maximum = prop.get('maximum')
-        
-        if minimum is not None:
-            return minimum
-        elif maximum is not None:
-            return max(1, int(maximum * 0.3))
-        else:
-            return 0
-    
-    elif prop_type == 'string':
-        # Only add default for strings if it makes sense
-        # Check if there's an enum - use first value
-        enum_values = prop.get('enum')
-        if enum_values:
-            return enum_values[0]
-        
-        # For optional string fields, empty string might be okay, but be cautious
-        # We'll skip adding defaults for strings unless explicitly needed
-        return None
-    
-    elif prop_type == 'array':
-        # Empty array as default
-        return []
-    
-    elif prop_type == 'object':
-        # Empty object - but we'll handle nested objects separately
-        return {}
-    
-    return None
-
-
-def should_add_default(prop: Dict[str, Any], field_path: str) -> bool:
-    """
-    Determine if we should add a default value to this field.
-    
-    Args:
-        prop: Field property schema
-        field_path: Dot-separated path to the field
-        
-    Returns:
-        True if default should be added
-    """
-    # Skip if already has a default
-    if 'default' in prop:
-        return False
-    
-    # Skip secret fields (they should be user-provided)
-    if prop.get('x-secret', False):
-        return False
-    
-    # Skip API keys and similar sensitive fields
-    field_name = field_path.split('.')[-1].lower()
-    sensitive_keywords = ['key', 'password', 'secret', 'token', 'auth', 'credential']
-    if any(keyword in field_name for keyword in sensitive_keywords):
-        return False
-    
-    prop_type = prop.get('type')
-    if isinstance(prop_type, list):
-        prop_type = next((t for t in prop_type if t != 'null'), prop_type[0] if prop_type else None)
-    
-    # Only add defaults for certain types
-    if prop_type in ('boolean', 'number', 'integer', 'array'):
-        return True
-    
-    # For strings, only if there's an enum
-    if prop_type == 'string' and 'enum' in prop:
-        return True
-    
-    return False
-
-
-def add_defaults_recursive(schema: Dict[str, Any], path: str = "", modified: List[str] = None) -> bool:
-    """
-    Recursively add default values to schema fields.
-    
-    Args:
-        schema: Schema dictionary to modify
-        path: Current path in the schema (for logging)
-        modified: List to track which fields were modified
-        
-    Returns:
-        True if any modifications were made
-    """
-    if modified is None:
-        modified = []
-    
-    if not isinstance(schema, dict) or 'properties' not in schema:
-        return False
-    
-    changes_made = False
-    
-    for key, prop in schema['properties'].items():
-        if not isinstance(prop, dict):
-            continue
-        
-        current_path = f"{path}.{key}" if path else key
-        
-        # Check nested objects
-        if prop.get('type') == 'object' and 'properties' in prop:
-            if add_defaults_recursive(prop, current_path, modified):
-                changes_made = True
-        
-        # Add default if appropriate
-        if should_add_default(prop, current_path):
-            default_value = get_default_for_field(prop)
-            if default_value is not None:
-                prop['default'] = default_value
-                modified.append(current_path)
-                changes_made = True
-                print(f"  Added default to {current_path}: {default_value} (type: {prop.get('type')})")
-    
-    return changes_made
-
-
-def process_schema_file(schema_path: Path) -> bool:
-    """
-    Process a single schema file to add defaults.
-    
-    Args:
-        schema_path: Path to the schema file
-        
-    Returns:
-        True if file was modified
-    """
-    print(f"\nProcessing: {schema_path}")
-    
-    try:
-        with open(schema_path, 'r', encoding='utf-8') as f:
-            schema = json.load(f)
-    except Exception as e:
-        print(f"  Error reading schema: {e}")
-        return False
-    
-    modified_fields = []
-    changes_made = add_defaults_recursive(schema, modified=modified_fields)
-    
-    if changes_made:
-        # Write back with pretty formatting
-        with open(schema_path, 'w', encoding='utf-8') as f:
-            json.dump(schema, f, indent=2, ensure_ascii=False)
-            f.write('\n')  # Add trailing newline
-        
-        print(f"  ✓ Modified {len(modified_fields)} fields")
-        return True
-    else:
-        print(f"  ✓ No changes needed")
-        return False
-
-
-def main():
-    """Main entry point."""
-    project_root = Path(__file__).parent.parent
-    plugins_dir = project_root / 'plugin-repos'
-    
-    if not plugins_dir.exists():
-        print(f"Error: Plugins directory not found: {plugins_dir}")
-        sys.exit(1)
-    
-    # Find all config_schema.json files
-    schema_files = list(plugins_dir.rglob('config_schema.json'))
-    
-    if not schema_files:
-        print("No config_schema.json files found")
-        sys.exit(0)
-    
-    print(f"Found {len(schema_files)} schema files")
-    
-    modified_count = 0
-    for schema_file in sorted(schema_files):
-        if process_schema_file(schema_file):
-            modified_count += 1
-    
-    print(f"\n{'='*60}")
-    print(f"Summary: Modified {modified_count} out of {len(schema_files)} schema files")
-    print(f"{'='*60}")
-
-
-if __name__ == '__main__':
-    main()
-

scripts/analyze_plugin_schemas.py

@@ -1,280 +0,0 @@
-#!/usr/bin/env python3
-"""
-Analyze all plugin config schemas to identify issues:
-- Duplicate fields
-- Inconsistencies
-- Missing common fields
-- Naming variations
-- Formatting issues
-"""
-
-import json
-from pathlib import Path
-from typing import Dict, List, Any
-import jsonschema
-from jsonschema import Draft7Validator
-
-# Standard common fields that should be in all plugins
-STANDARD_COMMON_FIELDS = {
-    "enabled": {
-        "type": "boolean",
-        "default": False,
-        "description": "Enable or disable this plugin",
-        "required": True,
-        "order": 1
-    },
-    "display_duration": {
-        "type": "number",
-        "default": 15,
-        "minimum": 1,
-        "maximum": 300,
-        "description": "How long to display this plugin in seconds",
-        "order": 2
-    },
-    "live_priority": {
-        "type": "boolean",
-        "default": False,
-        "description": "Enable live priority takeover when plugin has live content",
-        "order": 3
-    },
-    "high_performance_transitions": {
-        "type": "boolean",
-        "default": False,
-        "description": "Use high-performance transitions (120 FPS) instead of standard (30 FPS)",
-        "order": 4
-    },
-    "update_interval": {
-        "type": "integer",
-        "default": 60,
-        "minimum": 1,
-        "description": "How often to refresh data in seconds",
-        "order": 5
-    },
-    "transition": {
-        "type": "object",
-        "order": 6
-    }
-}
-
-def find_duplicate_fields(schema: Dict[str, Any], path: str = "") -> List[str]:
-    """Find duplicate field definitions within a schema."""
-    duplicates = []
-    seen_fields = {}
-    
-    def check_properties(props: Dict[str, Any], current_path: str):
-        if not isinstance(props, dict):
-            return
-        
-        for key, value in props.items():
-            full_path = f"{current_path}.{key}" if current_path else key
-            if key in seen_fields:
-                duplicates.append(f"Duplicate field '{key}' at {full_path} (also at {seen_fields[key]})")
-            else:
-                seen_fields[key] = full_path
-            
-            # Recursively check nested objects
-            if isinstance(value, dict):
-                if "properties" in value:
-                    check_properties(value["properties"], full_path)
-                elif "items" in value and isinstance(value["items"], dict):
-                    if "properties" in value["items"]:
-                        check_properties(value["items"]["properties"], f"{full_path}[items]")
-    
-    if "properties" in schema:
-        check_properties(schema["properties"], "")
-    
-    return duplicates
-
-def validate_schema_syntax(schema_path: Path) -> tuple[bool, List[str]]:
-    """Validate JSON Schema syntax."""
-    errors = []
-    try:
-        with open(schema_path, 'r', encoding='utf-8') as f:
-            schema = json.load(f)
-        
-        # Validate schema structure
-        Draft7Validator.check_schema(schema)
-        return True, []
-    except json.JSONDecodeError as e:
-        return False, [f"JSON syntax error: {str(e)}"]
-    except jsonschema.SchemaError as e:
-        return False, [f"Schema validation error: {str(e)}"]
-    except Exception as e:
-        return False, [f"Error: {str(e)}"]
-
-def analyze_schema(schema_path: Path) -> Dict[str, Any]:
-    """Analyze a single schema file."""
-    plugin_id = schema_path.parent.name
-    analysis = {
-        "plugin_id": plugin_id,
-        "path": str(schema_path),
-        "valid": False,
-        "errors": [],
-        "warnings": [],
-        "has_title": False,
-        "has_description": False,
-        "common_fields": {},
-        "missing_common_fields": [],
-        "naming_issues": [],
-        "duplicates": [],
-        "property_order": [],
-        "update_interval_variant": None
-    }
-    
-    try:
-        with open(schema_path, 'r', encoding='utf-8') as f:
-            schema = json.load(f)
-        
-        # Check for title and description
-        analysis["has_title"] = "title" in schema
-        analysis["has_description"] = "description" in schema
-        
-        if not analysis["has_title"]:
-            analysis["warnings"].append("Missing 'title' field at root level")
-        if not analysis["has_description"]:
-            analysis["warnings"].append("Missing 'description' field at root level")
-        
-        # Validate schema syntax
-        is_valid, errors = validate_schema_syntax(schema_path)
-        analysis["valid"] = is_valid
-        analysis["errors"].extend(errors)
-        
-        if not is_valid:
-            return analysis
-        
-        # Check for duplicate fields
-        duplicates = find_duplicate_fields(schema)
-        analysis["duplicates"] = duplicates
-        
-        # Check properties
-        if "properties" not in schema:
-            analysis["errors"].append("Missing 'properties' field")
-            return analysis
-        
-        properties = schema["properties"]
-        
-        # Check common fields
-        for field_name, field_spec in STANDARD_COMMON_FIELDS.items():
-            if field_name in properties:
-                analysis["common_fields"][field_name] = properties[field_name]
-            else:
-                # Check for variants
-                if field_name == "update_interval":
-                    # Check for update_interval_seconds variant
-                    if "update_interval_seconds" in properties:
-                        analysis["update_interval_variant"] = "update_interval_seconds"
-                        analysis["naming_issues"].append(
-                            f"Uses 'update_interval_seconds' instead of 'update_interval'"
-                        )
-                    else:
-                        analysis["missing_common_fields"].append(field_name)
-                else:
-                    analysis["missing_common_fields"].append(field_name)
-        
-        # Check property order (enabled should be first)
-        prop_keys = list(properties.keys())
-        analysis["property_order"] = prop_keys
-        
-        if prop_keys and prop_keys[0] != "enabled":
-            analysis["warnings"].append(
-                f"'enabled' is not first property. First property is '{prop_keys[0]}'"
-            )
-        
-        # Check for required fields
-        required = schema.get("required", [])
-        if "enabled" not in required:
-            analysis["warnings"].append("'enabled' is not in required fields")
-        
-    except Exception as e:
-        analysis["errors"].append(f"Failed to analyze schema: {str(e)}")
-    
-    return analysis
-
-def main():
-    """Main analysis function."""
-    project_root = Path(__file__).parent.parent
-    plugins_dir = project_root / "plugin-repos"
-    
-    if not plugins_dir.exists():
-        print(f"Plugins directory not found: {plugins_dir}")
-        return
-    
-    results = []
-    
-    # Find all config_schema.json files
-    schema_files = list(plugins_dir.glob("*/config_schema.json"))
-    
-    print(f"Found {len(schema_files)} plugin schemas to analyze\n")
-    
-    for schema_path in sorted(schema_files):
-        print(f"Analyzing {schema_path.parent.name}...")
-        analysis = analyze_schema(schema_path)
-        results.append(analysis)
-    
-    # Print summary
-    print("\n" + "="*80)
-    print("ANALYSIS SUMMARY")
-    print("="*80)
-    
-    for result in results:
-        print(f"\n{result['plugin_id']}:")
-        print(f"  Valid: {result['valid']}")
-        
-        if result['errors']:
-            print(f"  Errors ({len(result['errors'])}):")
-            for error in result['errors']:
-                print(f"    - {error}")
-        
-        if result['warnings']:
-            print(f"  Warnings ({len(result['warnings'])}):")
-            for warning in result['warnings']:
-                print(f"    - {warning}")
-        
-        if result['duplicates']:
-            print(f"  Duplicates ({len(result['duplicates'])}):")
-            for dup in result['duplicates']:
-                print(f"    - {dup}")
-        
-        if result['missing_common_fields']:
-            print(f"  Missing common fields: {', '.join(result['missing_common_fields'])}")
-        
-        if result['naming_issues']:
-            print(f"  Naming issues:")
-            for issue in result['naming_issues']:
-                print(f"    - {issue}")
-        
-        if result['property_order'] and result['property_order'][0] != 'enabled':
-            print(f"  Property order: First is '{result['property_order'][0]}' (should be 'enabled')")
-    
-    # Overall statistics
-    print("\n" + "="*80)
-    print("OVERALL STATISTICS")
-    print("="*80)
-    
-    valid_count = sum(1 for r in results if r['valid'])
-    has_title_count = sum(1 for r in results if r['has_title'])
-    has_description_count = sum(1 for r in results if r['has_description'])
-    enabled_first_count = sum(1 for r in results if r['property_order'] and r['property_order'][0] == 'enabled')
-    total_errors = sum(len(r['errors']) for r in results)
-    total_warnings = sum(len(r['warnings']) for r in results)
-    total_duplicates = sum(len(r['duplicates']) for r in results)
-    
-    print(f"Total plugins: {len(results)}")
-    print(f"Valid schemas: {valid_count}/{len(results)}")
-    print(f"Has title: {has_title_count}/{len(results)}")
-    print(f"Has description: {has_description_count}/{len(results)}")
-    print(f"'enabled' first: {enabled_first_count}/{len(results)}")
-    print(f"Total errors: {total_errors}")
-    print(f"Total warnings: {total_warnings}")
-    print(f"Total duplicates: {total_duplicates}")
-    
-    # Save detailed report
-    report_path = project_root / "plugin_schema_analysis.json"
-    with open(report_path, 'w', encoding='utf-8') as f:
-        json.dump(results, f, indent=2)
-    
-    print(f"\nDetailed report saved to: {report_path}")
-
-if __name__ == "__main__":
-    main()
-

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

@@ -28,12 +28,12 @@ print_success() {
 
 print_warning() {
     echo -e "${YELLOW}⚠${NC} $1"
-    ((WARNINGS++))
+    WARNINGS=$((WARNINGS + 1))
 }
 
 print_error() {
     echo -e "${RED}✗${NC} $1"
-    ((COMPATIBILITY_ISSUES++))
+    COMPATIBILITY_ISSUES=$((COMPATIBILITY_ISSUES + 1))
 }
 
 # Check if running on Raspberry Pi
@@ -53,28 +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}"
-    
-    if [[ "$ID" == "raspbian" ]] || [[ "$ID" == "debian" ]]; then
-        if [ "${VERSION_ID:-0}" -ge "12" ]; then
-            print_success "Running compatible Debian/Raspbian version (${VERSION_ID})"
-            
-            if [ "${VERSION_ID:-0}" -eq "13" ]; then
-                print_success "Detected Debian 13 Trixie - full compatibility expected"
-            elif [ "${VERSION_ID:-0}" -eq "12" ]; then
-                print_success "Detected Debian 12 Bookworm - full compatibility confirmed"
-            fi
-        else
-            print_warning "Old Debian/Raspbian version (${VERSION_ID}) - upgrade recommended"
-        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_warning "Not running Debian/Raspbian - compatibility not guaranteed"
+        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"
@@ -94,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+)"
@@ -106,27 +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 "12" ]; then
-            print_success "Python version is fully supported (3.10-3.12)"
-        elif [ "$PYTHON_MINOR" -eq "13" ]; then
-            print_warning "Python 3.13 detected - most packages compatible, but some may have limited testing"
-            print_warning "Please report any compatibility issues you encounter"
-        elif [ "$PYTHON_MINOR" -ge "14" ]; then
-            print_warning "Python 3.${PYTHON_MINOR} is very new - some packages may not be compatible yet"
-        else
-            print_warning "Python 3.${PYTHON_MINOR} is outdated - upgrade to 3.10+ recommended"
-        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
@@ -157,7 +171,10 @@ ESSENTIAL_PACKAGES=(
 
 for pkg_info in "${ESSENTIAL_PACKAGES[@]}"; do
     IFS=':' read -r pkg desc <<< "$pkg_info"
-    if dpkg -l | grep -q "^ii  $pkg "; then
+    # dpkg-query rather than `dpkg -l | grep -q`: under pipefail, grep -q
+    # exiting on its first match kills dpkg with SIGPIPE and fails the pipeline,
+    # which reported installed packages as missing.
+    if [ "$(dpkg-query -W -f='${Status}' "$pkg" 2>/dev/null)" = "install ok installed" ]; then
         print_success "$desc ($pkg) is installed"
     else
         print_warning "$desc ($pkg) not installed - will be installed during setup"
@@ -269,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/check_types.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""Type-check the modules listed in mypy-clean.txt (the mypy ratchet).
+
+Most of src/ still has mypy errors, so CI can't require a clean `mypy src`.
+Instead mypy-clean.txt lists the modules that *are* clean, and this script
+fails if any of them regresses. When you make another module clean, add it to
+the list; nothing ever comes off it.
+
+Imports are followed silently: a listed module is checked against the types of
+everything it imports, but errors inside those imported modules are not
+reported, so a clean file isn't failed by an unlisted neighbour.
+
+Usage:
+    python scripts/check_types.py            # check the listed modules
+    python scripts/check_types.py --list     # print the list and exit
+
+Extra arguments after ``--`` are passed to mypy.
+Exit status: 0 clean, 1 mypy errors, 2 a bad list (missing file, duplicate,
+unsorted, or empty).
+"""
+
+import argparse
+import subprocess  # nosec B404 - list-form argv only, no shell  # nosemgrep
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+LIST_FILE = REPO_ROOT / "mypy-clean.txt"
+
+
+def read_list(path: Path = LIST_FILE) -> list:
+    """The listed paths, in file order, with comments and blank lines dropped."""
+    entries = []
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.split("#", 1)[0].strip()
+        if line:
+            entries.append(line)
+    return entries
+
+
+def list_problems(entries: list, root: Path = REPO_ROOT) -> list:
+    """Why the list can't be used as-is; empty when it is fine."""
+    problems = []
+    if not entries:
+        problems.append(f"{LIST_FILE.name} lists no modules")
+    seen = set()
+    for entry in entries:
+        if entry in seen:
+            problems.append(f"listed twice: {entry}")
+        seen.add(entry)
+        if "\\" in entry:
+            problems.append(f"use forward slashes: {entry}")
+        elif not (root / entry).is_file():
+            problems.append(f"listed but not found (renamed or deleted? update the list): {entry}")
+    if entries != sorted(entries):
+        problems.append(f"{LIST_FILE.name} is not sorted")
+    return problems
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    parser.add_argument("--list", action="store_true", help="print the listed modules and exit")
+    parser.add_argument("mypy_args", nargs="*", help="extra mypy arguments (after --)")
+    args = parser.parse_args(argv)
+
+    entries = read_list()
+    problems = list_problems(entries)
+    if problems:
+        for problem in problems:
+            print(f"check_types: {problem}", file=sys.stderr)
+        return 2
+    if args.list:
+        print("\n".join(entries))
+        return 0
+
+    cmd = [
+        sys.executable, "-m", "mypy",
+        "--config-file", str(REPO_ROOT / "mypy.ini"),
+        "--follow-imports=silent",
+        *args.mypy_args,
+        *entries,
+    ]
+    print(f"check_types: mypy on {len(entries)} modules from {LIST_FILE.name}", flush=True)
+    # This interpreter's mypy, fixed flags, and paths from the checked-in list.
+    result = subprocess.run(cmd, cwd=REPO_ROOT)  # nosec B603 - list-form argv, no shell  # nosemgrep
+    if result.returncode > 1:  # mypy itself failed (bad config, crash)
+        return result.returncode
+    if result.returncode != 0:
+        print(
+            "check_types: a module on the mypy ratchet has type errors. Fix them "
+            f"(annotation-only where possible) rather than taking it off {LIST_FILE.name}.",
+            file=sys.stderr,
+        )
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/dev/README.md

@@ -5,7 +5,8 @@ This directory contains scripts and utilities for development and testing.
 ## Scripts
 
 - **`dev_plugin_setup.sh`** - Sets up plugin development environment by linking plugin repositories
-- **`run_emulator.sh`** - Runs the LED Matrix display in emulator mode (for development without hardware)
+- **`vegas_audit.py`** - Measures how much of the Vegas ticker strip actually shows content (dead-frame ratio)
+- **`test_pillow_compat.py`** - Pillow API smoke test to run after upgrading Pillow (`python3 scripts/dev/test_pillow_compat.py`)
 
 ## Usage
 
@@ -26,6 +27,6 @@ links. To use a fork or another clone location, copy
 
 ### Running Emulator
 ```bash
-./scripts/dev/run_emulator.sh
+python3 run.py -e
 ```
 

scripts/dev/run_emulator.sh

@@ -1,13 +0,0 @@
-#!/bin/bash
-# LEDMatrix Emulator Runner
-# This script runs the LEDMatrix system in emulator mode for development and testing
-
-echo "Starting LEDMatrix Emulator..."
-echo "Press Ctrl+C to stop"
-echo ""
-
-# Set emulator mode
-export EMULATOR=true
-
-# Run the main application
-python3 run.py

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
@@ -423,7 +474,7 @@ def main():
     global _extra_dirs
     _extra_dirs = args.extra_dir
 
-    print(f"LEDMatrix Dev Preview Server")
+    print("LEDMatrix Dev Preview Server")
     print(f"Open http://{args.host}:{args.port} in your browser")
     print(f"Plugin search dirs: {[str(d) for d in get_search_dirs()]}")
     print()

scripts/fix_perms/README.md

@@ -18,21 +18,26 @@ system user.
   permissions on the `assets/` tree so plugins can download and cache
   team logos, fonts, and other static content.
 
-- **`fix_cache_permissions.sh`** — Creates (if missing) and fixes
-  permissions on `/var/cache/ledmatrix/` and `~/.ledmatrix_cache/` of the
-  user running `sudo`, and creates
-  `/var/cache/ledmatrix/placeholder_logos/` for the sports plugins. It does
-  not touch the cache manager's other fallbacks (`/opt/ledmatrix/cache`,
-  `$TMPDIR/ledmatrix_cache`).
+- **`fix_cache_permissions.sh`** — Restores `/var/cache/ledmatrix/` to the
+  shared `ledmatrix`-group setup by running
+  `scripts/install/setup_cache.sh` (the same script the installer uses),
+  and creates/fixes `~/.ledmatrix_cache/` of the user running `sudo`. It
+  does not touch the cache manager's other fallbacks
+  (`/opt/ledmatrix/cache`, `$TMPDIR/ledmatrix_cache`).
 
 - **`fix_plugin_permissions.sh`** — Fixes ownership on the plugins
   directory so both the root display service and the web service user
   can read and write plugin files (manifests, configs, requirements
   installs).
 
-- **`fix_web_permissions.sh`** — Fixes permissions on log files,
-  systemd journal access, and the sudoers entries the web interface
-  needs to control the display service.
+- **`fix_web_permissions.sh`** — Adds you to the `systemd-journal` and
+  `adm` groups so the web UI can read logs, and makes the project
+  directory yours again, keeping the root-owned sudo helpers
+  (`safe_plugin_rm.sh`, `safe_pip_install.sh`) and `config_secrets.json`
+  the way the installer leaves them. Run it as the web interface's user,
+  **without** `sudo` (it refuses to run as root and calls `sudo` itself).
+  It does not write sudoers rules; that is
+  `scripts/install/configure_web_sudo.sh`.
 
 - **`safe_pip_install.sh`** — Installs a `requirements.txt` as root
   after checking it is the project's own or one under `plugin-repos/` or
@@ -67,7 +72,9 @@ Run these scripts only when:
 sudo ./scripts/fix_perms/fix_cache_permissions.sh
 sudo ./scripts/fix_perms/fix_assets_permissions.sh
 sudo ./scripts/fix_perms/fix_plugin_permissions.sh
-sudo ./scripts/fix_perms/fix_web_permissions.sh
+
+# Run as the web interface's user, without sudo (it asks for sudo itself)
+./scripts/fix_perms/fix_web_permissions.sh
 ```
 
 If you're not sure which one you need, run `fix_cache_permissions.sh`

scripts/fix_perms/fix_assets_permissions.sh

@@ -36,11 +36,12 @@ else
     exit 1
 fi
 
-# Set permissions to allow read/write for owner, group, and others (for root service user)
-# Note: 777 allows root (service user) to write, which is necessary when service runs as root
+# 777: read/write for owner, group and every other account. Root (the display
+# service) does not need it -- root ignores mode bits -- so the "other" bits
+# only matter to accounts that are neither $REAL_USER nor root.
 echo "Setting permissions for assets directory..."
 if sudo chmod -R 777 "$ASSETS_DIR"; then
-    echo "✓ Set assets directory permissions to 777 (writable by root service user)"
+    echo "✓ Set assets directory permissions to 777"
 else
     echo "✗ Failed to set assets directory permissions"
     exit 1
@@ -70,8 +71,7 @@ for SPORTS_DIR in "${SPORTS_DIRS[@]}"; do
         echo "  - Current permissions:"
         ls -ld "$FULL_PATH"
         
-        # Ensure the directory is writable by both the real user and root (service user)
-        # Use 777 permissions to allow root (service) to write, or set group ownership
+        # Owned by the real user; 777 as above (root can write here regardless)
         sudo chmod 777 "$FULL_PATH"
         sudo chown "$REAL_USER:$REAL_GROUP" "$FULL_PATH"
         

scripts/fix_perms/fix_cache_permissions.sh

@@ -1,11 +1,23 @@
 #!/bin/bash
 
 # LEDMatrix Cache Permissions Fix Script
-# This script fixes permissions on all known cache directories so they're writable by the daemon or current user
-# Also sets up placeholder logo directories for sports managers
+#
+# /var/cache/ledmatrix is shared by the display service (root) and the web
+# interface (your user) through the ledmatrix group: root:ledmatrix, 2775,
+# files 660. scripts/install/setup_cache.sh is what sets that up (the
+# installer's Step 2 runs it, and install_web_service.sh keeps the group), so
+# this script runs it rather than applying a model of its own. It used to set
+# the directory 777 and re-group it to your own group, replacing the ledmatrix
+# group everything else relies on.
+#
+# It also repairs ~/.ledmatrix_cache, the cache manager's fallback when
+# /var/cache/ledmatrix is unusable.
 
 echo "Fixing LEDMatrix cache directory permissions..."
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SETUP_CACHE="$SCRIPT_DIR/../install/setup_cache.sh"
+
 # Get the real user (not root when running with sudo)
 REAL_USER=${SUDO_USER:-$USER}
 # Resolve the home directory of the real user robustly
@@ -16,72 +28,36 @@ else
 fi
 REAL_GROUP=$(id -gn "$REAL_USER")
 
-# Known cache directories for LEDMatrix. Use the actual user's home instead of a hard-coded path.
-CACHE_DIRS=(
-    "/var/cache/ledmatrix"
-    "$REAL_HOME/.ledmatrix_cache"
-)
-
-for CACHE_DIR in "${CACHE_DIRS[@]}"; do
-    echo ""
-    echo "Checking cache directory: $CACHE_DIR"
-    if [ ! -d "$CACHE_DIR" ]; then
-        echo "  - Directory does not exist. Creating it..."
-        sudo mkdir -p "$CACHE_DIR"
-    fi
-    echo "  - Current permissions:"
-    ls -ld "$CACHE_DIR"
-    echo "  - Fixing permissions..."
-    # Make directory writable by services regardless of user context
-    sudo chmod 777 "$CACHE_DIR"
-    sudo chown "$REAL_USER":"$REAL_GROUP" "$CACHE_DIR"
-    echo "  - Updated permissions:"
-    ls -ld "$CACHE_DIR"
-    echo "  - Testing write access as $REAL_USER..."
-    if sudo -u "$REAL_USER" test -w "$CACHE_DIR"; then
-        echo "    ✓ $CACHE_DIR is now writable by $REAL_USER"
-    else
-        echo "    ✗ $CACHE_DIR is still not writable by $REAL_USER"
-    fi
-    echo "  - Permissions fix complete for $CACHE_DIR."
-done
-
-# Set up placeholder logos directory for sports managers
 echo ""
-echo "Setting up placeholder logos directory for sports managers..."
-
-PLACEHOLDER_DIR="/var/cache/ledmatrix/placeholder_logos"
-if [ ! -d "$PLACEHOLDER_DIR" ]; then
-    echo "Creating placeholder logos directory: $PLACEHOLDER_DIR"
-    sudo mkdir -p "$PLACEHOLDER_DIR"
-    sudo chown "$REAL_USER":"$REAL_GROUP" "$PLACEHOLDER_DIR"
-    sudo chmod 777 "$PLACEHOLDER_DIR"
+echo "Checking cache directory: /var/cache/ledmatrix"
+if [ -f "$SETUP_CACHE" ]; then
+    bash "$SETUP_CACHE"
 else
-    echo "Placeholder logos directory already exists: $PLACEHOLDER_DIR"
-    sudo chmod 777 "$PLACEHOLDER_DIR"
-    sudo chown "$REAL_USER":"$REAL_GROUP" "$PLACEHOLDER_DIR"
+    echo "  ✗ $SETUP_CACHE not found; /var/cache/ledmatrix left unchanged."
 fi
 
+CACHE_DIR="$REAL_HOME/.ledmatrix_cache"
+echo ""
+echo "Checking cache directory: $CACHE_DIR"
+if [ ! -d "$CACHE_DIR" ]; then
+    echo "  - Directory does not exist. Creating it..."
+    sudo mkdir -p "$CACHE_DIR"
+fi
 echo "  - Current permissions:"
-ls -ld "$PLACEHOLDER_DIR"
+ls -ld "$CACHE_DIR"
+echo "  - Fixing permissions..."
+sudo chmod 777 "$CACHE_DIR"
+sudo chown "$REAL_USER":"$REAL_GROUP" "$CACHE_DIR"
+echo "  - Updated permissions:"
+ls -ld "$CACHE_DIR"
 echo "  - Testing write access as $REAL_USER..."
-if sudo -u "$REAL_USER" test -w "$PLACEHOLDER_DIR"; then
-    echo "    ✓ Placeholder logos directory is writable by $REAL_USER"
+if sudo -u "$REAL_USER" test -w "$CACHE_DIR"; then
+    echo "    ✓ $CACHE_DIR is now writable by $REAL_USER"
 else
-    echo "    ✗ Placeholder logos directory is not writable by $REAL_USER"
-fi
-
-# Test with daemon user (which the system might run as)
-if sudo -u daemon test -w "$PLACEHOLDER_DIR" 2>/dev/null; then
-    echo "    ✓ Placeholder logos directory is writable by daemon user"
-else
-    echo "    ✗ Placeholder logos directory is not writable by daemon user"
+    echo "    ✗ $CACHE_DIR is still not writable by $REAL_USER"
 fi
+echo "  - Permissions fix complete for $CACHE_DIR."
 
 echo ""
 echo "All cache directory permission fixes attempted."
 echo "If you still see errors, check which user is running the LEDMatrix service and ensure it matches the owner above."
-echo ""
-echo "The system will now create placeholder logos in:"
-echo "  $PLACEHOLDER_DIR"
-echo "This should eliminate the permission denied warnings for sports logos." 

scripts/fix_perms/fix_plugin_permissions.sh

@@ -51,9 +51,10 @@ fi
 echo "Setting ownership to root:$ACTUAL_USER..."
 sudo chown -R root:"$ACTUAL_USER" "$PLUGINS_DIR"
 
-# Set directory permissions (775: rwxrwxr-x)
-# Root: read/write/execute, Group (ACTUAL_USER): read/write/execute, Others: read/execute
-echo "Setting directory permissions to 2775 (rwxrwxr-x + sticky bit)..."
+# Set directory permissions (2775: rwxrwsr-x)
+# Owner (root) and group (ACTUAL_USER): read/write/execute, others: read/execute.
+# The setgid bit makes new entries inherit the ACTUAL_USER group.
+echo "Setting directory permissions to 2775 (rwxrwsr-x, setgid)..."
 find "$PLUGINS_DIR" -type d -exec sudo chmod 2775 {} \;
 
 # Set file permissions (664: rw-rw-r--)
@@ -71,7 +72,7 @@ fi
 echo "Setting ownership of plugin-repos to root:$ACTUAL_USER..."
 sudo chown -R root:"$ACTUAL_USER" "$PLUGIN_REPOS_DIR"
 
-echo "Setting plugin-repos directory permissions to 2775 (rwxrwxr-x + sticky bit)..."
+echo "Setting plugin-repos directory permissions to 2775 (rwxrwsr-x, setgid)..."
 find "$PLUGIN_REPOS_DIR" -type d -exec sudo chmod 2775 {} \;
 
 echo "Setting plugin-repos file permissions to 664..."
@@ -87,7 +88,7 @@ echo "plugin-repos/:"
 ls -la "$PLUGIN_REPOS_DIR" 2>/dev/null || echo "  (empty or not accessible)"
 echo ""
 echo "Permissions summary:"
-echo "- Root service: Can read/write plugins (for PWM hardware access)"
+echo "- Root service: Can read/write plugins (as root it needs no permission bits)"
 echo "- Web service ($ACTUAL_USER): Can read/write plugins (for installation)"
 echo "- Others: Can read plugins"
 

scripts/fix_perms/fix_web_permissions.sh

@@ -25,8 +25,9 @@ echo ""
 echo "This script will:"
 echo "1. Add the web user to the 'systemd-journal' group for log access"
 echo "2. Add the web user to the 'adm' group for additional system access"
-echo "3. Configure sudoers for passwordless access to system commands"
-echo "4. Set proper file permissions"
+echo "3. Make the project directory yours again, keeping the root-owned sudo"
+echo "   helpers and config_secrets.json as the installer leaves them"
+echo "   (sudoers rules are configure_web_sudo.sh's job, not this script's)"
 echo ""
 
 # Ask for confirmation
@@ -62,6 +63,51 @@ else
     echo "✗ Failed to set project ownership"
 fi
 
+# The chown above also takes back two kinds of file that first_time_install.sh
+# deliberately keeps from the web user. Put them back the way the installer
+# leaves them (its Steps 11 and 11.1), whether or not the chown succeeded.
+#
+# 1. The helpers /etc/sudoers.d/ledmatrix_web lets the web user run as root
+#    (scripts/install/lib_sudoers.sh). A copy the web user owns is a root shell
+#    for whoever can edit it, so they stay root-owned and writable by root only.
+#    Keep this list in step with the installer's Step 11.1 loop;
+#    test/test_web_sudoers_installers_agree.py checks both against the grants.
+for helper in safe_plugin_rm.sh safe_pip_install.sh; do
+    HELPER_PATH="$PROJECT_DIR/scripts/fix_perms/$helper"
+    if [ -f "$HELPER_PATH" ]; then
+        if sudo chown root:root "$HELPER_PATH" && sudo chmod 755 "$HELPER_PATH"; then
+            echo "✓ $helper is root-owned again (sudo runs it as root)"
+        else
+            echo "⚠ Could not make $HELPER_PATH root-owned, mode 755."
+            echo "  Fix it by hand: sudo chown root:root $HELPER_PATH && sudo chmod 755 $HELPER_PATH"
+        fi
+    fi
+done
+
+# 2. config_secrets.json: owned by the account ledmatrix-web.service runs as,
+#    group ledmatrix, mode 640 -- the same owner, group and mode as the
+#    installer's Step 11 gives it.
+SECRETS_FILE="$PROJECT_DIR/config/config_secrets.json"
+if [ -f "$SECRETS_FILE" ]; then
+    SECRETS_OWNER=""
+    if [ -f /etc/systemd/system/ledmatrix-web.service ]; then
+        SECRETS_OWNER=$(grep -m1 "^User=" /etc/systemd/system/ledmatrix-web.service | cut -d'=' -f2 || true)
+    fi
+    SECRETS_OWNER="${SECRETS_OWNER:-$WEB_USER}"
+    if getent group ledmatrix >/dev/null 2>&1; then
+        SECRETS_OWNERSHIP="$SECRETS_OWNER:ledmatrix"
+    else
+        # No ledmatrix group means the installer never ran; keep the chown's group.
+        SECRETS_OWNERSHIP="$SECRETS_OWNER"
+    fi
+    if sudo chown "$SECRETS_OWNERSHIP" "$SECRETS_FILE" && sudo chmod 640 "$SECRETS_FILE"; then
+        echo "✓ config_secrets.json restored to $SECRETS_OWNERSHIP, mode 640"
+    else
+        echo "⚠ Could not restore $SECRETS_FILE to $SECRETS_OWNERSHIP, mode 640."
+        echo "  Fix it by hand: sudo chown $SECRETS_OWNERSHIP $SECRETS_FILE && sudo chmod 640 $SECRETS_FILE"
+    fi
+fi
+
 # Set proper permissions for config files
 if sudo chmod 644 "$PROJECT_DIR/config/config.json" 2>/dev/null; then
     echo "✓ Set config file permissions"
@@ -86,7 +132,7 @@ echo "Step 5: Testing sudo access..."
 if sudo -n systemctl status ledmatrix.service > /dev/null 2>&1; then
     echo "✓ Sudo access test passed"
 else
-    echo "⚠ Sudo access test failed - you may need to run configure_web_sudo.sh"
+    echo "⚠ Sudo access test failed - you may need to run scripts/install/configure_web_sudo.sh"
 fi
 
 echo ""
@@ -101,5 +147,5 @@ echo ""
 echo "After logging back in, test journal access with:"
 echo "  journalctl --no-pager --lines=5"
 echo ""
-echo "If you still have sudo issues, run:"
-echo "  ./configure_web_sudo.sh"
+echo "If you still have sudo issues, run (as this user, without sudo):"
+echo "  $PROJECT_DIR/scripts/install/configure_web_sudo.sh"

scripts/frame_soak.py

@@ -0,0 +1,479 @@
+#!/usr/bin/env python3
+"""Soak a running display and report how often moving frames reached the panel late.
+
+Runs NEXT TO the display service, as any user: it only reads the stats file the
+service writes (src/common/frame_timing.py) at the start and end of the run and
+reports the difference. Nothing is stopped, restarted or drawn.
+
+    # 10 minutes, as the display is now
+    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). 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
+    python3 scripts/frame_soak.py --show
+
+    # keep the report for a before/after comparison
+    python3 scripts/frame_soak.py --duration 600 --json soak-before.json
+
+Exit status: 0 when the late-frame rate is within ``--max-late-pct``, 1 when it
+is not, 2 when there was nothing to measure (no stats file, the service
+restarted mid-run, or nothing scrolled).
+
+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
+                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
+
+import argparse
+import json
+import os
+import sys
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from src.common.frame_timing import (  # noqa: E402
+    BUCKET_COUNT,
+    SCHEMA_VERSION,
+    default_stats_path,
+)
+
+#: Touched by the web UI while someone has the preview open; a fresh marker
+#: 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
+
+#: A stats file not rewritten for this long means nothing is being presented.
+STALE_SECONDS = 30.0
+
+
+def load(path: str) -> Optional[Dict[str, Any]]:
+    try:
+        with open(path, encoding="utf-8") as handle:
+            stats = json.load(handle)
+    except (OSError, ValueError):
+        return None
+    if not isinstance(stats, dict) or stats.get("version") != SCHEMA_VERSION:
+        return None
+    return stats
+
+
+def _histogram(stats: Dict[str, Any], name: str) -> Dict[int, int]:
+    raw = (stats.get("histograms") or {}).get(name) or {}
+    return {int(k): int(v) for k, v in raw.items()}
+
+
+def diff(before: Dict[str, Any], after: Dict[str, Any]) -> Dict[str, Any]:
+    """What happened between two snapshots of the same process."""
+    tb, ta = before["totals"], after["totals"]
+    totals = {}
+    for key, value in ta.items():
+        if isinstance(value, dict):
+            totals[key] = {k: v - tb.get(key, {}).get(k, 0)
+                           for k, v in value.items()}
+        elif key == "worst_interval_ms":
+            # A running maximum can't be differenced; it is reported as the
+            # worst since the service started.
+            totals[key] = value
+        else:
+            totals[key] = value - tb.get(key, 0)
+    histograms = {}
+    for name in (after.get("histograms") or {}):
+        hb, ha = _histogram(before, name), _histogram(after, name)
+        histograms[name] = {k: v - hb.get(k, 0) for k, v in ha.items()
+                            if v - hb.get(k, 0) > 0}
+    return {"totals": totals, "histograms": histograms,
+            "seconds": after["updated"] - before["updated"]}
+
+
+def percentiles(histogram: Dict[int, int], bucket_ms: float) -> Dict[str, Any]:
+    """p50/p95/p99/max from a sparse histogram, as each bucket's upper edge."""
+    count = sum(histogram.values())
+    if not count:
+        return {}
+    out = {}
+    targets = {"p50": 0.50, "p95": 0.95, "p99": 0.99}
+    running = 0
+    for index in sorted(histogram):
+        running += histogram[index]
+        for name, fraction in list(targets.items()):
+            if running >= fraction * count:
+                out[name] = _edge(index, bucket_ms)
+                del targets[name]
+    out["max"] = _edge(max(histogram), bucket_ms)
+    return out
+
+
+def _edge(index: int, bucket_ms: float):
+    if index >= BUCKET_COUNT - 1:
+        return f">={index * bucket_ms:g}"
+    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"]
+    frames = totals["scroll_frames"]
+    # The rates are over frames judged against a known refresh period. Stats
+    # from a recorder that predates the count fall back to every frame.
+    timed = totals.get("timed_frames", frames) if "timed_frames" in totals else frames
+    hours = delta["seconds"] / 3600.0 if delta["seconds"] > 0 else 0.0
+    bucket_ms = after.get("bucket_ms", 0.25)
+    report = {
+        "seconds": round(delta["seconds"], 1),
+        "preview": preview,
+        "info": after.get("info"),
+        "binding_releases_gil": after.get("binding_releases_gil"),
+        "measured_refresh_hz": after.get("measured_refresh_hz"),
+        "scroll_frames": frames,
+        "static_frames": totals["static_frames"],
+        "late_frames": totals["late_frames"],
+        "timed_frames": timed,
+        "late_pct": round(100.0 * totals["late_frames"] / timed, 3) if timed else None,
+        "missed_refreshes": totals["missed_refreshes"],
+        "late_by": totals["late_by"],
+        "early_frames": totals.get("early_frames", 0),
+        "early_pct": (round(100.0 * totals.get("early_frames", 0) / timed, 3)
+                      if timed else None),
+        "freeze_by": totals.get("freeze_by", {}),
+        "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
+    # bit-banging the panel and pushing frames at once); a widening gap between
+    # the two is a render-cost regression even when nothing is late.
+    typical = (report["timing_ms"].get("interval_per_hold") or {}).get("p50")
+    # percentiles() reports a bucket's upper edge; the midpoint is the better
+    # estimate, and half a 0.25ms bucket is already ~1% at 100Hz -- the size
+    # of the idle-vs-held gap this number exists to show.
+    if isinstance(typical, (int, float)) and typical > bucket_ms / 2:
+        report["held_refresh_hz"] = round(1000.0 / (typical - bucket_ms / 2), 1)
+    else:
+        report["held_refresh_hz"] = None
+    return report
+
+
+def print_report(report: Dict[str, Any], limit: float) -> None:
+    info = report.get("info") or {}
+    size = "{}x{}".format(
+        (info.get("cols") or 0) * (info.get("chain_length") or 1),
+        (info.get("rows") or 0) * (info.get("parallel") or 1))
+    gil = {True: "releases the GIL", False: "STOCK (holds the GIL in SwapOnVSync)",
+           None: "unknown"}[report.get("binding_releases_gil")]
+    print(f"Rig       {info.get('pi_model') or 'unknown'}")
+    print(f"Panel     {size}  chain {info.get('chain_length')} x parallel "
+          f"{info.get('parallel')}  pwm_bits {info.get('pwm_bits')}  "
+          f"slowdown {info.get('gpio_slowdown')}  mapping {info.get('hardware_mapping')}")
+    print(f"Refresh   {report.get('measured_refresh_hz') or '?'} Hz measured, "
+          f"cap {info.get('limit_refresh_rate_hz')}")
+    print(f"Binding   {gil}")
+    print(f"Run       {report['seconds']:.0f}s, preview "
+          f"{'open (simulated)' if report['preview'] else 'as-is'}")
+    print()
+    frames = report["scroll_frames"]
+    print(f"Scrolling frames   {frames}")
+    if frames:
+        late_by = report["late_by"]
+        print(f"Late frames        {report['late_frames']} ({report['late_pct']}%)"
+              f"  missed refreshes {report['missed_refreshes']}"
+              f"  [by 1: {late_by['1']}, 2: {late_by['2']}, "
+              f"3-5: {late_by['3-5']}, 6+: {late_by['6+']}]")
+        if report["early_frames"]:
+            print(f"Early frames       {report['early_frames']} "
+                  f"({report['early_pct']}%)  swaps returned a refresh early")
+    print(f"Freezes >=250ms    {report['freezes']}"
+          f" ({report['freezes_per_hour']}/h, {report['freeze_seconds']}s total)"
+          f"  worst gap since start {report['worst_interval_ms'] or '-'} ms")
+    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"):
+        row = report["timing_ms"].get(name) or {}
+        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):
+        ceiling = refresh_ceiling(report)
+        if (report.get("early_pct") or 0.0) > limit:
+            why = (f"{report['early_pct']}% of frames came a refresh early, so the "
+                   "swaps were not waiting for the panel")
+        else:
+            why = (f"frames arrived at {report['measured_refresh_hz']}Hz, faster than "
+                   f"the panel can refresh ({ceiling:g}Hz)")
+        print(f"RESULT  FAIL  NOT LOCKED: {why}, and the late count means nothing")
+    elif report["late_pct"] <= limit:
+        print(f"RESULT  PASS  {report['late_pct']}% late <= {limit}%")
+    else:
+        print(f"RESULT  FAIL  {report['late_pct']}% late > {limit}%")
+
+
+#: How far over the panel's rate frames may arrive before the loop cannot have
+#: been waiting for it. The margin covers the refresh wandering a little.
+CEILING_MARGIN = 1.05
+
+
+def refresh_ceiling(report: Dict[str, Any]) -> Optional[float]:
+    """The fastest the panel can refresh, as far as this run knows.
+
+    The benchmark measures it (``idle_refresh_hz``); the service only knows its
+    cap. With neither, there is no ceiling to check against.
+    """
+    idle = report.get("idle_refresh_hz")
+    if idle:
+        return float(idle)
+    cap = (report.get("info") or {}).get("limit_refresh_rate_hz")
+    try:
+        cap = float(cap)
+    except (TypeError, ValueError):
+        return None
+    return cap if cap > 0 else None
+
+
+def locked(report: Dict[str, Any], limit: float) -> bool:
+    """Whether the loop was paced by the panel at all.
+
+    Two ways it is not. Frames a whole refresh early mean some swaps did not
+    wait. And a loop that never waited at all -- the dirty-tracking skip firing
+    mid-scroll let one free-run at 827fps -- looks self-consistent to a refresh
+    estimate taken from its own frames, so nothing registers as early; what
+    gives it away is a "refresh" faster than the panel can physically do.
+    """
+    if (report.get("early_pct") or 0.0) > limit:
+        return False
+    ceiling = refresh_ceiling(report)
+    measured = report.get("measured_refresh_hz")
+    return not (ceiling and measured and measured > ceiling * CEILING_MARGIN)
+
+
+def passed(report: Dict[str, Any], limit: float) -> bool:
+    return (report["late_pct"] is not None and locked(report, limit)
+            and report["late_pct"] <= limit)
+
+
+def touch_marker() -> bool:
+    try:
+        with open(VIEWER_MARKER, "a"):
+            pass
+        os.utime(VIEWER_MARKER, None)
+        return True
+    except OSError:
+        return False
+
+
+def wait_for_fresh(path: str, timeout: float) -> Optional[Dict[str, Any]]:
+    """The first snapshot written after now, so both ends of the run are exact."""
+    first = load(path)
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        current = load(path)
+        if current and (first is None or current["updated"] != first["updated"]):
+            return current
+        time.sleep(0.5)
+    return None
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("--duration", type=float, default=600.0,
+                        help="seconds to soak (default 600)")
+    parser.add_argument("--preview", action="store_true",
+                        help="keep the web-preview viewer marker fresh, as an "
+                             "open preview tab does")
+    parser.add_argument("--max-late-pct", type=float, default=0.1,
+                        help="fail above this percentage of late frames (default 0.1)")
+    parser.add_argument("--stats", default=default_stats_path(),
+                        help="stats file written by the display service")
+    parser.add_argument("--json", metavar="PATH",
+                        help="also write the report as JSON")
+    parser.add_argument("--show", action="store_true",
+                        help="print totals since the service started and exit")
+    args = parser.parse_args(argv)
+
+    current = load(args.stats)
+    if current is None:
+        print(f"No frame stats at {args.stats}. Is the display service running a "
+              "build with frame timing, and has anything scrolled for ~10s?",
+              file=sys.stderr)
+        return 2
+    if time.time() - current["updated"] > STALE_SECONDS:
+        print(f"Frame stats are {time.time() - current['updated']:.0f}s old: nothing "
+              "has been presented recently (static screen, or the service stopped).",
+              file=sys.stderr)
+        if not args.show:
+            return 2
+
+    if args.show:
+        empty = json.loads(json.dumps(current))
+        for key, value in empty["totals"].items():
+            empty["totals"][key] = ({k: 0 for k in value} if isinstance(value, dict)
+                                    else 0)
+        empty["histograms"] = {}
+        empty["updated"] = current["started"]
+        report = build_report(empty, current, preview=False)
+        print_report(report, args.max_late_pct)
+        return 0
+
+    if args.preview and not touch_marker():
+        print(f"Cannot touch {VIEWER_MARKER}; run as the web service's user to "
+              "simulate an open preview.", file=sys.stderr)
+        return 2
+
+    print(f"Waiting for a fresh baseline from {args.stats} ...", flush=True)
+    before = wait_for_fresh(args.stats, timeout=60.0)
+    if before is None:
+        print("The stats file stopped updating.", file=sys.stderr)
+        return 2
+
+    end = time.time() + args.duration
+    next_progress = time.time() + 60.0
+    while time.time() < end:
+        if args.preview:
+            touch_marker()
+        time.sleep(1.0)
+        if time.time() >= next_progress:
+            now = load(args.stats)
+            if now and now.get("pid") == before["pid"]:
+                done = now["totals"]["scroll_frames"] - before["totals"]["scroll_frames"]
+                late = now["totals"]["late_frames"] - before["totals"]["late_frames"]
+                print(f"  {int(end - time.time())}s left: {done} scrolling frames, "
+                      f"{late} late", flush=True)
+            next_progress += 60.0
+
+    after = wait_for_fresh(args.stats, timeout=60.0)
+    if after is None:
+        print("The stats file stopped updating during the run.", file=sys.stderr)
+        return 2
+    if after.get("pid") != before.get("pid"):
+        print("The display service restarted during the run; results discarded.",
+              file=sys.stderr)
+        return 2
+
+    report = build_report(before, after, preview=args.preview)
+    print()
+    print_report(report, args.max_late_pct)
+    if args.json:
+        with open(args.json, "w", encoding="utf-8") as handle:
+            json.dump(report, handle, indent=2)
+    if report["late_pct"] is None:
+        return 2
+    return 0 if passed(report, args.max_late_pct) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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
@@ -19,6 +26,24 @@ This directory contains scripts for installing and configuring the LEDMatrix sys
   (the user who runs the script, i.e. the one you installed LEDMatrix as;
   there is no `ledmatrix` system user) the passwordless `nmcli` and related
   WiFi permissions the web interface needs
+- **`install_dns_fix.sh`** - Optional. Installs `ledmatrix-dns-fix.service`,
+  which adds `options single-request` to the resolver when API calls time
+  out (see `systemd/README.md`)
+- **`install_mqtt_bridge.sh`** - Optional. Installs the Home Assistant MQTT
+  bridge service (see `integrations/mqtt_bridge/README.md`)
+
+Libraries (sourced, not run):
+
+- **`lib_sudoers.sh`** - The web interface's sudo allow-list
+  (`/etc/sudoers.d/ledmatrix_web`), shared by `first_time_install.sh` and
+  `configure_web_sudo.sh`
+- **`lib_systemd_render.sh`** - `sed_escape_replacement`, used by every
+  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

@@ -26,17 +26,31 @@ fi
 # Get the full paths to commands and validate each one
 MISSING_CMDS=()
 
-PYTHON_PATH=$(command -v python3)   || true
-SYSTEMCTL_PATH=$(command -v systemctl) || true
-REBOOT_PATH=$(command -v reboot)    || true
-POWEROFF_PATH=$(command -v poweroff)  || true
-BASH_PATH=$(command -v bash)        || true
-JOURNALCTL_PATH=$(command -v journalctl) || true
+# Full path of a command, also looking in the sbin directories. This script runs
+# as the web user, whose PATH usually lacks /usr/sbin and /sbin -- where reboot
+# and poweroff live -- so `command -v` alone silently dropped their rules.
+find_command() {
+    local found
+    found=$(command -v "$1" 2>/dev/null) && { printf '%s\n' "$found"; return 0; }
+    for dir in /usr/sbin /sbin /usr/bin /bin; do
+        if [ -x "$dir/$1" ]; then
+            printf '%s\n' "$dir/$1"
+            return 0
+        fi
+    done
+    return 1
+}
+
+SYSTEMCTL_PATH=$(find_command systemctl) || true
+REBOOT_PATH=$(find_command reboot)    || true
+POWEROFF_PATH=$(find_command poweroff)  || true
+BASH_PATH=$(find_command bash)        || true
+JOURNALCTL_PATH=$(find_command journalctl) || true
 SAFE_RM_PATH="$PROJECT_ROOT/scripts/fix_perms/safe_plugin_rm.sh"
 SAFE_PIP_INSTALL_PATH="$PROJECT_ROOT/scripts/fix_perms/safe_pip_install.sh"
 
-# Validate required commands (systemctl, bash, python3 are essential)
-for CMD_NAME in SYSTEMCTL_PATH BASH_PATH PYTHON_PATH; do
+# Validate required commands (systemctl and bash are essential)
+for CMD_NAME in SYSTEMCTL_PATH BASH_PATH; do
     CMD_VAL="${!CMD_NAME}"
     if [ -z "$CMD_VAL" ]; then
         MISSING_CMDS+=("$CMD_NAME")
@@ -59,8 +73,17 @@ if [ ! -f "$SAFE_PIP_INSTALL_PATH" ]; then
     exit 1
 fi
 
+# The rules are shared with first_time_install.sh (Step 10) so the two cannot
+# drift apart; add or remove a grant in lib_sudoers.sh, not here.
+SUDOERS_LIB="$PROJECT_DIR/lib_sudoers.sh"
+if [ ! -f "$SUDOERS_LIB" ]; then
+    echo "Error: Sudoers rules library not found: $SUDOERS_LIB" >&2
+    exit 1
+fi
+# shellcheck source=scripts/install/lib_sudoers.sh
+. "$SUDOERS_LIB"
+
 echo "Command paths:"
-echo "  Python: $PYTHON_PATH"
 echo "  Systemctl: $SYSTEMCTL_PATH"
 echo "  Reboot: ${REBOOT_PATH:-(not found, skipping)}"
 echo "  Poweroff: ${POWEROFF_PATH:-(not found, skipping)}"
@@ -69,62 +92,24 @@ echo "  Journalctl: ${JOURNALCTL_PATH:-(not found, skipping)}"
 echo "  Safe plugin rm: $SAFE_RM_PATH"
 echo "  Safe pip install: $SAFE_PIP_INSTALL_PATH"
 
-# Create a temporary sudoers file
-TEMP_SUDOERS="/tmp/ledmatrix_web_sudoers_$$"
+# Create a temporary sudoers file. A predictable name in a world-writable
+# directory is a symlink target, and these rules end up in /etc/sudoers.d, so
+# let mktemp pick the name; the trap removes it however the script ends.
+TEMP_SUDOERS=$(mktemp "${TMPDIR:-/tmp}/ledmatrix_web_sudoers.XXXXXX") || {
+    echo "Error: could not create a temporary file" >&2
+    exit 1
+}
+trap 'rm -f "$TEMP_SUDOERS"' EXIT
 
-{
-    echo "# LED Matrix Web Interface passwordless sudo configuration"
-    echo "# This allows the web interface user to run specific commands without a password"
-    echo ""
-    echo "# Allow $WEB_USER to run specific commands without a password for the LED Matrix web interface"
-
-    # Optional: reboot/poweroff (non-critical — skip if not found)
-    if [ -n "$REBOOT_PATH" ]; then
-        echo "$WEB_USER ALL=(ALL) NOPASSWD: $REBOOT_PATH"
-    fi
-    if [ -n "$POWEROFF_PATH" ]; then
-        echo "$WEB_USER ALL=(ALL) NOPASSWD: $POWEROFF_PATH"
-    fi
-
-    # Required: systemctl
-    echo "$WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH start ledmatrix.service"
-    echo "$WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH stop ledmatrix.service"
-    echo "$WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH restart ledmatrix.service"
-    echo "$WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH enable ledmatrix.service"
-    echo "$WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH disable ledmatrix.service"
-    echo "$WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH status ledmatrix.service"
-    echo "$WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH is-active ledmatrix"
-    echo "$WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH is-active ledmatrix.service"
-    echo "$WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH start ledmatrix-web.service"
-    echo "$WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH stop ledmatrix-web.service"
-    echo "$WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH restart ledmatrix-web.service"
-
-    # Optional: journalctl (non-critical — skip if not found)
-    #
-    # NOEXEC, matching first_time_install.sh. These rules end in a wildcard and
-    # journalctl starts a pager, so without it the caller can reach a shell:
-    # less runs "!command" as the user the pager belongs to, which here is
-    # root. NOEXEC stops the granted command executing anything of its own.
-    if [ -n "$JOURNALCTL_PATH" ]; then
-        echo "$WEB_USER ALL=(ALL) NOPASSWD:NOEXEC: $JOURNALCTL_PATH -u ledmatrix.service *"
-        echo "$WEB_USER ALL=(ALL) NOPASSWD:NOEXEC: $JOURNALCTL_PATH -u ledmatrix *"
-        echo "$WEB_USER ALL=(ALL) NOPASSWD:NOEXEC: $JOURNALCTL_PATH -t ledmatrix *"
-    fi
-
-    echo ""
-    echo "# Allow web user to remove plugin directories via vetted helper script"
-    echo "# The helper validates that the target path resolves inside plugin-repos/ or plugins/"
-    echo "$WEB_USER ALL=(ALL) NOPASSWD: $BASH_PATH $SAFE_RM_PATH *"
-    echo ""
-    echo "# Allow web user to install a plugin's requirements.txt as root via vetted"
-    echo "# helper script, so packages are visible to root-run ledmatrix.service"
-    echo "# (not just the web interface's own user). The helper validates the target"
-    echo "# is requirements.txt at the project root or under plugin-repos/ or plugins/."
-    echo "$WEB_USER ALL=(ALL) NOPASSWD: $BASH_PATH $SAFE_PIP_INSTALL_PATH *"
-} > "$TEMP_SUDOERS"
+web_sudoers_rules "$WEB_USER" "$PROJECT_ROOT" "$SYSTEMCTL_PATH" "$BASH_PATH" \
+    "$REBOOT_PATH" "$POWEROFF_PATH" "$JOURNALCTL_PATH" > "$TEMP_SUDOERS"
 
 # Never offer to install rules we have not parsed. A malformed drop-in in
 # /etc/sudoers.d makes sudo refuse every command for every user.
+# visudo lives in /usr/sbin, which is not on every user's PATH.
+if ! command -v visudo >/dev/null 2>&1 && [ -x /usr/sbin/visudo ]; then
+    PATH="$PATH:/usr/sbin"
+fi
 if command -v visudo >/dev/null 2>&1; then
     if ! visudo -c -f "$TEMP_SUDOERS" >/dev/null 2>&1; then
         echo ""
@@ -134,6 +119,8 @@ if command -v visudo >/dev/null 2>&1; then
         rm -f "$TEMP_SUDOERS"
         exit 1
     fi
+else
+    echo "⚠ visudo not found; the rules below have not been validated"
 fi
 
 echo ""
@@ -151,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
@@ -162,7 +151,7 @@ if [[ ! $REPLY =~ ^[Yy]$ ]]; then
     exit 0
 fi
 
-# Apply the configuration using visudo
+# Apply the configuration
 echo "Applying sudoers configuration..."
 # Harden the helper script: root-owned, not writable by web user
 echo "Hardening safe_plugin_rm.sh ownership..."
@@ -181,21 +170,29 @@ if ! sudo chmod 755 "$SAFE_PIP_INSTALL_PATH"; then
 fi
 
 if sudo cp "$TEMP_SUDOERS" /etc/sudoers.d/ledmatrix_web; then
+    # sudo reads /etc/sudoers.d files that are root-owned and not writable by
+    # group or other; 440 is the mode visudo and first_time_install.sh use.
+    if ! sudo chmod 440 /etc/sudoers.d/ledmatrix_web; then
+        echo "Warning: could not set mode 440 on /etc/sudoers.d/ledmatrix_web"
+    fi
     echo "Configuration applied successfully!"
     echo ""
     echo "Testing sudo access..."
     
-    # Test a few commands
-    if sudo -n systemctl status ledmatrix.service > /dev/null 2>&1; then
+    # Ask sudo whether two of the new rules let this user in without a
+    # password. `sudo -l CMD` answers from the rules without running CMD, so
+    # this does not depend on whether ledmatrix.service is running, and it
+    # tests commands the rules actually grant.
+    if sudo -n -l "$SYSTEMCTL_PATH" status ledmatrix.service > /dev/null 2>&1; then
         echo "✓ systemctl status ledmatrix.service - OK"
     else
-        echo "✗ systemctl status ledmatrix.service - Failed"
+        echo "✗ systemctl status ledmatrix.service - not allowed without a password"
     fi
-    
-    if sudo -n test -f "$PROJECT_ROOT/start_display.sh"; then
-        echo "✓ File access test - OK"
+
+    if sudo -n -l "$BASH_PATH" "$SAFE_RM_PATH" "$PROJECT_ROOT/plugin-repos/example" > /dev/null 2>&1; then
+        echo "✓ safe_plugin_rm.sh helper - OK"
     else
-        echo "✗ File access test - Failed"
+        echo "✗ safe_plugin_rm.sh helper - not allowed without a password"
     fi
     
     echo ""

scripts/install/configure_wifi_permissions.sh

@@ -144,6 +144,11 @@ $WEB_USER ALL=(ALL) NOPASSWD: $MKDIR_PATH -p /etc/NetworkManager/dnsmasq-shared.
 $WEB_USER ALL=(ALL) NOPASSWD: /usr/bin/cp /tmp/hostapd.conf /etc/hostapd/hostapd.conf
 $WEB_USER ALL=(ALL) NOPASSWD: /usr/bin/cp /tmp/dnsmasq.conf /etc/dnsmasq.d/ledmatrix-captive.conf
 $WEB_USER ALL=(ALL) NOPASSWD: /usr/bin/rm -f /etc/dnsmasq.d/ledmatrix-captive.conf
+# The same captive-portal DNS drop-in for NetworkManager's shared-mode dnsmasq
+# (wifi_manager._write_nm_dnsmasq_captive_conf / _remove_nm_dnsmasq_captive_conf),
+# exact paths.
+$WEB_USER ALL=(ALL) NOPASSWD: /usr/bin/cp /tmp/ledmatrix-nm-dnsmasq.conf /etc/NetworkManager/dnsmasq-shared.d/ledmatrix-captive.conf
+$WEB_USER ALL=(ALL) NOPASSWD: /usr/bin/rm -f /etc/NetworkManager/dnsmasq-shared.d/ledmatrix-captive.conf
 EOF
 
 echo "Generated sudoers configuration:"
@@ -151,6 +156,21 @@ echo "--------------------------------"
 cat "$TEMP_SUDOERS"
 echo "--------------------------------"
 
+# Never install rules we have not parsed. A malformed drop-in in
+# /etc/sudoers.d makes sudo refuse every command for every user, which on a
+# headless Pi leaves no way in at all. first_time_install.sh and
+# configure_web_sudo.sh check their rules the same way.
+if command -v visudo >/dev/null 2>&1; then
+    if ! visudo -c -f "$TEMP_SUDOERS" >/dev/null 2>&1; then
+        echo "✗ The generated sudoers rules did not parse:" >&2
+        visudo -c -f "$TEMP_SUDOERS" >&2 || true
+        echo "  Leaving $SUDOERS_FILE unchanged." >&2
+        exit 1
+    fi
+else
+    echo "⚠ visudo not found; installing the sudoers rules unvalidated"
+fi
+
 # Apply the sudoers configuration
 echo ""
 echo "Applying sudoers configuration..."
@@ -213,11 +233,14 @@ rm -f "$TEMP_POLKIT"
 echo ""
 echo "Step 3: Testing permissions..."
 
-# Test sudo access
-if sudo -n "$NMCLI_PATH" device status > /dev/null 2>&1; then
-    echo "✓ nmcli device status - OK"
+# Ask sudo whether one of the new rules lets this user in without a password.
+# `sudo -l CMD` answers from the rules without running CMD, so the radio is
+# left alone. (This used to run `nmcli device status`, which is not granted,
+# so it could only ever report a failure.)
+if sudo -n -l "$NMCLI_PATH" radio wifi on > /dev/null 2>&1; then
+    echo "✓ nmcli radio wifi on - OK"
 else
-    echo "✗ nmcli device status - Failed (this is expected if not connected)"
+    echo "✗ nmcli radio wifi on - not allowed without a password"
 fi
 
 echo ""

scripts/install/install_dns_fix.sh

@@ -10,6 +10,10 @@
 set -e
 
 PROJECT_ROOT_DIR=$(cd "$(dirname "$0")/../.." && pwd)
+
+# shellcheck source=scripts/install/lib_systemd_render.sh
+source "$PROJECT_ROOT_DIR/scripts/install/lib_systemd_render.sh"
+
 SERVICE_NAME="ledmatrix-dns-fix"
 UNIT_SRC="$PROJECT_ROOT_DIR/systemd/$SERVICE_NAME.service"
 UNIT_DEST="/etc/systemd/system/$SERVICE_NAME.service"
@@ -34,7 +38,8 @@ fi
 chmod +x "$PROJECT_ROOT_DIR/scripts/utils/apply_dns_single_request.sh"
 
 echo "Installing $UNIT_DEST..."
-sed "s|__PROJECT_ROOT_DIR__|$PROJECT_ROOT_DIR|g" "$UNIT_SRC" \
+ESCAPED_PROJECT_ROOT_DIR=$(sed_escape_replacement "$PROJECT_ROOT_DIR")
+sed "s|__PROJECT_ROOT_DIR__|$ESCAPED_PROJECT_ROOT_DIR|g" "$UNIT_SRC" \
     | $SUDO tee "$UNIT_DEST" > /dev/null
 
 # Order ledmatrix.service after the fix. `Before=` in the unit itself only

scripts/install/install_mqtt_bridge.sh

@@ -9,6 +9,10 @@
 set -e
 
 PROJECT_ROOT_DIR=$(cd "$(dirname "$0")/../.." && pwd)
+
+# shellcheck source=scripts/install/lib_systemd_render.sh
+source "$PROJECT_ROOT_DIR/scripts/install/lib_systemd_render.sh"
+
 BRIDGE_DIR="$PROJECT_ROOT_DIR/integrations/mqtt_bridge"
 SERVICE_NAME="ledmatrix-mqtt-bridge"
 UNIT_SRC="$PROJECT_ROOT_DIR/systemd/$SERVICE_NAME.service"
@@ -40,7 +44,8 @@ python3 -m pip install -r "$BRIDGE_DIR/requirements.txt" 2>/dev/null \
     || python3 -m pip install --break-system-packages -r "$BRIDGE_DIR/requirements.txt"
 
 echo "Installing $UNIT_DEST..."
-sed "s|__PROJECT_ROOT_DIR__|$PROJECT_ROOT_DIR|g" "$UNIT_SRC" \
+ESCAPED_PROJECT_ROOT_DIR=$(sed_escape_replacement "$PROJECT_ROOT_DIR")
+sed "s|__PROJECT_ROOT_DIR__|$ESCAPED_PROJECT_ROOT_DIR|g" "$UNIT_SRC" \
     | $SUDO tee "$UNIT_DEST" > /dev/null
 
 $SYSTEMCTL_CMD daemon-reload

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/install_wifi_monitor.sh

@@ -51,20 +51,25 @@ if [ ${#MISSING_PACKAGES[@]} -gt 0 ]; then
     
     # Install packages automatically (no prompt)
     # Use apt directly if running as root, otherwise use sudo
+    PACKAGES_OK=true
     if [ "$EUID" -eq 0 ]; then
         apt update || echo "⚠ apt update failed, continuing anyway..."
         apt install -y "${MISSING_PACKAGES[@]}" || {
+            PACKAGES_OK=false
             echo "⚠ Package installation failed, but continuing with WiFi monitor setup"
             echo "  You may need to install packages manually: apt install -y ${MISSING_PACKAGES[*]}"
         }
     else
         sudo apt update || echo "⚠ apt update failed, continuing anyway..."
         sudo apt install -y "${MISSING_PACKAGES[@]}" || {
+            PACKAGES_OK=false
             echo "⚠ Package installation failed, but continuing with WiFi monitor setup"
             echo "  You may need to install packages manually: sudo apt install -y ${MISSING_PACKAGES[*]}"
         }
     fi
-    echo "✓ Package installation completed"
+    if [ "$PACKAGES_OK" = true ]; then
+        echo "✓ Package installation completed"
+    fi
 fi
 
 # Render the unit from systemd/ledmatrix-wifi-monitor.service rather than

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

@@ -0,0 +1,85 @@
+#!/bin/bash
+#
+# The web interface's passwordless-sudo allow-list, /etc/sudoers.d/ledmatrix_web.
+#
+# Sourced by first_time_install.sh (Step 10) and
+# scripts/install/configure_web_sudo.sh. Both used to carry their own copy of
+# these rules, and the copies drifted: one granted safe_pip_install.sh and the
+# other did not. Each caller still owns its own validate (visudo -c) / install /
+# confirm flow; this file only prints the rules.
+#
+# 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.
+#
+# SYSTEMCTL_PATH and BASH_PATH are required, and the caller must make sure they
+# are not empty: `visudo -c` does not catch every such rule (with an empty
+# BASH_PATH the helper rules still parse, granting the script itself).
+# first_time_install.sh stops on a failed `which`; configure_web_sudo.sh checks
+# them before calling this.
+# REBOOT_PATH, POWEROFF_PATH and JOURNALCTL_PATH are optional: pass "" and
+# their rules are left out.
+web_sudoers_rules() {
+    local WEB_USER="${1:-}"
+    local PROJECT_ROOT="${2:-}"
+    local SYSTEMCTL_PATH="${3:-}"
+    local BASH_PATH="${4:-}"
+    local REBOOT_PATH="${5:-}"
+    local POWEROFF_PATH="${6:-}"
+    local JOURNALCTL_PATH="${7:-}"
+
+    cat << EOF
+# LED Matrix Web Interface passwordless sudo configuration
+# This allows the web interface user to run specific commands without a password
+
+# Allow $WEB_USER to run specific commands without a password for the LED Matrix web interface
+EOF
+    if [ -n "$REBOOT_PATH" ]; then
+        printf '%s\n' "$WEB_USER ALL=(ALL) NOPASSWD: $REBOOT_PATH"
+    fi
+    if [ -n "$POWEROFF_PATH" ]; then
+        printf '%s\n' "$WEB_USER ALL=(ALL) NOPASSWD: $POWEROFF_PATH"
+    fi
+    cat << EOF
+$WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH start ledmatrix.service
+$WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH stop ledmatrix.service
+$WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH restart ledmatrix.service
+$WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH enable ledmatrix.service
+$WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH disable ledmatrix.service
+$WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH status ledmatrix.service
+$WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH is-active ledmatrix
+$WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH is-active ledmatrix.service
+$WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH start ledmatrix-web.service
+$WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH stop ledmatrix-web.service
+$WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH restart ledmatrix-web.service
+$WEB_USER ALL=(ALL) NOPASSWD: $BASH_PATH $PROJECT_ROOT/scripts/fix_perms/safe_plugin_rm.sh *
+# 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
+# NOEXEC, because these rules end in a wildcard and journalctl starts a pager
+# when its output is a terminal. From that pager (less) a "!sh" is a root
+# shell -- the standard journalctl escalation. The web interface always passes
+# --no-pager, so nothing here needs it, but the rule cannot require a flag that
+# sits in the middle of the command line. NOEXEC stops the command executing
+# another program at all, which closes the hole without depending on wildcard
+# matching subtleties.
+$WEB_USER ALL=(ALL) NOPASSWD:NOEXEC: $JOURNALCTL_PATH -u ledmatrix.service *
+$WEB_USER ALL=(ALL) NOPASSWD:NOEXEC: $JOURNALCTL_PATH -u ledmatrix *
+$WEB_USER ALL=(ALL) NOPASSWD:NOEXEC: $JOURNALCTL_PATH -t ledmatrix *
+EOF
+    fi
+}

scripts/install/lib_systemd_render.sh

@@ -2,9 +2,10 @@
 #
 # Shared helper for rendering systemd unit templates via sed.
 #
-# Sourced by install_service.sh, install_web_service.sh and
-# install_wifi_monitor.sh so all three escape sed replacement text the same
-# way instead of carrying three copies of the same fix.
+# Sourced by install_service.sh, install_web_service.sh,
+# install_wifi_monitor.sh, install_dns_fix.sh and install_mqtt_bridge.sh so
+# every unit renderer escapes sed replacement text the same way instead of
+# carrying its own copy of the fix.
 
 # sed_escape_replacement VALUE
 #

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,27 +209,114 @@ check_sudo() {
     print_success "Sudo access confirmed"
 }
 
-# Fix /tmp permissions if needed (common issue when running via curl | bash)
-# Note: /tmp permission fixing is now done inline before running first_time_install.sh
-# This function is kept for backward compatibility but not actively used
-fix_tmp_permissions() {
-    CURRENT_STEP="TMP directory check"
-    # Only fix if /tmp is actually not writable (don't preemptively fix)
-    if [ ! -w /tmp ]; then
-        print_warning "/tmp is not writable, attempting to fix..."
-        if [ "$EUID" -eq 0 ]; then
-            chmod 1777 /tmp 2>/dev/null || true
-        else
-            sudo chmod 1777 /tmp 2>/dev/null || true
+# --- 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
-    
-    # Ensure TMPDIR is set correctly
-    if [ -z "${TMPDIR:-}" ] || [ ! -w "${TMPDIR:-/tmp}" ]; then
-        export TMPDIR=/tmp
-    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"
@@ -313,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
@@ -344,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
@@ -418,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=$?
@@ -429,6 +526,13 @@ main() {
         print_step "Installation Complete!"
         print_success "LED Matrix has been successfully installed!"
         echo ""
+        # first_time_install.sh -y reboots as its last action, so by now the
+        # reboot is under way (unless LEDMATRIX_SKIP_REBOOT_PROMPT=1 was set).
+        if [ "${LEDMATRIX_SKIP_REBOOT_PROMPT:-0}" != "1" ]; then
+            echo "The installer has just started a reboot to finish setup, so this"
+            echo "session may disconnect now. Give the Pi a few minutes to come back, then:"
+            echo ""
+        fi
         echo "Next steps:"
         echo "  1. Configure your settings: sudo nano $REPO_DIR/config/config.json"
         if command -v hostname >/dev/null 2>&1; then
@@ -449,7 +553,7 @@ main() {
         else
             echo "  2. Or use the web interface: http://<your-pi-ip>:5000"
         fi
-        echo "  3. Start the service: sudo systemctl start ledmatrix.service"
+        echo "  3. The display service starts on boot; to start it by hand: sudo systemctl start ledmatrix.service"
         echo ""
     else
         print_error "Main installation script exited with code $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,785 @@
+#!/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"),
+    "PluginStateManager": ("state_manager", "plugin_state", "state_mgr"),
+    "ConfigManager": ("config_manager", "config_mgr", "configmanager"),
+    "LogoDownloader": ("logo_downloader", "downloader", "logodownloader"),
+    "APIHelper": ("api_helper", "apihelper", "api"),
+    "BackgroundDataService": ("background_service", "background_data_service", "bg_service",
+                              "data_service"),
+    "BaseOddsManager": ("odds_manager", "oddsmanager", "odds"),
+    "DynamicTeamResolver": ("dynamic_resolver", "team_resolver", "resolver"),
+}
+
+#: 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
+            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

@@ -0,0 +1,590 @@
+#!/usr/bin/env python3
+"""Benchmark the render loop against the panel's real refresh rate.
+
+The question this answers is the one that decides whether a rig ships: *does
+every frame present on the refresh it was meant to?* It drives the production
+path -- a real ``DisplayManager`` and ``ScrollHelper``, the same crisp speed
+resolver every ticker uses -- scrolls a synthetic strip for a while, and grades
+it with the same frame-timing recorder the display service uses
+(``src.common.frame_timing``), printing the same report as
+``scripts/frame_soak.py``. A run passes when the loop was genuinely locked to
+the panel and no more than ``--max-late-pct`` percent of frames were late.
+
+Where frame_soak.py measures the service as it runs -- live content, plugin
+updates, the web preview -- this measures the hardware and the render path
+with nothing else in the way, on content that is identical every run. That is
+what makes it the tool for comparing rigs (a Pi 3 against a Pi 4, one HAT
+against another) and for A/B testing a change to the render path.
+
+    # stop the service first; it owns the GPIO
+    sudo systemctl stop ledmatrix
+
+    sudo python3 scripts/render_bench.py                    # 60s, default speed
+    sudo python3 scripts/render_bench.py --seconds 600      # the 10-minute gate
+    sudo python3 scripts/render_bench.py --speed 50         # a slower, held speed
+    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,
+so a crash here can never leave the panel dark.
+
+Exit status is 0 when the run clears the gate, 1 when it does not, and 2 when
+the run could not be set up (no hardware, no root, unusable config) -- so a rig
+that cannot be measured is never mistaken for a rig that passed.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import sys
+import threading
+import time
+import zlib
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from src.common import frame_timing, scroll_config  # noqa: E402
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import frame_soak  # noqa: E402  (same report, same verdict as the soak)
+
+REPO = Path(__file__).resolve().parent.parent
+CONFIG = REPO / "config" / "config.json"
+
+#: Long enough to average out a scheduler hiccup, short enough that nobody
+#: skips running it. The shipping gate is --seconds 600.
+DEFAULT_SECONDS = 60.0
+
+#: Seconds spent timing bare swaps before the scroll starts. The measurement
+#: has to settle, but every second here is a second not scrolling.
+MEASURE_SECONDS = 4.0
+
+#: Scrolling discarded before the graded run starts: the first frames carry
+#: first-touch costs and the scrolling state settling.
+WARMUP_SECONDS = 2.0
+
+
+def load_config() -> dict:
+    """The config the display service would run with."""
+    try:
+        from src.config_manager import ConfigManager
+
+        config = ConfigManager().config
+        if isinstance(config, dict) and config:
+            return config
+    except Exception as exc:  # noqa: BLE001 - any failure means use the plain read
+        print(f"ConfigManager unavailable ({exc}); reading {CONFIG} directly",
+              file=sys.stderr)
+    # ConfigManager pulls in a lot; a plain read is enough to drive the panel
+    # and keeps the benchmark usable on a half-installed machine.
+    try:
+        with open(CONFIG, encoding="utf-8") as handle:
+            config = json.load(handle)
+    except (OSError, ValueError) as exc:
+        sys.exit(f"could not read {CONFIG}: {exc}")
+    if not isinstance(config, dict):
+        sys.exit(f"{CONFIG} is not a config object")
+    return config
+
+
+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
+
+    from src.common.font_layout import load_truetype
+
+    font = None
+    for path, size in (
+        (str(REPO / "assets/fonts/PressStart2P-Regular.ttf"), max(8, height // 4)),
+        ("/usr/share/fonts/truetype/dejavu/DejaVuSansMono-Bold.ttf", max(10, height // 2)),
+    ):
+        try:
+            font = load_truetype(path, size)
+            break
+        except OSError:
+            continue
+    if font is None:
+        font = ImageFont.load_default()
+
+    text = f"  {label}  ***  THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG  ***  "
+    probe = ImageDraw.Draw(Image.new("RGB", (8, 8)))
+    box = probe.textbbox((0, 0), text, font=font)
+    text_width = max(1, box[2] - box[0])
+    text_height = box[3] - box[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
+    palette = [(255, 210, 60), (80, 200, 255), (255, 90, 90), (140, 255, 140)]
+    for i in range(reps):
+        left = i * text_width
+        # A filled block per repeat, so a meaningful share of the strip is lit.
+        draw.rectangle(
+            [left + 4, height - 4, left + text_width - 4, height - 2],
+            fill=palette[i % len(palette)],
+        )
+        draw.text((left, (height - text_height) // 2 - box[1]), text,
+                  font=font, fill=palette[(i + 1) % len(palette)])
+    return strip
+
+
+class BackgroundLoad:
+    """Threads that imitate plugins updating while the panel scrolls.
+
+    Not a simulation of any particular plugin -- it is the shape of the work
+    that competes with the render loop for the GIL: decoding JSON, resizing an
+    image, compressing bytes. A render loop that only holds its pacing on an
+    idle machine is not shippable, and this is how that shows up.
+    """
+
+    def __init__(self, workers: int) -> None:
+        self.workers = max(0, workers)
+        self._stop = threading.Event()
+        self._threads: list = []
+
+    def __enter__(self) -> "BackgroundLoad":
+        for index in range(self.workers):
+            thread = threading.Thread(
+                target=self._run, args=(index,), name=f"bench-load-{index}", daemon=True)
+            thread.start()
+            self._threads.append(thread)
+        return self
+
+    def __exit__(self, *exc_info) -> None:
+        self._stop.set()
+        for thread in self._threads:
+            thread.join(timeout=2.0)
+
+    def _run(self, index: int) -> None:
+        from PIL import Image
+
+        payload = json.dumps({"games": [{"id": n, "score": [n, n + 1],
+                                         "name": f"team {n}"} for n in range(200)]})
+        image = Image.new("RGB", (256, 64), (12, 34, 56))
+        while not self._stop.wait(0.25 + 0.05 * index):
+            json.loads(payload)
+            image.resize((128, 32), Image.LANCZOS)
+            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(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--seconds", type=float, default=DEFAULT_SECONDS,
+                        help=f"how long to scroll for (default {DEFAULT_SECONDS:.0f}; "
+                             "the shipping gate is 600)")
+    parser.add_argument("--speed", type=float, default=None,
+                        help="requested px/s; snapped to the nearest speed the "
+                             "panel can show in whole pixels (default: one pixel "
+                             "per refresh)")
+    parser.add_argument("--hz", type=float, default=None,
+                        help="skip the idle measurement and take this as the "
+                             "panel's rate (for reproducing a rig's numbers)")
+    parser.add_argument("--busy", type=int, default=0, metavar="N",
+                        help="run N background workers imitating plugin updates")
+    parser.add_argument("--max-late-pct", "--max-missed", dest="max_late_pct",
+                        type=float, default=0.1, metavar="PCT",
+                        help="fail above this percentage of late frames (default 0.1)")
+    parser.add_argument("--json", dest="json_path", default=None, metavar="PATH",
+                        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.
+    logging.basicConfig(level=logging.ERROR, stream=sys.stderr)
+    logging.getLogger("src.common.frame_timing").setLevel(logging.WARNING)
+
+    if hasattr(os, "geteuid") and os.geteuid() != 0:
+        print("this needs root for GPIO access - rerun with sudo", file=sys.stderr)
+        return 2
+
+    config = load_config()
+
+    from src.common.scroll_helper import ScrollHelper
+    from src.display_manager import DisplayManager
+
+    try:
+        display = DisplayManager(config, suppress_test_pattern=True)
+    except Exception as exc:
+        print(f"could not open the display ({exc}).\n"
+              "If the display service is running it owns the GPIO - stop it "
+              "first:\n    sudo systemctl stop ledmatrix", file=sys.stderr)
+        return 2
+
+    if getattr(display, "matrix", None) is None:
+        print("the display came up in fallback mode - there is no panel here to "
+              "measure, and a software loop's frame times say nothing about "
+              "vsync. Run this on a rig.", file=sys.stderr)
+        return 2
+
+    width, height = display.width, display.height
+
+    if args.hz is not None:
+        idle_hz = float(args.hz)
+        print(f"taking the panel's rate as {idle_hz:.1f}Hz (given, not measured)")
+    else:
+        print(f"measuring the panel for {MEASURE_SECONDS:.0f}s...", flush=True)
+        idle_hz = frame_timing.measure_refresh_hz(display.matrix, MEASURE_SECONDS)
+        if idle_hz <= 0:
+            print("the panel did not answer a swap; cannot measure it",
+                  file=sys.stderr)
+            return 2
+        cap = scroll_config.refresh_hz_from_config(config)
+        note = (f" (cap is {cap:.0f}Hz)" if idle_hz < cap * 0.98
+                else " (at its configured cap)")
+        print(f"panel refreshes at {idle_hz:.1f}Hz{note}")
+
+    requested = args.speed if args.speed else idle_hz
+
+    # Configured through the shared resolver rather than by setting the helper
+    # up by hand, so the benchmark measures the engine every ticker runs on. A
+    # speed the bench reached some other way would be measuring something no
+    # plugin does.
+    helper = ScrollHelper(width, height)
+    settings = scroll_config.configure(
+        helper,
+        plugin_config={"scroll_pixels_per_second": requested},
+        global_config=config,
+        refresh_hz=idle_hz,
+        display_manager=display,
+    )
+    choice = settings.crisp
+    if choice is None:
+        print("the resolver did not snap to a whole-pixel speed; nothing to "
+              "grade against", file=sys.stderr)
+        return 2
+    print(f"asked for {requested:.1f} px/s -> {choice.describe()}")
+
+    helper.set_sub_pixel_scrolling(False)
+    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
+    # graded run, and seeded with the idle rate so a loop that never locked
+    # (free-running, or stuck at a fraction of the refresh) shows as early or
+    # late frames instead of looking self-consistent.
+    recorder = frame_timing.FrameTimingRecorder(
+        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
+
+    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
+    duplicates = 0
+    blanks = 0
+    restarts = 0
+    last_column = None
+    before = None
+    started = time.perf_counter()
+    run_started = None
+    try:
+        with BackgroundLoad(args.busy):
+            while True:
+                now = time.perf_counter()
+                if run_started is None and now - started >= WARMUP_SECONDS:
+                    recorder.drain()
+                    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
+                    # advancing, exactly as it does under a plugin -- which
+                    # then hands over to the next one. Here there is nothing
+                    # to hand over to, so start the strip again. Without this
+                    # 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)
+                if column == last_column:
+                    duplicates += 1
+                last_column = column
+                if visible is None:
+                    blanks += 1
+                else:
+                    display.image.paste(visible, (0, 0))
+                # Every frame, not once before the loop. The scrolling state
+                # expires on its own inactivity threshold and takes the frame
+                # hold with it, so a scroll that announces itself once is
+                # presented at the wrong rate for all but its first moments --
+                # and its unchanged frames start taking the dirty-tracking
+                # skip, which returns without waiting for the panel at all.
+                # Every ticker re-announces per frame; so does this.
+                display.set_scrolling_state(True, frame_hold=choice.frame_hold)
+                display.update_display()
+                frames += 1
+    except KeyboardInterrupt:
+        print("\ninterrupted - reporting what was measured so far")
+    finally:
+        display.set_scrolling_state(False)
+        try:
+            display.clear()
+        except Exception as exc:  # noqa: BLE001 - a lit panel is harmless; say so and go on
+            print(f"could not blank the panel: {exc}", file=sys.stderr)
+
+    if before is None:
+        print("interrupted during warm-up; nothing was graded", file=sys.stderr)
+        return 2
+    recorder.drain()
+    report = frame_soak.build_report(before, recorder.snapshot(), preview=False)
+    report["idle_refresh_hz"] = round(idle_hz, 2)
+
+    print()
+    frame_soak.print_report(report, args.max_late_pct)
+    held = report.get("held_refresh_hz")
+    if held:
+        drop = 100.0 * (idle_hz - held) / idle_hz
+        print(f"\npanel held ~{held:.1f}Hz while rendering, {drop:.1f}% below its "
+              f"{idle_hz:.1f}Hz idle rate (a widening gap is a render-cost "
+              "regression even with nothing late)")
+    if duplicates:
+        # A frame that shows the same columns as the one before it is work the
+        # panel did not need. It is not a miss -- the frame arrived on time --
+        # but it means the loop is presenting faster than the strip is moving.
+        print(f"duplicate   {duplicates} frames advanced no pixels "
+              f"({100.0 * duplicates / max(1, frames):.2f}%)")
+    if blanks:
+        print(f"blank       {blanks} frames had no visible slice to draw")
+    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({
+            "label": args.label or os.uname().nodename,
+            "bench": True,
+            "requested_pixels_per_second": requested,
+            "pixels_per_second": choice.pixels_per_second,
+            "pixels_per_frame": choice.pixels_per_frame,
+            "frame_hold": choice.frame_hold,
+            "busy_workers": args.busy,
+            "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),
+        })
+        Path(args.json_path).write_text(json.dumps(report, indent=2) + "\n",
+                                        encoding="utf-8")
+        print(f"\nwrote {args.json_path}")
+
+    if report["late_pct"] is None:
+        return 2
+    return 0 if frame_soak.passed(report, args.max_late_pct) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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/run_plugin_tests.py

@@ -299,6 +299,5 @@ def main():
 
 if __name__ == '__main__':
     import importlib.util
-    from typing import Optional
     sys.exit(main())
 

scripts/scroll_speeds.py

@@ -42,7 +42,7 @@ from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 
-from src.common import scroll_config  # noqa: E402
+from src.common import frame_timing, scroll_config  # noqa: E402
 
 CONFIG = Path(__file__).resolve().parent.parent / "config" / "config.json"
 
@@ -99,20 +99,13 @@ def open_matrix(config, refresh_override=None):
 def measure_refresh(config, seconds=6.0):
     """Actual refresh rate, by running uncapped and timing the swaps.
 
-    SwapOnVSync blocks until the panel's next refresh, so an unthrottled loop
-    runs at exactly the panel's rate. This is what an older Pi or a longer
-    chain will really give you, as opposed to whatever limit_refresh_rate_hz
-    optimistically asks for.
+    What an older Pi or a longer chain will really give you, as opposed to
+    whatever limit_refresh_rate_hz optimistically asks for. The timing loop
+    itself lives in src.common.frame_timing so the benchmark grades against
+    the same measurement this ladder is built from.
     """
     matrix = open_matrix(config, refresh_override=0)
-    canvas = matrix.CreateFrameCanvas()
-    canvas = matrix.SwapOnVSync(canvas)  # discard the first, it includes setup
-    frames = 0
-    started = time.perf_counter()
-    while time.perf_counter() - started < seconds:
-        canvas = matrix.SwapOnVSync(canvas)
-        frames += 1
-    measured = frames / (time.perf_counter() - started)
+    measured = frame_timing.measure_refresh_hz(matrix, seconds)
     matrix.Clear()
     return measured
 

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/test_captive_portal.sh

@@ -1,149 +0,0 @@
-#!/bin/bash
-
-# Test script for captive portal functionality
-# This script tests the captive portal from a device connected to the AP network
-
-set -e
-
-PI_IP="192.168.4.1"
-PI_PORT="5000"
-BASE_URL="http://${PI_IP}:${PI_PORT}"
-
-echo "=========================================="
-echo "Captive Portal Functionality Test"
-echo "=========================================="
-echo ""
-echo "Make sure you're connected to 'LEDMatrix-Setup' network"
-echo "Pi IP: ${PI_IP}"
-echo "Web Interface Port: ${PI_PORT}"
-echo ""
-
-# Colors for output
-GREEN='\033[0;32m'
-RED='\033[0;31m'
-YELLOW='\033[1;33m'
-NC='\033[0m' # No Color
-
-# Test counter
-PASSED=0
-FAILED=0
-
-test_result() {
-    if [ $1 -eq 0 ]; then
-        echo -e "${GREEN}✓${NC} $2"
-        ((PASSED++))
-    else
-        echo -e "${RED}✗${NC} $2"
-        ((FAILED++))
-    fi
-}
-
-# Test 1: Check if Pi is reachable
-echo "1. Testing Pi connectivity..."
-if ping -c 1 -W 2 ${PI_IP} > /dev/null 2>&1; then
-    test_result 0 "Pi is reachable at ${PI_IP}"
-else
-    test_result 1 "Pi is NOT reachable at ${PI_IP}"
-    echo "   Make sure you're connected to LEDMatrix-Setup network"
-    exit 1
-fi
-
-# Test 2: DNS Redirection
-echo ""
-echo "2. Testing DNS redirection..."
-DNS_RESULT=$(nslookup google.com 2>/dev/null | grep -i "address" | tail -1 | awk '{print $2}')
-if [ "$DNS_RESULT" = "${PI_IP}" ]; then
-    test_result 0 "DNS redirection works (google.com resolves to ${PI_IP})"
-else
-    test_result 1 "DNS redirection failed (got ${DNS_RESULT}, expected ${PI_IP})"
-fi
-
-# Test 3: HTTP Redirect
-echo ""
-echo "3. Testing HTTP redirect..."
-HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" -L --max-time 5 "${BASE_URL}/google.com" 2>/dev/null || echo "000")
-if [ "$HTTP_CODE" = "200" ]; then
-    test_result 0 "HTTP redirect works (got 200, redirected to setup page)"
-else
-    test_result 1 "HTTP redirect failed (got ${HTTP_CODE})"
-fi
-
-# Test 4: Captive Portal Detection Endpoints
-echo ""
-echo "4. Testing captive portal detection endpoints..."
-
-# iOS/macOS
-IOS_RESPONSE=$(curl -s --max-time 5 "${BASE_URL}/hotspot-detect.html" 2>/dev/null || echo "")
-if echo "$IOS_RESPONSE" | grep -qi "success"; then
-    test_result 0 "iOS/macOS endpoint works"
-else
-    test_result 1 "iOS/macOS endpoint failed"
-fi
-
-# Android
-ANDROID_CODE=$(curl -s -o /dev/null -w "%{http_code}" --max-time 5 "${BASE_URL}/generate_204" 2>/dev/null || echo "000")
-if [ "$ANDROID_CODE" = "204" ]; then
-    test_result 0 "Android endpoint works"
-else
-    test_result 1 "Android endpoint failed (got ${ANDROID_CODE})"
-fi
-
-# Windows
-WIN_RESPONSE=$(curl -s --max-time 5 "${BASE_URL}/connecttest.txt" 2>/dev/null || echo "")
-if echo "$WIN_RESPONSE" | grep -qi "microsoft"; then
-    test_result 0 "Windows endpoint works"
-else
-    test_result 1 "Windows endpoint failed"
-fi
-
-# Firefox
-FF_RESPONSE=$(curl -s --max-time 5 "${BASE_URL}/success.txt" 2>/dev/null || echo "")
-if echo "$FF_RESPONSE" | grep -qi "success"; then
-    test_result 0 "Firefox endpoint works"
-else
-    test_result 1 "Firefox endpoint failed"
-fi
-
-# Test 5: API Endpoints (should NOT redirect)
-echo ""
-echo "5. Testing API endpoints (should work normally)..."
-API_RESPONSE=$(curl -s --max-time 5 "${BASE_URL}/api/v3/wifi/status" 2>/dev/null || echo "")
-if echo "$API_RESPONSE" | grep -qi "status"; then
-    test_result 0 "API endpoints work (not redirected)"
-else
-    test_result 1 "API endpoints failed or were redirected"
-fi
-
-# Test 6: Main Interface (should be accessible)
-echo ""
-echo "6. Testing main interface accessibility..."
-MAIN_CODE=$(curl -s -o /dev/null -w "%{http_code}" --max-time 5 "${BASE_URL}/v3" 2>/dev/null || echo "000")
-if [ "$MAIN_CODE" = "200" ]; then
-    test_result 0 "Main interface is accessible"
-else
-    test_result 1 "Main interface failed (got ${MAIN_CODE})"
-fi
-
-# Summary
-echo ""
-echo "=========================================="
-echo "Test Summary"
-echo "=========================================="
-echo -e "${GREEN}Passed: ${PASSED}${NC}"
-echo -e "${RED}Failed: ${FAILED}${NC}"
-echo ""
-
-if [ $FAILED -eq 0 ]; then
-    echo -e "${GREEN}All tests passed! Captive portal is working correctly.${NC}"
-    exit 0
-else
-    echo -e "${YELLOW}Some tests failed. Check the output above for details.${NC}"
-    echo ""
-    echo "Troubleshooting tips:"
-    echo "1. Verify AP mode is active: sudo systemctl status hostapd"
-    echo "2. Check dnsmasq config: sudo cat /etc/dnsmasq.conf"
-    echo "3. Check web interface logs: sudo journalctl -u ledmatrix-web -n 50"
-    echo "4. Verify you're connected to LEDMatrix-Setup network"
-    exit 1
-fi
-

scripts/update_plugin_repos.py

@@ -1,43 +0,0 @@
-#!/usr/bin/env python3
-"""
-Update the ledmatrix-plugins monorepo by pulling latest changes.
-"""
-
-import subprocess
-import sys
-from pathlib import Path
-
-MONOREPO_DIR = Path(__file__).parent.parent.parent / "ledmatrix-plugins"
-
-
-def main():
-    if not MONOREPO_DIR.exists():
-        print(f"Error: Monorepo not found: {MONOREPO_DIR}")
-        return 1
-
-    if not (MONOREPO_DIR / ".git").exists():
-        print(f"Error: {MONOREPO_DIR} is not a git repository")
-        return 1
-
-    print(f"Updating {MONOREPO_DIR}...")
-    try:
-        result = subprocess.run(
-            ["git", "-C", str(MONOREPO_DIR), "pull"],
-            capture_output=True,
-            text=True,
-            timeout=120,
-        )
-    except subprocess.TimeoutExpired:
-        print(f"Error: git pull timed out after 120 seconds for {MONOREPO_DIR}")
-        return 1
-
-    if result.returncode == 0:
-        print(result.stdout.strip())
-        return 0
-    else:
-        print(f"Error: {result.stderr.strip()}")
-        return 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())