test: fix the emulator port collision behind the intermittent suite failures (#562)

* chore: stop tests and rigs writing to shared paths

Two shared-state problems, both of which show up as a permanently dirty
checkout or an unreproducible test failure.

test_display_dirty_tracking.py builds a real DisplayManager, whose
_snapshot_path defaults to the fixed /tmp/led_matrix_preview.png that the web
UI reads. Every pytest process on the machine shares that one file, so two
concurrent runs -- CI shards, a second worktree, an agent running the suite
alongside -- overwrite each other's snapshot and the mtime assertions stop
meaning anything. The module fixture now points it at a session-unique temp
path; the individual tests that care still override it further.

To be clear about what this does and does not fix: this is a real shared-path
hazard, but it is NOT the cause of the intermittent 15-test failure in that
module. That turned out to be the emulator's fixed TCP port, fixed in the
follow-up commit. This change stands on its own merits.

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`. Only
data/.gitkeep is tracked under data/, so the negation keeps it.

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

* test: stop the emulator binding a fixed port, so concurrent runs can't collide

This is the cause of the intermittent full-suite failures we have been chasing:
runs of identical code landing anywhere between 100 and 130 failures, while
every implicated test passed in isolation.

Six test modules set EMULATOR=true and build a real DisplayManager. The repo's
emulator_config.json selects the "browser" adapter, which binds 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 catches it and
falls back to `self.matrix = None`, and every test that subsequently touches the
matrix dies with

    AttributeError: 'NoneType' object has no attribute 'SwapOnVSync'

which names neither a port nor a socket, and points at the wrong file entirely.
Because test_display_dirty_tracking's fixture is module-scoped, all 15 of its
matrix-touching tests fail together or not at all -- the 15-test swing that made
the totals look random.

Demonstrated rather than assumed. Holding 0.0.0.0:8888 from a separate process
and running test_display_dirty_tracking.py:

    without this change    15 failed, 6 passed
    with this change       21 passed

The "raw" adapter renders in memory and binds nothing. Only display_adapter is
overridden, in a throwaway config written per pytest process; the repo's
emulator_config.json is untouched and `run.py -e` still opens the browser
preview on 8888. Nothing in the suite referenced the adapter, and the tests
wrap SwapOnVSync on the matrix object itself, so they are indifferent to what
sits underneath. allow_adapter_fallback is forced off -- falling back would
land us on the browser adapter and its fixed port, which is the whole problem.

CONFIG_PATH is a bare relative filename resolved against the CWD, so it is set
to an absolute path: the previous behaviour depended on where pytest was invoked
from, and silently wrote a default config into whatever directory that was.

Verified no regressions: full suite on this branch and with origin/main's
versions of the touched files, same machine, back to back -- 115 failed /
4347 passed on both sides, zero failures unique to either. That 115 is the
pre-existing Windows-environment baseline (POSIX file modes, fcntl, shell
scripts, Linux-only binaries); CI on Linux remains authoritative.

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

* chore: mark the shell entry points executable

Eleven scripts shipped as 100644, so `./scripts/install/configure_web_sudo.sh`
fails with "Permission denied" and only works if you know to prefix `bash`.
That one matters most: the web UI's own error hint, added in #560, tells users
to run exactly that path when a system action fails for want of passwordless
sudo, and following that instruction verbatim did not work.

All eleven carry a shebang and are invoked directly, never sourced. The two
sourced libraries -- lib_lowmem.sh and lib_systemd_render.sh -- are deliberately
left non-executable, which is what distinguishes a library from an entry point.

Mode bits only, no content: 11 files changed, 0 insertions, 0 deletions. Applied
with `git update-index --chmod=+x` because this checkout is on Windows, where
core.fileMode is off and the working-tree bit is not tracked.

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

---------

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

.gitignore

@@ -49,3 +49,40 @@ config/backups/
 # Starlark apps runtime storage (installed .star files and cached renders)
 /starlark-apps/
 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

docs/REST_API_REFERENCE.md

@@ -33,7 +33,7 @@ All endpoints return JSON responses with a standard format:
 
 > The API blueprint is mounted at `/api/v3` (`web_interface/app.py:199`).
 > SSE stream endpoints (`/api/v3/stream/*`) are defined directly on the
-> Flask app at `app.py:799-809`. There are 94 routes total — see
+> Flask app at `app.py:799-809`. There are 111 routes total — see
 > `web_interface/blueprints/api_v3.py` for the canonical list.
 
 ---
@@ -223,6 +223,56 @@ Get the current display state and preview image.
 }
 ```
 
+### List Display Modes
+
+**GET** `/api/v3/display/modes`
+
+Every display mode that can be requested on-demand, with the plugin that owns
+it. This is the list the force-display dialog offers.
+
+Send the reported `plugin_id` alongside `mode` when starting an on-demand
+display: `/display/on-demand/start` falls back to `find_plugin_for_mode` when
+`plugin_id` is omitted, and that lookup only sees modes declared in a static
+manifest — a plugin whose modes are generated (each installed Starlark app is
+one) returns 404 there.
+
+Triggers plugin discovery, which is otherwise lazy — so a caller that never
+opens the dashboard still gets the full list.
+
+**Query Parameters**:
+- `include_disabled` (optional): `1` to include modes belonging to disabled
+  plugins. They are still valid on-demand targets — the controller enables the
+  plugin for the duration of the request — and are reported with
+  `"enabled": false`.
+
+**Response**:
+```json
+{
+  "status": "success",
+  "data": {
+    "modes": [
+      {
+        "mode": "nfl_live",
+        "plugin_id": "football-scoreboard",
+        "plugin_name": "Football Scoreboard",
+        "name": "nfl_live",
+        "enabled": true
+      },
+      {
+        "mode": "clock-simple",
+        "plugin_id": "clock-simple",
+        "plugin_name": "Simple Clock",
+        "name": "Simple Clock",
+        "enabled": true
+      }
+    ]
+  }
+}
+```
+
+`name` is a label for a dropdown: a single-mode plugin's own name, or the raw
+mode string for a multi-mode plugin, since there is no per-mode name anywhere.
+
 ### On-Demand Display Status
 
 **GET** `/api/v3/display/on-demand/status`

docs/SCROLL_PERFORMANCE.md

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

integrations/mqtt_bridge/.gitignore

@@ -0,0 +1 @@
+bridge_config.json

integrations/mqtt_bridge/README.md

@@ -0,0 +1,118 @@
+# Home Assistant MQTT Bridge
+
+Control the matrix from Home Assistant: force any plugin or mode on demand,
+turn the display on and off, and set brightness — as real HA entities, not
+hand-written `mqtt.publish` calls.
+
+The bridge owns no display logic. It subscribes to one command topic and
+turns each message into a call against the same `api_v3` routes the web UI
+uses, so behaviour lives in one place. It talks to the API over HTTP only —
+no filesystem access — so it can run on the Pi or anywhere that can reach
+the web interface.
+
+## What appears in Home Assistant
+
+On connect the bridge publishes [MQTT Discovery](https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery)
+config, so the matrix shows up under **Settings → Devices & Services → MQTT**
+with no YAML:
+
+| Entity | Does |
+|---|---|
+| `select.ledmatrix_display_mode` | Every mode across enabled plugins. Choosing one force-displays it. |
+| `button.ledmatrix_stop_display` | Back to normal rotation. |
+| `switch.ledmatrix_power` | Starts/stops the display service. |
+| `number.ledmatrix_brightness` | 0–100. |
+
+State is read back from the API every 30 seconds, so the entities also track
+changes made from the web UI or an on-demand window expiring on its own.
+All four share an availability topic that is the bridge's MQTT last will:
+if the bridge dies, HA greys the controls out rather than leaving them
+looking live but inert.
+
+## Raw commands
+
+For anything the entities do not cover, publish JSON to the command topic
+(`ledmatrix/command` by default):
+
+```jsonc
+// Force a mode. plugin_id is optional — the bridge fills it in from
+// /api/v3/display/modes.
+{"action": "display", "mode": "nfl_live"}
+
+// duration is seconds; pinned holds this one mode instead of rotating
+// through every mode the plugin owns. Pin Starlark apps, where each mode
+// is an unrelated widget; leave a sports plugin unpinned so live/recent/
+// upcoming still cycle.
+{"action": "display", "plugin_id": "starlark-apps", "mode": "aquarium",
+ "duration": 300, "pinned": true}
+
+{"action": "stop_display"}
+{"action": "power", "state": "on"}
+{"action": "brightness", "value": 75}
+
+// Re-read the mode list and re-publish discovery, after installing a plugin
+{"action": "refresh"}
+```
+
+Every command publishes its outcome to `<command_topic>/status`, and current
+state to `<command_topic>/state`.
+
+## Requirements
+
+- A LEDMatrix install with its web interface reachable (default `http://localhost:5000`)
+- An MQTT broker that Home Assistant is also connected to
+- Python 3 with `paho-mqtt` 2.x and `requests`
+
+## Install
+
+```bash
+sudo ./scripts/install/install_mqtt_bridge.sh
+```
+
+That copies `bridge_config.example.json` to `bridge_config.json` on first
+run, installs the dependencies, and enables `ledmatrix-mqtt-bridge.service`.
+Edit the config with your broker details and re-run it.
+
+```json
+{
+  "mqtt_host": "192.168.1.10",
+  "mqtt_port": 8883,
+  "mqtt_username": "ledmatrix",
+  "mqtt_password": null,
+  "mqtt_topic": "ledmatrix/command",
+  "mqtt_tls": true,
+  "ledmatrix_api_base": "http://localhost:5000"
+}
+```
+
+**TLS is on by default.** Without it the broker password and every display
+command cross the network in cleartext. If your broker only listens on plain
+1883 — which the Mosquitto add-on does out of the box — set `"mqtt_tls": false`
+and `"mqtt_port": 1883`. The bridge logs a warning at startup when a password
+is configured without TLS.
+
+`bridge_config.json` is gitignored. Any key can also be supplied through the
+environment as `LEDMATRIX_MQTT_<KEY>` (`LEDMATRIX_MQTT_MQTT_PASSWORD`, say),
+which keeps a broker password out of a file on disk — put it in a systemd
+drop-in with `Environment=` or `EnvironmentFile=` instead.
+
+Set `mqtt_tls: true` for a broker with TLS. `mqtt_tls_insecure` skips
+certificate verification and exists only for a self-signed broker on a
+trusted LAN; it logs a warning when used.
+
+To run it in the foreground while setting things up:
+
+```bash
+python3 integrations/mqtt_bridge/ledmatrix_mqtt_bridge.py --config integrations/mqtt_bridge/bridge_config.json
+```
+
+## Notes
+
+- Only one thing can be on-demand at a time — the same constraint the web UI has.
+- Forcing a mode restarts the display service, so the panel blanks for a moment.
+- The mode list comes from `/api/v3/display/modes`, which triggers plugin
+  discovery itself. Discovery is lazy and normally happens because somebody
+  opened the dashboard; without that endpoint a bridge that never does would
+  see an empty list.
+- Brightness writes `display.hardware.brightness` through `/api/v3/config/main`.
+  The display service picks it up on its next restart, not instantly.

integrations/mqtt_bridge/bridge_config.example.json

@@ -0,0 +1,13 @@
+{
+  "mqtt_host": "192.168.1.10",
+  "mqtt_port": 8883,
+  "mqtt_username": "ledmatrix",
+  "mqtt_password": null,
+  "mqtt_client_id": "ledmatrix-mqtt-bridge",
+  "mqtt_topic": "ledmatrix/command",
+  "mqtt_tls": true,
+  "ledmatrix_api_base": "http://localhost:5000",
+  "request_timeout": 15,
+  "on_demand_duration": null,
+  "log_level": "INFO"
+}

integrations/mqtt_bridge/ledmatrix_mqtt_bridge.py

@@ -0,0 +1,548 @@
+#!/usr/bin/env python3
+"""Control a LEDMatrix display from Home Assistant over MQTT.
+
+The bridge owns no display logic. It subscribes to one command topic and
+turns each message into a call against the same api_v3 routes the web UI
+uses, so behaviour stays in one place and this stays a translation layer.
+
+On connect it publishes Home Assistant MQTT Discovery config, so a matrix
+appears in HA as real entities rather than something you drive with
+`mqtt.publish` by hand:
+
+    select.ledmatrix_display_mode   every mode across enabled plugins;
+                                    choosing one force-displays it
+    button.ledmatrix_stop_display   back to normal rotation
+    switch.ledmatrix_power          the display service, on or off
+    number.ledmatrix_brightness     0-100
+
+Anything the entities do not cover is still reachable by publishing JSON
+to the command topic:
+
+    {"action": "display", "mode": "nfl_live"}
+    {"action": "display", "plugin_id": "starlark-apps", "mode": "aquarium",
+     "duration": 300, "pinned": true}
+    {"action": "stop_display"}
+    {"action": "power", "state": "on" | "off"}
+    {"action": "brightness", "value": 75}
+    {"action": "refresh"}          re-publish discovery after installing a plugin
+
+Every command publishes its result to <command_topic>/status.
+
+Run it with `python3 ledmatrix_mqtt_bridge.py [--config PATH]`, or install
+ledmatrix-mqtt-bridge.service.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import signal
+import sys
+import threading
+from typing import Any, Callable, Dict, List, Optional
+
+import requests
+
+logger = logging.getLogger("ledmatrix-mqtt-bridge")
+
+DISCOVERY_PREFIX = "homeassistant"
+DEVICE_ID = "ledmatrix"
+DEVICE_INFO = {
+    "identifiers": [DEVICE_ID],
+    "name": "LEDMatrix",
+    "manufacturer": "ChuckBuilds",
+    "model": "LEDMatrix Display",
+}
+
+DEFAULTS = {
+    "mqtt_host": "localhost",
+    "mqtt_port": 1883,
+    "mqtt_username": None,
+    "mqtt_password": None,  # nosec B105 - "no password configured", not a credential
+    "mqtt_client_id": "ledmatrix-mqtt-bridge",
+    "mqtt_topic": "ledmatrix/command",
+    "mqtt_tls": False,
+    "mqtt_tls_insecure": False,
+    "ledmatrix_api_base": "http://localhost:5000",
+    "request_timeout": 15,
+    "on_demand_duration": None,
+    "log_level": "INFO",
+}
+
+
+class ConfigError(Exception):
+    """The bridge cannot start with the configuration it was given."""
+
+
+def load_config(path: str) -> Dict[str, Any]:
+    """Read bridge_config.json, overlaid on DEFAULTS.
+
+    Every value may also come from the environment as LEDMATRIX_MQTT_<KEY>,
+    which is how a password stays out of a file that has to be world-readable
+    for the service user.
+    """
+    config = dict(DEFAULTS)
+    if os.path.isfile(path):
+        with open(path, encoding="utf-8") as handle:
+            try:
+                loaded = json.load(handle)
+            except json.JSONDecodeError as err:
+                raise ConfigError(f"{path} is not valid JSON: {err}") from err
+        if not isinstance(loaded, dict):
+            raise ConfigError(f"{path} must contain a JSON object")
+        config.update(loaded)
+    else:
+        logger.warning("No config file at %s - using defaults and environment", path)
+
+    for key in DEFAULTS:
+        env_value = os.environ.get(f"LEDMATRIX_MQTT_{key.upper()}")
+        if env_value is not None:
+            config[key] = env_value
+
+    for key in ("mqtt_port", "request_timeout"):
+        try:
+            config[key] = int(config[key])
+        except (TypeError, ValueError) as err:
+            raise ConfigError(f"{key} must be a whole number, got {config[key]!r}") from err
+    for key in ("mqtt_tls", "mqtt_tls_insecure"):
+        config[key] = str(config[key]).lower() in ("1", "true", "yes", "on")
+
+    if config.get("mqtt_password") == "REPLACE_WITH_YOUR_ACTUAL_MQTT_PASSWORD":
+        raise ConfigError(
+            "mqtt_password is still the example placeholder - set a real password, "
+            "or remove the key if your broker allows anonymous connections")
+    return config
+
+
+class LEDMatrixClient:
+    """The api_v3 calls the bridge needs, and nothing else.
+
+    Everything goes through the HTTP API rather than the filesystem, so the
+    bridge does not have to live on the Pi, does not need read access to
+    config.json, and cannot drift from the web UI's own behaviour.
+    """
+
+    def __init__(self, api_base: str, timeout: int = 15,
+                 session: Optional[requests.Session] = None):
+        self.api_base = api_base.rstrip("/")
+        self.timeout = timeout
+        self.session = session or requests.Session()
+
+    def _call(self, method: str, path: str, **kwargs) -> Dict[str, Any]:
+        url = f"{self.api_base}/api/v3{path}"
+        response = self.session.request(method, url, timeout=self.timeout, **kwargs)
+        try:
+            body = response.json()
+        except ValueError:
+            body = {}
+        if response.status_code >= 400 or body.get("status") == "error":
+            message = body.get("message") or f"HTTP {response.status_code}"
+            raise RuntimeError(f"{method} {path} failed: {message}")
+        return body.get("data", body)
+
+    def list_modes(self) -> List[Dict[str, Any]]:
+        """Every display mode that can be force-displayed, newest discovery.
+
+        /display/modes triggers plugin discovery itself, which matters because
+        discovery is lazy: a bridge that never opens the dashboard would
+        otherwise see nothing at all.
+        """
+        return self._call("GET", "/display/modes").get("modes", [])
+
+    def display_status(self) -> Dict[str, Any]:
+        return self._call("GET", "/display/on-demand/status")
+
+    def start_on_demand(self, mode: str, plugin_id: Optional[str] = None,
+                        duration: Optional[int] = None, pinned: bool = False) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"mode": mode, "pinned": pinned}
+        if plugin_id:
+            # find_plugin_for_mode only sees modes declared in a static
+            # manifest, so a plugin whose modes are generated -- each installed
+            # Starlark app is one -- 404s when plugin_id is omitted. Sending it
+            # skips that lookup. /display/modes reports it for every mode.
+            payload["plugin_id"] = plugin_id
+        if duration:
+            payload["duration"] = int(duration)
+        return self._call("POST", "/display/on-demand/start", json=payload)
+
+    def stop_on_demand(self) -> Dict[str, Any]:
+        return self._call("POST", "/display/on-demand/stop", json={})
+
+    def set_power(self, on: bool) -> Dict[str, Any]:
+        action = "start_display" if on else "stop_display"
+        return self._call("POST", "/system/action", json={"action": action})
+
+    def get_brightness(self) -> Optional[int]:
+        config = self._call("GET", "/config/main")
+        value = config.get("display", {}).get("hardware", {}).get("brightness")
+        try:
+            return int(value)
+        except (TypeError, ValueError):
+            return None
+
+    def set_brightness(self, value: int) -> Dict[str, Any]:
+        return self._call("POST", "/config/main", json={"brightness": int(value)})
+
+
+class CommandHandler:
+    """Turns one decoded MQTT payload into one API call.
+
+    Kept free of MQTT so it can be tested against a fake client: the failure
+    modes worth pinning are all in here (an unknown mode, an out-of-range
+    brightness, a mode name that needs its plugin_id attached).
+    """
+
+    def __init__(self, client: LEDMatrixClient, default_duration: Optional[int] = None):
+        self.client = client
+        self.default_duration = default_duration
+        self._modes_by_name: Dict[str, Dict[str, Any]] = {}
+
+    def refresh_modes(self) -> List[Dict[str, Any]]:
+        modes = self.client.list_modes()
+        self._modes_by_name = {m["mode"]: m for m in modes}
+        # Home Assistant's select shows labels, so accept them back as well --
+        # otherwise picking "Simple Clock" in a dashboard is not a mode name.
+        for entry in modes:
+            self._modes_by_name.setdefault(entry.get("name") or entry["mode"], entry)
+        return modes
+
+    @property
+    def known_modes(self) -> List[Dict[str, Any]]:
+        return list({id(v): v for v in self._modes_by_name.values()}.values())
+
+    def handle(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        action = payload.get("action")
+        handlers: Dict[str, Callable[[Dict[str, Any]], Dict[str, Any]]] = {
+            "display": self._display,
+            "stop_display": lambda _p: self._ok(self.client.stop_on_demand()),
+            "power": self._power,
+            "brightness": self._brightness,
+            "refresh": lambda _p: self._ok({"modes": len(self.refresh_modes())}),
+        }
+        handler = handlers.get(action)
+        if handler is None:
+            return self._error(f"Unknown action {action!r}; expected one of "
+                               f"{', '.join(sorted(handlers))}")
+        try:
+            return handler(payload)
+        except (requests.RequestException, RuntimeError) as err:
+            logger.error("Command %s failed: %s", action, err)
+            return self._error(str(err))
+
+    def _display(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        mode = payload.get("mode")
+        plugin_id = payload.get("plugin_id")
+        if not mode and not plugin_id:
+            return self._error("display requires 'mode' or 'plugin_id'")
+
+        known = self._modes_by_name.get(mode) if mode else None
+        if known is None and mode and not plugin_id:
+            # One retry against a fresh listing: a plugin installed since the
+            # last refresh is the common reason a valid mode looks unknown.
+            self.refresh_modes()
+            known = self._modes_by_name.get(mode)
+        if known is not None:
+            mode = known["mode"]
+            plugin_id = plugin_id or known.get("plugin_id")
+
+        duration = payload.get("duration", self.default_duration)
+        pinned = bool(payload.get("pinned", False))
+        result = self.client.start_on_demand(
+            mode=mode, plugin_id=plugin_id, duration=duration, pinned=pinned)
+        return self._ok(result, mode=mode, plugin_id=plugin_id)
+
+    def _power(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        state = str(payload.get("state", "")).strip().lower()
+        if state not in ("on", "off"):
+            return self._error("power requires 'state' of 'on' or 'off'")
+        return self._ok(self.client.set_power(state == "on"), state=state)
+
+    def _brightness(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        raw = payload.get("value")
+        try:
+            value = int(float(raw))
+        except (TypeError, ValueError):
+            return self._error(f"brightness requires a number, got {raw!r}")
+        if not 0 <= value <= 100:
+            return self._error(f"brightness must be between 0 and 100, got {value}")
+        return self._ok(self.client.set_brightness(value), value=value)
+
+    @staticmethod
+    def _ok(result: Any, **extra) -> Dict[str, Any]:
+        return {"status": "success", "result": result, **extra}
+
+    @staticmethod
+    def _error(message: str) -> Dict[str, Any]:
+        return {"status": "error", "message": message}
+
+
+def discovery_messages(command_topic: str, state_topic: str, availability_topic: str,
+                       mode_labels: List[str]) -> List[Dict[str, Any]]:
+    """The retained MQTT Discovery configs, as {topic, payload} pairs.
+
+    Pure, so the entity shapes can be asserted without a broker. Every entity
+    shares one availability topic, which is also the bridge's last will -- HA
+    then shows the matrix as unavailable when the bridge dies, instead of
+    leaving stale controls that silently do nothing.
+    """
+    common = {
+        "device": DEVICE_INFO,
+        "availability_topic": availability_topic,
+        "payload_available": "online",
+        "payload_not_available": "offline",
+    }
+    return [
+        {
+            "topic": f"{DISCOVERY_PREFIX}/select/{DEVICE_ID}/display_mode/config",
+            "payload": {
+                **common,
+                "name": "Display Mode",
+                "unique_id": f"{DEVICE_ID}_display_mode",
+                "command_topic": command_topic,
+                "command_template": '{"action": "display", "mode": "{{ value }}"}',
+                "state_topic": state_topic,
+                "value_template": "{{ value_json.mode }}",
+                "options": mode_labels,
+                "icon": "mdi:view-dashboard",
+            },
+        },
+        {
+            "topic": f"{DISCOVERY_PREFIX}/button/{DEVICE_ID}/stop_display/config",
+            "payload": {
+                **common,
+                "name": "Stop Display",
+                "unique_id": f"{DEVICE_ID}_stop_display",
+                "command_topic": command_topic,
+                "payload_press": '{"action": "stop_display"}',
+                "icon": "mdi:stop",
+            },
+        },
+        {
+            "topic": f"{DISCOVERY_PREFIX}/switch/{DEVICE_ID}/power/config",
+            "payload": {
+                **common,
+                "name": "Power",
+                "unique_id": f"{DEVICE_ID}_power",
+                "command_topic": command_topic,
+                "payload_on": '{"action": "power", "state": "on"}',
+                "payload_off": '{"action": "power", "state": "off"}',
+                "state_topic": state_topic,
+                "value_template": "{{ 'ON' if value_json.power else 'OFF' }}",
+                "state_on": "ON",
+                "state_off": "OFF",
+                "icon": "mdi:power",
+            },
+        },
+        {
+            "topic": f"{DISCOVERY_PREFIX}/number/{DEVICE_ID}/brightness/config",
+            "payload": {
+                **common,
+                "name": "Brightness",
+                "unique_id": f"{DEVICE_ID}_brightness",
+                "command_topic": command_topic,
+                "command_template": '{"action": "brightness", "value": {{ value }}}',
+                "state_topic": state_topic,
+                "value_template": "{{ value_json.brightness }}",
+                "min": 0,
+                "max": 100,
+                "step": 1,
+                "icon": "mdi:brightness-6",
+            },
+        },
+    ]
+
+
+def warn_if_cleartext(config: Dict[str, Any]) -> bool:
+    """Say so, once, when a broker password is going over an unencrypted link.
+
+    The shipped example has TLS on, so reaching here means somebody turned it
+    off deliberately -- which is legitimate (the Mosquitto add-on is plaintext
+    on 1883) but should not be silent when there is a password to lose. Returns
+    whether it warned, so the decision is testable without a broker.
+    """
+    if config.get("mqtt_tls") or not config.get("mqtt_password"):
+        return False
+    logger.warning(
+        'mqtt_tls is off and a password is set: the broker password and every '
+        'command are sent unencrypted. Set "mqtt_tls": true (port 8883 on most '
+        'brokers) unless this is a trusted, isolated network.')
+    return True
+
+
+def read_state(client: LEDMatrixClient) -> Dict[str, Any]:
+    """The state every entity reads, so HA opens on real values.
+
+    Each field is fetched independently: a matrix with its display service
+    stopped still has a brightness worth showing, and one unreachable field
+    should not blank the rest.
+    """
+    state: Dict[str, Any] = {"power": False, "mode": None, "brightness": None}
+    try:
+        status = client.display_status()
+        state["power"] = bool(status.get("service", {}).get("active"))
+        on_demand = status.get("state", {})
+        if on_demand.get("active"):
+            state["mode"] = on_demand.get("mode")
+    except (requests.RequestException, RuntimeError) as err:
+        logger.debug("Could not read display status: %s", err)
+    try:
+        state["brightness"] = client.get_brightness()
+    except (requests.RequestException, RuntimeError) as err:
+        logger.debug("Could not read brightness: %s", err)
+    return state
+
+
+class Bridge:
+    """MQTT wiring around CommandHandler."""
+
+    def __init__(self, config: Dict[str, Any]):
+        self.config = config
+        self.command_topic = config["mqtt_topic"]
+        self.status_topic = f"{self.command_topic}/status"
+        self.state_topic = f"{self.command_topic}/state"
+        self.availability_topic = f"{self.command_topic}/availability"
+        self.client = LEDMatrixClient(config["ledmatrix_api_base"], config["request_timeout"])
+        self.handler = CommandHandler(self.client, config.get("on_demand_duration"))
+        self._stop = threading.Event()
+        self._mqtt = None
+
+    # -- MQTT callbacks (paho-mqtt 2.x VERSION2 signatures) ------------------
+
+    def _on_connect(self, client, _userdata, _flags, reason_code, _properties=None):
+        if getattr(reason_code, "is_failure", reason_code != 0):
+            logger.error("MQTT connection refused: %s", reason_code)
+            return
+        logger.info("Connected to MQTT broker; subscribing to %s", self.command_topic)
+        client.subscribe(self.command_topic, qos=1)
+        client.publish(self.availability_topic, "online", qos=1, retain=True)
+        # Re-publish on every reconnect, not just the first connect: a broker
+        # restart drops retained discovery configs, and HA would otherwise be
+        # left with entities it can no longer describe.
+        self.publish_discovery()
+        self.publish_state()
+
+    def _on_message(self, _client, _userdata, message):
+        try:
+            payload = json.loads(message.payload.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as err:
+            logger.warning("Ignoring unparseable message on %s: %s", message.topic, err)
+            self._publish(self.status_topic, {"status": "error", "message": f"bad payload: {err}"})
+            return
+        if not isinstance(payload, dict):
+            self._publish(self.status_topic,
+                          {"status": "error", "message": "payload must be a JSON object"})
+            return
+
+        logger.info("Command: %s", payload)
+        result = self.handler.handle(payload)
+        self._publish(self.status_topic, result)
+        # The API applies changes asynchronously (the controller polls its
+        # mailbox), so read state back rather than assuming the command took.
+        self.publish_state()
+
+    # -- publishing ---------------------------------------------------------
+
+    def _publish(self, topic: str, payload: Any, retain: bool = False) -> None:
+        if self._mqtt is None:
+            return
+        body = payload if isinstance(payload, str) else json.dumps(payload)
+        self._mqtt.publish(topic, body, qos=1, retain=retain)
+
+    def publish_discovery(self) -> None:
+        try:
+            modes = self.handler.refresh_modes()
+        except (requests.RequestException, RuntimeError) as err:
+            logger.error("Could not list display modes: %s", err)
+            modes = self.handler.known_modes
+        labels = sorted({m.get("name") or m["mode"] for m in modes})
+        for message in discovery_messages(self.command_topic, self.state_topic,
+                                          self.availability_topic, labels):
+            self._publish(message["topic"], message["payload"], retain=True)
+        logger.info("Published discovery for %d display mode(s)", len(labels))
+
+    def publish_state(self) -> None:
+        self._publish(self.state_topic, read_state(self.client), retain=True)
+
+    # -- lifecycle ----------------------------------------------------------
+
+    def run(self) -> int:
+        try:
+            import paho.mqtt.client as mqtt
+        except ImportError:
+            logger.error("paho-mqtt is not installed: pip install -r requirements.txt")
+            return 1
+
+        # VERSION2 is the current callback API. The compatibility note in
+        # CLAUDE.md is about code written against the v1 signatures; this file
+        # is written against v2 and requires paho-mqtt >= 2.0.
+        self._mqtt = mqtt.Client(
+            mqtt.CallbackAPIVersion.VERSION2,
+            client_id=self.config["mqtt_client_id"])
+        if self.config.get("mqtt_username"):
+            self._mqtt.username_pw_set(self.config["mqtt_username"],
+                                       self.config.get("mqtt_password"))
+        if self.config.get("mqtt_tls"):
+            self._mqtt.tls_set()
+            if self.config.get("mqtt_tls_insecure"):
+                logger.warning("TLS certificate verification is disabled (mqtt_tls_insecure)")
+                self._mqtt.tls_insecure_set(True)
+        else:
+            warn_if_cleartext(self.config)
+
+        self._mqtt.will_set(self.availability_topic, "offline", qos=1, retain=True)
+        self._mqtt.on_connect = self._on_connect
+        self._mqtt.on_message = self._on_message
+
+        logger.info("Connecting to %s:%s", self.config["mqtt_host"], self.config["mqtt_port"])
+        try:
+            self._mqtt.connect(self.config["mqtt_host"], self.config["mqtt_port"], keepalive=60)
+        except OSError as err:
+            logger.error("Could not reach the MQTT broker: %s", err)
+            return 1
+
+        self._mqtt.loop_start()
+        try:
+            while not self._stop.wait(30):
+                # HA is told the truth about state that changed outside the
+                # bridge -- somebody using the web UI, or an on-demand window
+                # expiring on its own.
+                self.publish_state()
+        finally:
+            self._publish(self.availability_topic, "offline", retain=True)
+            self._mqtt.loop_stop()
+            self._mqtt.disconnect()
+        return 0
+
+    def stop(self, *_args) -> None:
+        logger.info("Shutting down")
+        self._stop.set()
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument(
+        "--config",
+        default=os.path.join(os.path.dirname(os.path.abspath(__file__)), "bridge_config.json"),
+        help="Path to bridge_config.json (default: alongside this script)")
+    args = parser.parse_args(argv)
+
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s - %(levelname)s - %(name)s - %(message)s")
+    try:
+        config = load_config(args.config)
+    except ConfigError as err:
+        logger.error("%s", err)
+        return 1
+    logging.getLogger().setLevel(str(config.get("log_level", "INFO")).upper())
+
+    bridge = Bridge(config)
+    signal.signal(signal.SIGTERM, bridge.stop)
+    signal.signal(signal.SIGINT, bridge.stop)
+    return bridge.run()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

integrations/mqtt_bridge/requirements.txt

@@ -0,0 +1,5 @@
+# Floors are security floors, not API floors. requests < 2.33.0 carries
+# CVE-2024-35195, CVE-2024-47081 and CVE-2026-25645; matches the pin in the
+# project's own requirements.txt.
+paho-mqtt>=2.0.0,<3.0.0
+requests>=2.33.0,<3.0.0

plugin-repos/starlark-apps/manager.py

@@ -194,6 +194,15 @@ class StarlarkAppsPlugin(BasePlugin):
     Each installed app becomes a dynamic display mode.
     """
 
+    #: Starlark apps are animations: a .webp render carries per-frame delays
+    #: and _display_frame advances at most one frame per call. The controller
+    #: reads this attribute to decide whether a mode needs its high-FPS loop;
+    #: without it display() was called once per rotation slot, so a multi-frame
+    #: app showed a single frame and never moved. static-image is force-run at
+    #: high FPS for the same reason (GIFs), but that plugin is special-cased by
+    #: name in the controller and this one has to declare it.
+    enable_scrolling = True
+
     def __init__(self, plugin_id: str, config: Dict[str, Any],
                  display_manager, cache_manager, plugin_manager):
         """Initialize the Starlark Apps plugin."""
@@ -211,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
@@ -555,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
@@ -563,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
@@ -621,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)
@@ -681,38 +699,62 @@ class StarlarkAppsPlugin(BasePlugin):
                 if app.is_enabled() and app.should_render(current_time):
                     self._render_app(app, force=False)
 
-    def display(self, force_clear: bool = False) -> None:
+    def display(self, display_mode: Optional[str] = None, force_clear: bool = False) -> bool:
         """
         Display current Starlark app.
 
         This method is called during the display rotation.
         Displays frames from the currently active app.
+
+        `display_mode` names the app to show when it matches an installed
+        app_id. The controller passes the mode it is rotating to and inspects
+        this signature to decide whether to, so accepting it is what lets a
+        specific app be addressed -- including by an on-demand request pinned
+        to one app. Anything else (the plugin id itself, when the plugin
+        exposes no per-app modes) falls through to normal rotation.
+
+        Returns False when there is no app to show -- which is the state of
+        every install without Pixlet, and of a fresh one before any app is
+        added. The display controller only skips a mode on a boolean False
+        (it checks isinstance(result, bool)), so returning None held a black
+        panel for the full display_duration instead of rotating on.
         """
         try:
             if force_clear:
                 self.display_manager.clear()
 
-            # If no current app, try to select one
-            if not self.current_app:
+            if display_mode and display_mode in self.apps:
+                self.current_app = self.apps[display_mode]
+            elif force_clear or not self.current_app:
+                # Advance on entry to the mode. _select_next_app only ran when
+                # current_app was unset, so the first enabled app was picked
+                # once and then shown forever -- every other installed app was
+                # rendered on schedule and never displayed. force_clear is the
+                # controller's "we just switched to you" signal (it is reset
+                # immediately after this call), so one app gets each turn.
                 self._select_next_app()
 
             if not self.current_app:
                 # No apps available
                 self.logger.debug("No Starlark apps to display")
-                return
+                return False
 
             # Render app if needed
             if not self.current_app.frames:
                 success = self._render_app(self.current_app, force=True)
                 if not success:
                     self.logger.error(f"Failed to render app: {self.current_app.app_id}")
-                    return
+                    return False
 
-            # Display current frame
-            self._display_frame()
+            # Display current frame. The result is propagated: a failed frame
+            # update is not a displayed frame, and returning True regardless
+            # told the controller the mode had rendered, so it held the dead
+            # frame for the whole display_duration instead of rotating on.
+            return self._display_frame()
 
         except Exception as e:
             self.logger.error(f"Error displaying Starlark app: {e}")
+            return False
 
     def _select_next_app(self) -> None:
         """Select the next enabled app for display."""
@@ -763,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:
@@ -835,10 +887,13 @@ class StarlarkAppsPlugin(BasePlugin):
             self.logger.error(f"Error loading frames for {app.app_id}: {e}")
             return False
 
-    def _display_frame(self) -> None:
-        """Display the current frame of the current app."""
+    def _display_frame(self) -> bool:
+        """Display the current frame of the current app.
+
+        :returns: whether a frame actually reached the display manager.
+        """
         if not self.current_app or not self.current_app.frames:
-            return
+            return False
 
         try:
             current_time = time.time()
@@ -856,8 +911,11 @@ class StarlarkAppsPlugin(BasePlugin):
                 )
                 self.current_app.last_frame_time = current_time
 
+            return True
+
         except Exception as e:
             self.logger.error(f"Error displaying frame: {e}")
+            return False
 
     def install_app(self, app_id: str, star_file_path: str, metadata: Optional[Dict[str, Any]] = None, assets_dir: Optional[str] = None) -> bool:
         """

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])
@@ -264,10 +281,18 @@ class PixletRenderer:
                     else:
                         value_str = str(value)
 
-                    # Validate value doesn't contain dangerous shell metacharacters
-                    # Block: backticks, $(), pipes, redirects, semicolons, ampersands, null bytes
-                    # Allow: most printable chars including spaces, quotes, brackets, braces
-                    if re.search(r'[`$|<>&;\x00]|\$\(', value_str):
+                    # Validate value doesn't contain dangerous shell metacharacters.
+                    # Kept as defence in depth only: cmd is a list and there is no
+                    # shell=True below, so nothing here is ever interpreted by a
+                    # shell. That made the list worth trimming rather than growing
+                    # -- "|" is a normal character inside a config value, and apps
+                    # do use it as a separator (a PennDOT sign id is
+                    # "I-476 North|175659"). Blocking it dropped the whole key
+                    # silently, and the app then rendered its own "not configured"
+                    # screen with nothing to say why.
+                    # Block: backticks, $(), redirects, semicolons, ampersands, null bytes
+                    # Allow: most printable chars including spaces, quotes, brackets, braces, pipes
+                    if re.search(r'[`$<>&;\x00]|\$\(', value_str):
                         logger.warning(f"Skipping config value with unsafe shell characters for key {key}: {value_str}")
                         continue
 
@@ -279,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]
@@ -286,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
@@ -299,13 +332,21 @@ class PixletRenderer:
             )
 
             if result.returncode == 0:
-                if os.path.isfile(output_path):
-                    logger.debug(f"Successfully rendered: {star_file} -> {output_path}")
-                    return True, None
-                else:
+                if not os.path.isfile(output_path):
                     error = "Rendering succeeded but output file not found"
                     logger.error(error)
                     return False, error
+                # Pixlet exits 0 and writes a 0-byte file when the app renders
+                # nothing -- an app whose config leaves it with no content to
+                # show does exactly that. Treating existence alone as success
+                # handed the caller a file with no frames in it, which reads
+                # downstream as a working app that draws a black panel.
+                if os.path.getsize(output_path) == 0:
+                    error = "Rendering produced an empty (0-byte) file - the app rendered no content"
+                    logger.error(error)
+                    return False, error
+                logger.debug(f"Successfully rendered: {star_file} -> {output_path}")
+                return True, None
             else:
                 error = f"Pixlet failed (exit {result.returncode}): {result.stderr}"
                 logger.error(error)
@@ -319,11 +360,76 @@ class PixletRenderer:
             logger.exception("Rendering exception")
             return False, "Rendering failed - see logs for details"
 
+    #: Schema extraction runs an app's own get_schema(), which may make a
+    #: network call. Short enough that a hung app does not stall an upload,
+    #: long enough for a real API round trip on a slow connection.
+    SCHEMA_TIMEOUT = 20
+
+    def extract_schema_via_pixlet(self, star_file: str) -> Optional[Dict[str, Any]]:
+        """Ask Pixlet itself for the app's schema, or None if it cannot say.
+
+        `pixlet schema` executes get_schema() instead of reading it, which is
+        the only way to see options an app computes at runtime -- a dropdown
+        whose choices come from a live API call has no option list anywhere in
+        the source for the regex parser below to find, so that parser reports
+        an empty dropdown and the config form offers nothing to pick.
+
+        Pixlet's own field keys are remapped to the ones the rest of this
+        plugin and the config UI already use ("typeOf"/"desc"), so the two
+        extractors return the same shape and callers cannot tell them apart.
+        """
+        if not self.pixlet_binary:
+            return None
+        try:
+            result = subprocess.run(
+                [self.pixlet_binary, "schema", star_file],
+                capture_output=True, text=True, timeout=self.SCHEMA_TIMEOUT,
+                cwd=self._get_safe_working_directory(star_file),
+            )
+        except subprocess.TimeoutExpired:
+            logger.warning(
+                "pixlet schema timed out after %ss for %s - get_schema() may be "
+                "making a slow network call", self.SCHEMA_TIMEOUT, star_file)
+            return None
+        except (subprocess.SubprocessError, OSError) as e:
+            logger.warning(f"Could not run pixlet schema for {star_file}: {e}")
+            return None
+
+        if result.returncode != 0:
+            # Not an error worth failing on: older Pixlet builds have no
+            # `schema` subcommand at all, and the source parser still works.
+            logger.debug(
+                "pixlet schema exited %d for %s: %s",
+                result.returncode, star_file, (result.stderr or '').strip()[:300])
+            return None
+
+        try:
+            schema = json.loads(result.stdout)
+        except (json.JSONDecodeError, ValueError) as e:
+            logger.warning(f"pixlet schema returned unparseable output for {star_file}: {e}")
+            return None
+
+        if not isinstance(schema, dict) or not isinstance(schema.get("schema"), list):
+            logger.warning(f"pixlet schema returned an unexpected shape for {star_file}")
+            return None
+
+        for field in schema["schema"]:
+            if not isinstance(field, dict):
+                continue
+            if "type" in field and "typeOf" not in field:
+                field["typeOf"] = field.pop("type")
+            if "description" in field and "desc" not in field:
+                field["desc"] = field.pop("description")
+        return schema
+
     def extract_schema(self, star_file: str) -> Tuple[bool, Optional[Dict[str, Any]], Optional[str]]:
         """
-        Extract configuration schema from a .star file by parsing source code.
+        Extract configuration schema from a .star file.
 
-        Supports:
+        Prefers `pixlet schema`, which runs the app and therefore sees options
+        it computes at runtime. Falls back to parsing the source when Pixlet is
+        unavailable, too old to have the subcommand, or the app fails to run --
+        that parser handles:
         - Static field definitions (location, text, toggle, dropdown, color, datetime)
         - Variable-referenced dropdown options
         - Graceful degradation for unsupported field types
@@ -337,6 +443,13 @@ class PixletRenderer:
         if not os.path.isfile(star_file):
             return False, None, f"Star file not found: {star_file}"
 
+        schema = self.extract_schema_via_pixlet(star_file)
+        if schema is not None:
+            logger.debug(
+                "Extracted schema with %d field(s) from %s via pixlet schema",
+                len(schema.get('schema', [])), star_file)
+            return True, schema, None
+
         try:
             # Read .star file
             with open(star_file, 'r', encoding='utf-8') as f:

plugin-repos/starlark-apps/tronbyte_repository.py

@@ -5,6 +5,7 @@ Handles interaction with the Tronbyte apps repository on GitHub.
 Fetches app listings, metadata, and downloads .star files.
 """
 
+import json
 import logging
 import time
 import requests
@@ -49,6 +50,13 @@ class TronbyteRepository:
         self.base_url = "https://api.github.com"
         self.raw_url = "https://raw.githubusercontent.com"
 
+        # Why the last GitHub API call failed, in words a user can act on.
+        # _make_request used to log the reason and return a bare None, so
+        # every caller up the stack knew only that "something" went wrong --
+        # which is how an exhausted rate limit reached the store page as an
+        # empty grid with no explanation.
+        self.last_error: Optional[str] = None
+
         self.session = requests.Session()
         if github_token:
             self.session.headers.update({
@@ -70,29 +78,50 @@ class TronbyteRepository:
         Returns:
             JSON response or None on error
         """
+        self.last_error = None
         try:
             response = self.session.get(url, timeout=timeout)
 
-            if response.status_code == 403:
-                # Rate limit exceeded
-                logger.warning("[Tronbyte Repo] GitHub API rate limit exceeded")
+            if response.status_code in (403, 429):
+                # 403 is both "rate limited" and "forbidden"; the remaining
+                # counter is what tells them apart, and the difference matters
+                # to whoever reads the message -- one is fixed by waiting or
+                # adding a token, the other is not.
+                remaining = response.headers.get('X-RateLimit-Remaining')
+                if remaining == '0':
+                    self.last_error = (
+                        "GitHub API rate limit exceeded"
+                        f" ({response.headers.get('X-RateLimit-Limit', '?')} requests/hour"
+                        f"{'' if self.github_token else ', unauthenticated'})."
+                        " Add a GitHub token in settings, or wait for the limit to reset."
+                    )
+                else:
+                    self.last_error = f"GitHub refused the request ({response.status_code})"
+                logger.warning(f"[Tronbyte Repo] {self.last_error}")
                 return None
             elif response.status_code == 404:
+                self.last_error = "Not found on GitHub"
                 logger.warning(f"[Tronbyte Repo] Resource not found: {url}")
                 return None
             elif response.status_code != 200:
+                self.last_error = f"GitHub API error {response.status_code}"
                 logger.error(f"[Tronbyte Repo] GitHub API error: {response.status_code}")
                 return None
 
             return response.json()
 
         except requests.Timeout:
+            self.last_error = "Timed out reaching GitHub"
             logger.error(f"[Tronbyte Repo] Request timeout: {url}")
             return None
         except requests.RequestException as e:
+            self.last_error = f"Network error reaching GitHub: {e.__class__.__name__}"
             logger.error(f"[Tronbyte Repo] Request error: {e}", exc_info=True)
             return None
         except (json.JSONDecodeError, ValueError) as e:
+            # Reachable whenever something on the path answers with HTML --
+            # a captive portal, a proxy error page, a DNS-hijacking router.
+            self.last_error = "GitHub returned a response that was not JSON"
             logger.error(f"[Tronbyte Repo] JSON parse error for {url}: {e}", exc_info=True)
             return None
 
@@ -125,6 +154,61 @@ class TronbyteRepository:
             logger.error(f"[Tronbyte Repo] Network error fetching raw file {file_path}: {e}", exc_info=True)
             return None
 
+    def _list_app_dirs_via_trees(self) -> Optional[List[Dict[str, Any]]]:
+        """App directories via the git trees API, or None on failure.
+
+        The contents API caps a directory listing at 1000 entries and says
+        nothing about having truncated it, so the store showed the first 1000
+        apps of a repository that has more and looked complete while doing it.
+        The trees API caps far higher and sets `truncated` when it does, at
+        the cost of one extra call to resolve the `apps` tree.
+        """
+        repo = f"{self.base_url}/repos/{self.REPO_OWNER}/{self.REPO_NAME}"
+
+        root = self._make_request(f"{repo}/git/trees/{self.DEFAULT_BRANCH}")
+        if not isinstance(root, dict):
+            return None
+
+        apps_sha = next(
+            (e.get('sha') for e in root.get('tree', []) or []
+             if e.get('path') == self.APPS_PATH and e.get('type') == 'tree'),
+            None)
+        if not apps_sha:
+            self.last_error = f"No '{self.APPS_PATH}' directory in the repository"
+            return None
+
+        tree = self._make_request(f"{repo}/git/trees/{apps_sha}")
+        if not isinstance(tree, dict):
+            return None
+
+        if tree.get('truncated'):
+            logger.warning(
+                "[Tronbyte Repo] GitHub truncated the app tree; the listing is incomplete")
+
+        return [
+            {'id': e['path'], 'path': f"{self.APPS_PATH}/{e['path']}", 'url': None}
+            for e in tree.get('tree', []) or []
+            if e.get('type') == 'tree' and e.get('path') and not e['path'].startswith('.')
+        ]
+
+    def _list_app_dirs_via_contents(self) -> Optional[List[Dict[str, Any]]]:
+        """App directories via the contents API. Capped at 1000 entries."""
+        url = f"{self.base_url}/repos/{self.REPO_OWNER}/{self.REPO_NAME}/contents/{self.APPS_PATH}"
+
+        data = self._make_request(url)
+        if data is None:
+            return None
+        if not isinstance(data, list):
+            self.last_error = "GitHub returned an unexpected listing format"
+            return None
+
+        return [
+            {'id': item.get('name'), 'path': item.get('path'), 'url': item.get('url')}
+            for item in data
+            if item.get('type') == 'dir' and item.get('name')
+            and not item['name'].startswith('.')
+        ]
+
     def list_apps(self) -> Tuple[bool, Optional[List[Dict[str, Any]]], Optional[str]]:
         """
         List all available apps in the repository.
@@ -132,26 +216,17 @@ class TronbyteRepository:
         Returns:
             Tuple of (success, apps_list, error_message)
         """
-        url = f"{self.base_url}/repos/{self.REPO_OWNER}/{self.REPO_NAME}/contents/{self.APPS_PATH}"
-
-        data = self._make_request(url)
-        if data is None:
-            return False, None, "Failed to fetch repository contents"
-
-        if not isinstance(data, list):
-            return False, None, "Invalid response format"
-
-        # Filter directories (apps)
-        apps = []
-        for item in data:
-            if item.get('type') == 'dir':
-                app_id = item.get('name')
-                if app_id and not app_id.startswith('.'):
-                    apps.append({
-                        'id': app_id,
-                        'path': item.get('path'),
-                        'url': item.get('url')
-                    })
+        apps = self._list_app_dirs_via_trees()
+        if apps is None:
+            # Fall back rather than fail: the contents API was what shipped,
+            # so a trees-only outage should not take the store down with it.
+            trees_error = self.last_error
+            logger.warning(
+                f"[Tronbyte Repo] Trees listing failed ({trees_error}); "
+                "falling back to the contents API")
+            apps = self._list_app_dirs_via_contents()
+            if apps is None:
+                return False, None, self.last_error or trees_error or "Failed to fetch repository contents"
 
         logger.info(f"Found {len(apps)} apps in repository")
         return True, apps, None
@@ -267,14 +342,22 @@ class TronbyteRepository:
                     'categories': _apps_cache['categories'],
                     'authors': _apps_cache['authors'],
                     'count': len(_apps_cache['data']),
-                    'cached': True
+                    'cached': True,
+                    'error': None,
                 }
 
-        # Fetch directory listing (1 GitHub API call)
+        # Fetch directory listing (a small number of GitHub API calls)
         success, app_dirs, error = self.list_apps()
         if not success or not app_dirs:
-            logger.error(f"Failed to list apps for bulk fetch: {error}")
-            return {'apps': [], 'categories': [], 'authors': [], 'count': 0, 'cached': False}
+            # Returning an empty list here used to read downstream as "the
+            # repository has no apps", and the route reported that as a
+            # success -- so a rate limit, a DNS failure and an empty
+            # repository were all drawn as the same blank grid. Hand the
+            # reason back instead and let the caller surface it.
+            reason = error or "No apps found in the repository"
+            logger.error(f"Failed to list apps for bulk fetch: {reason}")
+            return {'apps': [], 'categories': [], 'authors': [],
+                    'count': 0, 'cached': False, 'error': reason}
 
         logger.info(f"Bulk-fetching manifests for {len(app_dirs)} apps...")
 
@@ -341,7 +424,8 @@ class TronbyteRepository:
             'categories': categories,
             'authors': authors,
             'count': len(apps_with_metadata),
-            'cached': False
+            'cached': False,
+            'error': None,
         }
 
     def download_star_file(self, app_id: str, output_path: Path, filename: Optional[str] = None) -> Tuple[bool, Optional[str]]:

requirements-test.txt

@@ -7,3 +7,8 @@ freezegun>=1.2,<2        # deterministic time for golden-image tests
 psutil>=6.0.0,<8.0.0     # optional at runtime; installed for tests so the
                          # /system/status endpoint's real path is exercised
 mypy>=1.5.0,<2.0.0       # static type checking (also pinned in .pre-commit-config.yaml)
+PyYAML>=6.0.2,<7.0.0     # not a core dependency: test_starlark_pixlet_routes loads
+                         # plugin-repos/starlark-apps/tronbyte_repository.py the way
+                         # the blueprint does, and that plugin imports yaml. The
+                         # plugin declares it in its own requirements.txt, which the
+                         # store installs on a real rig but CI never does.

requirements.txt

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

scripts/audit_render_path.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""Find blocking work reachable from a plugin's render path.
+
+`display()` runs on the render thread. Anything slow reached from it stalls the
+panel for its whole duration, and on a vsync-paced loop that is immediately
+visible: a single 15ms call on a 100Hz panel drops a frame, and a network round
+trip freezes the marquee outright.
+
+This has bitten twice already. odds-ticker called `_has_live_games()` every
+frame, whose slow path read the scoreboard cache from disk and parsed JSON per
+enabled league -- one stalled frame every few minutes. soccer-scoreboard timed
+out inside `update()` during a cache refresh. Both were found by staring at
+frame-time histograms, which is a slow way to find a bug that is visible in the
+source.
+
+The audit walks the call graph from `display()` through same-class `self.*`
+methods and reports anything that reaches a known-blocking API. It is a
+heuristic, not a proof: it cannot see through indirection, and a hit is not
+automatically a bug -- a call guarded by an interval check may be fine. It is a
+list of places worth a human look.
+
+    python3 scripts/audit_render_path.py                    # all plugins
+    python3 scripts/audit_render_path.py --dir plugin-repos # a specific tree
+    python3 scripts/audit_render_path.py --plugin odds-ticker
+"""
+from __future__ import annotations
+
+import argparse
+import ast
+import sys
+from pathlib import Path
+
+#: Calls that can block for longer than a frame. Matched on the attribute or
+#: function name, so `requests.get`, `self.session.get` and a bare `get` on a
+#: requests-ish object all register.
+BLOCKING = {
+    "get": "network or cache read",
+    "post": "network",
+    "put": "network",
+    "request": "network",
+    "urlopen": "network",
+    "read": "I/O",
+    "open": "file I/O",
+    "load": "JSON/file parse",
+    "loads": "JSON parse",
+    "dump": "file write",
+    "dumps": "serialise",
+    "sleep": "sleep on the render thread",
+    "run": "subprocess",
+    "check_output": "subprocess",
+    "connect": "network",
+    "download_logo": "network",
+    "_fetch": "fetch",
+}
+
+#: Names that make a hit far more likely to matter.
+HIGH_SIGNAL = ("requests", "urllib", "session", "cache_manager", "subprocess",
+               "socket", "http")
+
+RENDER_ENTRY = "display"
+
+
+class Analyzer:
+    def __init__(self, tree: ast.AST):
+        self.methods: dict[str, ast.FunctionDef] = {}
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                self.methods.setdefault(node.name, node)
+
+    def calls_in(self, fn: ast.AST):
+        """(self-method names called, blocking hits) inside one function."""
+        self_calls, hits = set(), []
+        for node in ast.walk(fn):
+            if not isinstance(node, ast.Call):
+                continue
+            func = node.func
+            if isinstance(func, ast.Attribute):
+                name = func.attr
+                base = ast.unparse(func.value) if hasattr(ast, "unparse") else ""
+                if base == "self" and name in self.methods:
+                    self_calls.add(name)
+                    continue
+                if name in BLOCKING:
+                    hits.append((name, base, BLOCKING[name], node.lineno))
+            elif isinstance(func, ast.Name) and func.id in BLOCKING:
+                hits.append((func.id, "", BLOCKING[func.id], node.lineno))
+        return self_calls, hits
+
+    def reachable_from(self, entry: str, max_depth: int = 3):
+        """Blocking hits reachable from `entry`, with the path that reaches them."""
+        if entry not in self.methods:
+            return []
+        found, seen = [], set()
+        stack = [(entry, [entry], 0)]
+        while stack:
+            name, path, depth = stack.pop()
+            if name in seen or depth > max_depth:
+                continue
+            seen.add(name)
+            self_calls, hits = self.calls_in(self.methods[name])
+            for hit in hits:
+                found.append((path, hit))
+            for callee in sorted(self_calls):
+                stack.append((callee, path + [callee], depth + 1))
+        return found
+
+
+def audit_file(path: Path):
+    try:
+        tree = ast.parse(path.read_text(encoding="utf-8"))
+    except (OSError, SyntaxError):
+        return []
+    analyzer = Analyzer(tree)
+    return analyzer.reachable_from(RENDER_ENTRY)
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    root = Path(__file__).resolve().parent.parent
+    ap.add_argument("--dir", default=str(root / "plugin-repos"))
+    ap.add_argument("--plugin", help="only this plugin directory")
+    ap.add_argument("--all-hits", action="store_true",
+                    help="include low-signal hits (open/read/load on locals)")
+    args = ap.parse_args()
+
+    base = Path(args.dir)
+    if not base.is_dir():
+        sys.exit("not a directory: %s" % base)
+
+    plugins = [base / args.plugin] if args.plugin else sorted(
+        d for d in base.iterdir() if d.is_dir())
+
+    total = 0
+    for plugin in plugins:
+        rows = []
+        for src in sorted(plugin.glob("*.py")):
+            if src.name.startswith("test_"):
+                continue
+            for path, (name, s_base, why, lineno) in audit_file(src):
+                signal = any(h in s_base.lower() for h in HIGH_SIGNAL)
+                if not signal and not args.all_hits:
+                    continue
+                rows.append((src.name, lineno, "->".join(path),
+                             ("%s.%s" % (s_base, name)) if s_base else name, why))
+        if rows:
+            total += len(rows)
+            print("\n%s" % plugin.name)
+            for fname, lineno, chain, call, why in sorted(rows):
+                print("  %s:%-5d %-34s via %s" % (fname, lineno, call + "  (" + why + ")", chain))
+
+    print("\n%d blocking call(s) reachable from display() across %d plugin(s)"
+          % (total, len(plugins)))
+    print("Heuristic: a hit guarded by an interval check may be fine. Look, do "
+          "not assume.")
+
+
+if __name__ == "__main__":
+    main()

scripts/build_rgbmatrix_nogil.sh

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

scripts/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_dns_fix.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+
+# DNS single-request fix installation script.
+#
+# Optional. Install this only if plugins that call external APIs (Starlark
+# apps, weather, sports, music) are timing out or feel slow to first paint
+# while the network is otherwise fine. See the header of
+# scripts/utils/apply_dns_single_request.sh for what it changes and why.
+
+set -e
+
+PROJECT_ROOT_DIR=$(cd "$(dirname "$0")/../.." && pwd)
+SERVICE_NAME="ledmatrix-dns-fix"
+UNIT_SRC="$PROJECT_ROOT_DIR/systemd/$SERVICE_NAME.service"
+UNIT_DEST="/etc/systemd/system/$SERVICE_NAME.service"
+DROPIN_DIR="/etc/systemd/system/ledmatrix.service.d"
+
+if [ "$EUID" -eq 0 ]; then
+    SYSTEMCTL_CMD="systemctl"
+    SUDO=""
+else
+    SYSTEMCTL_CMD="sudo systemctl"
+    SUDO="sudo"
+fi
+
+echo "Installing LED Matrix DNS fix service"
+echo "Project root directory: $PROJECT_ROOT_DIR"
+
+if [ ! -f "$UNIT_SRC" ]; then
+    echo "✗ Missing unit file: $UNIT_SRC"
+    exit 1
+fi
+
+chmod +x "$PROJECT_ROOT_DIR/scripts/utils/apply_dns_single_request.sh"
+
+echo "Installing $UNIT_DEST..."
+sed "s|__PROJECT_ROOT_DIR__|$PROJECT_ROOT_DIR|g" "$UNIT_SRC" \
+    | $SUDO tee "$UNIT_DEST" > /dev/null
+
+# Order ledmatrix.service after the fix. `Before=` in the unit itself only
+# orders units already in the same transaction, so a plain
+# `systemctl restart ledmatrix` would not wait for it -- and since this fix is
+# opt-in, ledmatrix.service cannot carry the dependency in the repo.
+# Wants=, not Requires=: a DNS workaround failing should not stop the display.
+echo "Installing the ledmatrix.service ordering drop-in..."
+$SUDO mkdir -p "$DROPIN_DIR"
+printf '[Unit]\nWants=%s.service\nAfter=%s.service\n' "$SERVICE_NAME" "$SERVICE_NAME" \
+    | $SUDO tee "$DROPIN_DIR/10-dns-fix.conf" > /dev/null
+
+$SYSTEMCTL_CMD daemon-reload
+$SYSTEMCTL_CMD enable "$SERVICE_NAME.service"
+
+# Do not mask a failure here. The unit exits non-zero when it could not apply
+# the option -- a systemd-resolved host, an unwritable resolv.conf, a failed
+# `resolvconf -u` -- and reporting "installation complete" over that would
+# leave the operator believing a workaround is active when it is not.
+START_STATUS=0
+$SYSTEMCTL_CMD start "$SERVICE_NAME.service" || START_STATUS=$?
+
+echo ""
+if grep -qs "^options single-request$" /etc/resolv.conf; then
+    echo "✓ 'options single-request' is active in /etc/resolv.conf"
+elif [ "$START_STATUS" -ne 0 ]; then
+    echo "✗ The DNS fix could not be applied on this host."
+    echo "  The service reported why:"
+    echo "    journalctl -u $SERVICE_NAME -n 20"
+    echo ""
+    echo "  The unit is installed and will try again on the next boot. Nothing"
+    echo "  else about your install has changed."
+    exit "$START_STATUS"
+else
+    echo "⚠ 'options single-request' is not in /etc/resolv.conf yet."
+    echo "  Check what the service reported:"
+    echo "    journalctl -u $SERVICE_NAME -n 20"
+fi
+
+echo ""
+echo "DNS fix installation complete."
+echo ""
+echo "Useful commands:"
+echo "  sudo systemctl status $SERVICE_NAME   # Check status"
+echo "  sudo journalctl -u $SERVICE_NAME -n 50  # View logs"
+echo "  sudo systemctl disable --now $SERVICE_NAME  # Undo the service"
+echo "  sudo rm $DROPIN_DIR/10-dns-fix.conf        # Undo the ordering drop-in"
+echo "  # then remove the 'options single-request' line from /etc/resolv.conf"
+echo ""

scripts/install/install_mqtt_bridge.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+
+# Home Assistant MQTT bridge installation script.
+#
+# Optional. Installs integrations/mqtt_bridge as a service so Home Assistant
+# can force display modes, toggle power and set brightness over MQTT.
+# See integrations/mqtt_bridge/README.md.
+
+set -e
+
+PROJECT_ROOT_DIR=$(cd "$(dirname "$0")/../.." && pwd)
+BRIDGE_DIR="$PROJECT_ROOT_DIR/integrations/mqtt_bridge"
+SERVICE_NAME="ledmatrix-mqtt-bridge"
+UNIT_SRC="$PROJECT_ROOT_DIR/systemd/$SERVICE_NAME.service"
+UNIT_DEST="/etc/systemd/system/$SERVICE_NAME.service"
+
+if [ "$EUID" -eq 0 ]; then
+    SYSTEMCTL_CMD="systemctl"
+    SUDO=""
+else
+    SYSTEMCTL_CMD="sudo systemctl"
+    SUDO="sudo"
+fi
+
+echo "Installing LED Matrix MQTT bridge"
+echo "Project root directory: $PROJECT_ROOT_DIR"
+
+if [ ! -f "$BRIDGE_DIR/bridge_config.json" ]; then
+    cp "$BRIDGE_DIR/bridge_config.example.json" "$BRIDGE_DIR/bridge_config.json"
+    chmod 600 "$BRIDGE_DIR/bridge_config.json"
+    echo ""
+    echo "⚠ Created $BRIDGE_DIR/bridge_config.json from the example."
+    echo "  Edit it with your broker details, then re-run this script."
+    echo "  The service will refuse to start until the placeholder password is replaced."
+    echo ""
+fi
+
+echo "Installing Python dependencies..."
+python3 -m pip install -r "$BRIDGE_DIR/requirements.txt" 2>/dev/null \
+    || python3 -m pip install --break-system-packages -r "$BRIDGE_DIR/requirements.txt"
+
+echo "Installing $UNIT_DEST..."
+sed "s|__PROJECT_ROOT_DIR__|$PROJECT_ROOT_DIR|g" "$UNIT_SRC" \
+    | $SUDO tee "$UNIT_DEST" > /dev/null
+
+$SYSTEMCTL_CMD daemon-reload
+$SYSTEMCTL_CMD enable "$SERVICE_NAME.service"
+$SYSTEMCTL_CMD restart "$SERVICE_NAME.service" || true
+
+echo ""
+if $SYSTEMCTL_CMD is-active --quiet "$SERVICE_NAME.service" 2>/dev/null; then
+    echo "✓ MQTT bridge is running"
+    echo "  The matrix should appear in Home Assistant under Settings > Devices > MQTT."
+else
+    echo "⚠ MQTT bridge is not running. Check the logs:"
+    echo "  sudo journalctl -u $SERVICE_NAME -n 50"
+fi
+
+echo ""
+echo "Useful commands:"
+echo "  sudo systemctl status $SERVICE_NAME"
+echo "  sudo journalctl -u $SERVICE_NAME -f"
+echo "  sudo systemctl disable --now $SERVICE_NAME   # Undo"
+echo ""

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,49 @@ 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
-
-[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
+# 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
 
 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
+    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."
+    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,22 @@ 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
 
 # Ensure cache directory exists with proper permissions
 # This is a fallback for older systemd versions that don't support CacheDirectory

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

@@ -52,6 +52,10 @@ def main() -> int:
     parser.add_argument('--height', type=int, default=32, help='Display height (default: 32)')
     parser.add_argument('--skip-update', action='store_true',
                         help='Skip calling update() (render display only)')
+    parser.add_argument('--display-mode', default=None,
+                        help='Display mode to render, for plugins that declare '
+                             'more than one in their manifest (e.g. nrl_live). '
+                             'Omitted, the plugin picks its own default.')
 
     args = parser.parse_args()
 
@@ -141,8 +145,26 @@ def main() -> int:
         except Exception as e:
             logger.warning("update() raised: %s — continuing to display()", e)
 
+    # A plugin that declares several display modes usually renders nothing
+    # useful without being told which one to draw: the scoreboards keep their
+    # state on per-mode sub-managers and their no-argument path returns False.
+    # Only pass the argument when asked for, so the many plugins whose display()
+    # takes no display_mode keep working untouched.
     try:
-        plugin_instance.display(force_clear=True)
+        if args.display_mode:
+            try:
+                plugin_instance.display(display_mode=args.display_mode,
+                                        force_clear=True)
+            except TypeError as error:
+                if ("unexpected keyword argument" not in str(error)
+                        or "display_mode" not in str(error)):
+                    raise
+                logger.warning(
+                    "%s.display() does not accept display_mode; rendering its "
+                    "default screen instead", args.plugin)
+                plugin_instance.display(force_clear=True)
+        else:
+            plugin_instance.display(force_clear=True)
         logger.debug("display() completed")
     except Exception as e:
         logger.error("Error in display(): %s", e)

scripts/run_plugin_tests.py

@@ -6,6 +6,9 @@ Discovers and runs tests for LEDMatrix plugins.
 Supports both unittest and pytest.
 """
 
+import os
+import re
+import subprocess  # nosec B404 - list-form argv only, no shell  # nosemgrep
 import sys
 import argparse
 from pathlib import Path
@@ -68,6 +71,79 @@ def _find_tests_in_dir(directory: Path) -> list:
     return sorted(set(test_files))
 
 
+def _is_script_style(path) -> bool:
+    """True when a test file is a standalone script, not a pytest module.
+
+    Most plugin tests are written as `def main()` plus an `if __name__ ==
+    "__main__"` guard and signal through an exit code. pytest collects zero
+    items from those, so handing them to pytest printed "no tests ran" and this
+    runner reported success over work it had not done -- 151 of 248 files on a
+    fully populated rig.
+    """
+    try:
+        src = Path(path).read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return False
+    has_pytest_items = re.search(r"^\s*(def test_|class Test|async def test_)", src, re.M)
+    has_main_guard = "__main__" in src and "__name__" in src
+    return bool(has_main_guard and not has_pytest_items)
+
+
+def run_script_tests(test_files: list, verbose: bool = False) -> int:
+    """Run standalone test scripts, honouring the 0 pass / 2 skip / 1 fail
+    convention that ledmatrix-plugins' own runner established.
+
+    Scripts opt into skipping by printing "SKIP: <reason>" and exiting 2 --
+    a script that needs a tty or an LED matrix is not a regression.
+    """
+    env = dict(os.environ)
+    # Prepend rather than setdefault. An inherited PYTHONPATH -- a developer's
+    # shell, a tox run, another checkout -- otherwise wins outright, and the
+    # subprocess imports a different copy of the core than the one under test.
+    # That is exactly the failure ledmatrix-plugins#467 describes, and it is
+    # invisible: the tests pass or fail against a tree nobody meant to test.
+    inherited = env.get("PYTHONPATH")
+    env["PYTHONPATH"] = (f"{PROJECT_ROOT}{os.pathsep}{inherited}"
+                         if inherited else str(PROJECT_ROOT))
+    env["LEDMATRIX_CORE"] = str(PROJECT_ROOT)
+
+    passed = skipped = failed = 0
+    failures = []
+    for path in test_files:
+        try:
+            # Fixed interpreter (sys.executable) plus a test path this script
+            # discovered by globbing the repo; argument list, no shell, so
+            # nothing is word-split or expanded. Same suppression pair the
+            # rest of the repo uses for this shape (see permission_utils.py).
+            proc = subprocess.run(  # noqa: S603  # nosec B603 - no shell invoked (list-form argv)  # nosemgrep
+                [sys.executable, str(path)],  # nosemgrep
+                cwd=str(Path(path).parent),
+                capture_output=True, text=True, env=env,
+                stdin=subprocess.DEVNULL, timeout=300,
+            )
+            rc = proc.returncode
+            tail = " | ".join((proc.stdout or proc.stderr or "").strip().splitlines()[-2:])[:200]
+        except subprocess.TimeoutExpired:
+            rc, tail = 1, "timed out after 300s"
+        if rc == 0:
+            passed += 1
+            label = "pass"
+        elif rc == 2:
+            skipped += 1
+            label = "SKIP"
+        else:
+            failed += 1
+            label = "FAIL"
+            failures.append(f"{Path(path).name}: exit {rc} | {tail}")
+        if verbose or rc != 0:
+            print(f"  [{label}] {Path(path).name}" + (f" -- {tail}" if rc != 0 else ""))
+
+    print(f"\n{passed} passed, {skipped} skipped, {failed} failed (scripts)")
+    for f in failures:
+        print(f"  - {f}", file=sys.stderr)
+    return 1 if failed else 0
+
+
 def run_unittest_tests(test_files: list, verbose: bool = False) -> int:
     """
     Run tests using unittest.
@@ -186,11 +262,16 @@ def main():
             print("No test files found in plugins directory")
         return 0
     
-    print(f"Found {len(test_files)} test file(s)")
+    scripts = [f for f in test_files if _is_script_style(f)]
+    modules = [f for f in test_files if f not in scripts]
+
+    print(f"Found {len(test_files)} test file(s)"
+          + (f" -- {len(modules)} collectable, {len(scripts)} standalone script(s)"
+             if scripts else ""))
     for test_file in test_files:
         print(f"  - {test_file}")
     print()
-    
+
     # Determine runner
     runner = args.runner
     if runner == 'auto':
@@ -199,12 +280,21 @@ def main():
             runner = 'pytest'
         except ImportError:
             runner = 'unittest'
-    
-    # Run tests
-    if runner == 'pytest':
-        return run_pytest_tests(test_files, args.verbose, args.coverage)
-    else:
-        return run_unittest_tests(test_files, args.verbose)
+
+    # Standalone scripts cannot be collected by pytest or unittest -- run them
+    # as the scripts they are. Doing this rather than silently collecting zero
+    # items is the whole point: this runner used to report success having
+    # executed nothing.
+    rc = 0
+    if scripts:
+        rc |= run_script_tests(scripts, args.verbose)
+
+    if modules:
+        if runner == 'pytest':
+            rc |= run_pytest_tests(modules, args.verbose, args.coverage)
+        else:
+            rc |= run_unittest_tests(modules, args.verbose)
+    return rc
 
 
 if __name__ == '__main__':

scripts/scroll_speeds.py

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

scripts/sports_scroll_check.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""Drive a sports scoreboard scroll on the panel and report what it did.
+
+The eight sports scoreboards scroll through ``src/common/sports_scroll.py``,
+and that path is per-league opt-in: a rig showing static game cards never
+constructs a SportsScrollDisplay at all, so nothing about its pacing can be
+observed from a normal run. This drives it directly, with synthetic games, so
+the pacing can be measured without changing anyone's configuration.
+
+What it checks is what the shared resolver is supposed to buy:
+
+* the requested speed lands on a whole number of pixels per refresh
+* the frame hold that makes that true is published to the display manager
+* frames actually arrive at the interval the hold implies
+
+    sudo systemctl stop ledmatrix
+    sudo python3 scripts/sports_scroll_check.py --seconds 20
+    sudo systemctl start ledmatrix
+
+Like scripts/scroll_speeds.py, this never starts or stops the display service
+itself -- that is left to the caller, so a crash here cannot leave the panel
+dark.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import statistics
+import subprocess  # nosec B404 - list-form argv only, no shell  # nosemgrep
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from PIL import Image  # noqa: E402
+
+from src.common.sports_scroll import SportsScrollDisplay  # noqa: E402
+from src.display_manager import DisplayManager  # noqa: E402
+
+
+class _Check(SportsScrollDisplay):
+    """A scoreboard whose cards are plain blocks -- pacing is what matters."""
+
+    SCROLL_LEAGUE_KEYS = ("nfl",)
+
+    def prepare_scroll_content(self, games, game_type, leagues, rankings_cache=None):
+        width = self.display_height * 2
+        cards = []
+        for i, _ in enumerate(games):
+            card = Image.new("RGB", (width, self.display_height), (0, 0, 0))
+            shade = 40 + (i * 37) % 180
+            for x in range(2, width - 2):
+                for y in range(2, self.display_height - 2):
+                    card.putpixel((x, y), (shade, 90, 220 - shade // 2))
+            cards.append(card)
+        self._current_games = list(games)
+        self._current_game_type = game_type
+        self._current_leagues = list(leagues)
+        self.scroll_helper.create_scrolling_image(content_items=cards, item_gap=24)
+        return bool(cards)
+
+
+class _HoldSpy:
+    """Records what the scroll publishes, without changing what it does."""
+
+    def __init__(self, display_manager):
+        self.dm = display_manager
+        self.calls = []
+        self._real = display_manager.set_scrolling_state
+
+    def __enter__(self):
+        def spy(is_scrolling, frame_hold=1):
+            self.calls.append((is_scrolling, frame_hold))
+            return self._real(is_scrolling, frame_hold=frame_hold)
+        self.dm.set_scrolling_state = spy
+        return self
+
+    def __exit__(self, *exc):
+        self.dm.set_scrolling_state = self._real
+        return False
+
+
+MESSAGE = """ledmatrix is running and owns the panel's GPIO.
+
+Stop it first, or this run can leave the display dark:
+
+    sudo systemctl stop ledmatrix
+    sudo python3 scripts/sports_scroll_check.py
+    sudo systemctl start ledmatrix
+
+Use --fallback to check the pacing logic without the panel, or --force if
+you really mean it."""
+
+
+def _refuse_if_the_service_is_running(force):
+    """Refuse to touch the panel while ledmatrix has it.
+
+    rpi-rgb-led-matrix configures GPIO directions and the hardware PWM inside
+    RGBMatrix(), and on the root check it calls exit() from C -- no cleanup.
+    Do that while the service is driving those same pins and the panel goes
+    dark while the service carries on rendering happily: fresh framebuffer,
+    every pixel lit, "RGB Matrix initialized successfully", nothing in the log.
+    A restart brings it back, but only once you work out that is what happened.
+
+    The module docstring says to stop the service first. This makes it true.
+    """
+    if force:
+        return
+    try:
+        active = subprocess.run(  # nosec B603 B607 - hardcoded systemctl args  # nosemgrep
+            ["systemctl", "is-active", "ledmatrix"],
+            capture_output=True, text=True).stdout.strip()
+    except OSError:
+        return  # not a systemd box; nothing to protect
+    if active == "active":
+        sys.exit(MESSAGE)
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--seconds", type=float, default=20.0)
+    ap.add_argument("--speed", type=float, default=None,
+                    help="px/s to request; default is the module's own")
+    ap.add_argument("--games", type=int, default=6)
+    ap.add_argument("--force", action="store_true",
+                    help="run even though the display service is up. It owns "
+                         "the GPIO; expect a dark panel until you restart it.")
+    ap.add_argument("--fallback", action="store_true",
+                    help="run without the panel. Driving the real matrix needs "
+                         "root; this checks everything except the vsync pacing "
+                         "-- what speed resolves to, that the hold is published, "
+                         "and that it is released afterwards.")
+    args = ap.parse_args()
+
+    if not args.fallback:
+        _refuse_if_the_service_is_running(args.force)
+
+    root = Path(__file__).resolve().parent.parent
+    config = json.loads((root / "config" / "config.json").read_text(encoding="utf-8"))
+
+    display_manager = DisplayManager(config, force_fallback=args.fallback)
+    settings = {} if args.speed is None else {
+        "nfl": {"scroll_settings": {"scroll_speed": args.speed}}}
+
+    display = _Check(display_manager, settings, global_config=config)
+    resolved = display._scroll_settings
+    print("resolved: %s" % resolved.describe())
+    print("frame hold: %d refresh(es) per frame" % resolved.frame_hold)
+    if resolved.warning:
+        print("warning: %s" % resolved.warning)
+
+    display.prepare_scroll_content(
+        [{"id": "g%d" % i} for i in range(args.games)], "live", ["nfl"])
+
+    gaps, drawn = [], 0
+    last = None
+    with _HoldSpy(display_manager) as spy:
+        started = time.perf_counter()
+        while time.perf_counter() - started < args.seconds:
+            if not display.display_scroll_frame():
+                break
+            now = time.perf_counter()
+            if last is not None:
+                gaps.append((now - last) * 1000.0)
+            last = now
+            drawn += 1
+        display.clear()
+
+    if not gaps:
+        sys.exit("no frames were drawn -- the scroll never started")
+
+    gaps.sort()
+    expected = 1000.0 * resolved.frame_hold / (resolved.crisp.refresh_hz
+                                               if resolved.crisp else 100.0)
+    print("\n%d frames in %.1fs -> %.1f fps" % (
+        drawn, args.seconds, drawn / args.seconds))
+    print("frame gap  median %.2fms  p95 %.2fms  max %.2fms  (hold implies %.2fms)"
+          % (statistics.median(gaps), gaps[int(len(gaps) * 0.95)], gaps[-1], expected))
+
+    holds = {h for on, h in spy.calls if on}
+    print("published while scrolling: frame_hold=%s" % (sorted(holds) or "NOTHING"))
+    print("released on clear: %s" % any(not on for on, _ in spy.calls))
+    print("display manager hold now: %d (1 means released)"
+          % getattr(display_manager, "_frame_hold", -1))
+
+    if not holds:
+        sys.exit("FAIL: the scroll never told the core it was scrolling")
+    if holds != {resolved.frame_hold}:
+        sys.exit("FAIL: published %s but resolved %d" % (holds, resolved.frame_hold))
+    print("\nOK: the resolved hold reached the panel and was released after")
+
+
+if __name__ == "__main__":
+    main()

scripts/utils/README.md

@@ -9,6 +9,8 @@ This directory contains utility scripts for maintenance and system operations.
 - **`wifi_monitor_daemon.py`** - Background daemon that monitors WiFi/Ethernet connection and manages access point mode
 - **`cleanup_venv.sh`** - Cleans up Python virtual environment files
 - **`clear_python_cache.sh`** - Clears Python cache files (__pycache__, *.pyc, etc.)
+- **`pixlet_config_editor.sh`** - Opens Pixlet's own config UI for one installed Starlark app
+- **`apply_dns_single_request.sh`** - Adds `options single-request` to the resolver (run by `ledmatrix-dns-fix.service`)
 
 ## Usage
 
@@ -25,3 +27,31 @@ This script is typically called by the systemd service (`ledmatrix-web.service`)
 ### WiFi Monitor Daemon
 This daemon is typically run as a systemd service (`ledmatrix-wifi-monitor.service`) and automatically manages WiFi access point mode based on network connectivity.
 
+
+### Pixlet Config Editor
+Run it when you want Pixlet's own config form for a Starlark app -- live
+render preview, cascading dropdowns -- rather than the LEDMatrix one.
+
+```bash
+./scripts/utils/pixlet_config_editor.sh                 # list installed apps
+./scripts/utils/pixlet_config_editor.sh penndot_signs   # edit, on localhost:8080
+```
+
+Deliberately not a service. It stops the display for the length of the
+session and `pixlet serve` listens with no authentication, so it should only
+be running while you are actually editing. It backs the config up first and
+restarts the display on exit, however it exits.
+
+It binds loopback only, with no flag to change that: anything that can reach
+`pixlet serve` can rewrite the app's config, and a printed warning is not
+access control. To edit from another machine, forward the port -- SSH does the
+authenticating and nothing is left listening on the LAN:
+
+```bash
+ssh -L 8080:localhost:8080 pi@ledpi.local
+```
+
+### Apply DNS Single-Request Fix
+Installed and run by `ledmatrix-dns-fix.service`; see `systemd/README.md`.
+Safe to run by hand (`sudo ./scripts/utils/apply_dns_single_request.sh`) and
+idempotent.

scripts/utils/apply_dns_single_request.sh

@@ -0,0 +1,94 @@
+#!/bin/bash
+#
+# Add `options single-request` to the system resolver configuration.
+#
+# glibc's getaddrinfo() sends the A and AAAA queries for a name in
+# parallel on one socket. Some routers answer the A query and drop the
+# AAAA one, so the resolver waits out its full timeout -- about five
+# seconds -- before returning an address that was already available.
+# Disabling IPv6 in the kernel does not help: the resolver still asks.
+#
+# `single-request` makes it send the two queries one after the other,
+# which those routers answer correctly. Anything on the matrix that
+# calls an external API pays that five seconds per lookup otherwise, and
+# a Starlark app with a render timeout will simply fail instead.
+#
+# Idempotent, and safe to run on a machine that does not need it. Run by
+# ledmatrix-dns-fix.service on every boot, because whatever manages
+# resolv.conf regenerates it and drops the option again.
+#
+# Usage: sudo ./scripts/utils/apply_dns_single_request.sh
+
+set -eu
+
+OPTION="options single-request"
+RESOLVCONF_TAIL="/etc/resolvconf/resolv.conf.d/tail"
+RESOLV_CONF="/etc/resolv.conf"
+
+log() { echo "[dns-single-request] $*"; }
+
+already_applied() {
+    grep -qs "^${OPTION}\$" "$1"
+}
+
+# resolvconf regenerates /etc/resolv.conf from these fragments, so the
+# tail file is the only place an addition survives. Prefer it when the
+# directory exists, whether or not resolvconf has run yet.
+if [ -d "$(dirname "$RESOLVCONF_TAIL")" ]; then
+    if already_applied "$RESOLVCONF_TAIL"; then
+        log "already present in $RESOLVCONF_TAIL"
+    else
+        echo "$OPTION" >> "$RESOLVCONF_TAIL"
+        log "added to $RESOLVCONF_TAIL"
+    fi
+    # Only a missing resolvconf is ignorable. If it is present and the
+    # regeneration fails, /etc/resolv.conf still lacks the option, and
+    # reporting success would be a lie.
+    if command -v resolvconf >/dev/null 2>&1; then
+        if ! resolvconf -u; then
+            log "resolvconf -u failed; $RESOLV_CONF was not regenerated"
+            exit 1
+        fi
+    fi
+fi
+
+# systemd-resolved owns its stub file and rewrites anything appended to it,
+# and `single-request` is a glibc resolv.conf option with no resolved.conf
+# equivalent -- so there is nothing this script can do here. Exit non-zero:
+# the unit would otherwise record success while the workaround is inactive,
+# which is the failure mode this whole script exists to avoid.
+if [ -L "$RESOLV_CONF" ] && readlink -f "$RESOLV_CONF" | grep -q "systemd"; then
+    log "$RESOLV_CONF is managed by systemd-resolved."
+    log "'options single-request' is a glibc resolv.conf option and has no"
+    log "resolved.conf equivalent, so it cannot be applied on this host."
+    log "If external API calls are slow, the workaround is to stop using the"
+    log "systemd-resolved stub (see 'man systemd-resolved', NSS/resolv.conf modes)."
+    exit 1
+fi
+
+if already_applied "$RESOLV_CONF"; then
+    log "already present in $RESOLV_CONF"
+    exit 0
+fi
+
+if [ ! -w "$RESOLV_CONF" ] && [ -e "$RESOLV_CONF" ]; then
+    log "cannot write $RESOLV_CONF (run with sudo?)"
+    exit 1
+fi
+
+# A NetworkManager-generated resolv.conf is regenerated on every connection
+# change, not only at boot -- and this unit is oneshot with RemainAfterExit,
+# so it will not re-run within the same boot to put the option back. Say so
+# rather than implying the fix is permanent. Nothing is silently swallowed:
+# the append below still happens and still works until the next renewal.
+if grep -qs "Generated by NetworkManager" "$RESOLV_CONF" \
+        && [ ! -d "$(dirname "$RESOLVCONF_TAIL")" ]; then
+    log "NOTE: $RESOLV_CONF is generated by NetworkManager and has no"
+    log "resolvconf tail directory to write to. The option is being added, but"
+    log "NetworkManager will drop it on the next connection renewal, and this"
+    log "unit does not run again until the next boot. If lookups go slow again"
+    log "before a reboot, re-run this script."
+fi
+
+echo "$OPTION" >> "$RESOLV_CONF"
+log "added to $RESOLV_CONF"

scripts/utils/pixlet_config_editor.sh

@@ -0,0 +1,223 @@
+#!/bin/bash
+#
+# Edit an installed Starlark app's config in Pixlet's own config UI.
+#
+# `pixlet serve` runs the app for real, so its form has working cascading
+# dropdowns and option lists fetched live -- useful for an app whose choices
+# only exist at runtime, or when you want to see the render change as you
+# type. The LEDMatrix config form now reads the same runtime schema (see
+# PixletRenderer.extract_schema_via_pixlet), so reach for this when you want
+# Pixlet's live preview, not because the normal form is missing options.
+#
+# Deliberately a script you run and then Ctrl+C, not a service: it stops the
+# display for the length of the session, and `pixlet serve` listens on a port
+# with no authentication. Nothing here should be listening when you are not
+# actually editing.
+#
+# Usage:
+#   ./scripts/utils/pixlet_config_editor.sh            # list installed apps
+#   ./scripts/utils/pixlet_config_editor.sh <app_id>   # edit
+#
+# 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}"
+# 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:-}"
+
+list_apps() {
+    if [ -d "$APPS_DIR" ]; then
+        find "$APPS_DIR" -maxdepth 1 -mindepth 1 -type d -printf '  %f\n' 2>/dev/null | sort
+    fi
+}
+
+if [ -z "$APP_ID" ]; then
+    echo "Usage: $0 <app_id>"
+    echo ""
+    echo "Installed apps:"
+    list_apps || true
+    [ -n "$(list_apps)" ] || echo "  (none found in $APPS_DIR)"
+    exit 1
+fi
+
+APP_DIR="$APPS_DIR/$APP_ID"
+if [ ! -d "$APP_DIR" ]; then
+    echo "No such app: $APP_ID"
+    echo ""
+    echo "Installed apps:"
+    list_apps
+    exit 1
+fi
+
+STAR_FILE=$(find "$APP_DIR" -maxdepth 1 -iname "*.star" | head -1)
+if [ -z "$STAR_FILE" ]; then
+    echo "No .star file found in $APP_DIR"
+    exit 1
+fi
+
+# Same search order the plugin itself uses: the bundled binary for this
+# architecture first, then PATH -- so this works on an install that never put
+# pixlet on PATH.
+find_pixlet() {
+    local arch bundled
+    case "$(uname -s)-$(uname -m)" in
+        Linux-aarch64|Linux-arm64)  arch="pixlet-linux-arm64" ;;
+        Linux-x86_64|Linux-amd64)   arch="pixlet-linux-amd64" ;;
+        Darwin-arm64)               arch="pixlet-darwin-arm64" ;;
+        Darwin-x86_64)              arch="pixlet-darwin-amd64" ;;
+        *)                          arch="" ;;
+    esac
+    bundled="$PROJECT_ROOT_DIR/bin/pixlet/$arch"
+    if [ -n "$arch" ] && [ -x "$bundled" ]; then
+        echo "$bundled"
+        return 0
+    fi
+    command -v pixlet 2>/dev/null || return 1
+}
+
+PIXLET_BIN=$(find_pixlet) || {
+    echo "Pixlet not found. Install it with:"
+    echo "  ./scripts/download_pixlet.sh"
+    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"
+    echo "Backed up existing config to $CONFIG_FILE.backup"
+else
+    echo "{}" > "$CONFIG_FILE"
+fi
+
+DISPLAY_WAS_RUNNING=false
+if systemctl is-active --quiet ledmatrix 2>/dev/null; then
+    DISPLAY_WAS_RUNNING=true
+fi
+
+# Restart the display however this exits -- Ctrl+C, an error, or pixlet
+# dying on its own. Leaving the panel dark because the editor crashed is the
+# 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"
+    fi
+    echo "Your config as it was before this session: $CONFIG_FILE.backup"
+}
+trap cleanup EXIT INT TERM
+
+if [ "$DISPLAY_WAS_RUNNING" = true ]; then
+    echo "Stopping the display service so it does not read config.json mid-write..."
+    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://$REACH_HOST:$PORT/"
+echo ""
+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"
+# `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" &
+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__':

scripts/validate_skin.py

@@ -27,6 +27,8 @@ sys.path.insert(0, str(PROJECT_ROOT))
 
 from PIL import Image, ImageDraw, ImageFont  # noqa: E402
 
+from src.common.font_layout import load_truetype  # noqa: E402
+
 FIXTURES_DIR = PROJECT_ROOT / "src" / "skin_system" / "fixtures"
 MODES = ("live", "recent", "upcoming")
 SPORTS = ("baseball", "basketball", "football", "hockey")
@@ -52,12 +54,12 @@ class FixtureHost:
         try:
             press = str(PROJECT_ROOT / "assets/fonts/PressStart2P-Regular.ttf")
             small = str(PROJECT_ROOT / "assets/fonts/4x6-font.ttf")
-            fonts['score'] = ImageFont.truetype(press, 10)
-            fonts['time'] = ImageFont.truetype(press, 8)
-            fonts['team'] = ImageFont.truetype(press, 8)
-            fonts['status'] = ImageFont.truetype(small, 6)
-            fonts['detail'] = ImageFont.truetype(small, 6)
-            fonts['rank'] = ImageFont.truetype(press, 10)
+            fonts['score'] = load_truetype(press, 10)
+            fonts['time'] = load_truetype(press, 8)
+            fonts['team'] = load_truetype(press, 8)
+            fonts['status'] = load_truetype(small, 6)
+            fonts['detail'] = load_truetype(small, 6)
+            fonts['rank'] = load_truetype(press, 10)
         except IOError:
             default = ImageFont.load_default()
             for key in ('score', 'time', 'team', 'status', 'detail', 'rank'):

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
@@ -15,6 +16,7 @@ from typing import Any, Dict, List, Optional, Tuple
 import pytz
 import requests
 from PIL import Image, ImageDraw, ImageFont
+from src.common.font_layout import load_truetype
 from requests.adapters import HTTPAdapter
 from urllib3.util.retry import Retry
 
@@ -166,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
@@ -449,12 +458,12 @@ class SportsCore(ABC):
         press_start = self._resolve_font_path("PressStart2P-Regular.ttf")
         four_by_six = self._resolve_font_path("4x6-font.ttf")
         try:
-            fonts['score'] = ImageFont.truetype(press_start, 10)
-            fonts['time'] = ImageFont.truetype(press_start, 8)
-            fonts['team'] = ImageFont.truetype(press_start, 8)
-            fonts['status'] = ImageFont.truetype(four_by_six, 6) # Using 4x6 for status
-            fonts['detail'] = ImageFont.truetype(four_by_six, 6) # Added detail font
-            fonts['rank'] = ImageFont.truetype(press_start, 10)
+            fonts['score'] = load_truetype(press_start, 10)
+            fonts['time'] = load_truetype(press_start, 8)
+            fonts['team'] = load_truetype(press_start, 8)
+            fonts['status'] = load_truetype(four_by_six, 6) # Using 4x6 for status
+            fonts['detail'] = load_truetype(four_by_six, 6) # Added detail font
+            fonts['rank'] = load_truetype(press_start, 10)
             self.logger.info("Successfully loaded fonts")
         except OSError:
             # Name the directory we searched: the usual cause is an install
@@ -559,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:
@@ -603,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:
@@ -1031,7 +1048,7 @@ class SportsCore(ABC):
             if os.path.exists(font_path):
                 # Try loading as TTF first (works for both TTF and some BDF files with PIL)
                 if font_path.lower().endswith('.ttf'):
-                    font = ImageFont.truetype(font_path, font_size)
+                    font = load_truetype(font_path, font_size)
                     self.logger.debug(f"Loaded font: {font_name} at size {font_size}")
                     self._font_cache[cache_key] = font
                     return font
@@ -1049,7 +1066,7 @@ class SportsCore(ABC):
                     # correct one: the newer copies call truetype() on a BDF at
                     # any size (which simply fails) or refuse BDF outright.
                     try:
-                        font = ImageFont.truetype(font_path, font_size)
+                        font = load_truetype(font_path, font_size)
                         self.logger.debug(f"Loaded BDF font: {font_name} at size {font_size}")
                         self._font_cache[cache_key] = font
                         return font
@@ -1061,7 +1078,7 @@ class SportsCore(ABC):
                             self._bdf_native_size_cache[font_path] = native_size
                         if native_size and native_size != font_size:
                             try:
-                                font = ImageFont.truetype(font_path, native_size)
+                                font = load_truetype(font_path, native_size)
                                 self.logger.debug(
                                     f"Loaded BDF font: {font_name} at its native size {native_size} "
                                     f"(requested {font_size} isn't a valid strike for this file)"
@@ -1089,7 +1106,7 @@ class SportsCore(ABC):
             _resolve_font_family_alias(base_default))
         try:
             if os.path.exists(default_font_path):
-                font = ImageFont.truetype(default_font_path, font_size)
+                font = load_truetype(default_font_path, font_size)
             else:
                 self.logger.warning("Default font not found, using PIL default")
                 font = ImageFont.load_default()

src/cache/disk_cache.py

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

src/common/__init__.py

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

src/common/font_layout.py

@@ -0,0 +1,43 @@
+"""One text layout engine, everywhere.
+
+``PIL.ImageFont.truetype`` picks its layout engine at load time: Raqm when the
+host Pillow was built with libraqm, Basic otherwise. The two disagree about
+fractional glyph advances, so the *same* Pillow version renders the *same*
+string differently depending on a build option of the host.
+
+That is invisible for ``PressStart2P-Regular.ttf`` at 8px, whose advances are
+whole pixels either way — which is why most of the fleet's golden images
+matched on every machine. It is not invisible for ``4x6-font.ttf`` at 6px,
+where the advances are fractional: glyph positions drift cumulatively along a
+run, and the committed goldens for geochron, of-the-day, christmas-countdown
+and ledmatrix-weather's almanac passed on the machine that generated them and
+failed everywhere else (ChuckBuilds/ledmatrix-plugins#371, #375, #378, #391).
+
+Pinning the Basic engine makes a render depend on the font file and the size,
+and nothing else. Basic gives up complex-script shaping (Arabic, Indic) and
+kerning pairs; neither applies to the bitmap-grid faces this project draws
+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.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Union
+
+from PIL import ImageFont
+
+#: The engine every core font load pins. Named once so the reason above has a
+#: single referent, and so a future change is one line.
+LAYOUT_ENGINE = ImageFont.Layout.BASIC
+
+
+def load_truetype(font: Union[str, Any], size: int, **kwargs: Any) -> ImageFont.FreeTypeFont:
+    """``ImageFont.truetype`` with the layout engine pinned.
+
+    Same signature and same exceptions as the PIL call it replaces, so it is a
+    drop-in at every call site.
+    """
+    kwargs.setdefault("layout_engine", LAYOUT_ENGINE)
+    return ImageFont.truetype(font, size, **kwargs)

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,21 @@ 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
+
+
 
 # Well above any real team logo; bounds what a remote URL can write to disk.
 MAX_LOGO_BYTES = 10 * 1024 * 1024
@@ -56,6 +72,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()
@@ -100,9 +124,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
             
@@ -179,6 +213,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 +309,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]:

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_config.py

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

src/common/scroll_helper.py

@@ -16,6 +16,7 @@ Features:
 """
 
 import logging
+import math
 import time
 from typing import Optional, Dict, Any
 from PIL import Image
@@ -29,6 +30,49 @@ except ImportError:
     HAS_SCIPY = False
 
 
+def frame_stats(frame_times: list) -> Dict[str, Any]:
+    """Summary statistics over one window of frame durations (seconds).
+
+    Split out of log_frame_rate() so the arithmetic can be tested without a
+    clock. Median and p95 are the real ones: the median takes both middle
+    samples on an even window, and p95 is nearest-rank, so a 100-frame window
+    reports the 95th sorted sample rather than the 96th. That matters twice
+    over, because the median is also the threshold the stall and skip counts
+    are measured against.
+    """
+    window = sorted(frame_times)
+    n = len(window)
+    median = (window[n // 2] if n % 2
+              else (window[n // 2 - 1] + window[n // 2]) / 2.0)
+    mean = sum(window) / n
+    # Anything past 1.5x the median missed a panel refresh; anything under
+    # half of it never reached the panel at all (dirty tracking skipped the
+    # swap, so the frame did not wait for vsync).
+    return {
+        "frames": n,
+        "fps": (1.0 / mean) if mean > 0 else 0.0,
+        "median": median,
+        "p95": window[max(0, math.ceil(0.95 * n) - 1)],
+        "max": window[-1],
+        "min": window[0],
+        "stalls": sum(1 for f in window if f > median * 1.5),
+        "skips": sum(1 for f in window if f < median * 0.5),
+    }
+
+
+def format_frame_stats(frame_times: list) -> str:
+    """The one-line rendering of frame_stats(), in milliseconds."""
+    s = frame_stats(frame_times)
+    n = s["frames"]
+    return (
+        f"{s['fps']:.1f} fps over {n} frames | "
+        f"median {s['median'] * 1000:.2f}ms p95 {s['p95'] * 1000:.2f}ms "
+        f"max {s['max'] * 1000:.2f}ms min {s['min'] * 1000:.2f}ms | "
+        f"stalls {s['stalls']} ({100.0 * s['stalls'] / n:.1f}%) "
+        f"skips {s['skips']} ({100.0 * s['skips'] / n:.1f}%)"
+    )
+
+
 class ScrollHelper:
     """
     Helper class for scrolling text and image content on LED displays.
@@ -75,12 +119,26 @@ class ScrollHelper:
         # Pre-allocated buffer for output frame (reused to avoid allocations)
         self._frame_buffer: Optional[np.ndarray] = None
         
-        # Sub-pixel scrolling settings (disabled - using high FPS integer scrolling instead)
-        self.sub_pixel_scrolling = False  # Disabled - use high frame rate for smoothness
+        # Sub-pixel scrolling: OFF by default, and that is deliberate.
+        # Blending renders a half-step by mixing two adjacent columns 50/50.
+        # On a high-resolution screen that reads as smooth motion; on a coarse
+        # LED matrix showing pixel-font text it does not. A one-pixel stroke
+        # becomes two half-brightness pixels, so frames alternate between crisp
+        # and smeared and the text appears to shimmer and jump a pixel ahead --
+        # tested on a 2x128x64 panel and clearly worse than integer stepping.
+        #
+        # The rule this display obeys: motion is smooth when it advances a
+        # whole number of pixels per refresh. Anything slower must either
+        # blend (blur) or repeat frames (judder); blending is the worse of the
+        # two here. Vegas mode still opts in via set_sub_pixel_scrolling().
+        self.sub_pixel_scrolling = False
         self._last_integer_position = 0  # Cache for integer position to avoid repeated calculations
         
         # Frame-based scrolling settings
-        self.frame_based_scrolling = False  # If True, use scroll_delay to throttle and move scroll_speed pixels
+        self.frame_based_scrolling = False
+        #: Whole pixels to advance per presented frame, or None to pace
+        #: off elapsed time. See set_pixels_per_frame.
+        self.fixed_pixels_per_frame = None  # If True, use scroll_delay to throttle and move scroll_speed pixels
         self.last_step_time = 0.0  # Track last step time for frame-based throttling
         
         # Time tracking for scroll updates
@@ -105,6 +163,9 @@ class ScrollHelper:
         self.last_frame_time = time.time()
         self.last_fps_log_time = time.time()
         self.frame_times = []
+        # Every frame time since the last stats line, so the 5s summary can
+        # report the tail rather than one arbitrary sample. Cleared on log.
+        self._window: list = []
         
         # Scrolling state management
         self.is_scrolling = False
@@ -237,26 +298,44 @@ class ScrollHelper:
             self.last_progress_log_time = current_time
         
         # Update scroll position
-        if self.frame_based_scrolling:
+        if self.fixed_pixels_per_frame:
+            # One presented frame, one fixed whole-pixel step. No clock is
+            # consulted, so no jitter reaches the position and every frame
+            # moves the eye by the same amount. See set_pixels_per_frame.
+            pixels_to_move = self.fixed_pixels_per_frame
+            self.last_step_time = current_time
+        elif self.frame_based_scrolling:
             # Frame-based: move fixed amount when scroll_delay has passed
             # This matches stock ticker behavior: move pixels, then wait scroll_delay
             # Initialize last_step_time on first call to prevent huge initial jump
             if self.last_step_time == 0.0:
                 self.last_step_time = current_time
             
-            # Check if scroll_delay has passed
-            time_since_last_step = current_time - self.last_step_time
-            if time_since_last_step >= self.scroll_delay:
-                # Move pixels (can move multiple steps if lag occurred, but cap to prevent huge jumps)
-                steps = int(time_since_last_step / self.scroll_delay)
-                # Cap at reasonable number to prevent huge jumps from lag
-                max_steps = max(1, int(0.04 / self.scroll_delay))  # Limit to 0.04s (2 steps at 50 FPS) for smoother scrolling
-                steps = min(steps, max_steps)
-                pixels_to_move = self.scroll_speed * steps
-                # Update last_step_time, preserving fractional delay for smooth timing
-                self.last_step_time = current_time - (time_since_last_step % self.scroll_delay)
+            # Frame-based mode advances by elapsed time, exactly like the
+            # time-based branch below, at the same configured speed
+            # (scroll_speed px per scroll_delay seconds).
+            #
+            # It used to step discretely: 0, 1 or 2 whole pixels depending on
+            # whether a wall clock had passed scroll_delay. Plugins set
+            # scroll_delay to the target frame period, so that comparison sits
+            # exactly on its own threshold and the decision flips on sub-
+            # millisecond jitter -- a frame a hair early moved nothing and
+            # rendered an identical frame, a frame a hair late moved two
+            # pixels. Rounding the step count fixed the stalls but still
+            # discarded the remainder, so the error never corrected.
+            #
+            # Accumulating elapsed time keeps position exactly proportional to
+            # real time: jitter shifts a pixel boundary by a fraction of a
+            # frame instead of flipping a whole step, and nothing is lost or
+            # gained. This is what the one visibly smooth scroller on the
+            # hardware (the stock ticker) was already doing by virtue of never
+            # enabling frame-based mode.
+            if self.scroll_delay > 0:
+                pixels_per_second = self.scroll_speed / self.scroll_delay
             else:
-                pixels_to_move = 0.0
+                pixels_per_second = self.scroll_speed * 100.0
+            pixels_to_move = pixels_per_second * delta_time
+            self.last_step_time = current_time
         else:
             # Time-based: move based on time delta (correct speed over time)
             # scroll_speed is pixels per second
@@ -909,6 +988,13 @@ class ScrollHelper:
         Args:
             speed: Scroll speed (interpretation depends on frame_based_scrolling mode)
         """
+        # A speed set directly is a request to pace off that speed, so drop any
+        # fixed per-frame step left by an earlier configure(). scroll_config
+        # calls this first and set_pixels_per_frame second, so the crisp path
+        # is unaffected; what this protects is a legacy caller changing speed
+        # on a helper that scroll_config had already put in fixed-step mode,
+        # where the new speed would otherwise be silently ignored.
+        self.fixed_pixels_per_frame = None
         if self.frame_based_scrolling:
             # In frame-based mode, clamp to reasonable pixels per frame (0.1-5)
             # Higher values cause visible jumps - 1-2 pixels/frame is ideal for smoothness
@@ -929,6 +1015,35 @@ class ScrollHelper:
         self.scroll_delay = max(0.001, min(1.0, delay))
         self.logger.debug(f"Scroll delay set to: {self.scroll_delay}")
     
+    def set_pixels_per_frame(self, pixels) -> None:
+        """Advance exactly `pixels` per presented frame, ignoring the clock.
+
+        Pass None to go back to pacing off elapsed time.
+
+        Smooth motion is not a frame-rate property. The strip has to advance
+        the same number of WHOLE pixels every frame, and deriving that from a
+        wall clock cannot deliver it: the position accumulates
+        ``speed * delta_time`` and is then truncated to a pixel, so any jitter
+        in delta_time lands either side of an integer boundary. Measured on
+        hardware at a rock-steady 100.0 fps, individual frames still ranged
+        5.6ms to 15.2ms -- 0.57px to 1.44px of movement -- and 53% of frames
+        advanced by something other than one pixel: about half moved nothing
+        at all and then jumped two. That is the micro-stutter, and it survived
+        every frame-timing fix because frame timing was never the problem.
+
+        It is worst precisely at a crisp speed. At 100 px/s on a 100Hz panel
+        the accumulator sits exactly on integer boundaries, so sub-millisecond
+        jitter flips it either way and the motion beats at around 50Hz.
+
+        Stepping per frame is only correct because SwapOnVSync blocks until
+        the panel has taken the frame, which makes the frame count a truer
+        clock than time.time(). Before the swap was locked to vsync this would
+        have run at whatever speed the loop happened to spin at.
+        """
+        self.fixed_pixels_per_frame = int(pixels) if pixels else None
+        self.logger.debug("Fixed step set to: %s px/frame",
+                          self.fixed_pixels_per_frame)
+
     def set_target_fps(self, fps: float) -> None:
         """
         Set the target frames per second for scrolling.
@@ -1017,18 +1132,25 @@ class ScrollHelper:
         # Keep only last 100 frames for average
         if len(self.frame_times) > 100:
             self.frame_times.pop(0)
+
+        # Every frame since the last log, not just the last 100 and not just
+        # the one that happens to land on the 5s boundary. The old line
+        # reported a single instantaneous sample -- roughly 1 frame in 500 --
+        # which cannot see a stall that hits 1% of frames, and reported it
+        # next to an average that hides the same stall by construction (a 2ms
+        # duplicate and a 21ms double-wait mean exactly 10ms). Chasing scroll
+        # judder needs the tail, so keep the window and report percentiles.
+        self._window.append(frame_time)
         
         # Log FPS every 5 seconds to avoid spam
         if current_time - self.last_fps_log_time >= 5.0:
-            avg_frame_time = sum(self.frame_times) / len(self.frame_times)
-            avg_fps = 1.0 / avg_frame_time if avg_frame_time > 0 else 0
-            instant_fps = 1.0 / frame_time if frame_time > 0 else 0
-            
-            self.logger.info(f"Scroll frame stats - Avg FPS: {avg_fps:.1f}, "
-                           f"Current FPS: {instant_fps:.1f}, "
-                           f"Frame time: {frame_time*1000:.2f}ms")
+            self.logger.info(
+                "Scroll frame stats - %s",
+                format_frame_stats(self._window or [frame_time]),
+            )
             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

@@ -17,10 +17,13 @@ deliberate difference is `crisp_size`, which takes the seven-plugin guard
 the extra guard only stops a None size raising TypeError.
 """
 
+import logging
 from datetime import datetime, timezone
 from typing import Any, Dict, Optional, Tuple
 from zoneinfo import ZoneInfo
 
+logger = logging.getLogger(__name__)
+
 __all__ = [
     "ELEMENT_FOR_FONT", "FAVORITE_RESULT_COLOR_DEFAULTS", "FONT_NAME_ALIASES",
     "FONT_PIXEL_GRID", "MONTH_ABBR", "WEEKDAY_ABBR",
@@ -395,7 +398,14 @@ def schema_font_size(schema_path: str, element_key) -> Optional[int]:
                 size = spec.get('properties', {}).get('font_size', {}).get('default')
                 if size is not None:
                     cache[key] = int(size)
-        except Exception:
+        except Exception as exc:
+            # See sports_shared._schema_font_size: an unreadable schema
+            # silently disables the pixel-grid snap for every element.
+            # Built once per schema path, so this cannot repeat per frame.
+            logger.warning(
+                "could not read %s (%s: %s); font sizes will skip their "
+                "pixel grid snap and may render a pixel narrow",
+                schema_path, type(exc).__name__, exc)
             cache = {}
         _SCHEMA_FONT_SIZE_CACHE[schema_path] = cache
     return cache.get(element_key)

src/common/sports_scroll.py

@@ -43,6 +43,7 @@ from typing import Any, Dict, List, Optional
 
 from PIL import Image
 
+from src.common import scroll_config
 from src.common.scroll_helper import ScrollHelper
 
 logger = logging.getLogger(__name__)
@@ -58,13 +59,9 @@ DEFAULT_SCROLL_SETTINGS: Dict[str, Any] = {
     "dynamic_duration": True,
 }
 
-#: Bounds on the px/second -> px/frame conversion, applied before the helper
-#: sees the value. FPS is *not* clamped here — ScrollHelper.set_target_fps
-#: already does that, and a second copy of the range would drift from it.
-MIN_PIXELS_PER_FRAME = 0.1
-MAX_PIXELS_PER_FRAME = 5.0
-
 #: Pacing to assume when scroll_delay is 0, i.e. the plugin has not set one.
+#: Only used to interpret this module's own px/frame config shape; the speed
+#: bounds and the px/s -> px/frame conversion belong to scroll_config now.
 ASSUMED_FPS_WHEN_UNPACED = 100.0
 
 
@@ -236,51 +233,75 @@ class SportsScrollDisplay:
         """Apply config to the scroll helper. Safe to call again after a change."""
         settings = self._get_scroll_settings()
 
-        scroll_speed = self._coerce_float(settings.get("scroll_speed"), 50.0)
-        scroll_delay = self._coerce_float(settings.get("scroll_delay"), 0.01)
         dynamic_duration = bool(settings.get("dynamic_duration", True))
-
-        self.scroll_helper.set_scroll_delay(scroll_delay)
         self.scroll_helper.set_dynamic_duration_settings(
             enabled=dynamic_duration,
             min_duration=settings.get("min_duration", 30),
             max_duration=settings.get("max_duration", 600),
             buffer=0.2,  # ensure the strip clears the panel completely
         )
-        # Frame-based scrolling: motion advances per rendered frame rather than
-        # per wall-clock second, which is what makes the pacing stable.
-        self.scroll_helper.set_frame_based_scrolling(True)
 
-        # Config states speed in px/second; frame-based mode wants px/frame.
-        if scroll_delay > 0:
-            pixels_per_frame = scroll_speed * scroll_delay
-        else:
-            pixels_per_frame = scroll_speed / ASSUMED_FPS_WHEN_UNPACED
-        pixels_per_frame = max(
-            MIN_PIXELS_PER_FRAME, min(MAX_PIXELS_PER_FRAME, pixels_per_frame)
-        )
-        self.scroll_helper.set_scroll_speed(pixels_per_frame)
+        # Speed goes through scroll_config, which every other scrolling plugin
+        # already uses. What must NOT happen is handing it this module's
+        # settings dict: the two read the same key names with different
+        # meanings, and the collision is a factor of 1/scroll_delay.
+        #
+        #   sports_scroll: scroll_speed is px/SECOND; scroll_delay is only the
+        #                  frame period used to reach px/frame.
+        #   scroll_config: scroll_speed is px per STEP, so px/s = speed/delay.
+        #
+        # Passing {"scroll_speed": 50.0, "scroll_delay": 0.01} straight through
+        # resolves to 5000 px/s (clamped to 500) instead of 50. So this module
+        # keeps ownership of reading its own config -- _get_scroll_settings
+        # merges the league overrides -- and hands the resolver a plain px/s.
+        pixels_per_second = self._resolve_pixels_per_second(settings)
 
-        effective_pps = (
-            pixels_per_frame / scroll_delay
-            if scroll_delay > 0
-            else pixels_per_frame * ASSUMED_FPS_WHEN_UNPACED
+        resolved = scroll_config.configure(
+            self.scroll_helper,
+            plugin_config=None,
+            global_config=self.global_config,
+            default_pixels_per_second=pixels_per_second,
+            display_manager=self.display_manager,
+            plugin_logger=self.logger,
+            refresh_hz=self._resolve_refresh_hz(),
         )
+        self._scroll_settings = resolved
         self.logger.info(
-            f"ScrollHelper configured: {pixels_per_frame:.2f} px/frame, "
-            f"delay={scroll_delay}s (effective {effective_pps:.1f} px/s from "
-            f"{scroll_speed} px/s config), dynamic_duration={dynamic_duration}"
+            "ScrollHelper configured: %s (requested %.1f px/s), "
+            "dynamic_duration=%s",
+            resolved.describe(),
+            pixels_per_second, dynamic_duration,
         )
 
-        # The reason this module exists upstream: the bundled copies hardcode
-        # ~100 FPS via scroll_delay and never consult the global target.
-        # No hasattr guard here, unlike the plugin copies: they probe because
-        # they may run against an older core, whereas this module ships in the
-        # same release as the ScrollHelper it calls. The helper clamps.
-        target_fps = self._resolve_target_fps()
-        if target_fps:
-            self.scroll_helper.set_target_fps(target_fps)
-            self.logger.info(f"Target FPS set to {target_fps}")
+    def _resolve_pixels_per_second(self, settings: Dict[str, Any]) -> float:
+        """This module's config shape, expressed as plain pixels per second.
+
+        ``scroll_speed`` is already px/s here. ``scroll_delay`` only matters
+        when a caller supplied px/frame instead, which the 0 case covers.
+        """
+        scroll_speed = self._coerce_float(settings.get("scroll_speed"), 50.0)
+        scroll_delay = self._coerce_float(settings.get("scroll_delay"), 0.01)
+        if scroll_delay <= 0:
+            return scroll_speed * ASSUMED_FPS_WHEN_UNPACED
+        return scroll_speed
+
+    def _resolve_refresh_hz(self) -> Optional[float]:
+        """The panel refresh the crisp ladder should be computed against.
+
+        Prefers the configured hardware refresh. Falls back to the global
+        ``target_fps``/``scroll_target_fps`` this module has always honoured:
+        under the old model that key *was* the rate frames were presented at,
+        so it is the faithful translation for anyone who set it. Returning
+        None lets scroll_config apply its own default.
+        """
+        hardware = scroll_config.refresh_hz_from_config(self.global_config)
+        if hardware and hardware != scroll_config.DEFAULT_REFRESH_HZ:
+            return hardware
+        return self._resolve_target_fps() or hardware or None
+
+    def _scroll_frame_hold(self) -> int:
+        """Refreshes to hold each frame for, from the resolved settings."""
+        return getattr(getattr(self, "_scroll_settings", None), "frame_hold", 1)
 
     # ------------------------------------------------------------------
     # Frame pumping
@@ -305,6 +326,16 @@ class SportsScrollDisplay:
             if not visible:
                 return False
 
+            # Tell the core the panel is scrolling, and for how many
+            # refreshes to hold each frame. Without this the frame hold is
+            # never applied -- so a speed the ladder made crisp still presents
+            # a new frame every refresh and judders -- and, because deferred
+            # updates only run while nothing is scrolling, core would run
+            # blocking work in the middle of this scroll.
+            if hasattr(self.display_manager, "set_scrolling_state"):
+                self.display_manager.set_scrolling_state(
+                    True, frame_hold=self._scroll_frame_hold())
+
             self.display_manager.image = visible
             self.display_manager.update_display()
             self._frame_count += 1
@@ -331,7 +362,19 @@ class SportsScrollDisplay:
 
     def is_scroll_complete(self) -> bool:
         """True when the strip has scrolled fully past the panel."""
-        return self.scroll_helper.is_scroll_complete()
+        complete = self.scroll_helper.is_scroll_complete()
+        if complete:
+            self._release_scrolling_state()
+        return complete
+
+    def _release_scrolling_state(self) -> None:
+        """Tell the core this display is no longer scrolling.
+
+        The scrolling flag and the frame hold are global to the display
+        manager, so leaving them set holds every other plugin's frames too.
+        """
+        if hasattr(self.display_manager, "set_scrolling_state"):
+            self.display_manager.set_scrolling_state(False)
 
     def reset_scroll(self) -> None:
         """Return the strip to its starting position, keeping the content."""
@@ -349,6 +392,7 @@ class SportsScrollDisplay:
         self._vegas_content_items = []
         self._is_scrolling = False
         self._scroll_start_time = None
+        self._release_scrolling_state()
         self.logger.debug("Scroll display cleared")
 
     # ------------------------------------------------------------------

src/common/sports_shared.py

@@ -86,6 +86,7 @@ from typing import Any, ClassVar, Dict, List, Optional, Tuple
 import pytz
 import requests
 from PIL import Image, ImageDraw, ImageFont
+from src.common.font_layout import load_truetype
 
 logger = logging.getLogger(__name__)
 
@@ -211,17 +212,52 @@ class SportsCoreSharedMixin:
             return desired
         return max(grid, int(round(float(desired) / grid)) * grid)
 
+    #: Absolute path of this plugin's directory, declared by the plugin
+    #: itself. The mixin cannot work it out -- see _plugin_dir.
+    _PLUGIN_DIR: ClassVar[Optional[str]] = None
+
     def _plugin_dir(self) -> Optional[str]:
-        """Directory of the plugin that defines this class.
+        """Directory of the plugin that owns this instance.
 
         In sports.py these methods could just use ``__file__``. Here that is
-        src/common/, so the plugin's own directory has to be recovered from the
-        instance. ``type(self).__module__`` alone is not enough: SportsCore is
-        an ABC, so a subclass built with ``type(name, bases, ns)`` -- which the
-        plugins' own tests do -- reports its module as "abc". Walking the MRO
-        steps past those synthetic classes to the first one whose module sits
-        next to a config_schema.json, which is the real plugin.
+        src/common/, so the directory has to come from the plugin.
+
+        It is TOLD, not deduced. The first version walked the MRO for a class
+        whose module sits beside a config_schema.json. That works when a test
+        imports the plugin itself, and returns None under the real loader, for
+        a specific reason worth recording:
+
+            PluginLoader._namespace_plugin_modules renames every bare module a
+            plugin brought in (sports, game_renderer, ...) to
+            "_plg_<plugin_id>_<module>" and REMOVES the bare entry, so two
+            plugins owning a module of the same name cannot collide.
+
+        The class still reports ``__module__ == "sports"``, but
+        ``sys.modules["sports"]`` no longer exists, so the walk finds no
+        __file__ and falls off the end. The failure was silent and expensive:
+
+            _plugin_dir()       -> None
+            _schema_font_size() -> None for every element
+            -> a configured size equal to the schema default stops looking
+               like a default and is treated as a deliberate user choice
+            -> the snap to the font's pixel grid is skipped
+            -> 4x6-font.ttf renders at 6 instead of 7: 3px-wide glyphs
+               instead of 4px
+
+        On a 256x64 panel that made the odds, the team records and the date row
+        hard to read. It was found by a user counting pixels on the panel. No
+        gate here caught it: the tests imported plugins directly and the
+        safety harness loads them its own way, so neither reproduced the
+        loader's renaming.
+
+        The MRO walk stays as a fallback for hosts that declare no
+        _PLUGIN_DIR -- the plugins' own probe harnesses build classes with
+        ``type()`` -- but it is no longer the primary answer.
         """
+        declared = getattr(self, "_PLUGIN_DIR", None)
+        if declared and os.path.isfile(os.path.join(declared, "config_schema.json")):
+            return declared
+
         for cls in type(self).__mro__:
             module = sys.modules.get(getattr(cls, "__module__", ""), None)
             path = getattr(module, "__file__", None)
@@ -253,7 +289,23 @@ class SportsCoreSharedMixin:
                     size = spec.get('properties', {}).get('font_size', {}).get('default')
                     if size is not None:
                         cache[key] = int(size)
-            except Exception:
+            except Exception as exc:
+                # Say so. An unreadable schema is not cosmetic: every element's
+                # configured size then stops matching "the schema default", is
+                # treated as a deliberate user choice, and skips the snap to the
+                # font's pixel grid -- which renders 4x6-font.ttf at 6 instead
+                # of 7, a 3px-wide glyph instead of 4px. That shipped once,
+                # silently, and was found by a user counting pixels on a photo
+                # of the panel.
+                #
+                # Logged, not raised: a missing schema must not stop a plugin
+                # rendering. The cache is built once per class, so this cannot
+                # repeat per frame.
+                logger.warning(
+                    "%s: could not read config_schema.json (%s: %s); every font "
+                    "size will be treated as user-chosen and will skip its pixel "
+                    "grid snap. Font sizes may render a pixel narrow.",
+                    type(self).__name__, type(exc).__name__, exc)
                 cache = {}
             self.__class__._SCHEMA_FONT_SIZES = cache
         return cache.get(element_key)
@@ -661,11 +713,11 @@ class SportsCoreSharedMixin:
                 while size > grid:
                     if probe.textlength(
                             self._SCORE_PROBE_TEXT,
-                            font=ImageFont.truetype(path, size)) <= budget:
+                            font=load_truetype(path, size)) <= budget:
                         break
                     size -= grid
                 if size != getattr(fonts['score'], 'size', size):
-                    fonts['score'] = ImageFont.truetype(path, size)
+                    fonts['score'] = load_truetype(path, size)
                     self._score_grew = True
 
             if not self._score_grew and not self._user_chose_size('score_text') \
@@ -685,7 +737,7 @@ class SportsCoreSharedMixin:
                     if _size <= current:
                         continue
                     _path = _resolve_font_path(f"assets/fonts/{_name}")
-                    _candidate = ImageFont.truetype(_path, _size)
+                    _candidate = load_truetype(_path, _size)
                     if probe.textlength(self._SCORE_PROBE_TEXT,
                                         font=_candidate) <= budget:
                         fonts['score'] = _candidate
@@ -700,7 +752,7 @@ class SportsCoreSharedMixin:
                 if ceiling and size >= ceiling:
                     size = max(grid, ceiling - grid)
                 if size != getattr(fonts['time'], 'size', size):
-                    fonts['time'] = ImageFont.truetype(path, size)
+                    fonts['time'] = load_truetype(path, size)
         except Exception:
             self.logger.debug("Headline font scaling skipped", exc_info=True)
         return fonts

src/common/text_helper.py

@@ -10,6 +10,7 @@ from pathlib import Path
 from typing import Dict, List, Optional, Tuple, Union
 
 from PIL import Image, ImageDraw, ImageFont
+from src.common.font_layout import load_truetype
 
 # Shared throwaway draw surface for measuring text without a target canvas.
 _measure_draw = ImageDraw.Draw(Image.new("RGB", (1, 1)))
@@ -60,7 +61,7 @@ class TextHelper:
                 size = config['size']
                 
                 if font_path.exists():
-                    font = ImageFont.truetype(str(font_path), size)
+                    font = load_truetype(str(font_path), size)
                     fonts[font_name] = font
                     self.logger.debug(f"Loaded font: {font_name} ({font_path}, size {size})")
                 else:

src/display_controller.py

@@ -198,6 +198,10 @@ class DisplayController:
         # the main run loop reconciles (loads/unloads) on its own thread so
         # mutating available_modes never races with rendering.
         self._pending_plugin_reconcile = False
+        # Monotonic stamp of the last mailbox disk read; see
+        # _poll_on_demand_requests. None means "never polled", so the first
+        # call always goes through.
+        self._last_on_demand_poll: Optional[float] = None
         self.on_demand_active = False
         self.on_demand_mode: Optional[str] = None
         self.on_demand_modes: List[str] = []  # All modes for the on-demand plugin
@@ -303,40 +307,8 @@ class DisplayController:
 
             # Check for on-demand plugin filter from cache
             on_demand_config = self.cache_manager.get('display_on_demand_config', max_age=3600)
-            on_demand_plugin_id = on_demand_config.get('plugin_id') if on_demand_config else None
+            enabled_plugins = self._select_startup_plugins(discovered_plugins, on_demand_config)
 
-            if on_demand_plugin_id:
-                logger.info("On-demand mode detected during initialization: filtering to plugin '%s' only", on_demand_plugin_id)
-                # Only load the on-demand plugin, but ensure it's enabled
-                if on_demand_plugin_id not in discovered_plugins:
-                    error_msg = f"On-demand plugin '{on_demand_plugin_id}' not found in discovered plugins"
-                    logger.error(error_msg)
-                    logger.warning("Falling back to normal mode (all enabled plugins)")
-                    on_demand_plugin_id = None
-                    enabled_plugins = [p for p in discovered_plugins if self.config.get(p, {}).get('enabled', False)]
-                else:
-                    plugin_config = self.config.get(on_demand_plugin_id, {})
-                    was_disabled = not plugin_config.get('enabled', False)
-                    if was_disabled:
-                        logger.info("Temporarily enabling plugin '%s' for on-demand mode", on_demand_plugin_id)
-                        if on_demand_plugin_id not in self.config:
-                            self.config[on_demand_plugin_id] = {}
-                        self.config[on_demand_plugin_id]['enabled'] = True
-                    enabled_plugins = [on_demand_plugin_id]
-                    # Set on-demand state from cached config
-                    self.on_demand_active = True
-                    self.on_demand_plugin_id = on_demand_plugin_id
-                    self.on_demand_mode = on_demand_config.get('mode')
-                    self.on_demand_duration = on_demand_config.get('duration')
-                    self.on_demand_pinned = on_demand_config.get('pinned', False)
-                    self.on_demand_requested_at = on_demand_config.get('requested_at')
-                    self.on_demand_expires_at = on_demand_config.get('expires_at')
-                    self.on_demand_status = 'active'
-                    self.on_demand_schedule_override = True
-                    logger.info("On-demand mode: loading only plugin '%s'", on_demand_plugin_id)
-            else:
-                enabled_plugins = [p for p in discovered_plugins if self.config.get(p, {}).get('enabled', False)]
-            
             # Count enabled plugins for progress tracking
             enabled_count = len(enabled_plugins)
             logger.info("Loading %d enabled plugin(s) in parallel (max 4 concurrent)...", enabled_count)
@@ -1267,12 +1239,119 @@ class DisplayController:
         self.on_demand_schedule_override = False
         self._publish_on_demand_state()
 
+    #: Shortest gap between mailbox disk reads. This is called after every
+    #: frame -- about 125 times a second on a scrolling mode -- and the read
+    #: below is deliberately uncached, so without a floor it was 125 disk reads
+    #: per second to find nothing. An on-demand request comes from a person
+    #: clicking in the web UI, so a quarter second of latency is not
+    #: perceptible, and it cuts the read rate by 30x.
+    ON_DEMAND_POLL_INTERVAL = 0.25
+
+    def _select_startup_plugins(self, discovered_plugins: List[str],
+                                on_demand_config: Optional[Dict[str, Any]]) -> List[str]:
+        """Which plugins to load at startup, restoring on-demand state if any.
+
+        Every normally-enabled plugin loads, on-demand or not. Loading only the
+        on-demand plugin left every other plugin unavailable for the rest of
+        the process's life whenever the service was restarted while on-demand
+        was still active -- and a restart during an on-demand session is
+        routine, since that is how updates and config changes are applied. The
+        panel came back cycling that one plugin's modes and nothing else, with
+        no way out but clearing the on-demand cache by hand.
+
+        On-demand still resumes on its saved mode; this only widens what gets
+        loaded, so normal rotation has somewhere to return to when it ends.
+        A plugin that is disabled in config but named by the on-demand request
+        is still enabled and added, since otherwise the mode being resumed
+        would have nothing behind it.
+        """
+        enabled_plugins = [p for p in discovered_plugins
+                           if self.config.get(p, {}).get('enabled', False)]
+
+        on_demand_plugin_id = on_demand_config.get('plugin_id') if on_demand_config else None
+        if not on_demand_plugin_id:
+            return enabled_plugins
+
+        if on_demand_plugin_id not in discovered_plugins:
+            logger.error("On-demand plugin '%s' not found in discovered plugins",
+                         on_demand_plugin_id)
+            logger.warning("Falling back to normal mode (all enabled plugins)")
+            return enabled_plugins
+
+        if not self.config.get(on_demand_plugin_id, {}).get('enabled', False):
+            logger.info("Temporarily enabling plugin '%s' for on-demand mode", on_demand_plugin_id)
+            self.config.setdefault(on_demand_plugin_id, {})['enabled'] = True
+            if on_demand_plugin_id not in enabled_plugins:
+                enabled_plugins.append(on_demand_plugin_id)
+
+        # Restore on-demand state from the cached request so it resumes.
+        self.on_demand_active = True
+        self.on_demand_plugin_id = on_demand_plugin_id
+        self.on_demand_mode = on_demand_config.get('mode')
+        self.on_demand_duration = on_demand_config.get('duration')
+        self.on_demand_pinned = on_demand_config.get('pinned', False)
+        self.on_demand_requested_at = on_demand_config.get('requested_at')
+        self.on_demand_expires_at = on_demand_config.get('expires_at')
+        self.on_demand_status = 'active'
+        self.on_demand_schedule_override = True
+        logger.info("On-demand mode detected during initialization: resuming on plugin '%s'; "
+                    "all %d enabled plugin(s) still load normally",
+                    on_demand_plugin_id, len(enabled_plugins))
+        return enabled_plugins
+
+    def _consume_on_demand_request(self, request_id: str) -> None:
+        """Remove the request we just handled from the mailbox.
+
+        Leaving it on disk meant a restart replayed the previous request: the
+        fresh controller read it, activated it and cached it, so the request
+        the caller had just made was ignored and the panel silently showed the
+        earlier plugin.
+
+        Compare before deleting. The web process can post a newer request
+        between the read and this delete; an unconditional delete threw that
+        one away and it was never processed -- the user's second click did
+        nothing. Re-reading uncached and only deleting our own request_id
+        leaves a newer request in the mailbox for the next poll instead.
+
+        This narrows the window rather than closing it: a request landing
+        between the re-read and the delete is still lost. Closing it properly
+        needs an atomic claim (a rename, or a compare-and-delete primitive)
+        that the cache layer does not currently offer, so the honest fix is a
+        smaller window plus this note, not a bigger lock. For start requests
+        processed_id still guards against reprocessing if the delete fails.
+        """
+        try:
+            current = self.cache_manager.get('display_on_demand_request',
+                                             max_age=3600, memory_ttl=0)
+            if not current or current.get('request_id') == request_id:
+                self.cache_manager.delete('display_on_demand_request')
+            else:
+                logger.debug("Newer on-demand request %s arrived while processing "
+                             "%s; leaving it in the mailbox",
+                             current.get('request_id'), request_id)
+        except (OSError, AttributeError, KeyError) as err:
+            logger.debug("Could not clear the on-demand request mailbox: %s", err)
+
     def _poll_on_demand_requests(self) -> None:
         """Poll cache for new on-demand requests from external controllers."""
+        now = time.monotonic()
+        if (self._last_on_demand_poll is not None
+                and now - self._last_on_demand_poll < self.ON_DEMAND_POLL_INTERVAL):
+            return
+        self._last_on_demand_poll = now
+
         try:
             # Use a long max_age (1 hour) to ensure requests aren't expired before processing
-            # The request_id check prevents duplicate processing
-            request = self.cache_manager.get('display_on_demand_request', max_age=3600)
+            # The request_id check prevents duplicate processing.
+            #
+            # memory_ttl=0 is required, not optional: this key is a mailbox the
+            # web process writes and this process reads. get() defaults the
+            # in-memory TTL to max_age, so without it the first request read was
+            # pinned in memory for the full hour and every later poll returned
+            # that stale copy -- meaning no second on-demand request was honoured
+            # for an hour, while the API still reported success.
+            request = self.cache_manager.get('display_on_demand_request',
+                                             max_age=3600, memory_ttl=0)
         except (OSError, RuntimeError, ValueError, TypeError) as err:
             logger.error("Failed to read on-demand request: %s", err, exc_info=True)
             return
@@ -1299,8 +1378,15 @@ class DisplayController:
                 logger.debug("Stop request %s received but on-demand is not active", request_id)
                 # Still update request_id to acknowledge the request
                 self.on_demand_request_id = request_id
+            # Stop requests are deliberately exempt from the request_id/
+            # processed_id guards above, so that a second click stops a mode
+            # that a race left running. Consuming the mailbox is therefore the
+            # only thing that ends the request: without it the same stop was
+            # re-read and re-processed on every poll, forever, logging at
+            # ON_DEMAND_POLL_INTERVAL for the life of the process.
+            self._consume_on_demand_request(request_id)
             return
-        
+
         # For start requests, check if already processed
         if request_id == self.on_demand_request_id:
             logger.debug("On-demand start request %s already processed (instance check)", request_id)
@@ -1318,7 +1404,8 @@ class DisplayController:
         # Mark as processed BEFORE processing (to prevent duplicate processing)
         self.cache_manager.set('display_on_demand_processed_id', request_id, ttl=3600)
         self.on_demand_request_id = request_id
-        
+        self._consume_on_demand_request(request_id)
+
         if action == 'start':
             logger.info("Processing on-demand start request for plugin: %s", request.get('plugin_id'))
             self._activate_on_demand(request)
@@ -1360,34 +1447,28 @@ class DisplayController:
                 return modes[0]
         return plugin_id
 
-    def _populate_on_demand_modes_from_plugin(self) -> None:
+    def _on_demand_modes_for_plugin(self, plugin_id: str) -> List[str]:
+        """Every loaded display mode belonging to `plugin_id`, in rotation order.
+
+        Live modes that actually have content lead, then the rest, then live
+        modes with nothing to show -- so an on-demand request for a sports
+        plugin opens on a game in progress rather than an empty live screen.
+        Returns an empty list when the plugin has no loaded modes.
         """
-        Populate on_demand_modes from the on-demand plugin's display modes.
-        Called after plugin loading completes when on-demand state is restored from cache.
-        """
-        if not self.on_demand_active or not self.on_demand_plugin_id:
-            return
-        
-        plugin_id = self.on_demand_plugin_id
-        
-        # Get all modes for this plugin
         plugin_modes = self.plugin_display_modes.get(plugin_id, [])
         if not plugin_modes:
             # Fallback: find all modes that belong to this plugin
             plugin_modes = [mode for mode, pid in self.mode_to_plugin_id.items() if pid == plugin_id]
-        
+
         # Filter to only include modes that exist in plugin_modes
         available_plugin_modes = [m for m in plugin_modes if m in self.plugin_modes]
-        
         if not available_plugin_modes:
-            logger.warning("No valid display modes found for on-demand plugin '%s' after restoration", plugin_id)
-            self.on_demand_modes = []
-            return
-        
+            return []
+
         # Prioritize live modes if they exist and have content
         live_modes = [m for m in available_plugin_modes if m.endswith('_live')]
         other_modes = [m for m in available_plugin_modes if not m.endswith('_live')]
-        
+
         # Check if live modes have content
         live_with_content = []
         for live_mode in live_modes:
@@ -1398,18 +1479,57 @@ class DisplayController:
                         live_with_content.append(live_mode)
                 except Exception:
                     pass
-        
+
         # Build mode list: live modes with content first, then other modes, then live modes without content
         if live_with_content:
             ordered_modes = live_with_content + other_modes + [m for m in live_modes if m not in live_with_content]
         else:
             # No live content, skip live modes
             ordered_modes = other_modes
-        
+
         if not ordered_modes:
             # Only live modes available but no content - use them anyway
             ordered_modes = live_modes
-        
+
+        return ordered_modes
+
+    def _apply_on_demand_pin(self, ordered_modes: List[str], resolved_mode: Optional[str],
+                             pinned: bool) -> List[str]:
+        """Narrow an on-demand rotation to the single requested mode when pinned.
+
+        `pinned` reaches the controller from the API and was stored and
+        republished but never acted on, so a pinned request still rotated
+        through every mode the resolved plugin owns. That is the right default
+        for a sports plugin, whose modes are views of one subject
+        (nfl_live/nfl_recent/nfl_upcoming), and the wrong one for a plugin
+        whose modes are unrelated -- each Starlark app is its own widget, so
+        asking for one and getting all of them is not what was requested.
+        """
+        if not pinned or not resolved_mode or resolved_mode not in ordered_modes:
+            return ordered_modes
+        return [resolved_mode]
+
+    def _populate_on_demand_modes_from_plugin(self) -> None:
+        """
+        Populate on_demand_modes from the on-demand plugin's display modes.
+        Called after plugin loading completes when on-demand state is restored from cache.
+        """
+        if not self.on_demand_active or not self.on_demand_plugin_id:
+            return
+
+        plugin_id = self.on_demand_plugin_id
+
+        ordered_modes = self._on_demand_modes_for_plugin(plugin_id)
+        if not ordered_modes:
+            logger.warning("No valid display modes found for on-demand plugin '%s' after restoration", plugin_id)
+            self.on_demand_modes = []
+            return
+
+        # A restart must not silently un-pin: the pin is part of the request
+        # being resumed, and it is restored from the same cached config above.
+        ordered_modes = self._apply_on_demand_pin(
+            ordered_modes, self.on_demand_mode, self.on_demand_pinned)
+
         self.on_demand_modes = ordered_modes
         # Set index to match the restored mode if available, otherwise start at 0
         if self.on_demand_mode and self.on_demand_mode in ordered_modes:
@@ -1464,46 +1584,14 @@ class DisplayController:
         if resolved_mode in self.available_modes:
             self.current_mode_index = self.available_modes.index(resolved_mode)
 
-        # Get all modes for this plugin
-        plugin_modes = self.plugin_display_modes.get(resolved_plugin_id, [])
-        if not plugin_modes:
-            # Fallback: find all modes that belong to this plugin
-            plugin_modes = [mode for mode, pid in self.mode_to_plugin_id.items() if pid == resolved_plugin_id]
-        
-        # Filter to only include modes that exist in plugin_modes
-        available_plugin_modes = [m for m in plugin_modes if m in self.plugin_modes]
-        
-        if not available_plugin_modes:
+        ordered_modes = self._on_demand_modes_for_plugin(resolved_plugin_id)
+        if not ordered_modes:
             logger.error("No valid display modes found for plugin '%s'", resolved_plugin_id)
             self._set_on_demand_error("no-modes")
             return
-        
-        # Prioritize live modes if they exist and have content
-        live_modes = [m for m in available_plugin_modes if m.endswith('_live')]
-        other_modes = [m for m in available_plugin_modes if not m.endswith('_live')]
-        
-        # Check if live modes have content
-        live_with_content = []
-        for live_mode in live_modes:
-            plugin_instance = self.plugin_modes.get(live_mode)
-            if plugin_instance and hasattr(plugin_instance, 'has_live_content'):
-                try:
-                    if plugin_instance.has_live_content():
-                        live_with_content.append(live_mode)
-                except Exception:
-                    pass
-        
-        # Build mode list: live modes with content first, then other modes, then live modes without content
-        if live_with_content:
-            ordered_modes = live_with_content + other_modes + [m for m in live_modes if m not in live_with_content]
-        else:
-            # No live content, skip live modes
-            ordered_modes = other_modes
-        
-        if not ordered_modes:
-            # Only live modes available but no content - use them anyway
-            ordered_modes = live_modes
-        
+
+        ordered_modes = self._apply_on_demand_pin(ordered_modes, resolved_mode, pinned)
+
         self.on_demand_active = True
         self.on_demand_mode = resolved_mode  # Keep for backward compatibility
         self.on_demand_modes = ordered_modes
@@ -2081,7 +2169,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
@@ -2404,7 +2499,17 @@ 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:
                                     with self._display_lock_or_skip(plugin_id) as can_display:
                                         if can_display:
@@ -2425,11 +2530,26 @@ class DisplayController:
                                 # Multi-display sync: send follower frame after each render
                                 self._send_follower_frame(manager_to_display)
 
-                                time.sleep(display_interval)
                                 self._tick_plugin_updates()
                                 self._poll_on_demand_requests()
                                 self._check_on_demand_expiration()
 
+                                # Pace to the frame deadline rather than sleeping a flat
+                                # interval on top of the work. display() has already
+                                # blocked on the panel's vsync by this point, so an
+                                # unconditional sleep is added to a wait that already
+                                # happened. Measured on a 2x128x64 chain at
+                                # limit_refresh_rate_hz=100: ~4ms of render plus a flat
+                                # 8ms put each iteration at ~12ms against a 10ms refresh
+                                # grid, so every swap missed a refresh and the loop
+                                # settled at 50fps where display_interval asks for 125 --
+                                # and with zero headroom, ~14% of frames slipped a
+                                # further refresh, which is what reads as scroll stutter.
+                                _remaining = display_interval - (time.perf_counter() - _frame_start)
+                                # Yield even when the frame overran its budget, so plugin
+                                # update threads and the web UI are not starved of the GIL.
+                                time.sleep(_remaining if _remaining > 0 else 0.001)
+
                                 if self.current_display_mode != active_mode:
                                     logger.debug("Mode changed during high-FPS loop, breaking early")
                                     break
@@ -2460,6 +2580,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_manager.py

@@ -34,6 +34,7 @@ else:
 from contextlib import contextmanager
 from pathlib import Path
 from PIL import Image, ImageDraw, ImageFont
+from src.common.font_layout import load_truetype
 import threading
 import time
 from collections import OrderedDict
@@ -55,6 +56,31 @@ from src.common.permission_utils import (
 logger = logging.getLogger(__name__)
 logger.setLevel(logging.INFO)  # Set to INFO level
 
+#: The strike 5x7.bdf is drawn at. FreeType renders a BDF at its own fixed
+#: size regardless, but a Face needs an active size before its metrics --
+#: and therefore get_font_height() -- report anything but 0.
+_CALENDAR_FONT_PX = 7
+
+
+def _bdf_native_size(face) -> int:
+    """The pixel height a BDF Face declares, or 0 if it does not say.
+
+    Used only to rescue a Face that was built without ``set_char_size``, so a
+    zero line height never reaches layout code.
+    """
+    try:
+        sizes = getattr(face, "available_sizes", None) or []
+        if sizes:
+            return int(getattr(sizes[0], "height", 0) or 0)
+    except (AttributeError, IndexError, TypeError, ValueError) as exc:
+        # This runs on the measurement path for a face the caller already
+        # holds, so a malformed strike table must degrade to "unknown" rather
+        # than take the display down. Say which face, so a font that is
+        # actually broken is diagnosable rather than silently 8px.
+        logger.debug("Could not read BDF strike size from %r: %s", face, exc)
+    return 0
+
+
 
 class _LogicalMatrix:
     """Proxy that reports a logical (per-screen) size for a physical matrix.
@@ -240,6 +266,14 @@ class DisplayManager:
         self._update_lock = threading.RLock()
         
         # Scrolling state tracking for graceful updates
+        # How many panel refreshes each pushed frame is held for. 1 means a new
+        # frame every refresh. Higher values are how a scroll runs slower than
+        # one pixel per refresh WITHOUT fractional pixel positions: the panel
+        # keeps refreshing at full rate (so flicker is unchanged) but motion
+        # advances a whole pixel every Nth refresh instead of every one.
+        # See src/common/scroll_config.py and scripts/scroll_speeds.py.
+        self._frame_hold = 1
+
         self._scrolling_state = {
             'is_scrolling': False,
             'last_scroll_activity': 0,
@@ -364,11 +398,12 @@ class DisplayManager:
             # Create image with the (logical) display dimensions
             self.image = Image.new('RGB', (self.matrix.width, self.matrix.height))
             self.draw = ImageDraw.Draw(self.image)
+            self.draw.fontmode = "1"  # 1-bit text: the panel has no partial brightness, so AA only smears glyphs.
             logger.info(f"Image canvas created with dimensions: {self.matrix.width}x{self.matrix.height}")
             
             # Initialize font with Press Start 2P
             try:
-                self.font = ImageFont.truetype("assets/fonts/PressStart2P-Regular.ttf", 8)
+                self.font = load_truetype("assets/fonts/PressStart2P-Regular.ttf", 8)
                 logger.info("Initial Press Start 2P font loaded successfully")
             except Exception as e:
                 logger.error(f"Failed to load initial font: {e}")
@@ -403,6 +438,7 @@ class DisplayManager:
 
             self.image = Image.new('RGB', (fallback_width, fallback_height))
             self.draw = ImageDraw.Draw(self.image)
+            self.draw.fontmode = "1"  # 1-bit text: the panel has no partial brightness, so AA only smears glyphs.
             # Simple fallback visualization so web UI shows a realistic canvas
             try:
                 self.draw.rectangle([0, 0, fallback_width - 1, fallback_height - 1], outline=(255, 0, 0))
@@ -547,19 +583,33 @@ class DisplayManager:
                     pass
 
     def _fitting_font(self, lines, width):
-        """The largest font from the usual ladder that fits every line."""
+        """The largest font from the usual ladder that fits every line.
+
+        The ladder ends at 4x6 at 5px because a full dotted-quad address --
+        "255.255.255.255", the widest this screen ever shows -- is 66px at
+        6px and a 64px panel has 62 to give it. That used to squeak in only
+        because the measurement depended on which text layout engine the host
+        Pillow had; with the engine pinned it does not, so the rung the
+        worst case actually needs is here rather than implied.
+        """
         candidates = [self.font,
-                      ("assets/fonts/4x6-font.ttf", 6)]
+                      ("assets/fonts/4x6-font.ttf", 6),
+                      ("assets/fonts/4x6-font.ttf", 5)]
+        narrowest = None
         for candidate in candidates:
             try:
                 font = candidate
                 if isinstance(candidate, tuple):
-                    font = ImageFont.truetype(candidate[0], candidate[1])
+                    font = load_truetype(candidate[0], candidate[1])
+                narrowest = font
                 if all(self.draw.textlength(t, font=font) <= width for t in lines):
                     return font
             except (OSError, ValueError, AttributeError):
                 continue
-        return self.font
+        # Nothing fit. Return the smallest face that loaded, not self.font --
+        # falling back to the widest option is how "Initializing" ran off the
+        # side of a 64px panel in the first place.
+        return narrowest or self.font
 
     def _draw_startup_banner(self, lines, width: int, height: int) -> None:
         """Centre `lines` over whatever the test pattern already drew.
@@ -705,6 +755,7 @@ class DisplayManager:
             # self.image, so swapping the buffer below is enough on its own.
             self.image = Image.new('RGB', (target_w, target_h))
             self.draw = ImageDraw.Draw(self.image)
+            self.draw.fontmode = "1"  # 1-bit text: the panel has no partial brightness, so AA only smears glyphs.
             yield
         finally:
             self.matrix = real_matrix
@@ -768,16 +819,33 @@ class DisplayManager:
                     return  # Skip hardware write — content is being captured off-screen
 
                 digest = None
+                frame_checksum = None
                 if self._dirty_tracking_enabled:
                     try:
                         brightness = getattr(self.matrix, 'brightness', None)
                     except AttributeError:
                         brightness = None
-                    digest = (zlib.adler32(self.image.tobytes()), brightness)
-                    if digest == self._last_pushed_digest:
+                    frame_checksum = zlib.adler32(self.image.tobytes())
+                    digest = (frame_checksum, brightness)
+                    if digest == self._last_pushed_digest and not self.is_currently_scrolling():
                         # Nothing changed since the last push — the panel is
                         # already showing exactly this frame.
-                        self._write_snapshot_if_due()
+                        #
+                        # Never taken mid-scroll, and that exception is the
+                        # point. SwapOnVSync is what paces the render loop, so
+                        # skipping it also skips the wait: a duplicate frame
+                        # returns in ~8ms instead of ~10ms on a 100Hz panel,
+                        # advances only 0.8px instead of 1.0px, and so makes
+                        # the *next* frame more likely to repeat as well. That
+                        # is self-sustaining -- measured at ~20% duplicate
+                        # frames mid-scroll on the odds ticker, against
+                        # essentially zero on a lighter plugin with identical
+                        # scroll settings. Swapping an identical frame costs
+                        # one canvas copy and keeps the loop locked to the
+                        # panel; falling out of that lock costs smooth motion.
+                        # Static content is unaffected: is_currently_scrolling()
+                        # expires on its own inactivity threshold.
+                        self._write_snapshot_if_due(frame_checksum)
                         return
 
                 # Copy the current image to the offscreen canvas. In double-sided
@@ -787,8 +855,10 @@ class DisplayManager:
                 else:
                     self.offscreen_canvas.SetImage(self.image)
 
-                # Swap buffers immediately
-                self.matrix.SwapOnVSync(self.offscreen_canvas)
+                # Swap buffers immediately. framerate_fraction holds the frame
+                # for N refreshes; SwapOnVSync blocks for all of them, which is
+                # what paces the render loop to the chosen frame rate.
+                self.matrix.SwapOnVSync(self.offscreen_canvas, self._frame_hold)
 
                 # Swap our canvas references
                 self.offscreen_canvas, self.current_canvas = self.current_canvas, self.offscreen_canvas
@@ -796,7 +866,7 @@ class DisplayManager:
                 self._last_pushed_digest = digest
 
                 # Write a snapshot for the web preview (throttled)
-                self._write_snapshot_if_due()
+                self._write_snapshot_if_due(frame_checksum)
         except Exception as e:
             logger.error(f"Error updating display: {e}")
 
@@ -814,6 +884,7 @@ class DisplayManager:
                 
                 self.image = Image.new('RGB', (width, height))
                 self.draw = ImageDraw.Draw(self.image)
+                self.draw.fontmode = "1"  # 1-bit text: the panel has no partial brightness, so AA only smears glyphs.
                 logger.debug("Cleared display in fallback mode")
                 return
                 
@@ -825,6 +896,7 @@ class DisplayManager:
             # Create a new black image
             self.image = Image.new('RGB', (self.matrix.width, self.matrix.height))
             self.draw = ImageDraw.Draw(self.image)
+            self.draw.fontmode = "1"  # 1-bit text: the panel has no partial brightness, so AA only smears glyphs.
 
             if not self._capture_mode_active:
                 # Clear both canvases and the underlying matrix to ensure no artifacts.
@@ -901,11 +973,11 @@ class DisplayManager:
         self._text_width_cache.clear()
         try:
             # Load Press Start 2P font
-            self.regular_font = ImageFont.truetype("assets/fonts/PressStart2P-Regular.ttf", 8)
+            self.regular_font = load_truetype("assets/fonts/PressStart2P-Regular.ttf", 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 = ImageFont.truetype("assets/fonts/PressStart2P-Regular.ttf", 8)
+            self.small_font = load_truetype("assets/fonts/PressStart2P-Regular.ttf", 8)
             logger.info("Press Start 2P small font loaded successfully")
 
             # Load 5x7 BDF font for calendar events
@@ -918,6 +990,17 @@ class DisplayManager:
                 
                 # Load with freetype for proper BDF handling
                 face = freetype.Face(self.calendar_font_path)
+                # A freshly constructed Face has no active size, so
+                # face.size.height is 0 until set_char_size is called -- and
+                # get_font_height() reads exactly that. Without this, every
+                # caller measuring the 5x7 face got 0 and stacked rows on top
+                # of one another; the "Calendar font size: 0 pixels" line
+                # below has been printing the symptom on every start-up.
+                # font_manager._load_bdf_font already does this; the two paths
+                # disagreed about whether a Face was usable for measurement.
+                # 5x7.bdf is a fixed strike, so FreeType renders 7px whatever
+                # is asked for -- this sets the metrics, not the raster.
+                face.set_char_size(_CALENDAR_FONT_PX * 64, _CALENDAR_FONT_PX * 64, 72, 72)
                 logger.info(f"5x7 calendar font loaded successfully from {self.calendar_font_path}")
                 logger.info(f"Calendar font size: {face.size.height >> 6} pixels")
                 
@@ -938,7 +1021,7 @@ class DisplayManager:
             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 = ImageFont.truetype(font_path, 6)
+                self.extra_small_font = load_truetype(font_path, 6)
                 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.")
@@ -996,7 +1079,13 @@ class DisplayManager:
         try:
             if isinstance(font, freetype.Face):
                 # For FreeType faces (BDF), the 'height' metric gives the recommended line spacing.
-                return font.size.height >> 6
+                height = font.size.height >> 6
+                if height:
+                    return height
+                # A Face constructed without set_char_size reports 0, and a
+                # zero line height collapses every stacked row onto one line.
+                # Fall back to the strike the file declares.
+                return _bdf_native_size(font) or 8
             else:
                 # For PIL TTF fonts, getmetrics() provides ascent and descent.
                 # The line height is the sum of ascent and descent.
@@ -1258,6 +1347,7 @@ class DisplayManager:
             try:
                 self.image = Image.new('RGB', (self.width, self.height))
                 self.draw = ImageDraw.Draw(self.image)
+                self.draw.fontmode = "1"  # 1-bit text: the panel has no partial brightness, so AA only smears glyphs.
             except (OSError, RuntimeError, ValueError, MemoryError):
                 logger.debug("Canvas reset during cleanup failed", exc_info=True)
         # Reset the singleton state when cleaning up
@@ -1274,12 +1364,65 @@ class DisplayManager:
         
         return dt.strftime(f"%b %-d{suffix}") 
 
-    def set_scrolling_state(self, is_scrolling: bool):
-        """Set the current scrolling state. Call this when a display starts/stops scrolling."""
+    @property
+    def refresh_hz(self) -> float:
+        """The panel's refresh rate in Hz, from the hardware config.
+
+        The authoritative place to ask, because a plugin only receives its own
+        config section and cannot see display.hardware. Scroll pacing needs
+        this: the speeds a panel can show in whole pixels are refresh_hz
+        divided by the frame hold, so getting it wrong silently produces
+        fractional-pixel motion. See src/common/scroll_config.py.
+
+        Note this is the configured *cap*, not necessarily what the panel
+        achieves -- scripts/scroll_speeds.py --measure reports the real rate.
+        """
+        hardware = (self.config.get('display') or {}).get('hardware') or {}
+        try:
+            value = float(hardware.get('limit_refresh_rate_hz') or 0)
+        except (TypeError, ValueError):
+            value = 0.0
+        return value if value > 0 else 100.0
+
+    def set_frame_hold(self, refreshes: int) -> None:
+        """Hold each pushed frame for this many panel refreshes (>=1).
+
+        Set by the scroll configuration so a plugin can run at, say, 50px/s on
+        a 100Hz panel as one whole pixel every second refresh, rather than half
+        a pixel every refresh (which has to be blended or repeated unevenly).
+
+        Reset to 1 whenever scrolling stops, so one plugin's pacing cannot
+        leak into the next thing on screen.
+        """
+        try:
+            value = int(refreshes)
+        except (TypeError, ValueError):
+            logger.warning("Ignoring unusable frame hold: %r", refreshes)
+            return
+        self._frame_hold = max(1, min(255, value))
+
+    def set_scrolling_state(self, is_scrolling: bool, frame_hold: int = 1):
+        """Set the current scrolling state, and this scroll's frame pacing.
+
+        Call this when a display starts or stops scrolling. ``frame_hold`` is
+        how many panel refreshes each frame is held for -- 2 gives one whole
+        pixel every second refresh, which is how a scroll runs at half the
+        refresh rate without fractional pixel positions.
+
+        The hold is set here rather than once at plugin construction because
+        it must not outlive the scroll that asked for it: plugins share one
+        display manager, so a hold left set by whoever scrolled last would
+        silently re-pace the next plugin. Passing it alongside the state makes
+        the lifetime exactly the scroll, and the default of 1 means any caller
+        that does not care gets a new frame every refresh.
+        """
         current_time = time.time()
         self._scrolling_state['is_scrolling'] = is_scrolling
         if is_scrolling:
             self._scrolling_state['last_scroll_activity'] = current_time
+            self.set_frame_hold(frame_hold)
+        else:
+            self._frame_hold = 1
         logger.debug(f"Scrolling state set to: {is_scrolling}")
 
     def is_currently_scrolling(self) -> bool:
@@ -1293,6 +1436,14 @@ class DisplayManager:
         # If we've been inactive for the threshold period, consider it not scrolling
         if current_time - self._scrolling_state['last_scroll_activity'] > self._scrolling_state['scroll_inactivity_threshold']:
             self._scrolling_state['is_scrolling'] = False
+            # Drop the hold with the state, exactly as set_scrolling_state(False)
+            # does. This path is the one a scroll takes when it ends without
+            # saying so -- the rotation moves on mid-scroll, or the plugin is
+            # torn down -- and leaving the hold set there means every later
+            # plugin, scrolling or static, is presented at refresh/N until
+            # somebody calls set_scrolling_state(False). The hold must not
+            # outlive the scroll that asked for it, however that scroll ends.
+            self._frame_hold = 1
             return False
             
         return True
@@ -1410,11 +1561,20 @@ class DisplayManager:
                 self._viewer_fresh = False
         return self._viewer_fresh
 
-    def _write_snapshot_if_due(self) -> None:
+    def _write_snapshot_if_due(self, frame_checksum: Optional[int] = None) -> None:
         """Mirror the current frame to the preview snapshot when the policy
         says it's worth it — see src/common/snapshot_policy.py. Unchanged
         frames are never re-encoded; without viewers the cadence drops to
-        the idle keepalive."""
+        the idle keepalive.
+
+        Args:
+            frame_checksum: adler32 of the current frame, when the caller has
+                already computed one. Dirty tracking checksums every frame a
+                few lines above the call site, and re-deriving it here meant a
+                second tobytes() plus a second pass over the whole framebuffer
+                on every single frame — ~0.17ms per frame of the two combined
+                at 256x64, paid 100 times a second to reach the same number.
+        """
         try:
             now = time.time()
             viewer_fresh = self._viewer_is_fresh(now)
@@ -1424,7 +1584,8 @@ class DisplayManager:
                 self._last_snapshot_ts = 0.0
             self._viewer_was_fresh = viewer_fresh
 
-            digest = zlib.adler32(self.image.tobytes())
+            digest = (frame_checksum if frame_checksum is not None
+                      else zlib.adler32(self.image.tobytes()))
             action = snapshot_policy.decide(
                 now, self._last_snapshot_ts, self._last_snapshot_touch_ts,
                 viewer_fresh, digest != self._last_snapshot_digest)
@@ -1447,12 +1608,30 @@ class DisplayManager:
                 if parent_dir and str(parent_dir) != '/tmp':  # nosec B108 - guard to skip /tmp for permission ops
                     ensure_directory_permissions(parent_dir, get_assets_dir_mode())
                 self._snapshot_dir_prepared = True
-            # Write atomically: temp then replace
-            tmp_path = f"{self._snapshot_path}.tmp"
-            self.image.save(tmp_path, format='PNG')
+            # Write atomically: temp then replace. The temp name must be
+            # unique, not "<snapshot>.tmp": /tmp is world-writable and sticky,
+            # and this file is written by whichever user the display service
+            # runs as while tests and tooling run as someone else. A leftover
+            # fixed-name temp owned by another user is then unopenable even by
+            # root (fs.protected_regular refuses O_CREAT on a foreign file in a
+            # sticky dir), which froze the preview and the health check's
+            # liveness proxy until somebody deleted it by hand. Same pattern as
+            # the hardware-status write above.
+            _fd, tmp_path = tempfile.mkstemp(
+                dir=str(snapshot_path_obj.parent),
+                prefix=f".{snapshot_path_obj.name}.", suffix=".tmp")
             try:
+                with os.fdopen(_fd, "wb") as _f:
+                    self.image.save(_f, format='PNG')
+                os.chmod(tmp_path, 0o644)
                 os.replace(tmp_path, self._snapshot_path)
             except Exception:
+                # Never leave the temp behind -- that is what made the failure
+                # permanent rather than transient.
+                try:
+                    os.unlink(tmp_path)
+                except OSError:
+                    pass
                 # Fallback to direct save if replace not supported
                 self.image.save(self._snapshot_path, format='PNG')
             # Set proper file permissions after saving

src/element_style.py

@@ -51,6 +51,7 @@ from dataclasses import dataclass
 from typing import Any, Dict, Optional, Tuple, Union
 
 from PIL import ImageFont
+from src.common.font_layout import load_truetype
 
 try:
     import freetype
@@ -155,7 +156,7 @@ def load_font(font_name: str, size: int) -> Any:
             face.set_char_size(size * 64, size * 64, 72, 72)
             font: Any = face
         else:
-            font = ImageFont.truetype(path, size)
+            font = load_truetype(path, size)
     except Exception as e:
         logger.warning("Error loading font %s at %spx: %s, using fallback",
                        path, size, e)
@@ -174,7 +175,7 @@ def _load_fallback_font(size: int) -> Any:
         if cached is not None:
             return cached
         try:
-            font = ImageFont.truetype(path, size)
+            font = load_truetype(path, size)
             _font_cache[cache_key] = font
             return font
         except Exception as e:

src/font_manager.py

@@ -38,6 +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 typing import Dict, Tuple, Optional, Union, Any, List
 
 logger = logging.getLogger(__name__)
@@ -96,7 +97,8 @@ class FontManager:
         self.common_fonts = {
             "press_start": "assets/fonts/PressStart2P-Regular.ttf",
             "four_by_six": "assets/fonts/4x6-font.ttf",
-            "five_by_seven": "assets/fonts/5x7.bdf"
+            "five_by_seven": "assets/fonts/5x7.bdf",
+            "tom_thumb": "assets/fonts/tom-thumb.bdf"
             # Note: cozette_bdf removed - font file not available
             # To re-enable: download cozette.bdf from https://github.com/the-moonwitch/Cozette
             # and add: "cozette_bdf": "assets/fonts/cozette.bdf"
@@ -478,7 +480,7 @@ class FontManager:
                 if font_path.endswith('.bdf'):
                     font = self._load_bdf_font(font_path, size_px)
                 else:
-                    font = ImageFont.truetype(font_path, size_px)
+                    font = load_truetype(font_path, size_px)
             except Exception as e:
                 logger.error(f"Error loading font {font_path}: {e}")
                 self.performance_stats["failed_loads"] += 1
@@ -858,7 +860,7 @@ class FontManager:
                 return {"valid": True, "type": "bdf", "family": "unknown"}
             elif font_path.endswith('.ttf'):
                 # Try to load TTF font
-                ImageFont.truetype(font_path, 12)
+                load_truetype(font_path, 12)
                 return {"valid": True, "type": "ttf", "family": "unknown"}
             else:
                 return {"valid": False, "error": "Unsupported font format"}

src/logo_downloader.py

@@ -14,6 +14,7 @@ import json
 from typing import Dict, List, Optional, Tuple
 from pathlib import Path
 from PIL import Image, ImageDraw, ImageFont
+from src.common.font_layout import load_truetype
 from PIL.PngImagePlugin import PngInfo
 from requests.adapters import HTTPAdapter
 from urllib3.util.retry import Retry
@@ -747,7 +748,7 @@ class LogoDownloader:
             
             # Try to load a font, fallback to default
             try:
-                font = ImageFont.truetype("assets/fonts/PressStart2P-Regular.ttf", 12)
+                font = load_truetype("assets/fonts/PressStart2P-Regular.ttf", 12)
             except (OSError, IOError):
                 try:
                     font = ImageFont.load_default()

src/plugin_system/base_plugin.py

@@ -520,6 +520,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

@@ -1589,6 +1589,7 @@ class PluginStoreManager:
             with open(manifest_path, 'r') as f:
                 manifest = json.load(f)
             
+            requested_id = plugin_id
             plugin_id = plugin_id or manifest.get('id')
             if not plugin_id:
                 return {
@@ -1664,6 +1665,15 @@ class PluginStoreManager:
             
             branch_info = f" (branch: {branch_used})" if branch_used else ""
             self.logger.info(f"Successfully installed plugin from URL: {plugin_id}{branch_info}")
+            # User deliberately (re)installed this plugin -- clear any persistent
+            # uninstall record, exactly as install_plugin() does. Without this the
+            # id stays in config/uninstalled_plugins.json and
+            # purge_uninstalled_plugins(), which runs at every web-app startup,
+            # deletes the directory again: the plugin works for the rest of the
+            # session and is gone after the next reboot.
+            self.forget_uninstalled_plugin(
+                *(pid for pid in (requested_id, plugin_id, manifest.get('id')) if pid)
+            )
             result = {
                 'success': True,
                 'plugin_id': plugin_id,
@@ -2423,7 +2433,66 @@ class PluginStoreManager:
                     return plugin_path
         except (OSError, ValueError):
             pass
-        
+
+        # Last resort: the directory name may differ from the id being looked
+        # up. install_plugin() deliberately renames a plugin's directory to the
+        # MANIFEST id when it differs from the REGISTRY id (see the rename near
+        # "doesn't match registry ID" above), so `stocks` in the registry lands
+        # in `ledmatrix-stocks/`. Every lookup above is by directory name, so
+        # update_plugin("stocks") found nothing and reported the plugin as not
+        # installed -- silently, and for good: the user sees no error and stays
+        # on a stale version. Four installed plugins hit this in practice
+        # (leaderboard, music, stocks, weather).
+        #
+        # Deliberately last so the two lookups above keep their exact meaning;
+        # this only runs when a direct hit already failed. See
+        # test_discovery_path_contract.py, which pins that ordering.
+        for search_dir in self._candidate_plugin_dirs():
+            match = self._find_by_manifest_id(search_dir, plugin_id)
+            if match is not None:
+                self.logger.debug(
+                    "Resolved plugin '%s' to %s via its manifest id "
+                    "(directory name differs from the id)", plugin_id, match)
+                return match
+
+        return None
+
+    def _candidate_plugin_dirs(self) -> List[Path]:
+        """Directories that may hold installed plugins, configured one first."""
+        dirs = [self.plugins_dir]
+        try:
+            base = self.plugins_dir if self.plugins_dir.is_absolute()                 else self.plugins_dir.resolve()
+            sibling = base.parent / 'plugins'
+            if sibling != self.plugins_dir:
+                dirs.append(sibling)
+        except (OSError, ValueError):
+            pass
+        return [d for d in dirs if d.exists()]
+
+    @staticmethod
+    def _find_by_manifest_id(search_dir: Path, plugin_id: str) -> Optional[Path]:
+        """A subdirectory of `search_dir` whose manifest declares `plugin_id`.
+
+        Skips half-finished installs: store_manager renames a directory aside
+        with '.standalone-backup-' during install and rollback, and treating
+        one as installed would resurrect a ghost plugin.
+        """
+        try:
+            entries = sorted(search_dir.iterdir())
+        except (OSError, ValueError):
+            return None
+        for entry in entries:
+            if not entry.is_dir() or '.standalone-backup-' in entry.name:
+                continue
+            manifest = entry / 'manifest.json'
+            if not manifest.is_file():
+                continue
+            try:
+                with open(manifest, 'r', encoding='utf-8') as handle:
+                    if json.load(handle).get('id') == plugin_id:
+                        return entry
+            except (OSError, ValueError):
+                continue
         return None
     
     _SKIN_ID_PATTERN = re.compile(r'^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$')

src/plugin_system/testing/harness.py

@@ -14,6 +14,8 @@ via BoundsCheckingDisplayManager, and golden-image comparison.
 import contextlib
 import http.client
 import inspect
+import time
+from datetime import timedelta
 import socket
 import ssl
 import urllib.error
@@ -25,7 +27,7 @@ from PIL import Image, ImageChops
 
 from src.logging_config import get_logger
 from .bounds_display_manager import BoundsCheckingDisplayManager
-from .loading import load_config_defaults, load_manifest
+from .loading import load_config_defaults, load_manifest, merge_config
 from .sizes import DEFAULT_TEST_SIZES, safe_mode_filename, size_label
 
 logger = get_logger("[Plugin Harness]")
@@ -116,14 +118,23 @@ def list_modes(plugin_instance: Any, manifest: Dict[str, Any], plugin_id: str) -
 
 def _instantiate(plugin_id: str, manifest: Dict[str, Any], plugin_dir: Path,
                  config: Dict[str, Any], mock_data: Dict[str, Any],
-                 display_manager: Any) -> Any:
-    """Load and construct a plugin instance with mocked managers."""
+                 display_manager: Any, cache_manager: Any = None) -> Any:
+    """Load and construct a plugin instance with mocked managers.
+
+    Pass ``cache_manager`` to share one cache across the renders of a plugin.
+    Building a fresh one per (size, mode) made every render a cold start, so a
+    plugin that fetches per game or per player re-fetched everything N times --
+    baseball-scoreboard took 840s for nine renders where ~72s was the arithmetic
+    -- and the cache-hit path, which is what a running rig executes almost
+    always, was never exercised.
+    """
     from src.plugin_system.plugin_loader import PluginLoader
     from src.plugin_system.testing import MockCacheManager, MockPluginManager
 
-    cache_manager = MockCacheManager()
-    for key, value in (mock_data or {}).items():
-        cache_manager.set(key, value)
+    if cache_manager is None:
+        cache_manager = MockCacheManager()
+        for key, value in (mock_data or {}).items():
+            cache_manager.set(key, value)
 
     loader = PluginLoader()
     plugin_instance, _module = loader.load_plugin(
@@ -160,6 +171,107 @@ def _render_mode(plugin_instance: Any, mode: str) -> Any:
     return plugin_instance.display(force_clear=False)
 
 
+# How many extra frames to drive before believing a mode really draws nothing.
+# A scroll starts with its content off-panel, so frame 1 is legitimately blank;
+# measured across the fleet, content appears by frame 2-4 (f1-scoreboard),
+# frame 4 (ledmatrix-elections) and frame 38 at 64px (ledmatrix-leaderboard).
+EMPTY_RECHECK_FRAMES = 48
+# Seconds to advance the clock between those frames. Scroll position is usually
+# driven by elapsed time, which a frozen clock never provides.
+EMPTY_RECHECK_STEP = 0.05
+
+
+def _has_content(image) -> bool:
+    """True when any pixel is lit above the threshold."""
+    if image is None:
+        return False
+    return image.convert("L").point(
+        lambda p: 255 if p > _LIT_THRESHOLD else 0).getbbox() is not None
+
+
+def _render_mode_again(plugin_instance: Any, mode: str) -> Any:
+    """Draw one more frame WITHOUT force_clear.
+
+    _render_mode passes force_clear=True, which for a scrolling plugin means
+    "reset the scroll to the start" -- so repeating it would redraw frame 1 for
+    ever. The re-check needs the plugin to advance.
+    """
+    sig = inspect.signature(plugin_instance.display)
+    if "display_mode" in sig.parameters:
+        return plugin_instance.display(force_clear=False, display_mode=mode)
+    return plugin_instance.display(force_clear=False)
+
+
+def _settle_empty_frame(inst, mode, dm, result, freezer) -> None:
+    """Give an apparently-empty mode a few frames to draw before believing it.
+
+    One frame is not evidence: a scroll's first frame is its blank scroll-in
+    buffer. Without this, every scrolling plugin was warned about -- 60 of 76
+    warnings on a 44-plugin rig were false, which is the rate at which people
+    stop reading a warning.
+    """
+    if result.error is not None or result.display_returned is False:
+        return
+    if _has_content(result.image):
+        return
+    # The frozen clock is shared by every render in the matrix, so any time this
+    # probe borrows has to be given back -- otherwise a mode that scrolls in
+    # leaves the clock advanced and every later mode renders at the wrong
+    # instant, drifting its golden. Seen as 5 spurious f1_upcoming drifts.
+    resume_at = None
+    if freezer is not None:
+        try:
+            resume_at = freezer()
+        except (AttributeError, TypeError, ValueError):
+            # Not a freezegun factory, or a version whose factory is not
+            # callable. Only used to restore the clock, never load-bearing.
+            resume_at = None
+    try:
+        _settle_loop(inst, mode, dm, result, freezer)
+    finally:
+        if resume_at is not None:
+            try:
+                freezer.move_to(resume_at)
+            except (AttributeError, TypeError, ValueError):
+                pass
+
+
+def _settle_loop(inst, mode, dm, result, freezer) -> None:
+    tick = getattr(freezer, "tick", None) if freezer is not None else None
+    for _ in range(EMPTY_RECHECK_FRAMES):
+        if tick is not None:
+            # timedelta rather than a bare float: freezegun has accepted a
+            # number only since 1.x, and a stale pin would raise here.
+            try:
+                tick(timedelta(seconds=EMPTY_RECHECK_STEP))
+            except (AttributeError, TypeError, ValueError):
+                # Pacing is best-effort; a freezegun that will not take a
+                # timedelta just means this probe runs without advancing time.
+                pass
+        else:
+            # No frozen clock, so the real one has to do the advancing. Without
+            # this the 48 frames run in microseconds, elapsed time stays ~0, and
+            # a scroll driven by elapsed time never moves -- which is exactly
+            # the plugin this check is trying not to slander.
+            time.sleep(EMPTY_RECHECK_STEP)
+        try:
+            result.display_returned = _render_mode_again(inst, mode)
+        except Exception as e:  # noqa: BLE001
+            # Deliberately broad: this calls a plugin's display(), which can
+            # raise anything. Recorded rather than swallowed -- a mode that
+            # renders one good frame and then crashes on the next is broken,
+            # and returning silently here reported it as passing. The frame
+            # already captured stays on the result so the failure is still
+            # inspectable.
+            result.error = repr(e)
+            return
+        image = dm.get_image()
+        if _has_content(image):
+            result.image = image
+            result.overflow = dm.check_overflow()
+            return
+
+
 def _freeze(freeze_time: Optional[str]):
     """Context manager that freezes wall-clock time when freeze_time is given,
     so time-dependent plugins (clocks, countdowns) render deterministic goldens."""
@@ -193,7 +305,9 @@ def render_plugin_matrix(
     manifest = load_manifest(plugin_dir)
     # Start from config_schema.json defaults so the plugin behaves like a real
     # install; explicit caller config still wins over a schema default.
-    config = {"enabled": True, **load_config_defaults(plugin_dir), **(config or {})}
+    config = merge_config(
+        merge_config({"enabled": True}, load_config_defaults(plugin_dir)),
+        config or {})
     sizes = sizes or DEFAULT_TEST_SIZES
     results: List[RenderResult] = []
 
@@ -202,25 +316,35 @@ def render_plugin_matrix(
     # rendering a smaller one, instead of being clipped into a false pass.
     extent = (max(w for w, _ in sizes), max(h for _, h in sizes))
 
-    with _freeze(freeze_time):
+    # One cache for the whole matrix: see _instantiate. The display manager
+    # stays per-render (the bounds checking depends on that); only fetched data
+    # is shared.
+    from src.plugin_system.testing import MockCacheManager
+    cache_manager = MockCacheManager()
+    for key, value in (mock_data or {}).items():
+        cache_manager.set(key, value)
+
+    with _freeze(freeze_time) as freezer:
         for width, height in sizes:
             results.extend(_render_size(
                 plugin_id, manifest, plugin_dir, config, mock_data or {},
-                width, height, run_update, extent,
+                width, height, run_update, extent, cache_manager, freezer,
             ))
 
     return results
 
 
 def _render_size(plugin_id, manifest, plugin_dir, config, mock_data,
-                 width, height, run_update, extent) -> List[RenderResult]:
+                 width, height, run_update, extent,
+                 cache_manager=None, freezer=None) -> List[RenderResult]:
     """Render every mode at one size. A fresh instance per mode avoids state leaks."""
     results: List[RenderResult] = []
 
     # Discover modes once per size (instance build can depend on config).
     try:
         probe_dm = BoundsCheckingDisplayManager(width=width, height=height, overflow_extent=extent)
-        probe = _instantiate(plugin_id, manifest, plugin_dir, config, mock_data, probe_dm)
+        probe = _instantiate(plugin_id, manifest, plugin_dir, config, mock_data, probe_dm,
+                             cache_manager)
         modes = list_modes(probe, manifest, plugin_id)
     except Exception as e:  # noqa: BLE001 — surface any load failure as a result
         return [RenderResult(plugin_id, width, height, "<load>", error=repr(e))]
@@ -229,7 +353,8 @@ def _render_size(plugin_id, manifest, plugin_dir, config, mock_data,
         result = RenderResult(plugin_id, width, height, mode)
         dm = BoundsCheckingDisplayManager(width=width, height=height, overflow_extent=extent)
         try:
-            inst = _instantiate(plugin_id, manifest, plugin_dir, config, mock_data, dm)
+            inst = _instantiate(plugin_id, manifest, plugin_dir, config, mock_data, dm,
+                                cache_manager)
             if run_update:
                 try:
                     inst.update()
@@ -248,6 +373,9 @@ def _render_size(plugin_id, manifest, plugin_dir, config, mock_data,
                 result.display_returned = _render_mode(inst, mode)
                 result.image = dm.get_image()
                 result.overflow = dm.check_overflow()
+                # A blank first frame is not proof of a blank mode; see
+                # _settle_empty_frame.
+                _settle_empty_frame(inst, mode, dm, result, freezer)
         except Exception as e:  # noqa: BLE001 — a display crash is a real failure
             result.error = repr(e)
         results.append(result)

src/plugin_system/testing/loading.py

@@ -33,6 +33,45 @@ def load_manifest(plugin_dir: Union[str, Path]) -> Dict[str, Any]:
         return json.load(f)
 
 
+def _defaults_from_properties(properties: Dict[str, Any]) -> Dict[str, Any]:
+    """Defaults for one `properties` block, recursing into nested objects.
+
+    An object property carries its defaults on its children, not on itself, so
+    reading only the top level dropped everything nested. That is most of the
+    fleet: config organised by league, or under customization/display_options,
+    lost 2,386 defaults across 37 of 44 plugins -- soccer-scoreboard alone lost
+    539 of 565 -- and the harness rendered them with a config no install would
+    ever have.
+    """
+    defaults: Dict[str, Any] = {}
+    for key, prop in (properties or {}).items():
+        if not isinstance(prop, dict):
+            continue
+        if prop.get('type') == 'object' and isinstance(prop.get('properties'), dict):
+            nested = _defaults_from_properties(prop['properties'])
+            if nested:
+                defaults[key] = nested
+        elif 'default' in prop:
+            defaults[key] = prop['default']
+    return defaults
+
+
+def merge_config(base: Dict[str, Any], override: Dict[str, Any]) -> Dict[str, Any]:
+    """Deep-merge override onto base, without dropping sibling defaults.
+
+    A shallow merge would let `-c '{"nhl": {"enabled": true}}'` replace the whole
+    nhl subtree and silently discard every other nhl default -- the same class of
+    bug this function exists to fix.
+    """
+    merged = dict(base)
+    for key, value in (override or {}).items():
+        if isinstance(value, dict) and isinstance(merged.get(key), dict):
+            merged[key] = merge_config(merged[key], value)
+        else:
+            merged[key] = value
+    return merged
+
+
 def load_config_defaults(plugin_dir: Union[str, Path]) -> Dict[str, Any]:
     """Extract default values from a plugin's config_schema.json (empty if none)."""
     schema_path = Path(plugin_dir) / 'config_schema.json'
@@ -40,11 +79,7 @@ def load_config_defaults(plugin_dir: Union[str, Path]) -> Dict[str, Any]:
         return {}
     with open(schema_path, 'r') as f:
         schema = json.load(f)
-    defaults: Dict[str, Any] = {}
-    for key, prop in schema.get('properties', {}).items():
-        if isinstance(prop, dict) and 'default' in prop:
-            defaults[key] = prop['default']
-    return defaults
+    return _defaults_from_properties(schema.get('properties', {}))
 
 
 def load_harness_spec(plugin_dir: Union[str, Path]) -> Dict[str, Any]:

src/plugin_system/testing/visual_display_manager.py

@@ -31,6 +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.logging_config import get_logger
 
@@ -70,6 +71,7 @@ class VisualTestDisplayManager:
         # Canvas
         self.image = Image.new('RGB', (width, height), (0, 0, 0))
         self.draw = ImageDraw.Draw(self.image)
+        self.draw.fontmode = "1"  # Match production: 1-bit text, so goldens show what the panel shows.
 
         # Matrix proxy (plugins access display_manager.matrix.width/height)
         self.matrix = _MatrixProxy(width, height)
@@ -140,8 +142,8 @@ class VisualTestDisplayManager:
 
             # Press Start 2P — regular and small (both 8px)
             ttf_path = str(fonts_dir / 'PressStart2P-Regular.ttf')
-            self.regular_font = ImageFont.truetype(ttf_path, 8)
-            self.small_font = ImageFont.truetype(ttf_path, 8)
+            self.regular_font = load_truetype(ttf_path, 8)
+            self.small_font = load_truetype(ttf_path, 8)
             self.font = self.regular_font  # alias used by some code paths
 
             # 5x7 BDF font via freetype
@@ -161,7 +163,7 @@ class VisualTestDisplayManager:
             # 4x6 extra small TTF
             try:
                 xs_path = str(fonts_dir / '4x6-font.ttf')
-                self.extra_small_font = ImageFont.truetype(xs_path, 6)
+                self.extra_small_font = load_truetype(xs_path, 6)
             except (FileNotFoundError, OSError) as e:
                 logger.debug("Extra small font not available, using fallback: %s", e)
                 self.extra_small_font = self.small_font
@@ -184,6 +186,7 @@ class VisualTestDisplayManager:
         self.clear_called = True
         self.image = Image.new('RGB', (self._width, self._height), (0, 0, 0))
         self.draw = ImageDraw.Draw(self.image)
+        self.draw.fontmode = "1"  # Match production: 1-bit text, so goldens show what the panel shows.
 
     def update_display(self):
         """No-op for hardware; marks that display was updated."""
@@ -211,6 +214,7 @@ class VisualTestDisplayManager:
             self.matrix = _MatrixProxy(target_w, target_h)
             self.image = Image.new('RGB', (target_w, target_h), (0, 0, 0))
             self.draw = ImageDraw.Draw(self.image)
+            self.draw.fontmode = "1"  # Match production: 1-bit text, so goldens show what the panel shows.
             yield
         finally:
             self._width, self._height = prev_w, prev_h
@@ -503,9 +507,18 @@ class VisualTestDisplayManager:
     # Scrolling state (no-op interface compat)
     # ------------------------------------------------------------------
 
-    def set_scrolling_state(self, is_scrolling: bool):
-        """Set the current scrolling state (no-op for testing)."""
+    def set_scrolling_state(self, is_scrolling: bool, frame_hold: int = 1):
+        """Set the current scrolling state (no-op for testing).
+
+        ``frame_hold`` mirrors the DisplayManager signature this change adds.
+        The two are kept in step deliberately: a double that accepts arguments
+        production does not lets a call pass every harness run and then raise
+        TypeError on the panel, and a double that lacks one production has
+        fails every render of a plugin that legitimately paces its scroll.
+        Plugins begin passing it in ledmatrix-plugins#462.
+        """
         self._scrolling_state['is_scrolling'] = is_scrolling
+        self._scrolling_state['frame_hold'] = frame_hold
         if is_scrolling:
             self._scrolling_state['last_scroll_activity'] = time.time()
 
@@ -569,6 +582,7 @@ class VisualTestDisplayManager:
         self.draw_calls = []
         self.image = Image.new('RGB', (self._width, self._height), (0, 0, 0))
         self.draw = ImageDraw.Draw(self.image)
+        self.draw.fontmode = "1"  # Match production: 1-bit text, so goldens show what the panel shows.
         self._scrolling_state = {
             'is_scrolling': False,
             'last_scroll_activity': 0,
@@ -582,3 +596,4 @@ class VisualTestDisplayManager:
         """Clean up resources."""
         self.image = Image.new('RGB', (self._width, self._height), (0, 0, 0))
         self.draw = ImageDraw.Draw(self.image)
+        self.draw.fontmode = "1"  # Match production: 1-bit text, so goldens show what the panel shows.

src/startup_validator.py

@@ -111,17 +111,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 +140,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__)
@@ -1248,14 +1248,28 @@ 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
+
         # Save current connection info for failsafe restoration
         original_connection = None
         original_ssid = None
@@ -1635,6 +1649,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."""

systemd/README.md

@@ -19,12 +19,35 @@ This directory contains systemd service unit files for LEDMatrix services.
   - Automatically enables/disables access point mode
   - Uses `scripts/utils/wifi_monitor_daemon.py`
 
+- **`ledmatrix-dns-fix.service`** - DNS single-request fix (optional)
+  - Re-applies `options single-request` to the resolver on every boot,
+    because whatever manages `resolv.conf` regenerates it and drops the
+    option again
+  - Works around glibc's parallel A/AAAA lookup stalling ~5s per name on
+    routers that answer only the A query, which makes any plugin calling an
+    external API slow or (for Starlark apps, which have a render timeout)
+    fail outright
+  - Uses `scripts/utils/apply_dns_single_request.sh`
+  - Install only if external API calls are timing out; it is not part of a
+    normal install
+
+- **`ledmatrix-mqtt-bridge.service`** - Home Assistant MQTT bridge (optional)
+  - Exposes the display to Home Assistant over MQTT Discovery: force a mode,
+    stop on-demand, toggle power, set brightness
+  - Uses `integrations/mqtt_bridge/ledmatrix_mqtt_bridge.py`, which drives the
+    web API rather than the display directly
+  - Needs `integrations/mqtt_bridge/bridge_config.json`; see that directory's
+    README
+
 ## Installation
 
 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_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)
+- `install_mqtt_bridge.sh` installs `ledmatrix-mqtt-bridge.service` (opt-in)
 
 ## Manual Installation
 

systemd/ledmatrix-dns-fix.service

@@ -0,0 +1,16 @@
+[Unit]
+Description=LED Matrix DNS single-request fix (works around slow A/AAAA lookups)
+After=network-online.target NetworkManager.service
+Wants=network-online.target
+Before=ledmatrix.service
+
+[Service]
+Type=oneshot
+ExecStart=__PROJECT_ROOT_DIR__/scripts/utils/apply_dns_single_request.sh
+RemainAfterExit=yes
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=ledmatrix-dns-fix
+
+[Install]
+WantedBy=multi-user.target

systemd/ledmatrix-mqtt-bridge.service

@@ -0,0 +1,18 @@
+[Unit]
+Description=LED Matrix Home Assistant MQTT Bridge
+After=network-online.target ledmatrix-web.service
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=root
+WorkingDirectory=__PROJECT_ROOT_DIR__
+ExecStart=/usr/bin/python3 __PROJECT_ROOT_DIR__/integrations/mqtt_bridge/ledmatrix_mqtt_bridge.py
+Restart=on-failure
+RestartSec=10
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=ledmatrix-mqtt-bridge
+
+[Install]
+WantedBy=multi-user.target

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

@@ -16,6 +16,60 @@ 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)
+
+
 @pytest.fixture
 def mock_display_manager():
     """Create a mock DisplayManager for testing."""

test/fixtures/api_v3_url_map.json

@@ -0,0 +1,998 @@
+[
+ [
+  "/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/overrides",
+  "api_v3.get_fonts_overrides",
+  [
+   "GET",
+   "HEAD",
+   "OPTIONS"
+  ]
+ ],
+ [
+  "/api/v3/fonts/overrides",
+  "api_v3.save_fonts_overrides",
+  [
+   "OPTIONS",
+   "POST"
+  ]
+ ],
+ [
+  "/api/v3/fonts/overrides/<element_key>",
+  "api_v3.delete_font_override",
+  [
+   "DELETE",
+   "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/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

@@ -0,0 +1,66 @@
+# Web-interface JS tests
+
+Covers `web_interface/static/v3/js/plugins/list_filter.js` (the shared
+search/filter/sort controller) and the plugin-manager grids that use it:
+Installed Plugins, the Plugin Store, and Starlark Apps.
+
+There is no JS toolchain in this repo, so these are plain node scripts with no
+test framework. Each prints `ok`/`FAIL` lines and exits non-zero on failure.
+
+## Running
+
+```bash
+cd test/js
+npm install                 # jsdom, for the DOM suites only
+node run_all.js
+```
+
+The unit suites need nothing but node. The DOM suites additionally need a
+running web interface, because they test against the **real** server-rendered
+HTML and the **real** API rather than fixtures:
+
+```bash
+# in another shell, from the repo root
+EMULATOR=true python3 web_interface/app.py         # http://localhost:5000
+
+# or point the suites at a device
+BASE=http://10.0.10.169:5000 node run_all.js
+```
+
+`run_all.js` skips the DOM suites (rather than failing) when jsdom is missing or
+nothing is listening, so it stays useful in a bare checkout.
+
+## The suites
+
+| Suite | Needs a server | Covers |
+|---|---|---|
+| `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 |
+| `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.
+
+## Notes for whoever changes this next
+
+- The suites read the shipped files off disk and, for the DOM ones, the partial
+  from the running server. They do not keep their own copy of the markup, so
+  renaming an element id will fail them loudly rather than silently pass.
+- `unit/test_list_filter.js` `eval`s a slice of `plugins_manager.js` located by
+  the text `function installedSortName(plugin)`. If that function is renamed,
+  fix the slice markers rather than pasting a copy of the config into the test.
+- A few assertions exist specifically to stop earlier bugs coming back:
+  trailing spaces surviving the search debounce; a multi-word query that spans
+  two adjacent search fields (field order in the haystack is load-bearing);
+  `window.installedPlugins` staying at full length while the grid is filtered.
+- Watch for assertions that can pass vacuously. Several here deliberately guard
+  against it — e.g. counting only non-skeleton cards, and asserting a search
+  phrase matches something before comparing two results.
+
+The old-vs-new differential suites used to verify that the store and Starlark
+migrations were behaviour-preserving are not included: they compared against the
+pre-refactor implementation, which now only exists in git history. See PR #540
+if that comparison ever needs redoing.

test/js/dom/test_installed_dom.js

@@ -0,0 +1,279 @@
+// Integration test in a REAL DOM (jsdom):
+//   - HTML comes from the running server's /partials/plugins (real template output)
+//   - list_filter.js is loaded as a real script
+//   - plugin data comes from the running server's real API
+//   - interactions are real dispatched DOM events on the real pill/select nodes
+// This exercises HTML parsing, attribute reflection, event bubbling and
+// delegation for real — none of which the hand-rolled shim could vouch for.
+const fs = require('fs');
+const http = require('http');
+const { JSDOM, VirtualConsole } = require('jsdom');
+
+const path = require('path');
+const V3 = path.resolve(__dirname, '../../../web_interface/static/v3');
+const BASE = process.env.BASE || 'http://localhost:5000';
+
+function get(path) {
+  return new Promise((res, rej) => {
+    http.get(BASE + path, r => { let d = ''; r.on('data', c => d += c); r.on('end', () => res(d)); })
+        .on('error', rej);
+  });
+}
+
+(async () => {
+  const partial = await get('/partials/plugins');
+  const installed = JSON.parse(await get('/api/v3/plugins/installed')).data.plugins;
+
+  // Collected so an uncaught error inside a handler fails the run instead of
+  // silently vanishing.
+  const jsErrors = [];
+  const vc = new VirtualConsole();
+  vc.on('jsdomError', e => jsErrors.push(String(e.message || e)));
+  vc.on('error', (...a) => jsErrors.push('console.error: ' + a.join(' ')));
+
+  const dom = new JSDOM(
+    `<!doctype html><html><body><div id="app">${partial}</div></body></html>`,
+    { runScripts: 'dangerously', virtualConsole: vc, url: BASE + '/' });
+
+  const { window } = dom;
+  const { document } = window;
+
+  // Minimal ambient globals the extracted block expects from plugins_manager.js.
+  window.pluginLog = () => {};
+  window.debugLog = () => {};
+  window.PLUGIN_DEBUG = false;
+  window.installedPlugins = installed;
+  window.escapeHtml = function (text) {
+    if (!text) return '';
+    const div = document.createElement('div');
+    div.textContent = text;
+    return div.innerHTML;
+  };
+
+  // Load the helper as a real <script>.
+  const s = document.createElement('script');
+  s.textContent = fs.readFileSync(V3 + '/js/plugins/list_filter.js', 'utf8');
+  document.body.appendChild(s);
+
+  if (!window.ListFilter) { console.log('FAIL: list_filter.js did not expose window.ListFilter'); process.exit(1); }
+
+  // Pull the installed-plugins wiring out of plugins_manager.js verbatim and run
+  // it as a real script in this document.
+  const src = fs.readFileSync(V3 + '/plugins_manager.js', 'utf8');
+  const a = src.indexOf('function installedSortName(plugin)');
+  const b = src.indexOf('// Set up event delegation for plugin action buttons');
+  const c = src.indexOf('function handlePluginAction(event)');
+  const d = src.indexOf('function findInstalledPlugin(pluginId)');
+  if ([a, b, c, d].some(i => i < 0)) { console.log('FAIL: could not slice plugins_manager.js'); process.exit(1); }
+
+  const s2 = document.createElement('script');
+  s2.textContent = `
+    var installedPlugins = window.installedPlugins;
+    var escapeHtml = window.escapeHtml, pluginLog = window.pluginLog, debugLog = window.debugLog;
+    var PLUGIN_DEBUG = false;
+    ${src.slice(a, b)}
+    ${src.slice(b, c)}
+    ${src.slice(c, d)}
+    window.__t = { getInstalledFilter, renderInstalledPlugins, setupInstalledFilterListeners,
+                   applyInstalledFiltersAndRender };
+  `;
+  document.body.appendChild(s2);
+  if (jsErrors.length) { console.log('FAIL: errors while loading:\n  ' + jsErrors.join('\n  ')); process.exit(1); }
+
+  const T = window.__t;
+  const $ = id => document.getElementById(id);
+  const grid = () => $('installed-plugins-grid');
+  const cards = () => grid().querySelectorAll('.plugin-card:not(.installed-skeleton)').length;
+  const pill = v => document.querySelector(`#installed-filter-pills [data-installed-filter="${v}"]`);
+  const litPills = () => [...document.querySelectorAll('#installed-filter-pills [data-installed-filter]')]
+    .filter(b => b.getAttribute('data-active') === 'true')
+    .map(b => b.getAttribute('data-installed-filter'));
+  const countText = () => $('installed-count').textContent.trim();
+
+  const click = el => el.dispatchEvent(new window.MouseEvent('click', { bubbles: true, cancelable: true }));
+  const type = (el, v) => { el.value = v; el.dispatchEvent(new window.Event('input', { bubbles: true })); };
+  const change = (el, v) => { el.value = v; el.dispatchEvent(new window.Event('change', { bubbles: true })); };
+  const tick = ms => new Promise(r => setTimeout(r, ms));
+
+  let pass = 0, fail = 0;
+  const ok = (l, cond, extra) => cond ? (pass++, console.log('  ok   ' + l))
+    : (fail++, console.log('  FAIL ' + l + (extra !== undefined ? '  → ' + JSON.stringify(extra) : '')));
+
+  console.log('\n── real-DOM integration (jsdom) ──');
+  console.log(`   server gave ${installed.length} installed plugins: ` +
+              installed.map(p => `${p.id}(en=${p.enabled},upd=${!!p.update_available})`).join(' '));
+
+  // ── the markup the server actually rendered ────────────────────────────
+  ok('toolbar present in server HTML', !!$('installed-filter-bar'));
+  ok('4 pills parsed from server HTML',
+     document.querySelectorAll('#installed-filter-pills [data-installed-filter]').length === 4);
+  ok('sort dropdown has the 5 agreed options',
+     [...$('installed-sort').options].map(o => o.value).join(',') === 'a-z,z-a,status,recent,category',
+     [...$('installed-sort').options].map(o => o.value));
+  ok('skeletons present before first render', grid().querySelectorAll('.installed-skeleton').length === 3);
+
+  // ── first render ───────────────────────────────────────────────────────
+  T.setupInstalledFilterListeners();
+  T.renderInstalledPlugins(installed);
+  ok('skeletons removed after render', grid().querySelectorAll('.installed-skeleton').length === 0);
+  ok('one card per plugin', cards() === installed.length, cards());
+  ok('count text unfiltered', countText() === `${installed.length} installed`, countText());
+  ok('only the All pill is lit', litPills().join(',') === 'all', litPills());
+  ok('aria-pressed mirrors data-active', pill('all').getAttribute('aria-pressed') === 'true');
+
+  const enabledCount = installed.filter(p => p.enabled).length;
+  const disabledCount = installed.length - enabledCount;
+  const updCount = installed.filter(p => p.update_available).length;
+
+  // ── the CSS hook this feature depends on ───────────────────────────────
+  // .filter-pill[data-active="true"] had never been used by any code before
+  // this change, so confirm the attribute really flips on the real nodes.
+  click(pill('enabled'));
+  ok('Enabled pill lights up', litPills().join(',') === 'enabled', litPills());
+  ok('Enabled filters the grid', cards() === enabledCount, { cards: cards(), expect: enabledCount });
+  ok('count switches to "N of M shown"', countText() === `${enabledCount} of ${installed.length} shown`, countText());
+  ok('Clear button revealed', !$('installed-clear-filters').classList.contains('hidden'));
+
+  click(pill('disabled'));
+  ok('Disabled pill lights, Enabled unlights', litPills().join(',') === 'disabled', litPills());
+  ok('Disabled filters the grid', cards() === disabledCount, { cards: cards(), expect: disabledCount });
+
+  click(pill('updates'));
+  ok('Updates filters the grid', cards() === updCount, { cards: cards(), expect: updCount });
+  ok('updates badge count matches', $('installed-updates-count').textContent === String(updCount),
+     $('installed-updates-count').textContent);
+  ok('badge visible when >0', updCount === 0 || !$('installed-updates-count').classList.contains('hidden'));
+
+  click(pill('all'));
+  ok('back to All shows everything', cards() === installed.length);
+  ok('Clear button hidden again', $('installed-clear-filters').classList.contains('hidden'));
+
+  // ── debounced search, through the real event path ──────────────────────
+  const first = installed[0];
+  type($('installed-search'), first.name.slice(0, 4));
+  await tick(350);
+  ok('search narrows to a match', cards() >= 1 && cards() <= installed.length, cards());
+  ok('search clear ✕ revealed', !$('installed-search-clear').classList.contains('hidden'));
+
+  type($('installed-search'), 'zzz-no-such-plugin');
+  await tick(350);
+  ok('no matches → zero cards', cards() === 0);
+  ok('shows the filter empty state', /No plugins match your filters/.test(grid().textContent));
+  ok('does NOT say "No plugins installed"', !/No plugins installed/.test(grid().textContent));
+
+  // Clear button inside the empty state goes through the delegated handler.
+  const emptyClear = grid().querySelector('[data-action="clear-installed-filters"]');
+  ok('empty state offers a Clear button', !!emptyClear);
+  if (emptyClear) {
+    click(emptyClear);
+    ok('empty-state Clear restores the grid', cards() === installed.length, cards());
+    ok('empty-state Clear empties the search box', $('installed-search').value === '');
+  }
+
+  // ── regression: typing a space must survive the debounce ───────────────
+  // setSearch() trims for matching; if the trimmed value were written back into
+  // the input, pausing mid-phrase would delete the space you just typed and
+  // multi-word terms would be untypable.
+  const si = $('installed-search');
+  type(si, 'web ');
+  await tick(350);
+  ok('trailing space survives the debounce', si.value === 'web ', JSON.stringify(si.value));
+  type(si, 'web u');
+  await tick(350);
+  ok('can keep typing past the space', si.value === 'web u', JSON.stringify(si.value));
+  type(si, '   ');
+  await tick(350);
+  ok('whitespace-only is not treated as an active filter', cards() === installed.length, cards());
+  ok('whitespace-only text is still left in the box', si.value === '   ', JSON.stringify(si.value));
+  type(si, '');
+  await tick(350);
+
+  // ── sorts, via the real select ─────────────────────────────────────────
+  const names = () => [...grid().querySelectorAll('.plugin-card h4')].map(h => h.textContent.trim());
+  change($('installed-sort'), 'a-z');
+  const az = names();
+  change($('installed-sort'), 'z-a');
+  ok('z-a is the reverse of a-z', names().join('|') === [...az].reverse().join('|'),
+     { az, za: names() });
+  for (const s of ['status', 'recent', 'category']) {
+    change($('installed-sort'), s);
+    ok(`sort "${s}" keeps every card`, cards() === installed.length, cards());
+  }
+
+  // ── Clear Filters resets all three axes at once ────────────────────────
+  type($('installed-search'), first.name.slice(0, 3));
+  await tick(350);
+  click(pill('enabled'));
+  change($('installed-sort'), 'z-a');
+  click($('installed-clear-filters'));
+  ok('Clear resets search box', $('installed-search').value === '');
+  ok('Clear resets sort select', $('installed-sort').value === 'a-z');
+  ok('Clear relights All', litPills().join(',') === 'all', litPills());
+  ok('Clear restores all cards', cards() === installed.length, cards());
+  ok('Clear hides itself', $('installed-clear-filters').classList.contains('hidden'));
+
+  // ── the state-leak guard, on a real DOM ────────────────────────────────
+  click(pill('updates'));
+  ok('grid is filtered', cards() === updCount);
+  ok('window.installedPlugins still full length', window.installedPlugins.length === installed.length,
+     window.installedPlugins.length);
+  click(pill('all'));
+
+  // ── HTMX partial re-swap: the path no unit test could reach ────────────
+  // Replace the section's markup wholesale (what hx-swap does when you leave
+  // and re-enter the tab), then re-run init exactly as initPluginsPage would.
+  click(pill('enabled'));
+  type($('installed-search'), first.name.slice(0, 3));
+  await tick(350);
+  type($('installed-search'), $('installed-search').value + ' ');   // trailing space, on purpose
+  await tick(350);
+  const beforeSwap = { search: $('installed-search').value, pills: litPills().join(','), cards: cards() };
+  ok('pre-swap value retains its trailing space', /\s$/.test(beforeSwap.search), JSON.stringify(beforeSwap.search));
+
+  document.getElementById('app').innerHTML = partial;   // fresh toolbar at defaults
+  ok('post-swap DOM starts at defaults',
+     $('installed-search').value === '' && litPills().join(',') === 'all');
+
+  T.setupInstalledFilterListeners();        // what initPluginsPage() calls
+  T.renderInstalledPlugins(window.installedPlugins);
+  ok('post-swap: search text restored', $('installed-search').value === beforeSwap.search,
+     { got: $('installed-search').value, want: beforeSwap.search });
+  ok('post-swap: pill state restored', litPills().join(',') === beforeSwap.pills, litPills());
+  // Search AND pill are both still active, so the restored view must match the
+  // pre-swap view exactly — comparing to it avoids restating the filter logic.
+  ok('post-swap: same view restored', cards() === beforeSwap.cards,
+     { got: cards(), want: beforeSwap.cards });
+
+  // and the freshly swapped controls must still be live
+  type($('installed-search'), '');
+  await tick(350);
+  ok('post-swap: clearing search re-widens to the pill alone', cards() === enabledCount, cards());
+  click(pill('all'));
+  ok('post-swap: pills still clickable', cards() === installed.length, cards());
+  click(pill('disabled'));
+  ok('post-swap: pill filters again', cards() === disabledCount, cards());
+  click(pill('all'));
+  type($('installed-search'), 'zzz-none');
+  await tick(350);
+  ok('post-swap: search still live', cards() === 0);
+  click(grid().querySelector('[data-action="clear-installed-filters"]'));
+  ok('post-swap: delegated Clear still wired', cards() === installed.length);
+
+  // ── does the stylesheet actually hook the markup? ──────────────────────
+  const css = fs.readFileSync(V3 + '/app.css', 'utf8');
+  const st = document.createElement('style');
+  st.textContent = css;
+  document.head.appendChild(st);
+  click(pill('enabled'));
+  const activeWeight = window.getComputedStyle(pill('enabled')).fontWeight;
+  const idleWeight = window.getComputedStyle(pill('disabled')).fontWeight;
+  ok('.filter-pill[data-active="true"] matches our markup (font-weight 600)',
+     activeWeight === '600', { active: activeWeight, idle: idleWeight });
+  ok('inactive pill does not pick up the active rule', idleWeight !== '600', idleWeight);
+  click(pill('all'));
+
+  ok('no uncaught JS errors anywhere', jsErrors.length === 0, jsErrors.slice(0, 4));
+
+  console.log(`\n${pass} passed, ${fail} failed\n`);
+  process.exit(fail ? 1 : 0);
+})().catch(e => { console.log('HARNESS ERROR: ' + e.stack); process.exit(1); });

test/js/dom/test_no_double_fetch.js

@@ -0,0 +1,132 @@
+// Proves CodeRabbit's second finding is fixed: typing in the store search or
+// changing the category must filter the CACHED list, not refetch
+// /api/v3/plugins/store/list.
+//
+// This loads the WHOLE of plugins_manager.js into jsdom (not a slice), so the
+// legacy initializePlugins() wiring is present if it still exists, and counts
+// every fetch the page makes.
+const fs = require('fs');
+const http = require('http');
+const { JSDOM, VirtualConsole } = require('jsdom');
+
+const path = require('path');
+const V3 = path.resolve(__dirname, '../../../web_interface/static/v3');
+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/plugins');
+  const store = JSON.parse(await get('/api/v3/plugins/store/list'));
+  const installed = JSON.parse(await get('/api/v3/plugins/installed'));
+
+  const loadErrors = [];
+  const vc = new VirtualConsole();          // quiet, but keep real errors
+  vc.on('jsdomError', e => loadErrors.push(String(e.message || e).split('\n')[0]));
+  const dom = new JSDOM(`<!doctype html><html><body><div id="app">${partial}</div></body></html>`,
+    { runScripts: 'dangerously', virtualConsole: vc, url: BASE + '/', pretendToBeVisual: true });
+  const { window } = dom;
+
+  // Record every request the page attempts; serve from the payloads above.
+  const calls = [];
+  window.fetch = (url, opts) => {
+    const u = String(url);
+    calls.push(u);
+    let body = { status: 'success', data: {} };
+    if (u.includes('/plugins/store/list')) body = store;
+    else if (u.includes('/plugins/installed')) body = installed;
+    return Promise.resolve({
+      ok: true, status: 200,
+      json: () => Promise.resolve(body),
+      text: () => Promise.resolve(JSON.stringify(body)),
+    });
+  };
+  window.EventSource = function () { return { addEventListener() {}, close() {} }; };
+  window.confirm = () => false;
+  window.alert = () => {};
+  window.scrollTo = () => {};
+
+  // Globals plugins_manager.js expects from app.js (it declares /* global debugLog */).
+  const s0 = window.document.createElement('script');
+  s0.textContent = `
+    window.debugLog = function () {};
+    window.showNotification = function () {};
+    window.showError = function () {};
+    window.updateSystemStatus = function () {};
+    window.Alpine = undefined;
+    window.htmx = { process: function () {}, ajax: function () {} };
+  `;
+  window.document.body.appendChild(s0);
+
+  const s = window.document.createElement('script');
+  s.textContent = fs.readFileSync(V3 + '/js/plugins/list_filter.js', 'utf8');
+  window.document.body.appendChild(s);
+
+  const s2 = window.document.createElement('script');
+  s2.textContent = fs.readFileSync(V3 + '/plugins_manager.js', 'utf8');
+  window.document.body.appendChild(s2);
+
+  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, 300) : '')));
+  const tick = ms => new Promise(r => setTimeout(r, ms));
+
+  console.log('\n── store search must not refetch (CodeRabbit #2) ──');
+  if (loadErrors.length) console.log('   load errors: ' + loadErrors.slice(0, 3).join(' | '));
+  ok('whole plugins_manager.js evaluated', typeof window.initPluginsPage === 'function');
+
+  if (typeof window.initPluginsPage === 'function') window.initPluginsPage();
+  await tick(600);
+
+  const storeListCalls = () => calls.filter(u => u.includes('/plugins/store/list')).length;
+  const afterInit = storeListCalls();
+  console.log(`   init issued ${afterInit} store/list request(s) — that part is expected`);
+  ok('init loaded the store at least once', afterInit >= 1, calls);
+
+  const search = window.document.getElementById('plugin-search');
+  const category = window.document.getElementById('plugin-category');
+  ok('store search input present', !!search);
+
+  // Type a realistic burst, then wait past both debounce windows (300 ms each).
+  const before = storeListCalls();
+  for (const v of ['w', 'we', 'wea', 'weat', 'weath', 'weathe', 'weather']) {
+    search.value = v;
+    search.dispatchEvent(new window.Event('input', { bubbles: true }));
+    await tick(40);
+  }
+  await tick(700);
+  ok('typing 7 characters issued ZERO new store/list fetches',
+     storeListCalls() === before, { before, after: storeListCalls(), calls: calls.slice(-4) });
+
+  const beforeCat = storeListCalls();
+  if (category) {
+    category.value = 'sports';
+    category.dispatchEvent(new window.Event('change', { bubbles: true }));
+    await tick(700);
+    ok('changing category issued ZERO new store/list fetches',
+       storeListCalls() === beforeCat, { before: beforeCat, after: storeListCalls() });
+  }
+
+  // ...and the filtering still actually happened.
+  // Clear both axes before counting: 'weather' AND category=sports legitimately
+  // matches nothing, so counting here would measure the filter, not the render.
+  const beforeClear = storeListCalls();
+  search.value = '';
+  search.dispatchEvent(new window.Event('input', { bubbles: true }));
+  if (category) { category.value = ''; category.dispatchEvent(new window.Event('change', { bubbles: true })); }
+  await tick(700);
+  ok('clearing the filters also issued ZERO fetches', storeListCalls() === beforeClear,
+     { before: beforeClear, after: storeListCalls() });
+
+  // Count only real cards: the partial ships loading skeletons that also carry
+  // .plugin-card, which would let this pass on a dead page.
+  const grid = window.document.getElementById('plugin-store-grid');
+  const real = grid.querySelectorAll('.plugin-card:not(.animate-pulse)').length;
+  ok('the grid rendered real cards from the cache', real > 0, { real, html: grid.innerHTML.slice(0, 160) });
+
+  ok('no leftover _listenerSetup flag on the search input',
+     search && search._listenerSetup === undefined, search && search._listenerSetup);
+
+  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, 6).join('\n')); process.exit(1); });

