docs(changelog): complete 3.4.0 with weekly auto-updates and scroll timing fix (#584)

* docs(changelog): complete 3.4.0 with weekly auto-updates and scroll timing fix

#581 (weekly automatic updates) and #582 (scroll frame-stats idle gap)
merged after the 3.4.0 section was written in #580. v3.4.0 will be tagged
on main including both, so they belong in 3.4.0.

Also record src.common.font_layout (#539, #565), a src.* module plugins
may import that shipped in 3.4.0 but was never listed, and mark
display_geometry and auto_update_setup as core-internal.

Correct the 3.3.0 historical note: remote tags v3.3.0 (bc2dbf38) and
v3.3.1 (32d637a4) both report "3.3.0" and both ship sports_shared.py.
The "3.2.0" claim came from a stale local tag.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(changelog): cover the whole 3.4.0 release since v3.3.1

The 3.4.0 section listed plugin-facing API and per-element customization
but not the rest of what merged since v3.3.1. Group it under subheadings:
Install and updates, Scrolling, Plugins, Web interface, Tools and
security, Fixes, and put the existing customization block under its own
heading.

Omitted on purpose: #569 (fixes a regression and an editor race in the
unreleased per-element framework), #570 (no runtime change), and
test-only, refactor and dev-tooling PRs.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

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

.gitignore

@@ -5,6 +5,9 @@ __pycache__/
 
 # 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
@@ -53,3 +56,36 @@ skin_renders/
 # JS test deps (test/js)
 node_modules/
 package-lock.json
+
+# Team logos fetched at runtime.
+#
+# src/logo_downloader.py and LogoHelper write into assets/sports/<league>_logos/
+# whenever a plugin meets a team whose logo is not on disk. Those directories are
+# also tracked -- 209 NCAA logos and 153 soccer ones ship with the repo -- so
+# every rig accumulated untracked files it was never meant to commit and
+# `git status` was permanently dirty. That noise is not harmless: it trains
+# everyone to ignore the one signal that says a checkout is not what you think
+# it is, which is how a stale tree sat unnoticed on a rig until a restart
+# surfaced four dead sports plugins.
+#
+# Ignoring a directory does not untrack what is already in it, so the logos that
+# ship keep shipping. Only new downloads are hidden.
+#
+# Adding a logo on purpose is rare and deliberate -- the last time was #415, four
+# named NCAA logos a plugin needed, and there has been no other in a year. Do it
+# with an explicit override:
+#     git add -f assets/sports/ncaa_logos/DUKE.png
+assets/sports/*_logos/
+assets/stocks/ticker_icons/
+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
+# 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/*
+!data/.gitkeep

CHANGELOG.md

@@ -17,8 +17,260 @@ release that ships it.
 accepts both, but the store flags the old spelling as deprecated
 (`store_manager.py`) and only the new one is in `schema/manifest_schema.json`.
 
+## Unreleased
+
+## 3.4.0
+
+Plugin-facing changes since 3.3.0 (tag `v3.3.1`) not covered further down:
+
+- `BasePlugin.get_update_interval()` (#555) — return seconds to override the
+  manifest's `update_interval` at runtime (e.g. poll fast only while a game is
+  live), or `None` to keep it. Clamped to at least 5 seconds; a raising or
+  non-numeric return is ignored. Called every scheduling tick, so keep it
+  cheap. Older cores never call it. See `docs/PLUGIN_API_REFERENCE.md`.
+- `src.common.scroll_config` (#523) — turns a plugin's scroll config into a
+  configured `ScrollHelper` in one place, replacing per-plugin resolution that
+  disagreed between tickers, and warns when a speed won't advance whole pixels
+  per panel refresh. Floor on 3.4.0 to import it.
+- **Skins are marked unsupported.** No current scoreboard plugin builds on
+  `src.base_classes`, so the skin hook (`SportsCore._render_game`) never runs.
+  The web UI no longer shows the Visual Skin dropdown, the store hides and
+  refuses `"type": "skin"` entries, and `GET /api/v3/skins` reports
+  `"supported": false`. Saved `skin` config values still load and save.
+  `src/skin_system/` is unchanged.
+- **Web preview size** now comes from `src/display_geometry.py`, the same
+  computation `DisplayManager` uses: double-sided setups preview one screen,
+  and a missing `chain_length` defaults to 2 everywhere (the Starlark magnify
+  default and the sync handshake used 1). The module is core-internal: plugins
+  keep reading `display_manager.width`/`height`.
+- `src.common.font_layout` (#539, #565) — `load_truetype()` is
+  `ImageFont.truetype` with the layout engine pinned, so text lays out the same
+  whether or not the host's Pillow was built with libraqm; `crisp_size()` and
+  `FONT_PIXEL_GRID` give the size a bundled face renders on whole pixels at
+  (`sports_card` still re-exports them); `resolve_asset_path()` resolves
+  `assets/fonts/...` against the install root, not the working directory.
+  Floor on 3.4.0 to import it. Relatedly, `DisplayManager` now draws text
+  1-bit (#521), so golden images recorded against 3.3.x may need regenerating.
+
+### Install and updates
+
+**Weekly automatic updates (#581), off by default.** Switching on
+*Automatically check for and install updates once a week* on the General tab
+(or `first_time_install.sh --enable-auto-update` / `LEDMATRIX_AUTO_UPDATE=1`)
+updates the core and then every installed plugin once a week, preferably 2–5 AM
+local time. It follows the branch the checkout tracks — `main` on a standard
+install — so a device gets whatever has merged there, not only tagged releases.
+See `docs/WEB_INTERFACE_GUIDE.md`.
+
+- The core step is skipped, with the reason shown, when the checkout has local
+  edits or commits, a rebase or merge is in progress, the branch has no
+  upstream, less than 300 MB is free, or that commit was already rolled back.
+- After pulling, `ledmatrix-update-verify.service` restarts the services and
+  requires the web interface to answer and the display to stay up. If they
+  don't, or the new requirements fail to install, it resets to the previous
+  commit, reinstalls its requirements and restarts again. Anything but success
+  shows under the toggle and as a banner on Overview.
+- Plugins update through the Plugin Store even when the core step is skipped,
+  fails or is rolled back. A plugin version whose `ledmatrix_min_version` is
+  above the device's core is held back, not installed. When the core did
+  update, plugins wait for its health check, and are left alone if that check
+  never reports or the rollback fails.
+- No SSH is needed: switching the toggle on restarts the display service, which
+  installs the health-check units (`src/auto_update_setup.py`, core-internal
+  and not a plugin API).
+
+Installer and service fixes:
+
+- rgbmatrix builds on ARMv6 boards (Pi Zero, Pi 1); an existing checkout is
+  moved forward to the new pin and no longer left root-owned (#577).
+- `first_time_install.sh` grants the web user `safe_pip_install.sh`, as
+  `configure_web_sudo.sh` already did, so plugin requirements install where
+  the display service can see them (#579).
+- The web interface starts when `web_display_autostart` is missing or
+  `config.json` is unreadable; only an explicit `false` keeps it down (#556).
+- Installers render every systemd unit from its `systemd/` template, so the
+  boot-time unit-drift warning can clear, non-root installs included (#547).
+
+### Scrolling
+
+- **Frame pacing (#523).** The loop waits only for the rest of each panel
+  refresh instead of a flat 8 ms: 44–46 fps → 100 fps, and slow frames 14% →
+  0.02%, on a 2×128×64 chain. Sub-pixel blending is off by default again (it
+  shimmered on pixel fonts; Vegas mode still opts in).
+- **Whole-pixel steps (#545).** At a speed `scroll_config` can render in whole
+  pixels, every frame advances by exactly the same amount, removing about six
+  hitches a second. A loop that can't keep up now scrolls slightly slow rather
+  than jumping.
+- The eight sports scoreboards scroll through `scroll_config` too (#542): the
+  default 50 px/s holds each frame for two refreshes instead of alternating
+  0 px and 1 px steps.
+- **Frame stats ignore the pause between scrolls (#582).** The `Scroll frame
+  stats` log line counted the idle wait before each scroll as one frame,
+  inflating `max` and the stall rate. `docs/SCROLL_PERFORMANCE.md` now
+  describes the line actually logged.
+
+### Plugins
+
+- `FontManager` registers the bundled `tom_thumb` font, so plugins no longer
+  need a private loader (#534).
+- The test harness's `set_scrolling_state()` accepts `frame_hold`, as
+  `DisplayManager`'s does (#534).
+- A `display()` with nothing to draw should return `False`, the only value the
+  controller skips on; starlark-apps now does, rather than holding a black
+  panel (#534).
+- Starlark apps may set `render_width`/`render_height` in their `config.json`
+  to render at their own canvas size instead of Pixlet's 64×32 (#552).
+- `scripts/render_plugin.py --display-mode <mode>` renders one mode of a
+  multi-mode plugin; scoreboards previously rendered blank (#522).
+- Scoreboards resolve their own directory under the real plugin loader
+  (declare `_PLUGIN_DIR`), so 4x6 text snaps to its 7px grid instead of
+  rendering a pixel narrow, and an unreadable schema is logged (#519, #520).
+  `DisplayManager` loads 4x6 on that grid too (#565).
+- The 5x7 BDF face reports a real height, so rows stacked by
+  `get_font_height()` no longer overlap (#539).
+- `LogoHelper` remembers a missing logo instead of warning every rotation
+  (#548), and the decoded sports logo cache is bounded (#559).
+
+### Web interface
+
+- Installed Plugins has search, All / Enabled / Disabled / Updates filters and
+  sort (#540).
+- Hardened and polished per the September 2026 audit (#568): utility classes
+  such as `.hidden` actually exist, focus rings, labels and modal focus
+  trapping, dark theme throughout, no overflow at phone width, and background
+  streams pause when hidden, with first-load JS/CSS down from 1358 KB to 291 KB.
+- WiFi Connect works from the LEDMatrix-Setup hotspot: the page is answered
+  before the hotspot drops, and reopening it shows why an attempt failed (#571).
+- Pixlet install, the Starlark app store and app toggles work again (#535,
+  #537); the store uses the configured GitHub token and reports a rate limit
+  instead of drawing a blank grid (#541).
+- Plugin config: geochron and news saves no longer always fail (#575), the page
+  survives stored values the schema outgrew (#578), the form uses the full page
+  height (#573), and file-manager widgets show the script's error (#574).
+- The live status stream reports real disk usage and available memory (#558);
+  a system action refused for want of passwordless sudo says so and names
+  `configure_web_sudo.sh` (#560).
+
+### Tools and security
+
+- **CodeQL triage (#561):** 129 of 134 alerts fixed. Three were exploitable
+  path-handling flaws in the web interface and are closed; web UI escapers now
+  escape quotes, and URL fields refuse script schemes. Path checks share
+  `src/common/path_safety.py` (core-internal).
+- **Home Assistant MQTT bridge** (`integrations/mqtt_bridge`, #538): mode
+  select, stop, power and brightness over MQTT Discovery.
+- **Tools tab** manages the MQTT bridge and the Pixlet editor (#554); the
+  editor stays on loopback when `PIXLET_EDITOR_HOST` says so.
+
+### Fixes
+
+- Updating a plugin whose directory is named for its manifest id (leaderboard,
+  music, stocks, weather) silently did nothing (#536).
+- Plugin reconciliation no longer reports working plugins as stale or replaces
+  their config with a stub, and the Overview banner advises each case correctly
+  (#557).
+- Two config saves in the same second no longer share one backup, so rollback
+  restores the version asked for (#564).
+- On-demand: a second request is honoured without a restart (#534), a pinned
+  request stays on its mode, and restarting mid-session loads every plugin
+  again (#538).
+- `/health` and `/display/current` report real state, and the preview no longer
+  freezes on a leftover snapshot temp file (#534).
+
+### Per-element display customization
+
+**Per-element display customization, and the last mile of it into the web UI.**
+A user can set the font, size, colour, position, visibility and alignment of
+individual display elements per plugin -- and, where a plugin has display
+modes, separately per mode.
+
+New public API a plugin may import via `src.*` (floor on the release that
+ships this):
+
+- `src.element_style.layout_offset(config, element, axis, default, mode)` and
+  `element_color(config, element, default, mode)` — the stateless reads the
+  scoreboard helpers share. There were three copies of the offset read and two
+  of the colour read; these are the one implementation, and they carry the
+  element-name aliasing and the per-mode lookup.
+- `src.element_style.alias_keys(element)` — the names one element may be stored
+  under. The style block names elements `score_text` while the layout block
+  says `score`, and `records`/`record` and `status_text`/`status` split seven
+  to two across the published schemas. A lookup tries the exact name first, so
+  this is inert for a config that already matches.
+- `src.element_style.element_visible(config, element, default, mode)`,
+  `element_align(...)` and `element_scale(...)` — the stateless reads for the
+  three knobs the resolver already understood but no draw path consumed, so an
+  element could be marked hidden in the web UI and still render.
+- `SportsCoreSharedMixin._draw_text_with_outline(..., element="score_text")` —
+  naming the element resolves its colour by name and honours its visibility
+  toggle. Without a name the colour is inferred from font-object identity,
+  which cannot separate two elements sharing a face; that is the case every
+  bitmap font is in, because a `freetype.Face` cannot be re-instantiated, and
+  it is how a BDF-rendered element silently lost a configured colour. Shared
+  faces now resolve when exactly one sharer has a colour set.
+- `LogoHelper.load_logo(..., scale=)` — applies a user's image scale, and keys
+  the cache on the scaled box so two elements scaled differently cannot be
+  served each other's image.
+- `src.element_style.native_bdf_size(font)` — the one pixel size a bitmap font
+  can render at, or None for a scalable one. The web UI needs this to know
+  whether a size control can take effect at all.
+- `ElementStyleResolver(config, defaults, mode=...)` plus `visible`, `align`
+  and `scale` on `ElementStyle`. The mode binds to the resolver rather than
+  being passed per call, so a plugin with one instance per mode makes every
+  existing lookup mode-aware by setting one class attribute.
+- `BasePlugin.styles` / `styles_for(mode)` / `STYLE_MODE` — the accessor every
+  plugin inherits, so adopting this is no longer a guarded import plus schema
+  discovery plus resolver invalidation in each plugin.
+- `SportsCoreSharedMixin._get_layout_offset` — promoted from the plugins'
+  bundled copies. Each still carries its own, which wins by MRO, so adopting
+  it is a deletion.
+
+Schema and web UI:
+
+- A `customization` block is now rendered by a composite style editor: one row
+  per element rather than nested accordions, with a tab per declared mode.
+  Plugins that hand-wrote their style blocks get it without a plugin release;
+  `x-style-elements` and `x-style-modes` declare it compactly.
+- Font fields become a real picker rather than a hardcoded `enum`, so a font
+  the user uploads is selectable. Bitmap fonts taller than the element's
+  declared size ceiling are filtered out, because a bitmap font ignores
+  `font_size` and renders at its own size.
+- `/static/plugin-widgets/<plugin>/<widget>.js` serves a plugin's own web-UI
+  widgets. The client half and the docs already existed; nothing served them.
+
+Fixed:
+
+- A bitmap font asked for a size it has no strike for fell back to
+  *PressStart2P* — a different typeface — rather than to its own native size.
+  32 of the 35 shipped fonts are bitmap, so this was reachable for most font
+  choices.
+- The plugin config form read `config_schema.json` directly while the save
+  route read it through `SchemaManager`. Only the latter expands a compact
+  `x-style-elements` declaration, so a plugin using that form had a
+  customization section that rendered as empty space.
+- `unshare_element_fonts` rebuilt faces through bare `ImageFont.truetype`,
+  bypassing the layout engine `src/common/font_layout.py` pins. These were the
+  only two call sites in `src/` doing so.
+- The form parser compared a schema type to a bare string, so a nullable field
+  (`["array", "null"]`) never had its indexed colour inputs recombined, and a
+  blank one became `[]` rather than null.
+
+Removed:
+
+- The Fonts tab's "Element Font Overrides" panel and its three endpoints. They
+  reported success and saved nothing, and the element keys the panel offered
+  (`nfl.live.score`, `clock.time`) are read by no plugin, so wiring them to the
+  real `FontManager` methods would still have changed nothing on the panel.
+  Per-element font choice now lives in each plugin's own config editor.
+- "Detected Manager Fonts", which listed every installed font with a hardcoded
+  usage count.
+- Two dead client-side config-form renderers in `app-shell.js` (~580 lines) and
+  the legacy `plugins/config_manager.js`, superseded by server-side rendering.
+
 ## 3.3.0
 
+Historical note: tags `v3.3.0` and `v3.3.1` both report `__version__` "3.3.0" and both ship `src/common/sports_shared.py`, so a "3.3.0" floor always means a core with `sports_shared`.
+
 **The release the sports scoreboards floor on to delete their bundled copies.**
 3.2.0 shipped the unified sports library and made `ledmatrix_min_version`
 enforceable; this ships the last three shared modules and completes the store

CLAUDE.md

@@ -6,7 +6,7 @@
 - `config/config.json` — User plugin configuration (persists across plugin reinstalls)
 - `plugin-repos/` — **Default** plugin install directory used by the
   Plugin Store, set by `plugin_system.plugins_directory` in
-  `config.json` (default per `config/config.template.json:167`).
+  `config.json` (default per `config/config.template.json`).
   Not gitignored.
 - `plugins/` — Legacy/dev plugin location. Gitignored (`plugins/*`).
   Used by `scripts/dev/dev_plugin_setup.sh` for symlinks. The plugin
@@ -23,7 +23,7 @@
 - Each plugin needs: `manifest.json`, `config_schema.json`, `manager.py`, `requirements.txt`
 - 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.matrix.width/height`
+- 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)
 - Secrets: namespaced by plugin id in `config/config_secrets.json`, declared
   via `"x-secret": true` in the plugin's config schema, and deep-merged into
   the plugin's config dict at load time — plugins read them with plain
@@ -45,9 +45,12 @@
 - 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`
 
-## Skin System (visual overlays for sports scoreboards)
+## Skin System (visual overlays for sports scoreboards) — NOT SUPPORTED YET
+- Skins do not render with the current scoreboard plugins: the only hook is `SportsCore._render_game()` in `src/base_classes/sports/core.py`, and no current scoreboard plugin (monorepo or third-party registry) builds on `src.base_classes`
+- So core doesn't offer them: no Visual Skin dropdown (`get_plugin_schema` skips `inject_skin_selector`), the store hides/refuses `"type": "skin"` entries, `GET /api/v3/skins` reports `"supported": false`. Switch: `SKINS_RENDER_SUPPORTED` in `src/skin_system/__init__.py`
+- Stored `skin` / `skin_options` config values must keep loading and saving (base schema allows them; form saves deep-merge over the stored section)
 - Skins live in `skins/<skin-id>/` (skin.json + skin.py), NOT in plugin dirs — plugin reinstall deletes plugin dirs
-- Core: `src/skin_system/` (ScoreboardSkin, SkinContext, runtime); hook: `SportsCore._render_game()` in `src/base_classes/sports/core.py`
+- Core: `src/skin_system/` (ScoreboardSkin, SkinContext, runtime); keep it and its tests
 - Skins render onto `ctx.canvas` only; fallback to built-in renderer on `False`/exception (3 strikes disables for session)
 - View-model guaranteed keys are frozen (see `test/test_skin_system.py::TestViewModelContract`) — renaming keys in `_extract_game_details_common` or sport extractors breaks published skins
 - Validate skins headlessly: `python scripts/validate_skin.py --skin <id>`; docs: `docs/SKIN_SYSTEM.md`, `docs/CREATING_SKINS.md`

PRODUCT.md

@@ -0,0 +1,74 @@
+# Product
+
+<!-- impeccable:product-schema 1 -->
+
+## Platform
+
+web
+
+## Users
+
+Designed novice-first, with power tools kept within reach.
+
+- **Primary: hobbyist builders.** People who assembled an LED matrix panel on a Raspberry Pi, often by following the install video, and are frequently new to Linux and the Pi. They set the display up once (panel size, timezone, WiFi), install and enable a few plugins, then come back occasionally to tweak what the panel shows. They usually reach the control panel from a phone or laptop on their home network, sometimes as an installed home-screen app.
+- **Secondary: tinkerers and plugin developers.** Comfortable with SSH, `config.json`, and GitHub. They lean on the Config Editor, Logs, Cache, Operation History, Tools, GitHub-repo installs, and per-plugin config while building or debugging. Their tools must stay reachable without sitting in the novice's path.
+
+## Product Purpose
+
+LEDMatrix turns a Raspberry Pi and an RGB LED matrix panel into an information-rich display (clock, weather, calendar, sports scores, stocks, music, and more) through a plugin platform. The web control panel ("LED Matrix Control") is where the display gets configured, extended, and kept healthy.
+
+Success means a builder gets from a freshly flashed Pi to a working, personalized display without needing a terminal, and can keep it running (updates, recovery, troubleshooting) the same way.
+
+## Positioning
+
+Four strengths define LEDMatrix, and future work must protect all of them:
+
+1. **Plugin ecosystem.** The core ships only `starlark-apps` and `web-ui-info`; everything else comes from the built-in Plugin Store (the official `ledmatrix-plugins` monorepo), third-party GitHub repos, or Starlark (Tidbyt-style) apps. Each installed plugin gets its own configuration tab, generated from its schema.
+2. **Runs on tiny Pis.** The UI is served by the same device that drives the matrix, on boards as small as the Pi Zero 2 W (512 MB), Pi 3/3B+, and the 1 GB Pi 4.
+3. **Recovers without SSH.** WiFi access-point fallback with a captive setup page, backup & restore, in-UI updates, live logs, diagnostics, service control, and plugin health let users fix problems from the browser.
+4. **Open and community-led.** GPL-3.0, a Discord community, and contributions welcome. The maintainer (ChuckBuilds) builds in public and openly relies on AI development tools.
+
+## Operating Context
+
+- **Access.** Served on the local network at `http://<pi-ip>:5000` by the `ledmatrix-web` service. It is installable as a PWA (`web_interface/static/v3/manifest.json`, short name "LEDMatrix").
+- **First run.** When the Pi has no network it creates its own WiFi access point, so the captive setup page (`templates/v3/captive_setup.html`) may be the very first screen a user sees, on a phone, with no internet connection.
+- **Navigation.**
+  - System tabs: Overview, General, WiFi, Schedule, Display, Rotation, Config Editor, Backup & Restore, Fonts, Logs, Cache, Operation History, Tools.
+  - A second row holds Plugin Manager (with the Plugin Store), Starlark Apps, and one tab per installed plugin.
+- **Live data.** The Overview shows system stats (CPU, memory, temperature, power/throttling) and a live display preview, streamed over SSE.
+- **Getting Started checklist.** The Overview's first-run checklist runs: set panel size → set timezone → install a plugin → enable it → configure it.
+- **Development.** `python3 scripts/dev_server.py` gives a browser preview without the display loop; `python3 run.py -e` runs the full display in emulator mode.
+
+## Capabilities and Constraints
+
+- **Hard constraint: plugin UI compatibility.** Third-party plugins rely on JSON Schema (Draft-7) generated config forms, the widget registry (`static/v3/js/widgets/`), `x-secret` fields, and plugin web-UI actions. UI changes must keep these working.
+- **Config storage.** Plugin configuration lives in `config/config.json` and secrets in `config/config_secrets.json`, never in plugin directories, so configs survive reinstalls.
+- **Stack.** An existing Flask + HTMX + Alpine.js app with Jinja templates (`web_interface/templates/v3/`) and static JS/CSS (`web_interface/static/v3/`), with self-hosted vendor assets.
+- **Terminology.** Plugin, Plugin Store, Starlark app, rotation, display duration, Vegas Scroll Mode, skin, on-demand, AP mode.
+- **Open decisions** (offered during init, not adopted as constraints):
+  - Whether the UI must work fully offline, with no CDN fallbacks at runtime.
+  - Whether a Node/CSS build step is acceptable for contributors.
+  - Whether a formal accessibility standard (e.g. WCAG 2.2 AA) is a requirement.
+
+## Brand Commitments
+
+- **Names.** The product is "LEDMatrix" and the web UI is titled "LED Matrix Control". The maintainer brand is ChuckBuilds.
+- **Voice.** Friendly, honest, and learning-in-public, as in the README.
+- **App icons.** They live in `web_interface/static/v3/icons/`.
+
+No other visual identity has been made binding.
+
+## Evidence on Hand
+
+- **Photos.** Real photographs of running displays are linked in `README.md` (clock, weather, calendar, NHL/MLB/NFL/NCAA, stocks, music).
+- **Video.** YouTube install and walkthrough videos from ChuckBuilds.
+- **Docs.** Extensive documentation in `docs/`, e.g. `WEB_INTERFACE_GUIDE.md`, `GETTING_STARTED.md`, `WIFI_NETWORK_SETUP.md`, `LOW_MEMORY_BOARDS.md`, `PLUGIN_STORE_GUIDE.md`.
+- **Absences.** There are no testimonials, user counts, or benchmark figures. Do not fabricate them.
+
+## Product Principles
+
+1. **Novice path first, power one click away.** Default views serve the first-time builder, while advanced tools stay discoverable for tinkerers.
+2. **Never strand the user at a terminal.** Every setup, recovery, and troubleshooting task has a browser path, including from the AP-mode captive page.
+3. **Respect the Pi.** Every feature is paid for in memory and CPU on a Pi Zero 2 W that is also driving the display.
+4. **The ecosystem is the product.** Plugins, including third-party ones, must feel first-class and keep working across core UI changes.
+5. **Honest and welcoming.** Plain language, truthful status, and no overstated claims, in keeping with an open, community-built project.

README.md

@@ -463,13 +463,12 @@ For plugin development, check out the [Hello World Plugin](https://github.com/Ch
 
 ### Visual Skins for Scoreboards
 
-Want a different look for a sports scoreboard without forking the plugin?
-**Skins** restyle the live/recent/upcoming screens while the plugin keeps
-handling data, scheduling, caching, and vegas mode. Install one with
-`git clone <skin repo> skins/<skin-id>`, select it in the plugin's config,
-and you're done — see [docs/SKIN_SYSTEM.md](docs/SKIN_SYSTEM.md) (how it
-works) and [docs/CREATING_SKINS.md](docs/CREATING_SKINS.md) (build your own,
-including a ready-made Claude Code prompt).
+**Not supported yet.** Skins are meant to restyle a sports scoreboard's
+live/recent/upcoming screens without forking the plugin, but the current
+scoreboard plugins don't render them: a selected skin has no effect. The web
+UI doesn't offer skin install or selection for that reason. The skin system
+and its docs stay in place for when scoreboards adopt it; see
+[docs/SKIN_SYSTEM.md](docs/SKIN_SYSTEM.md) for why.
 
 2. **Built-in Managers Deprecated**: The built-in managers (hockey, football, stocks, etc.) are now deprecated and have been moved to the plugin system. **You must install replacement plugins from the Plugin Store** in the web interface instead. The plugin system provides the same functionality with better maintainability and extensibility.
 </details>

config/config.template.json

@@ -1,5 +1,8 @@
 {
     "web_display_autostart": true,
+    "auto_update": {
+        "enabled": false
+    },
     "schedule": {
         "enabled": false,
         "mode": "per-day",

docs/ADAPTIVE_LAYOUT.md

@@ -223,8 +223,8 @@ The harness already renders every plugin at a spread of sizes (now
 including 96x48):
 
 ```bash
-python scripts/check_plugin.py <plugin-dir> --sizes 64x32,128x32,96x48,128x64,256x64
-python scripts/render_plugin.py <plugin-dir> --width 96 --height 48
+python scripts/check_plugin.py --plugin <plugin-id> --sizes 64x32,128x32,96x48,128x64,256x64
+python scripts/render_plugin.py --plugin <plugin-id> --width 96 --height 48
 ```
 
 `BoundsCheckingDisplayManager` flags right/bottom overflow and now records

docs/CREATING_SKINS.md

@@ -1,5 +1,14 @@
 # Creating Skins
 
+> **Not supported yet: skins don't render with the current scoreboard
+> plugins.** The only render hook is `SportsCore._render_game()` in
+> `src/base_classes/sports/core.py`, and no current scoreboard (monorepo or
+> third-party) builds on `src.base_classes`, so a skin you build here passes
+> `validate_skin.py` but never appears on the matrix. The web UI and Plugin
+> Store don't offer skins for that reason. Details:
+> [SKIN_SYSTEM.md](SKIN_SYSTEM.md#status-not-supported-yet). The guide below
+> stays accurate for the skin API itself.
+
 A skin restyles a sports scoreboard (live / recent / upcoming) without
 forking the plugin: the plugin keeps fetching data, scheduling, caching, and
 doing vegas mode; your skin only draws. Architecture background:
@@ -19,7 +28,9 @@ panel sizes with **no hardware, no network, no running service**, saves PNGs
 (plus 4x previews) to `skin_renders/`, and fails loudly on errors. Iterate:
 edit → validate → look at the PNGs.
 
-To see it on your matrix, add to your plugin's section in `config/config.json`:
+To select it, add to your plugin's section in `config/config.json` (this is
+stored and validated, but has no visible effect until a scoreboard uses the
+skin hook — see the note at the top):
 
 ```json
 "baseball-scoreboard": {
@@ -28,8 +39,8 @@ To see it on your matrix, add to your plugin's section in `config/config.json`:
 }
 ```
 
-or pick it from the **Visual Skin** dropdown in the web UI (it appears once a
-matching skin is installed). `"skin"` also accepts a per-mode mapping:
+The web UI's **Visual Skin** dropdown is hidden while skins are unsupported.
+`"skin"` also accepts a per-mode mapping:
 `{"live": "my-skin", "recent": "built-in"}`.
 
 ## The manifest (`skin.json`)
@@ -234,8 +245,9 @@ Tips that keep Claude (and you) out of trouble:
       dev machine
 
 Distribute by publishing the directory as a git repo (users
-`git clone <repo> skins/<id>`), or submit it to the plugin registry as an
-entry with `"type": "skin"` (see [SKIN_SYSTEM.md](SKIN_SYSTEM.md) §Distribution).
+`git clone <repo> skins/<id>`). Registry entries with `"type": "skin"` are
+hidden and refused by the Plugin Store while skins are unsupported (see
+[SKIN_SYSTEM.md](SKIN_SYSTEM.md) §Distribution).
 
 **Trust note:** a skin is Python running inside the display service — the
 same trust level as a plugin. Review code before installing skins from

docs/PLUGIN_API_REFERENCE.md

@@ -36,7 +36,11 @@ self.enabled            # Boolean enabled status
 
 #### `update() -> None`
 
-Fetch/update data for this plugin. Called based on `update_interval` specified in the plugin's manifest.
+Fetch/update data for this plugin. Called on the plugin's update interval:
+the value `get_update_interval()` returns when it returns a number, otherwise
+the static interval: the `update_interval` in the plugin's manifest, else
+`update_interval` in the plugin's section of `config.json`, else 60 seconds
+(see [`get_update_interval()`](#get_update_interval---optionalfloat) below).
 
 **Example**:
 ```python
@@ -109,6 +113,46 @@ Called when plugin is enabled.
 
 Called when plugin is disabled.
 
+#### `get_update_interval() -> Optional[float]`
+
+How often this plugin wants `update()` called right now, in seconds. The
+manifest's `update_interval` is one static number; override this when the
+right cadence depends on state only the plugin knows, e.g. poll every 15s
+while a game is live and fall back to the manifest value otherwise.
+
+**Returns**: seconds as a number, or `None` (the default) for no opinion.
+
+How `PluginManager` (`_get_plugin_update_interval` in
+`src/plugin_system/plugin_manager.py`) resolves the interval on each
+scheduling tick:
+
+1. It calls `get_update_interval()`. A number wins over everything below.
+   Values under `PluginManager.MIN_DYNAMIC_UPDATE_INTERVAL` (5 seconds) are
+   raised to it.
+2. If the hook returns `None`, raises, or returns something that isn't a
+   finite number (a `bool`, a string, NaN, infinity), it is ignored and the
+   static interval applies: the manifest's `update_interval`, else
+   `update_interval` in the plugin's section of `config.json`, else 60
+   seconds.
+
+The static value is cached per plugin until the plugin is loaded or
+unloaded again, so editing `update_interval` in config takes effect on the
+next reload. The hook's return value is never cached: it is called on every
+tick of the display loop, so keep it to attribute reads (no config lookups,
+no I/O, no locks a fetch might hold) and don't let it raise.
+
+**Example**:
+```python
+def get_update_interval(self):
+    # Fast while something is live, manifest default otherwise.
+    if any(m.live_games for m in self._live_managers):
+        return self.config.get("live_update_interval", 15)
+    return None
+```
+
+Added in core 3.4.0; older cores never call it, so a plugin that relies on
+it should floor `ledmatrix_min_version` at `3.4.0`.
+
 #### `get_display_duration() -> float`
 
 Get display duration for this plugin. Can be overridden for dynamic durations.

docs/PLUGIN_ARCHITECTURE_SPEC.md

@@ -189,7 +189,9 @@ class BasePlugin(ABC):
     def update(self) -> None:
         """
         Fetch/update data for this plugin.
-        Called based on update_interval in manifest.
+        Called every get_update_interval() seconds when that returns a
+        number, otherwise at the static interval: the manifest's
+        update_interval, else the plugin config's update_interval, else 60s.
         """
         pass
     
@@ -204,6 +206,21 @@ class BasePlugin(ABC):
         """
         pass
     
+    def get_update_interval(self) -> Optional[float]:
+        """
+        Seconds until update() should run again, decided at runtime.
+        Return None (the default) to use the static interval.
+
+        PluginManager._get_plugin_update_interval calls this on every
+        scheduling tick. A number overrides the manifest and is clamped up
+        to PluginManager.MIN_DYNAMIC_UPDATE_INTERVAL (5s); None, a raise,
+        or a non-finite/non-numeric value falls back to the manifest's
+        update_interval, then the plugin config's update_interval, then
+        60s. The static value is cached until the plugin reloads; the hook
+        is not cached, so it must be cheap and must not raise.
+        """
+        return None
+    
     def get_display_duration(self) -> float:
         """
         Get the display duration for this plugin instance.

docs/PLUGIN_DEVELOPMENT_GUIDE.md

@@ -10,11 +10,11 @@ This guide explains how to set up a development workflow for plugins that are ma
 > scale. Existing plugins keep their classic rendering unless they adopt
 > those APIs; nothing migrates automatically.
 
-> **Just want a different look for an existing sports scoreboard?** You may
-> not need a plugin at all — a **skin** restyles the live/recent/upcoming
-> rendering while the plugin keeps handling data, scheduling, caching, and
-> vegas mode, in ~100 lines of drawing code. See
-> [CREATING_SKINS.md](CREATING_SKINS.md).
+> **Want a different look for an existing sports scoreboard?** Skins are
+> meant for that, but they are **not supported yet**: the current scoreboard
+> plugins don't render them (see [SKIN_SYSTEM.md](SKIN_SYSTEM.md#status-not-supported-yet)).
+> For now, change the look through the plugin's own display settings or its
+> code.
 
 ## Overview
 

docs/PLUGIN_ELEMENT_STYLING.md

@@ -0,0 +1,135 @@
+# Per-element styling for plugin authors
+
+Users want to change the font, size and colour of individual things on screen,
+nudge them a few pixels, hide the ones they do not care about, and scale a logo
+down. This is the one system that does that, and a plugin joins it by
+**declaring elements in its `config_schema.json`** — not by writing a style
+resolver, a font cache or a web form.
+
+The short version:
+
+```jsonc
+"customization": {
+  "type": "object",
+  "title": "Display Customization",
+  "x-style-elements": {
+    "score_text": {
+      "title": "Score",
+      "font":  { "default": "PressStart2P-Regular.ttf" },
+      "size":  { "default": 10, "min": 4, "max": 16 },
+      "color": { "default": [255, 255, 255] },
+      "offsets": true,
+      "visible": true,
+      "align": true
+    },
+    "home_logo": { "title": "Home logo", "offsets": true, "scale": true }
+  },
+  "x-style-modes": ["live", "upcoming", "recent"]
+}
+```
+
+That is the whole declaration. The core expands it into a full JSON Schema, the
+web UI renders a compact style editor with a row per element, and the values
+land in `config.json` under the keys you named.
+
+## What each key does
+
+| Key | Effect |
+|---|---|
+| `font` | Font picker listing every shipped **and user-uploaded** font. |
+| `size` | Number field. `min`/`max` also cap which fixed-size fonts are offered. |
+| `color` | Colour swatch; stored as `[r, g, b]`. |
+| `offsets` | X/Y nudge, stored under `customization.layout.<element>`. |
+| `visible` | Show/hide toggle. |
+| `align` | `left` / `center` / `right`. |
+| `scale` | Size multiplier, for logos and images. Also under `layout`. |
+
+`x-style-modes` is optional. Declare it and every element gains a per-mode
+override tab — a scoreboard can then style its live, upcoming and recent cards
+separately. **A mode field left blank means "inherit", not zero.**
+
+## Reading the values
+
+Every plugin inherits `BasePlugin.styles`, which finds your `config_schema.json`
+on its own:
+
+```python
+style = self.styles.style(
+    "score_text",
+    classic_font="PressStart2P-Regular.ttf",   # what you shipped
+    classic_size=10,
+    classic_color=(255, 255, 255),
+)
+if style.visible:
+    draw.text((x + style.offset[0], y + style.offset[1]),
+              text, font=style.font, fill=style.color)
+```
+
+For a specific mode, use `self.styles_for("recent")`, or set
+`STYLE_MODE = "recent"` on the class and keep calling `self.styles`.
+
+### The one rule that matters
+
+**Pass your shipped values as the `classic_*` arguments.** The resolver returns
+them verbatim unless the user actually changed something, which is what keeps an
+untouched install rendering byte-identically. It can tell the difference because
+a value only counts as user-forced when it *differs from the schema default* —
+the save path writes the full default object into `config.json` on every save,
+so "present in config" proves nothing.
+
+Never compare against the default yourself; that rule lives in exactly one place.
+
+### Stateless readers
+
+For helpers handed a config dict rather than a plugin instance:
+
+```python
+from src.element_style import (element_color, element_visible,
+                               element_align, element_scale, layout_offset)
+
+colour = element_color(config, "score_text", (255, 255, 255), mode)
+shown  = element_visible(config, "records", True, mode)
+dy     = layout_offset(config, "score", "y_offset", 0, mode)
+```
+
+## Sports scoreboards
+
+`SportsCoreSharedMixin` wires most of this up already. Two things to know:
+
+* **Name your draws.** `_draw_text_with_outline(..., element="score_text")`
+  resolves the colour by name *and* honours the visibility toggle. Without it
+  the colour has to be guessed from the identity of the font object, which
+  cannot tell two elements apart when they share a face — the case every
+  bitmap font is in.
+* **Modes are free.** Live/upcoming/recent are separate instances, so setting
+  `SKIN_MODE` on each is enough; no call site passes a mode.
+
+## Adopting an existing hand-written block
+
+If your schema already spells out `font` / `font_size` / `text_color` per
+element longhand, **you do not need to change anything**. The core recognises
+that shape and upgrades it in place: the style editor, the real font picker
+(including uploaded fonts) and per-mode overrides all appear on a core update.
+Add `x-style-modes` if you want the mode tabs.
+
+## Fonts, and why size is sometimes locked
+
+32 of the 35 shipped fonts are fixed-strike BDF bitmaps: they render at exactly
+one pixel size and ignore `font_size`. The picker knows which, and the editor
+locks the size field to the native size and labels it `fixed`. A font too tall
+for the `max` you declared is not offered at all.
+
+Uploaded fonts (Fonts tab) land in `assets/fonts/` and appear in the picker
+automatically.
+
+## Checklist
+
+1. Declare `x-style-elements` (and `x-style-modes` if you have modes).
+2. Read through `self.styles`, passing your shipped values as `classic_*`.
+3. Honour `style.visible`, `style.offset` and `style.scale` where they apply.
+4. Confirm an untouched config renders identically:
+   `python scripts/check_plugin.py --plugin <id>`.
+5. Monorepo plugins: bump `manifest.json` and run `python update_registry.py`.
+
+See also: [docs/PLUGIN_CONFIGURATION_GUIDE.md](PLUGIN_CONFIGURATION_GUIDE.md),
+[docs/FONT_MANAGER.md](FONT_MANAGER.md).

docs/README.md

@@ -45,6 +45,8 @@ Going deeper:
 
 - [PLUGIN_CONFIG_QUICK_START.md](PLUGIN_CONFIG_QUICK_START.md) — minimal config you need
 - [PLUGIN_CONFIGURATION_GUIDE.md](PLUGIN_CONFIGURATION_GUIDE.md) — schema design
+- [PLUGIN_ELEMENT_STYLING.md](PLUGIN_ELEMENT_STYLING.md) — let users restyle,
+  move, hide and scale individual elements (per display mode, if you have them)
 - [PLUGIN_CONFIGURATION_TABS.md](PLUGIN_CONFIGURATION_TABS.md) — multi-tab UI configs
 - [PLUGIN_CONFIG_ARCHITECTURE.md](PLUGIN_CONFIG_ARCHITECTURE.md) — how the config system works
 - [PLUGIN_CONFIG_CORE_PROPERTIES.md](PLUGIN_CONFIG_CORE_PROPERTIES.md) — properties every plugin honors
@@ -54,8 +56,8 @@ 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
-- [SKIN_SYSTEM.md](SKIN_SYSTEM.md) — skin architecture for sports scoreboards
-- [CREATING_SKINS.md](CREATING_SKINS.md) — writing and validating a skin
+- [SKIN_SYSTEM.md](SKIN_SYSTEM.md) — skin architecture for sports scoreboards (not supported yet: current scoreboards don't render skins)
+- [CREATING_SKINS.md](CREATING_SKINS.md) — writing and validating a skin (same caveat)
 
 ## Reference
 

docs/SCROLL_PERFORMANCE.md

@@ -203,26 +203,61 @@ configured speed, so position stays proportional to real time.
 
 ## Diagnosing a juddery scroller
 
-**`Avg FPS` will lie to you.** It is a 100-frame moving average, and a 2 ms
-duplicate frame plus a 21 ms double-wait average to exactly 10 ms. A ticker
-that is stalling on half its frames still reports a healthy `100.0`.
+**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.
 
-Look at the **distribution** instead:
+Every scroller emits one line every 5 seconds covering *every* frame in that
+window, tagged with the plugin it came from:
 
 ```bash
-journalctl -u ledmatrix --since "-10min" --no-pager \
-  | grep -oE "Frame time: [0-9.]+ms" | awk '{print $3}' | sed 's/ms//' \
-  | awk '{printf "%.0f\n", $1}' | sort -n | uniq -c
+journalctl -u ledmatrix --since "-10min" --no-pager | grep "Scroll frame stats"
+```
+
+```
+[Plugin: news] Scroll frame stats - 100.0 fps over 501 frames | median 10.00ms
+p95 10.11ms max 12.03ms min 7.98ms | stalls 0 (0.0%) skips 0 (0.0%)
 ```
 
 Reading it, on a 100 Hz panel:
 
 | you see | it means |
 |---|---|
-| everything at 10 ms | healthy |
-| a mode at ~2 ms | **duplicate frames** — the swap was skipped because the image did not change. The scroller is advancing less than one pixel per frame. |
-| a mode at 20/30/50 ms | frames missing refreshes — per-frame work is overrunning, or a background thread is holding the GIL |
-| `Avg FPS` above 100 | duplicates present, unless the scroll cycle has completed and is idling |
+| median 10 ms, p95 within ~0.5 ms of it | healthy — locked to the panel |
+| p95 or max at 20/30/50 ms | frames missing refreshes — per-frame work is overrunning, or a background thread is holding the GIL |
+| non-zero **skips**, or a median *below* 10 ms | **duplicate frames** — the swap was skipped because the image did not change, so the frame never waited on vsync. The scroller is advancing less than one pixel per frame. |
+| non-zero **stalls** | frames past 1.5× the median, which is the measure of judder that survives averaging |
+
+`stalls` and `skips` are both counted against that window's own median, so they
+stay meaningful on a panel running at any refresh rate.
+
+To rank every scroller at once rather than reading lines one at a time:
+
+```bash
+journalctl -u ledmatrix --since "-3h" --no-pager | grep "Scroll frame stats" \
+  | sed -E 's/.*- (\S+) - (\[Plugin: [^]]+\] )?Scroll.*median ([0-9.]+)ms p95 ([0-9.]+)ms.*/\1 \3 \4/' \
+  | awk '$2 < 1000 {n[$1]++; m[$1]+=$2; p[$1]+=$3} END {for (k in n)
+        printf "%-28s %5d windows  median %6.2fms  p95 %6.2fms\n", k, n[k], m[k]/n[k], p[k]/n[k]}' \
+  | sort -k7 -rn
+```
+
+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
+the gap between them was recorded as one enormous sample — it landed in the
+`max` field of otherwise healthy windows and counted as one stall per scroll,
+roughly 0.2% at 500 frames to a window, which is the same order as the real
+stall rates it sat beside. Current builds emit none, but the guard costs
+nothing and keeps the command honest against older journals.
+
+A scroller whose p95 sits several times its median is the one to fix, and it is
+usually the one doing the most per-frame work rather than the one configured
+worst. Measured over 20 minutes with two scrollers set identically at 100 px/s,
+the leaderboard held 10 ms flat while the odds ticker spent ~20% of its frames
+on duplicates. Same settings, different render cost: odds does more per-frame
+work, and more variably, so it is first to land a frame that advances less than
+a whole pixel. Check the render path before the config.
 
 Then confirm what the plugin actually loaded — config edits do not always reach
 the running code:

docs/SKIN_SYSTEM.md

@@ -1,5 +1,35 @@
 # Skin System Architecture
 
+## Status: not supported yet
+
+**Skins don't render with the current scoreboard plugins.** The skin system
+below works in isolation (it loads, validates and renders skins in
+`scripts/validate_skin.py` and `test/test_skin_system.py`), but nothing on a
+running display calls it:
+
+- The only render hook is `SportsCore._render_game()` in
+  `src/base_classes/sports/core.py`.
+- None of the current scoreboard plugins build on `src.base_classes`. The
+  official scoreboards in the `ledmatrix-plugins` monorepo, and the
+  third-party scoreboards in the plugin registry, carry their own sports and
+  rendering code (with the shared `src/common/sports_*` helpers) and never
+  reach `SportsCore._render_game()`.
+
+So a skin can be dropped into `skins/` and named in a plugin's config, but the
+scoreboard keeps drawing its built-in layout. Until a scoreboard adopts the
+hook, core does not offer skins to users:
+
+- The plugin config page shows no **Visual Skin** dropdown.
+- The Plugin Store hides registry entries with `"type": "skin"` and refuses
+  to install one (`POST /api/v3/plugins/install` answers 400 with the reason).
+- `GET /api/v3/skins` still lists what is in `skins/`, with
+  `"supported": false` and a `message`.
+- A config that already contains `"skin"` / `"skin_options"` still loads,
+  validates and saves unchanged; the value is simply unused.
+
+The rest of this document describes the design as built, for whoever wires a
+scoreboard to it.
+
 Skins are user-installable **visual overlays** for the sports scoreboards.
 A skin replaces only the *look* of a scoreboard — the host plugin keeps doing
 data fetching, scheduling, caching, dedup, live-priority takeover, and vegas
@@ -32,8 +62,10 @@ crashing) simply restores the built-in look.
 
 ## The render funnel
 
-Every sports scoreboard (baseball, football, basketball, hockey — anything
-built on the `src/base_classes/sports/` package, `core.py`) renders through exactly one seam:
+A sports scoreboard built on the `src/base_classes/sports/` package
+(`core.py`) renders through exactly one seam. No current scoreboard plugin is
+built on it (see [Status](#status-not-supported-yet)), so for them this seam is
+never reached:
 `SportsCore._render_game(game, force_clear)`.
 
 1. The mode class's `display()` (live, `SportsUpcoming`, `SportsRecent`)
@@ -135,22 +167,26 @@ Inside the plugin's own config section in `config/config.json`:
 `"built-in"` means the stock renderer. Because this rides the plugin's config
 section, it persists across plugin reinstalls like every other setting.
 
-The web UI shows a **Visual Skin** dropdown for plugins that have matching
-skins installed: `SchemaManager.inject_skin_selector` adds an enum to the
-*served* schema only. Validation never sees the enum — so a config that
-references an uninstalled skin stays valid (rendering just falls back), and
-the currently-configured value is always kept selectable. `GET /api/v3/skins`
-lists installed skins (optionally filtered by `?plugin_id=`).
+`SchemaManager.inject_skin_selector` can add a **Visual Skin** enum to the
+*served* schema for plugins with matching skins installed. While skins are
+unsupported the plugin schema endpoint does not call it, so the dropdown is
+not shown. Validation never sees the enum either way: the base schema allows
+any `skin` value, so a config that references an uninstalled skin stays valid.
+`GET /api/v3/skins` lists installed skins (optionally filtered by
+`?plugin_id=`) and reports `"supported": false`.
 
 ## Distribution
 
 - **Manual:** `git clone <skin repo> skins/<skin-id>` — that's the whole
   install. No manifest bumps, no `update_registry.py`; skins are not monorepo
   plugins.
-- **Store:** registry entries with `"type": "skin"` install through the same
-  `plugins.json` pipeline; `PluginStoreManager` routes them to `skins/`,
-  validates `skin.json` (including the API major version) instead of
-  `manifest.json`, and never installs dependencies — skins are render-only
+- **Store (disabled while unsupported):** registry entries with
+  `"type": "skin"` are hidden from the store list and refused on install.
+  `PluginStoreManager._install_skin_from_info` is kept: once
+  `SKINS_RENDER_SUPPORTED` in `src/skin_system/__init__.py` is true, such
+  entries install through the same `plugins.json` pipeline, land in `skins/`,
+  are validated against `skin.json` (including the API major version) instead
+  of `manifest.json`, and never install dependencies — skins are render-only
   (stdlib + PIL + the provided context, no third-party packages in v1).
 
 ## Trust model

docs/WEB_INTERFACE_GUIDE.md

@@ -96,6 +96,33 @@ Configure basic system settings:
 - **Plugin System Settings** — including the `plugins_directory` (default
   `plugin-repos/`) used by the plugin loader
 - **Autostart** options for the display service
+- **Automatic updates** — once a week, update LEDMatrix and every installed
+  plugin with a newer version. Off by default. Runs 2–5 AM local time when
+  possible, otherwise within a day of being due. The last result and next
+  check are shown under the toggle, and anything other than success raises a
+  banner on **Overview**.
+  - *Checks first:* the code update is skipped, with the reason shown, if
+    tracked files were edited locally, the checkout has local commits, a
+    rebase/merge is in progress, the branch has no upstream, less than 300 MB
+    is free, or the newest version already failed once. A failed fetch is
+    retried the next day.
+  - *Health check and rollback:* after pulling, `ledmatrix-update-verify.service`
+    restarts the services and checks that the web interface responds and the
+    display (if it was running) stays up. If not — or if the new dependencies
+    failed to install — it resets to the previous commit, reinstalls the
+    previous dependencies and restarts again. A running display is restarted;
+    a stopped one stays stopped.
+  - *Plugins* update through the Plugin Store, which refuses versions that need
+    a newer LEDMatrix and restores the old copy when an install fails. When the
+    code changed, plugins wait until it passes its health check. Plugins are
+    not health-checked after updating.
+  - *Setup needs no SSH.* Turning the toggle on restarts the display service,
+    which installs the health check (`ledmatrix-update-verify.path` and
+    `.service`); the General tab shows when it is ready, or why setup failed.
+    Until then only plugins update. New installs set it up during
+    installation and can switch updates on with
+    `first_time_install.sh --enable-auto-update` (or `LEDMATRIX_AUTO_UPDATE=1`,
+    which `one-shot-install.sh` passes through), or at the installer's prompt.
 
 Click **Save** to write changes to `config/config.json`. Most changes
 require a display service restart from **Overview**.

docs/archive/WEB_UI_AUDIT_2026-09.md

@@ -0,0 +1,164 @@
+# Web UI Technical Audit — September 2026
+
+Scope: `web_interface/` (Flask + HTMX + Alpine, `templates/v3/`, `static/v3/`).
+Method: Impeccable design detector, code review (accessibility; performance,
+theming, responsive), and a live pass on the running app at desktop and
+375px mobile widths in light and dark themes. Severe claims were verified
+against the live page; one was rejected (see below). No code was changed.
+
+Product context: see [`PRODUCT.md`](../../PRODUCT.md).
+
+## Health score: 8/20 (Poor)
+
+| # | Dimension | Score | Key finding |
+|---|-----------|-------|-------------|
+| 1 | Accessibility | 2 | Focus rings never render; modals have no dialog semantics or focus management |
+| 2 | Performance | 2 | ~1.2 MB JS (≈250 KB gzip) on every page; SSE streams and polling never pause |
+| 3 | Responsive | 2 | Mobile drawer works; header title wraps to 3 lines; many ~24px touch targets |
+| 4 | Theming | 1 | Tokens exist but hex dominates; dark mode is a class-by-class patch with leaks |
+| 5 | Implementation integrity | 1 | Templates use Tailwind classes that don't exist in the stylesheet |
+
+## Implementation integrity verdict: fail
+
+There is no Tailwind build. `static/v3/app.css` is a hand-written subset of
+Tailwind, while templates and JS are authored as if full Tailwind were loaded.
+
+- **333 of 516 utility class names used have no CSS rule** (2,582 uses),
+  confirmed against the live stylesheets. Top offenders: `border` (250),
+  `text-gray-700` (183), `block` (148), `mr-1` (127), `hidden` (79),
+  `py-1`, `text-blue-600`, `px-2`, `text-center`, `hover:bg-blue-700`,
+  `divide-y`, `uppercase`, `font-mono`.
+- **`.hidden` has never existed in `app.css`**, so the 145
+  `classList.add/remove/toggle('hidden')` calls across 26 files do nothing.
+  Visible proof: the header shows both the moon and sun theme icons.
+- **15 classes are defined only under `[data-theme="dark"]`** (e.g.
+  `bg-blue-50`, `bg-red-50`, `bg-yellow-50`, `border-blue-200`,
+  `text-red-700`), so tinted notice boxes are unstyled in light mode.
+- Visible damage: the Getting Started checklist (`partials/overview.html:96-117`)
+  renders native gray outset buttons in both themes; 32 visible buttons on
+  the Plugin Manager page render with default browser chrome; search icons
+  overlap inputs; error/diff modal backdrops are transparent
+  (`bg-gray-500 bg-opacity-75` undefined).
+
+Other drift:
+- Four competing `showNotification` definitions (`app.js:6`,
+  `app-shell.js:2464`, `widgets/notification.js:298`, `partials/fonts.html:249`)
+  — the winner depends on load order — plus 53 `alert()`/`confirm()` calls.
+- At least four modal implementations (on-demand modal in `base.html:1032`,
+  Tailwind-UI style in `error_handler.js`/`diff_viewer.js`, `.jfm-*`/`.pfm-*`
+  with injected CSS, ad-hoc modals in `plugins_manager.js`).
+- `.btn` mixed with ~90 hand-assembled color-utility button combos.
+- SSE wiring duplicated in `app-shell.js:5-60` and `app.js:186-205`.
+
+## Findings by severity
+
+### P0
+
+**Undefined utility layer** (above). Every show/hide toggle and every layout
+built from missing classes silently fails; root cause of most visual bugs.
+Fix: replace the hand-rolled subset with a real, purged Tailwind build
+(with dark-mode variants), or at minimum define the high-use missing classes
+(`hidden`, `border`, `block`, spacing/text utilities) and a button reset.
+→ `/impeccable harden`
+
+### P1
+
+- **Focus rings never render.** `focus:ring-2` (`app.css:289-291`) references
+  `--tw-ring-inset` and `--tw-ring-offset-width`, which are never defined, so
+  the `box-shadow` is invalid. `focus:outline-none` (18 uses) does remove the
+  outline. `peer-focus:ring-4` has no rule, so the plugin enable toggle
+  (`plugins_manager.js:1586-1593`, `sr-only` checkbox) shows no focus.
+  WCAG 2.4.7.
+- **Modals lack dialog semantics.** Only `json-file-manager.js` has
+  `role="dialog"`/`aria-modal`/Escape/initial focus; none trap focus or
+  return it. On-demand (`base.html:1032`), error (`error_handler.js:164-205`),
+  diff (`diff_viewer.js:211-214`), plugin file manager
+  (`plugin-file-manager.js:372-392, 576-599`), array-table editor
+  (`array-table.js:460-467`) have none of it. WCAG 2.1.2 / 4.1.2.
+- **Unnamed controls.** ~16 icon-only buttons with no accessible name, e.g.
+  `base.html:1036`, `plugins.html:173,210`, `plugin_config.html:485,656`,
+  `number-input.js:102,129`, `text-input.js:120`, `date-picker.js:95`,
+  `time-picker.js:100`, `password-input.js:141`. ~115 of 245 form fields have
+  no label (hotspots: `plugin_config.html` 19, `starlark_config.html` 14,
+  `plugins.html` 11); confirmed live on the 11 store search/sort/filter inputs.
+- **Captive WiFi setup page** (first-run surface): `#msg` status has no live
+  region, and `outline:none` is replaced by a 15%-alpha shadow
+  (`captive_setup.html:16,48`).
+- **Background traffic never stops.** `/stream/stats` and `/stream/display`
+  SSE stay open on every tab (display frames push with no preview visible).
+  Tab timers keep running after leaving the tab (`display.html:1046` 5s,
+  `logs.html:222` 5s, `tools.html:987` 15s, `plugins_manager.js:1882` 15s,
+  update check `base.html:1196` 30min). Only `tools.html:999` checks
+  `visibilitychange`. Costly on a Pi Zero 2 W.
+- **Page weight.** 47 script tags on every page, including all 33 widgets
+  (`base.html:984-1018`). `app-shell.js` (177 KB) is render-blocking
+  (`base.html:956`); `plugins_manager.js` is 277 KB.
+- **Dark mode leaks.** `plugin-file-manager.js` (53 hex) and
+  `json-file-manager.js` (63 hex, e.g. `.jfm-modal-box{background:#fff}`)
+  inject CSS that ignores `data-theme`; `.form-control` hard-codes
+  `#fff`/`#111827` (`app.css:668-671`). `app.css` has 186 hex + 46 rgb
+  literals vs 94 `var(--…)` uses.
+
+### P2
+
+- Toasts: `role="alert"` inside an `aria-live="polite"` container
+  (`notification.js:78,156`) → double/assertive announcements; auto-dismiss 4s.
+- `prefers-reduced-motion` covers 3 animations; ~106 `animate-pulse`/`fa-spin`
+  uses, `modalSlideIn`, and toast slides ignore it.
+- Mobile: header title wraps to three lines and spills out of the header;
+  ~33 plugin-card buttons are `text-xs px-2 py-1` (~24px); `#logs-container`
+  forced to 400/350px with `!important` (`app.css:399-411`).
+- Logs panel contrast: `text-gray-400` on `bg-gray-900` ≈ 3.9:1
+  (`logs.html:75,86`).
+- Three unnamed nested `<nav>` landmarks (`base.html:474,477,548`); no skip link.
+- Plugin lists fully rebuilt via `innerHTML` on every filter change
+  (`plugins_manager.js:1554, 3784, 3993, 4389, 5905`); `logs.html:225` adds a
+  reflow-forcing resize listener on every partial load.
+
+### P3
+
+- No `loading="lazy"` on images; Font Awesome `font-display:block`.
+- Unpinned `alpinejs@3.x.x` unpkg fallback (`base.html:241`).
+- `widgets/example-color-picker.js` is not loaded anywhere.
+- Detector: 3px accent stripe on `.plugin-card::before` (`app.css:721`).
+
+## Verified and rejected
+
+- **"Static assets are never cache-busted" (raised as P0): false.**
+  `app.py:491` (`@app.url_defaults add_static_version`) appends file mtime as
+  `?v=` to every static URL; the live HTML confirms it. The manual
+  `?v=20260307` on two script tags is merely redundant.
+- Light-mode gray text contrast is mostly fine: `app.css` remaps grays darker
+  (4.8–10:1).
+- Detector `gray-on-color` hits at `app.css:84,285` and `broken-image` hits
+  (JS-populated `src`) are not real rendered issues.
+
+## What works
+
+- Theme set before first paint, follows OS preference, `data-theme` + tokens.
+- Mobile drawer: Escape closes it, focus returns to the hamburger, 44px rows.
+- `aria-current="page"` on nav tabs; real `<header>` and `<main>`.
+- Status colors always paired with text; nearly all images have alt text.
+- `toggle-switch.js` uses `role="switch"`; vendor assets self-hosted.
+
+## Open decisions (block the P0 fix approach)
+
+Recorded as undecided in `PRODUCT.md`:
+- Must the UI work fully offline (no CDN fallbacks)?
+- Is a Node/CSS build step acceptable for contributors?
+- Is WCAG 2.2 AA a formal requirement?
+
+## Recommended order
+
+1. **[P0] `/impeccable harden`** — fix the utility layer (real Tailwind build
+   or define missing classes + button reset).
+2. **[P1] `/impeccable harden`** — focus-ring variables and `peer-focus`;
+   one shared accessible modal helper; name icon buttons and label fields;
+   live region on the captive page.
+3. **[P1] `/impeccable optimize`** — pause SSE/timers on hidden tab or page;
+   load widget scripts on demand.
+4. **[P1] `/impeccable colorize`** — move file-manager CSS and `.form-control`
+   onto theme tokens.
+5. **[P2] `/impeccable adapt`** — header wrap, touch targets, log height.
+6. **[P2] `/impeccable animate`** — reduced-motion alternatives.
+7. **`/impeccable polish`** — final pass.

docs/widget-guide.md

@@ -285,7 +285,9 @@ Guidelines:
 
 ### Step 1: Create Widget File
 
-Create a JavaScript file in your plugin directory. The recommended location is `widgets/[widget-name].js`:
+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
@@ -366,7 +368,29 @@ window.LEDMatrixWidgets.register('my-custom-widget', {
 });
 ```
 
-### Step 2: Reference Widget in Schema
+### 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`:
 
@@ -383,15 +407,30 @@ In your plugin's `config_schema.json`:
 }
 ```
 
-### Step 3: Widget Loading
+### Step 4: Widget Loading
 
-The widget will be automatically loaded when the plugin configuration form is rendered. The system will:
+The widget is loaded on demand when the plugin's configuration form renders a
+field that references it. The system will:
 
-1. Check if widget is registered in the core registry
-2. If not found, attempt to load from plugin directory: `/static/plugin-widgets/[plugin-id]/[widget-name].js`
-3. Render the widget using the registered `render` function
+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.
 
-**Note:** Currently, widgets are server-side rendered via Jinja2 templates. Custom widgets registered via the registry will have their handlers available, but full client-side rendering is a future enhancement.
+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
 
@@ -497,10 +536,11 @@ See [`web_interface/static/v3/js/widgets/example-color-picker.js`](../web_interf
 - ✅ Plugin widget loading system implemented
 
 **Current Behavior:**
-- Widgets are server-side rendered via Jinja2 templates (existing behavior preserved)
+- Core widgets are server-side rendered via Jinja2 templates (existing behavior preserved)
 - Widget handlers are registered and available globally
-- Custom widgets can be created and registered
-- Full client-side rendering is a future enhancement
+- 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

first_time_install.sh

@@ -125,6 +125,72 @@ fi
 # Get the home directory of the actual user
 USER_HOME=$(eval echo ~$ACTUAL_USER)
 
+# --- rpi-rgb-led-matrix checkout helpers -------------------------------------
+# Run git as whoever owns the project directory. Run as root against a
+# user-owned repo, git refuses it ("dubious ownership"), and anything it does
+# create — such as .git/modules/<submodule> — ends up root-owned, locking the
+# user out of their own checkout. A root-owned install keeps running as root.
+_rgb_repo_owner() {
+    stat -c %U "$PROJECT_ROOT_DIR" 2>/dev/null || echo root
+}
+
+_git_as_repo_owner() {
+    local owner
+    owner=$(_rgb_repo_owner)
+    if [ "$(id -u)" = "0" ] && [ "$owner" != "root" ] && command -v sudo >/dev/null 2>&1; then
+        sudo -u "$owner" -H git "$@"
+    else
+        git "$@"
+    fi
+}
+
+# Earlier installer versions ran the submodule git commands as root, leaving
+# root-owned files the repo owner (and so _git_as_repo_owner) cannot write.
+_reclaim_rgb_checkout() {
+    local owner path
+    owner=$(_rgb_repo_owner)
+    if [ "$(id -u)" != "0" ] || [ "$owner" = "root" ]; then
+        return 0
+    fi
+    for path in "$PROJECT_ROOT_DIR/rpi-rgb-led-matrix-master" "$PROJECT_ROOT_DIR/.git/modules/rpi-rgb-led-matrix-master"; do
+        if [ -e "$path" ]; then
+            chown -R "$owner:" "$path" 2>/dev/null || true
+        fi
+    done
+}
+
+# `git pull` on the main repo never moves an existing submodule checkout, so a
+# submodule bump (e.g. the ARMv6 build fix for Pi Zero/1) would never reach a
+# device installed before it. Move the checkout forward to the pinned commit —
+# but never backward or sideways: a user who ran `git submodule update --remote`
+# is newer than the pin and is left alone. Never fatal.
+_sync_rgb_submodule() {
+    local sub="$PROJECT_ROOT_DIR/rpi-rgb-led-matrix-master" pinned current
+    if [ ! -f "$PROJECT_ROOT_DIR/.gitmodules" ] || ! grep -q "rpi-rgb-led-matrix" "$PROJECT_ROOT_DIR/.gitmodules" \
+        || [ ! -e "$sub/.git" ]; then
+        return 0
+    fi
+    if ! pinned=$(_git_as_repo_owner -C "$PROJECT_ROOT_DIR" rev-parse "HEAD:rpi-rgb-led-matrix-master" 2>/dev/null) \
+        || [ -z "$pinned" ]; then
+        return 0
+    fi
+    current=$(_git_as_repo_owner -C "$sub" rev-parse HEAD 2>/dev/null) || current=""
+    if [ "$current" = "$pinned" ]; then
+        return 0
+    fi
+    if [ -n "$current" ] && _git_as_repo_owner -C "$sub" cat-file -e "${pinned}^{commit}" 2>/dev/null \
+        && ! _git_as_repo_owner -C "$sub" merge-base --is-ancestor "$current" "$pinned" 2>/dev/null; then
+        echo "rpi-rgb-led-matrix-master is at ${current:0:7}, not behind the pinned ${pinned:0:7}; leaving it as is"
+        return 0
+    fi
+    echo "Updating rpi-rgb-led-matrix-master to the pinned commit ${pinned:0:7}..."
+    if ! _git_as_repo_owner -C "$PROJECT_ROOT_DIR" submodule update --init --recursive rpi-rgb-led-matrix-master; then
+        echo "⚠ Could not update rpi-rgb-led-matrix-master to the pinned commit; building the existing checkout"
+    fi
+    return 0
+}
+# --- end rpi-rgb-led-matrix checkout helpers ---------------------------------
+
 # Determine the Project Root Directory (where this script is located)
 PROJECT_ROOT_DIR=$(cd "$(dirname "$0")" && pwd)
 
@@ -154,6 +220,8 @@ SKIP_PERF=${LEDMATRIX_SKIP_PERF:-0}
 SKIP_REBOOT_PROMPT=${LEDMATRIX_SKIP_REBOOT_PROMPT:-0}
 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:-}
 
 usage() {
     cat <<USAGE
@@ -168,12 +236,15 @@ Options:
       --skip-swap           Never add temporary swap for the C++ build
       --build-jobs N        Compile the C++ library with N parallel jobs
                             (default: scaled to available RAM)
+      --enable-auto-update  Turn on weekly automatic updates (with health
+                            check and automatic rollback)
+      --no-auto-update      Leave weekly automatic updates off
   -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_SKIP_SWAP=1, LEDMATRIX_BUILD_JOBS=N, LEDMATRIX_AUTO_UPDATE=1|0
 
 Low-memory devices:
   On a Pi with under 2GB of RAM the C++ build is limited to fewer parallel
@@ -191,6 +262,8 @@ while [ $# -gt 0 ]; do
         --skip-perf) SKIP_PERF=1 ;;
         --no-reboot-prompt) SKIP_REBOOT_PROMPT=1 ;;
         --skip-swap) SKIP_SWAP=1 ;;
+        --enable-auto-update) AUTO_UPDATE=1 ;;
+        --no-auto-update) AUTO_UPDATE=0 ;;
         --build-jobs)
             shift
             if [ $# -eq 0 ]; then echo "--build-jobs requires a number"; usage; exit 1; fi
@@ -797,6 +870,50 @@ else
     echo "✓ Main config file already exists"
 fi
 
+# Weekly automatic updates (General tab -> Automatic Updates). Off unless asked
+# for: --enable-auto-update / LEDMATRIX_AUTO_UPDATE=1, or "y" at the prompt when
+# installing interactively. Only an explicit choice changes the setting, so
+# re-running the installer with -y never switches it silently.
+if [ -z "$AUTO_UPDATE" ] && [ "$ASSUME_YES" != "1" ] && [ -t 0 ]; then
+    read -p "Automatically check for and install LEDMatrix updates once a week, with automatic rollback if an update breaks something? (y/N): " -n 1 -r
+    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'
+import json, os, sys, tempfile
+path, enabled = sys.argv[1], sys.argv[2] == "1"
+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
+# 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)
+fd, tmp = tempfile.mkstemp(dir=os.path.dirname(os.path.abspath(path)), prefix=".config.")
+try:
+    with os.fdopen(fd, "w", encoding="utf-8") as f:
+        json.dump(config, f, indent=4)
+        f.write("\n")
+        f.flush()
+        os.fsync(f.fileno())
+    os.chmod(tmp, original.st_mode & 0o777)
+    if hasattr(os, "chown"):
+        os.chown(tmp, original.st_uid, original.st_gid)
+    os.replace(tmp, path)
+except BaseException:
+    if os.path.exists(tmp):
+        os.unlink(tmp)
+    raise
+PY
+    then
+        if [ "$AUTO_UPDATE" = "1" ]; then echo "✓ Weekly automatic updates enabled"; else echo "✓ Weekly automatic updates off"; fi
+    else
+        echo "⚠ Could not set auto_update in config/config.json; turn it on from the General tab instead"
+    fi
+fi
+
 # Create config_secrets.json from template if missing
 if [ ! -f "$PROJECT_ROOT_DIR/config/config_secrets.json" ]; then
     if [ -f "$PROJECT_ROOT_DIR/config/config_secrets.template.json" ]; then
@@ -1038,8 +1155,9 @@ else
     # so git clone doesn't fail with "destination path already exists".
     _clone_rpi_rgb() {
         rm -rf "$PROJECT_ROOT_DIR/rpi-rgb-led-matrix-master"
-        git clone https://github.com/hzeller/rpi-rgb-led-matrix.git rpi-rgb-led-matrix-master
+        _git_as_repo_owner clone https://github.com/hzeller/rpi-rgb-led-matrix.git rpi-rgb-led-matrix-master
     }
+    _reclaim_rgb_checkout
     if [ ! -d "$PROJECT_ROOT_DIR/rpi-rgb-led-matrix-master" ]; then
         echo "rpi-rgb-led-matrix-master not found. Initializing git submodule..."
         cd "$PROJECT_ROOT_DIR"
@@ -1047,7 +1165,7 @@ else
         # Try to initialize submodule if .gitmodules exists
         if [ -f "$PROJECT_ROOT_DIR/.gitmodules" ] && grep -q "rpi-rgb-led-matrix" "$PROJECT_ROOT_DIR/.gitmodules"; then
             echo "Initializing rpi-rgb-led-matrix submodule..."
-            if ! retry git submodule update --init --recursive rpi-rgb-led-matrix-master; then
+            if ! retry _git_as_repo_owner submodule update --init --recursive rpi-rgb-led-matrix-master; then
                 echo "⚠ Submodule init failed, cloning directly from GitHub..."
                 retry _clone_rpi_rgb
             fi
@@ -1066,12 +1184,14 @@ else
             cd "$PROJECT_ROOT_DIR"
             rm -rf rpi-rgb-led-matrix-master
             if [ -f "$PROJECT_ROOT_DIR/.gitmodules" ] && grep -q "rpi-rgb-led-matrix" "$PROJECT_ROOT_DIR/.gitmodules"; then
-                retry git submodule update --init --recursive rpi-rgb-led-matrix-master
+                retry _git_as_repo_owner submodule update --init --recursive rpi-rgb-led-matrix-master
             else
                 retry _clone_rpi_rgb
             fi
         fi
 
+        _sync_rgb_submodule
+
         # Add temporary swap on low-memory devices so the compiler survives.
         CURRENT_STEP="Prepare the low-memory build environment"
         if [ "$LOWMEM_AVAILABLE" = "1" ] && [ "$SKIP_SWAP" != "1" ]; then
@@ -1272,7 +1392,7 @@ if [ -f "$PROJECT_ROOT_DIR/scripts/install/install_web_service.sh" ]; then
         fi
     fi
     
-    if [ ! -f "/etc/systemd/system/ledmatrix-web.service" ] || [ "$NEEDS_UPDATE" = true ]; then
+    if [ ! -f "/etc/systemd/system/ledmatrix-web.service" ] || [ ! -f "/etc/systemd/system/ledmatrix-update-verify.path" ] || [ "$NEEDS_UPDATE" = true ]; then
         bash "$PROJECT_ROOT_DIR/scripts/install/install_web_service.sh"
         # Ensure systemd sees any new/changed unit files
         systemctl daemon-reload || true
@@ -1288,7 +1408,7 @@ echo ""
 CURRENT_STEP="Harden systemd unit file permissions"
 echo "Step 8.1: Setting systemd unit file permissions..."
 echo "-----------------------------------------------"
-for unit in "/etc/systemd/system/ledmatrix.service" "/etc/systemd/system/ledmatrix-web.service" "/etc/systemd/system/ledmatrix-wifi-monitor.service"; do
+for unit in "/etc/systemd/system/ledmatrix.service" "/etc/systemd/system/ledmatrix-web.service" "/etc/systemd/system/ledmatrix-wifi-monitor.service" "/etc/systemd/system/ledmatrix-update-verify.service" "/etc/systemd/system/ledmatrix-update-verify.path"; do
     if [ -f "$unit" ]; then
         chown root:root "$unit" || true
         chmod 644 "$unit" || true
@@ -1416,6 +1536,9 @@ $ACTUAL_USER ALL=(ALL) NOPASSWD: $PYTHON_PATH $PROJECT_ROOT_DIR/display_controll
 $ACTUAL_USER ALL=(ALL) NOPASSWD: $BASH_PATH $PROJECT_ROOT_DIR/start_display.sh
 $ACTUAL_USER ALL=(ALL) NOPASSWD: $BASH_PATH $PROJECT_ROOT_DIR/stop_display.sh
 $ACTUAL_USER ALL=(ALL) NOPASSWD: $BASH_PATH $PROJECT_ROOT_DIR/scripts/fix_perms/safe_plugin_rm.sh *
+# 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 >> /tmp/ledmatrix_web_sudoers << EOF
@@ -1623,6 +1746,19 @@ chmod 755 "$PROJECT_ROOT_DIR/scripts/install/install_service.sh" "$PROJECT_ROOT_
 # Re-apply special permissions for config directory (lost during normalization)
 chmod 2775 "$PROJECT_ROOT_DIR/config" || true
 
+# Harden the sudo-granted helper scripts: root-owned, not writable by the web
+# user (matches scripts/install/configure_web_sudo.sh). The sudoers rules in
+# Step 10 run these as root, so a user-owned copy is a root shell for whoever
+# can edit it. This must come after Step 11's project-wide chown to
+# $ACTUAL_USER, which would otherwise hand them straight back.
+for helper in safe_plugin_rm.sh safe_pip_install.sh; do
+    HELPER_PATH="$PROJECT_ROOT_DIR/scripts/fix_perms/$helper"
+    if [ -f "$HELPER_PATH" ]; then
+        chown root:root "$HELPER_PATH" || echo "⚠ Could not set ownership on $HELPER_PATH"
+        chmod 755 "$HELPER_PATH" || echo "⚠ Could not set permissions on $HELPER_PATH"
+    fi
+done
+
 echo "✓ Project file permissions normalized"
 echo ""
 

plugin-repos/starlark-apps/manager.py

@@ -220,6 +220,8 @@ class StarlarkAppsPlugin(BasePlugin):
         # App storage
         self.apps_dir = self._get_apps_directory()
         self.manifest_file = self.apps_dir / "manifest.json"
+        # A dedicated, never-replaced file to flock -- see _update_manifest_safe.
+        self.manifest_lock_file = self.apps_dir / "manifest.json.lock"
         self.apps: Dict[str, StarlarkApp] = {}
 
         # Display state
@@ -564,7 +566,8 @@ class StarlarkAppsPlugin(BasePlugin):
     def _save_manifest(self, manifest: Dict[str, Any]) -> bool:
         """
         Save apps manifest to file with file locking to prevent race conditions.
-        Acquires exclusive lock on manifest file before writing to prevent concurrent modifications.
+        Acquires exclusive lock on the manifest lock sidecar before writing to
+        prevent concurrent modifications.
         """
         temp_file = None
         lock_fd = None
@@ -572,9 +575,14 @@ class StarlarkAppsPlugin(BasePlugin):
             # Create parent directory if needed
             self.manifest_file.parent.mkdir(parents=True, exist_ok=True)
 
-            # Open manifest file for locking (create if doesn't exist, don't truncate)
-            # Use os.open with O_CREAT | O_RDWR to create if missing, but don't truncate
-            lock_fd = os.open(str(self.manifest_file), os.O_CREAT | os.O_RDWR, 0o644)
+            # Lock the sidecar file, not manifest_file itself: manifest_file is
+            # replaced by an atomic rename below, which swaps in a fresh inode
+            # a second locker's fresh os.open() would pick up unguarded. The
+            # sidecar is never written to or renamed over, so it always
+            # resolves to the same inode for every locker (see
+            # _update_manifest_safe and web_interface's _starlark_manifest_lock,
+            # which must lock this same file for the guarantee to hold).
+            lock_fd = os.open(str(self.manifest_lock_file), os.O_CREAT | os.O_RDWR, 0o644)
 
             # Acquire exclusive lock on manifest file BEFORE creating temp file
             # This serializes all writers and prevents concurrent races
@@ -630,8 +638,9 @@ class StarlarkAppsPlugin(BasePlugin):
             # Create parent directory if needed
             self.manifest_file.parent.mkdir(parents=True, exist_ok=True)
 
-            # Open manifest file for locking (create if doesn't exist, don't truncate)
-            lock_fd = os.open(str(self.manifest_file), os.O_CREAT | os.O_RDWR, 0o644)
+            # Lock the sidecar file, not manifest_file itself -- see the
+            # comment in _save_manifest for why.
+            lock_fd = os.open(str(self.manifest_lock_file), os.O_CREAT | os.O_RDWR, 0o644)
 
             # Acquire exclusive lock for entire read-modify-write cycle
             fcntl.flock(lock_fd, fcntl.LOCK_EX)
@@ -796,15 +805,25 @@ class StarlarkAppsPlugin(BasePlugin):
             magnify = self._get_effective_magnify()
             self.logger.debug(f"Using magnify={magnify} for {app.app_id}")
 
-            # Filter out LEDMatrix-internal timing keys before passing to pixlet
-            INTERNAL_KEYS = {'render_interval', 'display_duration'}
+            # Optional native render size for an app whose own declared canvas
+            # differs from Pixlet's 64x32 default -- without this an app
+            # declaring a wider native canvas got half its own content
+            # clipped at render time, before magnify ever got a chance to
+            # scale anything.
+            render_width = app.config.get("render_width")
+            render_height = app.config.get("render_height")
+
+            # Filter out LEDMatrix-internal timing/sizing keys before passing to pixlet
+            INTERNAL_KEYS = {'render_interval', 'display_duration', 'render_width', 'render_height'}
             pixlet_config = {k: v for k, v in app.config.items() if k not in INTERNAL_KEYS}
 
             success, error = self.pixlet.render(
                 star_file=str(app.star_file),
                 output_path=str(app.cache_file),
                 config=pixlet_config,
-                magnify=magnify
+                magnify=magnify,
+                width=render_width,
+                height=render_height
             )
 
             if not success:

plugin-repos/starlark-apps/pixlet_renderer.py

@@ -218,7 +218,9 @@ class PixletRenderer:
         star_file: str,
         output_path: str,
         config: Optional[Dict[str, Any]] = None,
-        magnify: int = 1
+        magnify: int = 1,
+        width: Optional[int] = None,
+        height: Optional[int] = None
     ) -> Tuple[bool, Optional[str]]:
         """
         Render a .star file to WebP output.
@@ -228,6 +230,21 @@ class PixletRenderer:
             output_path: Where to save WebP output
             config: Configuration dictionary to pass to app
             magnify: Magnification factor (default 1)
+            width: Optional native render width in pixels. Previously
+                there was no way to tell Pixlet to render at anything
+                other than its own default (64), relying entirely on
+                magnify to scale up afterward -- fine for apps designed
+                at that native size, but wrong for an app whose own
+                declared canvas size is genuinely different (confirmed
+                on real hardware, 2026-09-06, with an imported app
+                declaring width=128: rendering at the default 64 and
+                then magnifying silently clipped half the app's own
+                content before scaling ever happened, rather than
+                producing a correctly-sized image). Passed through as
+                Pixlet's own -w flag when provided; omitted (Pixlet's
+                default) otherwise, preserving existing behavior for
+                every other app.
+            height: Same as width, for Pixlet's -t flag.
 
         Returns:
             Tuple of (success: bool, error_message: Optional[str])
@@ -287,6 +304,10 @@ class PixletRenderer:
                 "-o", output_path,
                 "-m", str(magnify)
             ])
+            if width is not None:
+                cmd.extend(["-w", str(width)])
+            if height is not None:
+                cmd.extend(["-t", str(height)])
 
             # Build sanitized command for logging (redact sensitive values)
             sanitized_cmd = [self.pixlet_binary, "render", star_file]
@@ -294,6 +315,10 @@ class PixletRenderer:
                 config_keys = list(config.keys())
                 sanitized_cmd.append(f"[{len(config_keys)} config entries: {', '.join(config_keys)}]")
             sanitized_cmd.extend(["-o", output_path, "-m", str(magnify)])
+            if width is not None:
+                sanitized_cmd.extend(["-w", str(width)])
+            if height is not None:
+                sanitized_cmd.extend(["-t", str(height)])
             logger.debug(f"Executing Pixlet: {' '.join(sanitized_cmd)}")
 
             # Execute rendering

requirements.txt

@@ -43,10 +43,14 @@ packaging>=23.0,<27.0
 # full feature set, or skip them for a minimal install.
 # ───────────────────────────────────────────────────────────────────────
 #
-# scipy             — sub-pixel interpolation in
-#                     src/common/scroll_helper.py for smoother
-#                     scrolling. Falls back to a simpler shift algorithm.
-#   pip install 'scipy>=1.10.0,<2.0.0'
+# scipy             — nothing, as of #570. It was listed for the sub-pixel
+#                     interpolation path in src/common/scroll_helper.py, but
+#                     get_visible_portion never consulted HAS_SCIPY, so that
+#                     path was dead before it was deleted. The blend that
+#                     replaced it is numpy-only. Do not install it expecting
+#                     smoother scrolling: sub-pixel blending is off by default
+#                     because it reads worse on a coarse panel, not because it
+#                     is missing a library. See docs/SCROLL_PERFORMANCE.md.
 #
 # psutil            — per-plugin resource monitoring in
 #                     src/plugin_system/resource_monitor.py. The monitor

schema/manifest_schema.json

@@ -257,6 +257,30 @@
       },
       "description": "Web UI action definitions"
     },
+    "widgets": {
+      "type": "array",
+      "description": "Custom web-UI widgets this plugin provides. Each entry is served at /static/plugin-widgets/<plugin-id>/<name>.js from the plugin's widgets/ directory; only declared widgets are served. Reference one from config_schema.json with \"x-widget\": \"<name>\".",
+      "items": {
+        "type": "object",
+        "required": ["name"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9_-]{1,64}$",
+            "description": "Widget name, as used in x-widget and in the URL."
+          },
+          "script": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9_-]{1,64}\\.js$",
+            "description": "Filename inside widgets/. Defaults to <name>.js."
+          },
+          "description": {
+            "type": "string",
+            "description": "Human-readable summary shown to plugin authors."
+          }
+        }
+      }
+    },
     "ledmatrix_version": {
       "type": "string",
       "description": "Deprecated: Use compatible_versions instead. LEDMatrix version this plugin targets"

scripts/check_plugin.py

@@ -35,6 +35,31 @@ sys.path.insert(0, str(PROJECT_ROOT))
 
 os.environ['EMULATOR'] = 'true'
 
+
+def _make_output_encoding_safe() -> None:
+    """Stop an unencodable character from killing the run.
+
+    This script's own report is ASCII, but it echoes text it does not control
+    -- plugin ids, mode names and exception messages -- and a Windows console
+    is cp1252, which cannot encode most of what a plugin might put there. The
+    default 'strict' error handler turns that into a UnicodeEncodeError from
+    inside `print`, so a rendering run that had already succeeded exited
+    non-zero with a traceback instead of printing its results.
+
+    'replace' degrades the offending character to '?' and keeps going; the
+    encoding itself is left alone so output still matches the terminal.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(errors='replace')
+        except (AttributeError, ValueError, OSError):
+            # Not a reconfigurable TextIOWrapper (redirected, wrapped by a
+            # test harness). Nothing to do -- this is best-effort hardening.
+            pass
+
+
+_make_output_encoding_safe()
+
 from src.logging_config import get_logger  # noqa: E402
 from src.plugin_system.testing.loading import (  # noqa: E402
     build_full_config, find_plugin_dir, load_harness_spec, load_manifest,
@@ -53,6 +78,9 @@ logger = get_logger("[Check Plugin]")
 DEFAULT_SEARCH_DIRS = [
     str(PROJECT_ROOT / 'plugins'),
     str(PROJECT_ROOT / 'plugin-repos'),
+    # The scoreboards live in the sibling ledmatrix-plugins checkout, not
+    # in this repo. Without this, --all silently skips every one of them.
+    str(PROJECT_ROOT.parent / 'ledmatrix-plugins' / 'plugins'),
 ]
 
 
@@ -178,7 +206,7 @@ def print_report(all_results: Dict[str, List[RenderResult]]) -> bool:
                 status = "PASS"
                 detail = ""
                 if r.golden_checked:
-                    detail = " (golden ✓)"
+                    detail = " (golden ok)"
                 if r.update_error is not None:
                     detail += f" (update warn: {r.update_error})"
                 if r.fill_checked and r.fill_ok is None and r.fill_extent:
@@ -196,7 +224,7 @@ def print_report(all_results: Dict[str, List[RenderResult]]) -> bool:
                     status, detail = "FAIL", f" overflow bbox={r.overflow}"
                 elif r.golden_ok is False:
                     status = "FAIL"
-                    detail = f" golden drift: {r.golden_diff_pixels}px (max Δ={r.golden_max_delta})"
+                    detail = f" golden drift: {r.golden_diff_pixels}px (max delta={r.golden_max_delta})"
                 elif r.fill_ok is False:
                     ex, ey = r.fill_extent or (0.0, 0.0)
                     status = "FAIL"

scripts/dev/vegas_audit.py

@@ -72,12 +72,8 @@ def load_main_config(path: Path) -> Dict[str, Any]:
 
 def display_size_from_config(config: Dict[str, Any]) -> tuple:
     """Derive the logical ticker size the way DisplayManager does."""
-    hw = config.get('display', {}).get('hardware', {})
-    cols = int(hw.get('cols', 64))
-    chain = int(hw.get('chain_length', 1))
-    rows = int(hw.get('rows', 32))
-    parallel = int(hw.get('parallel', 1))
-    return cols * chain, rows * parallel
+    from src.display_geometry import logical_size
+    return logical_size(config)
 
 
 def enabled_plugin_ids(config: Dict[str, Any]) -> List[str]:

scripts/dev_server.py

@@ -32,6 +32,8 @@ os.environ['EMULATOR'] = 'true'
 
 from flask import Flask, render_template, request, jsonify
 
+from src.common.path_safety import resolve_under, safe_path_component
+
 app = Flask(__name__, template_folder=str(Path(__file__).parent / 'templates'))
 
 logger = logging.getLogger(__name__)
@@ -118,7 +120,8 @@ def find_plugin_dir(plugin_id: str) -> Optional[Path]:
     one of the plugin search dirs, so a crafted id can never name a path
     outside them.
     """
-    if not isinstance(plugin_id, str) or not _SAFE_PLUGIN_ID_RE.match(plugin_id):
+    plugin_id = safe_path_component(plugin_id)
+    if not plugin_id or not _SAFE_PLUGIN_ID_RE.match(plugin_id):
         return None
     from src.plugin_system.plugin_loader import PluginLoader
     loader = PluginLoader()
@@ -140,8 +143,8 @@ def find_plugin_dir(plugin_id: str) -> Optional[Path]:
 
 def load_config_defaults(plugin_dir: 'str | Path') -> Dict[str, Any]:
     """Extract default values from config_schema.json."""
-    schema_path = Path(plugin_dir) / 'config_schema.json'
-    if not schema_path.exists():
+    schema_path = resolve_under(plugin_dir, 'config_schema.json')
+    if schema_path is None or not schema_path.exists():
         return {}
     with open(schema_path, 'r') as f:
         schema = json.load(f)
@@ -175,8 +178,8 @@ def api_plugin_schema(plugin_id):
     if not plugin_dir:
         return jsonify({'error': f'Plugin not found: {plugin_id}'}), 404
 
-    schema_path = plugin_dir / 'config_schema.json'
-    if not schema_path.exists():
+    schema_path = resolve_under(plugin_dir, 'config_schema.json')
+    if schema_path is None or not schema_path.exists():
         return jsonify({'schema': {'type': 'object', 'properties': {}}})
 
     with open(schema_path, 'r') as f:

scripts/install/install_service.sh

@@ -16,20 +16,39 @@ USER_HOME=$(eval echo ~$ACTUAL_USER)
 # Determine the Project Root Directory (parent of scripts/install/)
 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"
+
 echo "Installing LED Matrix Display Service for user: $ACTUAL_USER"
 echo "Using home directory: $USER_HOME"
 echo "Project root directory: $PROJECT_ROOT_DIR"
 
-# Create a temporary service file for the main display with the correct paths
-# Assuming ledmatrix.service template exists and uses /home/ledpi as a placeholder for user home
+# Render the main display unit from its template. The display service runs as
+# root (it needs GPIO), so __USER__ is always root here -- unlike the web unit
+# below, which runs as whoever installed it.
+#
+# A missing template or a failed render is fatal: falling through would leave
+# whatever unit already sits at /etc/systemd/system/ledmatrix.service (from a
+# previous install) untouched, and the enable/start step below would then
+# silently reuse that stale unit instead of the one this run was asked to
+# install.
 if [ -f "$PROJECT_ROOT_DIR/systemd/ledmatrix.service" ]; then
-    sed "s|/home/ledpi|$USER_HOME|g; s|__PROJECT_ROOT_DIR__|$PROJECT_ROOT_DIR|g; s|__USER__|root|g" "$PROJECT_ROOT_DIR/systemd/ledmatrix.service" > /tmp/ledmatrix.service.tmp
+    ESCAPED_PROJECT_ROOT_DIR=$(sed_escape_replacement "$PROJECT_ROOT_DIR")
+    MAIN_UNIT_TMP=$(mktemp)
+    trap 'rm -f "$MAIN_UNIT_TMP"' EXIT
+    if ! sed "s|__PROJECT_ROOT_DIR__|$ESCAPED_PROJECT_ROOT_DIR|g; s|__USER__|root|g" \
+        "$PROJECT_ROOT_DIR/systemd/ledmatrix.service" > "$MAIN_UNIT_TMP"; then
+        echo "ERROR: failed to render ledmatrix.service from its template." >&2
+        exit 1
+    fi
     # Copy the service file to the systemd directory
-    sudo cp /tmp/ledmatrix.service.tmp /etc/systemd/system/ledmatrix.service
+    sudo cp "$MAIN_UNIT_TMP" /etc/systemd/system/ledmatrix.service
     # Clean up
-    rm /tmp/ledmatrix.service.tmp
+    rm -f "$MAIN_UNIT_TMP"
+    trap - EXIT
 else
-    echo "WARNING: ledmatrix.service template not found at $PROJECT_ROOT_DIR/systemd/ledmatrix.service. Main display service not configured."
+    echo "ERROR: ledmatrix.service template not found at $PROJECT_ROOT_DIR/systemd/ledmatrix.service." >&2
+    exit 1
 fi
 
 
@@ -48,42 +67,67 @@ fi
 # === LEDMatrix Web Interface service (ledmatrix-web.service) ===
 echo "Installing LEDMatrix Web Interface service (ledmatrix-web.service)..."
 
-WEB_SERVICE_FILE_CONTENT=$(cat <<EOF
-[Unit]
-Description=LED Matrix Web Interface (Conditional Start)
-After=network.target
-# Wants=ledmatrix.service
-# After=network.target ledmatrix.service
+# Rendered from systemd/ledmatrix-web.service, the same template
+# install_web_service.sh uses. This was an inline heredoc until it drifted from
+# the template: it had lost Wants=network-online.target, RestartSec,
+# SyslogIdentifier, CacheDirectory and Environment=USE_THREADING. Because
+# src/startup_validator.py compares the installed unit against the template,
+# every boot warned "re-run install_service.sh" -- and doing so reinstalled the
+# same stale copy, so the warning could never clear.
+#
+# As with the main unit above, a missing template or a failed render is
+# fatal -- otherwise the enable/start check below would fall back to
+# whatever unit (possibly stale) already exists at the destination path.
+if [ -f "$PROJECT_ROOT_DIR/systemd/ledmatrix-web.service" ]; then
+    ESCAPED_ACTUAL_USER=$(sed_escape_replacement "$ACTUAL_USER")
+    WEB_UNIT_TMP=$(mktemp)
+    trap 'rm -f "$WEB_UNIT_TMP"' EXIT
+    if ! sed "s|__PROJECT_ROOT_DIR__|$ESCAPED_PROJECT_ROOT_DIR|g; s|__USER__|$ESCAPED_ACTUAL_USER|g" \
+        "$PROJECT_ROOT_DIR/systemd/ledmatrix-web.service" > "$WEB_UNIT_TMP"; then
+        echo "ERROR: failed to render ledmatrix-web.service from its template." >&2
+        exit 1
+    fi
+    sudo cp "$WEB_UNIT_TMP" /etc/systemd/system/ledmatrix-web.service
+    rm -f "$WEB_UNIT_TMP"
+    trap - EXIT
+else
+    echo "ERROR: ledmatrix-web.service template not found at $PROJECT_ROOT_DIR/systemd/ledmatrix-web.service." >&2
+    exit 1
+fi
 
-[Service]
-Type=simple
-ExecStart=/usr/bin/python3 ${PROJECT_ROOT_DIR}/scripts/utils/start_web_conditionally.py
-WorkingDirectory=${PROJECT_ROOT_DIR}
-StandardOutput=journal
-StandardError=journal
-User=${ACTUAL_USER}
-Restart=on-failure
-# Environment="PYTHONUNBUFFERED=1"
-
-[Install]
-WantedBy=multi-user.target
-EOF
-)
-
-# Write the new service file
-echo "$WEB_SERVICE_FILE_CONTENT" | sudo tee /etc/systemd/system/ledmatrix-web.service > /dev/null
+# Health check / rollback units for automatic updates; see install_web_service.sh.
+for VERIFY_UNIT in ledmatrix-update-verify.service ledmatrix-update-verify.path; do
+    if [ -f "$PROJECT_ROOT_DIR/systemd/$VERIFY_UNIT" ]; then
+        VERIFY_UNIT_TMP=$(mktemp)
+        if sed "s|__PROJECT_ROOT_DIR__|$ESCAPED_PROJECT_ROOT_DIR|g; s|__USER__|$ESCAPED_ACTUAL_USER|g" "$PROJECT_ROOT_DIR/systemd/$VERIFY_UNIT" > "$VERIFY_UNIT_TMP"; then
+            sudo cp "$VERIFY_UNIT_TMP" "/etc/systemd/system/$VERIFY_UNIT"
+        else
+            echo "WARNING: failed to render $VERIFY_UNIT; automatic code updates will stay paused." >&2
+        fi
+        rm -f "$VERIFY_UNIT_TMP"
+    fi
+done
 
 echo "Reloading systemd daemon for web service..."
 sudo systemctl daemon-reload
 
-echo "Enabling ledmatrix-web.service to start on boot..."
-sudo systemctl enable ledmatrix-web.service
+if [ -f "/etc/systemd/system/ledmatrix-web.service" ]; then
+    echo "Enabling ledmatrix-web.service to start on boot..."
+    sudo systemctl enable ledmatrix-web.service
 
-echo "Starting ledmatrix-web.service..."
-sudo systemctl start ledmatrix-web.service
+    if [ -f /etc/systemd/system/ledmatrix-update-verify.path ]; then
+        echo "Enabling ledmatrix-update-verify.path (automatic update health check)..."
+        sudo systemctl enable --now ledmatrix-update-verify.path || echo "WARNING: could not enable ledmatrix-update-verify.path; automatic code updates will stay paused" >&2
+    fi
 
-echo "LEDMatrix Web Interface service (ledmatrix-web.service) installation complete."
-echo "It will start based on the 'web_display_autostart' setting in config/config.json."
+    echo "Starting ledmatrix-web.service..."
+    sudo systemctl start ledmatrix-web.service
+
+    echo "LEDMatrix Web Interface service (ledmatrix-web.service) installation complete."
+    echo "It will start based on the 'web_display_autostart' setting in config/config.json."
+else
+    echo "Skipping enable/start for ledmatrix-web.service as it was not configured."
+fi
 # === End of LEDMatrix Web Interface service ===
 
 

scripts/install/install_web_service.sh

@@ -17,6 +17,9 @@ fi
 # Determine the Project Root Directory (parent of scripts/install/)
 PROJECT_ROOT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
 
+# shellcheck source=scripts/install/lib_systemd_render.sh
+source "$PROJECT_ROOT_DIR/scripts/install/lib_systemd_render.sh"
+
 echo "Installing for user: $ACTUAL_USER"
 echo "Project root directory: $PROJECT_ROOT_DIR"
 
@@ -26,37 +29,38 @@ if [ "$EUID" -ne 0 ]; then
     exit 1
 fi
 
-# Generate the service file dynamically with the correct paths
-echo "Generating service file with dynamic paths..."
-WEB_SERVICE_FILE_CONTENT=$(cat <<EOF
-[Unit]
-Description=LED Matrix Web Interface Service
-After=network-online.target
-Wants=network-online.target
+# Render the unit from systemd/ledmatrix-web.service. That template is the
+# only description of the unit; this script used to carry its own heredoc copy,
+# and install_service.sh a third, which is how the installed unit on real rigs
+# ended up missing RestartSec, SyslogIdentifier and CacheDirectory while
+# src/startup_validator.py warned about drift on every boot.
+TEMPLATE="$PROJECT_ROOT_DIR/systemd/ledmatrix-web.service"
+if [ ! -f "$TEMPLATE" ]; then
+    echo "ERROR: unit template not found at $TEMPLATE"
+    exit 1
+fi
 
-[Service]
-Type=simple
-User=${ACTUAL_USER}
-WorkingDirectory=${PROJECT_ROOT_DIR}
-Environment=USE_THREADING=1
-ExecStart=/usr/bin/python3 ${PROJECT_ROOT_DIR}/scripts/utils/start_web_conditionally.py
-Restart=on-failure
-RestartSec=10
-StandardOutput=syslog
-StandardError=syslog
-SyslogIdentifier=ledmatrix-web
-# Automatically create and manage cache directory
-CacheDirectory=ledmatrix
-CacheDirectoryMode=0775
-
-[Install]
-WantedBy=multi-user.target
-EOF
-)
-
-# Write the service file to systemd directory
 echo "Writing service file to /etc/systemd/system/ledmatrix-web.service"
-echo "$WEB_SERVICE_FILE_CONTENT" > /etc/systemd/system/ledmatrix-web.service
+ESCAPED_PROJECT_ROOT_DIR=$(sed_escape_replacement "$PROJECT_ROOT_DIR")
+ESCAPED_ACTUAL_USER=$(sed_escape_replacement "$ACTUAL_USER")
+sed "s|__PROJECT_ROOT_DIR__|$ESCAPED_PROJECT_ROOT_DIR|g; s|__USER__|$ESCAPED_ACTUAL_USER|g" \
+    "$TEMPLATE" > /etc/systemd/system/ledmatrix-web.service
+
+# Health check and rollback for the web UI's automatic updates. Its own unit so
+# it survives the web service restart it performs; never enabled -- the web
+# interface starts it after an update. Without it, automatic code updates
+# stay paused rather than running with nothing to undo them.
+for VERIFY_UNIT in ledmatrix-update-verify.service ledmatrix-update-verify.path; do
+    VERIFY_TEMPLATE="$PROJECT_ROOT_DIR/systemd/$VERIFY_UNIT"
+    if [ -f "$VERIFY_TEMPLATE" ]; then
+        echo "Writing unit file to /etc/systemd/system/$VERIFY_UNIT"
+        sed "s|__PROJECT_ROOT_DIR__|$ESCAPED_PROJECT_ROOT_DIR|g; s|__USER__|$ESCAPED_ACTUAL_USER|g" \
+            "$VERIFY_TEMPLATE" > "/etc/systemd/system/$VERIFY_UNIT"
+        chmod 644 "/etc/systemd/system/$VERIFY_UNIT"
+    else
+        echo "WARNING: $VERIFY_TEMPLATE not found; automatic code updates will stay paused"
+    fi
+done
 
 # Ensure cache directory exists with proper permissions
 # This is a fallback for older systemd versions that don't support CacheDirectory
@@ -92,6 +96,13 @@ systemctl daemon-reload
 echo "Enabling ledmatrix-web.service..."
 systemctl enable ledmatrix-web.service
 
+# The path unit is what starts the health check after an automatic update.
+if [ -f /etc/systemd/system/ledmatrix-update-verify.path ]; then
+    echo "Enabling ledmatrix-update-verify.path..."
+    systemctl enable --now ledmatrix-update-verify.path || \
+        echo "WARNING: could not enable ledmatrix-update-verify.path; automatic code updates will stay paused"
+fi
+
 # Start the service
 echo "Starting ledmatrix-web.service..."
 systemctl start ledmatrix-web.service

scripts/install/install_wifi_monitor.sh

@@ -18,6 +18,9 @@ USER_HOME=$(eval echo ~$ACTUAL_USER)
 # Determine the Project Root Directory (parent of scripts/install/)
 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"
+
 echo "Installing LED Matrix WiFi Monitor Service for user: $ACTUAL_USER"
 echo "Using home directory: $USER_HOME"
 echo "Project root directory: $PROJECT_ROOT_DIR"
@@ -64,30 +67,19 @@ if [ ${#MISSING_PACKAGES[@]} -gt 0 ]; then
     echo "✓ Package installation completed"
 fi
 
-# Create service file with correct paths
+# Render the unit from systemd/ledmatrix-wifi-monitor.service rather than
+# inlining a second copy here. The copy this replaced had already drifted --
+# it wrote StandardOutput/StandardError=syslog where the template says journal.
 echo ""
 echo "Creating systemd service file..."
-SERVICE_FILE_CONTENT=$(cat <<EOF
-[Unit]
-Description=LED Matrix WiFi Monitor Daemon
-After=network.target
-Wants=network.target
+TEMPLATE="$PROJECT_ROOT_DIR/systemd/ledmatrix-wifi-monitor.service"
+if [ ! -f "$TEMPLATE" ]; then
+    echo "ERROR: unit template not found at $TEMPLATE"
+    exit 1
+fi
 
-[Service]
-Type=simple
-User=root
-WorkingDirectory=$PROJECT_ROOT_DIR
-ExecStart=/usr/bin/python3 $PROJECT_ROOT_DIR/scripts/utils/wifi_monitor_daemon.py --interval 30
-Restart=on-failure
-RestartSec=10
-StandardOutput=syslog
-StandardError=syslog
-SyslogIdentifier=ledmatrix-wifi-monitor
-
-[Install]
-WantedBy=multi-user.target
-EOF
-)
+ESCAPED_PROJECT_ROOT_DIR=$(sed_escape_replacement "$PROJECT_ROOT_DIR")
+SERVICE_FILE_CONTENT=$(sed "s|__PROJECT_ROOT_DIR__|$ESCAPED_PROJECT_ROOT_DIR|g; s|__USER__|root|g" "$TEMPLATE")
 
 if [ "$EUID" -eq 0 ]; then
     echo "$SERVICE_FILE_CONTENT" | tee /etc/systemd/system/ledmatrix-wifi-monitor.service > /dev/null

scripts/install/lib_systemd_render.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+#
+# 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.
+
+# sed_escape_replacement VALUE
+#
+# Print VALUE escaped for safe use as the replacement side of `sed
+# s|pattern|replacement|`. Every one of these scripts builds its sed
+# expression by interpolating a shell variable (a path, a username, ...)
+# straight into the replacement text. sed gives three characters special
+# meaning there: backslash (escape character), & (whole match) and the
+# delimiter itself (here `|`). A value containing any of them -- e.g. a
+# username or path with an `&`, a literal backslash, or a `|` -- would
+# otherwise corrupt the rendered unit file instead of being substituted
+# literally. Escape the backslash first so the later escapes aren't
+# double-escaped.
+sed_escape_replacement() {
+    local value="$1"
+    value="${value//\\/\\\\}"
+    value="${value//&/\\&}"
+    value="${value//|/\\|}"
+    printf '%s' "$value"
+}

scripts/install/one-shot-install.sh

@@ -408,6 +408,7 @@ main() {
         # which would silently reinstate the duplicate apt update.
         sudo -E env TMPDIR=/tmp LEDMATRIX_ASSUME_YES=1 \
             LEDMATRIX_APT_UPDATED="${LEDMATRIX_APT_UPDATED:-0}" \
+            LEDMATRIX_AUTO_UPDATE="${LEDMATRIX_AUTO_UPDATE:-}" \
             bash ./first_time_install.sh -y </dev/null
     fi
     INSTALL_EXIT_CODE=$?

scripts/scroll_speeds.py

@@ -59,10 +59,13 @@ def build_options(hardware, refresh_override=None):
     from rgbmatrix import RGBMatrixOptions
 
     o = RGBMatrixOptions()
-    o.rows = int(hardware.get("rows", 32))
-    o.cols = int(hardware.get("cols", 64))
-    o.chain_length = int(hardware.get("chain_length", 1))
-    o.parallel = int(hardware.get("parallel", 1))
+    from src.display_geometry import (
+        DEFAULT_CHAIN_LENGTH, DEFAULT_COLS, DEFAULT_PARALLEL, DEFAULT_ROWS,
+    )
+    o.rows = int(hardware.get("rows", DEFAULT_ROWS))
+    o.cols = int(hardware.get("cols", DEFAULT_COLS))
+    o.chain_length = int(hardware.get("chain_length", DEFAULT_CHAIN_LENGTH))
+    o.parallel = int(hardware.get("parallel", DEFAULT_PARALLEL))
     o.brightness = int(hardware.get("brightness", 80))
     o.hardware_mapping = hardware.get("hardware_mapping", "regular")
     o.pwm_bits = int(hardware.get("pwm_bits", 11))

scripts/utils/auto_update_verify.py

@@ -0,0 +1,277 @@
+#!/usr/bin/env python3
+"""Check that an automatic LEDMatrix update left the device working; roll it back if not.
+
+Started by the web interface's weekly updater (web_interface/auto_update.py)
+through ledmatrix-update-verify.service, right after it pulls new code. It has
+to run outside the web service: checking the update means restarting that
+service, and a check running inside it would be killed by its own restart.
+
+It must not be the code it is checking, either. The updater copies this file
+to data/auto_update_verifier.py *before* pulling and the unit runs that copy,
+so a broken update cannot break its own rollback. Standard library only for
+the same reason: the rollback cannot depend on packages the update changed.
+
+The updater leaves data/auto_update_pending.json:
+
+    {"status": "pending", "old_head": ..., "new_head": ...,
+     "display_was_active": bool, "dependency_failures": [...], "created_at": ...}
+
+This moves its status to "verifying" and then to one of "success",
+"rolled_back" or "rollback_failed", with "reason" and "detail" saying why.
+The web interface reports that outcome and raises a banner for anything but
+success.
+"""
+import json
+import os
+import subprocess  # nosec B404 - list-form argv only, no shell  # nosemgrep
+import sys
+from collections import namedtuple
+import tempfile
+import time
+import traceback
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+PENDING_NAME = 'auto_update_pending.json'
+REQUIREMENT_FILES = ('requirements.txt', 'web_interface/requirements.txt')
+WEB_HEALTH_URL = 'http://127.0.0.1:5000/api/v3/system/version'
+#: How long the services get to come up after a restart...
+HEALTH_TIMEOUT_SECONDS = 180
+#: ...and how long they must then stay up. Restart=on-failure makes a crash
+#: loop look healthy between attempts, so a single "is-active" proves nothing.
+STABLE_SECONDS = 45
+POLL_SECONDS = 5
+PIP_TIMEOUT_SECONDS = 600
+#: sudoers matches the exact command line, so bash is named by path, the same
+#: candidates src/common/permission_utils.install_requirements_file tries.
+BASH_CANDIDATES = ('/usr/bin/bash', '/bin/bash')
+
+#: What a command that could not run at all reports: its callers only read
+#: these three fields, the same ones a completed subprocess has.
+_Failed = namedtuple('_Failed', 'returncode stdout stderr')
+
+
+def pending_path(project_root):
+    return Path(project_root) / 'data' / PENDING_NAME
+
+
+def read_pending(path):
+    try:
+        with open(path, 'r', encoding='utf-8') as f:
+            data = json.load(f)
+        return data if isinstance(data, dict) else None
+    except (OSError, ValueError):
+        return None
+
+
+def write_pending(path, data):
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix='.auto_update_pending_')
+    try:
+        with os.fdopen(fd, 'w', encoding='utf-8') as f:
+            json.dump(data, f, indent=2)
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def _web_responds(url=WEB_HEALTH_URL):
+    try:
+        with urllib.request.urlopen(url, timeout=5) as resp:  # nosec B310 - fixed loopback URL
+            return resp.status == 200
+    except (urllib.error.URLError, OSError, ValueError):
+        return False
+
+
+def _short(sha):
+    return (sha or 'unknown')[:7]
+
+
+class Verifier:
+    def __init__(self, project_root, run=subprocess.run, sleep=time.sleep,
+                 clock=time.monotonic, web_responds=_web_responds, log=None):
+        self.project_root = Path(project_root)
+        self.pending_file = pending_path(project_root)
+        self.run = run
+        self.sleep = sleep
+        self.clock = clock
+        self.web_responds = web_responds
+        self.log = log or (lambda msg: print(f'[auto-update-verify] {msg}', flush=True))
+
+    def _run(self, args, timeout=60):
+        try:
+            return self.run(args, cwd=str(self.project_root), capture_output=True,
+                            text=True, timeout=timeout)
+        except (subprocess.SubprocessError, OSError) as e:
+            return _Failed(returncode=1, stdout='', stderr=str(e))
+
+    # -- services ---------------------------------------------------------
+
+    def service_active(self, unit):
+        return self._run(['systemctl', 'is-active', unit], timeout=10).stdout.strip() == 'active'
+
+    def restart_count(self, unit):
+        out = self._run(['systemctl', 'show', '-p', 'NRestarts', '--value', unit],
+                        timeout=10).stdout.strip()
+        return int(out) if out.isdigit() else None
+
+    def restart(self, unit):
+        result = self._run(['sudo', '-n', 'systemctl', 'restart', f'{unit}.service'], timeout=90)
+        if result.returncode != 0:
+            self.log(f'restarting {unit} failed: {(result.stderr or "").strip()}')
+        return result.returncode == 0
+
+    def restart_services(self, display):
+        """Restart what should be running. False if any restart command failed."""
+        ok = True
+        # A display the user had stopped stays stopped.
+        if display:
+            ok = self.restart('ledmatrix') and ok
+        return self.restart('ledmatrix-web') and ok
+
+    def wait_healthy(self, display):
+        """None once the services are up and stay up, else what went wrong."""
+        deadline = self.clock() + HEALTH_TIMEOUT_SECONDS + STABLE_SECONDS
+        healthy_since = baseline = None
+        web = disp = False
+        count_known = True
+        while self.clock() < deadline:
+            web = self.web_responds()
+            disp = self.service_active('ledmatrix') if display else True
+            restarts = self.restart_count('ledmatrix') if display else None
+            # Without a restart count a crash loop looks healthy between
+            # attempts, so an unreadable count never counts as stable.
+            count_known = not display or restarts is not None
+            if web and disp and count_known and (healthy_since is None or restarts == baseline):
+                if healthy_since is None:
+                    healthy_since, baseline = self.clock(), restarts
+                elif self.clock() - healthy_since >= STABLE_SECONDS:
+                    return None
+            else:
+                healthy_since = None
+            self.sleep(POLL_SECONDS)
+        problems = []
+        if not web:
+            problems.append('the web interface did not respond')
+        if not disp:
+            problems.append('the display service did not stay running')
+        if web and disp and not count_known:
+            problems.append("the display service's restart count could not be read")
+        return '; '.join(problems) or 'the display service kept restarting'
+
+    # -- rollback ---------------------------------------------------------
+
+    def changed_requirements(self, old, new):
+        result = self._run(['git', 'diff', '--name-only', old, new])
+        # If the diff is unavailable, reinstall both rather than guess.
+        changed = set(result.stdout.split()) if result.returncode == 0 else set(REQUIREMENT_FILES)
+        return [rel for rel in REQUIREMENT_FILES if rel in changed]
+
+    def install_requirements(self, rel):
+        wrapper = self.project_root / 'scripts' / 'fix_perms' / 'safe_pip_install.sh'
+        req = self.project_root / rel
+        if not req.exists():
+            return True
+        for bash in BASH_CANDIDATES:
+            result = self._run(['sudo', '-n', bash, str(wrapper), str(req)],
+                               timeout=PIP_TIMEOUT_SECONDS)
+            if result.returncode == 0:
+                return True
+        return False
+
+    def rollback(self, pending):
+        """Reset to the previous commit and its dependencies. Returns (ok, detail)."""
+        old, new = pending.get('old_head'), pending.get('new_head')
+        if not old:
+            return False, 'the commit to roll back to is unknown'
+        requirements = self.changed_requirements(old, new) if new else list(REQUIREMENT_FILES)
+        # Safe to --hard: the updater refuses to run with local edits to
+        # tracked files, so the only thing this discards is the update.
+        result = self._run(['git', 'reset', '--hard', old], timeout=120)
+        if result.returncode != 0:
+            return False, (f'"git reset --hard {old}" failed: '
+                           f'{(result.stderr or result.stdout or "").strip()}')
+        failed = [rel for rel in requirements if not self.install_requirements(rel)]
+        if failed:
+            return True, ('reinstalling the previous dependencies from ' + ', '.join(failed)
+                          + ' failed; run Install Base Requirements from the Tools tab')
+        return True, ''
+
+    # -- the check itself -------------------------------------------------
+
+    def _finish(self, pending, status, reason=None, detail=None):
+        pending.update({'status': status, 'reason': reason, 'detail': detail or None,
+                        'finished_at': time.time()})
+        write_pending(self.pending_file, pending)
+        self.log(' '.join(p for p in (status, reason or '', detail or '') if p))
+
+    def verify(self):
+        pending = read_pending(self.pending_file)
+        if not pending or pending.get('status') != 'pending':
+            self.log('no update is waiting to be verified')
+            return 0
+        pending['status'] = 'verifying'
+        write_pending(self.pending_file, pending)
+
+        display = bool(pending.get('display_was_active'))
+        dependency_failures = pending.get('dependency_failures') or []
+        if dependency_failures:
+            # Never restart onto code whose packages did not install.
+            reason = 'installing its dependencies failed (' + ', '.join(dependency_failures) + ')'
+        elif not self.restart_services(display):
+            # The old process may still be answering; checking it would pass
+            # an update that never started.
+            reason = 'restarting the services failed'
+        else:
+            reason = self.wait_healthy(display)
+            if reason is None:
+                self._finish(pending, 'success')
+                return 0
+
+        self.log(f'update to {_short(pending.get("new_head"))} is unhealthy ({reason}); '
+                 f'rolling back to {_short(pending.get("old_head"))}')
+        ok, detail = self.rollback(pending)
+        if not ok:
+            self._finish(pending, 'rollback_failed', reason, detail)
+            return 1
+        still = (self.wait_healthy(display) if self.restart_services(display)
+                 else 'restarting the services failed')
+        if still:
+            self._finish(pending, 'rollback_failed', reason,
+                         f'still unhealthy after rolling back: {still}'
+                         + (f'; {detail}' if detail else ''))
+            return 1
+        self._finish(pending, 'rolled_back', reason, detail)
+        return 0
+
+
+def main(argv):
+    if len(argv) != 2:
+        print('usage: auto_update_verify.py PROJECT_ROOT', file=sys.stderr)
+        return 2
+    verifier = Verifier(Path(argv[1]))
+    try:
+        return verifier.verify()
+    except Exception as e:
+        traceback.print_exc()
+        # Whatever happened, the web interface must not be left thinking the
+        # check is still running.
+        try:
+            pending = read_pending(verifier.pending_file) or {}
+            if pending.get('status') in ('pending', 'verifying'):
+                pending.update({'status': 'rollback_failed', 'reason': 'the health check crashed',
+                                'detail': str(e), 'finished_at': time.time()})
+                write_pending(verifier.pending_file, pending)
+        except OSError:
+            pass
+        return 1
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv))

scripts/utils/pixlet_config_editor.sh

@@ -18,20 +18,33 @@
 #   ./scripts/utils/pixlet_config_editor.sh            # list installed apps
 #   ./scripts/utils/pixlet_config_editor.sh <app_id>   # edit
 #
-# Binds loopback only, and there is deliberately no flag to change that:
-# `pixlet serve` has no authentication, and anything that can reach it can
-# rewrite the app's config. To edit from another machine, forward the port --
-# which authenticates as SSH and leaves nothing listening on the LAN:
+# Binds the LAN by default, matching the web interface, which already serves
+# 0.0.0.0:5000 with no authentication -- anything that can reach this can
+# already reconfigure the display there. `pixlet serve` has no authentication
+# either, so treat both the same way: fine on a home network, not on an open
+# one. Override the bind and the session length with:
+#
+#   PIXLET_EDITOR_HOST=127.0.0.1 ./scripts/utils/pixlet_config_editor.sh <app>
+#   PIXLET_EDITOR_TIMEOUT=600    ./scripts/utils/pixlet_config_editor.sh <app>
+#
+# For loopback-only editing from another machine, forward the port instead:
 #
 #   ssh -L 8080:localhost:8080 pi@ledpi.local
+#
+# The session always ends by itself after PIXLET_EDITOR_TIMEOUT seconds
+# (default 30 minutes). The display is stopped while editing, so a session
+# left open would otherwise leave the panel dark indefinitely -- the timeout
+# is what makes it safe to start one from the web interface.
 
 set -eu
 
 PROJECT_ROOT_DIR=$(cd "$(dirname "$0")/../.." && pwd)
 APPS_DIR="$PROJECT_ROOT_DIR/starlark-apps"
 PORT="${PIXLET_EDITOR_PORT:-8080}"
-# Loopback only. See the header: pixlet serve is unauthenticated.
-BIND_HOST="127.0.0.1"
+# LAN by default; see the header for why, and how to force loopback.
+BIND_HOST="${PIXLET_EDITOR_HOST:-0.0.0.0}"
+# Hard stop, so the display cannot be left off by a forgotten session.
+EDITOR_TIMEOUT="${PIXLET_EDITOR_TIMEOUT:-1800}"
 
 APP_ID="${1:-}"
 
@@ -91,6 +104,29 @@ PIXLET_BIN=$(find_pixlet) || {
     exit 1
 }
 
+# find_pixlet supports Darwin, so this script has to as well. macOS ships no
+# timeout(1); GNU coreutils installs it as gtimeout. Resolve whichever exists
+# and fail here with instructions rather than at the invocation far below,
+# where the failure would land after the display has already been stopped.
+find_timeout() {
+    local candidate
+    for candidate in timeout gtimeout; do
+        if command -v "$candidate" >/dev/null 2>&1; then
+            command -v "$candidate"
+            return 0
+        fi
+    done
+    return 1
+}
+
+TIMEOUT_BIN=$(find_timeout) || {
+    echo "Neither 'timeout' nor 'gtimeout' was found on PATH."
+    echo "This script needs one to bound the editing session."
+    echo "On macOS, install GNU coreutils:"
+    echo "  brew install coreutils"
+    exit 1
+}
+
 CONFIG_FILE="$APP_DIR/config.json"
 if [ -f "$CONFIG_FILE" ]; then
     cp "$CONFIG_FILE" "$CONFIG_FILE.backup"
@@ -109,6 +145,19 @@ fi
 # failure worth guarding against.
 cleanup() {
     echo ""
+    # Kill the serve child explicitly. `timeout` is started with --foreground so
+    # it shares this script's process group (without that it makes its own, and
+    # a group signal aimed at this script would orphan pixlet with the port
+    # still bound). Belt and braces: signal the recorded pid too, because a
+    # group signal only reaches it while the group is shared.
+    if [ -n "${SERVE_PID:-}" ] && kill -0 "$SERVE_PID" 2>/dev/null; then
+        kill -TERM "$SERVE_PID" 2>/dev/null || true
+        for _ in 1 2 3 4 5 6 7 8 9 10; do
+            kill -0 "$SERVE_PID" 2>/dev/null || break
+            sleep 0.3
+        done
+        kill -KILL "$SERVE_PID" 2>/dev/null || true
+    fi
     if [ "$DISPLAY_WAS_RUNNING" = true ]; then
         echo "Restarting the display service..."
         sudo systemctl restart ledmatrix || echo "⚠ Could not restart ledmatrix - do it by hand"
@@ -122,22 +171,53 @@ if [ "$DISPLAY_WAS_RUNNING" = true ]; then
     sudo systemctl stop ledmatrix
 fi
 
+# Wildcard, loopback and an explicit interface address are three different
+# cases. Collapsing the last two into "localhost" printed a URL pointing at the
+# user's own machine whenever PIXLET_EDITOR_HOST named a LAN address.
+case "$BIND_HOST" in
+    0.0.0.0|::|"")            REACH_HOST="$(hostname).local" ;;
+    127.0.0.1|::1|localhost)  REACH_HOST="localhost" ;;
+    *)                        REACH_HOST="$BIND_HOST" ;;
+esac
+
 echo ""
 echo "Editing:  $APP_ID"
 echo "App file: $STAR_FILE"
-echo "URL:      http://localhost:$PORT/"
+echo "URL:      http://$REACH_HOST:$PORT/"
 echo ""
-echo "Listening on localhost only -- pixlet serve has no authentication."
-echo "From another machine, forward the port:"
-echo "  ssh -L $PORT:localhost:$PORT $(whoami)@$(hostname)"
+if [ "$BIND_HOST" = "0.0.0.0" ]; then
+    echo "Reachable on the LAN, and pixlet serve has no authentication -- the"
+    echo "same footing as the web interface on port 5000. Set"
+    echo "PIXLET_EDITOR_HOST=127.0.0.1 to keep it to this machine."
+else
+    echo "Listening on $BIND_HOST only. From another machine, forward the port:"
+    echo "  ssh -L $PORT:localhost:$PORT $(whoami)@$(hostname)"
+fi
 echo ""
 echo "Changes save straight to the real config as you make them."
 echo "Press Ctrl+C when finished - the display restarts automatically."
+echo "This session stops on its own after ${EDITOR_TIMEOUT}s regardless."
 echo ""
 
 cd "$APP_DIR"
-"$PIXLET_BIN" serve "$(basename "$STAR_FILE")" \
+# `timeout` owns the hard stop rather than the caller: the trap above restarts
+# the display however this exits, so a session that outlives the person who
+# started it still gives the panel back. Exit 124 is timeout's own code for
+# "expired", which is a normal end here, not a failure.
+# --foreground: stay in this script's process group so one signal reaches the
+# whole session. Backgrounded + `wait` so the EXIT trap can run while the child
+# is still alive; a foreground child would leave bash waiting on it instead.
+"$TIMEOUT_BIN" --foreground "$EDITOR_TIMEOUT" "$PIXLET_BIN" serve "$(basename "$STAR_FILE")" \
     --host "$BIND_HOST" \
     --port "$PORT" \
     --no-browser \
-    --saveconfig "$CONFIG_FILE"
+    --saveconfig "$CONFIG_FILE" &
+SERVE_PID=$!
+
+status=0
+wait "$SERVE_PID" || status=$?
+if [ "$status" -eq 124 ]; then
+    echo "Session reached its ${EDITOR_TIMEOUT}s limit."
+    status=0
+fi
+exit "$status"

scripts/utils/start_web_conditionally.py

@@ -74,23 +74,41 @@ def install_dependencies():
         print(f"Failed to install dependencies: {e}")
         return False
 
+#: String spellings that turn autostart OFF. Anything else -- including the key
+#: being absent entirely -- leaves it on.
+DISABLED_STRINGS = ("off", "false", "no", "0")
+
+
+def autostart_enabled(config_data):
+    """Whether to bring the web interface up. Defaults to True.
+
+    config.template.json and first_time_install.sh both ship
+    ``web_display_autostart`` as true, so a config that lacks the key is an
+    older or hand-edited one rather than a request to stay down. Defaulting to
+    False meant any such config silently got no web interface -- and because
+    the "not starting" path exits 0, systemd reported the unit as successfully
+    started while nothing was listening. Only an explicit false/off disables it.
+    """
+    value = config_data.get("web_display_autostart", True)
+    if isinstance(value, str):
+        return value.strip().lower() not in DISABLED_STRINGS
+    return bool(value)
+
+
 def main():
     try:
         with open(CONFIG_FILE, 'r') as f:
             config_data = json.load(f)
     except FileNotFoundError:
-        print(f"Config file {CONFIG_FILE} not found. Web interface will not start.")
-        sys.exit(0) # Exit gracefully, don't start
-    except Exception as e:
-        print(f"Error reading config file {CONFIG_FILE}: {e}. Web interface will not start.")
-        sys.exit(1) # Exit with error, service might restart depending on config
+        # The web interface is how a config gets created and repaired, so a
+        # missing one is the case where the user needs it most.
+        print(f"Config file {CONFIG_FILE} not found. Starting the web interface so it can be configured.")
+        config_data = {}
+    except (json.JSONDecodeError, OSError) as e:
+        print(f"Error reading config file {CONFIG_FILE}: {e}. Starting the web interface anyway so the config can be repaired.")
+        config_data = {}
 
-    autostart_enabled = config_data.get("web_display_autostart", False)
-
-    # Handle both boolean True and string "on"/"true" values
-    is_enabled = (autostart_enabled is True) or (isinstance(autostart_enabled, str) and autostart_enabled.lower() in ("on", "true", "yes", "1"))
-
-    if is_enabled:
+    if autostart_enabled(config_data):
         print("Configuration 'web_display_autostart' is enabled. Starting web interface...")
 
         # Only install dependencies if not already done during first-time setup
@@ -116,7 +134,7 @@ def main():
             print(f"Failed to exec web interface: {e}")
             sys.exit(1) # Failed to start
     else:
-        print("Configuration 'web_display_autostart' is false or not set. Web interface will not be started.")
+        print("Configuration 'web_display_autostart' is explicitly disabled. Web interface will not be started.")
         sys.exit(0) # Exit gracefully, service considered successful
 
 if __name__ == '__main__':

skins/README.md

@@ -1,5 +1,10 @@
 # skins/
 
+> **Not supported yet.** The current scoreboard plugins don't render skins,
+> so a skin placed here and selected in config has no effect, and the web UI
+> and Plugin Store don't offer them. See
+> [docs/SKIN_SYSTEM.md](../docs/SKIN_SYSTEM.md#status-not-supported-yet).
+
 User-installable **visual skins** for the sports scoreboards. Each
 subdirectory is one skin:
 
@@ -10,10 +15,10 @@ skins/<skin-id>/
   preview.png   # optional
 ```
 
-- Install a skin: `git clone <skin repo> skins/<skin-id>` (or via the Plugin
-  Store for registry entries with `"type": "skin"`).
+- Install a skin: `git clone <skin repo> skins/<skin-id>`. The Plugin Store
+  refuses registry entries with `"type": "skin"` while skins don't render.
 - Select it: set `"skin": "<skin-id>"` in the plugin's section of
-  `config/config.json`, or use the web UI's Visual Skin dropdown.
+  `config/config.json`. The web UI no longer shows a Visual Skin dropdown.
 - Build one: start from `example-classic-baseball/` and read
   [docs/CREATING_SKINS.md](../docs/CREATING_SKINS.md). Validate with
   `python scripts/validate_skin.py --skin <skin-id>`.

src/__init__.py

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

src/auto_update_setup.py

@@ -0,0 +1,221 @@
+"""Install the automatic-update health check, from the display service.
+
+The weekly updater (web_interface/auto_update.py) will not update LEDMatrix
+code unless ledmatrix-update-verify.path and .service are installed: they
+restart the services after an update and roll it back if the device is
+unhealthy. Installing units takes root and the web interface is not root, and
+"SSH in and run an installer" means most people never get updates with a
+safety net.
+
+The display service already runs this repository's code as root, so it
+installs them -- but only while the user has automatic updates turned on, only
+these two units, rendered from the repository's templates for the web
+interface's own user, and it reports what happened in
+data/auto_update_setup.json for the General tab. It grants nothing new: the
+units run as the web user, who can already change the code this process runs.
+
+Called at display startup; the web interface restarts the display service
+when the toggle is switched on, so setup happens straight away. Refreshing a
+unit whose template changed happens the same way, which is why this compares
+content rather than only checking that the files exist.
+"""
+import json
+import logging
+import os
+import re
+import subprocess  # nosec B404 - list-form argv only, no shell  # nosemgrep
+import tempfile
+import time
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+SYSTEMD_DIR = Path('/etc/systemd/system')
+SERVICE_UNIT = 'ledmatrix-update-verify.service'
+PATH_UNIT = 'ledmatrix-update-verify.path'
+UNITS = (SERVICE_UNIT, PATH_UNIT)
+WEB_UNIT = 'ledmatrix-web.service'
+RESULT_REL = Path('data') / 'auto_update_setup.json'
+_USER_RE = re.compile(r'^[a-z_][a-z0-9_-]{0,31}$')
+
+
+class SetupError(Exception):
+    """A reason setup cannot proceed, worded for the General tab."""
+
+
+def _is_root():
+    return hasattr(os, 'geteuid') and os.geteuid() == 0
+
+
+def _lookup_ids(user):
+    try:
+        import pwd
+        entry = pwd.getpwnam(user)
+        return entry.pw_uid, entry.pw_gid
+    except (ImportError, KeyError):
+        return None
+
+
+def _directive(text, key):
+    match = re.search(rf'^{key}=(.*)$', text or '', re.M)
+    return match.group(1).strip() if match else None
+
+
+def _read(path):
+    try:
+        return Path(path).read_text(encoding='utf-8')
+    except OSError:
+        return None
+
+
+def is_enabled(config):
+    return bool((config.get('auto_update') or {}).get('enabled', False))
+
+
+class UpdateHelperSetup:
+    def __init__(self, project_root=PROJECT_ROOT, systemd_dir=SYSTEMD_DIR, run=subprocess.run,
+                 is_root=_is_root, lookup_ids=_lookup_ids, clock=time.time):
+        self.project_root = Path(project_root)
+        self.systemd_dir = Path(systemd_dir)
+        self.run = run
+        self.is_root = is_root
+        self.lookup_ids = lookup_ids
+        self.clock = clock
+        self.result_file = self.project_root / RESULT_REL
+        self._web_ids = None
+
+    def _systemctl(self, *args):
+        return self.run(['systemctl', *args], capture_output=True, text=True, timeout=60)
+
+    def _check(self, result, what):
+        if result.returncode != 0:
+            raise SetupError(f'"{what}" failed: {(result.stderr or result.stdout or "").strip()}')
+
+    def path_active(self):
+        try:
+            return self._systemctl('is-active', PATH_UNIT).stdout.strip() == 'active'
+        except (subprocess.SubprocessError, OSError):
+            return False
+
+    def ensure(self, config):
+        """Install or refresh the units while automatic updates are on.
+
+        Returns the result recorded for the General tab, or None when there
+        was nothing to do (updates off, or not a systemd host at all).
+        """
+        if not is_enabled(config) or not self.systemd_dir.is_dir():
+            return None
+        try:
+            changed = self._install()
+        except SetupError as e:
+            return self._report('failed', str(e))
+        except (OSError, subprocess.SubprocessError) as e:
+            return self._report('failed', f'Could not install the update health check: {e}')
+        if changed:
+            return self._report('installed', 'Installed the update health check.')
+        return self._report('installed', 'The update health check is installed.', quiet=True)
+
+    def _install(self):
+        if not self.is_root():
+            raise SetupError('The display service is not running as root, so it cannot install the '
+                             'update health check. Run "sudo ./scripts/install/install_web_service.sh" once.')
+
+        web_text = _read(self.systemd_dir / WEB_UNIT)
+        if web_text is None:
+            raise SetupError('The web interface service (ledmatrix-web.service) is not installed.')
+        user = _directive(web_text, 'User') or 'root'
+        ids = self.lookup_ids(user) if _USER_RE.match(user) else None
+        if ids is None:
+            raise SetupError(f'The web interface runs as "{user}", which is not a usable account.')
+        self._web_ids = ids
+        workdir = _directive(web_text, 'WorkingDirectory')
+        if not workdir or Path(workdir).resolve() != self.project_root.resolve():
+            raise SetupError(f'The web interface service runs from {workdir or "an unknown folder"}, '
+                             f'not {self.project_root}.')
+        # Spaces are fine -- the templates quote every command-line path --
+        # but systemd expands % specifiers, and a quote, backslash or line
+        # break would be reinterpreted in a unit file. (On Windows, where the
+        # tests also run, a backslash is the path separator, not a name.)
+        root_text = str(self.project_root)
+        unsafe = set('%"') | ({'\\'} if os.sep == '/' else set())
+        if any(ch in unsafe or ord(ch) < 32 for ch in root_text):
+            raise SetupError(f'LEDMatrix is installed in {root_text!r}, a folder name systemd cannot use '
+                             'in a unit file. Move it to a path without %, quotes, backslashes or '
+                             'control characters.')
+
+        rendered = {}
+        for name in UNITS:
+            template = _read(self.project_root / 'systemd' / name)
+            if template is None:
+                raise SetupError(f'The unit template systemd/{name} is missing.')
+            rendered[name] = (template.replace('__PROJECT_ROOT_DIR__', str(self.project_root))
+                              .replace('__USER__', user))
+        # The templates are ordinary repository files. Whatever they say,
+        # this root process only installs a service that runs as the web user
+        # and a path unit that starts exactly that service.
+        if _directive(rendered[SERVICE_UNIT], 'User') != user:
+            raise SetupError(f'systemd/{SERVICE_UNIT} does not run as the web interface user; '
+                             'refusing to install it.')
+        if _directive(rendered[PATH_UNIT], 'Unit') != SERVICE_UNIT:
+            raise SetupError(f'systemd/{PATH_UNIT} does not start {SERVICE_UNIT}; refusing to install it.')
+
+        changed = [name for name in UNITS if _read(self.systemd_dir / name) != rendered[name]]
+        for name in changed:
+            self._write_unit(self.systemd_dir / name, rendered[name])
+        if changed:
+            self._check(self._systemctl('daemon-reload'), 'systemctl daemon-reload')
+            self._check(self._systemctl('enable', PATH_UNIT), f'systemctl enable {PATH_UNIT}')
+            self._check(self._systemctl('restart', PATH_UNIT), f'systemctl restart {PATH_UNIT}')
+        elif not self.path_active():
+            self._check(self._systemctl('enable', '--now', PATH_UNIT), f'systemctl enable --now {PATH_UNIT}')
+            changed = [PATH_UNIT]
+        if not self.path_active():
+            raise SetupError(f'{PATH_UNIT} did not start; see "journalctl -u {PATH_UNIT}".')
+        return bool(changed)
+
+    def _write_unit(self, path, text):
+        fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=f'.{path.name}.')
+        try:
+            with os.fdopen(fd, 'w', encoding='utf-8') as f:
+                f.write(text)
+            os.chmod(tmp, 0o644)
+            os.replace(tmp, path)
+        except BaseException:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+            raise
+
+    def _report(self, status, message, quiet=False):
+        previous = None
+        try:
+            previous = json.loads(_read(self.result_file) or 'null')
+        except ValueError:
+            pass
+        if quiet and isinstance(previous, dict) and previous.get('status') == status:
+            return previous  # nothing new; don't rewrite it on every boot
+        result = {'status': status, 'message': message, 'at': self.clock()}
+        (logger.info if status == 'installed' else logger.warning)("Automatic update setup: %s", message)
+        try:
+            self.result_file.parent.mkdir(parents=True, exist_ok=True)
+            fd, tmp = tempfile.mkstemp(dir=str(self.result_file.parent), prefix='.auto_update_setup_')
+            with os.fdopen(fd, 'w', encoding='utf-8') as f:
+                json.dump(result, f, indent=2)
+            os.chmod(tmp, 0o644)
+            if self._web_ids and hasattr(os, 'chown'):
+                # Only root can give the file away; the result is readable
+                # (0644) either way, so a failed chown must not lose it.
+                try:
+                    os.chown(tmp, *self._web_ids)
+                except OSError:
+                    pass
+            os.replace(tmp, self.result_file)
+        except OSError as e:
+            logger.warning("Could not record automatic update setup result: %s", e)
+        return result
+
+
+def ensure_update_helper(config):
+    return UpdateHelperSetup().ensure(config)

src/base_classes/baseball.py

@@ -37,51 +37,6 @@ class Baseball(SportsCore):
         self.data_source = ESPNDataSource(logger)
         self.sport = "baseball"
 
-    def _get_baseball_display_text(self, game: Dict) -> str:
-        """Get baseball-specific display text."""
-        try:
-            display_parts = []
-
-            # Inning information
-            if self.show_innings:
-                inning = game.get("inning", "")
-                if inning:
-                    display_parts.append(f"Inning: {inning}")
-
-            # Outs information
-            if self.show_outs:
-                outs = game.get("outs", 0)
-                if outs is not None:
-                    display_parts.append(f"Outs: {outs}")
-
-            # Bases information
-            if self.show_bases:
-                bases = game.get("bases", "")
-                if bases:
-                    display_parts.append(f"Bases: {bases}")
-
-            # Count information
-            if self.show_count:
-                strikes = game.get("strikes", 0)
-                balls = game.get("balls", 0)
-                if strikes is not None and balls is not None:
-                    display_parts.append(f"Count: {balls}-{strikes}")
-
-            # Pitcher/Batter information
-            if self.show_pitcher_batter:
-                pitcher = game.get("pitcher", "")
-                batter = game.get("batter", "")
-                if pitcher:
-                    display_parts.append(f"Pitcher: {pitcher}")
-                if batter:
-                    display_parts.append(f"Batter: {batter}")
-
-            return " | ".join(display_parts) if display_parts else ""
-
-        except Exception as e:
-            self.logger.error(f"Error getting baseball display text: {e}")
-            return ""
-
     def _is_baseball_game_live(self, game: Dict) -> bool:
         """Check if a baseball game is currently live."""
         try:

src/base_classes/sports/core.py

@@ -8,6 +8,7 @@ import os
 import tempfile
 import time
 from abc import ABC, abstractmethod
+from collections import OrderedDict
 from datetime import datetime, timedelta
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
@@ -167,7 +168,14 @@ class SportsCore(ABC):
         self.session.mount("https://", adapter)
         self.session.mount("http://", adapter)
 
-        self._logo_cache = {}
+        # LRU-bounded: entries are decoded RGBA thumbnails, not file bytes.
+        # Each is up to display_width*1.5 x display_height*1.5 -- about 36KB on
+        # a 256x64 panel, more for wide wordmarks. The key is a team
+        # abbreviation and assets/sports/ncaa_logos alone ships 307 of them, so
+        # an unbounded dict here held the whole league: ~11-18MB per manager
+        # instance, and a league runs three (live/recent/upcoming) each with
+        # its own cache. That is real money on a 1GB Pi.
+        self._logo_cache: "OrderedDict[str, Image.Image]" = OrderedDict()
 
         # Font caches for _load_custom_font_from_element_config: per-frame
         # callers (font-ladder walks) resolve the same (name, size) over and
@@ -560,11 +568,17 @@ class SportsCore(ABC):
             draw.text((x + dx, y + dy), text, font=font, fill=outline_color)
         draw.text((x, y), text, font=font, fill=fill)
 
+    #: Decoded logos to keep. A scroll of "other games" shows on the order of
+    #: 20 games (40 teams), so this holds a full cycle without thrashing while
+    #: capping the cache well below a 307-team league.
+    _LOGO_CACHE_MAX = 64
+
     def _load_and_resize_logo(self, team_id: str, team_abbrev: str, logo_path: Path, logo_url: str | None ) -> Optional[Image.Image]:
         """Load and resize a team logo, with caching and automatic download if missing."""
         self.logger.debug(f"Logo path: {logo_path}")
         if team_abbrev in self._logo_cache:
             self.logger.debug(f"Using cached logo for {team_abbrev}")
+            self._logo_cache.move_to_end(team_abbrev)
             return self._logo_cache[team_abbrev]
 
         try:
@@ -604,6 +618,8 @@ class SportsCore(ABC):
             max_height = int(self.display_height * 1.5)
             logo.thumbnail((max_width, max_height), Image.Resampling.LANCZOS)
             self._logo_cache[team_abbrev] = logo
+            while len(self._logo_cache) > self._LOGO_CACHE_MAX:
+                self._logo_cache.popitem(last=False)
             return logo
 
         except Exception as e:

src/cache/disk_cache.py

@@ -15,6 +15,8 @@ import zlib
 from typing import Dict, Any, Optional, Protocol
 from datetime import datetime
 
+from src.common.path_safety import safe_path_component
+
 try:  # optional: large speedup on the cache write path, see _dumps below
     import orjson
 except ImportError:  # pragma: no cover - exercised on hosts without the wheel
@@ -160,16 +162,30 @@ class DiskCache:
     def get_cache_path(self, key: str) -> Optional[str]:
         """
         Get the path for a cache file.
-        
+
+        The key becomes a filename, so it has to be one. Keys reach this
+        method from the web API -- POST /api/v3/cache/delete passes the
+        request body's ``key`` straight through CacheManager.clear_cache to
+        os.remove -- and a key of ``../../../../etc/whatever`` named a file
+        well outside the cache directory. Every real key is the stem of a
+        file already sitting flat in cache_dir (that is how list_cache_files
+        derives them), so rejecting anything with a path component turns
+        away only inputs that could never have been written here.
+
         Args:
             key: Cache key
-            
+
         Returns:
-            Path to cache file or None if cache is disabled
+            Path to cache file, or None if cache is disabled or the key is
+            not a usable filename
         """
         if not self.cache_dir:
             return None
-        return os.path.join(self.cache_dir, f"{key}.json")
+        safe_key = safe_path_component(key)
+        if safe_key is None:
+            self.logger.warning("Rejected unsafe cache key %r", key)
+            return None
+        return os.path.join(self.cache_dir, f"{safe_key}.json")
     
     def get(self, key: str, max_age: Optional[int] = 300) -> Optional[Dict[str, Any]]:
         """

src/common/font_layout.py

@@ -20,11 +20,23 @@ with on an LED panel.
 
 Use :func:`load_truetype` in place of ``ImageFont.truetype`` anywhere the
 result is drawn to a panel or compared against a golden image.
+
+The module also owns the other two things that decide whether a bundled face
+renders reproducibly, for the same reason — they are properties of the font
+file, not of whoever is drawing with it:
+
+* :func:`crisp_size` and :data:`FONT_PIXEL_GRID` — the size each face renders
+  on whole pixels at. ``4x6-font.ttf`` has a 7px grid, which is why the 6 that
+  reads as its natural size is the wrong number everywhere it appears.
+* :func:`resolve_asset_path` — ``assets/fonts/...`` resolved against the
+  install root rather than the process cwd.
 """
 
 from __future__ import annotations
 
-from typing import Any, Union
+import os
+from pathlib import Path
+from typing import Any, Dict, Union
 
 from PIL import ImageFont
 
@@ -41,3 +53,74 @@ def load_truetype(font: Union[str, Any], size: int, **kwargs: Any) -> ImageFont.
     """
     kwargs.setdefault("layout_engine", LAYOUT_ENGINE)
     return ImageFont.truetype(font, size, **kwargs)
+
+
+# --------------------------------------------------------------------------
+# Bundled-asset path resolution
+# --------------------------------------------------------------------------
+
+#: The install root, derived from this module's own location
+#: (``<root>/src/common/font_layout.py``) rather than from the process cwd.
+_INSTALL_ROOT = Path(__file__).resolve().parents[2]
+
+
+def resolve_asset_path(relative_path: str) -> str:
+    """Resolve a repo-relative asset path independently of the process cwd.
+
+    Prefers the path as given — so an absolute path is returned untouched and
+    behaviour is unchanged wherever the cwd already happened to be the install
+    root — then the install root derived above, then the original string so a
+    caller that wants to raise and fall back still can.
+
+    Without the fallback, any process started outside the install root (the
+    plugin safety harness, a manual ``python run.py`` from ``$HOME``, a unit
+    file written without ``WorkingDirectory``) silently loses every font and
+    degrades to PIL's default face.
+    """
+    if os.path.isabs(relative_path) and os.path.exists(relative_path):
+        return relative_path
+    candidate = _INSTALL_ROOT / relative_path
+    if candidate.exists():
+        return str(candidate)
+    return relative_path
+
+
+# --------------------------------------------------------------------------
+# Pixel-grid snapping
+# --------------------------------------------------------------------------
+
+#: Family aliases the web UI may write, mapped to the shipped filename.
+FONT_NAME_ALIASES: Dict[str, str] = {
+    "press_start": "PressStart2P-Regular.ttf",
+    "four_by_six": "4x6-font.ttf",
+}
+
+#: Pixel grid each face renders crisply on. Off-grid sizes anti-alias, which
+#: on an LED matrix is a dim lamp rather than a soft edge — and worse under
+#: ``draw.fontmode = "1"``, where the mono rasteriser thresholds each glyph at
+#: 50% coverage: an off-grid 4x6 glyph renders 3px wide instead of 4, so W/M
+#: and 0/8 stop being distinguishable. Off-grid sizes also make ``getlength``
+#: return a FreeType-dependent fractional advance, which is how two panels on
+#: one config centre the same string differently.
+FONT_PIXEL_GRID: Dict[str, int] = {
+    "PressStart2P-Regular.ttf": 8,
+    "4x6-font.ttf": 7,
+}
+
+
+def crisp_size(font_file, desired, aliases=None, grid_table=None):
+    """Snap *desired* to the nearest size *font_file* renders crisply at.
+
+    A face with no known grid is returned unchanged, so a user-supplied font is
+    never second-guessed.
+
+    ``aliases`` and ``grid_table`` default to the shared tables; a plugin that
+    ships an extra face can pass its own without forking this.
+    """
+    aliases = FONT_NAME_ALIASES if aliases is None else aliases
+    grid_table = FONT_PIXEL_GRID if grid_table is None else grid_table
+    font_file = aliases.get(font_file, font_file)
+    grid = grid_table.get(font_file)
+    if not grid or not desired or desired <= 0:
+        return desired
+    return max(grid, int(round(float(desired) / grid)) * grid)

src/common/logo_helper.py

@@ -8,6 +8,7 @@ Extracted from LEDMatrix core to provide reusable functionality for plugins.
 import logging
 import os
 import tempfile
+import time
 from pathlib import Path
 from typing import Dict, List, Optional, Union
 
@@ -20,6 +21,44 @@ from src.common.permission_utils import (
     get_assets_file_mode
 )
 
+# How long a missing logo stays remembered as missing.
+#
+# This was 600s, and measured on a live rig that turned out to suppress nothing:
+# the display rotation is ~618s, so every recheck landed just as the plugin came
+# round again and the warning rate was unchanged at ~6/hour. A TTL has to be long
+# relative to the loop that does the asking, not merely "a while".
+#
+# An hour is safe because the TTL is not the main way an entry clears. A download
+# through load_logo_with_download() drops it immediately, and clear_cache() drops
+# all of them; the TTL only covers a file that appeared some other way -- someone
+# copying one in by hand. Waiting up to an hour for that, or restarting, is a fair
+# trade for not re-warning about a file nobody is going to add.
+MISSING_LOGO_RECHECK_SECONDS = 3600.0
+
+#: Bounds on a user-supplied logo scale. Wide enough to be useful, closed
+#: enough that a typo cannot ask for a 4000px image on a 64px panel.
+MIN_LOGO_SCALE = 0.05
+MAX_LOGO_SCALE = 8.0
+
+
+def _usable_scale(scale) -> float:
+    """A scale that can be applied, or 1.0.
+
+    Anything unusable -- None, a string, zero, a negative, NaN, infinity --
+    means "as shipped", because the alternative is a blank panel from a
+    mistyped number.
+    """
+    try:
+        value = float(scale)
+    except (TypeError, ValueError):
+        return 1.0
+    if value != value or value in (float('inf'), float('-inf')):
+        return 1.0
+    if value < MIN_LOGO_SCALE or value > MAX_LOGO_SCALE:
+        return 1.0
+    return value
+
+
 
 # Well above any real team logo; bounds what a remote URL can write to disk.
 MAX_LOGO_BYTES = 10 * 1024 * 1024
@@ -56,6 +95,14 @@ class LogoHelper:
         # In-memory logo cache
         self._logo_cache: Dict[str, Image.Image] = {}
         self._cache_order: List[str] = []  # For LRU cache management
+
+        # Misses, so an absent file is stat'd and warned about once rather than
+        # on every call. Without this a permanently missing logo produced a
+        # warning per rotation forever -- measured at 114 lines in 24 hours for
+        # a single missing ticker icon, for a file nobody was going to add.
+        # Time-bounded rather than permanent so a logo that appears later (the
+        # downloader writes them at runtime) is still picked up.
+        self._missing_logos: Dict[str, float] = {}
         
         # Session for HTTP requests
         self.session = requests.Session()
@@ -64,18 +111,23 @@ class LogoHelper:
             'Accept': 'image/*',
         })
     
-    def load_logo(self, team_abbr: str, logo_path: Union[str, Path], 
-                  max_width: Optional[int] = None, 
-                  max_height: Optional[int] = None) -> Optional[Image.Image]:
+    def load_logo(self, team_abbr: str, logo_path: Union[str, Path],
+                  max_width: Optional[int] = None,
+                  max_height: Optional[int] = None,
+                  scale: float = 1.0) -> Optional[Image.Image]:
         """
         Load and resize a team logo.
-        
+
         Args:
             team_abbr: Team abbreviation for caching
             logo_path: Path to the logo file
             max_width: Maximum width (defaults to display_width * 1.5)
             max_height: Maximum height (defaults to display_height * 1.5)
-            
+            scale: User's size multiplier for this image, from
+                ``customization.layout.<element>.scale``. 1.0 is untouched and
+                takes exactly the path it always did. Callers hold the config,
+                so they resolve the element name; this only applies the number.
+
         Returns:
             PIL Image object or None if loading fails
 
@@ -91,6 +143,12 @@ class LogoHelper:
             max_width = int(self.display_width * 1.5)
         if max_height is None:
             max_height = int(self.display_height * 1.5)
+        scale = _usable_scale(scale)
+        if scale != 1.0:
+            max_width = max(1, int(round(max_width * scale)))
+            max_height = max(1, int(round(max_height * scale)))
+        # The key carries the scaled box, so two elements scaled differently
+        # cannot be served each other's image.
         cache_key = f"{team_abbr}_{logo_path}_{max_width}x{max_height}"
         if cache_key in self._logo_cache:
             self.logger.debug(f"Using cached logo for {team_abbr}")
@@ -100,9 +158,19 @@ class LogoHelper:
             self._cache_order.append(cache_key)
             return self._logo_cache[cache_key]
         
+        # A known-missing file: skip the stat and stay quiet until the entry
+        # ages out. Checked after the positive cache so a logo that has since
+        # been loaded always wins.
+        missed_at = self._missing_logos.get(cache_key)
+        if missed_at is not None:
+            if time.time() - missed_at < MISSING_LOGO_RECHECK_SECONDS:
+                return None
+            del self._missing_logos[cache_key]
+
         try:
             logo_path = Path(logo_path)
             if not logo_path.exists():
+                self._missing_logos[cache_key] = time.time()
                 self.logger.warning(f"Logo not found for {team_abbr} at {logo_path}")
                 return None
             
@@ -112,7 +180,8 @@ class LogoHelper:
                 logo = logo.convert('RGBA')
             
             # Resize if needed
-            logo = self._resize_logo(logo, max_width, max_height)
+            logo = self._resize_logo(logo, max_width, max_height,
+                                     allow_upscale=scale > 1.0)
             
             # Cache the logo
             self._cache_logo(cache_key, logo)
@@ -124,10 +193,11 @@ class LogoHelper:
             self.logger.error(f"Error loading logo for {team_abbr}: {e}")
             return None
     
-    def load_logo_with_download(self, team_abbr: str, logo_path: Union[str, Path], 
+    def load_logo_with_download(self, team_abbr: str, logo_path: Union[str, Path],
                                logo_url: Optional[str] = None,
                                max_width: Optional[int] = None,
-                               max_height: Optional[int] = None) -> Optional[Image.Image]:
+                               max_height: Optional[int] = None,
+                               scale: float = 1.0) -> Optional[Image.Image]:
         """
         Load logo with automatic download if missing.
         
@@ -147,7 +217,8 @@ class LogoHelper:
         # failed download does not count: it wears the real logo's filename, so
         # trusting the file's existence is what left teams as grey boxes.
         if logo_path.exists() and not self._is_stale_placeholder(logo_path):
-            return self.load_logo(team_abbr, logo_path, max_width, max_height)
+            return self.load_logo(team_abbr, logo_path, max_width, max_height,
+                                  scale)
         
         # Download if URL provided and file doesn't exist
         if logo_url:
@@ -159,7 +230,8 @@ class LogoHelper:
                 # from the cache before touching the disk -- so without this the
                 # real logo would not appear until the process restarted.
                 self._invalidate_cached_logo(team_abbr, logo_path)
-                return self.load_logo(team_abbr, logo_path, max_width, max_height)
+                return self.load_logo(team_abbr, logo_path, max_width, max_height,
+                                  scale)
             except Exception as e:
                 self.logger.error(f"Failed to download logo for {team_abbr}: {e}")
                 # The retry failed, so restart the back-off. The stale
@@ -179,6 +251,11 @@ class LogoHelper:
             self._logo_cache.pop(key, None)
             if key in self._cache_order:
                 self._cache_order.remove(key)
+        # The file exists now, so any record of it being missing is wrong --
+        # and load_logo() consults that record before it stats the disk, so
+        # leaving it would hide a logo we just downloaded.
+        for key in [k for k in self._missing_logos if k.startswith(prefix)]:
+            del self._missing_logos[key]
 
     @staticmethod
     def _refresh_stale_placeholder(logo_path: Path) -> None:
@@ -270,6 +347,7 @@ class LogoHelper:
         """Clear the logo cache."""
         self._logo_cache.clear()
         self._cache_order.clear()
+        self._missing_logos.clear()
         self.logger.debug("Logo cache cleared")
     
     def get_cache_stats(self) -> Dict[str, int]:
@@ -288,18 +366,31 @@ class LogoHelper:
             ),
         }
     
-    def _resize_logo(self, logo: Image.Image, max_width: Optional[int] = None, 
-                    max_height: Optional[int] = None) -> Image.Image:
-        """Resize logo to fit display dimensions."""
+    def _resize_logo(self, logo: Image.Image, max_width: Optional[int] = None,
+                    max_height: Optional[int] = None,
+                    allow_upscale: bool = False) -> Image.Image:
+        """Resize logo to fit display dimensions.
+
+        ``allow_upscale`` is only set when the user asked for a scale above 1:
+        the fit rule is "never larger than the box", and growing an image
+        nobody asked to grow would change every existing render.
+        """
         if max_width is None:
             max_width = int(self.display_width * 1.5)
         if max_height is None:
             max_height = int(self.display_height * 1.5)
-        
+
         # Only resize if necessary
         if logo.width <= max_width and logo.height <= max_height:
-            return logo
-        
+            if not allow_upscale or not logo.width or not logo.height:
+                return logo
+            ratio = min(max_width / logo.width, max_height / logo.height)
+            if ratio <= 1:
+                return logo
+            return logo.resize((max(1, int(logo.width * ratio)),
+                                max(1, int(logo.height * ratio))),
+                               Image.Resampling.LANCZOS)
+
         # Maintain aspect ratio
         logo.thumbnail((max_width, max_height), Image.Resampling.LANCZOS)
         return logo

src/common/path_safety.py

@@ -0,0 +1,125 @@
+"""One place to turn a request-supplied name into a path you can open.
+
+Every web handler that opens a file under a fixed directory had grown its own
+version of this: a regex here, an ``os.path.basename`` there, a
+``str(x).startswith(str(base))`` somewhere else. They were not equivalent.
+``startswith`` says ``plugin-repos/foo-evil`` is inside ``plugin-repos/foo``;
+validating a name in one place and rebuilding the path from the *raw* value in
+another leaves the guard checking something the filesystem never sees.
+
+Two functions, used the same way everywhere:
+
+``safe_path_component(value)``
+    ``value`` if it is one harmless path segment, otherwise ``None``.
+
+``resolve_under(base, *parts)``
+    the resolved path, or ``None`` if any part is unsafe or the result would
+    land outside ``base``.
+
+Both *return the sanitised value* rather than a boolean, so a caller cannot
+validate one string and then open another -- and so a scanner can follow what
+actually reaches ``open()``. ``os.path.basename`` does the stripping because it
+is the sanitiser CodeQL's path-injection query recognises; the equality check
+after it means an input with a directory part is rejected outright instead of
+being silently truncated to something the caller did not ask for.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, List, Optional, Union
+
+__all__ = [
+    'safe_path_component',
+    'safe_relative_parts',
+    'resolve_under',
+]
+
+# Names that are a path component syntactically but never name a real entry a
+# caller means to reach.
+_RESERVED_COMPONENTS = frozenset({'', '.', '..'})
+
+
+def safe_path_component(value: Any) -> Optional[str]:
+    """Return ``value`` when it is a single, harmless path segment.
+
+    Returns ``None`` for anything else: a non-string, an empty string, ``.`` or
+    ``..``, a value carrying a directory separator (either platform's), a drive
+    letter, or an embedded NUL.
+
+    The return value is what callers must join -- not the argument.
+    """
+    if not isinstance(value, str) or not value:
+        return None
+    if '\x00' in value:
+        return None
+
+    # basename strips any directory component, so what a caller joins cannot
+    # carry one. Comparing the result against the input rejects rather than
+    # truncates: "../etc/passwd" is an error, not a request for "passwd".
+    name = os.path.basename(value)
+    if name != value or name in _RESERVED_COMPONENTS:
+        return None
+
+    # basename only knows the host platform's separator. On POSIX a backslash
+    # is an ordinary character, and "C:" is a plausible-looking name that
+    # os.path.join would treat as a drive on Windows. Rule both out everywhere
+    # so behaviour does not depend on where the service happens to run.
+    if '/' in name or '\\' in name or os.sep in name or (os.altsep and os.altsep in name):
+        return None
+    if ':' in name and len(name) >= 2 and name[1] == ':':
+        return None
+
+    return name
+
+
+def safe_relative_parts(value: Any) -> Optional[List[str]]:
+    """Split a multi-segment relative path into safe components.
+
+    For Flask's ``<path:...>`` converter, where ``a/b/c.json`` is legitimate but
+    ``../../config/config_secrets.json`` is not. Returns the component list, or
+    ``None`` if any component fails :func:`safe_path_component`.
+    """
+    if not isinstance(value, str) or not value:
+        return None
+    if value.startswith('/') or value.startswith('\\'):
+        return None
+
+    parts: List[str] = []
+    for raw in value.replace('\\', '/').split('/'):
+        if raw == '':
+            # A trailing or doubled slash names nothing; skip it rather than
+            # rejecting a path a browser may well send.
+            continue
+        part = safe_path_component(raw)
+        if part is None:
+            return None
+        parts.append(part)
+
+    return parts or None
+
+
+def resolve_under(base: Union[str, Path], *parts: Any) -> Optional[Path]:
+    """Resolve ``base/parts...``, or ``None`` if that would escape ``base``.
+
+    Each part is validated with :func:`safe_path_component` first, so the value
+    that reaches the filesystem is the sanitised one. The containment check is
+    kept as well: it is what catches a symlink inside ``base`` pointing out of
+    it, which no amount of name validation can see.
+    """
+    safe_parts: List[str] = []
+    for part in parts:
+        component = safe_path_component(part)
+        if component is None:
+            return None
+        safe_parts.append(component)
+
+    try:
+        base_resolved = Path(base).resolve()
+        candidate = base_resolved.joinpath(*safe_parts).resolve()
+        candidate.relative_to(base_resolved)
+    except (OSError, ValueError, TypeError):
+        return None
+
+    return candidate

src/common/scroll_helper.py

@@ -30,6 +30,12 @@ except ImportError:
     HAS_SCIPY = False
 
 
+# How often the frame-stats line is emitted, and therefore also the ceiling
+# on a believable frame time: a scroll that renders at all cannot take this
+# long over one frame, so a sample this large is an idle gap between scrolls.
+FPS_LOG_INTERVAL = 5.0
+
+
 def frame_stats(frame_times: list) -> Dict[str, Any]:
     """Summary statistics over one window of frame durations (seconds).
 
@@ -158,9 +164,11 @@ class ScrollHelper:
         self.last_progress_log_time: Optional[float] = None
         self.progress_log_interval = 5.0  # seconds
         
-        # Frame rate tracking
+        # Frame rate tracking. last_frame_time is None until the first frame
+        # of a scroll is rendered -- see log_frame_rate() for why timing from
+        # construction (or from the end of the previous scroll) is wrong.
         self.frame_count = 0
-        self.last_frame_time = time.time()
+        self.last_frame_time: Optional[float] = None
         self.last_fps_log_time = time.time()
         self.frame_times = []
         # Every frame time since the last stats line, so the 5s summary can
@@ -534,168 +542,6 @@ class ScrollHelper:
 
             return Image.frombytes('RGB', _size, self._frame_buffer.tobytes())
     
-    def _get_visible_portion_subpixel(self, start_x_int: int, fractional: float) -> Image.Image:
-        """
-        Get visible portion with sub-pixel interpolation for smooth scrolling.
-        Uses bilinear interpolation to blend between pixels.
-        """
-        # We need to extract a region that's 1 pixel wider to allow for interpolation
-        start_x = start_x_int
-        end_x = start_x_int + self.display_width + 1
-        
-        # Check if we need wrap-around
-        if end_x <= self.cached_image.width:
-            # Normal case: extract region with 1 extra pixel for interpolation
-            source_region = self.cached_array[:, start_x:end_x]
-            
-            # Use bilinear interpolation for sub-pixel shifting
-            if HAS_SCIPY:
-                # Use scipy for high-quality sub-pixel shifting
-                shifted = shift(source_region, (0, -fractional, 0), mode='nearest', order=1, prefilter=False)
-                # Extract the display_width portion
-                frame_array = shifted[:, :self.display_width].astype(np.uint8)
-            else:
-                # Fallback: simple linear interpolation using numpy
-                # Blend between current and next pixel based on fractional part
-                frame_array = self._interpolate_subpixel(source_region, fractional)
-            
-            return Image.fromarray(frame_array)
-        else:
-            # Wrap-around case with sub-pixel
-            # Use pre-allocated buffer
-            if self._frame_buffer is None or self._frame_buffer.shape != (self.display_height, self.display_width, 3):
-                self._frame_buffer = np.zeros((self.display_height, self.display_width, 3), dtype=np.uint8)
-            
-            width1 = self.cached_image.width - start_x
-            if width1 > 0:
-                # First part from end of image
-                # Need width1 + 1 pixels for interpolation
-                source1_width = min(width1 + 1, self.cached_image.width - start_x)
-                source1 = self.cached_array[:, start_x:start_x + source1_width]
-                if HAS_SCIPY:
-                    shifted1 = shift(source1, (0, -fractional, 0), mode='nearest', order=1, prefilter=False)
-                    # Ensure we get exactly width1 pixels, padding if necessary
-                    if shifted1.shape[1] >= width1:
-                        self._frame_buffer[:, :width1] = shifted1[:, :width1].astype(np.uint8)
-                    else:
-                        # Shifted array is smaller - pad with zeros or repeat last pixel
-                        actual_width = shifted1.shape[1]
-                        self._frame_buffer[:, :actual_width] = shifted1.astype(np.uint8)
-                        if actual_width < width1:
-                            # Pad with last pixel
-                            self._frame_buffer[:, actual_width:width1] = shifted1[:, -1:].astype(np.uint8)
-                else:
-                    interpolated1 = self._interpolate_subpixel(source1, fractional, output_width=width1)
-                    # Ensure exact width match
-                    if interpolated1.shape[1] == width1:
-                        self._frame_buffer[:, :width1] = interpolated1
-                    else:
-                        # Handle size mismatch
-                        copy_width = min(width1, interpolated1.shape[1])
-                        self._frame_buffer[:, :copy_width] = interpolated1[:, :copy_width]
-                        if copy_width < width1:
-                            self._frame_buffer[:, copy_width:width1] = interpolated1[:, -1:]
-                
-                # Second part from beginning
-                remaining_width = self.display_width - width1
-                if remaining_width > 0:
-                    source2 = self.cached_array[:, :remaining_width + 1]
-                    if HAS_SCIPY:
-                        shifted2 = shift(source2, (0, -fractional, 0), mode='nearest', order=1, prefilter=False)
-                        # Ensure we get exactly remaining_width pixels
-                        if shifted2.shape[1] >= remaining_width:
-                            self._frame_buffer[:, width1:width1 + remaining_width] = shifted2[:, :remaining_width].astype(np.uint8)
-                        else:
-                            # Shifted array is smaller - pad if necessary
-                            actual_width = shifted2.shape[1]
-                            self._frame_buffer[:, width1:width1 + actual_width] = shifted2.astype(np.uint8)
-                            if actual_width < remaining_width:
-                                self._frame_buffer[:, width1 + actual_width:width1 + remaining_width] = shifted2[:, -1:].astype(np.uint8)
-                    else:
-                        interpolated2 = self._interpolate_subpixel(source2, fractional, output_width=remaining_width)
-                        # Ensure exact width match
-                        if interpolated2.shape[1] == remaining_width:
-                            self._frame_buffer[:, width1:] = interpolated2
-                        else:
-                            copy_width = min(remaining_width, interpolated2.shape[1])
-                            self._frame_buffer[:, width1:width1 + copy_width] = interpolated2[:, :copy_width]
-                            if copy_width < remaining_width:
-                                self._frame_buffer[:, width1 + copy_width:width1 + remaining_width] = interpolated2[:, -1:]
-            else:
-                # Edge case: wrap to beginning
-                source = self.cached_array[:, :self.display_width + 1]
-                if HAS_SCIPY:
-                    shifted = shift(source, (0, -fractional, 0), mode='nearest', order=1, prefilter=False)
-                    # Ensure we get exactly display_width pixels
-                    if shifted.shape[1] >= self.display_width:
-                        self._frame_buffer = shifted[:, :self.display_width].astype(np.uint8)
-                    else:
-                        # Shifted array is smaller - pad if necessary
-                        actual_width = shifted.shape[1]
-                        self._frame_buffer[:, :actual_width] = shifted.astype(np.uint8)
-                        if actual_width < self.display_width:
-                            self._frame_buffer[:, actual_width:] = shifted[:, -1:].astype(np.uint8)
-                else:
-                    interpolated = self._interpolate_subpixel(source, fractional, output_width=self.display_width)
-                    # _interpolate_subpixel now always returns exact width, so this should work
-                    self._frame_buffer = interpolated
-            
-            return Image.fromarray(self._frame_buffer)
-    
-    def _interpolate_subpixel(self, source: np.ndarray, fractional: float, output_width: Optional[int] = None) -> np.ndarray:
-        """
-        Simple linear interpolation for sub-pixel positioning.
-        Blends between adjacent pixels based on fractional offset.
-        
-        Args:
-            source: Source array to interpolate (width should be at least output_width + 1)
-            fractional: Fractional part of scroll position (0.0-1.0)
-            output_width: Desired output width (defaults to display_width)
-        
-        Returns:
-            Interpolated array of shape (height, output_width, 3) - ALWAYS exactly output_width
-        """
-        if output_width is None:
-            output_width = self.display_width
-        
-        # Always return exactly output_width pixels, padding if necessary
-        result = np.zeros((source.shape[0], output_width, 3), dtype=np.uint8)
-        
-        # Ensure we have enough source pixels for interpolation
-        if source.shape[1] < 2:
-            # Very small source - just copy what we have and pad
-            copy_width = min(source.shape[1], output_width)
-            result[:, :copy_width] = source[:, :copy_width].astype(np.uint8)
-            if copy_width < output_width:
-                # Pad with last pixel
-                result[:, copy_width:] = source[:, -1:].astype(np.uint8)
-            return result
-        
-        # Calculate how many pixels we can actually interpolate
-        # Need at least 2 pixels to interpolate, so max output is source.shape[1] - 1
-        max_interpolated_width = source.shape[1] - 1
-        interpolated_width = min(output_width, max_interpolated_width)
-        
-        if interpolated_width > 0:
-            # Extract pixels at x and x+1 for interpolation
-            pixels_x = source[:, :interpolated_width].astype(np.float32)
-            pixels_x1 = source[:, 1:interpolated_width + 1].astype(np.float32)
-            
-            # Linear interpolation
-            interpolated = pixels_x * (1.0 - fractional) + pixels_x1 * fractional
-            
-            # Clip and convert back to uint8
-            interpolated = np.clip(interpolated, 0, 255).astype(np.uint8)
-            
-            # Copy interpolated portion to result
-            result[:, :interpolated_width] = interpolated
-        
-        # If we need more pixels than we can interpolate, pad with last pixel
-        if interpolated_width < output_width:
-            result[:, interpolated_width:] = source[:, -1:].astype(np.uint8)
-        
-        return result
-    
     def calculate_dynamic_duration(self) -> int:
         """
         Calculate display duration based on content width and scroll settings.
@@ -926,6 +772,10 @@ class ScrollHelper:
         # Reset last_update_time to prevent large delta_time on next update
         # This ensures smooth scrolling after reset without jumping ahead
         self.last_update_time = now
+        # Same reasoning for the frame-rate clock: the first frame after a
+        # reset has no predecessor in this scroll, and timing it against the
+        # last frame of the previous one measures the idle gap between them.
+        self.last_frame_time = None
         self.logger.debug("Scroll position reset")
 
     def reset(self) -> None:
@@ -1124,11 +974,37 @@ class ScrollHelper:
         Log frame rate statistics for performance monitoring.
         """
         current_time = time.time()
-        
+
+        # The first frame of a scroll has no predecessor, so it has no frame
+        # time. Measuring one anyway records the whole idle gap since the last
+        # scroll as a single frame: on hardware that produced windows reading
+        # "0.0 fps over 1 frames | median 136776.02ms", and -- worse, because
+        # it is not obviously wrong -- put that gap in the max field of
+        # otherwise healthy windows and counted it as one stall per scroll.
+        # At ~500 frames to a window that is ~0.2%, which is the same order as
+        # the real stall rates being measured, so the number could not be
+        # trusted at all. Seed the clock and take no sample.
+        if self.last_frame_time is None:
+            self.last_frame_time = current_time
+            # Restart the window with the scroll. Otherwise the boundary is
+            # already long overdue when the second frame arrives, and the new
+            # scroll opens by reporting a window of exactly one frame.
+            self.last_fps_log_time = current_time
+            return
+
         # Calculate instantaneous frame time
         frame_time = current_time - self.last_frame_time
+
+        # A caller that scrolls without ever calling reset_scroll() never arms
+        # the sentinel above, so catch the same gap by its size. Nothing that
+        # renders a scroll produces a frame longer than the log interval; a
+        # sample that large is an idle period, not a frame.
+        if frame_time >= FPS_LOG_INTERVAL:
+            self.last_frame_time = current_time
+            return
+
         self.frame_times.append(frame_time)
-        
+
         # Keep only last 100 frames for average
         if len(self.frame_times) > 100:
             self.frame_times.pop(0)
@@ -1141,17 +1017,21 @@ class ScrollHelper:
         # duplicate and a 21ms double-wait mean exactly 10ms). Chasing scroll
         # judder needs the tail, so keep the window and report percentiles.
         self._window.append(frame_time)
-        
+
         # Log FPS every 5 seconds to avoid spam
-        if current_time - self.last_fps_log_time >= 5.0:
-            self.logger.info(
-                "Scroll frame stats - %s",
-                format_frame_stats(self._window or [frame_time]),
-            )
+        if current_time - self.last_fps_log_time >= FPS_LOG_INTERVAL:
+            # An empty window means every sample in this interval was dropped
+            # as an idle gap. There is nothing to report, and reporting the
+            # gap itself is the bug above.
+            if self._window:
+                self.logger.info(
+                    "Scroll frame stats - %s",
+                    format_frame_stats(self._window),
+                )
             self.last_fps_log_time = current_time
             self.frame_count = 0
             self._window = []
-        
+
         self.last_frame_time = current_time
         self.frame_count += 1
     

src/common/sports_card.py

@@ -22,6 +22,10 @@ from datetime import datetime, timezone
 from typing import Any, Dict, Optional, Tuple
 from zoneinfo import ZoneInfo
 
+from src.common.font_layout import (  # noqa: F401 - re-exported, see below
+    FONT_NAME_ALIASES, FONT_PIXEL_GRID, crisp_size,
+)
+
 logger = logging.getLogger(__name__)
 
 __all__ = [
@@ -52,18 +56,12 @@ FAVORITE_RESULT_COLOR_DEFAULTS: Dict[str, Tuple[int, int, int]] = {
     "tie": (255, 200, 0),
 }
 
-#: Family aliases the web UI may write, mapped to the shipped filename.
-FONT_NAME_ALIASES: Dict[str, str] = {
-    "press_start": "PressStart2P-Regular.ttf",
-    "four_by_six": "4x6-font.ttf",
-}
-
-#: Pixel grid each face renders crisply on. Off-grid sizes anti-alias, which
-#: on an LED matrix is a dim lamp rather than a soft edge.
-FONT_PIXEL_GRID: Dict[str, int] = {
-    "PressStart2P-Regular.ttf": 8,
-    "4x6-font.ttf": 7,
-}
+# Re-exported rather than defined: the grid tables and the snapping rule are
+# properties of the font files, which the display core needs too (it loads the
+# same two faces in DisplayManager._load_fonts). They live in
+# src/common/font_layout.py so there is one definition; they stay in this
+# module's namespace and __all__ so the eight scoreboards that delegate to
+# `sports_card.crisp_size` are untouched.
 
 MONTH_ABBR = ("Jan", "Feb", "Mar", "Apr", "May", "Jun",
               "Jul", "Aug", "Sep", "Oct", "Nov", "Dec")
@@ -99,38 +97,71 @@ def upcoming_center_mode(config: Optional[Dict[str, Any]]) -> str:
 # ---------------------------------------------------------------------------
 
 def element_color(config: Optional[Dict[str, Any]], element: str,
-                  default: Tuple[int, int, int] = (255, 255, 255)):
-    """Per-element text colour from customization.<element>.text_color."""
+                  default: Tuple[int, int, int] = (255, 255, 255),
+                  mode: Optional[str] = None):
+    """Per-element text colour from customization.<element>.text_color.
+
+    Delegated rather than reimplemented: there were two copies of this
+    read and three of the offset read, and the shared one also resolves
+    the element under the names plugins actually use (the layout block
+    says `score` where the style block says `score_text`) and honours a
+    per-mode override. Hex strings are still accepted.
+    """
+    from src.element_style import element_color as _shared
+    return _shared(config, element, default, mode)
+
+
+def resolve_font_color(config: Optional[Dict[str, Any]],
+                       fonts: Optional[Dict[str, Any]], font,
+                       default: Tuple[int, int, int],
+                       element_for_font: Dict[str, str],
+                       mode: Optional[str] = None):
+    """Colour for whichever element owns this face.
+
+    Identity matching is a stand-in for the element name, used where the draw
+    site only ever received a font. Prefer ``element=`` on the draw call; this
+    is the fallback for the sites that have not been annotated yet.
+
+    One object can legitimately belong to several elements -- a size resolver
+    can land two of them on the same face, and a BDF face cannot be un-shared
+    at all because ``freetype.Face`` objects cannot be rebuilt from a path.
+    Those draws used to go out white, which is how an element rendered in any
+    of the 32 shipped bitmap fonts could silently lose a colour the user had
+    set. So ambiguity is now narrowed before it is given up on: among the
+    elements sharing a face, a single configured colour is the only thing the
+    user can have meant, and several that agree mean the same thing. Only a
+    genuine disagreement falls back to *default*.
+
+    The element vocabulary is a parameter because the two callers disagree
+    about it -- the mixin's map says ``team_text`` where this module's says
+    ``team_name`` -- and quietly re-pointing either at the other's names would
+    change which colour setting a live install honours.
+    """
     try:
-        cfg = (config or {}).get("customization", {}).get(element, {})
-        value = cfg.get("text_color")
-        if isinstance(value, (list, tuple)) and len(value) == 3:
-            return tuple(max(0, min(255, int(c))) for c in value)
-        if isinstance(value, str) and value.startswith("#") and len(value) == 7:
-            return tuple(int(value[i:i + 2], 16) for i in (1, 3, 5))
-    except (TypeError, ValueError):
+        fonts = fonts or {}
+        matches = [element for key, element in element_for_font.items()
+                   if fonts.get(key) is font]
+        if len(matches) == 1:
+            return element_color(config, matches[0], default, mode)
+        if len(matches) > 1:
+            configured = []
+            for element in matches:
+                colour = element_color(config, element, None, mode)
+                if colour is not None and colour not in configured:
+                    configured.append(colour)
+            if len(configured) == 1:
+                return configured[0]
+    except (AttributeError, TypeError):
         pass
     return default
 
 
 def font_color(config: Optional[Dict[str, Any]], fonts: Optional[Dict[str, Any]],
-               font, default: Tuple[int, int, int] = (255, 255, 255)):
-    """Colour for whichever element owns this face.
-
-    Matched on identity, and deliberately gives up when one object is
-    shared: the last-resort font path can hand the same face to several
-    keys, and there is no right answer for which element's colour that is.
-    White is what those draws used before, so ambiguity costs nothing.
-    """
-    try:
-        fonts = fonts or {}
-        matches = [element for key, element in ELEMENT_FOR_FONT.items()
-                   if fonts.get(key) is font]
-        if len(matches) == 1:
-            return element_color(config, matches[0], default)
-    except (AttributeError, TypeError):
-        pass
-    return default
+               font, default: Tuple[int, int, int] = (255, 255, 255),
+               mode: Optional[str] = None):
+    """Colour for whichever element owns this face, by this module's map."""
+    return resolve_font_color(config, fonts, font, default, ELEMENT_FOR_FONT,
+                              mode)
 
 
 def coerce_rgb(value, fallback):
@@ -357,24 +388,6 @@ def format_game_time(config: Optional[Dict[str, Any]], time_text: str) -> str:
 _SCHEMA_FONT_SIZE_CACHE: Dict[str, Dict[str, int]] = {}
 
 
-def crisp_size(font_file, desired, aliases=None, grid_table=None):
-    """Snap *desired* to the nearest size *font_file* renders crisply at.
-
-    A face with no known grid is returned unchanged, so a user-supplied
-    font is never second-guessed.
-
-    ``aliases`` and ``grid_table`` default to the shared tables; a plugin
-    that ships an extra face can pass its own without forking this.
-    """
-    aliases = FONT_NAME_ALIASES if aliases is None else aliases
-    grid_table = FONT_PIXEL_GRID if grid_table is None else grid_table
-    font_file = aliases.get(font_file, font_file)
-    grid = grid_table.get(font_file)
-    if not grid or not desired or desired <= 0:
-        return desired
-    return max(grid, int(round(float(desired) / grid)) * grid)
-
-
 def schema_font_size(schema_path: str, element_key) -> Optional[int]:
     """The font_size this plugin's config_schema.json declares, or None.
 
@@ -448,7 +461,7 @@ def unshare_element_fonts(logger, fonts):
     path) are left shared, and their draws stay white as before.
     """
     try:
-        from PIL import ImageFont as _IF
+        from src.common.font_layout import load_truetype as _load
     except ImportError:  # pragma: no cover
         return fonts
     seen = {}
@@ -463,7 +476,7 @@ def unshare_element_fonts(logger, fonts):
         if not path or not size:
             continue
         try:
-            fonts[key] = _IF.truetype(path, size)
+            fonts[key] = _load(path, size)
         except (OSError, ValueError, TypeError):
             logger.debug(
                 "Could not un-share the %s face; it keeps the default colour", key)

src/common/sports_game_renderer.py

@@ -134,19 +134,9 @@ class SportsGameRendererMixin:
         the element on the scroll/Vegas card too -- previously the schema
         advertised these offsets but this renderer ignored them.
         """
-        try:
-            layout = (self.config or {}).get("customization", {}).get("layout", {})
-            value = (layout.get(element) or {}).get(axis, default)
-            if isinstance(value, bool):
-                return default
-            if isinstance(value, (int, float)):
-                return int(value) if math.isfinite(value) else default
-            if isinstance(value, str):
-                parsed = float(value)
-                return int(parsed) if math.isfinite(parsed) else default
-        except (TypeError, ValueError, OverflowError):
-            pass
-        return default
+        from src.element_style import layout_offset
+        return layout_offset(self.config, element, axis, default,
+                             getattr(self, "SKIN_MODE", None))
 
     # ---- upcoming cards ------------------------------------------------
 

src/common/sports_shared.py

@@ -191,7 +191,8 @@ class SportsCoreSharedMixin:
             img = Image.new("RGB", (self.display_width, self.display_height), (0, 0, 0))
             draw = ImageDraw.Draw(img)
             status = game.get("status_text", "N/A")
-            self._draw_text_with_outline(draw, status, (2, 2), self.fonts["status"])
+            self._draw_text_with_outline(draw, status, (2, 2), self.fonts["status"],
+                                         element="status_text")
             self.display_manager.image.paste(img, (0, 0))
             # Don't call update_display here, let subclasses handle it after drawing
         except Exception as e:
@@ -507,8 +508,10 @@ class SportsCoreSharedMixin:
                         + self._get_layout_offset('score', 'x_offset'))
                 vs_y = (center_y - 3
                         + self._get_layout_offset('score', 'y_offset'))
+                vs_x = self._aligned_x('score_text', vs_width, width, vs_x)
                 self._draw_text_with_outline(
-                    draw, vs_text, (vs_x, vs_y), self.fonts["score"]
+                    draw, vs_text, (vs_x, vs_y), self.fonts["score"],
+                    element="score_text"
                 )
 
         # "vs" and "none" both push the date and time out to the edges, time
@@ -757,18 +760,71 @@ class SportsCoreSharedMixin:
             self.logger.debug("Headline font scaling skipped", exc_info=True)
         return fonts
 
+    def _get_layout_offset(self, element: str, axis: str,
+                           default: int = 0) -> int:
+        """X/Y nudge for one element, from ``customization.layout``.
+
+        Promoted here so every scoreboard reads offsets the same way the
+        scroll card does. Each plugin still carries its own copy in its
+        bundled sports.py, which wins by MRO until that copy is deleted --
+        deleting it is what buys the alias handling (a plugin asking for
+        ``score_text`` finds the ``score`` its users configured) and the
+        per-mode overrides, since this resolves through SKIN_MODE.
+        """
+        from src.element_style import layout_offset
+        return layout_offset(self.config, element, axis, default,
+                             getattr(self, "SKIN_MODE", None))
+
     def _element_color(self, element: str, default: Tuple[int, int, int] = (255, 255, 255)):
-        """Per-element text colour from customization.<element>.text_color."""
-        try:
-            cfg = (self.config or {}).get("customization", {}).get(element, {})
-            value = cfg.get("text_color")
-            if isinstance(value, (list, tuple)) and len(value) == 3:
-                return tuple(max(0, min(255, int(c))) for c in value)
-            if isinstance(value, str) and value.startswith("#") and len(value) == 7:
-                return tuple(int(value[i:i + 2], 16) for i in (1, 3, 5))
-        except (TypeError, ValueError):
-            pass
-        return default
+        """Per-element text colour from customization.<element>.text_color.
+
+        Mode-aware through SKIN_MODE, so Live and Recent instances of the
+        same scoreboard resolve their own colours without any call site
+        passing a mode.
+        """
+        from src.element_style import element_color as _shared
+        return _shared(self.config, element, default,
+                       getattr(self, "SKIN_MODE", None))
+
+    def _element_visible(self, element: str, default: bool = True) -> bool:
+        """Whether ``customization.<element>.visible`` allows this draw.
+
+        Mode-aware like the colour read, so a user can hide the records on the
+        recent card and keep them on the upcoming one.
+        """
+        from src.element_style import element_visible
+        return element_visible(self.config, element, default,
+                               getattr(self, "SKIN_MODE", None))
+
+    def _element_align(self, element: str, default: Optional[str] = None):
+        """``customization.<element>.align``: 'left', 'center' or 'right'."""
+        from src.element_style import element_align
+        return element_align(self.config, element, default,
+                             getattr(self, "SKIN_MODE", None))
+
+    def _element_scale(self, element: str, default: float = 1.0) -> float:
+        """``customization.layout.<element>.scale`` -- logos, mostly."""
+        from src.element_style import element_scale
+        return element_scale(self.config, element, default,
+                             getattr(self, "SKIN_MODE", None))
+
+    def _aligned_x(self, element: str, text_width: float, container_width: int,
+                   centered_x: float) -> float:
+        """Where a run of text starts, honouring ``align``.
+
+        Unset means "leave it exactly where it was", so this returns the
+        caller's own x rather than re-deriving a centre: these draws have
+        accumulated per-sport nudges and a centre computed here would not be
+        the same pixel.
+        """
+        align = self._element_align(element)
+        if not align:
+            return centered_x
+        if align == 'left':
+            return 0
+        if align == 'right':
+            return max(0, container_width - text_width)
+        return centered_x
 
     def _unshare_element_fonts(self, fonts):
         """Give each colourable element its own face object.
@@ -787,7 +843,7 @@ class SportsCoreSharedMixin:
         path) are left shared, and their draws stay white as before.
         """
         try:
-            from PIL import ImageFont as _IF
+            from src.common.font_layout import load_truetype as _load
         except ImportError:  # pragma: no cover
             return fonts
         seen = {}
@@ -802,7 +858,7 @@ class SportsCoreSharedMixin:
             if not path or not size:
                 continue
             try:
-                fonts[key] = _IF.truetype(path, size)
+                fonts[key] = _load(path, size)
             except (OSError, ValueError, TypeError):
                 self.logger.debug(
                     "Could not un-share the %s face; it keeps the default colour", key)
@@ -811,25 +867,31 @@ class SportsCoreSharedMixin:
     def _font_color(self, font, default: Tuple[int, int, int] = (255, 255, 255)):
         """Colour for whichever element owns this face.
 
-        Matched on identity, and deliberately gives up when one object is
-        shared: the last-resort font path can hand the same face to several
-        keys, and there is no right answer for which element's colour that is.
-        White is what those draws used before, so ambiguity costs nothing.
+        The fallback for draw sites that were only ever handed a font. Prefer
+        ``element=`` on :meth:`_draw_text_with_outline`, which needs none of
+        this. Shared with the scroll card's copy so the narrowing rule that
+        rescues bitmap-font colours lives in one place; the element vocabulary
+        stays this class's own, because its map says ``team_text`` where
+        sports_card's says ``team_name``.
         """
-        try:
-            fonts = getattr(self, "fonts", None) or {}
-            matches = [element for key, element in self._ELEMENT_FOR_FONT.items()
-                       if fonts.get(key) is font]
-            if len(matches) == 1:
-                return self._element_color(matches[0], default)
-        except (AttributeError, TypeError):
-            pass
-        return default
+        from src.common.sports_card import resolve_font_color
+        return resolve_font_color(
+            getattr(self, "config", None), getattr(self, "fonts", None), font,
+            default, self._ELEMENT_FOR_FONT, getattr(self, "SKIN_MODE", None))
 
     def _draw_text_with_outline(
-        self, draw, text, position, font, fill=None, outline_color=(0, 0, 0)
+        self, draw, text, position, font, fill=None, outline_color=(0, 0, 0),
+        element=None
     ):
-        """Draw text with a black outline for better readability."""
+        """Draw text with a black outline for better readability.
+
+        Pass ``element`` (``"score_text"``, ``"status_text"``, ...) wherever the
+        caller knows what it is drawing: the colour is then read by name, which
+        is exact. Without it the colour has to be inferred from the identity of
+        the font object, which cannot tell two elements apart when they share a
+        face -- the case every bitmap font is in, because a ``freetype.Face``
+        cannot be re-instantiated.
+        """
         # Disable anti-aliasing: pixel/bitmap fonts (e.g. PressStart2P) get
         # anti-aliased into dim partial-lit pixels on a 1:1 LED matrix, muddying
         # glyphs. 1-bit mode keeps strokes crisp.
@@ -839,7 +901,14 @@ class SportsCoreSharedMixin:
         # and they only ever changed the font. An explicit fill still wins:
         # the odds colours and the favourite-result score tint mean something
         # the palette does not.
-        if fill is None:
+        if element is not None:
+            # Named, so both questions can be answered exactly: whether this
+            # element is meant to be on screen at all, and what colour it is.
+            if not self._element_visible(element):
+                return
+            if fill is None:
+                fill = self._element_color(element)
+        elif fill is None:
             fill = self._font_color(font)
         draw.fontmode = "1"
         x, y = position

src/common/sync_manager.py

@@ -32,6 +32,8 @@ from typing import Callable, Optional
 import numpy as np
 from PIL import Image
 
+from src.display_geometry import DEFAULT_CHAIN_LENGTH
+
 # Raw-frame wire format: 8-byte magic + 4-byte header + raw RGB pixels
 # Much faster than PNG: no encode/decode, negligible CPU, same UDP packet size
 _RAW_MAGIC = b'SYNC_RAW'
@@ -194,7 +196,7 @@ class DisplaySyncManager:
         local_cols = hw.get("cols", 64)
         peer_rows = int(msg.get("rows", 0))
         peer_cols = int(msg.get("cols", 0))
-        peer_chain = int(msg.get("chain", 1))
+        peer_chain = int(msg.get("chain", DEFAULT_CHAIN_LENGTH))
 
         compatible = peer_rows == local_rows and peer_cols == local_cols
 
@@ -589,7 +591,7 @@ class DisplaySyncManager:
             "t": "hello",
             "rows": hw.get("rows", 32),
             "cols": hw.get("cols", 64),
-            "chain": hw.get("chain_length", 1),
+            "chain": hw.get("chain_length", DEFAULT_CHAIN_LENGTH),
         }).encode("utf-8")
         heartbeat = json.dumps({"t": "hb"}).encode("utf-8")
         dest = ("<broadcast>", self.port)
@@ -660,7 +662,7 @@ class DisplaySyncManager:
             "port": self.port,
             "local_rows": hw.get("rows", 32),
             "local_cols": hw.get("cols", 64),
-            "local_chain": hw.get("chain_length", 1),
+            "local_chain": hw.get("chain_length", DEFAULT_CHAIN_LENGTH),
         }
 
         if self.role == SyncRole.STANDALONE:

src/config_manager_atomic.py

@@ -7,9 +7,10 @@ and enable recovery from failed saves.
 
 import json
 import os
+import re
 import shutil
 import tempfile
-from datetime import datetime
+from datetime import datetime, timedelta
 from pathlib import Path
 from typing import Dict, Any, Optional, List, Tuple
 from dataclasses import dataclass
@@ -19,6 +20,19 @@ from src.exceptions import ConfigError
 from src.logging_config import get_logger
 from src.common.permission_utils import ensure_shared_group_ownership
 
+# Version stamp in a backup's filename: config.json.backup.<version>.
+BACKUP_VERSION_FORMAT = "%Y%m%d_%H%M%S_%f"
+
+# Backups written before the format gained microseconds. Still read, never
+# written, so existing restore points on a rig stay usable after an upgrade.
+LEGACY_BACKUP_VERSION_FORMAT = "%Y%m%d_%H%M%S"
+
+# The numeric collision suffix _create_backup() appends to break a same-tick
+# tie: config.json.backup.<version>-<N>. Only digits count as this suffix, so
+# a hand-copied or renamed backup that happens to end in "-something" isn't
+# mistaken for one and silently mis-parsed.
+_BACKUP_COLLISION_SUFFIX_RE = re.compile(r"^(?P<base>.+)-(?P<collision>\d+)$")
+
 
 class SaveResultStatus(Enum):
     """Status of a save operation."""
@@ -246,23 +260,34 @@ class AtomicConfigManager:
         if not self.backup_dir.exists():
             return backups
         
-        # Look for backup files (format: config.json.backup.YYYYMMDD_HHMMSS)
+        # Look for backup files (format: config.json.backup.<version>)
         config_name = self.config_path.name
         backup_pattern = f"{config_name}.backup.*"
-        
+
         for backup_file in self.backup_dir.glob(backup_pattern):
             try:
-                # Extract timestamp from filename
-                # Format: config.json.backup.20240101_120000
-                parts = backup_file.stem.split('.')
-                if len(parts) >= 3 and parts[-2] == 'backup':
-                    timestamp_str = parts[-1]
-                    timestamp = datetime.strptime(timestamp_str, "%Y%m%d_%H%M%S")
-                else:
-                    # Fallback: use file modification time
+                # The version reported here is what rollback_config() matches
+                # against, so it has to be the exact string in the filename.
+                #
+                # It did not used to be. This read .stem, which drops only the
+                # last dot-component, so for config.json.backup.20240101_120000
+                # parts was ['config', 'json', 'backup'] and parts[-2] was
+                # 'json' -- never 'backup'. The filename branch could not be
+                # reached, every backup fell through to the mtime fallback, and
+                # the version was a second-granularity restamp of the mtime
+                # rather than the name on disk. Two backups a second apart could
+                # therefore report the same version, and rollback would pick
+                # whichever the glob happened to yield first.
+                # Strip the exact prefix the glob just matched, so a config
+                # whose own name contains '.backup.' can't shift the split.
+                timestamp_str = backup_file.name[len(f"{config_name}.backup."):]
+                timestamp = self._parse_backup_version(timestamp_str)
+                if timestamp is None:
+                    # Not a version this code wrote (hand-copied, renamed).
+                    # Order it by mtime, but keep the on-disk version string so
+                    # it can still be named in a rollback.
                     timestamp = datetime.fromtimestamp(backup_file.stat().st_mtime)
-                    timestamp_str = timestamp.strftime("%Y%m%d_%H%M%S")
-                
+
                 # Validate backup file
                 is_valid = self._validate_backup_file(backup_file)
                 
@@ -283,6 +308,35 @@ class AtomicConfigManager:
         
         return backups
     
+    @staticmethod
+    def _parse_backup_version(version: str) -> Optional[datetime]:
+        """
+        Parse the ``<version>`` of a ``config.json.backup.<version>`` filename
+        into the time the backup was taken, or None if it is not a version this
+        class wrote.
+
+        Accepts the current microsecond format and the legacy second-granularity
+        one, with or without the ``-N`` suffix _create_backup() appends to break
+        a collision. When that suffix is present, N is folded into the result
+        as extra microseconds so same-tick collisions still sort in the order
+        they were created rather than tying.
+        """
+        if not version:
+            return None
+        base = version
+        collision = 0
+        match = _BACKUP_COLLISION_SUFFIX_RE.match(version)
+        if match:
+            base = match.group('base')
+            collision = int(match.group('collision'))
+        for fmt in (BACKUP_VERSION_FORMAT, LEGACY_BACKUP_VERSION_FORMAT):
+            try:
+                parsed = datetime.strptime(base, fmt)
+            except ValueError:
+                continue
+            return parsed + timedelta(microseconds=collision) if collision else parsed
+        return None
+
     def validate_config_file(self, config_path: Optional[str] = None) -> ValidationResult:
         """
         Validate a configuration file.
@@ -303,19 +357,55 @@ class AtomicConfigManager:
             return None
         
         try:
-            # Generate backup filename with timestamp
-            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            # Generate backup filename with timestamp.
+            #
+            # This id is the backup's identity: save_config_atomic() returns the
+            # path, rollback_config(backup_version=...) looks the version up, and
+            # the paired secrets backup is found by reusing the same string. At
+            # second granularity two saves inside the same second produced the
+            # same filename, so the second copy2() below silently overwrote the
+            # first backup -- the path a caller was still holding then pointed at
+            # different content, and rolling back to it restored the wrong
+            # config. Microseconds make that collision vanishingly unlikely.
             config_name = self.config_path.name
-            backup_filename = f"{config_name}.backup.{timestamp}"
-            backup_path = self.backup_dir / backup_filename
-            
+            backup_secrets = bool(self.secrets_path and self.secrets_path.exists())
+
+            # exists() then copy2() is two steps: two concurrent callers can
+            # both see the path as free and pick the same one, so the second
+            # copy2() silently destroys the first call's restore point.
+            # Reserve the filename(s) with exclusive creation instead -- that
+            # is atomic, so only one caller can ever win a given timestamp.
+            # Each retry bumps the collision suffix, so this always
+            # terminates and stays compatible with _parse_backup_version().
+            collision = 0
+            while True:
+                timestamp = datetime.now().strftime(BACKUP_VERSION_FORMAT)
+                if collision:
+                    timestamp = f"{timestamp}-{collision}"
+                backup_path = self.backup_dir / f"{config_name}.backup.{timestamp}"
+                secrets_backup_path = (
+                    self.backup_dir / f"{self.secrets_path.name}.backup.{timestamp}"
+                    if backup_secrets else None
+                )
+                try:
+                    backup_path.touch(exist_ok=False)
+                except FileExistsError:
+                    collision += 1
+                    continue
+                if secrets_backup_path is not None:
+                    try:
+                        secrets_backup_path.touch(exist_ok=False)
+                    except FileExistsError:
+                        backup_path.unlink(missing_ok=True)
+                        collision += 1
+                        continue
+                break
+
             # Copy config file to backup
             shutil.copy2(self.config_path, backup_path)
-            
+
             # Also backup secrets file if it exists
-            if self.secrets_path and self.secrets_path.exists():
-                secrets_backup_filename = f"{self.secrets_path.name}.backup.{timestamp}"
-                secrets_backup_path = self.backup_dir / secrets_backup_filename
+            if secrets_backup_path is not None:
                 shutil.copy2(self.secrets_path, secrets_backup_path)
             
             # Rotate old backups

src/display_controller.py

@@ -119,6 +119,15 @@ class DisplayController:
                 # validator.raise_on_errors()  # Uncomment to fail fast on errors
         except Exception as e:
             logger.warning(f"Startup validation could not be completed: {e}")
+
+        # Automatic updates need their health-check units, and this is the
+        # one root process running project code, so it installs them while
+        # automatic updates are on. See src/auto_update_setup.py.
+        try:
+            from src.auto_update_setup import ensure_update_helper
+            ensure_update_helper(self.config)
+        except Exception as e:
+            logger.warning("Automatic update setup could not be completed: %s", e)
         
         config_time = time.time()
         self.display_manager = DisplayManager(self.config)
@@ -2169,7 +2178,14 @@ class DisplayController:
                                         types.SimpleNamespace(display=_display_target),
                                         plugin_id,
                                         force_clear=self.force_change,
-                                        display_mode=active_mode if _accepts_display_mode else None
+                                        display_mode=active_mode if _accepts_display_mode else None,
+                                        # Already resolved and cached above.
+                                        # Without this the executor re-derives
+                                        # it with inspect.signature() against
+                                        # the SimpleNamespace built two lines
+                                        # up -- a fresh callable every call, so
+                                        # nothing there can ever cache.
+                                        accepts_display_mode=_accepts_display_mode
                                     )
                                 except Exception:  # pragma: no cover - defensive;
                                     # execute_display catches everything
@@ -2492,6 +2508,15 @@ class DisplayController:
                                 1.0 / display_interval
                             )
 
+                            # Deliberate: frames after the first call
+                            # display() directly rather than through
+                            # PluginExecutor. The executor spawns a thread per
+                            # call, which at this loop's frame rate would cost
+                            # more than the advisory timeout it buys -- and
+                            # that timeout cannot cancel a hung plugin anyway
+                            # (see execute_with_timeout). The first dispatch
+                            # above still goes through it, so load-time
+                            # failures are still caught and recorded.
                             while True:
                                 _frame_start = time.perf_counter()
                                 try:
@@ -2564,6 +2589,15 @@ class DisplayController:
                                 display_interval
                             )
 
+                            # Deliberate: frames after the first call
+                            # display() directly rather than through
+                            # PluginExecutor. The executor spawns a thread per
+                            # call, which at this loop's frame rate would cost
+                            # more than the advisory timeout it buys -- and
+                            # that timeout cannot cancel a hung plugin anyway
+                            # (see execute_with_timeout). The first dispatch
+                            # above still goes through it, so load-time
+                            # failures are still caught and recorded.
                             while True:
                                 time.sleep(display_interval)
                                 self._tick_plugin_updates()

src/display_geometry.py

@@ -0,0 +1,144 @@
+"""Display size from config: the one computation every caller shares.
+
+``DisplayManager`` sizes its canvas from ``display.hardware`` plus
+``display.double_sided``. The web preview, the Starlark magnify default and
+the multi-display sync handshake used to re-derive that size themselves,
+each with its own defaults (``chain_length`` fell back to 2 in one place and
+1 in three others) and none of them applying double-sided mode. They now all
+call this module.
+
+Kept free of hardware imports on purpose: the web interface imports it, and
+``display_manager`` pulls in ``rgbmatrix``.
+"""
+
+import logging
+from typing import Any, Dict, Mapping, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+# Match config/config.template.json's display.hardware block.
+DEFAULT_ROWS = 32
+DEFAULT_COLS = 64
+DEFAULT_CHAIN_LENGTH = 2
+DEFAULT_PARALLEL = 1
+
+
+def _display(config: Optional[Mapping[str, Any]]) -> Mapping[str, Any]:
+    # A hand-edited config.json can hold anything here; treat a non-mapping
+    # like a missing block so callers get the defaults, not AttributeError.
+    display = (config or {}).get('display')
+    return display if isinstance(display, Mapping) else {}
+
+
+def _hardware(config: Optional[Mapping[str, Any]]) -> Mapping[str, Any]:
+    hw = _display(config).get('hardware')
+    return hw if isinstance(hw, Mapping) else {}
+
+
+def physical_size(config: Optional[Mapping[str, Any]]) -> Tuple[int, int]:
+    """Width and height of the whole panel chain, in pixels.
+
+    ``cols * chain_length`` by ``rows * parallel``. Raises ``ValueError`` or
+    ``TypeError`` on a non-numeric value, as ``DisplayManager`` does; callers
+    decide their own fallback.
+
+    A non-finite value (``Infinity``, which Python's JSON parser accepts in a
+    hand-edited config.json) raises ``ValueError`` too, not ``OverflowError``,
+    so every caller's existing fallback catches it.
+    """
+    hw = _hardware(config)
+    try:
+        rows = int(hw.get('rows', DEFAULT_ROWS))
+        cols = int(hw.get('cols', DEFAULT_COLS))
+        chain_length = int(hw.get('chain_length', DEFAULT_CHAIN_LENGTH))
+        parallel = int(hw.get('parallel', DEFAULT_PARALLEL))
+    except OverflowError as e:
+        raise ValueError(f"display.hardware size is not finite: {e}") from e
+    return max(1, cols * chain_length), max(1, rows * parallel)
+
+
+def resolve_double_sided(physical_width: int, physical_height: int,
+                         ds_config: Dict[str, Any],
+                         quiet: bool = False) -> Optional[Dict[str, Any]]:
+    """Validate the ``display.double_sided`` config against the physical size.
+
+    Returns a dict ``{copies, axis, logical_width, logical_height}`` when the
+    feature is enabled and the physical panel divides evenly into ``copies``
+    along the chosen axis, otherwise ``None`` (single-screen behaviour). Bad
+    config is logged and disabled rather than raised — a misconfigured panel
+    should still light up.
+
+    Only pixels are checked, not whole panels: ``chain_length`` and
+    ``parallel`` don't say which axis a panel lies on once an orientation
+    ``Rotate:`` or U-mapper ``pixel_mapper_config`` rearranges the chain.
+
+    ``quiet`` suppresses the log lines, for callers that run on every web
+    request and would otherwise repeat them on each poll.
+    """
+    def _log(level, *args):
+        if not quiet:
+            logger.log(level, *args)
+
+    if not isinstance(ds_config, dict) or not ds_config.get('enabled', False):
+        return None
+
+    copies = ds_config.get('copies', 2)
+    if not isinstance(copies, int) or copies < 2:
+        _log(logging.WARNING,
+             "double_sided: 'copies' must be an integer >= 2 (got %r); "
+             "disabling double-sided mode", copies)
+        return None
+
+    axis = ds_config.get('axis', 'horizontal')
+    if axis not in ('horizontal', 'vertical'):
+        _log(logging.WARNING,
+             "double_sided: 'axis' must be 'horizontal' or 'vertical' "
+             "(got %r); defaulting to 'horizontal'", axis)
+        axis = 'horizontal'
+
+    # Horizontal splits the chain (panels side by side); vertical splits the
+    # parallel outputs (panels stacked). The split axis must divide evenly.
+    if axis == 'horizontal':
+        if physical_width % copies != 0:
+            _log(logging.WARNING,
+                 "double_sided: physical width %d is not divisible by copies "
+                 "%d; disabling double-sided mode", physical_width, copies)
+            return None
+        logical_width = physical_width // copies
+        logical_height = physical_height
+    else:
+        if physical_height % copies != 0:
+            _log(logging.WARNING,
+                 "double_sided: physical height %d is not divisible by copies "
+                 "%d; disabling double-sided mode", physical_height, copies)
+            return None
+        logical_width = physical_width
+        logical_height = physical_height // copies
+
+    _log(logging.INFO,
+         "double_sided enabled: %d copies on %s axis — logical screen %dx%d "
+         "tiled across physical %dx%d", copies, axis, logical_width,
+         logical_height, physical_width, physical_height)
+    return {
+        'copies': copies,
+        'axis': axis,
+        'logical_width': logical_width,
+        'logical_height': logical_height,
+    }
+
+
+def logical_size(config: Optional[Mapping[str, Any]],
+                 quiet: bool = True) -> Tuple[int, int]:
+    """The size plugins draw at and the web preview shows.
+
+    The physical size, divided by ``double_sided.copies`` along its axis when
+    double-sided mode is enabled and valid — the same answer
+    ``DisplayManager.width``/``height`` give.
+    """
+    width, height = physical_size(config)
+    ds = resolve_double_sided(width, height,
+                              _display(config).get('double_sided') or {},
+                              quiet=quiet)
+    if ds is not None:
+        return ds['logical_width'], ds['logical_height']
+    return width, height

src/display_manager.py

@@ -34,7 +34,11 @@ else:
 from contextlib import contextmanager
 from pathlib import Path
 from PIL import Image, ImageDraw, ImageFont
-from src.common.font_layout import load_truetype
+from src.common.font_layout import crisp_size, load_truetype, resolve_asset_path
+from src.display_geometry import (
+    DEFAULT_CHAIN_LENGTH, DEFAULT_COLS, DEFAULT_PARALLEL, DEFAULT_ROWS,
+    physical_size, resolve_double_sided,
+)
 import threading
 import time
 from collections import OrderedDict
@@ -123,62 +127,10 @@ class _LogicalMatrix:
         setattr(object.__getattribute__(self, "_matrix"), name, value)
 
 
-def _resolve_double_sided(physical_width: int, physical_height: int,
-                          ds_config: Dict[str, Any]) -> Optional[Dict[str, Any]]:
-    """Validate the ``display.double_sided`` config against the physical size.
-
-    Returns a dict ``{copies, axis, logical_width, logical_height}`` when the
-    feature is enabled and the physical panel divides evenly into ``copies``
-    along the chosen axis, otherwise ``None`` (single-screen behaviour). Bad
-    config is logged and disabled rather than raised — a misconfigured panel
-    should still light up.
-    """
-    if not isinstance(ds_config, dict) or not ds_config.get('enabled', False):
-        return None
-
-    copies = ds_config.get('copies', 2)
-    if not isinstance(copies, int) or copies < 2:
-        logger.warning(
-            "double_sided: 'copies' must be an integer >= 2 (got %r); "
-            "disabling double-sided mode", copies)
-        return None
-
-    axis = ds_config.get('axis', 'horizontal')
-    if axis not in ('horizontal', 'vertical'):
-        logger.warning(
-            "double_sided: 'axis' must be 'horizontal' or 'vertical' "
-            "(got %r); defaulting to 'horizontal'", axis)
-        axis = 'horizontal'
-
-    # Horizontal splits the chain (panels side by side); vertical splits the
-    # parallel outputs (panels stacked). The split axis must divide evenly.
-    if axis == 'horizontal':
-        if physical_width % copies != 0:
-            logger.warning(
-                "double_sided: physical width %d is not divisible by copies "
-                "%d; disabling double-sided mode", physical_width, copies)
-            return None
-        logical_width = physical_width // copies
-        logical_height = physical_height
-    else:
-        if physical_height % copies != 0:
-            logger.warning(
-                "double_sided: physical height %d is not divisible by copies "
-                "%d; disabling double-sided mode", physical_height, copies)
-            return None
-        logical_width = physical_width
-        logical_height = physical_height // copies
-
-    logger.info(
-        "double_sided enabled: %d copies on %s axis — logical screen %dx%d "
-        "tiled across physical %dx%d", copies, axis, logical_width,
-        logical_height, physical_width, physical_height)
-    return {
-        'copies': copies,
-        'axis': axis,
-        'logical_width': logical_width,
-        'logical_height': logical_height,
-    }
+# Moved to src/display_geometry.py so the web preview, Starlark magnify and
+# sync handshake compute the display size exactly as DisplayManager does
+# without importing rgbmatrix. Aliased here for existing callers.
+_resolve_double_sided = resolve_double_sided
 
 
 class DisplayManager:
@@ -327,10 +279,10 @@ class DisplayManager:
             runtime_config = self.config.get('display', {}).get('runtime', {})
             
             # Basic hardware settings
-            options.rows = hardware_config.get('rows', 32)
-            options.cols = hardware_config.get('cols', 64)
-            options.chain_length = hardware_config.get('chain_length', 2)
-            options.parallel = hardware_config.get('parallel', 1)
+            options.rows = hardware_config.get('rows', DEFAULT_ROWS)
+            options.cols = hardware_config.get('cols', DEFAULT_COLS)
+            options.chain_length = hardware_config.get('chain_length', DEFAULT_CHAIN_LENGTH)
+            options.parallel = hardware_config.get('parallel', DEFAULT_PARALLEL)
             options.hardware_mapping = hardware_config.get('hardware_mapping', 'adafruit-hat-pwm')
             
             # Performance and stability settings
@@ -403,7 +355,9 @@ class DisplayManager:
             
             # Initialize font with Press Start 2P
             try:
-                self.font = load_truetype("assets/fonts/PressStart2P-Regular.ttf", 8)
+                self.font = load_truetype(
+                    self._font_asset(self._PRESS_START),
+                    crisp_size(self._PRESS_START, 8))
                 logger.info("Initial Press Start 2P font loaded successfully")
             except Exception as e:
                 logger.error(f"Failed to load initial font: {e}")
@@ -419,13 +373,7 @@ class DisplayManager:
             # Create a fallback image for web preview using configured dimensions when available
             self.matrix = None
             try:
-                hardware_config = self.config.get('display', {}).get('hardware', {}) if self.config else {}
-                rows = int(hardware_config.get('rows', 32))
-                cols = int(hardware_config.get('cols', 64))
-                chain_length = int(hardware_config.get('chain_length', 2))
-                parallel = int(hardware_config.get('parallel', 1))
-                fallback_width = max(1, cols * chain_length)
-                fallback_height = max(1, rows * parallel)
+                fallback_width, fallback_height = physical_size(self.config)
                 # Mirror double-sided in fallback so the preview shows one screen.
                 ds_config = self.config.get('display', {}).get('double_sided', {}) if self.config else {}
                 ds = _resolve_double_sided(fallback_width, fallback_height, ds_config)
@@ -592,9 +540,19 @@ class DisplayManager:
         Pillow had; with the engine pinned it does not, so the rung the
         worst case actually needs is here rather than implied.
         """
+        # The middle rung is on the 7px grid; the bottom one is deliberately
+        # not. 4x6 advances the same whether it is asked for 6 or 7 -- the
+        # dotted quad is 66px at both -- so the middle rung costs no width and
+        # gains the fourth column in every glyph, which is the difference
+        # between reading an address off a wall and guessing at it. The 5 rung
+        # is the exception this screen needs: it drops the advance to 4px and
+        # the quad to 51px, the only rung that fits a 64px panel, and no
+        # on-grid size does that. It is the one place in the core that draws
+        # 4x6 off-grid on purpose.
         candidates = [self.font,
-                      ("assets/fonts/4x6-font.ttf", 6),
-                      ("assets/fonts/4x6-font.ttf", 5)]
+                      (self._font_asset(self._FOUR_BY_SIX),
+                       crisp_size(self._FOUR_BY_SIX, 6)),
+                      (self._font_asset(self._FOUR_BY_SIX), 5)]
         narrowest = None
         for candidate in candidates:
             try:
@@ -966,6 +924,28 @@ class DisplayManager:
         except Exception as e:
             logger.error(f"Error drawing BDF text: {e}", exc_info=True)
 
+    #: The bundled faces, and the size each is *asked* for. Every size here is
+    #: run through `crisp_size`, so a number that drifts off the face's pixel
+    #: grid is snapped rather than rendered anti-aliased -- see the note on
+    #: `extra_small_font` below.
+    _FONT_DIR = "assets/fonts"
+    _PRESS_START = "PressStart2P-Regular.ttf"
+    _FOUR_BY_SIX = "4x6-font.ttf"
+
+    @classmethod
+    def _font_asset(cls, filename: str) -> str:
+        """Install-root-relative path to a bundled face.
+
+        `_load_fonts` named these relative to the process cwd, which holds
+        under the packaged systemd unit (WorkingDirectory is the install root)
+        and nowhere else: the plugin safety harness, `python run.py` from
+        $HOME, or a unit file written without WorkingDirectory all loaded
+        nothing and fell through to `ImageFont.load_default()`. That failure is
+        silent -- the panel just renders in PIL's default face at whatever size
+        the layout was computed for.
+        """
+        return resolve_asset_path(f"{cls._FONT_DIR}/{filename}")
+
     def _load_fonts(self):
         """Load fonts with proper error handling."""
         # Font objects get new id()s after reload, so the text-width cache would
@@ -973,16 +953,17 @@ class DisplayManager:
         self._text_width_cache.clear()
         try:
             # Load Press Start 2P font
-            self.regular_font = load_truetype("assets/fonts/PressStart2P-Regular.ttf", 8)
+            press_start = self._font_asset(self._PRESS_START)
+            self.regular_font = load_truetype(press_start, crisp_size(self._PRESS_START, 8))
             logger.info("Press Start 2P font loaded successfully")
             
             # Use the same font for small text (currently same size; adjust size here if needed)
-            self.small_font = load_truetype("assets/fonts/PressStart2P-Regular.ttf", 8)
+            self.small_font = load_truetype(press_start, crisp_size(self._PRESS_START, 8))
             logger.info("Press Start 2P small font loaded successfully")
 
             # Load 5x7 BDF font for calendar events
             try:
-                self.calendar_font_path = "assets/fonts/5x7.bdf"
+                self.calendar_font_path = self._font_asset("5x7.bdf")
                 logger.info(f"Attempting to load 5x7 font from: {self.calendar_font_path}")
                 
                 if not os.path.exists(self.calendar_font_path):
@@ -1017,11 +998,26 @@ class DisplayManager:
             self.bdf_5x7_font = self.calendar_font 
             logger.info(f"Assigned calendar_font (type: {type(self.bdf_5x7_font).__name__}) to bdf_5x7_font.")
 
-            # Load 4x6 font as extra_small_font
+            # Load 4x6 font as extra_small_font.
+            #
+            # Asked for 6 -- the size the face's name suggests -- for years,
+            # and 6 is off its 7px pixel grid. Plugins draw this face with
+            # `draw.fontmode = "1"`, and the mono rasteriser thresholds each
+            # glyph at 50% coverage, so off-grid every glyph came out 3px wide
+            # instead of 4. The lost column deforms the letterforms rather than
+            # merely thinning them: christmas-countdown rendered "UNTIL" as
+            # "VM1JL" and "CHRISTMAS" as "CHAJS1MAS", and zero loses the left
+            # half of its bowl. Those renders were committed as golden images.
+            #
+            # `crisp_size` snaps it to 7. The advance is unchanged -- 5px per
+            # glyph at either size -- so nothing reflows and no layout gets
+            # tighter; a string is at most a pixel or two wider because the
+            # last glyph finally occupies the width it was always given.
             try:
-                font_path = "assets/fonts/4x6-font.ttf"
-                logger.info(f"Attempting to load 4x6 TTF font from: {font_path} at size 6")
-                self.extra_small_font = load_truetype(font_path, 6)
+                font_path = self._font_asset(self._FOUR_BY_SIX)
+                size = crisp_size(self._FOUR_BY_SIX, 6)
+                logger.info(f"Attempting to load 4x6 TTF font from: {font_path} at size {size}")
+                self.extra_small_font = load_truetype(font_path, size)
                 logger.info(f"4x6 TTF extra small font loaded successfully from {font_path}")
             except Exception as font_err:
                 logger.error(f"Failed to load 4x6 TTF font: {font_err}. Falling back.")

src/font_manager.py

@@ -38,7 +38,7 @@ import time
 from collections import OrderedDict
 from pathlib import Path
 from PIL import ImageFont
-from src.common.font_layout import load_truetype
+from src.common.font_layout import load_truetype, resolve_asset_path
 from typing import Dict, Tuple, Optional, Union, Any, List
 
 logger = logging.getLogger(__name__)
@@ -665,20 +665,14 @@ class FontManager:
     def _resolve_asset_path(relative_path: str) -> str:
         """Resolve a repo-relative asset path independently of the process cwd.
 
-        Prefers the working directory (preserving behavior when the process
-        runs from the install root), then falls back to the install root
-        derived from this module's own location. Without the fallback, any
-        process started outside the install root (e.g. the plugin safety
-        harness on CI) silently loses every font and degrades to PIL's
-        default face.
+        Thin delegate to :func:`src.common.font_layout.resolve_asset_path`,
+        which holds the one definition (``DisplayManager._load_fonts`` needs
+        the same resolution and must not import this class for it). The method
+        stays because plugins probe for it by name to share the core's notion
+        of "install root" -- see the `_resolve_font_path` helpers in the
+        scoreboard plugins.
         """
-        if os.path.exists(relative_path):
-            return relative_path
-        install_root = Path(__file__).resolve().parent.parent
-        candidate = install_root / relative_path
-        if candidate.exists():
-            return str(candidate)
-        return relative_path
+        return resolve_asset_path(relative_path)
 
     def _initialize_fonts(self):
         """Initialize font catalog and validate configuration."""

src/plugin_system/base_plugin.py

@@ -12,11 +12,47 @@ from abc import ABC, abstractmethod
 from enum import Enum
 from typing import Dict, Any, Optional, List
 import logging
+import os
+import sys
 from src.logging_config import get_logger
 
 
 _shared_fallback_font_manager: Optional[Any] = None
 
+#: Distinguishes "not looked up yet" from "looked up and not found", so a
+#: plugin with no schema does not re-scan the disk on every frame.
+_UNSET_SCHEMA_PATH = object()
+
+
+class _NullStyleResolver:
+    """Stand-in for ElementStyleResolver when the module is unavailable.
+
+    Only reachable on a core that predates src.element_style, which
+    ``styles`` degrades to rather than raising: every lookup returns the
+    caller's classic values, which is what the plugin drew before styling
+    existed.
+    """
+
+    def __init__(self, config: Any) -> None:
+        self._config = config
+
+    def style(self, element_key: str, classic_font: str = None,
+              classic_size: int = 8, classic_color: Any = None,
+              mode: Optional[str] = None) -> Any:
+        from types import SimpleNamespace
+        return SimpleNamespace(
+            font=None, color=classic_color or (255, 255, 255), offset=(0, 0),
+            font_name=classic_font, font_size=classic_size,
+            user_forced=False, user_forced_color=False,
+            visible=True, align=None, scale=1.0)
+
+    def offset(self, element_key: str, mode: Optional[str] = None) -> tuple:
+        return (0, 0)
+
+    def offset_value(self, element_key: str, axis: str, default: int = 0,
+                     mode: Optional[str] = None) -> int:
+        return default
+
 
 def _fallback_font_manager() -> Any:
     """Shared FontManager for environments (unit tests, mocks) where the
@@ -63,6 +99,12 @@ class BasePlugin(ABC):
 
     API_VERSION = "1.0.0"
 
+    #: Which ``customization.modes.<mode>`` overrides :attr:`styles` applies.
+    #: A plugin with one instance per display mode (the scoreboards' live /
+    #: upcoming / recent classes) sets this and every existing style lookup
+    #: becomes mode-aware without changing a call site.
+    STYLE_MODE: Optional[str] = None
+
     def __init__(
         self,
         plugin_id: str,
@@ -260,6 +302,128 @@ class BasePlugin(ABC):
         self._layout_font_generation = generation
         return context
 
+    @property
+    def styles(self) -> Any:
+        """
+        The user's per-element styling: fonts, sizes, colours, offsets,
+        visibility, alignment and scale, resolved against this plugin's own
+        config_schema.json.
+
+        Every consumer of src.element_style used to repeat the same three
+        things -- a guarded import, finding its own schema file, and
+        rebuilding the resolver when on_config_change swapped the config
+        dict. This is those three things, once.
+
+        Ask for a style by element name, passing what the plugin drew before
+        the user could customise anything::
+
+            title = self.styles.style('title_text',
+                                      classic_font='PressStart2P-Regular.ttf',
+                                      classic_size=8,
+                                      classic_color=(255, 255, 255))
+            x, y = title.offset
+            self.display_manager.draw_text(text, x=x, y=y,
+                                           font=title.font, color=title.color)
+
+        The classic_* arguments matter: when the user has chosen nothing,
+        they come back verbatim, so a plugin that adopts this renders
+        identically until someone actually changes a setting.
+
+        A plugin whose display has modes (a scoreboard's live/upcoming/
+        recent, weather's current/hourly/daily) sets ``STYLE_MODE`` on the
+        class, and every lookup here honours the matching
+        ``customization.modes.<mode>`` overrides without any call site
+        passing a mode. Use :meth:`styles_for` for a one-off mode.
+
+        Never raises: with no schema on disk, or with the element-style
+        module unavailable, lookups fall back to the classic values.
+        """
+        resolver = getattr(self, "_style_resolver", None)
+        # The config dict is swapped wholesale by on_config_change, so
+        # identity is the invalidation signal -- the same check the sports
+        # base classes use.
+        if resolver is not None and resolver._config is self.config:
+            return resolver
+        resolver = self._build_style_resolver(getattr(self, "STYLE_MODE", None))
+        self._style_resolver = resolver
+        return resolver
+
+    def styles_for(self, mode: Optional[str]) -> Any:
+        """:attr:`styles`, bound to ``mode`` instead of ``STYLE_MODE``.
+
+        For a plugin that renders more than one mode from one instance. A
+        plugin with an instance per mode should set ``STYLE_MODE`` instead
+        and leave its call sites alone.
+        """
+        cache = getattr(self, "_style_resolvers_by_mode", None)
+        if cache is None or getattr(self, "_style_resolver_config", None) is not self.config:
+            cache = {}
+            self._style_resolvers_by_mode = cache
+            self._style_resolver_config = self.config
+        if mode not in cache:
+            cache[mode] = self._build_style_resolver(mode)
+        return cache[mode]
+
+    def _build_style_resolver(self, mode: Optional[str]) -> Any:
+        """Construct a resolver for this plugin's config and schema."""
+        try:
+            from src.element_style import (ElementStyleResolver,
+                                           defaults_from_schema_file)
+        except ImportError:  # pragma: no cover - core always ships it
+            return _NullStyleResolver(self.config)
+
+        schema_path = self._config_schema_path()
+        defaults = (defaults_from_schema_file(schema_path) if schema_path
+                    else {})
+        return ElementStyleResolver(self.config, defaults, mode=mode)
+
+    def _config_schema_path(self) -> Optional[str]:
+        """This plugin's config_schema.json, or None.
+
+        Looked up from the concrete class's own module rather than from this
+        file: a plugin's subclass lives in its plugin directory, while this
+        module lives in src/plugin_system, where no plugin schema exists.
+        Falls back to the configured plugins directory, including the
+        ledmatrix- prefix form the loader accepts.
+
+        Returning None is safe, not fatal -- the resolver then has no
+        defaults to compare against, so every configured value counts as a
+        deliberate override, which is the conservative reading.
+        """
+        cached = getattr(self, "_config_schema_path_cache", _UNSET_SCHEMA_PATH)
+        if cached is not _UNSET_SCHEMA_PATH:
+            return cached
+
+        path = None
+        try:
+            for candidate in self._schema_path_candidates():
+                if candidate and os.path.isfile(candidate):
+                    path = candidate
+                    break
+        except Exception as exc:  # pragma: no cover - defensive
+            self.logger.debug("Could not locate config_schema.json: %s", exc)
+        self._config_schema_path_cache = path
+        return path
+
+    def _schema_path_candidates(self) -> list:
+        """Where a plugin's schema might be, best guess first."""
+        candidates = []
+
+        module = sys.modules.get(type(self).__module__)
+        module_file = getattr(module, "__file__", None)
+        if module_file:
+            candidates.append(os.path.join(
+                os.path.dirname(os.path.abspath(module_file)),
+                "config_schema.json"))
+
+        plugins_dir = getattr(self.plugin_manager, "plugins_dir", None)
+        if plugins_dir:
+            for plugin_id in (self.plugin_id, f"ledmatrix-{self.plugin_id}"):
+                candidates.append(os.path.join(
+                    str(plugins_dir), os.path.basename(plugin_id),
+                    "config_schema.json"))
+        return candidates
+
     def draw_fit(self, text: str, box: Any,
                  color: tuple = (255, 255, 255),
                  ladder: Optional[Any] = None,
@@ -520,6 +684,38 @@ class BasePlugin(ABC):
         """
         return
 
+    def get_update_interval(self) -> Optional[float]:
+        """
+        How often this plugin wants update() called, right now, in seconds.
+
+        The manifest's ``update_interval`` is a single static number, which
+        cannot say "poll me every 15 seconds while a game is in progress and
+        every 15 minutes when nothing is on". Only the plugin knows which is
+        true at any moment, so override this to say so.
+
+        Return None (the default) to accept the manifest/config value.
+
+        Two constraints, both because the scheduler calls this on every tick of
+        the render loop:
+
+        - It must be cheap. Attribute reads only -- no config lookups, no I/O,
+          no locks that a fetch might be holding.
+        - It must not raise. A raising hook is ignored and the static interval
+          used, but a hook that raises every tick also logs every tick.
+
+        Values below PluginManager.MIN_DYNAMIC_UPDATE_INTERVAL are clamped up:
+        a plugin asking for 0 would otherwise busy-wait against its own API.
+
+        Example::
+
+            def get_update_interval(self):
+                # Fast while something is actually live, manifest default otherwise.
+                if any(m.live_games for m in self._live_managers):
+                    return self.config.get("live_update_interval", 15)
+                return None
+        """
+        return None
+
     def has_live_priority(self) -> bool:
         """
         Check if this plugin has live priority enabled.

src/plugin_system/plugin_executor.py

@@ -76,6 +76,13 @@ class PluginExecutor:
         thread.start()
         thread.join(timeout=timeout)
         
+        # NB: this timeout is advisory. Nothing cancels the thread -- Python
+        # has no way to -- so on expiry the operation keeps running to
+        # completion in the background and only this caller gives up waiting.
+        # A plugin that hangs permanently leaks one daemon thread per attempt.
+        # Callers that hold a resource across the call must release it from
+        # inside the wrapped callable rather than after this returns; see the
+        # _release_display_lock guard inside DisplayController.run().
         if not result_container['completed']:
             error_msg = f"{plugin_context} operation timed out after {timeout}s"
             self.logger.error(error_msg)
@@ -148,7 +155,8 @@ class PluginExecutor:
         plugin_id: str,
         force_clear: bool = False,
         display_mode: Optional[str] = None,
-        timeout: Optional[float] = None
+        timeout: Optional[float] = None,
+        accepts_display_mode: Optional[bool] = None
     ) -> bool:
         """
         Execute plugin display() method with error handling.
@@ -159,6 +167,9 @@ class PluginExecutor:
             force_clear: Whether to force clear display
             display_mode: Optional display mode parameter
             timeout: Timeout in seconds (None = use default)
+            accepts_display_mode: Whether plugin.display() takes a
+                display_mode keyword. Pass it when the caller already knows;
+                None falls back to inspecting the callable.
             
         Returns:
             True if display succeeded, False otherwise
@@ -166,10 +177,20 @@ class PluginExecutor:
         try:
             start_time = time.time()
             
-            # Check if plugin accepts display_mode parameter
-            import inspect
-            sig = inspect.signature(plugin.display)
-            has_display_mode = 'display_mode' in sig.parameters
+            # Does display() take a display_mode keyword? The caller usually
+            # knows and caches the answer, so prefer what it passed.
+            #
+            # Inspecting here was not merely redundant, it could never be
+            # cached: display_controller wraps the real plugin in a fresh
+            # SimpleNamespace per call, so inspect.signature() saw a new
+            # callable every time and paid ~55us on a Pi 4 to re-derive a
+            # value the caller had computed one line earlier and stored in
+            # self._plugin_accepts_display_mode.
+            if accepts_display_mode is None:
+                import inspect
+                accepts_display_mode = (
+                    'display_mode' in inspect.signature(plugin.display).parameters)
+            has_display_mode = accepts_display_mode
             
             # Capture the return value from the plugin's display() method
             if has_display_mode and display_mode:

src/plugin_system/plugin_manager.py

@@ -8,6 +8,7 @@ API Version: 1.0.0
 """
 
 import json
+import math
 import queue
 import sys
 import time
@@ -779,15 +780,68 @@ class PluginManager:
 
         return None
 
+    def _dynamic_update_interval(self, plugin_id: str, plugin_instance: Any) -> Optional[float]:
+        """The interval a plugin asks for right now, or None if it has no view."""
+        hook = getattr(plugin_instance, 'get_update_interval', None)
+        if not callable(hook):
+            return None
+        try:
+            requested = hook()
+        except Exception as exc:  # pylint: disable=broad-except
+            self.logger.debug(
+                "get_update_interval() failed for %s, using the static interval: %s",
+                plugin_id, exc)
+            return None
+        if requested is None:
+            return None
+        if isinstance(requested, bool):
+            self.logger.debug(
+                "get_update_interval() returned a bool for %s, which is not a number",
+                plugin_id)
+            return None
+        try:
+            requested = float(requested)
+        except (TypeError, ValueError):
+            self.logger.debug(
+                "get_update_interval() returned %r for %s, which is not a number",
+                requested, plugin_id)
+            return None
+        if not math.isfinite(requested):  # NaN / +inf / -inf
+            return None
+        return max(requested, self.MIN_DYNAMIC_UPDATE_INTERVAL)
+
+    #: Floor for a plugin-requested interval. A plugin asking for 0 (or a
+    #: negative) would otherwise be re-entered on every tick of the render
+    #: loop, which is a busy-wait against whatever API it fetches.
+    MIN_DYNAMIC_UPDATE_INTERVAL = 5.0
+
     def _get_plugin_update_interval(self, plugin_id: str, plugin_instance: Any) -> Optional[float]:
         """
         Get the data-fetch interval for a plugin (seconds between update() calls).
 
-        Result is cached per plugin_id after the first lookup to avoid calling
-        config_manager.get_config() — which returns a full dict copy — on every
-        tick of the 30-fps display loop.  The cache is invalidated when a plugin
-        is loaded or unloaded.
+        A plugin may implement ``get_update_interval()`` to vary its own cadence
+        at runtime, which the static manifest value cannot express. The case
+        this exists for: a sports scoreboard needs to poll every 15s while a
+        game is in progress and every 15 minutes when nothing is on, and only
+        the plugin knows which is true right now. Returning None from the hook
+        means "no opinion", and the static resolution below applies.
+
+        The hook is called on every scheduling tick, so implementations must be
+        cheap — attribute reads, no config lookups and no I/O. A raising or
+        non-numeric hook is ignored rather than allowed to stop the plugin
+        updating, since a scheduler that propagates a plugin bug stops every
+        other plugin too.
+
+        The static result is cached per plugin_id after the first lookup to
+        avoid calling config_manager.get_config() — which returns a full dict
+        copy — on every tick of the 30-fps display loop. The cache is
+        invalidated when a plugin is loaded or unloaded. The dynamic hook is
+        deliberately *not* cached: caching it would defeat its only purpose.
         """
+        dynamic = self._dynamic_update_interval(plugin_id, plugin_instance)
+        if dynamic is not None:
+            return dynamic
+
         if plugin_id in self._update_interval_cache:
             return self._update_interval_cache[plugin_id]
 

src/plugin_system/state_reconciliation.py

@@ -8,6 +8,7 @@ Detects and fixes inconsistencies between:
 - State manager state
 """
 
+import json
 from typing import Dict, Any, List, Set
 from dataclasses import dataclass
 from enum import Enum
@@ -55,6 +56,100 @@ class ReconciliationResult:
     message: str
 
 
+def secrets_top_level_keys(config_manager) -> Set[str]:
+    """Top-level keys load_config() merges in from the secrets file.
+
+    Deliberately fail-safe: an unreadable, absent, malformed or non-path
+    secrets location narrows this set rather than raising, because a failure
+    here must never break reconciliation.
+    """
+    try:
+        path = config_manager.get_secrets_path()
+        with open(path, 'r') as f:
+            secrets = json.load(f)
+    except (AttributeError, OSError, TypeError, ValueError):
+        return set()
+    return set(secrets) if isinstance(secrets, dict) else set()
+
+
+def ignored_config_keys(config_manager) -> Set[str]:
+    """Config keys that are not plugin ids: system keys plus secrets keys."""
+    return set(StateReconciliation._SYSTEM_CONFIG_KEYS) | secrets_top_level_keys(config_manager)
+
+
+def config_plugin_ids(config: Dict[str, Any], ignored_keys: Set[str]) -> Set[str]:
+    """Plugin ids a loaded config declares.
+
+    Shared with the web interface so a stored verdict is re-checked against the
+    same definition that produced it. ``set(config)`` is NOT equivalent: it also
+    contains system keys, the secrets-file keys load_config() merges in, and
+    non-dict values. Counting any of those as a plugin is exactly what turned a
+    'data' key in the secrets file into a phantom plugin, and using the loose
+    set to re-check findings would clear ones that are still true.
+    """
+    return {k for k, v in (config or {}).items()
+            if isinstance(v, dict) and k not in ignored_keys}
+
+
+def disk_plugin_ids(plugins_dir) -> Set[str]:
+    """Plugin ids actually installed on disk.
+
+    A directory counts only when it is not a standalone backup and its
+    manifest.json parses. A corrupt manifest must not read as installed, or a
+    live "in config but not on disk" finding gets cleared on the strength of an
+    unreadable file.
+    """
+    ids: Set[str] = set()
+    root = Path(plugins_dir)
+    try:
+        if not root.exists():
+            return ids
+        for entry in root.iterdir():
+            if not entry.is_dir() or '.standalone-backup-' in entry.name:
+                continue
+            manifest = entry / "manifest.json"
+            if not manifest.exists():
+                continue
+            try:
+                with open(manifest, 'r') as f:
+                    json.load(f)
+            except (OSError, ValueError):
+                continue
+            ids.add(entry.name)
+    except OSError:
+        return ids
+    return ids
+
+
+def still_unresolved(entries: List[Dict[str, Any]],
+                     config_keys: Set[str],
+                     installed_ids: Set[str]) -> List[Dict[str, Any]]:
+    """Drop stored reconciliation findings that are no longer true.
+
+    The verdict is written once to a status file and served to the web UI from
+    there, and a run that fails to apply a fix also declares it "will not retry
+    automatically". Together those froze a single moment forever: a device whose
+    plugins were all present in config kept being told, for hours, that four of
+    them were missing and should be removed from config.json.
+
+    Entry kinds this cannot re-check are kept, so filtering only ever removes
+    findings that are provably stale.
+    """
+    live: List[Dict[str, Any]] = []
+    for entry in entries:
+        kind = entry.get('type')
+        plugin_id = entry.get('plugin_id')
+        if kind == InconsistencyType.PLUGIN_MISSING_IN_CONFIG.value:
+            if plugin_id not in config_keys:
+                live.append(entry)
+        elif kind == InconsistencyType.PLUGIN_MISSING_ON_DISK.value:
+            if plugin_id not in installed_ids:
+                live.append(entry)
+        else:
+            live.append(entry)
+    return live
+
+
 class StateReconciliation:
     """
     State reconciliation system.
@@ -200,16 +295,26 @@ class StateReconciliation:
         'github', 'youtube',
     })
 
+    def _secrets_top_level_keys(self) -> Set[str]:
+        """Top-level keys that load_config() merges in from the secrets file.
+
+        load_config() merges config_secrets.json into the config it returns, so
+        those keys sit alongside plugin ids. _SYSTEM_CONFIG_KEYS named them
+        individually ('github', 'youtube'), which broke the moment anything else
+        was written there: a 'data' key became a phantom plugin, permanently
+        reported as "in config but not on disk". Reading the file keeps this
+        correct no matter what it holds.
+        """
+        return secrets_top_level_keys(self.config_manager)
+
     def _get_config_state(self) -> Dict[str, Dict[str, Any]]:
         """Get plugin state from config file."""
         state = {}
         try:
             config = self.config_manager.load_config()
-            for plugin_id, plugin_config in config.items():
-                if not isinstance(plugin_config, dict):
-                    continue
-                if plugin_id in self._SYSTEM_CONFIG_KEYS:
-                    continue
+            ignored = self._SYSTEM_CONFIG_KEYS | self._secrets_top_level_keys()
+            for plugin_id in config_plugin_ids(config, ignored):
+                plugin_config = config[plugin_id]
                 state[plugin_id] = {
                     'enabled': plugin_config.get('enabled', True),
                     'version': plugin_config.get('version'),
@@ -223,25 +328,21 @@ class StateReconciliation:
         """Get plugin state from disk (installed plugins)."""
         state = {}
         try:
-            if self.plugins_dir.exists():
-                for plugin_dir in self.plugins_dir.iterdir():
-                    if plugin_dir.is_dir():
-                        plugin_id = plugin_dir.name
-                        if '.standalone-backup-' in plugin_id:
-                            continue
-                        manifest_path = plugin_dir / "manifest.json"
-                        if manifest_path.exists():
-                            import json
-                            try:
-                                with open(manifest_path, 'r') as f:
-                                    manifest = json.load(f)
-                                state[plugin_id] = {
-                                    'exists_on_disk': True,
-                                    'version': manifest.get('version'),
-                                    'name': manifest.get('name')
-                                }
-                            except Exception:  # nosec B110 - corrupt/unreadable manifest; skip this plugin, outer except logs
-                                pass
+            # Membership comes from the shared extractor so the web interface
+            # re-checks stored findings against this same definition; the
+            # manifest is then re-read here only for version/name.
+            for plugin_id in disk_plugin_ids(self.plugins_dir):
+                manifest_path = self.plugins_dir / plugin_id / "manifest.json"
+                try:
+                    with open(manifest_path, 'r') as f:
+                        manifest = json.load(f)
+                except (OSError, ValueError):  # nosec B112 - raced or corrupt; skip
+                    continue
+                state[plugin_id] = {
+                    'exists_on_disk': True,
+                    'version': manifest.get('version'),
+                    'name': manifest.get('name')
+                }
         except Exception as e:
             self.logger.warning(f"Error reading disk state: {e}")
         return state
@@ -367,8 +468,18 @@ class StateReconciliation:
         """Attempt to fix an inconsistency."""
         try:
             if inconsistency.inconsistency_type == InconsistencyType.PLUGIN_MISSING_IN_CONFIG:
-                # Add plugin to config with default disabled state
                 config = self.config_manager.load_config()
+                if inconsistency.plugin_id in config:
+                    # Detection said "not in config" but it is there -- the
+                    # config changed under us, or the id came from a key merged
+                    # in from elsewhere. Assigning the stub below would replace
+                    # the real entry: one reported case would have traded 4.9KB
+                    # of league settings for {'enabled': False}. Nothing to fix.
+                    self.logger.info(
+                        "Skipped: %s is already in config; not overwriting it",
+                        inconsistency.plugin_id)
+                    return True
+                # Add plugin to config with default disabled state
                 config[inconsistency.plugin_id] = {
                     'enabled': False
                 }

src/plugin_system/store_manager.py

@@ -1338,9 +1338,16 @@ class PluginStoreManager:
             self.logger.error(f"Plugin not found in registry: {plugin_id}")
             return False
 
-        # Visual skins share the registry but install to skins/, not to a
-        # plugin directory (docs/SKIN_SYSTEM.md)
+        # Visual skins share the registry. _install_skin_from_info can put one
+        # in skins/, but no current scoreboard plugin renders skins, so the
+        # store refuses them rather than installing something that does
+        # nothing (docs/SKIN_SYSTEM.md). Manual installs under skins/ and
+        # uninstall_skin are unaffected.
         if (plugin_info.get('type') or 'plugin') == 'skin':
+            from src.skin_system import SKINS_RENDER_SUPPORTED, SKINS_UNSUPPORTED_MESSAGE
+            if not SKINS_RENDER_SUPPORTED:
+                self.logger.error(f"Not installing skin {plugin_id}: {SKINS_UNSUPPORTED_MESSAGE}")
+                return False
             return self._install_skin_from_info(plugin_id, plugin_info, branch)
 
         repo_url = plugin_info.get('repo')

src/plugin_system/testing/loading.py

@@ -25,11 +25,20 @@ def find_plugin_dir(plugin_id: str, search_dirs: Sequence[Union[str, Path]]) ->
 
 
 def load_manifest(plugin_dir: Union[str, Path]) -> Dict[str, Any]:
-    """Load and return manifest.json from a plugin directory."""
+    """Load and return manifest.json from a plugin directory.
+
+    Read as UTF-8 explicitly, not in the platform default encoding: JSON is
+    UTF-8 by RFC 8259, but `open()` honours the locale, which is cp1252 on
+    Windows. A manifest carrying any non-ASCII byte (an em dash in a
+    description, a degree sign in a mode name) therefore raised
+    UnicodeDecodeError and aborted the whole `check_plugin.py --all` run on the
+    byte rather than failing just that plugin. The three sibling loaders below
+    read JSON from the same plugin trees and had the same bug.
+    """
     manifest_path = Path(plugin_dir) / 'manifest.json'
     if not manifest_path.exists():
         raise FileNotFoundError(f"No manifest.json in {plugin_dir}")
-    with open(manifest_path, 'r') as f:
+    with open(manifest_path, 'r', encoding='utf-8') as f:
         return json.load(f)
 
 
@@ -77,7 +86,7 @@ def load_config_defaults(plugin_dir: Union[str, Path]) -> Dict[str, Any]:
     schema_path = Path(plugin_dir) / 'config_schema.json'
     if not schema_path.exists():
         return {}
-    with open(schema_path, 'r') as f:
+    with open(schema_path, 'r', encoding='utf-8') as f:
         schema = json.load(f)
     return _defaults_from_properties(schema.get('properties', {}))
 
@@ -106,7 +115,7 @@ def load_harness_spec(plugin_dir: Union[str, Path]) -> Dict[str, Any]:
     spec_path = Path(plugin_dir) / 'test' / 'harness.json'
     if not spec_path.exists():
         return {}
-    with open(spec_path, 'r') as f:
+    with open(spec_path, 'r', encoding='utf-8') as f:
         spec = json.load(f)
 
     # Resolve mock_data path and inline its contents for convenience.
@@ -120,7 +129,7 @@ def load_harness_spec(plugin_dir: Union[str, Path]) -> Dict[str, Any]:
                 f"harness.json references mock_data '{mock_rel}' but "
                 f"{mock_path} does not exist"
             )
-        with open(mock_path, 'r') as mf:
+        with open(mock_path, 'r', encoding='utf-8') as mf:
             spec['mock_data_contents'] = json.load(mf)
     return spec
 

src/plugin_system/testing/visual_display_manager.py

@@ -31,7 +31,7 @@ from pathlib import Path
 from typing import Any, List, Optional, Tuple
 
 from PIL import Image, ImageDraw, ImageFont
-from src.common.font_layout import load_truetype
+from src.common.font_layout import crisp_size, load_truetype
 
 from src.logging_config import get_logger
 
@@ -141,9 +141,10 @@ class VisualTestDisplayManager:
             fonts_dir = project_root / 'assets' / 'fonts'
 
             # Press Start 2P — regular and small (both 8px)
-            ttf_path = str(fonts_dir / 'PressStart2P-Regular.ttf')
-            self.regular_font = load_truetype(ttf_path, 8)
-            self.small_font = load_truetype(ttf_path, 8)
+            press_start = 'PressStart2P-Regular.ttf'
+            ttf_path = str(fonts_dir / press_start)
+            self.regular_font = load_truetype(ttf_path, crisp_size(press_start, 8))
+            self.small_font = load_truetype(ttf_path, crisp_size(press_start, 8))
             self.font = self.regular_font  # alias used by some code paths
 
             # 5x7 BDF font via freetype
@@ -160,10 +161,15 @@ class VisualTestDisplayManager:
                 self.calendar_font = self.small_font
                 self.bdf_5x7_font = self.small_font
 
-            # 4x6 extra small TTF
+            # 4x6 extra small TTF, snapped to the face's 7px grid exactly as
+            # DisplayManager._load_fonts does. Sizing this independently is how
+            # the harness would render -- and bless goldens -- in a face the
+            # panel never uses: at the off-grid 6 this asked for, every glyph
+            # loses its fourth column under `draw.fontmode = "1"`.
             try:
-                xs_path = str(fonts_dir / '4x6-font.ttf')
-                self.extra_small_font = load_truetype(xs_path, 6)
+                four_by_six = '4x6-font.ttf'
+                xs_path = str(fonts_dir / four_by_six)
+                self.extra_small_font = load_truetype(xs_path, crisp_size(four_by_six, 6))
             except (FileNotFoundError, OSError) as e:
                 logger.debug("Extra small font not available, using fallback: %s", e)
                 self.extra_small_font = self.small_font

src/skin_system/__init__.py

@@ -6,7 +6,19 @@ upcoming) while the host plugin keeps doing data fetching, scheduling,
 caching, live priority, and vegas mode. See docs/SKIN_SYSTEM.md.
 """
 
-from src.skin_system.skin_base import (
+# Skins are not offered to users yet. The only render hook is
+# SportsCore._render_game in src/base_classes/sports/core.py, and none of the
+# current scoreboard plugins (monorepo or third-party) build on
+# src.base_classes, so a selected skin never draws. The web UI and store
+# read these instead of offering install/selection; stored "skin" config
+# values still load and save. See docs/SKIN_SYSTEM.md.
+SKINS_RENDER_SUPPORTED = False
+SKINS_UNSUPPORTED_MESSAGE = (
+    "Skins aren't supported yet: the current scoreboard plugins don't render "
+    "them. Installed skins and saved skin settings are kept but have no effect."
+)
+
+from src.skin_system.skin_base import (  # noqa: E402
     SKIN_API_VERSION,
     VIEW_MODEL_VERSION,
     ScoreboardSkin,

src/startup_validator.py

@@ -81,6 +81,8 @@ class StartupValidator:
     _UNITS = (
         ("systemd/ledmatrix.service", "/etc/systemd/system/ledmatrix.service"),
         ("systemd/ledmatrix-web.service", "/etc/systemd/system/ledmatrix-web.service"),
+        ("systemd/ledmatrix-update-verify.service", "/etc/systemd/system/ledmatrix-update-verify.service"),
+        ("systemd/ledmatrix-update-verify.path", "/etc/systemd/system/ledmatrix-update-verify.path"),
     )
 
     def _validate_systemd_units(self) -> None:
@@ -111,17 +113,25 @@ class StartupValidator:
                 if not template.is_file() or not installed.is_file():
                     continue
 
-                # The template carries placeholders the installer substitutes,
-                # so compare the substituted form rather than the raw file.
-                expected = template.read_text(encoding="utf-8")
-                expected = expected.replace("__PROJECT_ROOT_DIR__", str(project_root))
-                expected = expected.replace("__USER__", "root")
-
                 try:
                     actual = installed.read_text(encoding="utf-8")
                 except PermissionError:
                     continue
 
+                # The template carries placeholders the installer substitutes,
+                # so compare the substituted form rather than the raw file.
+                expected = template.read_text(encoding="utf-8")
+                expected = expected.replace("__PROJECT_ROOT_DIR__", str(project_root))
+                # User= is an install-time decision, not something the template
+                # dictates: the installers write whoever ran them, which on a
+                # non-root install is never "root". Substituting a fixed "root"
+                # here reported drift on every such install, permanently -- and
+                # re-running the installer, which is what the warning tells you
+                # to do, could not clear it. Taking the installed unit's own
+                # value keeps the comparison on the directives the template
+                # actually controls.
+                expected = expected.replace("__USER__", self._installed_user(actual))
+
                 if self._unit_body(expected) != self._unit_body(actual):
                     self.warnings.append(
                         f"{installed.name} differs from {template_rel}; the "
@@ -132,6 +142,19 @@ class StartupValidator:
         except OSError as e:
             self.logger.debug("Could not compare systemd units: %s", e)
 
+    @staticmethod
+    def _installed_user(unit_text: str) -> str:
+        """The installed unit's ``User=``, or "root" when it does not set one.
+
+        systemd itself defaults to root for a system unit with no User=, so that
+        is the right fallback rather than an empty string.
+        """
+        for line in unit_text.splitlines():
+            stripped = line.strip()
+            if stripped.startswith("User="):
+                return stripped.split("=", 1)[1].strip()
+        return "root"
+
     @staticmethod
     def _unit_body(text: str) -> str:
         """A unit's meaningful lines, in order: no comments, no blanks.

src/web_interface/api_helpers.py

@@ -105,27 +105,3 @@ def validate_request_json(required_fields: list, data: Optional[Dict] = None) ->
         )
     
     return data, None
-
-
-def validate_request_params(required_params: list) -> Tuple[Optional[Dict], Optional[Any]]:
-    """
-    Validate request has required query parameters.
-    
-    Args:
-        required_params: List of required parameter names
-    
-    Returns:
-        Tuple of (params_dict, error_response) or (params_dict, None) if valid
-    """
-    missing_params = [param for param in required_params if param not in request.args]
-    if missing_params:
-        return None, error_response(
-            ErrorCode.INVALID_INPUT,
-            f"Missing required parameters: {', '.join(missing_params)}",
-            context={'missing_params': missing_params},
-            status_code=400
-        )
-    
-    params = {param: request.args.get(param) for param in required_params}
-    return params, None
-

src/wifi_manager.py

@@ -36,7 +36,7 @@ import os
 import time
 import re
 from pathlib import Path
-from typing import Dict, List, Optional, Tuple
+from typing import Any, Dict, List, Optional, Tuple
 from dataclasses import dataclass
 
 logger = logging.getLogger(__name__)
@@ -714,9 +714,24 @@ class WiFiManager:
     _IP_FORWARD_SAVE_PATH = Path("/tmp/ledmatrix_ip_forward_saved")  # nosec B108 - process-specific named file; device is single-user RPi
     # Written when AP mode is manually force-enabled; prevents daemon auto-disable
     _FORCE_AP_FLAG_PATH = Path("/tmp/ledmatrix_force_ap_active")  # nosec B108 - process-specific named file; device is single-user RPi
+    # Written by the web process while connect_to_network runs. Joining a network
+    # from the setup AP takes the AP down first, and the monitor daemon (a separate
+    # process) would otherwise see "disconnected" on its next tick and bring the
+    # AP straight back up mid-connect.
+    _CONNECT_IN_PROGRESS_FLAG_PATH = Path("/tmp/ledmatrix_wifi_connect_in_progress")  # nosec B108 - process-specific named file; device is single-user RPi
+    # Longest a connect can legitimately take (AP teardown, nmcli's 30s timeout,
+    # verification, restore). An older flag was left by a process that died.
+    _CONNECT_FLAG_MAX_AGE_SECONDS = 180
     # Ensures the startup stale-flag cleanup runs once per process, not per instantiation
     _startup_cleanup_done: bool = False
 
+    def _connect_in_progress(self) -> bool:
+        try:
+            age = time.time() - self._CONNECT_IN_PROGRESS_FLAG_PATH.stat().st_mtime
+        except OSError:
+            return False
+        return age < self._CONNECT_FLAG_MAX_AGE_SECONDS
+
     def _validate_ap_config(self) -> Tuple[str, int]:
         """Return a sanitized (ssid, channel) pair from config, falling back to defaults."""
         ssid = str(self.config.get("ap_ssid", DEFAULT_AP_SSID))
@@ -1248,14 +1263,43 @@ class WiFiManager:
     def connect_to_network(self, ssid: str, password: str) -> Tuple[bool, str]:
         """
         Connect to a WiFi network with failsafe to restore original connection on failure.
-        
+
         Args:
             ssid: Network SSID
             password: Network password (empty for open networks)
-            
+
         Returns:
             Tuple of (success, message)
         """
+        # Both values arrive verbatim from POST /api/v3/wifi/connect and end up
+        # as nmcli argv entries. There is no shell here, so no metacharacter
+        # can start a second command -- but nmcli reads a leading "-" as an
+        # option, so an SSID of "--ask" or "-t" is a request to run nmcli
+        # differently rather than to join a network. See _validate_ssid.
+        ssid, error = self._validate_ssid(ssid)
+        if error:
+            logger.warning("Rejected WiFi connect request: %s", error)
+            return False, error
+        password, error = self._validate_wifi_password(password)
+        if error:
+            logger.warning("Rejected WiFi connect request: %s", error)
+            return False, error
+
+        try:
+            self._CONNECT_IN_PROGRESS_FLAG_PATH.touch()
+        except OSError as e:
+            logger.warning(f"Could not create connect-in-progress flag: {e}")
+        try:
+            return self._connect_validated(ssid, password)
+        finally:
+            try:
+                self._CONNECT_IN_PROGRESS_FLAG_PATH.unlink(missing_ok=True)
+            except OSError as e:
+                # Never mask the connect result; the age limit retires the flag.
+                logger.warning(f"Could not remove connect-in-progress flag: {e}")
+
+    def _connect_validated(self, ssid: str, password: str) -> Tuple[bool, str]:
+        """connect_to_network after validation, with the in-progress flag held."""
         # Save current connection info for failsafe restoration
         original_connection = None
         original_ssid = None
@@ -1635,6 +1679,66 @@ class WiFiManager:
             self._show_led_message("Connection error", duration=5)
             return False, str(e)
 
+    # 802.11 caps an SSID at 32 octets. Control characters cannot appear in a
+    # real one, and a leading "-" would be read by nmcli as an option rather
+    # than a network name.
+    _SSID_MAX_OCTETS = 32
+    # WPA-PSK passphrases are 8-63 printable ASCII characters, or a 64-char hex
+    # key. Anything outside that cannot authenticate, so refusing it early
+    # costs nothing and keeps argv clean.
+    _PSK_MIN_LEN = 8
+    _PSK_MAX_LEN = 63
+
+    @classmethod
+    def _validate_ssid(cls, ssid: Any) -> Tuple[str, Optional[str]]:
+        """Return (ssid, None) for a usable SSID, or ('', reason) to refuse it.
+
+        Returns the value rather than a boolean so callers pass on what was
+        checked instead of re-reading the original.
+        """
+        if not isinstance(ssid, str):
+            return '', "SSID must be text"
+        ssid = ssid.strip()
+        if not ssid:
+            return '', "SSID cannot be empty"
+        if len(ssid.encode('utf-8')) > cls._SSID_MAX_OCTETS:
+            return '', f"SSID is longer than {cls._SSID_MAX_OCTETS} bytes"
+        if any(ord(ch) < 0x20 or ord(ch) == 0x7F for ch in ssid):
+            return '', "SSID contains control characters"
+        if ssid.startswith('-'):
+            # nmcli would take this for an option, not a network name.
+            return '', "SSID cannot start with '-'"
+        return ssid, None
+
+    @classmethod
+    def _validate_wifi_password(cls, password: Any) -> Tuple[str, Optional[str]]:
+        """Return (password, None) for a usable passphrase, or ('', reason).
+
+        An empty password means an open network and is allowed through.
+        """
+        if password is None:
+            return '', None
+        if not isinstance(password, str):
+            return '', "Password must be text"
+        if password == '':
+            return '', None
+        if any(ord(ch) < 0x20 or ord(ch) == 0x7F for ch in password):
+            return '', "Password contains control characters"
+        if not password.isascii():
+            # WPA-PSK passphrases are printable ASCII only; NetworkManager
+            # rejects anything else.
+            return '', "Password must be ASCII"
+        if password.startswith('-'):
+            # Same reason as the SSID: nmcli would read it as an option.
+            return '', "Password cannot start with '-'"
+        is_hex_key = len(password) == 64 and all(c in '0123456789abcdefABCDEF' for c in password)
+        if not is_hex_key and not (cls._PSK_MIN_LEN <= len(password) <= cls._PSK_MAX_LEN):
+            return '', (
+                f"Password must be {cls._PSK_MIN_LEN}-{cls._PSK_MAX_LEN} characters "
+                f"(or a 64-character hex key)"
+            )
+        return password, None
+
     @staticmethod
     def _is_wrong_password_error(error_msg: str) -> bool:
         """Return True when nmcli's error output indicates an authentication failure."""
@@ -2616,7 +2720,15 @@ address=/detectportal.firefox.com/192.168.4.1
                 if self._disconnected_checks > 0:
                     logger.debug("Network connected, resetting disconnected check counter")
                 self._disconnected_checks = 0
-            
+
+            if self._connect_in_progress():
+                # A connect has just taken the AP down on purpose. Leave the
+                # radio alone, and restart the grace period so a failed attempt
+                # (which re-enables the AP itself) isn't followed by a flap.
+                logger.debug("WiFi connect in progress; skipping AP management this check")
+                self._disconnected_checks = 0
+                return False
+
             # Only enable AP if we've had enough consecutive disconnected checks
             should_have_ap = (auto_enable and 
                             is_disconnected and 

systemd/README.md

@@ -14,6 +14,16 @@ This directory contains systemd service unit files for LEDMatrix services.
   - Starts automatically on boot if `web_display_autostart` is enabled
   - Uses `scripts/utils/start_web_conditionally.py`
 
+- **`ledmatrix-update-verify.service`** / **`.path`** - Automatic update health check and rollback
+  - The path unit starts the service when the web interface creates
+    `data/auto_update_verify.request` after a weekly automatic update
+  - Installed by the installers, or by the display service when automatic
+    updates are turned on in the web UI (`src/auto_update_setup.py`)
+  - Restarts the services, checks they stay up, and otherwise resets to the
+    previous commit and its dependencies
+  - Runs `data/auto_update_verifier.py`, a copy of
+    `scripts/utils/auto_update_verify.py` taken before the update
+
 - **`ledmatrix-wifi-monitor.service`** - WiFi monitor daemon service
   - Monitors WiFi/Ethernet connectivity
   - Automatically enables/disables access point mode
@@ -43,7 +53,8 @@ This directory contains systemd service unit files for LEDMatrix services.
 
 These service files are installed by the installation scripts in `scripts/install/`:
 - `install_service.sh` installs `ledmatrix.service`
-- `install_web_service.sh` installs `ledmatrix-web.service`
+- `install_web_service.sh` installs `ledmatrix-web.service` and the
+  `ledmatrix-update-verify` service and path units
 - `install_wifi_monitor.sh` installs `ledmatrix-wifi-monitor.service`
 - `install_dns_fix.sh` installs `ledmatrix-dns-fix.service` (opt-in, not run
   by the normal installer)

systemd/ledmatrix-update-verify.path

@@ -0,0 +1,20 @@
+# This is a template. Do not install it directly -- it is installed with
+# ledmatrix-update-verify.service by scripts/install/install_web_service.sh,
+# or by the display service when automatic updates are turned on
+# (src/auto_update_setup.py). Substitutes:
+#   __PROJECT_ROOT_DIR__  -> the directory the project is installed in
+#
+# Starts the automatic update health check when the web interface asks for it
+# by creating data/auto_update_verify.request. A path unit rather than a
+# sudoers rule: the web interface needs no extra privilege to trigger it, and
+# the service it starts runs as the web interface's own user.
+
+[Unit]
+Description=Watch for LED Matrix automatic update health check requests
+
+[Path]
+PathExists=__PROJECT_ROOT_DIR__/data/auto_update_verify.request
+Unit=ledmatrix-update-verify.service
+
+[Install]
+WantedBy=multi-user.target

systemd/ledmatrix-update-verify.service

@@ -0,0 +1,31 @@
+# This is a template. Do not install it directly -- run
+# scripts/install/install_web_service.sh (or install_service.sh); the display
+# service also installs it when automatic updates are turned on
+# (src/auto_update_setup.py). Substitutes:
+#   __PROJECT_ROOT_DIR__  -> the directory the project is installed in
+#   __USER__              -> the user the web interface runs as
+#
+# Health check and rollback for the web interface's weekly automatic update
+# (web_interface/auto_update.py). A separate unit because the check restarts
+# ledmatrix-web.service, which would kill it if it ran there.
+#
+# Never enabled itself: ledmatrix-update-verify.path starts it when the web
+# interface creates data/auto_update_verify.request. It runs as the web
+# interface's own user, and ExecStart points at the copy the updater makes
+# before pulling, so the update being checked cannot replace its checker.
+# Command-line paths are quoted so an install folder with spaces still works.
+
+[Unit]
+Description=LED Matrix automatic update health check and rollback
+
+[Service]
+Type=oneshot
+User=__USER__
+WorkingDirectory=__PROJECT_ROOT_DIR__
+# Consume the request first, so the path unit cannot start this again.
+ExecStartPre=/bin/rm -f "__PROJECT_ROOT_DIR__/data/auto_update_verify.request"
+ExecStart=/usr/bin/python3 "__PROJECT_ROOT_DIR__/data/auto_update_verifier.py" "__PROJECT_ROOT_DIR__"
+TimeoutStartSec=30min
+StandardOutput=syslog
+StandardError=syslog
+SyslogIdentifier=ledmatrix-update-verify

systemd/ledmatrix-web.service

@@ -1,9 +1,13 @@
-# This is a template file. The actual service file is generated dynamically
-# by install_web_service.sh with the correct paths based on where the project
-# is installed. Do not use this file directly - use install_web_service.sh instead.
+# This is a template. Do not install it directly -- run
+# scripts/install/install_web_service.sh (or install_service.sh, which
+# renders this same file). Both substitute:
+#   __PROJECT_ROOT_DIR__  -> the directory the project is installed in
+#   __USER__              -> the user the web interface runs as
 #
-# Template - paths will be replaced dynamically:
-# __PROJECT_ROOT_DIR__ will be replaced with the actual project directory
+# This file is the only description of the unit. It used to be duplicated as
+# an inline heredoc in both installers, which drifted apart; src/startup_validator.py
+# compares the installed unit against this template, so a second copy means a
+# permanent, unclearable drift warning on every boot.
 
 [Unit]
 Description=LED Matrix Web Interface Service
@@ -12,7 +16,7 @@ Wants=network-online.target
 
 [Service]
 Type=simple
-User=root
+User=__USER__
 WorkingDirectory=__PROJECT_ROOT_DIR__
 Environment=USE_THREADING=1
 ExecStart=/usr/bin/python3 __PROJECT_ROOT_DIR__/scripts/utils/start_web_conditionally.py

test/conftest.py

@@ -7,7 +7,7 @@ Provides common fixtures for mocking core components and test setup.
 import pytest
 import sys
 from pathlib import Path
-from unittest.mock import Mock, MagicMock
+from unittest.mock import Mock, MagicMock, NonCallableMock
 from typing import Dict, Any, Optional
 
 # Add project root to path
@@ -16,6 +16,115 @@ if str(project_root) not in sys.path:
     sys.path.insert(0, str(project_root))
 
 
+def pytest_configure(config):
+    """Point the emulator at a per-process config that binds no socket.
+
+    Six test modules set EMULATOR=true and build a real DisplayManager. The
+    repo's emulator_config.json selects the "browser" adapter, which binds a
+    fixed TCP port (8888) to serve the dev preview. That port is a machine-wide
+    singleton, so a second pytest process -- a CI shard, another worktree, an
+    agent running the suite alongside -- loses the bind. RGBMatrix construction
+    then raises, DisplayManager falls back to ``self.matrix = None``, and every
+    test that touches the matrix dies with a misleading
+    ``AttributeError: 'NoneType' object has no attribute 'SwapOnVSync'``.
+
+    The "raw" adapter renders in memory and binds nothing, so concurrent runs
+    stop fighting over the port. The tests wrap SwapOnVSync on the matrix object
+    itself, so they are indifferent to which adapter sits underneath. Only the
+    adapter is overridden -- every other key is inherited from the repo config,
+    which stays on "browser" for ``run.py -e``.
+    """
+    try:
+        from RGBMatrixEmulator.internal.emulator_config import RGBMatrixEmulatorConfig
+    except ImportError:
+        return  # No emulator installed; the EMULATOR=true modules can't run anyway.
+
+    import json
+    import tempfile
+
+    settings = {}
+    try:
+        settings = json.loads((project_root / "emulator_config.json").read_text())
+    except (OSError, ValueError):
+        pass  # Fall back to the emulator's own defaults; only the adapter matters.
+    if not isinstance(settings, dict):
+        settings = {}
+    settings["display_adapter"] = "raw"
+    # Falling back would land us back on the browser adapter and its fixed port.
+    settings["allow_adapter_fallback"] = False
+
+    tmp_dir = Path(tempfile.mkdtemp(prefix="ledmatrix-emulator-"))
+    tmp_config = tmp_dir / "emulator_config.json"
+    tmp_config.write_text(json.dumps(settings))
+    # CONFIG_PATH is a bare relative filename resolved against the CWD; an
+    # absolute path makes it independent of where pytest was invoked from.
+    RGBMatrixEmulatorConfig.CONFIG_PATH = str(tmp_config)
+    config._ledmatrix_emulator_tmp = tmp_dir
+
+
+def pytest_unconfigure(config):
+    """Remove the throwaway emulator config written by pytest_configure."""
+    tmp_dir = getattr(config, "_ledmatrix_emulator_tmp", None)
+    if tmp_dir is not None:
+        import shutil
+        shutil.rmtree(tmp_dir, ignore_errors=True)
+
+
+# DisplayManager is a process-wide singleton, and the RGBMatrix /
+# RGBMatrixOptions names it builds through are module globals bound once at
+# import to either the emulator or the hardware library. All three are shared
+# by every test module in the run, so a module that leaves a live instance in
+# _instance -- or leaves patch('src.display_manager.RGBMatrix') standing --
+# changes what the NEXT module constructs. None of that is visible when the
+# affected file is run on its own; it surfaces as a full-suite failure that
+# does not reproduce. The full-run failure diff is how a change is confirmed
+# non-regressive, so it has to mean the same thing on every run.
+_PRISTINE_MATRIX_BINDINGS = {}
+
+
+@pytest.fixture(autouse=True, scope="module")
+def _reset_display_manager_globals():
+    """Undo any DisplayManager global state a test module leaves behind.
+
+    Autouse fixtures are set up ahead of the fixtures a test asks for, so this
+    one is finalised after them -- including after a module-scoped fixture that
+    owns a real DisplayManager (test_display_dirty_tracking.py's ``dm``).
+    Module-scoped rather than per-test: files that deliberately share one
+    manager across their own tests keep doing so; only the leak across the
+    module boundary is cut.
+    """
+    # Record the real bindings on the way in, while no patch of this module's
+    # is active yet -- reading them on the way out would record the leak.
+    _remember_matrix_bindings()
+    yield
+
+    dm_mod = sys.modules.get("src.display_manager")
+    if dm_mod is None:
+        return  # Module never imported it; nothing to reset.
+
+    # An instance left here is what the next module's DisplayManager() call
+    # gets back -- potentially one built against a MagicMock matrix.
+    dm_mod.DisplayManager._instance = None
+    dm_mod.DisplayManager._initialized = False
+
+    # Put a binding back if a patch outlived the module that started it.
+    # Restoring rather than failing: a leak reported against an innocent module
+    # later in the run is the diagnosis problem, not the fix for it.
+    for name, pristine in _PRISTINE_MATRIX_BINDINGS.items():
+        if isinstance(getattr(dm_mod, name, None), NonCallableMock):
+            setattr(dm_mod, name, pristine)
+
+
+def _remember_matrix_bindings():
+    dm_mod = sys.modules.get("src.display_manager")
+    if dm_mod is None:
+        return
+    for name in ("RGBMatrix", "RGBMatrixOptions"):
+        current = getattr(dm_mod, name, None)
+        if current is not None and not isinstance(current, NonCallableMock):
+            _PRISTINE_MATRIX_BINDINGS.setdefault(name, current)
+
+
 @pytest.fixture
 def mock_display_manager():
     """Create a mock DisplayManager for testing."""

test/fixtures/api_v3_url_map.json

@@ -0,0 +1,990 @@
+[
+  [
+    "/api/v3/backup/<path:filename>",
+    "api_v3.backup_delete",
+    [
+      "DELETE",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/backup/download/<path:filename>",
+    "api_v3.backup_download",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/backup/export",
+    "api_v3.backup_export",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/backup/list",
+    "api_v3.backup_list",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/backup/preview",
+    "api_v3.backup_preview",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/backup/restore",
+    "api_v3.backup_restore",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/backup/validate",
+    "api_v3.backup_validate",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/cache/delete",
+    "api_v3.delete_cache_file",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/cache/list",
+    "api_v3.list_cache_files",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/config/dim-schedule",
+    "api_v3.get_dim_schedule_config",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/config/dim-schedule",
+    "api_v3.save_dim_schedule_config",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/config/main",
+    "api_v3.get_main_config",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/config/main",
+    "api_v3.save_main_config",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/config/raw/main",
+    "api_v3.save_raw_main_config",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/config/raw/secrets",
+    "api_v3.save_raw_secrets_config",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/config/schedule",
+    "api_v3.get_schedule_config",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/config/schedule",
+    "api_v3.save_schedule_config",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/config/secrets",
+    "api_v3.get_secrets_config",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/display/current",
+    "api_v3.get_display_current",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/display/current-status",
+    "api_v3.get_current_display_status",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/display/modes",
+    "api_v3.get_display_modes",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/display/on-demand/start",
+    "api_v3.start_on_demand_display",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/display/on-demand/status",
+    "api_v3.get_on_demand_status",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/display/on-demand/stop",
+    "api_v3.stop_on_demand_display",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/errors/clear",
+    "api_v3.clear_old_errors",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/errors/plugin/<plugin_id>",
+    "api_v3.get_plugin_errors",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/errors/summary",
+    "api_v3.get_error_summary",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/fonts/<font_family>",
+    "api_v3.delete_font",
+    [
+      "DELETE",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/fonts/catalog",
+    "api_v3.get_fonts_catalog",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/fonts/preview",
+    "api_v3.get_font_preview",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/fonts/tokens",
+    "api_v3.get_font_tokens",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/fonts/upload",
+    "api_v3.upload_font",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/hardware/status",
+    "api_v3.get_hardware_status",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/health",
+    "api_v3.get_health",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/integrations/mqtt-bridge",
+    "api_v3.get_mqtt_bridge",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/integrations/mqtt-bridge/config",
+    "api_v3.update_mqtt_bridge_config",
+    [
+      "OPTIONS",
+      "PUT"
+    ]
+  ],
+  [
+    "/api/v3/logs",
+    "api_v3.get_logs",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/plugins/<plugin_id>/static/<path:file_path>",
+    "api_v3.serve_plugin_static",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/plugins/action",
+    "api_v3.execute_plugin_action",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/plugins/assets/delete",
+    "api_v3.delete_plugin_asset",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/plugins/assets/list",
+    "api_v3.list_plugin_assets",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/plugins/assets/upload",
+    "api_v3.upload_plugin_asset",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/plugins/authenticate/spotify",
+    "api_v3.authenticate_spotify",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/plugins/authenticate/ytm",
+    "api_v3.authenticate_ytm",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/plugins/calendar/authenticate",
+    "api_v3.authenticate_calendar",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/plugins/calendar/list-calendars",
+    "api_v3.list_calendar_calendars",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/plugins/calendar/upload-credentials",
+    "api_v3.upload_calendar_credentials",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/plugins/config",
+    "api_v3.get_plugin_config",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/plugins/config",
+    "api_v3.save_plugin_config",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/plugins/config/reset",
+    "api_v3.reset_plugin_config",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/plugins/health",
+    "api_v3.get_plugin_health",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/plugins/health/<plugin_id>",
+    "api_v3.get_plugin_health_single",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/plugins/health/<plugin_id>/reset",
+    "api_v3.reset_plugin_health",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/plugins/install",
+    "api_v3.install_plugin",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/plugins/install-from-url",
+    "api_v3.install_plugin_from_url",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/plugins/installed",
+    "api_v3.get_installed_plugins",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/plugins/limits/<plugin_id>",
+    "api_v3.manage_plugin_limits",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/plugins/metrics",
+    "api_v3.get_plugin_metrics",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/plugins/metrics/<plugin_id>",
+    "api_v3.get_plugin_metrics_single",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/plugins/metrics/<plugin_id>/reset",
+    "api_v3.reset_plugin_metrics",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/plugins/of-the-day/json/delete",
+    "api_v3.delete_of_the_day_json",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/plugins/of-the-day/json/upload",
+    "api_v3.upload_of_the_day_json",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/plugins/operation/<operation_id>",
+    "api_v3.get_operation_status",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/plugins/operation/history",
+    "api_v3.clear_operation_history",
+    [
+      "DELETE",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/plugins/operation/history",
+    "api_v3.get_operation_history",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/plugins/reconciliation-status",
+    "api_v3.get_reconciliation_status",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/plugins/registry-from-url",
+    "api_v3.get_registry_from_url",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/plugins/saved-repositories",
+    "api_v3.add_saved_repository",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/plugins/saved-repositories",
+    "api_v3.get_saved_repositories",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/plugins/saved-repositories",
+    "api_v3.remove_saved_repository",
+    [
+      "DELETE",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/plugins/schema",
+    "api_v3.get_plugin_schema",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/plugins/state",
+    "api_v3.get_plugin_state",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/plugins/state/reconcile",
+    "api_v3.reconcile_plugin_state",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/plugins/store/github-status",
+    "api_v3.get_github_auth_status",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/plugins/store/list",
+    "api_v3.list_plugin_store",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/plugins/store/refresh",
+    "api_v3.refresh_plugin_store",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/plugins/toggle",
+    "api_v3.toggle_plugin",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/plugins/uninstall",
+    "api_v3.uninstall_plugin",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/plugins/update",
+    "api_v3.update_plugin",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/skins",
+    "api_v3.list_skins",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/starlark/apps",
+    "api_v3.get_starlark_apps",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/starlark/apps/<app_id>",
+    "api_v3.get_starlark_app",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/starlark/apps/<app_id>",
+    "api_v3.uninstall_starlark_app",
+    [
+      "DELETE",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/starlark/apps/<app_id>/config",
+    "api_v3.get_starlark_app_config",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/starlark/apps/<app_id>/config",
+    "api_v3.update_starlark_app_config",
+    [
+      "OPTIONS",
+      "PUT"
+    ]
+  ],
+  [
+    "/api/v3/starlark/apps/<app_id>/render",
+    "api_v3.render_starlark_app",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/starlark/apps/<app_id>/toggle",
+    "api_v3.toggle_starlark_app",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/starlark/editor/apps",
+    "api_v3.list_pixlet_editor_apps",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/starlark/editor/start",
+    "api_v3.start_pixlet_editor",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/starlark/editor/status",
+    "api_v3.get_pixlet_editor_status",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/starlark/editor/stop",
+    "api_v3.stop_pixlet_editor",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/starlark/install-pixlet",
+    "api_v3.install_pixlet",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/starlark/repository/browse",
+    "api_v3.browse_tronbyte_repository",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/starlark/repository/categories",
+    "api_v3.get_tronbyte_categories",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/starlark/repository/install",
+    "api_v3.install_from_tronbyte_repository",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/starlark/status",
+    "api_v3.get_starlark_status",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/starlark/upload",
+    "api_v3.upload_starlark_app",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/sync/status",
+    "api_v3.get_sync_status",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/system/action",
+    "api_v3.execute_system_action",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/system/auto-update",
+    "api_v3.get_auto_update_status",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/system/auto-update/dismiss",
+    "api_v3.dismiss_auto_update_alert",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/system/check-update",
+    "api_v3.check_for_update",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/system/git-branches",
+    "api_v3.get_git_branches",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/system/git-info",
+    "api_v3.get_git_info",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/system/status",
+    "api_v3.get_system_status",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/system/version",
+    "api_v3.get_system_version",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/wifi/ap/auto-enable",
+    "api_v3.get_auto_enable_ap_mode",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/wifi/ap/auto-enable",
+    "api_v3.set_auto_enable_ap_mode",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/wifi/ap/disable",
+    "api_v3.disable_ap_mode",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/wifi/ap/enable",
+    "api_v3.enable_ap_mode",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/wifi/connect",
+    "api_v3.connect_wifi",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/wifi/disconnect",
+    "api_v3.disconnect_wifi",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/wifi/radio",
+    "api_v3.get_wifi_radio",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/wifi/radio",
+    "api_v3.set_wifi_radio",
+    [
+      "OPTIONS",
+      "POST"
+    ]
+  ],
+  [
+    "/api/v3/wifi/scan",
+    "api_v3.scan_wifi_networks",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ],
+  [
+    "/api/v3/wifi/status",
+    "api_v3.get_wifi_status",
+    [
+      "GET",
+      "HEAD",
+      "OPTIONS"
+    ]
+  ]
+]

test/js/README.md

@@ -36,9 +36,13 @@ nothing is listening, so it stays useful in a bare checkout.
 |---|---|---|
 | `unit/test_list_filter.js` | no | `ListFilter` search/filter/sort/count/sticky, and the installed-plugins config **extracted verbatim** from `plugins_manager.js` so the test can't drift from it |
 | `unit/test_render_cards.js` | no | `renderInstalledCards` markup, both empty states, and HTML-escaping of hostile plugin metadata |
+| `unit/test_style_editor_element_keys.js` | no | `elementKeys()`/`styleRows()`/`positionRows()` from `widgets/style-editor.js`: every `customization.layout` entry gets exactly one row -- paired with its style element through core's `x-layout-key` (so `score` belongs to `score_text`, not a second row), or a position row of its own, leaves included -- since the widget claims the whole `layout` block from the generic fallback renderer |
+| `unit/test_style_editor_layout_leaf_columns.js` | no | `columnsFor()` from `widgets/style-editor.js`: a layout-only key whose own value is a leaf (no x/y sub-object, e.g. a `show_logo` toggle) gets a self-keyed column instead of a blank, uneditable row |
+| `unit/test_style_editor_layout_leaf_collision.js` | no | `columnsFor()` from `widgets/style-editor.js`: a layout-only leaf key still gets its own column even when its name collides with an unrelated element's style sub-field or another layout axis's sub-field |
 | `dom/test_installed_dom.js` | yes | The toolbar in a real DOM: pill/search/sort interaction, the HTMX partial re-swap, and a `getComputedStyle` check that `.filter-pill[data-active]` really matches the emitted markup |
 | `dom/test_store_dom.js` | yes | Store pagination, per-page, category, tri-state Installed button, and persistence across a re-boot, against the live registry |
 | `dom/test_no_double_fetch.js` | yes | Loads the **whole** `plugins_manager.js` and counts requests: typing in the store search must filter the cached list, not refetch `/api/v3/plugins/store/list` |
+| `dom/test_tools_sections.js` | yes | The Tools tab's MQTT bridge and Pixlet editor sections: form prefill, the write-only password (blank means unchanged), the running-session banner and countdown, and that the editor link points at the host you loaded the page from |
 
 Point the DOM suites at a rig with a full plugin set when it matters — a dev box
 with two plugins installed will pass while exercising very little.

test/js/dom/test_tools_sections.js

@@ -0,0 +1,127 @@
+// Real-DOM (jsdom) test of the two new Tools sections. The HTML is the actual
+// server-rendered /partials/tools, and the payloads are the real API's, so a
+// renamed field or a changed shape fails this rather than passing quietly.
+const http = require('http');
+const { JSDOM, VirtualConsole } = require('jsdom');
+
+const BASE = process.env.BASE || 'http://localhost:5000';
+const get = p => new Promise((res, rej) =>
+  http.get(BASE + p, r => { let d = ''; r.on('data', c => d += c); r.on('end', () => res(d)); }).on('error', rej));
+
+(async () => {
+  const partial = await get('/partials/tools');
+  const bridge = JSON.parse(await get('/api/v3/integrations/mqtt-bridge'));
+  const apps = JSON.parse(await get('/api/v3/starlark/editor/apps'));
+
+  const errs = [];
+  const vc = new VirtualConsole();
+  vc.on('jsdomError', e => errs.push(String(e.message || e).split('\n')[0]));
+
+  // Controllable fetch: serve the real payloads, and let tests swap in others.
+  let editorStatus = { status: 'success', data: { running: false } };
+  let bridgePayload = bridge;
+  let onPut = null;
+  const stubFetch = (url, opts) => {
+    const u = String(url);
+    if (onPut && opts && opts.method === 'PUT') onPut(JSON.parse(opts.body));
+    let body = { status: 'success', data: {} };
+    if (u.includes('/integrations/mqtt-bridge')) body = bridgePayload;
+    else if (u.includes('/starlark/editor/status')) body = editorStatus;
+    else if (u.includes('/starlark/editor/apps')) body = apps;
+    return Promise.resolve({ ok: true, status: 200, json: () => Promise.resolve(body) });
+  };
+
+  // runScripts:'dangerously' so the partial's own <script> executes the way a
+  // browser runs it -- function declarations land on window. Evaluating the
+  // source by hand instead leaves helpers like escHtml off the global object
+  // and the page fails in ways it never would in a browser.
+  const dom = new JSDOM(`<!doctype html><html><body>${partial}</body></html>`,
+    { runScripts: 'dangerously', virtualConsole: vc, url: BASE + '/',
+      beforeParse(w) { w.fetch = stubFetch; w.confirm = () => true; } });
+  const { window } = dom;
+
+  const tick = ms => new Promise(r => setTimeout(r, ms));
+  await tick(300);
+
+  const $ = id => window.document.getElementById(id);
+  let pass = 0, fail = 0;
+  const ok = (l, c, x) => c ? (pass++, console.log('  ok   ' + l))
+    : (fail++, console.log('  FAIL ' + l + (x !== undefined ? '  → ' + JSON.stringify(x).slice(0, 200) : '')));
+
+  console.log('\n── Tools: MQTT bridge + Pixlet editor (real DOM) ──');
+
+  // ── MQTT bridge ────────────────────────────────────────────────────────
+  ok('bridge form rendered', !!$('mqtt-host'), $('mqtt-bridge-body').textContent.slice(0, 80));
+  ok('host prefilled from the API', $('mqtt-host').value === bridge.data.config.mqtt_host,
+     { got: $('mqtt-host') && $('mqtt-host').value, want: bridge.data.config.mqtt_host });
+  ok('port prefilled', $('mqtt-port').value === String(bridge.data.config.mqtt_port));
+  ok('log level selected', $('mqtt-log-level').value === bridge.data.config.log_level);
+  ok('TLS checkbox matches', $('mqtt-tls').checked === !!bridge.data.config.mqtt_tls);
+  ok('password field is EMPTY', $('mqtt-password').value === '');
+  ok('password field is type=password', $('mqtt-password').type === 'password');
+  ok('no password value anywhere in the DOM',
+     !/s3cret|mqtt_password"\s*:\s*"/.test(window.document.body.innerHTML));
+  ok('state badge rendered', ($('mqtt-bridge-state').textContent || '').trim().length > 0,
+     $('mqtt-bridge-state').textContent);
+  ok('not-installed shows an Install button', !!$('btn-mqtt-install'));
+  ok('config path shown', $('mqtt-bridge-body').textContent.includes('bridge_config.json'));
+  ok('env override hint shown', $('mqtt-bridge-body').textContent.includes('LEDMATRIX_MQTT_'));
+
+  // The save body must omit the password when the field is blank.
+  let sent = null;
+  onPut = body => { sent = body; };
+  window.saveMqttBridge();
+  await tick(150);
+  ok('save omits password when left blank', sent && !('mqtt_password' in sent), sent && Object.keys(sent));
+  ok('save sends the edited fields', sent && sent.mqtt_host === bridge.data.config.mqtt_host, sent);
+
+  $('mqtt-password').value = 'typed-secret';
+  window.saveMqttBridge();
+  await tick(150);
+  ok('save includes password once typed', sent && sent.mqtt_password === 'typed-secret');
+  onPut = null;
+
+  // ── Pixlet editor, idle ────────────────────────────────────────────────
+  const appIds = (apps.data.apps || []).map(a => a.id);
+  ok('editor lists the apps on disk',
+     appIds.every(id => $('pixlet-editor-body').textContent.includes(id)), appIds);
+  ok('no session banner while idle', !$('pixlet-countdown'));
+  // escHtml does not encode single quotes, so an app id interpolated into an
+  // inline onclick="startPixletEditor('...')" could break out of the JS string
+  // and run script. The id must reach the handler through dataset instead.
+  const editBtns = [...window.document.querySelectorAll('[id^="btn-pixlet-edit-"]')];
+  ok('edit buttons exist', editBtns.length > 0, editBtns.length);
+  ok('edit buttons carry no inline onclick',
+     editBtns.every(b => !b.getAttribute('onclick')),
+     editBtns.map(b => b.getAttribute('onclick')));
+  ok('edit buttons pass the app id via dataset',
+     editBtns.every(b => appIds.includes(b.dataset.appId)),
+     editBtns.map(b => b.dataset.appId));
+  ok('warns that the display stops',
+     window.document.body.textContent.includes('display stops while a session is open'));
+
+  // ── Pixlet editor, running ─────────────────────────────────────────────
+  editorStatus = { status: 'success', data: {
+    running: true, app_id: 'test-editor-app', port: 8099, seconds_remaining: 1634,
+    timeout: 1800, host_bound: '0.0.0.0' } };
+  window.loadPixletEditor();
+  await tick(200);
+
+  ok('running session shows the banner', !!$('pixlet-countdown'));
+  ok('countdown formatted mm:ss', $('pixlet-countdown').textContent === '27:14',
+     $('pixlet-countdown') && $('pixlet-countdown').textContent);
+  ok('Stop button offered', !!$('btn-pixlet-stop'));
+  const link = [...window.document.querySelectorAll('#pixlet-editor-body a')].find(a => /Open the editor/.test(a.textContent));
+  ok('editor link present', !!link);
+  ok('link uses this host, not localhost — no tunnel needed',
+     !!link && link.href.includes(window.location.hostname) && link.href.includes(':8099'),
+     link && link.href);
+  ok('Edit buttons disabled while a session runs',
+     [...window.document.querySelectorAll('[id^="btn-pixlet-edit-"]')].every(b => b.disabled));
+  ok('banner names the app being edited',
+     $('pixlet-editor-body').textContent.includes('test-editor-app'));
+
+  ok('no uncaught JS errors', errs.length === 0, errs.slice(0, 3));
+  console.log(`\n${pass} passed, ${fail} failed\n`);
+  process.exit(fail ? 1 : 0);
+})().catch(e => { console.log('HARNESS ERROR: ' + e.stack.split('\n').slice(0, 5).join('\n')); process.exit(1); });

test/js/run_all.js

@@ -14,8 +14,12 @@ const path = require('path');
 const fs = require('fs');
 
 const BASE = process.env.BASE || 'http://localhost:5000';
-const UNIT = ['unit/test_list_filter.js', 'unit/test_render_cards.js'];
-const DOM = ['dom/test_installed_dom.js', 'dom/test_store_dom.js', 'dom/test_no_double_fetch.js'];
+const UNIT = ['unit/test_list_filter.js', 'unit/test_render_cards.js',
+              'unit/test_html_escaping.js', 'unit/test_style_editor_element_keys.js',
+              'unit/test_style_editor_layout_leaf_columns.js',
+              'unit/test_style_editor_layout_leaf_collision.js'];
+const DOM = ['dom/test_installed_dom.js', 'dom/test_store_dom.js', 'dom/test_no_double_fetch.js',
+             'dom/test_tools_sections.js'];
 
 function reachable(url) {
   return new Promise(res => {

test/js/unit/test_html_escaping.js

@@ -0,0 +1,320 @@
+// Every HTML escaper in the web interface must escape quotes, not just
+// & < >.
+//
+// The escapers are all written as `div.textContent = x; return div.innerHTML`.
+// That round-trip escapes &, < and > because those are the only characters the
+// HTML serializer has to escape in a *text node* -- quotes are left alone. But
+// the widgets interpolate the result into quoted attribute values
+// (`value="${escapeHtml(v)}"`, `title="${escapeHtml(v)}"`, ...), and there a
+// bare `"` closes the attribute and lets the value add attributes of its own:
+//
+//     name" onfocus="alert(1)
+//
+// CodeQL reported 83 js/incomplete-html-attribute-sanitization alerts for
+// exactly this. This suite pins the fix at the source: it reads each real
+// implementation out of the shipped file and runs it, so an escaper that loses
+// its quote handling again fails here rather than in a scanner run weeks later.
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '../../../web_interface');
+
+let pass = 0, fail = 0;
+const ok = (label, cond, extra) => cond
+  ? (pass++, console.log('  ok   ' + label))
+  : (fail++, console.log('  FAIL ' + label + (extra !== undefined ? '  -> ' + JSON.stringify(extra).slice(0, 300) : '')));
+
+// ── DOM shim ───────────────────────────────────────────────────────────────
+// Mirrors what a browser does reading innerHTML back off textContent: & < >
+// are escaped, quotes are not. Anything the escaper adds on top of that is
+// the escaper's own doing, which is what we are testing.
+class FakeEl {
+  set textContent(v) { this._t = String(v == null ? '' : v); }
+  get textContent() { return this._t || ''; }
+  get innerHTML() {
+    return (this._t || '')
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;');
+  }
+}
+global.document = { createElement: () => new FakeEl() };
+global.window = global;
+
+// ── source extraction ──────────────────────────────────────────────────────
+// Pull a function out of a real source file by its opening line and balanced
+// braces, so the test runs the shipped code rather than a copy of it.
+function extract(file, opener) {
+  const src = fs.readFileSync(path.join(ROOT, file), 'utf8');
+  const start = src.indexOf(opener);
+  if (start < 0) {
+    console.error(`FAIL: cannot find ${JSON.stringify(opener)} in ${file}`);
+    process.exit(1);
+  }
+  let i = src.indexOf('{', start), depth = 0;
+  for (let j = i; j < src.length; j++) {
+    if (src[j] === '{') depth++;
+    else if (src[j] === '}') {
+      depth--;
+      if (depth === 0) return src.slice(start, j + 1);
+    }
+  }
+  console.error(`FAIL: unbalanced braces after ${JSON.stringify(opener)} in ${file}`);
+  process.exit(1);
+}
+
+// Evaluate an extracted escaper and return it as a callable.
+function loadFn(file, opener, name, { method = false } = {}) {
+  const body = extract(file, opener);
+  // Class/object methods (`escapeHtml(text) {...}`) are not valid statements on
+  // their own -- wrap them in an object literal so they can be evaluated.
+  const code = method
+    ? `(function(){ const o = { ${body} }; return o.${name}.bind(o); })()`
+    : `(function(){ ${body}; return ${name}; })()`;
+  // eslint-disable-next-line no-eval
+  return eval(code);
+}
+
+// ── the escapers, as shipped ───────────────────────────────────────────────
+const ESCAPERS = [
+  ['base-widget.js (BaseWidget.escapeHtml)',
+   'static/v3/js/widgets/base-widget.js', 'escapeHtml(text) {', 'escapeHtml', true],
+  ['plugins_manager.js (top-level escapeHtml)',
+   'static/v3/plugins_manager.js', 'function escapeHtml(text) {', 'escapeHtml', false],
+  ['plugins_manager.js (starlark escapeHtml)',
+   'static/v3/plugins_manager.js', 'function escapeHtml(str) {', 'escapeHtml', false],
+  ['error_handler.js (escapeHtml)',
+   'static/v3/js/utils/error_handler.js', 'function escapeHtml(text) {', 'escapeHtml', false],
+  ['json-file-manager.js (_esc)',
+   'static/v3/js/widgets/json-file-manager.js', '_esc(str) {', '_esc', true],
+  ['plugin-file-manager.js (escHtml)',
+   'static/v3/js/widgets/plugin-file-manager.js', 'function escHtml(s) {', 'escHtml', false],
+  ['app-shell.js (escapeHtml)',
+   'static/v3/js/app-shell.js', 'escapeHtml(text) {', 'escapeHtml', true],
+  ['logs.html (escapeHtml)',
+   'templates/v3/partials/logs.html', 'function escapeHtml(text) {', 'escapeHtml', false],
+  ['cache.html (escapeHtml)',
+   'templates/v3/partials/cache.html', 'function escapeHtml(text) {', 'escapeHtml', false],
+];
+
+// The breakout payload: closes a double-quoted attribute and opens an event
+// handler. If `"` survives escaping, this is live script in the rendered page.
+const BREAKOUT = 'x" onmouseover="alert(1)';
+
+console.log('\n1. every escaper neutralises a double-quote attribute breakout');
+for (const [label, file, opener, name, method] of ESCAPERS) {
+  const fn = loadFn(file, opener, name, { method });
+  const out = String(fn(BREAKOUT));
+  ok(`${label}: no raw "`, !out.includes('"'), out);
+  ok(`${label}: emits &quot;`, out.includes('&quot;'), out);
+}
+
+console.log('\n2. every escaper also escapes single quotes');
+for (const [label, file, opener, name, method] of ESCAPERS) {
+  const fn = loadFn(file, opener, name, { method });
+  const out = String(fn("x' onmouseover='alert(1)"));
+  ok(`${label}: no raw '`, !out.includes("'"), out);
+}
+
+console.log('\n3. the & < > behaviour they already had is unchanged');
+for (const [label, file, opener, name, method] of ESCAPERS) {
+  const fn = loadFn(file, opener, name, { method });
+  const out = String(fn('<img src=x onerror=alert(1)> & done'));
+  ok(`${label}: no raw <`, !out.includes('<'), out);
+  ok(`${label}: no raw >`, !out.includes('>'), out);
+  ok(`${label}: & becomes &amp;`, /&amp;/.test(out), out);
+}
+
+console.log('\n4. ampersands are escaped before quotes, so &quot; cannot be forged');
+// If `&` were escaped last, the input `&quot;` would come out as a literal
+// `"` after the browser decodes the attribute. Order matters; pin it.
+for (const [label, file, opener, name, method] of ESCAPERS) {
+  const fn = loadFn(file, opener, name, { method });
+  const out = String(fn('&quot;'));
+  ok(`${label}: &quot; input stays inert`, out === '&amp;quot;', out);
+}
+
+// ── url-input scheme handling (js/xss-through-dom) ─────────────────────────
+console.log('\n5. url-input never treats a scriptable scheme as a valid URL');
+{
+  const src = fs.readFileSync(path.join(ROOT, 'static/v3/js/widgets/url-input.js'), 'utf8');
+  const a = src.indexOf('const RFC_SCHEME_PATTERN');
+  const b = src.indexOf("window.LEDMatrixWidgets.register('url-input'");
+  if (a < 0 || b < 0) { console.error('FAIL: cannot locate url-input helpers'); process.exit(1); }
+  // eslint-disable-next-line no-eval
+  const helpers = eval(`(function(){ ${src.slice(a, b)}; return { normalizeProtocols, isValidUrl, safeHref }; })()`);
+  const { normalizeProtocols, isValidUrl, safeHref } = helpers;
+
+  ok('javascript: rejected under the default protocols',
+     !isValidUrl('javascript:alert(1)', ['http', 'https']));
+  ok('javascript: still rejected when a schema asks for it',
+     !isValidUrl('javascript:alert(1)', normalizeProtocols(['javascript'])));
+  ok('a schema asking only for javascript falls back to http/https',
+     JSON.stringify(normalizeProtocols(['javascript'])) === JSON.stringify(['http', 'https']),
+     normalizeProtocols(['javascript']));
+  ok('data: rejected', !isValidUrl('data:text/html,<script>alert(1)</script>', ['http', 'https', 'data']));
+  ok('vbscript: rejected', !isValidUrl('vbscript:msgbox(1)', ['http', 'https', 'vbscript']));
+  ok('normalizeProtocols drops scriptable schemes but keeps the rest',
+     JSON.stringify(normalizeProtocols('https,javascript,ftp')) === JSON.stringify(['https', 'ftp']),
+     normalizeProtocols('https,javascript,ftp'));
+
+  ok('ordinary https URL still valid', isValidUrl('https://example.com/x?y=1', ['http', 'https']));
+  ok('ordinary http URL still valid', isValidUrl('http://example.com', ['http', 'https']));
+  ok('a scheme outside the allow-list is still rejected',
+     !isValidUrl('ftp://example.com', ['http', 'https']));
+
+  ok('safeHref passes a good URL through', safeHref('https://example.com', ['http', 'https']) === 'https://example.com');
+  ok('safeHref blanks a javascript: URL', safeHref('javascript:alert(1)', ['http', 'https']) === '');
+  ok('safeHref blanks an unparseable value', safeHref('not a url', ['http', 'https']) === '');
+}
+
+// ── url-input onInput: the sink itself, not just the pulled-out helpers ────
+// The scheme check now lives inline in onInput, right where the value reaches
+// `previewLink.href`, instead of behind safeHref/isValidUrl -- see the comment
+// at that assignment in url-input.js for why. Run the handler as shipped so a
+// regression that reintroduces an unguarded `previewLink.href = value` fails
+// here, not just in a scanner run weeks later.
+console.log('\n6. url-input onInput: previewLink.href is guarded at the sink');
+{
+  class FakeClassList {
+    constructor() { this.classes = new Set(['hidden']); }
+    add(c) { this.classes.add(c); }
+    remove(c) { this.classes.delete(c); }
+    contains(c) { return this.classes.has(c); }
+  }
+  const mockDoc = (value, protocolsAttr) => {
+    const elements = {
+      _input: { value, checkValidity: () => true, validationMessage: '', classList: new FakeClassList() },
+      _preview: { classList: new FakeClassList() },
+      _preview_link: {
+        classList: new FakeClassList(),
+        _href: undefined,
+        set href(v) { this._href = v; },
+        get href() { return this._href; },
+        removeAttribute(name) { if (name === 'href') this._href = undefined; },
+      },
+      _widget: { dataset: { protocols: protocolsAttr } },
+      _error: { classList: new FakeClassList(), textContent: '' },
+    };
+    return {
+      elements,
+      getElementById: (id) => elements[Object.keys(elements).find(k => id === `field${k}`)] || null,
+    };
+  };
+
+  function runOnInput(value, protocolsAttr) {
+    const { elements, getElementById } = mockDoc(value, protocolsAttr);
+    const savedDocument = global.document;
+    const savedWindow = global.window;
+    let registered = null;
+    global.document = { createElement: () => new FakeEl(), getElementById };
+    global.window = {
+      LEDMatrixWidgets: {
+        register: (name, obj) => { registered = obj; },
+        get: () => registered,
+        getHandlers: () => registered.handlers,
+      },
+    };
+    try {
+      const src = fs.readFileSync(path.join(ROOT, 'static/v3/js/widgets/url-input.js'), 'utf8');
+      // eslint-disable-next-line no-eval
+      eval(src);
+      registered.handlers.onInput('field');
+    } finally {
+      global.document = savedDocument;
+      global.window = savedWindow;
+    }
+    return elements;
+  }
+
+  let els = runOnInput('javascript:alert(1)', 'http,https');
+  ok('javascript: never reaches previewLink.href', els._preview_link.href === undefined, els._preview_link.href);
+  ok('javascript: leaves the preview hidden', els._preview.classList.contains('hidden'));
+
+  els = runOnInput('https://example.com', 'http,https');
+  ok('an ordinary https URL reaches previewLink.href', els._preview_link.href === 'https://example.com', els._preview_link.href);
+  ok('an ordinary https URL unhides the preview', !els._preview.classList.contains('hidden'));
+
+  els = runOnInput('data:text/html,<script>alert(1)</script>', 'http,https,data');
+  ok('data: never reaches previewLink.href even when the schema allows it',
+     els._preview_link.href === undefined, els._preview_link.href);
+
+  els = runOnInput('not a url', 'http,https');
+  ok('an unparseable value never reaches previewLink.href', els._preview_link.href === undefined, els._preview_link.href);
+}
+
+// ── plugin-file-manager: cell edits travel via data-*, not inline handlers ──
+// A JSON key/day from an uploaded file used to be spliced, HTML-escaped,
+// into an oninput="...('${escHtml(col)}'...)" attribute. escHtml neutralises
+// a quote for an ordinary attribute, but here the value also has to survive
+// as a *JS string literal* -- the browser HTML-decodes the attribute before
+// running it as script, which turns the escaped quote back into a real one
+// and lets a column named `x');alert(1);//` break out of the string and run
+// arbitrary JS. Cell edits now reach _pfmCellEdit only via data-day/data-col
+// read by one delegated listener, so this pins that no inline handler string
+// is built from the value at all.
+console.log("\n7. plugin-file-manager: cell edits never go through an inline handler string");
+{
+  const src = fs.readFileSync(path.join(ROOT, 'static/v3/js/widgets/plugin-file-manager.js'), 'utf8');
+
+  function extractFn(opener) {
+    const start = src.indexOf(opener);
+    if (start < 0) { console.error(`FAIL: cannot find ${JSON.stringify(opener)}`); process.exit(1); }
+    let i = src.indexOf('{', start), depth = 0;
+    for (let j = i; j < src.length; j++) {
+      if (src[j] === '{') depth++;
+      else if (src[j] === '}') { depth--; if (depth === 0) return src.slice(start, j + 1); }
+    }
+    console.error(`FAIL: unbalanced braces after ${JSON.stringify(opener)}`);
+    process.exit(1);
+  }
+
+  const escHtmlFn = loadFn('static/v3/js/widgets/plugin-file-manager.js', 'function escHtml(s) {', 'escHtml', false);
+  const renderEntryTableSrc = extractFn('function renderEntryTable(fieldId, container, content) {');
+
+  const calls = [];
+  const fakeWindow = { _pfmCellEdit: (fieldId, day, col, value) => calls.push({ fieldId, day, col, value }) };
+
+  class FakeContainer {
+    constructor() { this._html = ''; this._listeners = {}; }
+    set innerHTML(v) { this._html = v; }
+    get innerHTML() { return this._html; }
+    set textContent(v) { this._html = v; }
+    addEventListener(type, fn) { this._listeners[type] = fn; }
+    dispatch(type, target) { this._listeners[type]({ target }); }
+  }
+
+  function fakeCell(day, col, value) {
+    return {
+      closest: (sel) => (sel.includes('data-day') ? { dataset: { day: String(day), col: String(col) }, value } : null),
+    };
+  }
+
+  // eslint-disable-next-line no-eval
+  const renderEntryTable = eval(`(function(getState, escHtml, safeSetHTML, window){
+    ${renderEntryTableSrc}
+    return renderEntryTable;
+  })`)(
+    () => ({ entriesPerPage: 20, _tablePage: 1 }),
+    escHtmlFn,
+    (target, html) => { target.innerHTML = html; },
+    fakeWindow
+  );
+
+  const maliciousCol = "x');alert(1);//";
+  const container = new FakeContainer();
+  renderEntryTable('field1', container, { '1': { [maliciousCol]: 'hello' } });
+
+  ok('no inline oninput handler is emitted for a cell', !/oninput=/.test(container.innerHTML), container.innerHTML);
+  ok('the malicious column name never appears unescaped in the markup',
+     !container.innerHTML.includes(maliciousCol), container.innerHTML);
+
+  container.dispatch('input', fakeCell('1', maliciousCol, 'typed value'));
+  ok('the delegated listener still reaches _pfmCellEdit with the real day/col',
+     calls.length === 1 && calls[0].day === '1' && calls[0].col === maliciousCol && calls[0].value === 'typed value',
+     calls);
+}
+
+console.log(`\n${pass} passed, ${fail} failed\n`);
+process.exit(fail ? 1 : 0);

test/js/unit/test_style_editor_element_keys.js

@@ -0,0 +1,126 @@
+// Regression test for how style-editor.js decides which rows to draw,
+// extracted verbatim from the shipped widget (own/ownObj/elementKeys/
+// styleRows/positionRows have no DOM dependency) so the test can't drift from
+// the real implementation.
+//
+// render() claims the whole `layout` child of a customization schema as the
+// widget's own -- removing it from the generic fallback renderer entirely,
+// because posting the same offset twice from two controls is worse than
+// owning slightly too much. That is only safe when every entry under `layout`
+// gets exactly one row:
+//
+//   * styleRows(): one per style element, paired with the layout entry that
+//     holds its offsets. The pairing is not by exact name -- a hand-written
+//     schema styles 'score_text' but positions 'score' -- so core records it
+//     as x-layout-key, resolved through the same alias map the renderer reads
+//     offsets with.
+//   * positionRows(): one per layout entry no style element claimed -- a logo,
+//     a timeout indicator, a possession arrow, or a bare leaf like a
+//     show_logo toggle.
+//
+// This contract replaced an earlier one in which elementKeys() itself
+// appended layout-only keys. That compared names exactly, so an aliased entry
+// ('score' for 'score_text') was listed a second time and its offsets got two
+// controls posting the same field.
+const fs = require('fs');
+const path = require('path');
+const V3 = path.resolve(__dirname, '../../../web_interface/static/v3');
+
+const src = fs.readFileSync(path.join(V3, 'js/widgets/style-editor.js'), 'utf8');
+const start = src.indexOf('function own(obj, key)');
+const endMark = 'function control(opts)';
+const end = src.indexOf(endMark);
+if (start === -1 || end === -1) {
+  console.error('FAIL: could not locate own()..positionRows() in style-editor.js -- slice markers need updating');
+  process.exit(1);
+}
+eval(src.slice(start, end)); // defines own/ownObj/elementKeys/styleRows/positionRows
+
+let failures = 0;
+function ok(desc, cond) {
+  if (cond) { console.log(`ok - ${desc}`); }
+  else { console.log(`FAIL - ${desc}`); failures++; }
+}
+
+function layoutKeysOf(rows) { return rows.map(function (r) { return r.layoutKey; }); }
+
+// score_text is styled and positioned under an alias; odds_text has no
+// offsets at all; possession is positioned but never styled; show_logo is a
+// bare leaf under layout.
+const schema = {
+  properties: {
+    score_text: {
+      type: 'object', 'x-style-managed': true, 'x-layout-key': 'score',
+      properties: { font: { type: 'string' }, text_color: { type: 'array' } },
+    },
+    odds_text: {
+      type: 'object', 'x-style-managed': true,
+      properties: { font: { type: 'string' } },
+    },
+    layout: {
+      type: 'object',
+      'x-propertyOrder': ['score', 'possession', 'show_logo'],
+      properties: {
+        score: { type: 'object', properties: { x_offset: {}, y_offset: {} } },
+        possession: { type: 'object', properties: { x_offset: {}, y_offset: {} } },
+        show_logo: { type: 'boolean', default: true },
+      },
+    },
+  },
+};
+
+const keys = elementKeys(schema);
+ok('elementKeys lists the style elements', keys.join(',') === 'score_text,odds_text');
+ok('layout and modes containers are never treated as elements',
+   keys.indexOf('layout') === -1 && keys.indexOf('modes') === -1);
+
+const styled = styleRows(schema);
+ok('a style element is paired with the layout entry core resolved for it',
+   styled[0].key === 'score_text' && styled[0].layoutKey === 'score');
+ok('a style element with no offsets claims nothing', styled[1].layoutKey === null);
+
+const positions = positionRows(schema);
+ok('a layout-only object entry gets a position row',
+   layoutKeysOf(positions).indexOf('possession') !== -1);
+ok('a layout-only leaf gets a position row too',
+   layoutKeysOf(positions).indexOf('show_logo') !== -1);
+ok('an entry claimed through an alias is not listed again as a position',
+   layoutKeysOf(positions).indexOf('score') === -1);
+ok('positions follow the declared order',
+   layoutKeysOf(positions).join(',') === 'possession,show_logo');
+
+const every = layoutKeysOf(styled).filter(Boolean).concat(layoutKeysOf(positions));
+ok('every layout entry gets exactly one row',
+   every.length === new Set(every).size
+   && every.slice().sort().join(',') === ['possession', 'score', 'show_logo'].join(','));
+
+// A schema with no layout block at all must behave exactly as before --
+// the overwhelmingly common case must not gain a phantom row.
+const noLayout = {
+  properties: {
+    score_text: {
+      type: 'object', 'x-style-managed': true,
+      properties: { font: { type: 'string' } },
+    },
+  },
+};
+ok('a schema without a layout block has no positions',
+   elementKeys(noLayout).join(',') === 'score_text' && positionRows(noLayout).length === 0);
+
+// Without an annotation (the compact declaration, or a schema that never went
+// through expansion) the two blocks share one key.
+const unannotated = {
+  properties: {
+    home_logo: { type: 'object', 'x-style-managed': true, properties: {} },
+    layout: {
+      type: 'object',
+      properties: { home_logo: { type: 'object', properties: { x_offset: {}, scale: {} } } },
+    },
+  },
+};
+ok('an exact-name layout entry is claimed without an annotation',
+   styleRows(unannotated)[0].layoutKey === 'home_logo'
+   && positionRows(unannotated).length === 0);
+
+if (failures) { console.log(`\n${failures} failure(s)`); process.exit(1); }
+console.log('\nall checks passed');

test/js/unit/test_style_editor_layout_leaf_collision.js

@@ -0,0 +1,76 @@
+// Regression test for style-editor.js's columnsFor(), extracted verbatim
+// from the shipped widget (see test_style_editor_layout_leaf_columns.js for
+// the base case this builds on).
+//
+// A layout-only leaf key (e.g. a bare "scale" toggle directly under
+// `layout`, no x/y object underneath) used to be keyed in the internal
+// `seen` map by its own bare field name. If some *other* element's style
+// block, or another element's layout axis block, happened to declare a
+// sub-field with that exact same name (e.g. "scale" is also a real
+// COLUMN_ORDER axis name most elements use), the `!seen.has(key)` guard
+// skipped creating the leaf's column -- it silently reused the existing
+// 'element'/'layout' column instead. That column's row binding in
+// elementRow() then looked the field up under the wrong schema location for
+// the leaf's own row, found nothing, and rendered a blank cell: the same
+// "silently disappears" bug the leaf-column fix was meant to close, just
+// reached through a name collision instead of a missing column altogether.
+// This pins the fix: layout-leaf columns are keyed under a namespaced id so
+// they can never be shadowed by an unrelated column sharing their name.
+const fs = require('fs');
+const path = require('path');
+const V3 = path.resolve(__dirname, '../../../web_interface/static/v3');
+
+const src = fs.readFileSync(path.join(V3, 'js/widgets/style-editor.js'), 'utf8');
+const start = src.indexOf('function own(obj, key)');
+const endMark = 'function control(opts)';
+const end = src.indexOf(endMark);
+if (start === -1 || end === -1) {
+  console.error('FAIL: could not locate own()/columnsFor() in style-editor.js -- slice markers need updating');
+  process.exit(1);
+}
+eval(src.slice(start, end)); // defines own/ownObj/elementKeys/columnsFor
+
+let failures = 0;
+function ok(desc, cond) {
+  if (cond) { console.log(`ok - ${desc}`); }
+  else { console.log(`FAIL - ${desc}`); failures++; }
+}
+
+// `possession` is a real style element whose layout axis block declares a
+// "scale" sub-field, which seeds seen.set('scale', 'layout'). `timeout_flag`
+// is layout-only and a bare leaf valued directly under layout, but its own
+// key is *also* "scale" -- an unrelated collision with that same name.
+const schema = {
+  properties: {
+    possession: {
+      type: 'object',
+      'x-style-managed': true,
+      properties: { font: { type: 'string' } },
+    },
+    scale: {
+      // The collision: a second element literally named "scale", entirely
+      // unrelated to the layout-only leaf below sharing that string.
+      type: 'boolean',
+    },
+    layout: {
+      type: 'object',
+      properties: {
+        possession: { type: 'object', properties: { scale: { type: 'number' } } },
+        scale: { type: 'boolean', default: true },
+      },
+    },
+  },
+};
+
+const columns = columnsFor(schema);
+const leafColumns = columns.filter(function (c) { return c.where === 'layout-leaf'; });
+
+ok('the colliding layout axis sub-field still gets its own column',
+   columns.some(function (c) { return c.key === 'scale' && c.where === 'layout'; }));
+ok('the layout-only leaf key still gets its own column despite the name collision',
+   leafColumns.length === 1 && leafColumns[0].key === 'scale');
+ok('the leaf column is distinct from the colliding element/layout column',
+   columns.filter(function (c) { return c.key === 'scale'; }).length === 2);
+
+if (failures) { console.log(`\n${failures} failure(s)`); process.exit(1); }
+console.log('\nall checks passed');

test/js/unit/test_style_editor_layout_leaf_columns.js

@@ -0,0 +1,89 @@
+// Regression test for style-editor.js's columnsFor(), extracted verbatim
+// from the shipped widget (own/ownObj/elementKeys/columnsFor have no DOM
+// dependency) so the test can't drift from the real implementation.
+//
+// elementKeys() already appends a layout-only key that never got its own
+// top-level style block (see test_style_editor_element_keys.js), so table()
+// draws a row for it. But render() still claims the whole `layout` child as
+// the widget's own regardless of what that row actually shows -- and
+// columnsFor() only produced a column for a layout-only key whose own value
+// is an *object* with sub-fields (x_offset, y_offset, ...). A hand-written
+// schema can instead put a plain leaf value directly under layout -- a
+// "show_logo" toggle, a timeout indicator's on/off flag -- with no x/y
+// object underneath it. That key still got a row (data-element="show_logo"),
+// but zero columns ever matched it, so the row rendered with every cell
+// blank: no control, and no way back to the fallback since layout was
+// removed wholesale. This pins the fix: such a key gets its own
+// self-keyed 'layout-leaf' column.
+const fs = require('fs');
+const path = require('path');
+const V3 = path.resolve(__dirname, '../../../web_interface/static/v3');
+
+const src = fs.readFileSync(path.join(V3, 'js/widgets/style-editor.js'), 'utf8');
+const start = src.indexOf('function own(obj, key)');
+const endMark = 'function control(opts)';
+const end = src.indexOf(endMark);
+if (start === -1 || end === -1) {
+  console.error('FAIL: could not locate own()/columnsFor() in style-editor.js -- slice markers need updating');
+  process.exit(1);
+}
+eval(src.slice(start, end)); // defines own/ownObj/elementKeys/columnsFor
+
+let failures = 0;
+function ok(desc, cond) {
+  if (cond) { console.log(`ok - ${desc}`); }
+  else { console.log(`FAIL - ${desc}`); failures++; }
+}
+
+// score_text is a real style element; possession is layout-only but shaped
+// like an object (x/y); show_logo is layout-only and a bare leaf value.
+const schema = {
+  properties: {
+    score_text: {
+      type: 'object',
+      'x-style-managed': true,
+      properties: { font: { type: 'string' }, text_color: { type: 'array' } },
+    },
+    layout: {
+      type: 'object',
+      properties: {
+        score_text: { type: 'object', properties: { x_offset: {}, y_offset: {} } },
+        possession: { type: 'object', properties: { x_offset: {}, y_offset: {} } },
+        show_logo: { type: 'boolean', default: true },
+      },
+    },
+  },
+};
+
+const columns = columnsFor(schema);
+const byKey = {};
+columns.forEach(function (c) { byKey[c.key] = c; });
+
+ok('an element style field still gets its own column', byKey.font && byKey.font.where === 'element');
+ok('a layout-only object key still contributes its x/y columns',
+   byKey.x_offset && byKey.x_offset.where === 'layout');
+ok('a layout-only leaf key gets a column keyed to itself',
+   !!byKey.show_logo);
+ok('...marked as a layout-leaf column, not a shared sub-field',
+   byKey.show_logo && byKey.show_logo.where === 'layout-leaf');
+ok('nothing is duplicated', columns.length === new Set(columns.map(function (c) { return c.key; })).size);
+
+// A schema with no leaf-valued layout key must not gain a phantom column --
+// this is the common case (every existing scoreboard) and must be unaffected.
+const noLeaf = {
+  properties: {
+    score_text: {
+      type: 'object', 'x-style-managed': true,
+      properties: { font: { type: 'string' } },
+    },
+    layout: {
+      type: 'object',
+      properties: { score_text: { type: 'object', properties: { x_offset: {} } } },
+    },
+  },
+};
+ok('a schema with only object-shaped layout keys gets no layout-leaf column',
+   columnsFor(noLeaf).every(function (c) { return c.where !== 'layout-leaf'; }));
+
+if (failures) { console.log(`\n${failures} failure(s)`); process.exit(1); }
+console.log('\nall checks passed');

test/test_api_v3_font_upload_size.py

@@ -0,0 +1,60 @@
+"""Regression test: POST /fonts/upload must enforce its own stated size limit.
+
+validate_file_upload(filename, max_size_mb=10, allowed_extensions=[...]) reads
+like it checks the upload's size, but it only ever validated the filename
+(traversal characters, extension) -- max_size_mb was accepted and silently
+ignored. Nothing else in the handler checked the actual upload size either,
+so it saved whatever was posted to assets/fonts/<family><ext> regardless of
+size, unlike the sibling .star and plugin-asset upload routes, which check
+`file.tell()` against a stated limit before saving.
+"""
+
+import io
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from test._api_v3_test_helpers import api_v3_client, api_v3_module  # noqa: F401,E402
+
+URL = "/api/v3/fonts/upload"
+TEN_MB = 10 * 1024 * 1024
+
+
+@pytest.fixture
+def fonts_root(tmp_path):
+    # PROJECT_ROOT is bound by value in fonts.py, so it is patched there.
+    with patch("web_interface.blueprints.api_v3.fonts.PROJECT_ROOT", tmp_path):
+        yield tmp_path
+
+
+def upload(client, content, filename="myfont.ttf", family="myfont"):
+    data = {
+        "font_file": (io.BytesIO(content), filename),
+        "font_family": family,
+    }
+    return client.post(URL, data=data, content_type="multipart/form-data")
+
+
+class TestFontUploadSizeLimit:
+    def test_oversized_font_is_rejected(self, api_v3_client, fonts_root):
+        response = upload(api_v3_client, b"x" * (TEN_MB + 1))
+        assert response.status_code == 400
+        assert "too large" in response.get_json()["message"].lower()
+        assert not (fonts_root / "assets" / "fonts" / "myfont.ttf").exists(), (
+            "an oversized font was saved to disk before being rejected")
+
+    def test_a_font_right_at_the_limit_is_accepted(self, api_v3_client, fonts_root):
+        response = upload(api_v3_client, b"x" * TEN_MB,
+                          filename="atlimit.ttf", family="atlimit")
+        assert response.status_code == 200, response.get_json()
+        assert (fonts_root / "assets" / "fonts" / "atlimit.ttf").exists()
+
+    def test_an_ordinary_small_font_is_still_accepted(self, api_v3_client, fonts_root):
+        response = upload(api_v3_client, b"fake font bytes",
+                          filename="small.ttf", family="small")
+        assert response.status_code == 200, response.get_json()
+        assert (fonts_root / "assets" / "fonts" / "small.ttf").read_bytes() == b"fake font bytes"

test/test_api_v3_on_demand_restart.py

@@ -0,0 +1,93 @@
+"""Regression test: POST /display/on-demand/start restarting a running
+service must not import a name that does not exist.
+
+display.py has `import web_interface.blueprints.api_v3 as _pkg` and reads
+mutable, test-patched attributes back through it (`_pkg.time.time()`,
+`_pkg._get_starlark_plugin()`, ...) rather than binding them by value, per
+the package's own docstring. One spot went further and wrote a genuine
+`import` *statement* against that alias --
+
+    import _pkg.time as time_module
+
+-- but `_pkg` is a local name bound by `import ... as _pkg` in this module,
+not a real top-level package, so `import _pkg.time` is not something Python
+can resolve; it raises ModuleNotFoundError. That line only runs when the
+display service is already running and the caller also asked to (re)start
+it, so this endpoint failed on exactly the restart path -- the one where a
+cache write recording the new on-demand request had already happened.
+
+The route wraps its body in `except Exception`, so the failure reached the
+caller as a handled 500 with a generic message, not an unhandled crash --
+but a 500 all the same on a request that should have restarted the service
+and reported success.
+"""
+
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from test._api_v3_test_helpers import api_v3_client, api_v3_module  # noqa: F401,E402
+
+URL = "/api/v3/display/on-demand/start"
+
+
+@pytest.fixture
+def restart_path(api_v3_module):
+    """Force the `service_was_running and start_service` branch.
+
+    plugin_manager and config_manager are set to None so the route takes
+    the simplest path to that branch rather than tripping over unrelated
+    MagicMock plumbing; _ensure_cache_manager, _get_display_service_status,
+    _stop_display_service and _ensure_display_service_running are bound by
+    value in display.py (see its own docstring), so they are patched on
+    that submodule rather than on the package.
+    """
+    api_v3_module.api_v3.plugin_manager = None
+    api_v3_module.api_v3.config_manager = None
+
+    with patch("web_interface.blueprints.api_v3.display._ensure_cache_manager") as ensure_cache, \
+         patch("web_interface.blueprints.api_v3.display._get_display_service_status") as get_status, \
+         patch("web_interface.blueprints.api_v3.display._stop_display_service") as stop_service, \
+         patch("web_interface.blueprints.api_v3.display._ensure_display_service_running") as ensure_running:
+        ensure_cache.return_value = MagicMock()
+        # Active before the request: service_was_running becomes True.
+        get_status.return_value = {"active": True}
+        ensure_running.return_value = {"active": True}
+        yield {
+            "ensure_cache": ensure_cache,
+            "get_status": get_status,
+            "stop_service": stop_service,
+            "ensure_running": ensure_running,
+        }
+
+
+class TestRestartingARunningService:
+    def test_it_does_not_500(self, api_v3_client, restart_path):
+        response = api_v3_client.post(
+            URL, json={"plugin_id": "weather", "start_service": True})
+        body = response.get_json()
+        assert response.status_code == 200, body
+        assert body["status"] == "success", body
+
+    def test_the_service_is_actually_stopped_and_restarted(
+            self, api_v3_client, restart_path):
+        api_v3_client.post(
+            URL, json={"plugin_id": "weather", "start_service": True})
+        restart_path["stop_service"].assert_called_once()
+        restart_path["ensure_running"].assert_called_once()
+
+    def test_a_service_that_was_not_running_is_not_stopped_first(
+            self, api_v3_client, restart_path):
+        # The buggy import sits inside `if service_was_running and
+        # start_service`, so it only ever fired on the restart path --
+        # this is the other side of that branch, unaffected either way,
+        # kept here so the branch condition itself stays covered.
+        restart_path["get_status"].return_value = {"active": False}
+        response = api_v3_client.post(
+            URL, json={"plugin_id": "weather", "start_service": True})
+        assert response.status_code == 200, response.get_json()
+        restart_path["stop_service"].assert_not_called()

test/test_api_v3_optional_body.py

@@ -106,7 +106,12 @@ class TestMissingBodyGivesTheDeclaredError:
 
 
 class TestNoBodyReadContradictsItsOwnGuard:
-    SOURCE = Path(__file__).parent.parent / "web_interface/blueprints/api_v3.py"
+    PKG = Path(__file__).parent.parent / "web_interface/blueprints/api_v3"
+
+    @property
+    def _source(self) -> str:
+        """api_v3 is a package; read every module of it."""
+        return "\n".join(p.read_text() for p in sorted(self.PKG.glob("*.py")))
 
     def test_no_or_default_read_is_unguarded(self):
         """`get_json() or <default>` is a contradiction without silent=True.
@@ -115,7 +120,7 @@ class TestNoBodyReadContradictsItsOwnGuard:
         means the call raises before the default can apply.
         """
         offenders = [
-            line.strip() for line in self.SOURCE.read_text().splitlines()
+            line.strip() for line in self._source.splitlines()
             if "request.get_json()" in line and " or " in line
         ]
         assert offenders == [], (
@@ -124,7 +129,7 @@ class TestNoBodyReadContradictsItsOwnGuard:
 
     def test_no_not_data_guard_is_unreachable(self):
         """A `if not data:` guard needs a read that can actually return None."""
-        lines = self.SOURCE.read_text().splitlines()
+        lines = self._source.splitlines()
         offenders = []
         for i, line in enumerate(lines):
             if re.search(r"=\s*request\.get_json\(\)\s*$", line):

test/test_api_v3_schedule_error_messages.py

@@ -0,0 +1,54 @@
+"""Regression test: per-day schedule validation errors must say "time", not
+"_pkg.time".
+
+The split into a package rewrote every bare `time` reference that needed to
+read through the shared module as `_pkg.time` (see the package's own
+docstring on why -- tests patch it, so it has to be read back live rather
+than bound by value). That rewrite was mechanical and matched the substring
+"time" inside string literals and comments too, so the user-facing message
+
+    "Invalid start time for {day}: ..."
+
+came out as
+
+    "Invalid start _pkg.time for {day}: ..."
+
+in both POST /config/schedule and POST /config/dim-schedule, for both the
+start and end time of a per-day entry.
+"""
+
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from test._api_v3_test_helpers import api_v3_client, api_v3_module  # noqa: F401,E402
+
+
+@pytest.mark.parametrize("url", [
+    "/api/v3/config/schedule",
+    "/api/v3/config/dim-schedule",
+])
+class TestPerDayTimeErrorsAreNotCorrupted:
+    def test_invalid_start_time_message(self, api_v3_client, api_v3_module, url):
+        response = api_v3_client.post(url, json={
+            "mode": "per_day",
+            "monday_start": "not-a-time",
+        })
+        assert response.status_code == 400
+        message = response.get_json()["message"]
+        assert "_pkg" not in message, message
+        assert message.startswith("Invalid start time for monday:"), message
+
+    def test_invalid_end_time_message(self, api_v3_client, api_v3_module, url):
+        response = api_v3_client.post(url, json={
+            "mode": "per_day",
+            "monday_start": "07:00",
+            "monday_end": "not-a-time",
+        })
+        assert response.status_code == 400
+        message = response.get_json()["message"]
+        assert "_pkg" not in message, message
+        assert message.startswith("Invalid end time for monday:"), message

test/test_api_v3_url_map.py

@@ -0,0 +1,136 @@
+"""The /api/v3 URL map is a contract, and the split must not have moved it.
+
+api_v3.py was one 10,469-line module and is now a package. Every route module
+in it decorates the *same* Blueprint object, so this refactor was supposed to
+be invisible from outside: same URLs, same endpoint names, same methods.
+
+"Supposed to be" is the problem. A route function silently dropped during a
+move -- a module that never gets imported, a decorator left behind -- costs
+nothing at import time and fails only when someone hits the URL. So the map is
+pinned here.
+
+The snapshot is intentionally the *whole* map rather than a count. A count
+passes when one route is deleted and another added, which is exactly the shape
+a careless move produces.
+
+If you are adding a route, this test is meant to fail: add the entry to
+EXPECTED. If you are moving one between modules, it is meant to pass unchanged
+-- endpoint names are `api_v3.<function>` regardless of which module the
+function lives in, and that is the property that makes the package safe.
+"""
+import json
+import os
+
+import pytest
+from flask import Flask
+
+from web_interface.blueprints.api_v3 import api_v3
+
+SNAPSHOT = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                        "fixtures", "api_v3_url_map.json")
+
+
+def _current_map():
+    app = Flask(__name__)
+    app.register_blueprint(api_v3, url_prefix="/api/v3")
+    return sorted(
+        [r.rule, r.endpoint, sorted(r.methods)]
+        for r in app.url_map.iter_rules()
+        if r.endpoint != "static"
+    )
+
+
+def test_the_url_map_matches_the_snapshot():
+    current = _current_map()
+    with open(SNAPSHOT, encoding="utf-8") as fh:
+        expected = json.load(fh)
+
+    cur = {(r, e) for r, e, _ in current}
+    exp = {(r, e) for r, e, _ in expected}
+
+    lost = sorted(exp - cur)
+    added = sorted(cur - exp)
+    assert not lost, (
+        f"{len(lost)} route(s) disappeared from /api/v3: {lost[:5]}. "
+        "A route lost in a module move costs nothing at import time and fails "
+        "only when someone hits the URL.")
+    assert not added, (
+        f"{len(added)} new route(s): {added[:5]}. If that is intended, "
+        f"regenerate {os.path.relpath(SNAPSHOT)}.")
+
+    # Methods too: a route that quietly loses POST is still a broken route.
+    cur_methods = {(r, e): m for r, e, m in current}
+    for rule, endpoint, methods in expected:
+        assert cur_methods[(rule, endpoint)] == methods, (
+            f"{rule} ({endpoint}) methods changed: "
+            f"{methods} -> {cur_methods[(rule, endpoint)]}")
+
+
+def test_every_endpoint_is_on_the_one_blueprint():
+    """The package must not fragment into several blueprints.
+
+    Splitting into per-domain *blueprints* would rename every endpoint from
+    `api_v3.foo` to `api_v3_plugins.foo` and break any url_for() that names
+    one. Keeping a single Blueprint object across the modules is what makes
+    the split a pure code move, so assert it rather than trusting it.
+    """
+    for rule, endpoint, _ in _current_map():
+        assert endpoint.startswith("api_v3."), (
+            f"{rule} is registered as {endpoint}, not on the api_v3 blueprint")
+
+
+def test_the_snapshot_is_not_empty():
+    """Guards the failure mode this file exists to prevent.
+
+    An empty or truncated snapshot would make every assertion above pass
+    vacuously -- the same trap as a route map that imports no modules.
+    """
+    with open(SNAPSHOT, encoding="utf-8") as fh:
+        expected = json.load(fh)
+    assert len(expected) > 100, (
+        f"snapshot has only {len(expected)} routes; it should have the whole "
+        "/api/v3 surface")
+
+
+@pytest.mark.parametrize("module", [
+    "backup", "config", "display", "fonts", "misc",
+    "plugins", "starlark", "system", "wifi",
+])
+def test_every_route_module_contributes(module):
+    """Each module must actually register something.
+
+    A module that fails to import, or that is left out of __init__, takes its
+    routes with it silently -- the package still imports and the app still
+    starts.
+    """
+    import importlib
+    mod = importlib.import_module(f"web_interface.blueprints.api_v3.{module}")
+    routes = [n for n in dir(mod)
+              if callable(getattr(mod, n, None))
+              and getattr(getattr(mod, n), "__module__", "") == mod.__name__]
+    assert routes, f"{module}.py defines no view functions"
+
+
+def test_project_root_points_at_the_project():
+    """PROJECT_ROOT is derived from __file__, so moving the file breaks it.
+
+    The split moved this code from web_interface/blueprints/api_v3.py to
+    web_interface/blueprints/api_v3/_common.py -- one directory deeper -- and
+    `Path(__file__).parent.parent.parent` quietly began resolving to
+    web_interface/ instead of the project root. Nothing failed at import. It
+    surfaced as routes returning 404 and "installation script not found",
+    because every path built from it pointed one level too shallow.
+
+    A URL-map check cannot catch that: the routes were all registered, they
+    just could not find anything.
+    """
+    from pathlib import Path
+
+    from web_interface.blueprints.api_v3 import PROJECT_ROOT
+
+    # The project root is the directory holding run.py and web_interface/.
+    assert (PROJECT_ROOT / "run.py").is_file(), (
+        f"PROJECT_ROOT is {PROJECT_ROOT}, which has no run.py; it is not the "
+        "project root")
+    assert (PROJECT_ROOT / "web_interface").is_dir()
+    assert PROJECT_ROOT == Path(__file__).resolve().parents[1]

test/test_api_v3_wifi_endpoints.py

@@ -26,6 +26,9 @@ def wifi_manager():
     """Patch WiFiManager where it is defined; yield the instance mock."""
     with patch("src.wifi_manager.WiFiManager") as cls:
         instance = MagicMock()
+        # A bare MagicMock is truthy, which would send every connect down
+        # the setup-AP background path.
+        instance._is_ap_mode_active.return_value = False
         cls.return_value = instance
         yield instance
 
@@ -97,6 +100,129 @@ class TestConnect:
         assert "RuntimeError" in body["details"]
 
 
+class TestConnectThroughSetupAp:
+    """With the setup AP up, the phone making the request is connected through
+    the very network the connect tears down. A synchronous answer can never
+    arrive, so the route answers 202 first and connects in the background."""
+
+    URL = "/api/v3/wifi/connect"
+
+    @pytest.fixture(autouse=True)
+    def ap_active(self, api_v3_module, wifi_manager, monkeypatch):
+        from web_interface.blueprints.api_v3 import wifi as wifi_routes
+        wifi_manager._is_ap_mode_active.return_value = True
+        monkeypatch.setattr(wifi_routes, "_AP_HANDOFF_DELAY_SECONDS", 0)
+        monkeypatch.setattr(wifi_routes, "_last_connect_attempt", None)
+        self.spawned = []
+        monkeypatch.setattr(wifi_routes, "_spawn", self.spawned.append)
+        self.routes = wifi_routes
+
+    def _run_spawned(self):
+        assert len(self.spawned) == 1
+        self.spawned.pop()()
+
+    def test_answers_202_before_connecting(self, api_v3_client, wifi_manager):
+        response = api_v3_client.post(self.URL, json={"ssid": "HomeNet", "password": "hunter22"})
+        assert response.status_code == 202
+        assert response.get_json()["status"] == "pending"
+        wifi_manager.connect_to_network.assert_not_called()
+        assert self.routes._last_connect_snapshot()["state"] == "pending"
+
+    def test_background_result_is_reported_by_status(self, api_v3_client, wifi_manager):
+        wifi_manager.connect_to_network.return_value = (True, "Connected to HomeNet")
+        api_v3_client.post(self.URL, json={"ssid": "HomeNet", "password": "hunter22"})
+        self._run_spawned()
+        wifi_manager.connect_to_network.assert_called_once_with("HomeNet", "hunter22")
+
+        wifi_manager.config = {}
+        wifi_manager.get_wifi_status.return_value = MagicMock(
+            connected=True, ssid="HomeNet", ip_address="10.0.0.5", signal=70,
+            ap_mode_active=False)
+        attempt = api_v3_client.get("/api/v3/wifi/status").get_json()["data"]["last_connect_attempt"]
+        assert attempt["ssid"] == "HomeNet"
+        assert attempt["state"] == "success"
+        assert "hunter22" not in str(attempt)
+
+    def test_wrong_password_is_flagged(self, api_v3_client, wifi_manager):
+        wifi_manager.connect_to_network.return_value = (
+            False, "wrong_password: Secrets were required, but not provided")
+        api_v3_client.post(self.URL, json={"ssid": "HomeNet", "password": "hunter22"})
+        self._run_spawned()
+        attempt = self.routes._last_connect_snapshot()
+        assert attempt["state"] == "failed"
+        assert attempt["error_type"] == "wrong_password"
+        assert attempt["message"] == "Incorrect password for HomeNet"
+
+    def test_manager_exception_is_recorded_as_a_failure(self, api_v3_client, wifi_manager):
+        wifi_manager.connect_to_network.side_effect = RuntimeError("nmcli vanished")
+        api_v3_client.post(self.URL, json={"ssid": "HomeNet"})
+        self._run_spawned()
+        attempt = self.routes._last_connect_snapshot()
+        assert attempt["state"] == "failed"
+        assert "RuntimeError" in attempt["message"]
+
+    def test_a_second_connect_while_one_is_pending_is_refused(self, api_v3_client, wifi_manager):
+        api_v3_client.post(self.URL, json={"ssid": "HomeNet"})
+        response = api_v3_client.post(self.URL, json={"ssid": "OtherNet"})
+        assert response.status_code == 409
+        assert len(self.spawned) == 1
+
+    def test_pending_is_honoured_after_the_ap_has_gone_down(self, api_v3_client, wifi_manager):
+        # The background attempt tears the AP down long before it finishes; a
+        # second click must not slip through as a synchronous connect.
+        api_v3_client.post(self.URL, json={"ssid": "HomeNet"})
+        wifi_manager._is_ap_mode_active.return_value = False
+        response = api_v3_client.post(self.URL, json={"ssid": "OtherNet"})
+        assert response.status_code == 409
+        wifi_manager.connect_to_network.assert_not_called()
+
+    def test_a_thread_that_fails_to_start_does_not_leave_pending_behind(
+            self, api_v3_client, wifi_manager, monkeypatch):
+        def refuse(_target):
+            raise RuntimeError("can't start new thread")
+        monkeypatch.setattr(self.routes, "_spawn", refuse)
+        assert api_v3_client.post(self.URL, json={"ssid": "HomeNet"}).status_code == 500
+        assert self.routes._last_connect_snapshot() is None
+
+        monkeypatch.setattr(self.routes, "_spawn", self.spawned.append)
+        assert api_v3_client.post(self.URL, json={"ssid": "HomeNet"}).status_code == 202
+
+
+class TestConnectSerializedWithoutAp:
+    """Without the AP the route connects synchronously, but still one attempt
+    at a time: a second connect_to_network would remove the in-progress flag
+    the daemon relies on when the first finishes."""
+
+    URL = "/api/v3/wifi/connect"
+
+    @pytest.fixture(autouse=True)
+    def no_prior_attempt(self, api_v3_module, monkeypatch):
+        from web_interface.blueprints.api_v3 import wifi as wifi_routes
+        monkeypatch.setattr(wifi_routes, "_last_connect_attempt", None)
+        self.routes = wifi_routes
+
+    def test_a_connect_during_a_synchronous_connect_is_refused(
+            self, api_v3_client, wifi_manager):
+        inner = []
+
+        def connect(ssid, password):
+            if not inner:
+                inner.append(api_v3_client.post(self.URL, json={"ssid": "OtherNet"}))
+            return True, f"Connected to {ssid}"
+
+        wifi_manager.connect_to_network.side_effect = connect
+        response = api_v3_client.post(self.URL, json={"ssid": "HomeNet"})
+        assert response.status_code == 200
+        assert inner[0].status_code == 409
+        wifi_manager.connect_to_network.assert_called_once_with("HomeNet", "")
+        assert self.routes._last_connect_snapshot()["state"] == "success"
+
+    def test_an_exception_does_not_leave_pending_behind(self, api_v3_client, wifi_manager):
+        wifi_manager.connect_to_network.side_effect = RuntimeError("nmcli gone")
+        assert api_v3_client.post(self.URL, json={"ssid": "HomeNet"}).status_code == 500
+        assert self.routes._last_connect_snapshot()["state"] == "failed"
+
+
 class TestDisconnect:
     URL = "/api/v3/wifi/disconnect"
 
@@ -195,7 +321,7 @@ class TestRadio:
 
     @pytest.mark.parametrize("raw,expected", [
         (True, True), ("true", True), ("1", True), ("yes", True),
-        (False, False), ("false", False), ("off", False), (0, False),
+        (False, False), ("false", False), ("no", False), (0, False),
     ])
     def test_enabled_coercion_is_string_aware(
             self, api_v3_client, wifi_manager, raw, expected):
@@ -228,6 +354,84 @@ class TestRadio:
         wifi_manager.set_wifi_radio.side_effect = RuntimeError("boom")
         assert api_v3_client.post(self.URL, json={"enabled": True}).status_code == 500
 
+    def test_unrecognized_enabled_value_is_rejected_not_treated_as_false(
+            self, api_v3_client, wifi_manager):
+        # An invalid `enabled` used to silently fall back to False, which
+        # can disconnect Wi-Fi (or, with force=true, drop the caller's own
+        # connection to this interface) even though nothing asked for that.
+        response = api_v3_client.post(self.URL, json={"enabled": "typo"})
+        assert response.status_code == 400
+        wifi_manager.set_wifi_radio.assert_not_called()
+
+    def test_unrecognized_force_value_is_rejected_not_treated_as_false(
+            self, api_v3_client, wifi_manager):
+        response = api_v3_client.post(
+            self.URL, json={"enabled": False, "force": "typo"})
+        assert response.status_code == 400
+        wifi_manager.set_wifi_radio.assert_not_called()
+
+
+class TestAutoEnableApMode:
+    URL = "/api/v3/wifi/ap/auto-enable"
+
+    def test_requires_the_field(self, api_v3_client, wifi_manager):
+        response = api_v3_client.post(self.URL, json={})
+        assert response.status_code == 400
+
+    @pytest.mark.parametrize("raw,expected", [
+        (True, True), (False, False),
+        ("true", True), ("True", True), ("1", True), ("yes", True),
+        ("false", False), ("False", False), ("0", False), ("no", False),
+        (1, True), (0, False),
+    ])
+    def test_value_is_coerced_not_just_truthy(
+            self, api_v3_client, wifi_manager, raw, expected):
+        # Regression: bool(data['auto_enable_ap_mode']) meant a caller who
+        # sent the JSON string "false" got it stored as True — bool("false")
+        # is True, since any non-empty string is truthy.
+        wifi_manager.config = {}
+        response = api_v3_client.post(self.URL, json={"auto_enable_ap_mode": raw})
+        assert response.status_code == 200, response.get_json()
+        assert response.get_json()["data"]["auto_enable_ap_mode"] is expected
+        assert wifi_manager.config["auto_enable_ap_mode"] is expected
+
+    def test_a_string_false_does_not_enable_it(self, api_v3_client, wifi_manager):
+        # The exact shape of the bug.
+        wifi_manager.config = {}
+        api_v3_client.post(self.URL, json={"auto_enable_ap_mode": "false"})
+        assert wifi_manager.config["auto_enable_ap_mode"] is False
+
+    def test_unrecognized_value_is_rejected_not_treated_as_false(
+            self, api_v3_client, wifi_manager):
+        wifi_manager.config = {}
+        response = api_v3_client.post(self.URL, json={"auto_enable_ap_mode": "typo"})
+        assert response.status_code == 400
+        assert "auto_enable_ap_mode" not in wifi_manager.config
+
+
+class TestRadioEnabledAndForceAcceptIntegers:
+    """`{"enabled": 1}` / `{"enabled": 0}` used to be mishandled: the old
+    coercion was `raw is True or (isinstance(raw, str) and ...)`, and
+    `1 is True` is False in Python -- an int is never the `True` singleton
+    even though it equals it -- so a plain integer fell through to False
+    regardless of its value.
+    """
+    URL = "/api/v3/wifi/radio"
+
+    @pytest.mark.parametrize("raw,expected", [(1, True), (0, False)])
+    def test_enabled_as_an_integer(self, api_v3_client, wifi_manager, raw, expected):
+        wifi_manager.set_wifi_radio.return_value = (True, "ok", None)
+        wifi_manager.get_wifi_radio_state.return_value = {}
+        api_v3_client.post(self.URL, json={"enabled": raw})
+        wifi_manager.set_wifi_radio.assert_called_once_with(expected, force=False)
+
+    @pytest.mark.parametrize("raw,expected", [(1, True), (0, False)])
+    def test_force_as_an_integer(self, api_v3_client, wifi_manager, raw, expected):
+        wifi_manager.set_wifi_radio.return_value = (True, "ok", None)
+        wifi_manager.get_wifi_radio_state.return_value = {}
+        api_v3_client.post(self.URL, json={"enabled": True, "force": raw})
+        wifi_manager.set_wifi_radio.assert_called_once_with(True, force=expected)
+
 
 class TestNoRealNetworking:
     def test_wifi_manager_is_never_constructed_for_real(self, api_v3_client):

test/test_auto_update.py

@@ -0,0 +1,683 @@
+"""Weekly automatic updates (web_interface/auto_update.py).
+
+The updater pulls code and restarts services unattended. These pin down that
+it runs only when asked and due, refuses to touch a checkout it could damage,
+never leaves new code running without a health check, and reports every
+failure instead of logging it and moving on.
+
+Git runs for real against a throwaway origin/device clone pair; systemd, sudo
+and the health check service are faked.
+"""
+import json
+import shutil
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT))
+
+from web_interface import auto_update as au  # noqa: E402
+
+# Local time is pinned to UTC below, so 03:00 is inside the quiet hours.
+NIGHT = datetime(2026, 9, 14, 3, 0, tzinfo=timezone.utc).timestamp()
+NOON = datetime(2026, 9, 14, 12, 0, tzinfo=timezone.utc).timestamp()
+ON = {'auto_update': {'enabled': True}}
+OFF = {'auto_update': {'enabled': False}}
+
+needs_git = pytest.mark.skipif(shutil.which('git') is None, reason='git not installed')
+
+
+@pytest.fixture(autouse=True)
+def local_is_utc(monkeypatch):
+    """Pin 'local time' so quiet-hours checks don't depend on the host zone."""
+    monkeypatch.setattr(au, '_zone', lambda name: timezone.utc)
+
+
+def git(cwd, *args):
+    result = subprocess.run(['git', '-c', 'user.name=t', '-c', 'user.email=t@example.com', *args],
+                            cwd=str(cwd), capture_output=True, text=True)
+    assert result.returncode == 0, result.stderr
+    return result.stdout.strip()
+
+
+class Repo:
+    """An origin, a checkout that publishes to it, and the device's clone."""
+
+    def __init__(self, tmp):
+        self.seed = tmp / 'seed'
+        self.seed.mkdir()
+        git(self.seed, 'init', '-q', '-b', 'main')
+        (self.seed / 'app.py').write_text('v = 1\n')
+        git(self.seed, 'add', '.')
+        git(self.seed, 'commit', '-qm', 'one')
+        self.origin = tmp / 'origin.git'
+        git(tmp, 'clone', '-q', '--bare', str(self.seed), str(self.origin))
+        git(self.seed, 'remote', 'add', 'origin', str(self.origin))
+        self.device = tmp / 'device'
+        git(tmp, 'clone', '-q', str(self.origin), str(self.device))
+
+    def head(self):
+        return git(self.device, 'rev-parse', 'HEAD')
+
+    def publish(self, text='v = 2\n'):
+        (self.seed / 'app.py').write_text(text)
+        git(self.seed, 'commit', '-qam', 'next')
+        git(self.seed, 'push', '-q', 'origin', 'main')
+        return git(self.seed, 'rev-parse', 'HEAD')
+
+
+def real_pull(device, **extra):
+    def core_update():
+        before = git(device, 'rev-parse', 'HEAD')
+        r = subprocess.run(['git', 'pull', '-q', '--rebase', '--autostash'],
+                           cwd=str(device), capture_output=True, text=True)
+        after = git(device, 'rev-parse', 'HEAD')
+        result = {'status': 'success' if r.returncode == 0 else 'error',
+                  'message': 'Code updated successfully.' if r.returncode == 0 else r.stderr,
+                  'restart_required': before != after, 'dependency_failures': []}
+        result.update(extra)
+        return result
+    return core_update
+
+
+class FakeStore:
+    def __init__(self, plugins_dir, versions, bump=(), fail=()):
+        self.plugins_dir = str(plugins_dir)
+        self.bump, self.fail = set(bump), set(fail)
+        for pid, version in versions.items():
+            d = Path(plugins_dir) / pid
+            d.mkdir(parents=True)
+            (d / 'manifest.json').write_text(json.dumps({'id': pid, 'version': version}))
+        self.updated_calls = []
+
+    def list_installed_plugins(self):
+        return [p.name for p in Path(self.plugins_dir).iterdir()]
+
+    def _get_local_git_info(self, path):
+        return None
+
+    def update_plugin(self, pid):
+        self.updated_calls.append(pid)
+        if pid in self.fail:
+            return False
+        if pid in self.bump:
+            path = Path(self.plugins_dir) / pid / 'manifest.json'
+            m = json.loads(path.read_text())
+            m['version'] = '9.9.9'
+            path.write_text(json.dumps(m))
+        return True
+
+
+class Harness:
+    """An AutoUpdater on a real clone.
+
+    ``helper`` is whether the health check's path unit is active; ``pickup``
+    whether the health check actually starts when asked. Starting it is
+    simulated the way systemd does it: the request file is consumed
+    (ExecStartPre) and the verifier marks the pending update "verifying".
+    """
+
+    def __init__(self, tmp, repo, *, helper=True, pickup=True, core_update=None, store=None,
+                 disk_free=10 ** 12, display_active=True, enabled=True, clock=NIGHT):
+        self.sudo, self.restarts, self.now = [], [], clock
+        self.state_at_handoff = None
+
+        def run(args, **kwargs):
+            if args[0] == 'sudo':
+                self.sudo.append(list(args))
+                return subprocess.CompletedProcess(args, 0, stdout='', stderr='')
+            return subprocess.run(args, **kwargs)
+
+        def sleep(seconds):
+            updater = self.updater
+            if self.state_at_handoff is None:
+                self.state_at_handoff = au.load_state(updater.state_file)
+            if pickup and updater.request_file.exists():
+                updater.request_file.unlink()
+                pending = au._read_json(updater.pending_file)
+                pending['status'] = 'verifying'
+                au._write_json(updater.pending_file, pending)
+
+        self.config = {'auto_update': {'enabled': enabled}, 'timezone': 'UTC'}
+        cm = MagicMock()
+        cm.load_config.return_value = self.config
+        self.updater = au.AutoUpdater(
+            config_manager=cm, core_update=core_update or real_pull(repo.device),
+            store_manager=store, project_root=repo.device, clock=lambda: self.now,
+            restart=self.restarts.append, run=run,
+            service_active=lambda unit: display_active, helper_ready=lambda: helper,
+            disk_free=lambda path: disk_free, sleep=sleep)
+
+    @property
+    def state(self):
+        return au.load_state(self.updater.state_file)
+
+    @property
+    def pending(self):
+        return au._read_json(self.updater.pending_file)
+
+    def write_pending(self, **fields):
+        au._write_json(self.updater.pending_file, fields)
+
+
+def stub_updater(tmp_path, outcome='up_to_date', message='ok', store=None, enabled=True, clock=NIGHT):
+    """For scheduling and plugin tests: the core update is stubbed out."""
+    cm = MagicMock()
+    cm.load_config.return_value = {'auto_update': {'enabled': enabled}, 'timezone': 'UTC'}
+    restarts = []
+    updater = au.AutoUpdater(config_manager=cm, core_update=MagicMock(), store_manager=store,
+                             project_root=tmp_path, clock=lambda: clock,
+                             restart=restarts.append)
+    updater.update_core = MagicMock(return_value={'outcome': outcome, 'message': message})
+    return updater, restarts
+
+
+# -- scheduling ---------------------------------------------------------------
+
+class TestIsDue:
+    def test_not_before_next_due(self):
+        assert not au.is_due(100, 200, 3)
+
+    def test_in_quiet_hours_once_due(self):
+        assert au.is_due(200, 200, 3)
+
+    def test_waits_for_quiet_hours(self):
+        assert not au.is_due(200, 100, 12)
+
+    def test_gives_up_waiting_after_grace(self):
+        assert au.is_due(100 + au.QUIET_HOURS_GRACE_SECONDS, 100, 12)
+
+
+class TestTick:
+    def test_disabled_never_runs(self, tmp_path):
+        updater, _ = stub_updater(tmp_path, enabled=False)
+        assert updater.tick() is False
+        updater.update_core.assert_not_called()
+
+    def test_enabling_at_noon_waits_for_the_night(self, tmp_path):
+        updater, _ = stub_updater(tmp_path, clock=NOON)
+        assert updater.tick() is False
+        updater.update_core.assert_not_called()
+        assert au.load_state(updater.state_file)['next_due'] == NOON
+
+    def test_runs_when_due_and_schedules_a_week_out(self, tmp_path):
+        updater, _ = stub_updater(tmp_path)
+        assert updater.tick() is True
+        state = au.load_state(updater.state_file)
+        assert state['next_due'] == NIGHT + au.UPDATE_INTERVAL_SECONDS
+        assert updater.tick() is False, "ran twice in one night"
+
+    def test_transient_error_retries_next_day(self, tmp_path):
+        updater, _ = stub_updater(tmp_path, outcome='error', message='no network')
+        updater.tick()
+        state = au.load_state(updater.state_file)
+        assert state['next_due'] == NIGHT + au.RETRY_AFTER_FAILURE_SECONDS
+        assert state['alert']['message'] == 'no network'
+
+    def test_blocked_keeps_weekly_cadence_but_alerts(self, tmp_path):
+        updater, _ = stub_updater(tmp_path, outcome='blocked', message='local edits')
+        updater.tick()
+        state = au.load_state(updater.state_file)
+        assert state['next_due'] == NIGHT + au.UPDATE_INTERVAL_SECONDS
+        assert 'local edits' in state['alert']['message']
+
+
+# -- checks before touching the checkout ---------------------------------------
+
+@needs_git
+class TestPreflightRefuses:
+    def test_nothing_new_is_up_to_date(self, tmp_path):
+        repo = Repo(tmp_path)
+        h = Harness(tmp_path, repo)
+        result = h.updater.run()
+        assert result['core_outcome'] == 'up_to_date'
+        assert result['status'] == 'success'
+        assert h.sudo == [] and 'alert' not in h.state
+
+    def test_without_the_health_check_code_is_not_touched(self, tmp_path):
+        repo = Repo(tmp_path)
+        old = repo.head()
+        repo.publish()
+        h = Harness(tmp_path, repo, helper=False)
+        result = h.updater.run()
+        assert result['core_outcome'] == 'blocked'
+        assert repo.head() == old
+        assert 'health check is set up' in result['core_message']
+        assert h.state['alert']
+
+    def test_local_edits_are_never_stashed(self, tmp_path):
+        repo = Repo(tmp_path)
+        old = repo.head()
+        repo.publish()
+        (repo.device / 'app.py').write_text('mine\n')
+        h = Harness(tmp_path, repo)
+        result = h.updater.run()
+        assert result['core_outcome'] == 'blocked'
+        assert 'app.py' in result['core_message']
+        assert repo.head() == old
+        assert (repo.device / 'app.py').read_text() == 'mine\n'
+        assert git(repo.device, 'stash', 'list') == ''
+
+    def test_local_commits_block(self, tmp_path):
+        repo = Repo(tmp_path)
+        repo.publish()
+        (repo.device / 'extra.txt').write_text('x\n')
+        git(repo.device, 'add', 'extra.txt')
+        git(repo.device, 'commit', '-qm', 'local')
+        mine = repo.head()
+        h = Harness(tmp_path, repo)
+        result = h.updater.run()
+        assert result['core_outcome'] == 'blocked'
+        assert 'local commit' in result['core_message']
+        assert repo.head() == mine
+
+    def test_a_rebase_really_in_progress_blocks(self, tmp_path):
+        repo = Repo(tmp_path)
+        repo.publish('v = 2\n')
+        (repo.device / 'app.py').write_text('v = mine\n')
+        git(repo.device, 'commit', '-qam', 'local')
+        git(repo.device, 'fetch', '-q')
+        stopped = subprocess.run(['git', '-c', 'user.name=t', '-c', 'user.email=t@example.com',
+                                  'rebase', 'origin/main'], cwd=str(repo.device), capture_output=True, text=True)
+        assert stopped.returncode != 0, "the rebase should stop on the conflict"
+        result = Harness(tmp_path, repo).updater.run()
+        assert result['core_outcome'] == 'blocked'
+        assert 'rebase is in progress' in result['core_message']
+        assert (repo.device / '.git' / 'rebase-merge').exists(), "a live rebase must be left alone"
+
+    def test_an_abandoned_rebase_is_cleared_and_the_update_runs(self, tmp_path):
+        """Found on a real device: a pull stopped mid-rebase a week earlier,
+        HEAD was later checked out to a branch, and the leftover rebase
+        directory would have blocked every automatic update forever."""
+        repo = Repo(tmp_path)
+        leftover = repo.device / '.git' / 'rebase-merge'
+        leftover.mkdir()
+        (leftover / 'head-name').write_text('refs/heads/main\n')
+        new = repo.publish()
+        result = Harness(tmp_path, repo).updater.run()
+        assert not leftover.exists()
+        assert result['core_outcome'] == 'verifying'
+        assert repo.head() == new
+
+    def test_a_merge_in_progress_blocks(self, tmp_path):
+        repo = Repo(tmp_path)
+        repo.publish()
+        (repo.device / '.git' / 'MERGE_HEAD').write_text(repo.head() + '\n')
+        result = Harness(tmp_path, repo).updater.run()
+        assert result['core_outcome'] == 'blocked'
+        assert 'merge is in progress' in result['core_message']
+
+    def test_low_disk_blocks(self, tmp_path):
+        repo = Repo(tmp_path)
+        repo.publish()
+        result = Harness(tmp_path, repo, disk_free=10 * 1024 * 1024).updater.run()
+        assert result['core_outcome'] == 'blocked'
+        assert 'disk space' in result['core_message']
+
+    def test_unreachable_origin_retries_tomorrow(self, tmp_path):
+        repo = Repo(tmp_path)
+        git(repo.device, 'remote', 'set-url', 'origin', str(tmp_path / 'nowhere'))
+        h = Harness(tmp_path, repo)
+        result = h.updater.run()
+        assert result['core_outcome'] == 'error'
+        assert h.state['next_due'] == NIGHT + au.RETRY_AFTER_FAILURE_SECONDS
+
+    def test_version_already_rolled_back_is_not_retried(self, tmp_path):
+        repo = Repo(tmp_path)
+        old = repo.head()
+        bad = repo.publish()
+        h = Harness(tmp_path, repo)
+        au.save_state({'rolled_back_head': bad}, h.updater.state_file)
+        result = h.updater.run()
+        assert result['core_outcome'] == 'up_to_date'
+        assert 'rolled back before' in result['core_message']
+        assert repo.head() == old and h.sudo == []
+
+
+# -- the update and its hand-off to the health check ---------------------------
+
+@needs_git
+class TestUpdateIsVerified:
+    def test_pull_hands_off_to_the_health_check(self, tmp_path):
+        repo = Repo(tmp_path)
+        old = repo.head()
+        new = repo.publish()
+        store = FakeStore(tmp_path / 'plugins', {'weather': '1.0.0'}, bump={'weather'})
+        h = Harness(tmp_path, repo, store=store)
+        result = h.updater.run()
+
+        assert result['core_outcome'] == 'verifying' and result['status'] == 'pending'
+        assert repo.head() == new
+        assert h.pending == {**h.pending, 'status': 'verifying', 'old_head': old, 'new_head': new,
+                             'display_was_active': True, 'dependency_failures': []}
+        assert not h.updater.request_file.exists(), "the request is consumed when the check starts"
+        assert h.sudo == [], "triggering the health check needs no privilege"
+        assert h.restarts == [], "restarts belong to the health check, not the web process"
+        assert store.updated_calls == [], "plugins must wait until the new code is verified"
+        assert h.state['plugins_pending'] is True
+        assert h.updater.verifier_copy.read_text() == au.VERIFIER_SOURCE.read_text()
+
+    def test_state_is_saved_before_the_health_check_restarts_this_process(self, tmp_path):
+        repo = Repo(tmp_path)
+        repo.publish()
+        h = Harness(tmp_path, repo)
+        h.updater.run()
+        assert h.state_at_handoff['last_result']['core_outcome'] == 'verifying'
+        assert h.state_at_handoff['plugins_pending'] is True
+
+    def test_dependency_failures_reach_the_health_check(self, tmp_path):
+        repo = Repo(tmp_path)
+        repo.publish()
+        h = Harness(tmp_path, repo,
+                    core_update=real_pull(repo.device, dependency_failures=['requirements.txt']))
+        h.updater.run()
+        assert h.pending['dependency_failures'] == ['requirements.txt']
+
+    def test_a_health_check_that_never_starts_means_the_update_is_undone(self, tmp_path):
+        repo = Repo(tmp_path)
+        old = repo.head()
+        repo.publish()
+        h = Harness(tmp_path, repo, pickup=False)
+        result = h.updater.run()
+        assert repo.head() == old
+        assert result['core_outcome'] == 'blocked'
+        assert 'did not start' in result['core_message']
+        assert h.pending is None and not h.updater.request_file.exists()
+        assert h.state['alert']
+
+    def test_failed_pull_retries_tomorrow(self, tmp_path):
+        repo = Repo(tmp_path)
+        old = repo.head()
+        repo.publish()
+        h = Harness(tmp_path, repo,
+                    core_update=lambda: {'status': 'error', 'message': 'Update failed: network'})
+        result = h.updater.run()
+        assert result['core_outcome'] == 'error'
+        assert repo.head() == old
+        assert h.state['next_due'] == NIGHT + au.RETRY_AFTER_FAILURE_SECONDS
+
+    def test_failed_pull_that_moved_head_is_rolled_back(self, tmp_path):
+        repo = Repo(tmp_path)
+        old = repo.head()
+        repo.publish()
+        pull = real_pull(repo.device)
+
+        def half_failed():
+            pull()
+            return {'status': 'error', 'message': 'Update failed: interrupted'}
+        result = Harness(tmp_path, repo, core_update=half_failed).updater.run()
+        assert repo.head() == old
+        assert 'rolled back' in result['core_message']
+
+
+# -- reporting the health check's outcome --------------------------------------
+
+@needs_git
+class TestHealthCheckOutcome:
+    def _after_update(self, tmp_path, **pending):
+        repo = Repo(tmp_path)
+        store = FakeStore(tmp_path / 'plugins', {'weather': '1.0.0'}, bump={'weather'})
+        h = Harness(tmp_path, repo, store=store)
+        au.save_state({'plugins_pending': True, 'next_due': NIGHT + au.UPDATE_INTERVAL_SECONDS,
+                       'last_result': {'core_outcome': 'verifying', 'status': 'pending',
+                                       'plugins_deferred': True}}, h.updater.state_file)
+        h.write_pending(old_head='a' * 40, new_head='b' * 40, created_at=NIGHT, **pending)
+        return h, store
+
+    def test_waits_while_the_check_runs(self, tmp_path):
+        h, store = self._after_update(tmp_path, status='verifying')
+        h.now = NIGHT + 60
+        assert h.updater.tick() is False
+        assert store.updated_calls == [] and h.pending
+
+    def test_success_then_runs_the_deferred_plugins(self, tmp_path):
+        h, store = self._after_update(tmp_path, status='success')
+        assert h.updater.tick() is True
+        result = h.state['last_result']
+        assert result['core_outcome'] == 'updated' and result['status'] == 'success'
+        assert result['plugins_updated'] == ['weather']
+        assert h.restarts == ['ledmatrix']
+        assert 'alert' not in h.state and h.pending is None
+
+    def test_rollback_alerts_and_remembers_the_bad_commit(self, tmp_path):
+        h, store = self._after_update(tmp_path, status='rolled_back',
+                                      reason='the web interface did not respond')
+        h.updater.tick()
+        assert 'rolled back' in h.state['alert']['message']
+        assert 'the web interface did not respond' in h.state['alert']['message']
+        assert h.state['rolled_back_head'] == 'b' * 40
+        assert store.updated_calls == ['weather'], "the old code is healthy; plugins may update"
+
+    def test_failed_rollback_alerts_and_skips_plugins(self, tmp_path):
+        h, store = self._after_update(tmp_path, status='rollback_failed',
+                                      reason='display down', detail='reset failed')
+        h.updater.tick()
+        assert f'git reset --hard {"a" * 40}' in h.state['alert']['message']
+        assert store.updated_calls == []
+        assert h.state['plugins_pending'] is False
+
+    def test_a_check_that_never_reports_back_alerts(self, tmp_path):
+        h, _ = self._after_update(tmp_path, status='verifying')
+        h.now = NIGHT + au.VERIFY_LOST_SECONDS + 1
+        h.updater.tick()
+        assert h.state['last_result']['core_outcome'] == 'lost'
+        assert 'never reported back' in h.state['alert']['message']
+
+    def test_dismissed_alert_stays_hidden_until_a_new_one(self, tmp_path):
+        h, _ = self._after_update(tmp_path, status='rolled_back', reason='x')
+        h.updater.tick()
+        alert_id = h.state['alert']['id']
+
+        def status():
+            return au.describe_status(h.config, state_file=h.updater.state_file,
+                                      pending_file=h.updater.pending_file,
+                                      setup_file=tmp_path / 'no-setup.json', helper=lambda: True)
+        assert status()['alert_id'] == alert_id
+        au.dismiss_alert(alert_id, h.updater.state_file)
+        assert status()['alert'] is None
+        state = h.state
+        state['alert'] = {'id': 'newer', 'message': 'again'}
+        au.save_state(state, h.updater.state_file)
+        assert status()['alert'] == 'again'
+
+
+def test_describe_status_reports_setup(tmp_path):
+    setup = tmp_path / 'setup.json'
+    setup.write_text(json.dumps({'status': 'failed', 'message': 'not root'}))
+    kwargs = dict(state={}, state_file=tmp_path / 's.json', pending_file=tmp_path / 'p.json',
+                  setup_file=setup)
+    on = au.describe_status(ON, helper=lambda: False, **kwargs)
+    assert on['verifier_installed'] is False
+    assert (on['setup_status'], on['setup_message']) == ('failed', 'not root')
+
+    def never(): raise AssertionError("systemctl asked while updates are off")
+    assert au.describe_status(OFF, helper=never, **kwargs)['verifier_installed'] is None
+
+
+# -- setting it up from the web UI ----------------------------------------------
+
+class TestSetupFromTheWebUI:
+    def _host(self, monkeypatch, ready=False, active=True, restart_ok=True):
+        restarts = []
+        monkeypatch.setattr(au, 'helper_ready', lambda: ready)
+        monkeypatch.setattr(au, '_service_active', lambda unit: active)
+        monkeypatch.setattr(au, 'restart_service', lambda unit: restarts.append(unit) or restart_ok)
+        return restarts
+
+    def test_switching_on_restarts_the_display_to_finish_setup(self, monkeypatch):
+        restarts = self._host(monkeypatch)
+        note = au.start_setup_if_needed(False, ON)
+        assert restarts == ['ledmatrix']
+        assert 'display is restarting' in note
+
+    @pytest.mark.parametrize('was_enabled, config, ready', [
+        (True, ON, False),   # already on: an unrelated save must not restart the display
+        (False, OFF, False),  # still off
+        (False, ON, True),   # already set up
+    ])
+    def test_nothing_to_do(self, monkeypatch, was_enabled, config, ready):
+        restarts = self._host(monkeypatch, ready=ready)
+        assert au.start_setup_if_needed(was_enabled, config) is None
+        assert restarts == []
+
+    def test_a_stopped_display_is_not_started(self, monkeypatch):
+        restarts = self._host(monkeypatch, active=False)
+        assert 'next time the display service starts' in au.start_setup_if_needed(False, ON)
+        assert restarts == []
+
+    def test_a_failed_restart_says_so(self, monkeypatch):
+        self._host(monkeypatch, restart_ok=False)
+        assert 'Could not restart' in au.start_setup_if_needed(False, ON)
+
+
+# -- plugins --------------------------------------------------------------------
+
+class TestPlugins:
+    def test_nothing_changed_restarts_nothing(self, tmp_path):
+        store = FakeStore(tmp_path / 'plugins', {'clock': '1.0.0'})
+        updater, restarts = stub_updater(tmp_path, store=store)
+        updater.run()
+        assert store.updated_calls == ['clock']
+        assert restarts == []
+
+    def test_plugin_update_restarts_display_only(self, tmp_path):
+        store = FakeStore(tmp_path / 'plugins', {'clock': '1.0.0', 'weather': '1.0.0'},
+                          bump={'weather'})
+        updater, restarts = stub_updater(tmp_path, store=store)
+        result = updater.run()
+        assert result['plugins_updated'] == ['weather']
+        assert restarts == ['ledmatrix']
+
+    def test_plugin_failure_alerts_but_keeps_weekly_cadence(self, tmp_path):
+        store = FakeStore(tmp_path / 'plugins', {'zip-only': '1.0.0'}, fail={'zip-only'})
+        updater, _ = stub_updater(tmp_path, store=store)
+        result = updater.run()
+        assert result['plugins_failed'] == ['zip-only'] and result['status'] == 'error'
+        state = au.load_state(updater.state_file)
+        assert 'zip-only' in state['alert']['message']
+        assert state['next_due'] == NIGHT + au.UPDATE_INTERVAL_SECONDS
+
+    def test_local_only_plugins_are_left_alone(self, tmp_path):
+        store = FakeStore(tmp_path / 'plugins', {'mine': '1.0.0'})
+        path = tmp_path / 'plugins' / 'mine' / 'manifest.json'
+        path.write_text(json.dumps({'id': 'mine', 'version': '1.0.0', 'local_only': True}))
+        updater, _ = stub_updater(tmp_path, store=store)
+        updater.run()
+        assert store.updated_calls == []
+
+
+def test_restart_service_skips_a_stopped_unit(monkeypatch):
+    calls = []
+
+    def run(args, **kwargs):
+        calls.append(args)
+        return MagicMock(stdout='inactive\n', returncode=3, stderr='')
+    monkeypatch.setattr(au.subprocess, 'run', run)
+    assert au.restart_service('ledmatrix') is False
+    assert calls == [['systemctl', 'is-active', 'ledmatrix']], (
+        "a display the user stopped must not be started by an update")
+
+
+def test_core_update_names_the_requirement_files_that_failed():
+    """The health check refuses code whose dependencies did not install, so
+    the failure has to arrive as data, not only as a sentence in the message."""
+    from web_interface.blueprints import api_v3 as pkg
+    from web_interface.blueprints.api_v3 import system
+
+    heads = iter(['aaa111\n', 'bbb222\n'])
+
+    def run(args, **kwargs):
+        if args[:2] == ['git', 'rev-parse'] and args[-1] == 'HEAD':
+            out = next(heads, 'bbb222\n')
+        elif args[:2] == ['git', 'diff']:
+            out = 'requirements.txt\n'
+        elif '@{u}' in args:
+            out = 'origin/main\n'
+        else:
+            out = ''
+        return subprocess.CompletedProcess(args, 0, stdout=out, stderr='')
+
+    pkg.api_v3.plugin_store_manager = None
+    failed_install = subprocess.CompletedProcess([], 1, stdout='', stderr='boom')
+    with patch.object(pkg.subprocess, 'run', run), \
+            patch.object(system, '_pip_install_requirements', return_value=failed_install):
+        result = system.perform_core_update()
+    assert result['status'] == 'success'
+    assert result['dependency_failures'] == ['requirements.txt']
+
+
+# -- web routes -------------------------------------------------------------------
+
+@pytest.fixture
+def api_client(monkeypatch):
+    from flask import Flask
+    from web_interface.blueprints.api_v3 import api_v3
+    app = Flask(__name__)
+    app.register_blueprint(api_v3, url_prefix='/api/v3')
+    cm = MagicMock()
+    cm.load_config.return_value = {'timezone': 'UTC', 'auto_update': {'enabled': True}}
+    cm.get_raw_file_content.return_value = {}
+    cm.save_config_atomic.return_value = MagicMock(status=MagicMock(value='success'), message=None)
+    api_v3.config_manager = cm
+    api_v3.plugin_manager = MagicMock(plugins={})
+    # Never restart a real display from a test run.
+    setup_calls = []
+    monkeypatch.setattr(au, 'start_setup_if_needed',
+                        lambda was_enabled, config: setup_calls.append(was_enabled) or None)
+    return app.test_client(), cm, setup_calls
+
+
+class TestStatusRoutes:
+    def test_status_carries_the_alert(self, api_client, monkeypatch):
+        client, _, _ = api_client
+        monkeypatch.setattr(au, 'describe_status', lambda config: {'alert': 'rolled back', 'alert_id': '7'})
+        data = client.get('/api/v3/system/auto-update').get_json()['data']
+        assert data == {'alert': 'rolled back', 'alert_id': '7'}
+
+    @pytest.mark.parametrize('body', [{}, [1], 'x', 5])
+    def test_dismiss_needs_an_id_in_a_json_object(self, api_client, body):
+        client, _, _ = api_client
+        assert client.post('/api/v3/system/auto-update/dismiss', json=body).status_code == 400
+
+    def test_dismiss(self, api_client, monkeypatch):
+        client, _, _ = api_client
+        calls = []
+        monkeypatch.setattr(au, 'dismiss_alert', calls.append)
+        assert client.post('/api/v3/system/auto-update/dismiss', json={'alert_id': '7'}).status_code == 200
+        assert calls == ['7']
+
+
+class TestSettingsSave:
+    def _saved(self, cm):
+        return cm.save_config_atomic.call_args[0][0]
+
+    def test_checked_toggle_saves_enabled(self, api_client):
+        client, cm, setup_calls = api_client
+        cm.load_config.return_value = {'timezone': 'UTC'}
+        resp = client.post('/api/v3/config/main', json={'timezone': 'UTC', 'auto_update_enabled': 'true'})
+        assert resp.status_code == 200
+        saved = self._saved(cm)
+        assert saved['auto_update'] == {'enabled': True}
+        assert 'auto_update_enabled' not in saved, "the form field must not leak into config.json"
+        assert setup_calls == [False], "setup is told the toggle was previously off"
+
+    def test_unchecked_toggle_on_general_save_disables(self, api_client):
+        client, cm, setup_calls = api_client
+        resp = client.post('/api/v3/config/main', json={'timezone': 'UTC'})
+        assert resp.status_code == 200
+        assert self._saved(cm)['auto_update'] == {'enabled': False}
+        assert setup_calls == [True]
+
+    def test_setup_note_reaches_the_user(self, api_client, monkeypatch):
+        client, cm, _ = api_client
+        cm.load_config.return_value = {'timezone': 'UTC'}
+        monkeypatch.setattr(au, 'start_setup_if_needed',
+                            lambda was_enabled, config: 'Finishing automatic update setup: the display is restarting.')
+        body = client.post('/api/v3/config/main',
+                           json={'timezone': 'UTC', 'auto_update_enabled': 'true'}).get_json()
+        assert 'the display is restarting' in body['message']

test/test_auto_update_setup.py

@@ -0,0 +1,214 @@
+"""Installing the automatic-update health check from the display service.
+
+src/auto_update_setup.py is how a user who never opens a terminal gets updates
+with a safety net: it runs as root inside the display service and writes
+systemd units. So it has to install exactly the right thing when asked, do
+nothing when not asked, refuse templates that would run as anyone but the web
+user, and say why whenever it could not finish.
+"""
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT))
+
+from src import auto_update_setup as aus  # noqa: E402
+
+ON = {'auto_update': {'enabled': True}}
+
+
+class FakeSystemctl:
+    def __init__(self, fail=(), activates=True):
+        self.calls = []
+        self.fail = set(fail)
+        self.activates = activates
+        self.active = False
+
+    def __call__(self, args, **kwargs):
+        assert args[0] == 'systemctl', args
+        self.calls.append(args[1:])
+        verb = args[1]
+        if verb == 'is-active':
+            return subprocess.CompletedProcess(args, 0 if self.active else 3,
+                                               stdout='active\n' if self.active else 'inactive\n', stderr='')
+        if verb in self.fail:
+            return subprocess.CompletedProcess(args, 1, stdout='', stderr=f'{verb} refused')
+        if verb in ('restart', 'enable') and self.activates and (verb == 'restart' or '--now' in args):
+            self.active = True
+        return subprocess.CompletedProcess(args, 0, stdout='', stderr='')
+
+
+def project(tmp_path, user='hdpi', workdir=None, name='LEDMatrix'):
+    root = tmp_path / name
+    (root / 'systemd').mkdir(parents=True)
+    for name in aus.UNITS:
+        shutil.copy(ROOT / 'systemd' / name, root / 'systemd' / name)
+    etc = tmp_path / 'etc'
+    etc.mkdir()
+    (etc / aus.WEB_UNIT).write_text(
+        f'[Service]\nUser={user}\nWorkingDirectory={workdir or root}\n', encoding='utf-8')
+    return root, etc
+
+
+def setup(root, etc, systemctl, root_user=True):
+    return aus.UpdateHelperSetup(project_root=root, systemd_dir=etc, run=systemctl,
+                                 is_root=lambda: root_user,
+                                 lookup_ids=lambda user: None if user == 'ghost' else (1000, 1000),
+                                 clock=lambda: 1234.0)
+
+
+def result(root):
+    return json.loads((root / aus.RESULT_REL).read_text())
+
+
+def test_does_nothing_while_updates_are_off(tmp_path):
+    root, etc = project(tmp_path)
+    systemctl = FakeSystemctl()
+    assert setup(root, etc, systemctl).ensure({'auto_update': {'enabled': False}}) is None
+    assert systemctl.calls == []
+    assert not (etc / aus.SERVICE_UNIT).exists()
+    assert not (root / aus.RESULT_REL).exists()
+
+
+def test_installs_both_units_for_the_web_user(tmp_path):
+    root, etc = project(tmp_path)
+    systemctl = FakeSystemctl()
+    out = setup(root, etc, systemctl).ensure(ON)
+
+    assert out['status'] == 'installed' and result(root)['status'] == 'installed'
+    service = (etc / aus.SERVICE_UNIT).read_text()
+    assert 'User=hdpi' in service
+    assert f'ExecStart=/usr/bin/python3 "{root}/data/auto_update_verifier.py" "{root}"' in service
+    assert f'PathExists={root}/data/auto_update_verify.request' in (etc / aus.PATH_UNIT).read_text()
+    assert '__' not in service
+    assert ['daemon-reload'] in systemctl.calls
+    assert ['enable', aus.PATH_UNIT] in systemctl.calls
+    assert systemctl.active
+
+
+def test_second_start_changes_nothing(tmp_path):
+    root, etc = project(tmp_path)
+    systemctl = FakeSystemctl()
+    setup(root, etc, systemctl).ensure(ON)
+    first = result(root)
+    systemctl.calls.clear()
+    setup(root, etc, systemctl).ensure(ON)
+    assert systemctl.calls == [['is-active', aus.PATH_UNIT], ['is-active', aus.PATH_UNIT]]
+    assert result(root) == first, "an unchanged setup must not rewrite its result every boot"
+
+
+def test_a_changed_template_is_reinstalled(tmp_path):
+    root, etc = project(tmp_path)
+    systemctl = FakeSystemctl()
+    setup(root, etc, systemctl).ensure(ON)
+    template = root / 'systemd' / aus.SERVICE_UNIT
+    template.write_text(template.read_text() + '\n# newer\n')
+    systemctl.calls.clear()
+    assert setup(root, etc, systemctl).ensure(ON)['message'] == 'Installed the update health check.'
+    assert (etc / aus.SERVICE_UNIT).read_text().endswith('# newer\n')
+    assert ['daemon-reload'] in systemctl.calls
+
+
+def test_a_template_that_would_not_run_as_the_web_user_is_refused(tmp_path):
+    root, etc = project(tmp_path)
+    template = root / 'systemd' / aus.SERVICE_UNIT
+    template.write_text(template.read_text().replace('User=__USER__', 'User=root'))
+    systemctl = FakeSystemctl()
+    out = setup(root, etc, systemctl).ensure(ON)
+    assert out['status'] == 'failed' and 'refusing' in out['message']
+    assert not (etc / aus.SERVICE_UNIT).exists()
+    assert systemctl.calls == []
+
+
+def test_a_path_unit_that_starts_something_else_is_refused(tmp_path):
+    root, etc = project(tmp_path)
+    template = root / 'systemd' / aus.PATH_UNIT
+    template.write_text(template.read_text().replace('Unit=ledmatrix-update-verify.service', 'Unit=other.service'))
+    out = setup(root, etc, FakeSystemctl()).ensure(ON)
+    assert out['status'] == 'failed' and not (etc / aus.PATH_UNIT).exists()
+
+
+@pytest.mark.parametrize('case, expected', [
+    ('not_root', 'not running as root'),
+    ('no_web_unit', 'not installed'),
+    ('other_folder', 'runs from'),
+    ('bad_user', 'not a usable account'),
+])
+def test_reports_why_it_could_not_install(tmp_path, case, expected):
+    root, etc = project(tmp_path, user='ghost' if case == 'bad_user' else 'hdpi',
+                        workdir=tmp_path / 'elsewhere' if case == 'other_folder' else None)
+    if case == 'no_web_unit':
+        (etc / aus.WEB_UNIT).unlink()
+    out = setup(root, etc, FakeSystemctl(), root_user=case != 'not_root').ensure(ON)
+    assert out['status'] == 'failed' and expected in out['message']
+    assert result(root)['message'] == out['message']
+    assert not (etc / aus.SERVICE_UNIT).exists()
+
+
+def test_a_path_unit_that_will_not_start_is_a_failure(tmp_path):
+    root, etc = project(tmp_path)
+    out = setup(root, etc, FakeSystemctl(activates=False)).ensure(ON)
+    assert out['status'] == 'failed' and 'did not start' in out['message']
+
+
+def test_systemctl_errors_are_reported(tmp_path):
+    root, etc = project(tmp_path)
+    out = setup(root, etc, FakeSystemctl(fail={'daemon-reload'})).ensure(ON)
+    assert out['status'] == 'failed' and 'daemon-reload refused' in out['message']
+
+
+def test_not_a_systemd_host_is_left_alone(tmp_path):
+    root, _ = project(tmp_path)
+    systemctl = FakeSystemctl()
+    assert setup(root, tmp_path / 'no-etc', systemctl).ensure(ON) is None
+    assert systemctl.calls == []
+
+
+def test_a_folder_with_spaces_is_quoted_in_the_commands(tmp_path):
+    root, etc = project(tmp_path, name='LED Matrix')
+    assert setup(root, etc, FakeSystemctl()).ensure(ON)['status'] == 'installed'
+    service = (etc / aus.SERVICE_UNIT).read_text()
+    assert f'ExecStartPre=/bin/rm -f "{root}/data/auto_update_verify.request"' in service
+    assert f'ExecStart=/usr/bin/python3 "{root}/data/auto_update_verifier.py" "{root}"' in service
+
+
+def test_a_folder_name_systemd_would_reinterpret_is_refused(tmp_path):
+    root, etc = project(tmp_path, name='LED%Matrix')
+    systemctl = FakeSystemctl()
+    out = setup(root, etc, systemctl).ensure(ON)
+    assert out['status'] == 'failed' and 'systemd cannot use' in out['message']
+    assert not (etc / aus.SERVICE_UNIT).exists() and systemctl.calls == []
+
+
+def test_installer_sets_the_toggle_without_a_half_written_config(tmp_path):
+    """first_time_install.sh may run while the display service watches
+    config.json; the file must be replaced whole, never truncated in place."""
+    import re
+    text = (ROOT / 'first_time_install.sh').read_text(encoding='utf-8').replace('\r\n', '\n')
+    script = next(s for s in re.findall(r"<<'PY'\n(.*?)\nPY\n", text, re.S) if 'auto_update' in s)
+    assert 'os.replace(' in script
+    config = tmp_path / 'config.json'
+    config.write_text(json.dumps({'timezone': 'UTC', 'auto_update': {'enabled': False}}))
+    run = subprocess.run([sys.executable, '-', str(config), '1'], input=script, text=True,
+                         capture_output=True)
+    assert run.returncode == 0, run.stderr
+    assert json.loads(config.read_text()) == {'timezone': 'UTC', 'auto_update': {'enabled': True}}
+    assert [p.name for p in tmp_path.iterdir()] == ['config.json'], "a temp file was left behind"
+
+
+def test_the_result_is_kept_when_it_cannot_be_given_to_the_web_user(tmp_path, monkeypatch):
+    """Caught by CI, which runs as a non-root Linux user: chown needs root, and
+    a failed chown used to discard the result, so the General tab never
+    learned whether setup worked."""
+    def refuse(*args):
+        raise PermissionError('Operation not permitted')
+    monkeypatch.setattr(aus.os, 'chown', refuse, raising=False)
+    root, etc = project(tmp_path)
+    out = setup(root, etc, FakeSystemctl()).ensure(ON)
+    assert out['status'] == 'installed'
+    assert result(root) == out

test/test_auto_update_verify.py

@@ -0,0 +1,248 @@
+"""The automatic update's health check and rollback (scripts/utils/auto_update_verify.py).
+
+This is what stands between an unattended update and a device that no longer
+works, so each way an update can fail is exercised against a real git repo:
+the new commit is checked out, the services are "restarted", and whether they
+come up healthy depends on which commit they were restarted onto. Only
+systemd, sudo and the HTTP check are faked.
+"""
+import importlib.util
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT))
+
+_spec = importlib.util.spec_from_file_location(
+    'auto_update_verify', ROOT / 'scripts' / 'utils' / 'auto_update_verify.py')
+av = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(av)
+
+pytestmark = pytest.mark.skipif(shutil.which('git') is None, reason='git not installed')
+
+
+def git(cwd, *args):
+    result = subprocess.run(['git', '-c', 'user.name=t', '-c', 'user.email=t@example.com', *args],
+                            cwd=str(cwd), capture_output=True, text=True)
+    assert result.returncode == 0, result.stderr
+    return result.stdout.strip()
+
+
+def done(args, stdout='', rc=0):
+    return subprocess.CompletedProcess(args, rc, stdout=stdout, stderr='' if rc == 0 else 'failed')
+
+
+def updated_repo(tmp_path, new_requirements=False):
+    """A checkout on a new commit, with the commit it came from."""
+    repo = tmp_path / 'LEDMatrix'
+    repo.mkdir()
+    git(repo, 'init', '-q', '-b', 'main')
+    (repo / 'app.py').write_text('v = 1\n')
+    (repo / 'requirements.txt').write_text('requests\n')
+    git(repo, 'add', '.')
+    git(repo, 'commit', '-qm', 'old')
+    old = git(repo, 'rev-parse', 'HEAD')
+    (repo / 'app.py').write_text('v = 2\n')
+    if new_requirements:
+        (repo / 'requirements.txt').write_text('requests\nnewthing\n')
+    git(repo, 'commit', '-qam', 'new')
+    return repo, old, git(repo, 'rev-parse', 'HEAD')
+
+
+class FakeHost:
+    """systemd, sudo and the web interface.
+
+    Services run whatever commit was checked out when they were last
+    restarted; ``failure`` says how they misbehave on the new commit
+    ("display_down", "web_down", "crash_loop") or on any commit ("always").
+    """
+
+    def __init__(self, repo, bad_head, failure=None, pip_ok=True, restart_failures=0, count_readable=True):
+        self.repo, self.bad_head, self.failure, self.pip_ok = repo, bad_head, failure, pip_ok
+        self.restart_failures = restart_failures  # how many restart commands fail, first to last
+        self.count_readable = count_readable
+        self.running_head = None  # not restarted yet: still the old, healthy code
+        self.restarts = []        # (unit, commit it was restarted onto)
+        self.pip_installs = []
+        self.now = 0.0
+        self.nrestarts = 0
+
+    def broken(self, kind):
+        if self.running_head is None:
+            return False
+        return self.failure == 'always' or (self.running_head == self.bad_head and self.failure == kind)
+
+    def run(self, args, **kwargs):
+        if args[0] == 'git':
+            return subprocess.run(args, **kwargs)
+        if args[:2] == ['systemctl', 'is-active']:
+            return done(args, 'failed\n' if self.broken('display_down') else 'active\n')
+        if args[:2] == ['systemctl', 'show']:
+            if not self.count_readable:
+                return done(args, rc=1)
+            if self.broken('crash_loop'):
+                self.nrestarts += 1
+            return done(args, f'{self.nrestarts}\n')
+        if args[0] == 'sudo' and any(a.endswith('safe_pip_install.sh') for a in args):
+            self.pip_installs.append(args[-1])
+            return done(args, rc=0 if self.pip_ok else 1)
+        if args[:4] == ['sudo', '-n', 'systemctl', 'restart']:
+            if self.restart_failures:
+                self.restart_failures -= 1
+                return done(args, rc=1)  # the old process keeps running
+            self.running_head = git(self.repo, 'rev-parse', 'HEAD')
+            self.restarts.append((args[4], self.running_head))
+            return done(args)
+        raise AssertionError(f'unexpected command: {args}')
+
+    def web_responds(self):
+        return not self.broken('web_down')
+
+    def sleep(self, seconds):
+        self.now += seconds
+
+    def verifier(self):
+        return av.Verifier(self.repo, run=self.run, sleep=self.sleep, clock=lambda: self.now,
+                           web_responds=self.web_responds, log=lambda msg: None)
+
+
+def check(tmp_path, failure=None, new_requirements=False, pip_ok=True, restart_failures=0,
+          count_readable=True, **pending):
+    repo, old, new = updated_repo(tmp_path, new_requirements)
+    fields = {'status': 'pending', 'old_head': old, 'new_head': new,
+              'display_was_active': True, 'dependency_failures': []}
+    fields.update(pending)
+    av.write_pending(av.pending_path(repo), fields)
+    host = FakeHost(repo, new, failure, pip_ok, restart_failures, count_readable)
+    code = host.verifier().verify()
+    result = av.read_pending(av.pending_path(repo))
+    return code, result, host, git(repo, 'rev-parse', 'HEAD'), old, new
+
+
+def test_a_healthy_update_is_kept(tmp_path):
+    code, result, host, head, old, new = check(tmp_path)
+    assert code == 0 and result['status'] == 'success'
+    assert head == new
+    assert host.restarts == [('ledmatrix.service', new), ('ledmatrix-web.service', new)]
+
+
+@pytest.mark.parametrize('failure, reason', [
+    ('display_down', 'the display service did not stay running'),
+    ('web_down', 'the web interface did not respond'),
+    ('crash_loop', 'the display service kept restarting'),
+])
+def test_an_unhealthy_update_is_rolled_back(tmp_path, failure, reason):
+    code, result, host, head, old, new = check(tmp_path, failure)
+    assert code == 0
+    assert result['status'] == 'rolled_back' and result['reason'] == reason
+    assert head == old
+    assert host.restarts[-2:] == [('ledmatrix.service', old), ('ledmatrix-web.service', old)]
+
+
+def test_a_stopped_display_is_not_started(tmp_path):
+    code, result, host, head, old, new = check(tmp_path, display_was_active=False)
+    assert result['status'] == 'success'
+    assert [unit for unit, _ in host.restarts] == ['ledmatrix-web.service']
+
+
+def test_failed_dependencies_roll_back_before_anything_restarts_onto_them(tmp_path):
+    code, result, host, head, old, new = check(tmp_path, dependency_failures=['requirements.txt'])
+    assert result['status'] == 'rolled_back'
+    assert 'requirements.txt' in result['reason']
+    assert head == old
+    assert all(commit == old for _, commit in host.restarts), host.restarts
+
+
+def test_rollback_reinstalls_the_previous_dependencies(tmp_path):
+    code, result, host, head, old, new = check(tmp_path, 'display_down', new_requirements=True)
+    assert result['status'] == 'rolled_back' and result['detail'] is None
+    assert host.pip_installs == [str(tmp_path / 'LEDMatrix' / 'requirements.txt')]
+
+
+def test_a_failed_dependency_reinstall_is_reported(tmp_path):
+    code, result, host, head, old, new = check(tmp_path, 'display_down', new_requirements=True,
+                                               pip_ok=False)
+    assert result['status'] == 'rolled_back' and head == old
+    assert 'Install Base Requirements' in result['detail']
+
+
+def test_still_broken_after_rolling_back_is_rollback_failed(tmp_path):
+    code, result, host, head, old, new = check(tmp_path, 'always')
+    assert code == 1 and result['status'] == 'rollback_failed'
+    assert 'still unhealthy after rolling back' in result['detail']
+
+
+def test_a_failed_restart_is_not_mistaken_for_a_healthy_update(tmp_path):
+    """When the restart command itself fails the old process keeps answering,
+    so checking it would pass an update that never started."""
+    code, result, host, head, old, new = check(tmp_path, restart_failures=1)
+    assert result['status'] == 'rolled_back'
+    assert result['reason'] == 'restarting the services failed'
+    assert head == old
+
+
+def test_restarts_that_keep_failing_after_rollback_are_rollback_failed(tmp_path):
+    code, result, host, head, old, new = check(tmp_path, restart_failures=100)
+    assert code == 1 and result['status'] == 'rollback_failed'
+    assert 'restarting the services failed' in result['detail']
+
+
+def test_an_unreadable_restart_count_is_never_called_stable(tmp_path):
+    """With no restart count a crash loop looks healthy between attempts."""
+    code, result, host, head, old, new = check(tmp_path, count_readable=False)
+    assert result['status'] != 'success'
+    assert 'restart count could not be read' in result['reason']
+
+
+def test_nothing_pending_does_nothing(tmp_path):
+    repo, _, _ = updated_repo(tmp_path)
+    host = FakeHost(repo, None)
+    assert host.verifier().verify() == 0
+    assert host.restarts == []
+
+
+def test_a_crash_is_recorded_not_left_as_running(tmp_path, monkeypatch):
+    repo, old, new = updated_repo(tmp_path)
+    av.write_pending(av.pending_path(repo), {'status': 'pending', 'old_head': old, 'new_head': new})
+
+    def boom(self):
+        raise RuntimeError('boom')
+    monkeypatch.setattr(av.Verifier, 'verify', boom)
+    assert av.main(['auto_update_verify.py', str(repo)]) == 1
+    result = av.read_pending(av.pending_path(repo))
+    assert result['status'] == 'rollback_failed' and result['detail'] == 'boom'
+
+
+def test_units_installers_and_updater_agree():
+    """The request file, the copied verifier, the unit names and the places
+    that install them must all line up, or the health check silently never
+    starts on real devices -- and code updates stay paused."""
+    from web_interface import auto_update as au
+    from src import auto_update_setup as aus
+    from src.startup_validator import StartupValidator
+
+    service = (ROOT / 'systemd' / aus.SERVICE_UNIT).read_text(encoding='utf-8')
+    path = (ROOT / 'systemd' / aus.PATH_UNIT).read_text(encoding='utf-8')
+    request = f'__PROJECT_ROOT_DIR__/{au.REQUEST_REL.as_posix()}'
+    assert f'PathExists={request}' in path
+    assert f'Unit={aus.SERVICE_UNIT}' in path
+    assert f'ExecStartPre=/bin/rm -f "{request}"' in service, "the request must be consumed or the path unit re-fires"
+    assert f'"__PROJECT_ROOT_DIR__/{au.VERIFIER_COPY_REL.as_posix()}" "__PROJECT_ROOT_DIR__"' in service
+    assert au.PENDING_REL.name == av.PENDING_NAME
+    assert au.PATH_UNIT == aus.PATH_UNIT and au.SETUP_RESULT_REL == aus.RESULT_REL
+
+    for installer in ('scripts/install/install_web_service.sh', 'scripts/install/install_service.sh'):
+        text = (ROOT / installer).read_text(encoding='utf-8')
+        assert 'ledmatrix-update-verify.service ledmatrix-update-verify.path' in text, installer
+        assert 'enable --now ledmatrix-update-verify.path' in text, installer
+    for unit in aus.UNITS:
+        assert (f'systemd/{unit}', f'/etc/systemd/system/{unit}') in StartupValidator._UNITS
+
+    # Triggering takes no privilege any more; no sudoers rule should linger.
+    for sudoers in ('scripts/install/configure_web_sudo.sh', 'first_time_install.sh'):
+        assert not re.search(r'NOPASSWD:.*update-verify', (ROOT / sudoers).read_text(encoding='utf-8')), sudoers