test/js/dom/test_store_dom.js

@@ -0,0 +1,221 @@
+// Real-DOM (jsdom) test of the migrated Plugin Store toolbar, against the
+// server's actual 48-plugin registry — enough data for 4 pages, so pagination,
+// the ellipsis strip and per-page changes are exercised for real.
+// The card renderer itself is stubbed: Step 2 did not touch it, and stubbing
+// keeps the assertions on the parts that did change.
+const fs = require('fs');
+const http = require('http');
+const { JSDOM, VirtualConsole } = require('jsdom');
+
+const path = require('path');
+const V3 = path.resolve(__dirname, '../../../web_interface/static/v3');
+const BASE = process.env.BASE || 'http://localhost:5000';
+const get = path => new Promise((res, rej) =>
+  http.get(BASE + path, r => { let d = ''; r.on('data', c => d += c); r.on('end', () => res(d)); }).on('error', rej));
+
+function slice(src, a, b) {
+  const i = src.indexOf(a), j = src.indexOf(b, i + 1);
+  if (i < 0 || j < 0) throw new Error('cannot slice: ' + a);
+  return src.slice(i, j);
+}
+
+(async () => {
+  const partial = await get('/partials/plugins');
+  const storeJson = JSON.parse(await get('/api/v3/plugins/store/list'));
+  const storePlugins = (storeJson.data && storeJson.data.plugins) || storeJson.plugins || [];
+  const installed = JSON.parse(await get('/api/v3/plugins/installed')).data.plugins;
+
+  const jsErrors = [];
+  const vc = new VirtualConsole();
+  vc.on('jsdomError', e => jsErrors.push(String(e.message || e)));
+
+  const dom = new JSDOM(`<!doctype html><html><body><div id="app">${partial}</div></body></html>`,
+    { runScripts: 'dangerously', virtualConsole: vc, url: BASE + '/' });
+  const { window } = dom;
+  const { document } = window;
+
+  const src = fs.readFileSync(V3 + '/plugins_manager.js', 'utf8');
+
+  function boot() {
+    const s = document.createElement('script');
+    // IIFE-wrapped so a second boot gets a fresh closure instead of clashing on
+    // the top-level `const ListFilter`; it still publishes via window.ListFilter.
+    s.textContent = '(function(){\n' + fs.readFileSync(V3 + '/js/plugins/list_filter.js', 'utf8') + '\n})();';
+    document.body.appendChild(s);
+
+    const s2 = document.createElement('script');
+    s2.textContent = `(function(){
+      ${slice(src, 'const safeLocalStorage = {', '\n// ')}
+      var installedPlugins = ${JSON.stringify(installed)};
+      window.installedPlugins = installedPlugins;
+      var pluginStoreCache = ${JSON.stringify(storePlugins)};
+      window.__renderCalls = 0;
+      // Stand-in for renderPluginStore: real DOM nodes, minimal markup.
+      function renderPluginStore(plugins) {
+        window.__renderCalls++;
+        const grid = document.getElementById('plugin-store-grid');
+        grid.innerHTML = (plugins || []).map(p =>
+          '<div class="plugin-card" data-id="' + p.id + '"></div>').join('');
+      }
+      ${slice(src, 'function isStorePluginInstalled(', '// Expose searchPluginStore')}
+      window.__t = { applyStoreFiltersAndSort, setupStoreFilterListeners, getStoreFilter };
+    })();`;
+    document.body.appendChild(s2);
+  }
+  boot();
+  if (jsErrors.length) { console.log('FAIL loading:\n  ' + jsErrors.join('\n  ')); process.exit(1); }
+
+  const T = window.__t;
+  const $ = id => document.getElementById(id);
+  const cards = () => $('plugin-store-grid').querySelectorAll('.plugin-card').length;
+  const ids = () => [...$('plugin-store-grid').querySelectorAll('.plugin-card')].map(c => c.dataset.id);
+  const info = () => $('store-results-info').textContent.trim();
+  const infoBot = () => $('store-results-info-bottom') ? $('store-results-info-bottom').textContent.trim() : null;
+  const pagTop = () => $('store-pagination-top').innerHTML;
+  const pageBtns = () => [...$('store-pagination-top').querySelectorAll('[data-list-page]')];
+  const clickPage = label => {
+    const b = pageBtns().find(x => x.textContent.trim() === String(label));
+    if (!b) throw new Error('no page button labelled ' + label);
+    b.dispatchEvent(new window.MouseEvent('click', { bubbles: true, cancelable: true }));
+  };
+  const click = el => el.dispatchEvent(new window.MouseEvent('click', { bubbles: true, cancelable: true }));
+  const change = (el, v) => { el.value = v; el.dispatchEvent(new window.Event('change', { bubbles: true })); };
+  const type = (el, v) => { el.value = v; el.dispatchEvent(new window.Event('input', { bubbles: true })); };
+  const tick = ms => new Promise(r => setTimeout(r, ms));
+
+  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, 240) : '')));
+
+  console.log(`\n── store, real DOM, ${storePlugins.length} plugins from the live registry ──`);
+
+  T.setupStoreFilterListeners();
+  T.applyStoreFiltersAndSort();
+
+  const N = storePlugins.length;
+  ok('page 1 holds 12 cards', cards() === 12, cards());
+  ok('results info counts all ' + N, info() === `Showing 1–12 of ${N} plugins`, info());
+  ok('bottom info matches top', infoBot() === info(), { top: info(), bottom: infoBot() });
+  ok('pagination rendered', pageBtns().length > 0);
+  ok('per-page control shows 12', $('store-per-page').value === '12');
+
+  const totalPages = Math.ceil(N / 12);
+  ok(`last page button is ${totalPages}`,
+     pageBtns().some(b => b.textContent.trim() === String(totalPages)), pagTop().slice(0, 200));
+  ok('prev is disabled on page 1', pageBtns()[0].hasAttribute('disabled'));
+
+  const p1 = ids();
+  clickPage(2);
+  ok('page 2 renders 12 different cards', cards() === 12 && ids().join() !== p1.join());
+  ok('page 2 info', info() === `Showing 13–24 of ${N} plugins`, info());
+  clickPage(totalPages);
+  ok('last page info ends at ' + N, new RegExp(`–${N} of ${N} plugins$`).test(info()), info());
+  ok('next is disabled on the last page',
+     pageBtns()[pageBtns().length - 1].hasAttribute('disabled'));
+  ok('ellipsis appears for a far page', /&hellip;|…/.test(pagTop()), pagTop().slice(0, 120));
+  clickPage(1);
+  ok('back on page 1 shows the original slice', ids().join() === p1.join());
+
+  // ── per-page ───────────────────────────────────────────────────────────
+  change($('store-per-page'), '48');
+  ok('per-page 48 shows all in one page', cards() === Math.min(48, N), cards());
+  ok('pagination hidden when one page', pagTop().trim() === '' || pageBtns().length === 0, pagTop().slice(0, 80));
+  ok('per-page persisted', window.localStorage.getItem('storePerPage') === '48');
+  change($('store-per-page'), '12');
+  ok('back to 12 restores pagination', cards() === 12 && pageBtns().length > 0);
+
+  // ── sorts ──────────────────────────────────────────────────────────────
+  const firstOf = () => ids()[0];
+  change($('store-sort'), 'a-z');
+  const azFirst = firstOf();
+  change($('store-sort'), 'z-a');
+  ok('z-a changes the leading card', firstOf() !== azFirst, { az: azFirst, za: firstOf() });
+  ok('sort persisted to localStorage', window.localStorage.getItem('storeSort') === 'z-a');
+  for (const s of ['category', 'author', 'newest']) {
+    change($('store-sort'), s);
+    ok(`sort "${s}" still fills a page`, cards() === 12, cards());
+  }
+  change($('store-sort'), 'a-z');
+
+  // ── category ───────────────────────────────────────────────────────────
+  const cat = [...$('plugin-category').options].map(o => o.value).find(v => v && storePlugins.some(p => (p.category || '').toLowerCase() === v.toLowerCase()));
+  if (cat) {
+    change($('plugin-category'), cat);
+    const expect = storePlugins.filter(p => (p.category || '').toLowerCase() === cat.toLowerCase()).length;
+    ok(`category "${cat}" filters to ${expect}`, cards() === Math.min(expect, 12), { cards: cards(), expect });
+    ok('badge reports active filters', /filter/.test($('store-active-filters').textContent),
+       $('store-active-filters').textContent);
+    change($('plugin-category'), '');
+    ok('category cleared restores', cards() === 12);
+  } else { console.log('  --   no usable category option in the template, skipped'); }
+
+  // ── tri-state installed button ─────────────────────────────────────────
+  const instBtn = $('store-filter-installed');
+  ok('starts as All', /All/.test(instBtn.innerHTML) && instBtn.classList.contains('bg-white'), instBtn.innerHTML);
+  click(instBtn);
+  ok('→ Installed, green', /Installed/.test(instBtn.innerHTML) && instBtn.classList.contains('bg-green-50')
+     && !instBtn.classList.contains('bg-white'), instBtn.innerHTML);
+  const instCount = storePlugins.filter(p => installed.some(i => i.id === p.id ||
+      (p.plugin_path && i.id === p.plugin_path.split('/').pop()))).length;
+  ok('Installed count matches the installed set', cards() === Math.min(instCount, 12), { cards: cards(), expect: instCount });
+  click(instBtn);
+  ok('→ Not Installed, red', /Not Installed/.test(instBtn.innerHTML) && instBtn.classList.contains('bg-red-50'), instBtn.innerHTML);
+  ok('Not Installed count is the complement', cards() === Math.min(N - instCount, 12), { cards: cards(), expect: N - instCount });
+  click(instBtn);
+  ok('→ back to All', /All/.test(instBtn.innerHTML) && instBtn.classList.contains('bg-white'));
+
+  // ── search ─────────────────────────────────────────────────────────────
+  const term = (storePlugins[0].name || storePlugins[0].id).slice(0, 4);
+  type($('plugin-search'), term);
+  await tick(400);
+  ok(`search "${term}" narrows the set`, cards() > 0 && cards() <= 12, cards());
+  type($('plugin-search'), 'zzz-definitely-nothing');
+  await tick(400);
+  ok('no matches → 0 cards', cards() === 0);
+  ok('no-match info text', info() === 'No plugins match your filters', info());
+  type($('plugin-search'), '');
+  await tick(400);
+  ok('search cleared restores', cards() === 12);
+
+  // ── clear filters ──────────────────────────────────────────────────────
+  change($('store-per-page'), '24');
+  change($('store-sort'), 'z-a');
+  if (cat) change($('plugin-category'), cat);
+  click(instBtn);
+  type($('plugin-search'), term);
+  await tick(400);
+  ok('clear button visible with filters active', !$('store-clear-filters').classList.contains('hidden'));
+  click($('store-clear-filters'));
+  ok('clear resets search', $('plugin-search').value === '');
+  ok('clear resets sort to a-z', $('store-sort').value === 'a-z');
+  ok('clear resets category', $('plugin-category').value === '');
+  ok('clear resets installed button to All', /All/.test(instBtn.innerHTML));
+  ok('clear PRESERVES per-page 24', $('store-per-page').value === '24', $('store-per-page').value);
+  ok('clear shows a full 24-card page', cards() === 24, cards());
+  ok('clear hides itself', $('store-clear-filters').classList.contains('hidden'));
+
+  // ── persistence across a reload ────────────────────────────────────────
+  change($('store-sort'), 'author');
+  change($('store-per-page'), '48');
+  const saved = { sort: window.localStorage.getItem('storeSort'), per: window.localStorage.getItem('storePerPage') };
+  ok('prefs written under the original keys', saved.sort === 'author' && saved.per === '48', saved);
+
+  // Re-swap the partial (fresh controls at defaults) and re-boot the module, as
+  // a page reload would.
+  document.getElementById('app').innerHTML = partial;
+  ok('fresh markup starts at defaults',
+     $('store-sort').value === 'a-z' && $('store-per-page').value === '12');
+  const controllerBefore = window.__t;
+  boot();                       // fresh module instances, fresh localStorage read
+  ok('re-boot produced a new module instance', window.__t !== controllerBefore);
+  window.__t.setupStoreFilterListeners();
+  window.__t.applyStoreFiltersAndSort();
+  ok('reload restores sort=author into the control', $('store-sort').value === 'author', $('store-sort').value);
+  ok('reload restores per-page=48 into the control', $('store-per-page').value === '48', $('store-per-page').value);
+  ok('reload renders with the restored page size', cards() === Math.min(48, N), cards());
+
+  ok('no uncaught JS errors', jsErrors.length === 0, jsErrors.slice(0, 3));
+
+  console.log(`\n${pass} passed, ${fail} failed\n`);
+  process.exit(fail ? 1 : 0);
+})().catch(e => { console.log('HARNESS ERROR: ' + e.stack); process.exit(1); });

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/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "ledmatrix-webui-js-tests",
+  "version": "1.0.0",
+  "private": true,
+  "description": "JS tests for the v3 web interface (ListFilter and the plugin-manager grids)",
+  "scripts": {
+    "test": "node run_all.js"
+  },
+  "devDependencies": {
+    "jsdom": "^24.1.3"
+  }
+}

test/js/run_all.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// Runs the web-interface JS suites.
+//
+//   node run_all.js                        unit suites, plus DOM suites if a
+//                                          web interface is reachable
+//   BASE=http://10.0.10.169:5000 node run_all.js   point the DOM suites at a rig
+//
+// Unit suites need nothing but node. The DOM suites need `npm install` (jsdom)
+// and a running web interface, because they deliberately test against the real
+// server-rendered HTML and the real API rather than fixtures.
+const { spawnSync } = require('child_process');
+const http = require('http');
+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',
+              'unit/test_html_escaping.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 => {
+    const req = http.get(url, r => { r.resume(); res(r.statusCode < 500); });
+    req.on('error', () => res(false));
+    req.setTimeout(4000, () => { req.destroy(); res(false); });
+  });
+}
+
+function run(file) {
+  const r = spawnSync(process.execPath, [path.join(__dirname, file)],
+                      { stdio: 'inherit', cwd: __dirname, env: process.env });
+  return r.status === 0;
+}
+
+(async () => {
+  const results = [];
+  for (const f of UNIT) results.push([f, run(f)]);
+
+  const haveJsdom = fs.existsSync(path.join(__dirname, 'node_modules', 'jsdom'));
+  const up = await reachable(BASE + '/');
+
+  if (!haveJsdom) {
+    console.log(`\nSKIPPING DOM suites: jsdom not installed (run: npm install)\n`);
+  } else if (!up) {
+    console.log(`\nSKIPPING DOM suites: no web interface reachable at ${BASE}`);
+    console.log(`  start one with: EMULATOR=true python3 web_interface/app.py`);
+    console.log(`  or point at a rig: BASE=http://<host>:5000 node run_all.js\n`);
+  } else {
+    console.log(`\nDOM suites against ${BASE}\n`);
+    for (const f of DOM) results.push([f, run(f)]);
+  }
+
+  const failed = results.filter(([, ok]) => !ok);
+  console.log('\n─── summary ───');
+  results.forEach(([f, ok]) => console.log(`  ${ok ? 'PASS' : 'FAIL'}  ${f}`));
+  if (failed.length) { console.log(`\n${failed.length} suite(s) failed\n`); process.exit(1); }
+  console.log('\nall suites passed\n');
+})();

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_list_filter.js

@@ -0,0 +1,288 @@
+// Functional test for ListFilter + the installed-plugins config extracted
+// verbatim from plugins_manager.js. Runs under node with a minimal DOM shim.
+const fs = require('fs');
+const path = require('path');
+const V3 = path.resolve(__dirname, '../../../web_interface/static/v3');
+
+// ── minimal DOM shim ───────────────────────────────────────────────────────
+class El {
+  constructor(id, attrs = {}) {
+    this.id = id; this._attrs = { ...attrs }; this.value = '';
+    this.textContent = ''; this.innerHTML = ''; this.title = '';
+    this._classes = new Set(); this.children = []; this._listeners = {};
+    this.parentEl = null;
+    const self = this;
+    this.classList = {
+      add: (...c) => c.forEach(x => self._classes.add(x)),
+      remove: (...c) => c.forEach(x => self._classes.delete(x)),
+      contains: c => self._classes.has(c),
+      toggle: (c, force) => {
+        const on = force === undefined ? !self._classes.has(c) : !!force;
+        if (on) self._classes.add(c); else self._classes.delete(c);
+        return on;
+      },
+    };
+  }
+  setAttribute(k, v) { this._attrs[k] = String(v); }
+  getAttribute(k) { return k in this._attrs ? this._attrs[k] : null; }
+  addEventListener(type, fn) { (this._listeners[type] ||= []).push(fn); }
+  fire(type, target) {
+    // Real DOM listeners get `this` === the element the listener is bound to;
+    // the sort/select handlers rely on that, so mirror it.
+    (this._listeners[type] || []).forEach(fn =>
+      fn.call(this, { target: target || this, currentTarget: this, key: undefined,
+                      preventDefault() {}, stopPropagation() {} }));
+  }
+  append(child) { child.parentEl = this; this.children.push(child); return child; }
+  querySelectorAll(sel) {
+    const m = /^\[([^\]=]+)\]$/.exec(sel);
+    if (m) return this.children.filter(c => c.getAttribute(m[1]) !== null);
+    return [];
+  }
+  contains(node) { return node === this || this.children.includes(node); }
+  closest(sel) {
+    const m = /^\[([^\]=]+)\]$/.exec(sel);
+    let n = this;
+    while (n) { if (m && n.getAttribute(m[1]) !== null) return n; n = n.parentEl; }
+    return null;
+  }
+}
+
+const registry = new Map();
+function mk(id, attrs) { const e = new El(id, attrs); if (id) registry.set(id, e); return e; }
+
+global.document = {
+  getElementById: id => registry.get(id) || null,
+  querySelector: sel => {
+    let m = /^#([\w-]+)$/.exec(sel);
+    if (m) return registry.get(m[1]) || null;
+    m = /^#([\w-]+)\s+\[([\w-]+)="([^"]+)"\]$/.exec(sel);
+    if (m) {
+      const parent = registry.get(m[1]);
+      if (!parent) return null;
+      return parent.children.find(c => c.getAttribute(m[2]) === m[3]) || null;
+    }
+    return null;
+  },
+  dispatchEvent() {}, addEventListener() {},
+};
+global.CustomEvent = class { constructor(t, o) { this.type = t; Object.assign(this, o); } };
+global.window = global;
+
+// ── build the toolbar exactly as plugins.html declares it ─────────────────
+mk('installed-search');
+mk('installed-search-clear');
+mk('installed-sort');
+mk('installed-clear-filters');
+mk('installed-count');
+mk('installed-updates-count');
+mk('installed-plugins-grid');
+const pills = mk('installed-filter-pills');
+['all', 'enabled', 'disabled', 'updates'].forEach(v => {
+  const b = new El(null, { 'data-installed-filter': v });
+  pills.append(b);
+});
+document.getElementById('installed-sort').value = 'a-z';
+
+// ── load the helper ───────────────────────────────────────────────────────
+const ListFilter = require(path.join(V3, 'js/plugins/list_filter.js'));
+global.ListFilter = ListFilter;
+
+// ── extract the installed-plugins config verbatim from plugins_manager.js ──
+const src = fs.readFileSync(path.join(V3, 'plugins_manager.js'), 'utf8');
+const start = src.indexOf('function installedSortName(plugin)');
+const endMark = 'function setupInstalledFilterListeners()';
+const end = src.indexOf(endMark);
+if (start < 0 || end < 0) { console.error('FAIL: could not locate installed filter block'); process.exit(1); }
+const block = src.slice(start, end);
+
+// deps the block expects from its enclosing IIFE
+let rendered = null;
+global.installedPlugins = [];
+global.pluginLog = () => {};
+function renderInstalledCards(list, total) { rendered = { list, total }; }
+
+eval(block);   // defines installedSortName/comparators/getInstalledFilter/etc.
+
+// ── fixture ───────────────────────────────────────────────────────────────
+const P = (id, o) => Object.assign(
+  { id, name: id, enabled: true, update_available: false, category: 'general',
+    description: '', author: 'someone', tags: [], version: '1.0.0', last_updated: null }, o);
+
+const FIXTURE = [
+  P('zulu-clock',    { name: 'Zulu Clock',    enabled: true,  category: 'time',      last_updated: '2026-01-05' }),
+  P('alpha-weather', { name: 'Alpha Weather', enabled: false, category: 'weather',   last_updated: '2026-03-11', update_available: true, latest_version: '2.0.0' }),
+  P('mid-stocks',    { name: 'Mid Stocks',    enabled: true,  category: 'financial', last_updated: null,         update_available: true, latest_version: '3.1.0' }),
+  P('no-date',       { name: 'No Date Here',  enabled: false, category: 'general',   last_updated: null }),
+  P('taggy',         { name: 'Taggy',         enabled: true,  category: 'media',     last_updated: '2026-06-30', tags: ['hockey', 'nhl'] }),
+  P('bad-date',      { name: 'Bad Date',      enabled: true,  category: 'general',   last_updated: 'not-a-date' }),
+];
+global.installedPlugins = FIXTURE;
+window.installedPlugins = FIXTURE;
+
+const ctl = getInstalledFilter();
+if (!ctl) { console.error('FAIL: controller not created'); process.exit(1); }
+ctl.bind();
+
+// ── assertions ────────────────────────────────────────────────────────────
+let pass = 0, fail = 0;
+function ok(label, cond, extra) {
+  if (cond) { pass++; console.log('  ok   ' + label); }
+  else { fail++; console.log('  FAIL ' + label + (extra !== undefined ? '  → ' + JSON.stringify(extra) : '')); }
+}
+const ids = () => rendered.list.map(p => p.id);
+const countText = () => document.getElementById('installed-count').textContent;
+const badge = () => document.getElementById('installed-updates-count');
+const pillOf = v => pills.children.find(c => c.getAttribute('data-installed-filter') === v);
+const setPill = v => pills.fire('click', pillOf(v));
+
+console.log('\n1. default state (no filters)');
+ctl.apply();
+ok('renders all 6', rendered.list.length === 6, ids());
+ok('total is 6', rendered.total === 6);
+ok('sorted A→Z', ids().join(',') === 'alpha-weather,bad-date,mid-stocks,no-date,taggy,zulu-clock', ids());
+ok('count reads "6 installed"', countText() === '6 installed', countText());
+ok('updates badge shows 2', badge().textContent === '2' && !badge().classList.contains('hidden'), badge().textContent);
+ok('clear button hidden', document.getElementById('installed-clear-filters').classList.contains('hidden'));
+
+console.log('\n2. pill: enabled / disabled partition');
+setPill('enabled');
+const enabledIds = ids();
+ok('enabled → 4', enabledIds.length === 4, enabledIds);
+ok('count reads "4 of 6 shown"', countText() === '4 of 6 shown', countText());
+ok('clear button visible', !document.getElementById('installed-clear-filters').classList.contains('hidden'));
+ok('enabled pill lit', pillOf('enabled').getAttribute('data-active') === 'true');
+ok('all pill unlit', pillOf('all').getAttribute('data-active') === 'false');
+ok('aria-pressed set', pillOf('enabled').getAttribute('aria-pressed') === 'true');
+setPill('disabled');
+const disabledIds = ids();
+ok('disabled → 2', disabledIds.length === 2, disabledIds);
+ok('partition is exact, no overlap/loss',
+   enabledIds.length + disabledIds.length === 6 &&
+   !enabledIds.some(i => disabledIds.includes(i)));
+
+console.log('\n3. pill: updates');
+setPill('updates');
+ok('updates → only update_available', ids().join(',') === 'alpha-weather,mid-stocks', ids());
+ok('badge count unaffected by filtering', badge().textContent === '2');
+
+console.log('\n4. search');
+setPill('all');
+const searchEl = document.getElementById('installed-search');
+function search(text) { searchEl.value = text; ctl.setSearch(text); }
+search('weather');
+ok('name match', ids().join(',') === 'alpha-weather', ids());
+search('WEATHER');
+ok('case-insensitive', ids().join(',') === 'alpha-weather', ids());
+search('nhl');
+ok('matches tags[]', ids().join(',') === 'taggy', ids());
+search('financial');
+ok('matches category', ids().join(',') === 'mid-stocks', ids());
+search('someone');
+ok('matches author → all 6', ids().length === 6);
+search('  zulu  ');
+ok('trims whitespace', ids().join(',') === 'zulu-clock', ids());
+search('zzzznope');
+ok('no match → empty list, total preserved', rendered.list.length === 0 && rendered.total === 6);
+ok('count reads "0 of 6 shown"', countText() === '0 of 6 shown', countText());
+// The haystack joins fields in the CONFIGURED order (name, id, description,
+// author, category, tags), so a query may straddle a field boundary. The
+// fixtures deliberately insert `id` before `name`, so reading the object's own
+// entry order instead would break this.
+search('zulu clock zulu-clock');
+ok('phrase spanning name→id matches (field order preserved)',
+   ids().join(',') === 'zulu-clock', ids());
+search('zulu-clock zulu clock');
+ok('the reverse (object key order) does NOT match', rendered.list.length === 0, ids());
+search('taggy media');
+ok('phrase spanning category→tags respects field order', ids().length === 0, ids());
+search('');
+ok('cleared → all 6 back', ids().length === 6);
+ok('count back to "6 installed"', countText() === '6 installed', countText());
+
+console.log('\n5. search + pill combine (AND)');
+setPill('enabled');
+search('a');
+const both = rendered.list;
+ok('all results enabled', both.every(p => p.enabled), ids());
+ok('all results match "a"', both.every(p => (p.name + p.id + p.category + p.author).toLowerCase().includes('a')));
+search('');
+setPill('all');
+
+console.log('\n6. sorts');
+const sortEl = document.getElementById('installed-sort');
+function sort(v) { sortEl.value = v; sortEl.fire('change'); }
+sort('z-a');
+ok('z-a reverses', ids().join(',') === 'zulu-clock,taggy,no-date,mid-stocks,bad-date,alpha-weather', ids());
+sort('status');
+const st = ids();
+ok('status: updates first', st.slice(0, 2).sort().join(',') === 'alpha-weather,mid-stocks', st);
+ok('status: disabled last', st[st.length - 1] === 'no-date', st);
+sort('recent');
+const rec = ids();
+ok('recent: newest first', rec[0] === 'taggy' && rec[1] === 'alpha-weather' && rec[2] === 'zulu-clock', rec);
+ok('recent: missing/unparseable dates last',
+   ['bad-date', 'mid-stocks', 'no-date'].every(i => rec.indexOf(i) >= 3), rec);
+ok('recent: nothing dropped', rec.length === 6);
+sort('category');
+const cat = ids();
+ok('category groups', cat.join(',') === 'mid-stocks,bad-date,no-date,taggy,zulu-clock,alpha-weather', cat);
+sort('a-z');
+
+console.log('\n7. clear filters');
+search('taggy'); setPill('updates'); sort('z-a');
+ok('3 axes active', ctl.activeCount() === 3, ctl.activeCount());
+document.getElementById('installed-clear-filters').fire('click');
+ok('reset → all 6', ids().length === 6, ids());
+ok('reset clears search input', searchEl.value === '');
+ok('reset restores sort to a-z', ctl.state.sort === 'a-z' && sortEl.value === 'a-z');
+ok('reset relights All pill', pillOf('all').getAttribute('data-active') === 'true');
+ok('activeCount back to 0', ctl.activeCount() === 0);
+
+console.log('\n8. sticky: the just-toggled card must not vanish');
+setPill('enabled');
+ok('zulu-clock visible while enabled', ids().includes('zulu-clock'));
+ctl.sticky.add('zulu-clock');
+FIXTURE[0].enabled = false;               // simulate the toggle landing
+ctl.apply();
+ok('still visible after being disabled', ids().includes('zulu-clock'), ids());
+ok('but total unchanged', rendered.total === 6);
+setPill('enabled');                        // user touches toolbar → sticky clears
+ok('sticky cleared on toolbar use', !ids().includes('zulu-clock'), ids());
+FIXTURE[0].enabled = true;
+setPill('all');
+
+console.log('\n9. state-leak guard: window.installedPlugins must stay whole');
+search('taggy');
+ok('grid shows 1', rendered.list.length === 1);
+ok('window.installedPlugins still 6', window.installedPlugins.length === 6, window.installedPlugins.length);
+search('');
+
+console.log('\n10. updates badge when nothing needs updating');
+const noUpd = FIXTURE.map(p => ({ ...p, update_available: false }));
+window.installedPlugins = noUpd; global.installedPlugins = noUpd;
+ctl.apply();
+ok('badge hidden at 0', badge().classList.contains('hidden'));
+ok('updates pill dimmed', pillOf('updates').classList.contains('opacity-50'));
+ok('pill title explains', /No plugins have updates/.test(pillOf('updates').title), pillOf('updates').title);
+window.installedPlugins = FIXTURE; global.installedPlugins = FIXTURE;
+ctl.apply();
+ok('badge back at 2', badge().textContent === '2' && !badge().classList.contains('hidden'));
+ok('pill undimmed', !pillOf('updates').classList.contains('opacity-50'));
+
+console.log('\n11. empty installed list');
+window.installedPlugins = []; global.installedPlugins = [];
+ctl.apply();
+ok('renders nothing, total 0', rendered.list.length === 0 && rendered.total === 0);
+ok('count reads "0 installed"', countText() === '0 installed', countText());
+
+console.log('\n12. defensive: missing fields');
+const ragged = [{ id: 'bare' }, { id: 'nulls', name: null, tags: null, category: null, last_updated: null }];
+window.installedPlugins = ragged; global.installedPlugins = ragged;
+sort('recent'); ctl.apply();
+ok('no throw on ragged records, both rendered', rendered.list.length === 2, ids());
+search('bare');
+ok('search works on ragged records', ids().join(',') === 'bare', ids());
+
+console.log(`\n${pass} passed, ${fail} failed\n`);
+process.exit(fail ? 1 : 0);

test/js/unit/test_render_cards.js

@@ -0,0 +1,109 @@
+// Verifies renderInstalledCards (extracted verbatim from plugins_manager.js):
+// the two empty states, the card markup, and that it never publishes state.
+const fs = require('fs');
+const path = require('path');
+const V3 = path.resolve(__dirname, '../../../web_interface/static/v3');
+const src = fs.readFileSync(V3 + '/plugins_manager.js', 'utf8');
+
+function slice(fromMark, toMark) {
+  const a = src.indexOf(fromMark);
+  const b = src.indexOf(toMark, a + 1);
+  if (a < 0 || b < 0) { console.error('FAIL: cannot locate ' + fromMark); process.exit(1); }
+  return src.slice(a, b);
+}
+
+const container = {
+  innerHTML: '',
+  querySelectorAll: () => [],   // no skeletons in this harness
+};
+// escapeHtml() escapes via a detached element, so mirror what a browser does
+// when you read innerHTML back off textContent: & < > are escaped, quotes are not.
+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 = {
+  getElementById: id => (id === 'installed-plugins-grid' ? container : null),
+  createElement: () => new FakeEl(),
+};
+global.window = global;
+global.pluginLog = () => {};
+global.PLUGIN_DEBUG = false;
+global.debugLog = () => {};
+function setupInstalledEventDelegation() {}   // stubbed; tested separately
+
+eval(slice('function escapeHtml(text)', '\nfunction ', ));
+eval(slice('function renderInstalledCards(plugins, total)',
+           '// Set up event delegation for plugin action buttons'));
+
+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, 300) : '')));
+
+const SENTINEL = ['do', 'not', 'touch'];
+window.installedPlugins = SENTINEL;
+
+console.log('\n1. no plugins installed at all');
+renderInstalledCards([], 0);
+ok('shows "No plugins installed"', /No plugins installed/.test(container.innerHTML));
+ok('does NOT show the filter empty state', !/No plugins match/.test(container.innerHTML));
+ok('uses the plug icon', /fa-plug/.test(container.innerHTML));
+
+console.log('\n2. plugins installed but none match the filters');
+renderInstalledCards([], 12);
+ok('shows "No plugins match your filters"', /No plugins match your filters/.test(container.innerHTML));
+ok('does NOT claim nothing is installed', !/No plugins installed/.test(container.innerHTML));
+ok('reports the installed total', /12 plugins installed/.test(container.innerHTML), container.innerHTML.match(/\d+ plugins? installed/));
+ok('offers a Clear filters button', /data-action="clear-installed-filters"/.test(container.innerHTML));
+ok('uses the filter icon', /fa-filter/.test(container.innerHTML));
+
+console.log('\n3. singular/plural of the installed total');
+renderInstalledCards([], 1);
+ok('"1 plugin installed" (singular)', /1 plugin installed/.test(container.innerHTML) && !/1 plugins/.test(container.innerHTML));
+
+console.log('\n4. real cards');
+const plugins = [
+  { id: 'alpha', name: 'Alpha', author: 'Ann', version: '1.0.0', category: 'weather',
+    description: 'Shows weather', enabled: true, tags: ['a', 'b'], verified: true },
+  { id: 'beta', name: 'Beta', author: 'Bob', version: '1.0.0', latest_version: '2.0.0',
+    update_available: true, category: 'time', description: 'Clock', enabled: false },
+];
+renderInstalledCards(plugins, 5);
+const html = container.innerHTML;
+ok('renders 2 cards', (html.match(/class="plugin-card"/g) || []).length === 2);
+ok('enabled card shows Enabled', /<span>Enabled<\/span>/.test(html));
+ok('disabled card shows Disabled', /<span>Disabled<\/span>/.test(html));
+ok('update badge shows target version', /v2\.0\.0 available/.test(html));
+ok('update button labelled "Update to v2.0.0"', /Update to v2\.0\.0/.test(html));
+ok('pulsing ring class on the outdated one', /plugin-update-available/.test(html));
+ok('verified badge present', /Verified/.test(html));
+ok('tags rendered', /badge-info">a</.test(html) && /badge-info">b</.test(html));
+ok('per-plugin action hooks present',
+   /data-action="configure"/.test(html) && /data-action="update"/.test(html) &&
+   /data-action="uninstall"/.test(html) && /data-action="toggle"/.test(html));
+ok('no empty state alongside cards', !/empty-state/.test(html));
+
+console.log('\n5. it must not publish state');
+ok('window.installedPlugins untouched', window.installedPlugins === SENTINEL, window.installedPlugins);
+
+console.log('\n6. total defaults to list length when omitted');
+renderInstalledCards([], undefined);
+ok('omitted total + empty list → "no plugins installed"', /No plugins installed/.test(container.innerHTML));
+
+console.log('\n7. XSS: hostile plugin metadata is escaped');
+renderInstalledCards([{
+  id: 'evil', name: '<img src=x onerror=alert(1)>', author: '"><script>bad()</script>',
+  version: '1.0.0', category: 'x', description: '<b>nope</b>', enabled: true, tags: ['<i>t</i>'],
+}], 1);
+const evil = container.innerHTML;
+ok('no raw <img', !/<img src=x/.test(evil));
+ok('no raw <script', !/<script>bad/.test(evil));
+ok('no raw <b> from description', !/<b>nope<\/b>/.test(evil));
+ok('no raw <i> from tags', !/<i>t<\/i>/.test(evil));
+ok('escaped entities present instead', /&lt;/.test(evil));
+
+console.log(`\n${pass} passed, ${fail} failed\n`);
+process.exit(fail ? 1 : 0);

test/test_api_v3_display_modes.py

@@ -0,0 +1,157 @@
+"""GET /api/v3/display/modes -- the list of modes an on-demand request can name.
+
+Anything driving the display from outside the web UI needs two things that no
+existing endpoint gave it: the set of display modes, and which plugin owns each
+one. /plugins/installed carries neither, so callers read every plugin's
+manifest.json off disk and reimplemented PluginManager's own fallbacks.
+"""
+
+import json
+from unittest.mock import MagicMock
+
+import pytest
+
+from test._api_v3_test_helpers import (  # noqa: F401 - fixtures
+    api_v3_client, api_v3_module,
+)
+
+
+MANIFESTS = {
+    'clock-simple': {'name': 'Simple Clock', 'display_modes': ['clock-simple']},
+    'football-scoreboard': {
+        'name': 'Football Scoreboard',
+        'display_modes': ['nfl_live', 'nfl_recent', 'nfl_upcoming'],
+    },
+    'ledmatrix-weather': {'name': 'Weather', 'display_modes': ['weather']},
+}
+
+CONFIG = {
+    'clock-simple': {'enabled': True},
+    'football-scoreboard': {'enabled': True},
+    'ledmatrix-weather': {'enabled': False},
+}
+
+
+@pytest.fixture
+def client(api_v3_module, api_v3_client):
+    pm = api_v3_module.api_v3.plugin_manager
+    pm.plugin_manifests = MANIFESTS
+    pm.discover_plugins = MagicMock(return_value=list(MANIFESTS))
+    pm.get_plugin_display_modes = MagicMock(
+        side_effect=lambda pid: MANIFESTS[pid]['display_modes'])
+    api_v3_module.api_v3.config_manager.load_config = MagicMock(return_value=CONFIG)
+    return api_v3_client
+
+
+def _modes(response):
+    return {m['mode']: m for m in response.get_json()['data']['modes']}
+
+
+class TestTheModeListing:
+    def test_enabled_plugins_contribute_every_mode(self, client):
+        modes = _modes(client.get('/api/v3/display/modes'))
+        assert set(modes) == {'clock-simple', 'nfl_live', 'nfl_recent', 'nfl_upcoming'}
+
+    def test_each_mode_names_its_plugin(self, client):
+        """on-demand/start's find_plugin_for_mode fallback cannot see generated
+        modes, so the caller has to send plugin_id -- it must come from here."""
+        modes = _modes(client.get('/api/v3/display/modes'))
+        assert modes['nfl_live']['plugin_id'] == 'football-scoreboard'
+
+    def test_disabled_plugins_are_left_out_by_default(self, client):
+        modes = _modes(client.get('/api/v3/display/modes'))
+        assert 'weather' not in modes
+
+    def test_disabled_plugins_can_be_asked_for(self, client):
+        """They are still valid on-demand targets: the controller enables them
+        for the duration of the request."""
+        modes = _modes(client.get('/api/v3/display/modes?include_disabled=1'))
+        assert modes['weather']['enabled'] is False
+
+    def test_a_single_mode_plugin_is_labelled_with_its_own_name(self, client):
+        modes = _modes(client.get('/api/v3/display/modes'))
+        assert modes['clock-simple']['name'] == 'Simple Clock'
+
+    def test_a_multi_mode_plugin_labels_each_mode_distinctly(self, client):
+        """There is no per-mode name anywhere, and three modes all called
+        "Football Scoreboard" are not a usable dropdown."""
+        modes = _modes(client.get('/api/v3/display/modes'))
+        assert modes['nfl_live']['name'] == 'nfl_live'
+        assert modes['nfl_live']['plugin_name'] == 'Football Scoreboard'
+
+
+class TestItWorksForACallerThatNeverOpensTheDashboard:
+    def test_discovery_is_triggered(self, client, api_v3_module):
+        """Discovery is lazy and normally runs because a person loaded the
+        dashboard; a bridge or script would otherwise get an empty list."""
+        client.get('/api/v3/display/modes')
+        api_v3_module.api_v3.plugin_manager.discover_plugins.assert_called_once()
+
+    def test_no_plugin_manager_is_a_clean_error(self, api_v3_module, api_v3_client):
+        api_v3_module.api_v3.plugin_manager = None
+        response = api_v3_client.get('/api/v3/display/modes')
+        assert response.status_code == 500
+        assert response.get_json()['status'] == 'error'
+
+    def test_a_plugin_with_no_declared_modes_still_appears(self, client, api_v3_module):
+        """Its mode is its own id -- the same fallback the controller uses."""
+        pm = api_v3_module.api_v3.plugin_manager
+        pm.plugin_manifests = {'starlark-apps': {'name': 'Starlark Apps', 'display_modes': []}}
+        pm.get_plugin_display_modes = MagicMock(return_value=[])
+        api_v3_module.api_v3.config_manager.load_config = MagicMock(
+            return_value={'starlark-apps': {'enabled': True}})
+
+        modes = _modes(client.get('/api/v3/display/modes'))
+        assert modes['starlark-apps']['plugin_id'] == 'starlark-apps'
+
+
+class TestOneBadConfigSectionDoesNotBlankTheList:
+    """config.json can hold a non-dict under a plugin id.
+
+    DisplayController guards the same shape, so it happens in practice. Here it
+    used to raise AttributeError mid-loop and answer 500 with no modes at all --
+    and the MQTT bridge builds every one of its entities from this list, so one
+    hand-edited section would empty the Home Assistant dropdown.
+    """
+
+    @pytest.fixture
+    def client_with_bad_section(self, api_v3_module, api_v3_client):
+        pm = api_v3_module.api_v3.plugin_manager
+        pm.plugin_manifests = MANIFESTS
+        pm.discover_plugins = MagicMock(return_value=list(MANIFESTS))
+        pm.get_plugin_display_modes = MagicMock(
+            side_effect=lambda pid: MANIFESTS[pid]['display_modes'])
+        api_v3_module.api_v3.config_manager.load_config = MagicMock(return_value={
+            'clock-simple': {'enabled': True},
+            'football-scoreboard': "true",          # a string, not an object
+            'ledmatrix-weather': {'enabled': True},
+        })
+        return api_v3_client
+
+    def test_the_endpoint_still_answers(self, client_with_bad_section):
+        assert client_with_bad_section.get('/api/v3/display/modes').status_code == 200
+
+    def test_the_healthy_plugins_are_still_listed(self, client_with_bad_section):
+        modes = _modes(client_with_bad_section.get('/api/v3/display/modes'))
+        assert 'clock-simple' in modes and 'weather' in modes
+
+    def test_the_bad_section_is_treated_as_disabled(self, client_with_bad_section):
+        modes = _modes(client_with_bad_section.get('/api/v3/display/modes'))
+        assert 'nfl_live' not in modes
+
+    def test_a_failure_is_reported_the_way_every_other_handler_reports_one(
+            self, api_v3_module, api_v3_client):
+        """describe_exception, per test_web_error_detail's contract -- an
+        opaque "see logs for details" is what that test exists to prevent."""
+        api_v3_module.api_v3.plugin_manager.discover_plugins = MagicMock(
+            side_effect=RuntimeError("disk is gone"))
+        resp = api_v3_client.get('/api/v3/display/modes')
+        assert resp.status_code == 500
+        assert 'disk is gone' in resp.get_json()['details']
+
+    def test_credentials_in_the_exception_are_redacted(self, api_v3_module, api_v3_client):
+        """describe_exception is what makes returning detail safe."""
+        api_v3_module.api_v3.plugin_manager.discover_plugins = MagicMock(
+            side_effect=RuntimeError("GET https://x/y?api_key=SEC123 failed"))
+        body = api_v3_client.get('/api/v3/display/modes').get_json()
+        assert 'SEC123' not in json.dumps(body)

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

@@ -195,7 +195,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 +228,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_cache_nonfinite_floats.py

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

test/test_config_main_redacts_secrets.py

@@ -103,6 +103,54 @@ def test_non_dict_input_passes_through():
     assert _redact_credentials(None) is None
 
 
+def test_a_list_of_bare_credentials_is_redacted():
+    """A credential-named key whose value is a list of scalars, not a list
+    of named-field dicts, used to pass through untouched: the dict branch
+    recursed into `v` on its own value only, so a bare string list item had
+    no field name to test and fell through the base case unredacted.
+    """
+    config = {"tokens": ["abc123", "def456"], "timezone": "America/New_York"}
+    out = _redact_credentials(config)
+    assert out["tokens"] == ["", ""]
+    assert out["timezone"] == "America/New_York"
+
+
+def test_a_list_nested_inside_a_credential_named_container_is_also_blanked():
+    """The list fix applies at any depth under a credential-named key, not
+    only when the list is the key's direct value.
+    """
+    config = {"auth": {"backup_tokens": ["a", "b"], "note": "keep"}}
+    out = _redact_credentials(config)
+    assert out["auth"]["backup_tokens"] == ["", ""]
+    assert out["auth"]["note"] == "keep"
+
+
+def test_objects_inside_a_credential_named_list_are_blanked_regardless_of_field_names():
+    """A list item has no field name of its own to test against
+    `_CREDENTIAL_NAME_PARTS`, so an object reached through a credential-owned
+    list must be blanked outright rather than walked by field name -- unlike
+    the dict-directly-under-a-credential-key case in the test above.
+    """
+    config = {"tokens": [{"value": "secret", "kind": "bearer"}]}
+    out = _redact_credentials(config)
+    assert out["tokens"] == [{"value": "", "kind": ""}]
+
+
+def test_credential_shaped_container_with_named_fields_still_only_blanks_those():
+    """Unchanged behaviour for the case the container test above already
+    covers: a dict whose sub-keys are semantically named fields is walked
+    normally, not blanket-blanked, so an ordinary field next to a
+    credential-named one survives.
+    """
+    config = {"secrets": {"api_key": "k", "note": "keep", "list": ["a", "b"]}}
+    out = _redact_credentials(config)
+    assert out["secrets"]["api_key"] == ""
+    assert out["secrets"]["note"] == "keep"
+    # "list" isn't itself credential-named, so it is walked, not blanked --
+    # but it holds no credential-named field either, so it survives whole.
+    assert out["secrets"]["list"] == ["a", "b"]
+
+
 def test_the_endpoint_itself_redacts():
     """Through the view function, not the helper.
 
@@ -130,7 +178,8 @@ def test_the_endpoint_itself_redacts():
     app = flask.Flask(__name__)
     try:
         with app.test_request_context("/config/main"):
-            response = mod.get_main_config()
+            # get_main_config is a route; it lives in the config module now.
+            response = mod.config.get_main_config()
         payload = response.get_json() if hasattr(response, "get_json") else _json.loads(response[0].data)
     finally:
         mod.api_v3.config_manager = previous

test/test_discovery_path_contract.py

@@ -116,6 +116,77 @@ class TestFallbackDivergence:
             plugin_dir / "config_schema.json"
 
 
+class TestRegistryIdVersusDirectoryName:
+    """install_plugin() renames a plugin's directory to the MANIFEST id when it
+    differs from the REGISTRY id, so `stocks` in the registry lands in
+    `ledmatrix-stocks/`. Every path lookup is by directory name, so
+    update_plugin("stocks") used to find nothing and report the plugin as not
+    installed -- silently. Four installed plugins hit this in practice
+    (leaderboard, music, stocks, weather): the user clicks update, nothing
+    happens, no error, and they stay on a stale version indefinitely.
+    """
+
+    def test_resolves_a_plugin_whose_directory_name_differs_from_its_id(self, tmp_path):
+        configured = tmp_path / "plugin-repos"
+        configured.mkdir()
+        plugin_dir = _write_plugin(configured, "stocks", dir_name="ledmatrix-stocks")
+
+        store = PluginStoreManager(plugins_dir=str(configured))
+        assert store._find_plugin_path("stocks") == plugin_dir
+
+    def test_direct_directory_hit_still_wins(self, tmp_path):
+        """The manifest scan is a last resort. A directory named for the id
+        must still be preferred, so the two documented lookups above keep
+        their exact meaning."""
+        configured = tmp_path / "plugin-repos"
+        configured.mkdir()
+        direct = _write_plugin(configured, "demo", dir_name="demo")
+        # A second directory whose manifest claims the same id.
+        _write_plugin(configured, "demo", dir_name="zz-other-demo")
+
+        store = PluginStoreManager(plugins_dir=str(configured))
+        assert store._find_plugin_path("demo") == direct
+
+    def test_unknown_id_is_still_not_found(self, tmp_path):
+        configured = tmp_path / "plugin-repos"
+        configured.mkdir()
+        _write_plugin(configured, "stocks", dir_name="ledmatrix-stocks")
+
+        store = PluginStoreManager(plugins_dir=str(configured))
+        assert store._find_plugin_path("no-such-plugin") is None
+
+    def test_half_finished_installs_are_not_resurrected(self, tmp_path):
+        """A directory renamed aside during install/rollback carries a valid
+        manifest. Matching one would report a ghost plugin as installed."""
+        configured = tmp_path / "plugin-repos"
+        configured.mkdir()
+        _write_plugin(configured, "ghost",
+                      dir_name="ghost.standalone-backup-1234")
+
+        store = PluginStoreManager(plugins_dir=str(configured))
+        assert store._find_plugin_path("ghost") is None
+
+    def test_unreadable_manifest_does_not_break_the_scan(self, tmp_path):
+        configured = tmp_path / "plugin-repos"
+        configured.mkdir()
+        broken = configured / "broken-plugin"
+        broken.mkdir()
+        (broken / "manifest.json").write_text("{ not json")
+        wanted = _write_plugin(configured, "stocks", dir_name="ledmatrix-stocks")
+
+        store = PluginStoreManager(plugins_dir=str(configured))
+        assert store._find_plugin_path("stocks") == wanted
+
+    def test_sibling_plugins_dir_is_searched_too(self, tmp_path):
+        configured = tmp_path / "plugin-repos"
+        configured.mkdir()
+        legacy = _write_plugin(tmp_path / "plugins", "weather",
+                               dir_name="ledmatrix-weather")
+
+        store = PluginStoreManager(plugins_dir=str(configured))
+        assert store._find_plugin_path("weather") == legacy
+
+
 class TestStandaloneBackupContract:
     def test_discovery_skips_backup_dirs(self, tmp_path):
         plugins_dir = tmp_path / "plugins"

test/test_display_dirty_tracking.py

@@ -24,7 +24,7 @@ sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
 
 
 @pytest.fixture(scope="module")
-def dm():
+def dm(tmp_path_factory):
     """One real DisplayManager on the emulator (it's a process singleton)."""
     from src.display_manager import DisplayManager
     DisplayManager._instance = None
@@ -36,6 +36,14 @@ def dm():
             "runtime": {"gpio_slowdown": 0},
         },
     }, suppress_test_pattern=True)
+    # DisplayManager defaults _snapshot_path to the fixed /tmp/led_matrix_preview.png
+    # that the web UI reads. That path is shared by every pytest process on the
+    # machine, so two concurrent runs -- CI shards, a second worktree, a agent
+    # running the suite alongside -- write over each other's snapshot and the
+    # mtime assertions below stop meaning anything. Point it somewhere unique to
+    # this session; the individual tests that care still override it further.
+    manager._snapshot_path = str(
+        tmp_path_factory.mktemp("dirty_tracking") / "led_matrix_preview.png")
     yield manager
     DisplayManager._instance = None
     DisplayManager._initialized = False
@@ -47,12 +55,17 @@ class _SwapSpy:
     def __init__(self, matrix):
         self.matrix = matrix
         self.count = 0
+        self.last_frame_hold = None
         self._orig = matrix.SwapOnVSync
 
     def __enter__(self):
-        def counting(canvas):
+        def counting(canvas, *args):
+            # *args carries framerate_fraction, which display_manager passes so
+            # a frame can be held for several refreshes. Signature must match
+            # the real binding or the spy hides a TypeError as a failed push.
             self.count += 1
-            return self._orig(canvas)
+            self.last_frame_hold = args[0] if args else 1
+            return self._orig(canvas, *args)
         self.matrix.SwapOnVSync = counting
         return self
 
@@ -109,6 +122,11 @@ class TestDirtyTracking:
         dm.draw.rectangle([0, 0, 30, 8], fill=(255, 255, 0))
         dm.update_display()   # push + snapshot write (first frame)
         assert os.path.exists(dm._snapshot_path)
+        # Backdate the file so the "was it bumped?" check below cannot be
+        # defeated by filesystem mtime granularity -- on Windows two writes in
+        # the same tick get identical timestamps, which made this test fail
+        # roughly two runs in three regardless of the code under test.
+        os.utime(dm._snapshot_path, (time.time() - 60, time.time() - 60))
         first_mtime = os.path.getmtime(dm._snapshot_path)
 
         # Age the write/touch bookkeeping past TOUCH_INTERVAL so the next
@@ -125,6 +143,62 @@ class TestDirtyTracking:
         assert os.path.getmtime(dm._snapshot_path) > first_mtime
 
 
+class TestScrollLock:
+    """Dirty tracking must not skip the panel push while a scroll is running.
+
+    SwapOnVSync is what paces the render loop, so skipping it also skips the
+    wait for the panel. A duplicate frame therefore returns early -- ~8ms
+    instead of ~10ms on a 100Hz panel -- which advances the strip only 0.8px
+    instead of 1.0px, which makes the NEXT frame more likely to be a duplicate
+    too. That is self-sustaining: measured at ~20% duplicate frames mid-scroll
+    on the odds ticker against essentially zero on a lighter plugin with
+    identical scroll settings. Pushing an identical frame costs one canvas
+    copy; falling out of vsync lock costs smooth motion.
+    """
+
+    def test_identical_frames_still_push_while_scrolling(self, dm):
+        dm.draw.rectangle([0, 0, 12, 12], fill=(0, 0, 255))
+        dm.update_display()
+        dm.set_scrolling_state(True)
+        try:
+            with _SwapSpy(dm.matrix) as spy:
+                dm.update_display()
+                dm.update_display()
+                dm.update_display()
+            assert spy.count == 3, "scrolling must stay locked to the panel"
+        finally:
+            dm.set_scrolling_state(False)
+
+    def test_identical_frames_are_skipped_when_not_scrolling(self, dm):
+        """The optimisation still applies to static content."""
+        dm.set_scrolling_state(False)
+        dm.draw.rectangle([0, 0, 14, 14], fill=(255, 0, 255))
+        dm.update_display()
+        with _SwapSpy(dm.matrix) as spy:
+            dm.update_display()
+            dm.update_display()
+        assert spy.count == 0
+
+    def test_stale_scrolling_state_stops_forcing_pushes(self, dm):
+        """A plugin that stops scrolling without saying so must not pin the
+        panel into always-push forever. is_currently_scrolling() expires on
+        its own inactivity threshold, and the skip has to come back with it."""
+        dm.draw.rectangle([0, 0, 16, 16], fill=(0, 255, 255))
+        dm.update_display()
+        dm.set_scrolling_state(True)
+        try:
+            # Backdate the activity marker past the inactivity threshold.
+            dm._scrolling_state['last_scroll_activity'] = (
+                time.time() - dm._scrolling_state['scroll_inactivity_threshold'] - 1.0)
+            assert dm.is_currently_scrolling() is False
+            with _SwapSpy(dm.matrix) as spy:
+                dm.update_display()
+                dm.update_display()
+            assert spy.count == 0
+        finally:
+            dm.set_scrolling_state(False)
+
+
 class TestKillSwitch:
     def test_dirty_tracking_can_be_disabled(self, dm):
         dm._dirty_tracking_enabled = False
@@ -160,3 +234,112 @@ class TestKillSwitch:
 
 if __name__ == "__main__":
     sys.exit(pytest.main([__file__, "-v"]))
+
+
+class TestFrameHold:
+    """Holding a frame for N refreshes is how a scroll runs slower than one
+    pixel per refresh without fractional pixel positions."""
+
+    def test_hold_reaches_swap_on_vsync(self, dm):
+        dm.set_scrolling_state(True)
+        dm.set_frame_hold(3)
+        try:
+            dm.draw.rectangle([0, 0, 9, 9], fill=(120, 0, 200))
+            with _SwapSpy(dm.matrix) as spy:
+                dm.update_display()
+            assert spy.count == 1
+            assert spy.last_frame_hold == 3
+        finally:
+            dm.set_scrolling_state(False)
+
+    def test_default_is_every_refresh(self, dm):
+        dm.set_scrolling_state(True)
+        try:
+            dm.draw.rectangle([0, 0, 11, 11], fill=(0, 120, 200))
+            with _SwapSpy(dm.matrix) as spy:
+                dm.update_display()
+            assert spy.last_frame_hold == 1
+        finally:
+            dm.set_scrolling_state(False)
+
+    def test_hold_resets_when_scrolling_stops(self, dm):
+        """One plugin's pacing must not leak into whatever is on screen next."""
+        dm.set_scrolling_state(True)
+        dm.set_frame_hold(5)
+        dm.set_scrolling_state(False)
+        dm.set_scrolling_state(True)
+        try:
+            dm.draw.rectangle([0, 0, 13, 13], fill=(200, 120, 0))
+            with _SwapSpy(dm.matrix) as spy:
+                dm.update_display()
+            assert spy.last_frame_hold == 1
+        finally:
+            dm.set_scrolling_state(False)
+
+    @pytest.mark.parametrize("bad,expected", [(0, 1), (-4, 1), (None, 1), ("x", 1)])
+    def test_unusable_holds_are_ignored_or_floored(self, dm, bad, expected):
+        dm.set_frame_hold(bad)
+        assert dm._frame_hold == expected
+
+
+class TestFrameHoldLifetime:
+    """The hold must last exactly as long as the scroll that asked for it.
+
+    Plugins share one display manager. A hold applied at plugin construction is
+    wiped the moment any *other* plugin finishes scrolling, so by the time the
+    first plugin renders it is back to one pixel per refresh -- the speed reads
+    correct in the log and is wrong on the panel.
+    """
+
+    def test_scrolling_state_carries_the_hold(self, dm):
+        dm.set_scrolling_state(True, frame_hold=4)
+        try:
+            dm.draw.rectangle([0, 0, 7, 7], fill=(10, 200, 10))
+            with _SwapSpy(dm.matrix) as spy:
+                dm.update_display()
+            assert spy.last_frame_hold == 4
+        finally:
+            dm.set_scrolling_state(False)
+
+    def test_a_scroll_that_times_out_does_not_strand_a_hold(self, dm):
+        """The hold must go when the state does, however the scroll ended.
+
+        set_scrolling_state(False) is the polite exit. The other one is
+        is_currently_scrolling() deciding, after scroll_inactivity_threshold
+        of silence, that the scroll is over -- which is what happens when the
+        rotation moves on mid-scroll or a plugin is torn down. That path used
+        to clear the flag and keep the hold, so every later plugin, scrolling
+        or static, was presented at refresh/N by whoever scrolled last.
+        """
+        dm.set_scrolling_state(True, frame_hold=5)
+        # Age the scroll past the inactivity threshold rather than sleeping.
+        dm._scrolling_state['last_scroll_activity'] -= (
+            dm._scrolling_state['scroll_inactivity_threshold'] + 1.0)
+
+        assert dm.is_currently_scrolling() is False
+        dm.draw.rectangle([0, 0, 5, 5], fill=(10, 10, 200))
+        with _SwapSpy(dm.matrix) as spy:
+            dm.update_display()
+        assert spy.last_frame_hold == 1, (
+            "a timed-out scroll left its frame hold behind; the next plugin "
+            "is being presented at a fraction of the refresh rate")
+
+    def test_another_plugin_stopping_does_not_strand_a_hold(self, dm):
+        dm.set_scrolling_state(True, frame_hold=3)
+        dm.set_scrolling_state(False)          # some other plugin finishes
+        dm.set_scrolling_state(True)           # a plugin that wants no hold
+        try:
+            dm.draw.rectangle([0, 0, 6, 6], fill=(200, 10, 10))
+            with _SwapSpy(dm.matrix) as spy:
+                dm.update_display()
+            assert spy.last_frame_hold == 1
+        finally:
+            dm.set_scrolling_state(False)
+
+    def test_default_keeps_previous_behaviour(self, dm):
+        """Callers that never heard of frame holds get one frame per refresh."""
+        dm.set_scrolling_state(True)
+        try:
+            assert dm._frame_hold == 1
+        finally:
+            dm.set_scrolling_state(False)

test/test_display_double_parity.py

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

test/test_harness_empty_claimed.py

@@ -101,3 +101,61 @@ class TestSkippedResults:
         r = _result(None, returned=None)
         check_empty_claimed([r], strict=True)
         assert r.empty_claimed is None
+
+
+class TestSettleRecordsLaterFailures:
+    """A mode that renders one good frame and then crashes is broken.
+
+    _settle_loop re-renders a mode that came back blank, to give a scroll or an
+    animation time to put something on the panel. Swallowing an exception from
+    those later frames meant the harness reported a passing result for a mode
+    that crashes as soon as it is asked for a second frame -- exactly the kind
+    of defect the harness exists to catch.
+    """
+
+    class Boom:
+        """Renders once, then raises."""
+
+        def __init__(self):
+            self.calls = 0
+
+        def display(self, force_clear=False):
+            self.calls += 1
+            raise RuntimeError("second frame exploded")
+
+    def _settle(self, inst, dm, result):
+        from src.plugin_system.testing import harness
+        harness._settle_loop(inst, "mode", dm, result, None)
+
+    def test_the_exception_is_recorded_on_the_result(self, monkeypatch):
+        from src.plugin_system.testing import harness
+        # Keep the probe short; this test is about the error, not the pacing.
+        monkeypatch.setattr(harness, "EMPTY_RECHECK_FRAMES", 1)
+        monkeypatch.setattr(harness, "EMPTY_RECHECK_STEP", 0)
+
+        result = _result(_blank())
+        assert result.error is None
+        self._settle(self.Boom(), _FakeDM(), result)
+
+        assert result.error is not None, "a crash on a later frame was swallowed"
+        assert "second frame exploded" in result.error
+
+    def test_the_already_captured_frame_is_kept(self, monkeypatch):
+        from src.plugin_system.testing import harness
+        monkeypatch.setattr(harness, "EMPTY_RECHECK_FRAMES", 1)
+        monkeypatch.setattr(harness, "EMPTY_RECHECK_STEP", 0)
+
+        image = _blank()
+        result = _result(image)
+        self._settle(self.Boom(), _FakeDM(), result)
+        assert result.image is image, "the good frame was discarded along with the error"
+
+
+class _FakeDM:
+    """Minimal display-manager double for _settle_loop."""
+
+    def get_image(self):
+        return _blank()
+
+    def check_overflow(self):
+        return None

test/test_live_status_fields.py

@@ -0,0 +1,103 @@
+"""Tests for the metrics the live status stream reports.
+
+Two gaps made a struggling 1GB Pi look healthy on the dashboard:
+
+* ``disk_used_percent`` was the literal ``0`` in the SSE generator, so every
+  consumer of the live stream displayed 0% disk no matter how full the card was.
+  /api/v3/system/status computed it properly, but the live view -- the one people
+  actually watch -- did not.
+
+* ``memory_available_mb`` was absent. /api/v3/system/status carries it with a
+  comment explaining that MemAvailable, not used%, is what separates a board
+  that is fine from one about to fail fork(). The live stream omitted the one
+  number that predicts the failure.
+
+A wrong number is worse than a missing one, so an unreadable disk now reports
+None (the UI renders '--') rather than a confident 0.
+
+These import web_interface.system_metrics rather than web_interface.app on
+purpose: importing the app constructs a Flask application and a CacheManager,
+and the latter claims the cache directory with a cleanup thread -- which broke
+test_cache_cleanup_thread_ownership and the starlark route tests when this file
+first reached for the generator directly.
+"""
+
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+PROJECT_ROOT = Path(__file__).parent.parent
+sys.path.insert(0, str(PROJECT_ROOT))
+
+from web_interface.system_metrics import collect_system_metrics  # noqa: E402
+
+
+@pytest.fixture
+def metrics(monkeypatch):
+    """collect_system_metrics() with psutil's readings under our control."""
+    def _collect(disk_percent=12.0, available_bytes=512 * 1024 * 1024,
+                 used_percent=67.7, raise_disk=False):
+        import psutil
+        if raise_disk:
+            monkeypatch.setattr(psutil, "disk_usage",
+                                lambda _p: (_ for _ in ()).throw(OSError("no such mount")))
+        else:
+            monkeypatch.setattr(psutil, "disk_usage",
+                                lambda _p: SimpleNamespace(percent=disk_percent))
+        monkeypatch.setattr(psutil, "virtual_memory",
+                            lambda: SimpleNamespace(percent=used_percent,
+                                                    available=available_bytes))
+        return collect_system_metrics()
+    return _collect
+
+
+class TestDiskUsageIsReal:
+    def test_reported_value_comes_from_the_filesystem(self, metrics):
+        # The regression: this field was the literal 0.
+        assert metrics(disk_percent=91.4)["disk_used_percent"] == 91.4
+
+    def test_a_full_disk_is_not_reported_as_zero(self, metrics):
+        assert metrics(disk_percent=99.9)["disk_used_percent"] != 0
+
+    def test_unreadable_disk_is_null_not_a_confident_zero(self, metrics):
+        # null renders as '--'; 0 would read as "plenty of room".
+        assert metrics(raise_disk=True)["disk_used_percent"] is None
+
+
+class TestMemAvailableIsReported:
+    def test_mem_available_is_present_and_in_mb(self, metrics):
+        got = metrics(available_bytes=292 * 1024 * 1024)["memory_available_mb"]
+        assert got == pytest.approx(292.0, abs=0.1)
+
+    def test_the_1gb_danger_case_is_visible(self, metrics):
+        """67% used can be fine or nearly out of memory; only MemAvailable says."""
+        m = metrics(used_percent=67.7, available_bytes=40 * 1024 * 1024)
+        assert m["memory_used_percent"] == 67.7
+        assert m["memory_available_mb"] == pytest.approx(40.0, abs=0.1)
+
+
+class TestEveryPredictiveFieldIsPresent:
+    def test_nothing_the_dashboard_needs_is_missing(self, metrics):
+        m = metrics()
+        for field in ("cpu_percent", "cpu_temp", "memory_used_percent",
+                      "memory_available_mb", "disk_used_percent"):
+            assert field in m, f"{field} missing from collected metrics"
+
+    def test_absent_psutil_still_yields_every_key(self, monkeypatch):
+        """The no-psutil fallback must not drop fields the UI reads."""
+        import builtins
+        real_import = builtins.__import__
+
+        def _no_psutil(name, *args, **kwargs):
+            if name == "psutil":
+                raise ImportError("psutil missing")
+            return real_import(name, *args, **kwargs)
+
+        monkeypatch.setattr(builtins, "__import__", _no_psutil)
+        m = collect_system_metrics()
+        for field in ("cpu_percent", "cpu_temp", "memory_used_percent",
+                      "memory_available_mb", "disk_used_percent"):
+            assert field in m
+        assert m["disk_used_percent"] is None

test/test_live_update_cadence_integration.py

@@ -0,0 +1,159 @@
+"""The scheduler actually polls faster while a plugin reports live content.
+
+test_plugin_dynamic_update_interval.py proves _get_plugin_update_interval()
+returns the plugin's requested number. That is not the same claim as "the
+plugin gets updated more often", and the gap between those two is exactly where
+the original bug lived: the plugin knew it wanted 15s, said so in
+live_update_interval, and nothing downstream acted on it.
+
+So this drives the real run_scheduled_updates() over a simulated hour of ticks
+and counts dispatches. It is the test that would have caught the reported bug:
+
+    "the football plugin with live games only updates the live game in
+     progress if I restart the display"
+
+Measured on a rig before the fix, during an NFL fourth quarter, ESPN was polled
+at 23:21:49 / 23:22:50 / 23:23:50 / 23:24:50 -- exactly the manifest's 60s,
+never the configured 15.
+"""
+
+from unittest.mock import MagicMock
+
+import pytest
+
+from src.plugin_system.plugin_manager import PluginManager
+from src.plugin_system.plugin_state import PluginState
+
+
+class _StateManager:
+    """Enough of the real state machine for reservation to behave."""
+
+    def __init__(self):
+        self.states = {}
+
+    def can_execute(self, plugin_id):
+        return self.states.get(plugin_id, PluginState.ENABLED) != PluginState.RUNNING
+
+    def set_state(self, plugin_id, state):
+        self.states[plugin_id] = state
+
+
+class _Plugin:
+    """A sports plugin: fast while something is live, quiet otherwise."""
+
+    enabled = True
+
+    def __init__(self, live_interval=15):
+        self.live = False
+        self._live_interval = live_interval
+
+    def get_update_interval(self):
+        return self._live_interval if self.live else None
+
+    def update(self):
+        pass
+
+
+@pytest.fixture
+def scheduler():
+    pm = PluginManager.__new__(PluginManager)
+    import threading
+    pm._update_interval_cache = {}
+    pm.plugin_manifests = {"sports": {"update_interval": 60}}
+    pm.config_manager = None
+    pm.logger = MagicMock()
+    pm.state_manager = _StateManager()
+    pm.health_tracker = None
+    pm._synchronous_updates = False
+    pm._reservation_lock = threading.Lock()
+    pm._plugin_last_update_lock = threading.Lock()
+    pm.plugin_last_update = {}
+    pm.dispatched = []
+
+    # Stand in for the background worker: record the dispatch and complete it,
+    # so the next tick can reserve the plugin again.
+    def _enqueue(plugin_id, scheduled_time):
+        pm.dispatched.append(scheduled_time)
+        pm.plugin_last_update[plugin_id] = scheduled_time
+        pm.state_manager.set_state(plugin_id, PluginState.ENABLED)
+
+    pm._enqueue_update = _enqueue
+    return pm
+
+
+def _run_for(pm, plugin, seconds, start=1_000_000.0, step=1.0):
+    """Tick the real scheduler once a second for `seconds`."""
+    pm.plugins = {"sports": plugin}
+    t = start
+    end = start + seconds
+    while t < end:
+        pm.run_scheduled_updates(current_time=t)
+        t += step
+    return len(pm.dispatched)
+
+
+class TestTheReportedBug:
+    def test_a_live_game_is_polled_at_the_live_interval(self, scheduler):
+        """15s while live, not the manifest's 60s. This is the fix."""
+        plugin = _Plugin(live_interval=15)
+        plugin.live = True
+        count = _run_for(scheduler, plugin, seconds=600)   # ten minutes
+        # 600s / 15s = 40, allowing one for the first tick's free run.
+        assert 38 <= count <= 41, (
+            f"{count} updates in 10 minutes of a live game; expected ~40 at 15s. "
+            f"At the manifest's 60s it would be ~10 -- the reported bug.")
+
+    def test_the_same_window_without_the_hook_is_the_old_behaviour(self, scheduler):
+        """Pin what the bug actually looked like, so the contrast is asserted."""
+        plugin = _Plugin()
+        plugin.live = True
+        plugin.get_update_interval = lambda: None      # pre-fix: no opinion
+        count = _run_for(scheduler, plugin, seconds=600)
+        assert 9 <= count <= 11, (
+            f"{count} updates in 10 minutes; expected ~10 at the manifest's 60s")
+
+    def test_idle_polling_is_unchanged(self, scheduler):
+        """The regression that would be worse than the bug.
+
+        Asking for 15s year-round would poll ESPN four times a minute all
+        summer. Idle must stay exactly on the manifest.
+        """
+        plugin = _Plugin()
+        plugin.live = False
+        count = _run_for(scheduler, plugin, seconds=3600)  # a full hour idle
+        assert 59 <= count <= 61, (
+            f"{count} updates in an idle hour; expected ~60 at the manifest's 60s")
+
+
+class TestTheCadenceTracksTheGame:
+    def test_it_speeds_up_when_a_game_starts_and_slows_when_it_ends(self, scheduler):
+        """No reload, no restart -- the whole point of a per-tick hook."""
+        plugin = _Plugin(live_interval=15)
+        pm = scheduler
+
+        _run_for(pm, plugin, seconds=300, start=1_000_000.0)
+        idle_before = len(pm.dispatched)
+
+        plugin.live = True
+        _run_for(pm, plugin, seconds=300, start=1_000_300.0)
+        during = len(pm.dispatched) - idle_before
+
+        plugin.live = False
+        _run_for(pm, plugin, seconds=300, start=1_000_600.0)
+        idle_after = len(pm.dispatched) - idle_before - during
+
+        assert during > idle_before * 3, (
+            f"live window got {during} updates vs {idle_before} idle; "
+            "the hook did not speed anything up")
+        assert idle_after <= idle_before + 1, (
+            f"{idle_after} updates after the game ended vs {idle_before} before; "
+            "the fast cadence leaked past the live window")
+
+
+def test_a_broken_hook_does_not_stop_the_plugin_updating(scheduler):
+    """A scheduler that propagates one plugin's bug stops every other plugin."""
+    plugin = _Plugin()
+    plugin.get_update_interval = MagicMock(side_effect=RuntimeError("boom"))
+    count = _run_for(scheduler, plugin, seconds=600)
+    assert 9 <= count <= 11, (
+        f"{count} updates; a raising hook should fall back to the manifest's 60s")

test/test_logo_helper.py

@@ -24,7 +24,8 @@ import pytest
 import requests
 from PIL import Image, UnidentifiedImageError
 
-from src.common.logo_helper import MAX_LOGO_BYTES, LogoHelper
+from src.common.logo_helper import (MAX_LOGO_BYTES, MISSING_LOGO_RECHECK_SECONDS,
+                                    LogoHelper)
 
 
 @pytest.fixture(autouse=True)
@@ -494,3 +495,70 @@ class TestStalePlaceholderHandling:
             helper.load_logo_with_download("COLL", path, "http://x/c.png")
 
         assert should_attempt_download(path) is False
+
+
+class TestMissingLogosAreRememberedNotRewarned:
+    """A file that is not there does not become there by being asked again.
+
+    load_logo() stat'd the path and logged a WARNING on every call, so a
+    permanently absent logo produced one warning per rotation for as long as
+    the process ran -- measured at 114 lines in 24 hours for a single missing
+    ticker icon. The positive cache never covered this because a miss returns
+    None and caches nothing.
+    """
+
+    def test_a_missing_logo_warns_once(self, helper, tmp_path, caplog):
+        absent = tmp_path / "VOO.png"
+        with caplog.at_level(logging.WARNING):
+            for _ in range(50):
+                assert helper.load_logo("VOO", absent) is None
+        assert caplog.text.count("Logo not found for VOO") == 1, (
+            f"warned {caplog.text.count('Logo not found for VOO')} times in 50 calls")
+
+    def test_the_miss_is_not_remembered_forever(self, helper, tmp_path, monkeypatch):
+        """A logo written later -- logo_downloader does this at runtime -- must
+        still be picked up without a restart."""
+        path = tmp_path / "LATE.png"
+        assert helper.load_logo("LATE", path) is None
+
+        write_logo(path)
+        # Still inside the recheck window: the remembered miss stands.
+        assert helper.load_logo("LATE", path) is None
+
+        # Once it ages out, the next call stats the disk again and finds it.
+        for key in helper._missing_logos:
+            helper._missing_logos[key] -= MISSING_LOGO_RECHECK_SECONDS + 1
+        assert helper.load_logo("LATE", path) is not None
+
+    def test_a_download_clears_the_miss_immediately(self, helper, tmp_path):
+        """load_logo_with_download() must not be defeated by its own miss record.
+
+        load_logo() consults _missing_logos before it stats the disk, so a
+        logo we just downloaded would stay invisible for the whole recheck
+        window without the explicit invalidation.
+        """
+        path = tmp_path / "NEW.png"
+        assert helper.load_logo("NEW", path) is None
+        assert any(k.startswith("NEW_") for k in helper._missing_logos)
+
+        def _fake_download(url, file_path):
+            write_logo(Path(file_path))
+
+        with patch.object(helper, "_download_logo", side_effect=_fake_download):
+            got = helper.load_logo_with_download("NEW", path, logo_url="http://x/NEW.png")
+        assert got is not None, "a freshly downloaded logo was hidden by the miss record"
+        assert not any(k.startswith("NEW_") for k in helper._missing_logos)
+
+    def test_clear_cache_forgets_misses_too(self, helper, tmp_path):
+        helper.load_logo("GONE", tmp_path / "GONE.png")
+        assert helper._missing_logos
+        helper.clear_cache()
+        assert helper._missing_logos == {}
+
+    def test_a_present_logo_is_unaffected(self, helper, tmp_path, caplog):
+        path = write_logo(tmp_path / "OK.png")
+        with caplog.at_level(logging.WARNING):
+            for _ in range(10):
+                assert helper.load_logo("OK", path) is not None
+        assert "Logo not found" not in caplog.text
+        assert helper._missing_logos == {}

test/test_mqtt_bridge.py

@@ -0,0 +1,329 @@
+"""The Home Assistant MQTT bridge, without a broker or a matrix.
+
+The bridge is a translation layer: one MQTT payload in, one api_v3 call out.
+Everything worth pinning is on that path -- attaching the plugin_id a mode
+needs, rejecting values HA can produce but the API cannot take, and the
+discovery configs HA reads once and caches -- so it is all reachable with a
+fake API client and a pure function.
+"""
+
+import importlib.util
+import json
+import logging
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+BRIDGE_PATH = (Path(__file__).resolve().parent.parent
+               / "integrations" / "mqtt_bridge" / "ledmatrix_mqtt_bridge.py")
+
+
+@pytest.fixture(scope="module")
+def bridge_module():
+    if not BRIDGE_PATH.exists():
+        pytest.skip("mqtt bridge is not present")
+    try:
+        spec = importlib.util.spec_from_file_location("ledmatrix_mqtt_bridge", BRIDGE_PATH)
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[spec.name] = module
+        spec.loader.exec_module(module)
+        return module
+    except ImportError as e:
+        pytest.skip(f"mqtt bridge dependencies are not installed here: {e}")
+    finally:
+        sys.modules.pop("ledmatrix_mqtt_bridge", None)
+
+
+MODES = [
+    {"mode": "clock-simple", "plugin_id": "clock-simple",
+     "plugin_name": "Simple Clock", "name": "Simple Clock", "enabled": True},
+    {"mode": "nfl_live", "plugin_id": "football-scoreboard",
+     "plugin_name": "Football Scoreboard", "name": "nfl_live", "enabled": True},
+    {"mode": "aquarium", "plugin_id": "starlark-apps",
+     "plugin_name": "Starlark Apps", "name": "aquarium", "enabled": True},
+]
+
+
+@pytest.fixture
+def client():
+    """A stand-in for LEDMatrixClient that records what it was asked to do."""
+    fake = MagicMock()
+    fake.list_modes.return_value = list(MODES)
+    fake.start_on_demand.return_value = {"request_id": "r1"}
+    fake.stop_on_demand.return_value = {}
+    fake.set_power.return_value = {}
+    fake.set_brightness.return_value = {}
+    fake.get_brightness.return_value = 90
+    fake.display_status.return_value = {
+        "service": {"active": True},
+        "state": {"active": True, "mode": "nfl_live"},
+    }
+    return fake
+
+
+@pytest.fixture
+def handler(bridge_module, client):
+    h = bridge_module.CommandHandler(client)
+    h.refresh_modes()
+    return h
+
+
+class TestDisplayCommands:
+    def test_a_mode_is_forced_on_demand(self, handler, client):
+        result = handler.handle({"action": "display", "mode": "nfl_live"})
+        assert result["status"] == "success"
+        assert client.start_on_demand.call_args.kwargs["mode"] == "nfl_live"
+
+    def test_the_owning_plugin_is_sent_with_the_mode(self, handler, client):
+        """on-demand/start's find_plugin_for_mode fallback cannot resolve a
+        generated mode, so an omitted plugin_id 404s for every Starlark app."""
+        handler.handle({"action": "display", "mode": "aquarium"})
+        assert client.start_on_demand.call_args.kwargs["plugin_id"] == "starlark-apps"
+
+    def test_a_home_assistant_label_resolves_to_its_mode(self, handler, client):
+        """The select entity shows labels, so that is what comes back."""
+        handler.handle({"action": "display", "mode": "Simple Clock"})
+        assert client.start_on_demand.call_args.kwargs["mode"] == "clock-simple"
+
+    def test_an_unknown_mode_refreshes_before_giving_up(self, handler, client):
+        """A plugin installed since the last refresh is the usual reason."""
+        client.list_modes.return_value = MODES + [
+            {"mode": "new_app", "plugin_id": "starlark-apps", "name": "new_app"}]
+        handler.handle({"action": "display", "mode": "new_app"})
+        assert client.start_on_demand.call_args.kwargs["plugin_id"] == "starlark-apps"
+
+    def test_an_explicit_plugin_id_is_respected(self, handler, client):
+        handler.handle({"action": "display", "mode": "x", "plugin_id": "custom"})
+        assert client.start_on_demand.call_args.kwargs["plugin_id"] == "custom"
+
+    def test_duration_and_pinned_are_passed_through(self, handler, client):
+        handler.handle({"action": "display", "mode": "aquarium",
+                        "duration": 300, "pinned": True})
+        kwargs = client.start_on_demand.call_args.kwargs
+        assert kwargs["duration"] == 300 and kwargs["pinned"] is True
+
+    def test_display_with_nothing_to_show_is_rejected(self, handler, client):
+        result = handler.handle({"action": "display"})
+        assert result["status"] == "error"
+        client.start_on_demand.assert_not_called()
+
+    def test_stop_returns_to_normal_rotation(self, handler, client):
+        assert handler.handle({"action": "stop_display"})["status"] == "success"
+        client.stop_on_demand.assert_called_once()
+
+
+class TestPowerAndBrightness:
+    @pytest.mark.parametrize("state,expected", [("on", True), ("OFF", False), (" On ", True)])
+    def test_power_states_are_accepted(self, handler, client, state, expected):
+        assert handler.handle({"action": "power", "state": state})["status"] == "success"
+        client.set_power.assert_called_with(expected)
+
+    def test_an_unknown_power_state_is_rejected(self, handler, client):
+        assert handler.handle({"action": "power", "state": "maybe"})["status"] == "error"
+        client.set_power.assert_not_called()
+
+    def test_brightness_is_applied(self, handler, client):
+        assert handler.handle({"action": "brightness", "value": 75})["status"] == "success"
+        client.set_brightness.assert_called_with(75)
+
+    def test_a_float_from_home_assistant_is_accepted(self, handler, client):
+        """The number entity publishes "75.0"; int() would raise on that."""
+        handler.handle({"action": "brightness", "value": "75.0"})
+        client.set_brightness.assert_called_with(75)
+
+    @pytest.mark.parametrize("value", [-1, 101, "bright", None])
+    def test_out_of_range_brightness_never_reaches_the_api(self, handler, client, value):
+        assert handler.handle({"action": "brightness", "value": value})["status"] == "error"
+        client.set_brightness.assert_not_called()
+
+
+class TestFailuresAreReportedNotRaised:
+    """A failed command must publish an error, not kill the MQTT loop."""
+
+    def test_an_api_error_becomes_an_error_result(self, handler, client):
+        client.start_on_demand.side_effect = RuntimeError("Display service is not running")
+        result = handler.handle({"action": "display", "mode": "nfl_live"})
+        assert result["status"] == "error"
+        assert "not running" in result["message"]
+
+    def test_an_unknown_action_lists_the_known_ones(self, handler):
+        result = handler.handle({"action": "explode"})
+        assert result["status"] == "error"
+        assert "brightness" in result["message"]
+
+    def test_a_missing_action_is_an_error(self, handler):
+        assert handler.handle({})["status"] == "error"
+
+
+class TestDiscoveryPayloads:
+    """HA reads these once and caches them; a wrong shape is a dead entity."""
+
+    @pytest.fixture
+    def messages(self, bridge_module):
+        return bridge_module.discovery_messages(
+            "ledmatrix/command", "ledmatrix/command/state",
+            "ledmatrix/command/availability", ["Simple Clock", "nfl_live"])
+
+    def test_every_entity_is_published(self, messages):
+        components = {m["topic"].split("/")[1] for m in messages}
+        assert components == {"select", "button", "switch", "number"}
+
+    def test_each_entity_has_a_stable_unique_id(self, messages):
+        """Without one HA cannot let a user rename or reassign the entity."""
+        ids = [m["payload"]["unique_id"] for m in messages]
+        assert len(ids) == len(set(ids)) and all(ids)
+
+    def test_the_select_offers_the_modes_it_was_given(self, messages):
+        select = next(m for m in messages if "/select/" in m["topic"])
+        assert select["payload"]["options"] == ["Simple Clock", "nfl_live"]
+
+    def test_every_entity_shares_the_availability_topic(self, messages):
+        """It is also the bridge's last will, so HA greys the controls out
+        when the bridge dies rather than leaving them silently inert."""
+        assert all(m["payload"]["availability_topic"] == "ledmatrix/command/availability"
+                   for m in messages)
+
+    def test_every_entity_belongs_to_one_device(self, messages):
+        assert all(m["payload"]["device"]["identifiers"] == ["ledmatrix"] for m in messages)
+
+    def test_the_command_templates_are_valid_json_the_handler_accepts(self, messages, handler):
+        """A template that renders malformed JSON fails only at runtime, in HA."""
+        select = next(m for m in messages if "/select/" in m["topic"])
+        rendered = select["payload"]["command_template"].replace("{{ value }}", "nfl_live")
+        assert handler.handle(json.loads(rendered))["status"] == "success"
+
+        number = next(m for m in messages if "/number/" in m["topic"])
+        rendered = number["payload"]["command_template"].replace("{{ value }}", "40")
+        assert handler.handle(json.loads(rendered))["status"] == "success"
+
+    def test_the_switch_payloads_are_valid_json_the_handler_accepts(self, messages, handler):
+        switch = next(m for m in messages if "/switch/" in m["topic"])
+        for key in ("payload_on", "payload_off"):
+            assert handler.handle(json.loads(switch["payload"][key]))["status"] == "success"
+
+    def test_the_button_payload_is_valid_json_the_handler_accepts(self, messages, handler):
+        button = next(m for m in messages if "/button/" in m["topic"])
+        assert handler.handle(json.loads(button["payload"]["payload_press"]))["status"] == "success"
+
+
+class TestStateReporting:
+    def test_state_reflects_the_running_display(self, bridge_module, client):
+        state = bridge_module.read_state(client)
+        assert state == {"power": True, "mode": "nfl_live", "brightness": 90}
+
+    def test_normal_rotation_reports_no_forced_mode(self, bridge_module, client):
+        client.display_status.return_value = {
+            "service": {"active": True}, "state": {"active": False}}
+        assert bridge_module.read_state(client)["mode"] is None
+
+    def test_an_unreachable_field_does_not_blank_the_others(self, bridge_module, client):
+        """A stopped display service still has a brightness worth showing."""
+        client.display_status.side_effect = RuntimeError("connection refused")
+        state = bridge_module.read_state(client)
+        assert state["brightness"] == 90 and state["power"] is False
+
+
+class TestConfigLoading:
+    def test_defaults_apply_when_no_file_exists(self, bridge_module, tmp_path):
+        config = bridge_module.load_config(str(tmp_path / "absent.json"))
+        assert config["mqtt_topic"] == "ledmatrix/command"
+        assert config["mqtt_port"] == 1883
+
+    def test_the_file_overrides_defaults(self, bridge_module, tmp_path):
+        path = tmp_path / "bridge_config.json"
+        path.write_text(json.dumps({"mqtt_host": "broker.local", "mqtt_port": "8883"}))
+        config = bridge_module.load_config(str(path))
+        assert config["mqtt_host"] == "broker.local"
+        assert config["mqtt_port"] == 8883, "a port read from JSON must still be an int"
+
+    def test_the_environment_overrides_the_file(self, bridge_module, tmp_path, monkeypatch):
+        """So a password need not sit in a file the service user can read."""
+        path = tmp_path / "bridge_config.json"
+        path.write_text(json.dumps({"mqtt_password": "from-file"}))
+        monkeypatch.setenv("LEDMATRIX_MQTT_MQTT_PASSWORD", "from-env")
+        assert bridge_module.load_config(str(path))["mqtt_password"] == "from-env"
+
+    def test_the_example_placeholder_password_is_refused(self, bridge_module, tmp_path):
+        """Copying the example unedited must fail loudly, not silently fail to
+        authenticate against the broker."""
+        path = tmp_path / "bridge_config.json"
+        path.write_text(json.dumps(
+            {"mqtt_password": "REPLACE_WITH_YOUR_ACTUAL_MQTT_PASSWORD"}))
+        with pytest.raises(bridge_module.ConfigError):
+            bridge_module.load_config(str(path))
+
+    def test_malformed_json_is_a_clear_error(self, bridge_module, tmp_path):
+        path = tmp_path / "bridge_config.json"
+        path.write_text("{not json")
+        with pytest.raises(bridge_module.ConfigError):
+            bridge_module.load_config(str(path))
+
+    def test_a_non_numeric_port_is_a_clear_error(self, bridge_module, tmp_path):
+        path = tmp_path / "bridge_config.json"
+        path.write_text(json.dumps({"mqtt_port": "not-a-port"}))
+        with pytest.raises(bridge_module.ConfigError):
+            bridge_module.load_config(str(path))
+
+
+class TestTheExampleConfigIsSecureByDefault:
+    """The installer copies bridge_config.example.json verbatim on first run.
+
+    Without TLS the broker password and every display command cross the network
+    in cleartext, so the shipped default has to be the safe one -- a plaintext
+    broker is a deliberate edit, not something you get by not reading.
+    """
+
+    @pytest.fixture
+    def example(self):
+        path = (Path(__file__).resolve().parent.parent
+                / "integrations" / "mqtt_bridge" / "bridge_config.example.json")
+        if not path.exists():
+            pytest.skip("mqtt bridge example config is not present")
+        return json.loads(path.read_text(encoding="utf-8"))
+
+    def test_tls_is_on(self, example):
+        assert example["mqtt_tls"] is True
+
+    def test_the_port_is_the_tls_one(self, example):
+        """1883 with mqtt_tls on would just fail to connect."""
+        assert example["mqtt_port"] == 8883
+
+    def test_certificate_verification_is_not_disabled(self, example):
+        assert example.get("mqtt_tls_insecure", False) is False
+
+    def test_no_password_ships_in_the_example(self, example):
+        assert example["mqtt_password"] is None
+
+    def test_the_example_loads(self, bridge_module, tmp_path):
+        """It is copied verbatim, so it must survive load_config."""
+        path = (Path(__file__).resolve().parent.parent
+                / "integrations" / "mqtt_bridge" / "bridge_config.example.json")
+        config = bridge_module.load_config(str(path))
+        assert config["mqtt_tls"] is True and config["mqtt_port"] == 8883
+
+
+class TestCleartextIsCalledOut:
+    """Turning TLS off is allowed -- the Mosquitto add-on is plaintext on 1883 --
+    but it should not be silent when a password is going over it."""
+
+    def test_a_password_without_tls_warns(self, bridge_module, caplog):
+        with caplog.at_level(logging.WARNING):
+            warned = bridge_module.warn_if_cleartext(
+                {"mqtt_tls": False, "mqtt_password": "hunter2"})
+        assert warned is True
+        assert "unencrypted" in caplog.text
+
+    def test_the_warning_does_not_repeat_the_password(self, bridge_module, caplog):
+        with caplog.at_level(logging.WARNING):
+            bridge_module.warn_if_cleartext({"mqtt_tls": False, "mqtt_password": "hunter2"})
+        assert "hunter2" not in caplog.text
+
+    def test_no_password_means_nothing_to_lose(self, bridge_module):
+        assert bridge_module.warn_if_cleartext(
+            {"mqtt_tls": False, "mqtt_password": None}) is False
+
+    def test_tls_on_does_not_warn(self, bridge_module):
+        assert bridge_module.warn_if_cleartext(
+            {"mqtt_tls": True, "mqtt_password": "hunter2"}) is False