fix: September 16 core audit — partial saves, asset path safety, auto-update, display settings the library refuses, scroll speed (#595)

* fix(sports): share the ESPN rejected-range memo with the background service

BackgroundDataService always sent a season range first and, on a 400,
fell back to chunks without recording the rejection, so every background
season fetch spent a doomed request and live scoreboards learned nothing
from it (or it from them). The worker now consults and sets the same
6-hour memo fetch_espn_scoreboard() uses: a known rejection goes straight
to month/day chunks, and if every chunk fails the range is asked once for
a real error without re-spending the chunks.

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

* fix(web): keep plugin asset and action routes inside their directories

POST /plugins/assets/upload, GET /plugins/assets/list and POST
/plugins/assets/delete joined the request's plugin_id onto assets/plugins
unchecked, so '../../config' created, wrote, listed and deleted outside
it. #561 guarded only the route that serves the files. All three now go
through path_safety.resolve_under and answer 400 for anything but a
plain name, and delete only unlinks a metadata path that resolves into
that plugin's uploads directory.

PluginManager.get_plugin_directory refuses ids that are not one plain
path segment, so /plugins/action (which runs a manifest script from the
returned directory) and every other caller get the guard; the action
route also rejects such ids up front, covering its no-manager fallback.

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

* fix(web): report a no-op plugin update as already up to date

update_plugin() returns True both for a real update and for "nothing to
do" (a ZIP-installed monorepo plugin already at the registry version, a
bundled plugin). With no git commit to compare, POST /plugins/update
called every such success "updated successfully", so Check & Update All
counted most official plugins as updated on every run.

The route now reads what changed off the plugin itself (commit, else
manifest version, else last_updated) and returns data.update_status
(updated / up_to_date / local_only). The update-all toast is summarised
by PluginInstallManager.summarizeUpdateResults from that status, falling
back to the message for older servers.

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

* fix(sports): scoreboard scroll speed no longer follows target_fps

sports_scroll computed the crisp speed ladder against the global
target_fps whenever limit_refresh_rate_hz was the 100 Hz default. Since
frame-locked presentation (#545) the helper steps a fixed number of whole
pixels per presented frame and the panel presents at its real refresh, so
the General tab's "Scroll Frame Rate" became a speed multiplier: 60 ran a
50 px/s scoreboard at 100 px/s, 200 ran it at 25 px/s.

The ladder now uses the display manager's refresh_hz, then
display.hardware.limit_refresh_rate_hz, then the default. target_fps is
not consulted. Docstrings now say scroll_delay is ignored for pacing (no
behaviour change there) and describe the fixed-step model.

Tests: replace the tests that pinned target_fps as the ladder refresh and
described time-based stepping; assert speed independence from target_fps
(unit and end-to-end presented px/s against the real helper), that the
fixed per-frame step is applied, and that scroll_delay does not change
speed.

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

* fix(web): escape registry and upload values in plugin manager inline handlers

The store, saved-repository and custom-registry buttons built
onclick='...(${JSON.stringify(id)})...'. JSON.stringify leaves ' alone,
so a custom registry entry whose id contained ' closed the attribute and
added its own handler. One helper, jsStringAttr(), now HTML-escapes the
JSON literal for every one of those handlers, and the store View button
opens only http(s) repo links.

The live window.updateImageList (plugins_manager.js loads last, so its
copy wins over the file-upload widget's) wrote the uploaded file's
original name, path and ids into markup raw; they are escaped now.

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

* docs(changelog): note plugin asset, action and inline handler guards

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

* fix(update): let the root pip wrapper install web_interface/requirements.txt

Update Code, the automatic update's health check and Install Base
Requirements install web_interface/requirements.txt through
safe_pip_install.sh, which only allowed the root requirements.txt. The
first commit changing that file would fail its dependency install, and
the automatic updater rolls back any update whose dependencies did not
install -- on every device, for every newer commit.

The wrapper now lists both core requirement files. Only their folders
are resolved, so a requirements.txt symlinked out of the project is
compared by its target and refused (previously the root file's own
symlink target was what got allowed). The updater's file list is a
named constant, and a test runs the real wrapper (pip stubbed) on
every file Update Code and the rollback install.

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

* fix(web): do not retry plugin requests that got an HTTP answer

PluginAPI.request wrapped everything that was not a structured error as
NETWORK_ERROR: a proxy's 502 HTML page (response.json() throws) and a
JSON error without error_code included. Check & Update All retries
NETWORK_ERROR, so those updates were re-sent five more times with
backoff, contrary to the #587 contract that an HTTP error response is
the server's answer.

NETWORK_ERROR now means only that fetch() rejected. Any HTTP response
without an error_code, or with a body that is not JSON, is API_ERROR
with the HTTP status attached. Tested against the shipped api_client.js.

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

* fix(scroll): restart the stats window when an idle gap is dropped by size

#582 dropped an idle gap from the frame stats two ways: the reset_scroll()
sentinel, which also restarts the 5s window timer, and a size guard for
scrollers that never call reset_scroll(), which did not. On that path the
first real frame after the gap found the boundary overdue and logged a
stats line for a one-frame window. Both paths now share one seeding helper.

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

* fix(update): leave plugins alone when update_core's own rollback fails

update_core returns rollback_failed directly when a partial pull or an
update whose health check never started cannot be rolled back. run()
only held plugins back for 'verifying', so those devices still got new
plugin versions and a display restart on top of a core in an unknown
state -- the opposite of what the health-check path does, and of the
3.4.0 changelog (plugins are left alone if the rollback fails).

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

* docs(api): make the REST reference match the api_v3 package

Every documented request body, query parameter and response shape was
re-checked against the handlers in web_interface/blueprints/api_v3/.
Fixes calls that failed as documented (repo_url, action_id/params,
files/image_id, font_file+font_family, ?font=, cache key,
auto_enable_ap_mode, plugin limit keys), removes the font-override
endpoints dropped in #566, corrects response shapes (plugins/config,
plugins/schema, health, metrics, operation history, github-status,
fonts/catalog, cache/list, logs, wifi, on-demand, SSE streams), and adds
the 26 routes it omitted (backup, system auto-update/git, wifi radio,
starlark editor, MQTT bridge, status endpoints, skins).

Documents the merge semantics of partial JSON saves to /config/main and
/plugins/config and the dim-schedule POST accepting GET's days shape,
which land in the same change set. Replaces app.py line numbers and the
removed api_v3.py path with file and function names.

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

* fix(web): remove the General-tab plugin system toggles that did nothing

plugin_system.auto_discover, auto_load_enabled and development_mode had
General-tab toggles whose help tips promised dormant plugins and verbose
logging, but nothing reads them: every enabled plugin is discovered and
loaded regardless. Remove the three toggles.

The keys stay tolerated in stored configs. The save handler now stores
a flag only when a client sends it; treating a missing key as an
unchecked box would otherwise rewrite all three to false on every
General-tab save, which still posts plugins_directory.

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

* refactor(scroll): remove dead code left by #523/#570

- Drop the optional scipy.ndimage import and HAS_SCIPY; nothing read
  them since the numpy blend replaced the scipy path.
- Drop ScrollHelper._last_integer_position and frame_time_target, which
  were written but never read.
- Keep target_fps and set_target_fps() but document them as
  informational: nothing paces off them, yet ledmatrix-elections'
  test_scroll_pacing.py reads helper.target_fps back and third-party
  plugins may call the setter.
- Fix stale comments: fixed_pixels_per_frame's "use scroll_delay to
  throttle", set_sub_pixel_scrolling's "default: True", and
  set_frame_based_scrolling's claim that it steps.

The plugins monorepo was grepped for every removed name; none is used.

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

* docs(fonts): point plugins at plugin_manager.font_manager; drop removed overrides UI

FONT_MANAGER.md told plugins to read display_manager.font_manager, which
does not exist, so a plugin following it failed to load with
AttributeError. The shared FontManager lives on the PluginManager and
BasePlugin._get_font_manager() returns it (with a fallback for harnesses).

Also removes the Fonts-tab override workflow and element-override panels
that #566 deleted, from FONT_MANAGER.md and WEB_INTERFACE_GUIDE.md.

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

* docs(store): search via /plugins/store/list?query=; send Content-Type on registry curls

/plugins/store/search does not exist (404) and the list endpoint reads
query, not q. The registry guide's curl examples omitted the JSON
Content-Type, so the handlers saw an empty body and answered 400.

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

* fix(config): use the shared core-key list in the last three private copies

StartupValidator warned "Plugin 'auto_update' is enabled but not found" on
every display start with auto-update or a dim schedule on; the reserved
plugin-id check missed auto_update, sync, location and the rest; and
ConfigManager's (uncalled) orphan cleanup would have deleted display,
schedule and auto_update. All three now read src/core_config_keys.py, which
also gains CORE_SECRETS_KEYS for the github/youtube secrets sections.

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

* fix(web): partial JSON saves to /config/main change only what they send

A JSON body with one field reset every checkbox in the sections it touched:
the MQTT bridge's brightness slider turned off disable_hardware_pulsing,
inverse_colors, show_refresh_rate and use_short_date_format, and a
timezone-only save turned off web-UI autostart and weekly auto-updates.
Missing-means-unchecked now applies only to form posts: form-encoded bodies
and the v3 forms, which mark themselves with a hidden __form_section input.

Also on the config routes:
- vegas_min/max_cycle_duration no longer match the generic *_duration rule,
  so they stop landing in display_durations and a blank one no longer
  rejects the whole Display save;
- saving from the Raw JSON editor calls start_setup_if_needed like the
  General form, so enabling auto-update there finishes its setup;
- the schedule and dim-schedule POSTs accept the per-day days.<day> shape
  their GETs return, as well as the flat form keys.

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

* fix(scripts): install plugin dependencies from the configured plugins directory

install_plugin_dependencies.sh scanned only plugins/, but the Plugin
Store installs into plugin_system.plugins_directory (default
plugin-repos), so the documented "Recommended" fix found 0 plugins on
every store install. It now reads plugins_directory from
config/config.json (relative to the project root or absolute, default
plugin-repos) and also scans plugins/ for dev symlinks, installing a
plugin reached through both only once.

With set -e alone, `pip ... | tee` took tee's exit status, so a failed
pip install was reported as success; set -o pipefail.

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

* docs: replace stale API names, line numbers and the api_v3.py path

- ADVANCED_FEATURES: StreamManager methods that exist
  (get_next_segment, take_next_group, refresh, advance_cycle, ...), and the
  real on-demand status envelope ({status, data: {state, service}})
- app.py:199 / :144 / :607-619 line citations and
  web_interface/blueprints/api_v3.py (now a package) replaced with file and
  function names in ADVANCED_FEATURES, CONFIG_DEBUGGING,
  PLUGIN_ARCHITECTURE_SPEC, PLUGIN_QUICK_REFERENCE,
  PLUGIN_CONFIGURATION_TABS, TROUBLESHOOTING and web_interface/README
- CONFIG_DEBUGGING: partial /config/main saves change only sent keys; use
  /config/raw/main to replace the file; describe where validation runs
- TROUBLESHOOTING: clear_cache.py needs --clear-all (no args only prints
  usage)

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

* fix(scripts): verify the web interface that actually ships, on port 5000

verify_installation.sh failed every healthy install: it required the
long-removed web_interface_v2.py and looked for a listener on port 5001,
while the web interface binds 5000 (web_interface/start.py). It now
checks the files ledmatrix-web.service runs (start_web_conditionally.py,
web_interface/start.py, app.py) and port 5000. verify_web_ui.sh had the
same 5001 port in its listen check, HTTP probe and printed URLs.

Port matches are anchored so :50001 no longer counts as :5000.

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

* docs(plugins): one display-size contract: display_manager.width/height

CLAUDE.md (#580) says to read display_manager.width/height because
matrix is None when hardware init fails; the development guide, the
safety-harness doc and two DisplayManager docstrings still recommended
matrix.width/height. The bundled starlark-apps plugin read matrix.width
unguarded, so its magnify recommendation and frame scaling raised in
fallback mode (e.g. after the Pi 5 hardware refusal).

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

* fix(install): make install_service.sh --help print usage instead of installing

install_service.sh parsed no arguments, so `sudo ./scripts/install/
install_service.sh --help` (presented as harmless in MIGRATION_GUIDE.md)
rewrote ledmatrix.service, ledmatrix-web.service and both update-verify
units and enabled/started them. It now handles -h/--help (usage, exit 0,
no changes) and rejects any other argument with exit 2 before doing
anything. Running it with no arguments, as first_time_install.sh does,
is unchanged.

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

* docs(scroll): describe the fixed-step model and document frame_hold

Since #545 a crisp speed from scroll_config.configure() makes the helper
advance a fixed whole-pixel step per presented frame with no clock, and the
display manager's frame hold is part of the speed. The docs still described
the removed wall-clock model:

- scroll_config's module and configure() docstrings said speed is applied
  in time-based mode and that omitting the hold "falls back to fractional
  pixels"; omitting it actually runs the scroll frame_hold times too fast.
- SCROLL_PERFORMANCE.md said ScrollHelper accumulates elapsed time in both
  modes, and read a 20 ms stats median as missed refreshes although that
  is a healthy 50 px/s (hold 2) scroll. It now explains the fixed step,
  the hold-dependent healthy median, that target_fps plays no part, and
  that a hand-added scroll_pixels_per_second loses to a schema-default pair.
- PLUGIN_API_REFERENCE.md documented set_scrolling_state(is_scrolling)
  without frame_hold; it now documents the parameter (core 3.4.0) with a
  configure() + set_scrolling_state example.
- update_scroll_position/set_scroll_speed and set_scrolling_state
  docstrings say the same.

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

* docs(config): mark target_fps legacy; describe what Vegas scroll_delay does

- General tab "Scroll Frame Rate" (target_fps) is labelled legacy: after
  the sports_scroll fix nothing in core scrolling reads it. The field and
  its API validation stay so saved configs and plugins that read
  global_config['target_fps'] keep working. CONFIG_REFERENCE says the same.
- Vegas frame_based_scrolling/scroll_delay were described as frame-count
  stepping at ~50 FPS. Neither steps nor sets a frame rate: frame-based
  mode converts the speed to px per scroll_delay, clamps it to 0.1-5, and
  still advances by elapsed time, so the applied speed is
  clamp(scroll_speed * scroll_delay, 0.1, 5) / scroll_delay px/s. The
  config comments, render_pipeline comment and CONFIG_REFERENCE rows now
  say so. No behaviour change.

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

* docs(deps): describe how plugin dependencies are really installed

The guides said the web service runs as root, that installs pick --user
from os.geteuid(), and quoted a warning and a
PluginManager._install_plugin_dependencies() method that don't exist. The
web unit runs as the installing user; store installs go through
install_requirements_file() and sudo safe_pip_install.sh (root), with a
user-level fallback that says so, and load-time installs run in the
display service's own (root) interpreter.

Manual paths now use the configured plugins directory (plugin-repos/ by
default) instead of plugins/, which store installs no longer use, and
install_plugin_dependencies.sh is described as scanning that directory.

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

* fix(update): count local changes one way for the preflight and the pull

The automatic update's preflight ignored mode-only changes and anything
whose status line contained plugins/ or plugin-repos/, then promised
"Automatic updates will not stash your changes". perform_core_update
used plain git status (modes count) and ignored only 'plugins/', then
ran 'git stash push -- :!plugins', which nothing ever pops. So an edit
to a bundled plugin under plugin-repos/, or the installer's chmods on
tracked scripts, passed the preflight and was stashed away for good.

- auto_update.local_changes() is the one predicate both use:
  core.fileMode=false, porcelain -z, and plugins/ and plugin-repos/
  excluded by leading folder rather than substring (a core file under
  web_interface/static/v3/js/plugins/ now counts).
- Update Code's explicit stash leaves out both plugin folders; the
  pull's --autostash carries their edits and mode changes across and
  reapplies them.
- The automatic updater calls perform_core_update(stash_local_changes=
  False), which refuses instead of stashing edits that appeared after
  the preflight; update_core reports that as 'blocked'.

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

* fix(scripts): diagnostics follow the web autostart default and api_v3 package

#556 made a missing web_display_autostart mean "start" (only an explicit
false/off keeps the web interface down), but the diagnostics still said
otherwise: diagnose_web_ui.sh reported a missing key as "defaults to
false", diagnose_web_interface.sh said the web interface "will not start
unless this is set to true" and recommended enabling it, and
debug_web_manual.py printed False. Troubleshooting a down web UI pointed
users at a non-cause.

Both shell scripts now evaluate the setting with the launcher's own
autostart_enabled() (inline fallback if it cannot be imported) and report
on / off / not set (on) / unparseable config; debug_web_manual.py uses
the same function. They also check web_interface/blueprints/api_v3/
__init__.py: api_v3.py became a package in #553, so every healthy
checkout was reported as missing a file.

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

* docs(install): what install_service.sh installs; verify script port; no sudo for --help

install_service.sh installs and starts ledmatrix, ledmatrix-web and the
update-verify units, not only ledmatrix.service (systemd/README.md,
README.md). MIGRATION_GUIDE presented 'sudo install_service.sh --help'
as a harmless check; it now shows --help without sudo and warns what a
real run does. SSH_UNAVAILABLE_AFTER_INSTALL: verify_installation.sh
checks the web interface on port 5000.

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

* docs(changelog): note update-all, plugin system settings and script fixes

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

* fix(display): size the preview after orientation and pixel mappers

display_geometry.physical_size claimed to give DisplayManager's answer but
only computed cols*chain x rows*parallel. RGBMatrix.width/height are measured
after the library's pixel mappers, so a Rotate:90 / orientation 90 chain
previewed 128x32 for a 32x128 panel and a U-mapper chain of four 256x32 for
128x64.

Model the built-in mappers' size effect as the pinned lib/pixel-mapper.cc
does (Rotate, U-mapper, V-mapper, StackToRow, Remap; Mirror and unknown
names leave it alone), and move the orientation composition here so
DisplayManager and the preview share it. The module docstring no longer
claims the sync handshake uses it; that imports only DEFAULT_CHAIN_LENGTH.

Audit finding F18.

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

* fix(display): refuse settings the rgbmatrix library aborts on, on every board

The library answers several settings with a NULL matrix or abort() rather
than an error, so the display service crash-looped (Restart=on-failure)
instead of reaching fallback mode: rows above 64, chain_length above 255
(uint8_t binding setter, documented as "no upper limit"), a misspelled
hardware_mapping, and parallel 2-3 on a single-output mapping, reachable
from the Display form on the default adafruit-hat(-pwm) mapping. #586 only
guarded the Pi 5 subset.

- src/matrix_support.py holds the rules for every board (Options::Validate
  ranges, binding integer types, mapping names and outputs from
  lib/hardware-mapping.c) plus the Pi 5 ones, and is the one source of the
  API's numeric ranges.
- DisplayManager checks them before building options and raises
  MatrixSettingsRefused, so a hand-edited config falls back with a logged,
  reported reason. Emulator mode only warns.
- The config API refuses them with a 400 naming the setting; combinations
  are checked against stored values but reported only when the request
  sets a field involved.
- The hardware status file gains "cause" (settings/library/forced). The
  fallback log and Display banner give the Pi 5 rebuild hint only for a
  library failure instead of rebuild + gpio_slowdown advice for every
  failure; one Pi 5 slowdown recommendation (1-3, start at 1).
- The Display form offers classic/classic-pi1 and orientation 90/270 and
  renders any other stored mapping selected with a warning, so an
  unrelated save no longer rewrites them; the API accepts 90/270.

Audit findings F03, F16, F19, F21.

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

* docs(display): library limits, template defaults and Pi 5 slowdown

- rows 8-64, chain_length 1-255, parallel limited by the mapping's outputs,
  classic/classic-pi1 mappings and orientation 90/270 documented.
- Defaults are the config.template.json values: config migration adds
  missing keys from the template, so the listed "code defaults" never
  applied.
- One Raspberry Pi 5 gpio_slowdown recommendation: 1-3 in PIO mode,
  starting at 1.
- Troubleshooting describes the refused-settings fallback, and CHANGELOG
  corrects the Unreleased "no upper limit" entry.

Audit findings F19, F20, F21.

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

* fix(scripts): scroll_speeds.py opens the panel with the service's options

--measure and --demo built RGBMatrixOptions from a private copy of the
display service's builder that had drifted: gpio_slowdown came from
display.hardware (default 2) instead of display.runtime (default 3), and
rp1_rio, panel_type, disable_hardware_pulsing, inverse_colors,
pixel_mapper_config and orientation were skipped, with different defaults
(hardware_mapping "regular", pwm_bits 11). A panel needing a high slowdown
was measured -- or garbled -- in a setup the service never drives.

The option filling in DisplayManager._setup_matrix moves, unchanged, into
DisplayManager.apply_matrix_options(options, config), which _setup_matrix
calls and the script reuses (overriding only limit_refresh_rate_hz for
--measure). The script now loads the whole config rather than the hardware
block. Tests pin the script's options to the service's attribute for
attribute.

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

* fix(scripts): scroll_speeds.py recommends keys the resolver honours

The ladder ended by telling users to set
display_options.scroll_pixels_per_second. scroll_config ranks that key
below the scroll_speed + scroll_delay pair, deliberately, and several
plugin schemas default the pair into config, so the advised key was
silently ignored (a schema-default 1/0.02 pair plus an advised 66 still
resolved to 50 px/s).

The advice is now the pair that selects the crisp speed exactly
(pixels_per_frame every frame_hold/refresh seconds), explains that the
pair outranks scroll_pixels_per_second, and gives the scoreboards'
per-league scroll_settings.scroll_speed (px/s) form. Tests resolve the
printed pair over a schema-default pair and check it lands on the
advertised speed and hold.

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

* docs: withdraw the target_fps claim for sports_scroll; fix the Vegas speed formula

- SPORTS_UNIFICATION.md still presented honouring global target_fps as
  sports_scroll's added behaviour and its one user-visible gain; note that
  it was withdrawn because it had become a speed multiplier.
- ADVANCED_FEATURES.md gave Vegas scrolling as
  (scroll_speed / target_fps) * elapsed; the real rule is scroll_speed px/s
  by elapsed time, through a 0.1-5 px per scroll_delay clamp when
  frame_based_scrolling is on.

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

* docs(changelog): scroll model fixes

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

* fix(dev): link-github links plugins from the ledmatrix-plugins monorepo

link-github <name> cloned https://github.com/ChuckBuilds/ledmatrix-<name>.git,
and those per-plugin repositories no longer exist: official plugins are
directories in the ledmatrix-plugins monorepo. It now clones (or pulls) the
monorepo once into the dev directory, finds plugins/<name>,
plugins/ledmatrix-<name> or the plugin whose manifest id is <name>, and
links it under its manifest id. With an explicit repo URL it still links a
single-repository plugin as before.

dev_plugins.json: github_user is honoured again (monorepo owner, e.g. a
fork), plus plugins_repo and plugins_branch; github_pattern, which was
documented but never read, is dropped and warned about. Ships
dev_plugins.json.example and git-ignores dev_plugins.json, both of which
the guide promised. Reading JSON falls back to python3 when jq is missing
(get_plugin_id silently returned nothing without jq).

update/status/list find the git checkout above a monorepo plugin
directory (its .git is not in the plugin dir), and update pulls a shared
checkout once. status no longer exits 1 when nothing is broken.

Docs: PLUGIN_DEVELOPMENT_GUIDE (quick start, link-github, configuration,
workflow, store integration, hello-world link, submission), and the
nonexistent scripts/git-hooks/pre-push-plugin-version and
scripts/bump_plugin_version.py replaced with the real rule: bump the
manifest version and run update_registry.py. scripts/dev/README.md and
CLAUDE.md updated to match.

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

* docs(scripts): monorepo workspace layout; fix_perms and install READMEs

MULTI_ROOT_WORKSPACE_SETUP described one sibling repository per plugin;
setup_plugin_repos.py links ../ledmatrix-plugins/plugins/* into
plugin-repos/ and update_plugin_repos.py pulls only the monorepo, and the
workspace file opens LEDMatrix plus ../ledmatrix-plugins.

scripts/fix_perms/README.md listed cache directories
fix_cache_permissions.sh never touches and a 'ledmatrix' service user
that doesn't exist (also in scripts/install/README.md); adds
safe_pip_install.sh. install/README: install_service.sh installs the web
and update-verify units too.

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

* fix(update): keep the rollback's pip retries inside the unit time limit

The health check reinstalled the previous requirements by trying the
next bash path after any failure, including a 600 s pip timeout. Two
files, two paths: up to 40 minutes of pip alone, while systemd stops
ledmatrix-update-verify.service at TimeoutStartSec=30min -- killing the
rollback half-way and leaving the update 'verifying' until the web UI
calls it lost.

- Like permission_utils.install_requirements_file, only a sudo refusal
  moves on to the next bash; a pip that ran and failed or timed out is
  not repeated. The refusal wording is one list
  (permission_utils.SUDO_REFUSAL_PHRASES), mirrored in the stdlib-only
  verifier and pinned equal by a test.
- All reinstalls in one rollback share a 600 s budget.
- WORST_CASE_SECONDS adds up every timeout on the longest path (27.5
  min); a test holds it under the unit's TimeoutStartSec and that under
  the web UI's VERIFY_LOST_SECONDS.

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

* fix(plugins): prepare plugin configs one way for load, saves, GET, hot reload and dev tools

Plugin config was prepared differently depending on how it arrived:

- JSON POST /plugins/config built a partial body on schema defaults, so
  {"enabled": true} reset every other setting of the plugin. It now merges
  onto the stored section first, as the form path already did.
- Legacy-boolean normalization (#588) ran only at load: GET /plugins/config
  returned the raw boolean, posting it back failed validation, and hot
  reload handed plugins the raw section (a legacy dynamic_duration: true
  came back as a boolean). schema_manager.prepare_plugin_config (normalize,
  then defaults) is now used by PluginManager.load_plugin, both save paths,
  GET, the save notifications and DisplayController's hot-reload callback.
- The JSON save's filter kept only enabled/display_duration/live_priority
  and dropped a submitted skin, skin_options or vegas_* tuning key. There
  is now one core-owned per-plugin list, schema_manager.CORE_PLUGIN_PROPERTIES,
  used by validation and by the save filter; PluginManager's
  CORE_OWNED_CONFIG_KEYS is its vegas subset.
- Plugin sections posted to /config/main were stored verbatim, including
  values /plugins/config rejects. They now go through the same preparation
  (_prepare_plugin_config_for_save, extracted from save_plugin_config), and
  a failing section rejects the whole save before anything is written.
- dev_server read only top-level defaults and let a schema enabled:false
  win; build_full_config shallow-merged overrides, dropping sibling
  defaults; the harness extracted defaults differently from the device.
  loading.build_config now uses the device's extraction and preparation,
  and dev_server, check_plugin, render_plugin and the harness all use it.

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

* docs(mqtt-bridge): brightness changes apply live and touch nothing else

The display service's hot reload applies a saved brightness within a few
seconds, and /config/main no longer resets other display settings on a
brightness-only JSON body.

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

* docs(changelog): automatic update hardening

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

* docs(config): rewrite PLUGIN_CONFIG_ARCHITECTURE for the v3 web UI

It described web_interface_v2.py and index_v2.html (both gone), client-side
form generation, one POST per field with {key, value}, and 'no nested
objects'. The v3 UI renders plugin forms server-side from the schema
(pages_v3 partial + plugin_config.html macros, nested sections and
x-widgets), posts the whole form once, and save_plugin_config() merges onto
the stored section, validates, splits x-secret fields and notifies the
plugin.

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

* docs(mqtt): brightness saves apply via hot reload and leave other settings alone

The bridge README said brightness is applied on the display's next
restart; the display controller's config hot reload applies it within
seconds. It also now states that the bridge's partial JSON save changes
only brightness (the /config/main merge fix in this change set).

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

* fix(update): don't log pip's output from the health check's reinstall

pip can echo a private index URL with embedded credentials;
permission_utils redacts it, the stdlib-only verifier cannot, so it
logs the exit code only.

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

* docs(config): mark the plugin_system toggles as unused legacy keys

auto_discover, auto_load_enabled and development_mode are read by
nothing and leave the General tab in this change set (F40). CONFIG_REFERENCE
said they were read by the plugin loader; PLUGIN_CONFIGURATION_GUIDE and
the REST reference listed them as live settings.

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

* docs(changelog): docs and developer tools group

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

* fix(web): legacy plugin-system toggles no longer count as a General save

auto_discover, auto_load_enabled and development_mode have left the General
form, so a post carrying only one of them is not a general-settings save and
must not treat web_display_autostart and auto_update as unchecked. The
plugin_system block itself is left as on main for the branch that reworks it.

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

* docs(changelog): config-save and plugin-config preparation fixes

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

* docs(claude): re-check matrix_support.py rules when the library submodule is bumped

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

* fix: address Codacy findings on the core audit PR

- plugin_manager.prepare_plugin_config: when the fallback legacy-boolean
  pass also fails, log a warning instead of a bare except/pass.
- api_client.js: request() refuses any endpoint that is not a plain path
  under /api/v3 ("//host", backslashes, ".." or "." segments, whitespace,
  control characters) with INVALID_ENDPOINT before calling fetch(), and
  plugin ids are URL-encoded wherever they are put into a URL (also in the
  app-shell batch load).
- test_update_all.js: pins both against the shipped client.

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

* fix(web): check endpoint control characters without a control-character regex

Codacy (ESLint no-control-regex, Biome noControlCharactersInRegex) flags
the \x00-\x1f range in checkEndpoint's regex. Test the char codes
instead; the endpoints refused are unchanged.

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

* test(auto-update): make the seed script executable on disk, not only in the index

On Linux Repo.publish() commits with -a, which recorded scripts/run.sh
as 100644 upstream because the seed file was never chmod +x. The pull
then brought in the same mode the installer chmod had made locally, so
installer_chmod saw no mode change left to check. The updater was fine:
with the upstream commit at 100755 the --autostash carries the device's
chmod across. Verified under Linux (WSL, git 2.43): the old helper fails
exactly as CI did, the fixed one passes all 63 tests in the file.

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

---------

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

.gitignore

@@ -39,11 +39,12 @@ htmlcov/
 # Cache directory (root level only, not src/cache which is source code)
 /cache/
 
-# Development plugins directory
+# Development plugins directory: symlinks into a ledmatrix-plugins checkout
-# Plugins are managed as separate repositories via multi-root workspace
+# See docs/PLUGIN_DEVELOPMENT_GUIDE.md and docs/MULTI_ROOT_WORKSPACE_SETUP.md
-# See docs/MULTI_ROOT_WORKSPACE_SETUP.md for details
 plugins/*
 !plugins/.gitkeep
+# Local settings for scripts/dev/dev_plugin_setup.sh (template: dev_plugins.json.example)
+/dev_plugins.json
 
 # Binary files and backups
 bin/pixlet/

CHANGELOG.md

@@ -19,6 +19,44 @@ accepts both, but the store flags the old spelling as deprecated
 
 ## Unreleased
 
+Config saves and plugin config preparation:
+
+- A JSON `POST /api/v3/config/main` changes only the keys it sends. The MQTT
+  bridge's brightness slider used to turn off `disable_hardware_pulsing`,
+  `inverse_colors`, `show_refresh_rate` and `use_short_date_format`, and a
+  timezone- or location-only save turned off web-UI autostart and weekly
+  automatic updates. Missing checkboxes still save as unchecked for the
+  settings forms (they now send a hidden `__form_section` field) and for
+  form-encoded posts.
+- A partial JSON `POST /api/v3/plugins/config` merges onto the plugin's stored
+  settings instead of resetting everything it didn't send to the schema
+  defaults, and keeps a submitted `skin`, `skin_options`, `vegas_width_pct`,
+  `vegas_overflow` or `vegas_max_width_screens` (they were silently dropped).
+- Plugin sections posted to `/config/main` are validated and prepared exactly
+  like `/plugins/config`; a value that endpoint rejects is rejected here too,
+  and nothing is saved.
+- Legacy boolean settings (#588) are read as `{"enabled": ...}` objects
+  everywhere, not just when the plugin loads: `GET /plugins/config` returns
+  the object, posting it back saves, and hot reload hands plugins the same
+  shape (schema defaults included) they were constructed with.
+  `schema_manager.prepare_plugin_config` is the one implementation.
+- `scripts/dev_server.py`, `check_plugin.py`, `render_plugin.py` and the plugin
+  harness build configs the way a device does: nested defaults are included,
+  a schema `enabled: false` no longer beats the forced `enabled: true` in the
+  dev server, and nested overrides such as `{"nhl": {"enabled": true}}` keep
+  the other defaults of that section.
+- Clearing Vegas "Min/Max Cycle Time" no longer rejects the whole Display save,
+  and those fields no longer add junk entries to `display.display_durations`.
+- Turning automatic updates on from the Raw JSON editor finishes their setup
+  like the General tab does, instead of waiting for the next display restart.
+- `POST /config/schedule` and `/config/dim-schedule` accept the per-day
+  `days.<day>.{enabled,start_time,end_time}` shape their GETs return, as well
+  as the flat form keys.
+- The startup check no longer warns that `auto_update` or `dim_schedule` is
+  "enabled but not found in plugins directory", and plugin ids that collide
+  with any core config section are flagged: the last private copies of the
+  core-key list now use `src/core_config_keys.py`.
+
 New module a plugin may import via `src.*` (floor on the release that ships
 this):
 
@@ -59,6 +97,36 @@ Sports data:
   to decide whether to submit a season range to the service or fetch it
   themselves on an older core.
 
+Scrolling:
+
+- **Scoreboard scroll speed no longer changes with the General tab's "Scroll
+  Frame Rate" (`target_fps`).** Scoreboards on `src.common.sports_scroll`
+  computed their speed for that rate while the panel kept presenting at its
+  real refresh, so on a 100 Hz panel 60 ran a 50 px/s scoreboard at 100 px/s
+  and 200 ran it at 25 px/s. Speed now comes from `scroll_speed` and the panel
+  refresh only. The field is labelled legacy: nothing in core scrolling reads
+  it. Anyone who lowered it will see scoreboards scroll slower than before --
+  at the speed they configured.
+- `scripts/scroll_speeds.py --measure` / `--demo` open the panel with the
+  display service's own options (`DisplayManager.apply_matrix_options`), so
+  `display.runtime.gpio_slowdown`, `rp1_rio`, `panel_type` and orientation are
+  honoured; the script used to read `gpio_slowdown` from `display.hardware`.
+  Its closing advice now gives the `scroll_speed` + `scroll_delay` pair
+  instead of `scroll_pixels_per_second`, which the resolver ignores whenever
+  the pair is present.
+- The frame-stats log no longer opens a scroll with a one-frame window for
+  scrollers that never call `reset_scroll()`.
+- Removed dead scroll code: the optional scipy import (`HAS_SCIPY`),
+  `ScrollHelper._last_integer_position` and `frame_time_target`.
+  `ScrollHelper.target_fps` / `set_target_fps()` remain, documented as
+  informational.
+- Docs describe the fixed-step scroll model: `PLUGIN_API_REFERENCE.md`
+  documents `set_scrolling_state(..., frame_hold)` (omitting the hold runs a
+  scroll `frame_hold` times too fast), `SCROLL_PERFORMANCE.md` no longer reads a
+  held 20 ms frame as missed refreshes, and Vegas `frame_based_scrolling` /
+  `scroll_delay` are described as the speed clamp they are rather than frame
+  stepping. Scoreboard `scroll_delay` is documented as ignored for pacing.
+
 Web interface:
 
 - The plugin settings form honours `"x-display": "hidden"` in config schemas:
@@ -68,9 +136,9 @@ Web interface:
   declared, e.g. countdown's row `id` and weather's `api_key` / `radar_zoom`.
   See `docs/widget-guide.md`.
 - Display settings no longer silently cut values on save: columns were capped
-  at 128, chain length at 24 and PWM LSB nanoseconds at 500. Rows, columns and
+  at 128, chain length at 24 and PWM LSB nanoseconds at 500. Columns have no
-  chain length now have no upper limit (the current rgbmatrix library still
+  upper limit, chain length is 1–255 and rows must be even and 8–64 (see
-  rejects more than 64 rows per panel); rows must be even and at least 8,
+  "Display hardware settings the library refuses" below);
   parallel is 1–3 and PWM dither bits 0–2, matching the library. A stored GPIO
   slowdown, PWM dither bits or refresh-rate cap of 0 no longer shows (and
   re-saves) as 3, 1 or 120, and the refresh cap accepts 0 (no cap). The config
@@ -112,6 +180,57 @@ Web interface:
   re-sent with backoff instead of being counted as failed and skipped — that is
   how a disabled plugin with an update waiting was silently left out.
 
+Security (request paths and inline handlers, siblings of #561):
+
+- `POST /api/v3/plugins/assets/upload`, `GET .../assets/list` and
+  `POST .../assets/delete` validate `plugin_id` with `src/common/path_safety`
+  and answer 400 otherwise. A `plugin_id` of `../../config` used to create an
+  `uploads/` directory outside `assets/plugins`, write images and
+  `.metadata.json` there, list it, and delete whatever file a metadata entry
+  named. Delete now unlinks only a path that resolves inside that plugin's
+  uploads directory (any other entry is dropped without touching a file).
+- `PluginManager.get_plugin_directory()` returns `None` for anything but a
+  plain name, so `POST /api/v3/plugins/action` can no longer run a manifest
+  script from a directory outside the plugins directory (`../elsewhere`); the
+  route also rejects such ids with 400.
+- Plugin Store, saved-repository and custom-registry buttons escape registry
+  values for their inline `onclick` handlers (`jsStringAttr` in
+  `plugins_manager.js`). An entry id containing `'` used to close the attribute
+  and add its own script. The store's View button opens only `http(s)` links.
+- The uploaded-images list escapes each file's original name, path and ids; a
+  name like `<img src=x onerror=...>.png` was inserted as markup.
+
+Display hardware settings the library refuses:
+
+- The rgbmatrix library answers several settings with no matrix or `abort()`
+  rather than an error, on every board, so the display service crash-looped
+  instead of falling back: rows above 64, `chain_length` above 255 (the Python
+  binding stores it in one byte; this was documented as "no upper limit"), a
+  misspelled `hardware_mapping`, and `parallel` 2–3 on a mapping with one output
+  (`adafruit-hat`, `adafruit-hat-pwm`, `regular-pi1`, `classic-pi1`) — the last
+  one reachable from the Display form on the default mapping. The config API
+  now refuses them with a 400 naming the setting, and `DisplayManager` refuses
+  a hand-edited one before creating the matrix: logged, fallback mode, reported
+  by `/api/v3/hardware/status`. The rules, including the Pi 5 ones, live in
+  `src/matrix_support.py` and must be re-checked when the submodule is bumped.
+- `/api/v3/hardware/status` adds `cause`: `"settings"` when LEDMatrix refused
+  the config, `"library"` when the library failed. The Display tab banner and
+  the fallback log line give the Pi 5 rebuild hint only for a library failure;
+  they used to follow every failure with it and with GPIO slowdown advice.
+- The Display form offers the `classic` and `classic-pi1` mappings and the
+  `90` / `270` orientations, and renders any other stored mapping selected with
+  a warning. With no option selected the browser posted the first one, so one
+  unrelated save rewrote those settings. The API accepts orientation `90` and
+  `270`, which `DisplayManager` already applied.
+- The display size the web preview, Starlark magnify default and
+  `scripts/dev/vegas_audit.py` compute (`src/display_geometry.py`) now applies
+  `orientation` and `pixel_mapper_config` as the library does: `Rotate:90`
+  swaps width and height, `U-mapper` folds the chain.
+- One Raspberry Pi 5 GPIO slowdown recommendation everywhere: 1–3 in PIO mode,
+  starting at 1. README and the config reference now describe the template
+  values as the defaults; the "code default" values they listed never apply,
+  because config migration fills missing keys from the template.
+
 Plugin system:
 
 - A plugin no longer starts with a schema warning and a degraded flag because
@@ -141,6 +260,96 @@ Core:
   ownership step is now skipped where `os.chown` is missing. No behaviour
   change on the Pi.
 
+Automatic updates and Update Code:
+
+- An update that changes `web_interface/requirements.txt` is no longer rolled
+  back on every auto-updating device. `safe_pip_install.sh` allowed only the
+  root `requirements.txt`, so the install Update Code and the health check run
+  for the web requirements was refused, and the health check rolls back any
+  update whose dependencies failed (Install Base Requirements failed the same
+  way). The wrapper now allows both core requirement files; a core requirement
+  file symlinked out of the project is refused.
+- The automatic update's local-change check and Update Code now count changes
+  the same way (`auto_update.local_changes`): permission-only changes and
+  anything under `plugins/` or `plugin-repos/` don't count, and a core path
+  that merely contains `plugins/` does. Such edits used to pass the check and
+  then be stashed by the pull and never restored, despite "will not stash your
+  changes". The pull's `--autostash` now carries them across. Update Code
+  still stashes other edits; the automatic update refuses instead.
+- When the automatic update's own rollback fails (a partial pull, or a health
+  check that never started), plugins are no longer updated and the display is
+  not restarted, as the 3.4.0 notes promised.
+- The health check's dependency reinstall no longer retries pip failures or
+  timeouts with a second bash path, and all reinstalls share a 10-minute
+  budget, so a rollback finishes inside the unit's 30-minute limit instead of
+  being killed mid-way.
+
+Small fixes (update-all, plugin system settings, scripts):
+
+- **Check & Update All** counts a plugin that had nothing to update as
+  "already up to date" instead of "updated". ZIP-installed monorepo plugins
+  (most official ones) already at the registry version were called "updated
+  successfully" on every run. `POST /plugins/update` now returns
+  `data.update_status` (`updated`, `up_to_date`, `local_only`).
+- An update request that got an HTTP error answer without an `error_code`, or
+  a body that is not JSON (e.g. a reverse proxy's 502 page), is no longer
+  classified as `NETWORK_ERROR` and re-sent five times. Only a request that got
+  no HTTP answer is retried; the rest are `API_ERROR` with the HTTP status.
+- The General tab no longer shows Auto Discover Plugins, Auto Load Enabled
+  Plugins or Development Mode. Nothing read `plugin_system.auto_discover`,
+  `auto_load_enabled` or `development_mode`: every enabled plugin was always
+  discovered and loaded. Stored values are kept, and saving the General tab no
+  longer rewrites them to `false`.
+- `BackgroundDataService` shares the 6-hour "ESPN rejects date ranges" memo
+  with `fetch_espn_scoreboard`, so a background season fetch no longer spends a
+  doomed range request first once either path has seen a rejection.
+- `scripts/install_plugin_dependencies.sh` installs from the configured
+  `plugin_system.plugins_directory` (default `plugin-repos`, where the Plugin
+  Store installs) and also scans `plugins/` for dev symlinks. It used to scan
+  only `plugins/` and find nothing. A failed `pip install` is now reported as a
+  failure instead of being hidden by `tee`.
+- `scripts/verify_installation.sh` no longer fails a healthy install: it
+  checked for the removed `web_interface_v2.py` and port 5001. It and
+  `scripts/verify_web_ui.sh` now check port 5000, where the web interface
+  listens.
+- `scripts/install/install_service.sh --help` prints usage and exits without
+  changes. It used to ignore the flag and reinstall and restart every service.
+  Unknown arguments are rejected before anything runs.
+- `scripts/diagnose_web_ui.sh`, `scripts/diagnose_web_interface.sh` and
+  `scripts/debug/debug_web_manual.py` apply the launcher's own autostart rule
+  (only an explicit `web_display_autostart: false` keeps the web interface
+  down), so a missing key no longer shows as disabled. The shell scripts also
+  check `web_interface/blueprints/api_v3/`, which became a package, instead of
+  reporting `api_v3.py` as missing.
+
+Docs and developer tools:
+
+- `docs/REST_API_REFERENCE.md` rechecked against every handler: request
+  fields that made documented calls fail (`repo_url`, `action_id`/`params`,
+  `files`/`image_id`, `font_file`+`font_family`, `?font=`, cache `key`,
+  `auto_enable_ap_mode`, plugin limit keys) and response shapes are fixed, the
+  removed font-override endpoints are gone, and the 26 undocumented routes
+  (backup, git/auto-update, WiFi radio, Starlark editor, MQTT bridge, status
+  endpoints, skins) are listed. Store search is `/plugins/store/list?query=`.
+- `FONT_MANAGER.md` no longer tells plugins to read
+  `display_manager.font_manager`, which does not exist; use
+  `plugin_manager.font_manager` / `BasePlugin._get_font_manager()`.
+- Plugin docs, `DisplayManager` docstrings and the bundled `starlark-apps`
+  plugin now all read the display size from `display_manager.width/height`,
+  which works in fallback mode where `matrix` is `None`.
+- `scripts/dev/dev_plugin_setup.sh link-github <name>` links the plugin from a
+  clone of the `ledmatrix-plugins` monorepo (per-plugin `ledmatrix-<name>`
+  repositories no longer exist). `dev_plugins.json` honours `github_user`,
+  `plugins_repo` and `plugins_branch`; `dev_plugins.json.example` ships and
+  `dev_plugins.json` is git-ignored. `update`/`status` handle monorepo links,
+  and `status` no longer exits 1 when nothing is broken.
+- Rewritten for current behaviour: plugin dependency installation (web service
+  runs as the installing user and installs through `safe_pip_install.sh`),
+  `PLUGIN_CONFIG_ARCHITECTURE.md`, `MULTI_ROOT_WORKSPACE_SETUP.md`; stale
+  `app.py` line numbers, `api_v3.py` paths, StreamManager method names,
+  nonexistent version-bump scripts and `ledmatrix` service user references
+  removed.
+
 ## 3.4.0
 
 Plugin-facing changes since 3.3.0 (tag `v3.3.1`) not covered further down:

CLAUDE.md

@@ -30,7 +30,7 @@
   `config.get(...)`, never a separate accessor
 
 ## Dev Workflow
-- Link a plugin for development: `./scripts/dev/dev_plugin_setup.sh link-github <name>` (or `link <name> <path>`); symlinks land in `plugins/` — set `plugin_system.plugins_directory` to `plugins` so discovery picks them up
+- Link a plugin for development: `./scripts/dev/dev_plugin_setup.sh link-github <name>` clones the `ledmatrix-plugins` monorepo into `~/.ledmatrix-dev-plugins/` and links its `plugins/<name>` under the manifest id (add a repo URL for a plugin with its own repo; or `link <name> <path>`); symlinks land in `plugins/` — set `plugin_system.plugins_directory` to `plugins` so discovery picks them up. Fork/location overrides: `dev_plugins.json` (from `dev_plugins.json.example`)
 - Browser preview without the display loop: `python3 scripts/dev_server.py` → http://localhost:5001
 - Full display in emulator mode: `python3 run.py -e` (or `EMULATOR=true python3 run.py`)
 - Validate one plugin headlessly: `python3 scripts/check_plugin.py --plugin <id>`
@@ -63,4 +63,4 @@
   `self.display_manager.image.paste(img, (x, y))` then `update_display()`
   (use a mask for transparency: `image.paste(rgba, (x, y), rgba)`)
 - When modifying a plugin in the monorepo, you MUST bump `version` in its `manifest.json` and run `python update_registry.py` — otherwise users won't receive the update
-- `src/pi5_matrix_support.py` hardcodes what the pinned `rpi-rgb-led-matrix-master` can drive on a Raspberry Pi 5 (`Rp1PioConfigSupported()` in `lib/rp1/rp1_pio_backend.cc`). Re-check it whenever the submodule is bumped: a stale rule blocks Pi 5 settings the new library supports, and a missing one lets the display service crash-loop
+- `src/pi5_matrix_support.py` hardcodes what the pinned `rpi-rgb-led-matrix-master` can drive on a Raspberry Pi 5 (`Rp1PioConfigSupported()` in `lib/rp1/rp1_pio_backend.cc`). Re-check it whenever the submodule is bumped: a stale rule blocks Pi 5 settings the new library supports, and a missing one lets the display service crash-loop. `src/matrix_support.py` holds the same kind of rules for every board (rows, chain length, mapping names, parallel per mapping) and needs the same re-check

README.md

@@ -148,7 +148,7 @@ The system supports live, recent, and upcoming game information for multiple spo
     ```bash
     sudo RPI_RGB_FORCE_REBUILD=1 ./first_time_install.sh
     ```
-  - Pi 5 config: leave `rp1_rio` at `0` (PIO mode, default) and set `gpio_slowdown` to `1` or `2`.
+  - Pi 5 config: leave `rp1_rio` at `0` (PIO mode, default) and start `gpio_slowdown` at `1`, raising it a step at a time if the image flickers or shows garbage (see `gpio_slowdown` under Display Settings).
   - **1GB models (Pi 3B / 3B+) and other low-memory boards**: supported, but the `rpi-rgb-led-matrix` C++ build needs more memory than the Pi has. The installer detects this automatically, compiles with fewer parallel jobs, and adds a temporary swapfile for the build which it removes afterwards. Expect that step to take 15-25 minutes instead of 2-5, and leave at least **3GB free** on the SD card. If you manage swap yourself, opt out with `--skip-swap`. To pin the compiler down further, use `--build-jobs 1`.
 
 
@@ -485,6 +485,10 @@ If you are copying my exact setup, you can likely leave the defaults alone. Howe
 
 The display settings are located in `config/config.json` under the `"display"` key and are organized into three main sections: `hardware`, `runtime`, and `display_durations`.
 
+The defaults below are the values in `config/config.template.json`. They are what applies when you haven't set a key: on every load, LEDMatrix adds any key your `config.json` lacks from the template, so `DisplayManager`'s own fallbacks are never reached on a normal install.
+
+The web UI and the config API refuse values the rgbmatrix library can't start with. If one is written into `config.json` by hand anyway, the display logs which setting it is (`Failed to initialize RGB Matrix` in `sudo journalctl -u ledmatrix`), runs in fallback mode, and the Display tab shows the message.
+
 ### Hardware Configuration (`display.hardware`)
 
 These settings control the physical hardware configuration and how the matrix is driven.
@@ -494,9 +498,7 @@ These settings control the physical hardware configuration and how the matrix is
 - **`rows`** (integer, default: 32)
   - Number of LED rows (vertical pixels) in each panel
   - Common values: 16, 32, 48, 64
-  - Must be an even number, at least 8. LEDMatrix sets no upper limit, but the
+  - An even number from 8 to 64, the most the rgbmatrix library drives per panel
-    current rgbmatrix library rejects more than 64 rows per panel — the display
-    then won't start (see Troubleshooting Display Settings below)
   - Must match your physical panel configuration
 
 - **`cols`** (integer, default: 64)
@@ -507,7 +509,7 @@ These settings control the physical hardware configuration and how the matrix is
 
 - **`chain_length`** (integer, default: 2)
   - Number of LED panels chained together horizontally
-  - At least 1, with no upper limit; longer chains lower the refresh rate
+  - 1 to 255 (the library's Python binding stores it in one byte); longer chains lower the refresh rate
   - If you have 2 panels side-by-side, set to 2
   - If you have 4 panels in a row, set to 4
   - Total display width = `cols × chain_length`
@@ -516,7 +518,7 @@ These settings control the physical hardware configuration and how the matrix is
   - Number of parallel chains (panels stacked vertically)
   - Use 1 for a single row of panels
   - Use 2 if you have panels stacked in two rows
-  - 1–3 on a Raspberry Pi, and the HAT needs that many outputs
+  - 1–3, and no more than your `hardware_mapping` has outputs: `regular` and `classic` have 3 (e.g. the Adafruit Triple LED Matrix Bonnet); `adafruit-hat`, `adafruit-hat-pwm`, `regular-pi1` and `classic-pi1` have 1. The library stops the display service outright on a mismatch, so it is refused
   - Total display height = `rows × parallel`
 
 #### Brightness and Visual Settings
@@ -529,12 +531,14 @@ These settings control the physical hardware configuration and how the matrix is
 
 #### Hardware Mapping
 
-- **`hardware_mapping`** (string, default: "adafruit-hat-pwm")
+- **`hardware_mapping`** (string, default: "adafruit-hat")
   - Specifies which GPIO pin mapping to use for your hardware
   - **`"adafruit-hat-pwm"`**: Use this for Adafruit RGB Matrix Bonnet/HAT WITH the jumper mod (PWM enabled). This is the recommended setting for Adafruit hardware with the PWM jumper soldered.
   - **`"adafruit-hat"`**: Use this for Adafruit RGB Matrix Bonnet/HAT WITHOUT the jumper mod (no PWM). Remove `-pwm` from the value if you did not solder the jumper.
   - **`"regular"`**: Standard GPIO pin mapping for direct GPIO connections (Generic). Also the right choice for the Adafruit Triple LED Matrix Bonnet
   - **`"regular-pi1"`**: Standard GPIO pin mapping for Raspberry Pi 1 (older hardware or non-standard hat mapping)
+  - **`"classic"`** / **`"classic-pi1"`**: the library's original pin-outs, for old adapter boards wired to them. Not used by current HATs
+  - Any other name is refused. `compute-module` is only compiled in when the library is built with `ENABLE_WIDE_GPIO_COMPUTE_MODULE`, which the installer doesn't do. On a Raspberry Pi 5, `classic-pi1` isn't supported
   - Choose the option that matches your specific hardware setup, if aren't sure try them all.
   - Hardware pulsing (see `disable_hardware_pulsing`) needs the panel's OE line on GPIO 18, which `adafruit-hat-pwm` and `regular` provide and `adafruit-hat` does not
 
@@ -571,7 +575,6 @@ These settings affect color fidelity and smoothness of color transitions:
   - Caps the panel refresh rate in Hz; `0` = no cap
   - A steady cap reduces flicker caused by other activity on the Pi, and in camera recordings
   - Scroll speeds are worked out against this value (against 100 Hz when it is `0`), so a cap the panel can actually hold keeps scrolling even
-  - If the key is missing from the config, `DisplayManager` uses 90
   - Recommended: 80-120. `sudo python3 scripts/scroll_speeds.py --measure` reports the rate your panel really achieves
 
 - **`disable_hardware_pulsing`** (boolean, default: false)
@@ -613,8 +616,10 @@ These settings are typically only needed for non-standard panels or custom confi
   - Set to `"180"` (or use the "Upside Down" option in the web UI's Display
     settings) if the panel is mounted upside down — useful for optimizing
     where the Raspberry Pi and wiring sit relative to the mounting location
+  - `"90"` and `"270"` are for a panel mounted on its side; they swap the
+    display's width and height
   - Applied independently of `pixel_mapper_config` (appended as a trailing
-    `Rotate:180` mapper), so custom mapper configs keep working alongside it
+    `Rotate:<degrees>` mapper), so custom mapper configs keep working alongside it
 
 - **`row_address_type`** (integer, default: 0)
   - How rows are addressed on the panel
@@ -663,7 +668,7 @@ These settings control runtime behavior and GPIO timing:
   - **Raspberry Pi Zero/1**: 0-1
   - **Raspberry Pi 2/3**: 1-3
   - **Raspberry Pi 4**: 2-4 (the config template ships 3)
-  - **Raspberry Pi 5**: 1–3 in PIO mode (`rp1_rio: 0`, the default); start with `1` and increase if you see flickering
+  - **Raspberry Pi 5**: 1–3 in PIO mode (`rp1_rio: 0`, the default). Start at `1` (the library treats `0` as `1` there) and raise it a step at a time if the image flickers or shows garbage — chained panels are the likeliest to need it
   - Panels on `row_address_type` 5 (SM5368 row drivers) can need 6-8 on a Pi 4
   - Too low: garbage, flicker or rows jumping. Too high: a lower refresh rate
   - If you experience issues, try adjusting this value up or down by 1
@@ -752,7 +757,7 @@ Controls how long each installed plugin stays visible in seconds before switchin
 - Verify `hardware_mapping` matches your HAT/connection type
 - Try adjusting `gpio_slowdown`
 - Ensure your display doesn't need the E-Addressable line
-- If it went blank right after a settings change, check `sudo journalctl -u ledmatrix` for `Failed to initialize RGB Matrix`: the rgbmatrix library refused a value (for example more than 64 `rows`, or `pwm_dither_bits` above 2) and the display fell back to no output. The library's own message nearby names the setting; on a Raspberry Pi 5, LEDMatrix's message names any unsupported `row_address_type`, `parallel` or `hardware_mapping`
+- If it went blank right after a settings change, the Display tab shows a "simulation mode" banner, and `sudo journalctl -u ledmatrix` shows `Failed to initialize RGB Matrix` followed by the reason. When LEDMatrix refused the settings (for example more than 64 `rows`, `parallel` 2 on an `adafruit-hat` mapping, a misspelled `hardware_mapping`, or on a Raspberry Pi 5 a `row_address_type` other than 0 or 2), the message names each one: change them, save, and restart the display service. Otherwise the library itself failed, and its own message just before names the problem
 - A repeating scramble points at `row_address_type` or `multiplexing`; a panel that stays dark, at `panel_type`
 
 **Rows jump up and down, or the bottom row repeats other rows:**
@@ -834,9 +839,11 @@ sudo ./scripts/install/install_service.sh
 
 The script will:
 - Detect your user account and home directory
-- Install the service file with the correct paths
+- Install `ledmatrix.service` (display, runs as root), `ledmatrix-web.service`
-- Enable the service to start on boot
+  (web interface, runs as your user) and the `ledmatrix-update-verify` units,
-- Start the service immediately
+  with the correct paths
+- Enable them to start on boot
+- Start them immediately
 
 ### Managing the Service
 

dev_plugins.json.example

@@ -0,0 +1,6 @@
+{
+  "dev_plugins_dir": "~/.ledmatrix-dev-plugins",
+  "github_user": "ChuckBuilds",
+  "plugins_repo": "ledmatrix-plugins",
+  "plugins_branch": "main"
+}

docs/ADVANCED_FEATURES.md

@@ -377,9 +377,16 @@ Vegas mode consists of four core components working together to provide smooth 1
 5. Compose into continuous stream with separators
 
 **Key Methods:**
-- `get_stream_content()` - Returns current stream content as PIL Image
+- `get_next_segment()` - Returns the next buffered `ContentSegment` (or `None`)
-- `advance_stream(pixels)` - Advances stream by N pixels
+- `take_next_group(count=None, offscreen_only=False)` - Hands over the next
-- `refresh_stream()` - Regenerates stream from current plugins
+  slice of the rotation as `(plugin_id, images)` groups
+- `get_grouped_content_for_composition()` - Buffered images grouped by plugin
+- `mark_plugin_updated(plugin_id)` / `process_updates()` - Refresh one
+  plugin's segment in place when its data changes
+- `refresh()` - Re-read the plugin list and config
+- `advance_cycle()` - Clear the active buffer when a scroll cycle completes
+
+(`src/vegas_mode/stream_manager.py`)
 
 #### 3. PluginAdapter
 
@@ -433,10 +440,14 @@ Vegas mode consists of four core components working together to provide smooth 1
 - **Frame Rate Control:** Precise timing to maintain 125 FPS
 - **Pre-rendered Content:** Plugins pre-render during update()
 
-**Scroll Speed Calculation:**
+**Scroll Speed Calculation:** motion is by elapsed time; `target_fps` paces
+the render loop, not the speed.
 ```python
-pixels_per_frame = (scroll_speed / target_fps)
+# frame_based_scrolling: false
-scroll_position += pixels_per_frame * elapsed_time
+scroll_position += scroll_speed * elapsed_time            # scroll_speed in px/s
+# frame_based_scrolling: true (the default) -- not stepping, just a clamp
+applied = clamp(scroll_speed * scroll_delay, 0.1, 5) / scroll_delay
+scroll_position += applied * elapsed_time
 ```
 
 #### Component Interactions
@@ -552,7 +563,8 @@ time when something is active.
 
 ### REST API Reference
 
-The API is mounted at `/api/v3` (`web_interface/app.py:199`).
+The API is mounted at `/api/v3` (the `api_v3` blueprint, registered in
+`web_interface/app.py`). Full details: [REST_API_REFERENCE.md](REST_API_REFERENCE.md#display-control).
 
 #### Start On-Demand Display
 
@@ -608,20 +620,30 @@ curl http://localhost:5000/api/v3/display/on-demand/status
 
 # Response:
 {
+  "status": "success",
+  "data": {
+    "state": {
       "active": true,
       "plugin_id": "weather",
       "mode": "weather",
-  "remaining": 25.5,
+      "duration": 30,
       "pinned": false,
-  "status": "active"
+      "status": "running",
+      "last_updated": 1234567890.1
+    },
+    "service": {"active": true, "returncode": 0, "stdout": "active", "stderr": ""}
+  }
 }
 ```
 
+When nothing is running on demand, `data.state` is
+`{"active": false, "status": "idle", "last_updated": null}`.
+
 > There is no public Python on-demand API. The display controller's
 > on-demand machinery is internal — drive it through the REST endpoints
 > above (or the web UI buttons). The API handlers
 > (`start_on_demand_display()` / `stop_on_demand_display()` in
-> `web_interface/blueprints/api_v3.py`) write a request into the cache
+> `web_interface/blueprints/api_v3/display.py`) write a request into the cache
 > manager under the `display_on_demand_request` key, which
 > `DisplayController._poll_on_demand_requests()`
 > (`src/display_controller.py`) picks up. A separate

docs/CONFIG_DEBUGGING.md

@@ -250,14 +250,21 @@ WARNING - Plugin ID 'Football-Scoreboard' may conflict with 'football-scoreboard
 
 ## Checking Configuration via API
 
-The API blueprint mounts at `/api/v3` (`web_interface/app.py:144`).
+The API blueprint (`web_interface/blueprints/api_v3/`) is registered at
+`/api/v3` in `web_interface/app.py`.
 
 ```bash
-# Get full main config (includes all plugin sections)
+# Get full main config (includes all plugin sections; credential-named
+# fields are blanked in the response)
 curl http://localhost:5000/api/v3/config/main
 
-# Save updated main config
+# Change some settings: only the keys you send are changed
 curl -X POST http://localhost:5000/api/v3/config/main \
+  -H "Content-Type: application/json" \
+  -d '{"timezone": "America/Chicago", "brightness": 80}'
+
+# Replace config.json wholesale (advanced)
+curl -X POST http://localhost:5000/api/v3/config/raw/main \
   -H "Content-Type: application/json" \
   -d @new-config.json
 
@@ -269,8 +276,10 @@ curl "http://localhost:5000/api/v3/plugins/config?plugin_id=football-scoreboard"
 ```
 
 > There is no dedicated `/config/plugin/<id>` or `/config/validate`
-> endpoint — config validation runs server-side automatically when you
+> endpoint. `POST /plugins/config` validates against the plugin's schema
-> POST to `/config/main` or `/plugins/config`. See
+> and rejects an invalid config with `400`; `POST /config/main` checks the
+> individual fields it knows (display hardware values, durations, Vegas
+> and sync settings). See
 > [REST_API_REFERENCE.md](REST_API_REFERENCE.md) for the full list.
 
 ## Backup and Recovery

docs/CONFIG_REFERENCE.md

@@ -17,7 +17,7 @@ tooling against it.
 |---|---|---|---|
 | `web_display_autostart` | bool, `true` | Whether the web interface service starts with the system | `scripts/utils/start_web_conditionally.py` |
 | `timezone` | string, `"America/New_York"` | IANA timezone for schedules and displays | `ConfigManager.get_timezone()` |
-| `target_fps` | int, `100` | Frame-rate ceiling for plugin rendering | `src/plugin_system/base_plugin.py`, `src/common/sports_scroll.py` |
+| `target_fps` | int, `100` | Legacy "Scroll Frame Rate". Core scrolling no longer reads it: scroll frames are presented at `display.hardware.limit_refresh_rate_hz` divided by each scroll's frame hold, and speed comes from each plugin's scroll settings. Still exposed to plugins via `BasePlugin.global_config` | `src/plugin_system/base_plugin.py` |
 | `location` | object | `city` / `state` / `country`. Supplies the **default** for a plugin's own `location_city` / `location_state` / `location_country` setting, so weather, radar and friends follow this device without being configured twice. A value saved on the plugin itself still overrides it. | `SchemaManager.apply_device_location()`, then plugins via merged config |
 
 ## `schedule` — display on/off hours
@@ -47,38 +47,43 @@ saved via `POST /api/v3/config/dim-schedule`). The display returns to
 ## `display.hardware` — matrix panel hardware
 
 All keys map to the corresponding `rpi-rgb-led-matrix` options and are read
-in `DisplayManager` (`src/display_manager.py`, ~lines 270–295).
+in `DisplayManager._setup_matrix` (`src/display_manager.py`). Defaults are the
+`config/config.template.json` values: `ConfigManager` adds any key missing from
+`config.json` from the template on load, so `DisplayManager`'s own fallbacks
+don't apply on a normal install.
+
+The ranges are what the pinned rgbmatrix library and its Python binding accept
+(`src/matrix_support.py`). The config API refuses anything else; a value
+hand-edited into `config.json` makes the display log the setting and run in
+fallback mode instead of starting the matrix.
 
 | Key | Type / default |
 |---|---|
-| `rows` / `cols` | int, `32` / `64` — rows: even, at least 8, no upper limit here (the current rgbmatrix library rejects more than 64); cols: at least 16, no upper limit |
+| `rows` / `cols` | int, `32` / `64` — rows: even, 8–64; cols: at least 16 |
-| `chain_length` | int, `2` — at least 1, no upper limit |
+| `chain_length` | int, `2` — 1–255 (the Python binding stores it in one byte) |
-| `parallel` | int, `1` — 1–3 |
+| `parallel` | int, `1` — 1–3, and no more than `hardware_mapping` has outputs (`regular`, `classic`: 3; the others: 1) |
 | `brightness` | int, `90` — 1–100 |
-| `hardware_mapping` | string, `"adafruit-hat"` (code default `"adafruit-hat-pwm"`) |
+| `hardware_mapping` | string, `"adafruit-hat"` — `"adafruit-hat-pwm"`, `"adafruit-hat"`, `"regular"`, `"regular-pi1"`, `"classic"` or `"classic-pi1"` (case-insensitive; `compute-module` isn't in the installed build). A Pi 5 doesn't support `"classic-pi1"` |
 | `scan_mode` | int, `0` — `0` progressive, `1` interlaced |
-| `pwm_bits` | int, `9` (code default 10) — 1–11 |
+| `pwm_bits` | int, `9` — 1–11 |
 | `pwm_dither_bits` | int, `1` — 0–2 |
-| `pwm_lsb_nanoseconds` | int, `130` (code default 150) — 50–3000 |
+| `pwm_lsb_nanoseconds` | int, `130` — 50–3000 |
 | `disable_hardware_pulsing` | bool, `false` — `true` times brightness pulses in software (less exact); hardware pulsing needs the OE line on GPIO 18 and the Pi's onboard sound driver off |
 | `inverse_colors` | bool, `false` |
 | `show_refresh_rate` | bool, `false` — prints the refresh rate to stdout; draws nothing on the panel |
 | `led_rgb_sequence` | string, `"RGB"` — `"RGB"`, `"RBG"`, `"GRB"`, `"GBR"`, `"BRG"` or `"BGR"` |
-| `limit_refresh_rate_hz` | int, `100` (code default 90) — `0` = no cap; scroll timing assumes 100 Hz when `0` |
+| `limit_refresh_rate_hz` | int, `100` — `0` = no cap; scroll timing assumes 100 Hz when `0` |
-| `pixel_mapper_config` | string, `""` — e.g. `"U-mapper"` / `"Rotate:90"` |
+| `pixel_mapper_config` | string, `""` — e.g. `"U-mapper"` / `"Rotate:90"`; mappers that rotate or fold the chain change the display size plugins and the web preview see |
-| `orientation` | string, `"normal"` — `"180"` rotates the rendered image 180° for panels physically mounted upside down (e.g. to move the Pi/wiring to a more convenient side); composed onto `pixel_mapper_config` as a trailing `Rotate:180` mapper, so it stays independent of any custom `pixel_mapper_config` value |
+| `orientation` | string, `"normal"` — `"180"` rotates the rendered image 180° for panels physically mounted upside down (e.g. to move the Pi/wiring to a more convenient side); `"90"` / `"270"` for a panel on its side, swapping width and height; composed onto `pixel_mapper_config` as a trailing `Rotate:<degrees>` mapper, so it stays independent of any custom `pixel_mapper_config` value |
 | `row_address_type` | int, `0` — non-standard panel row addressing: `1` AB, `2` direct row select, `3` ABC, `4` ABC shift + DE direct, `5` SM5368 / B707 row shift register (e.g. Waveshare 96x48 V2, with `led_rgb_sequence` `"BGR"`). On a Pi 5 the library supports only `0` and `2`, and LEDMatrix enforces that (`src/pi5_matrix_support.py`) |
 | `multiplexing` | int, `0` — 0–22, pixel wiring scheme for outdoor/specialty panels (names listed in the README) |
 | `panel_type` | string, `""` — set to `"FM6126A"` or `"FM6127"` for panels needing init; FM6124 / FM6124D / FM6124DJ panels need none, so leave it `""` |
 
-Where "code default" differs from the template value, the code default only
-applies if the key is missing entirely from your config.
-
 ## `display.runtime`
 
 | Key | Type / default | Meaning |
 |---|---|---|
-| `gpio_slowdown` | int, `3` | GPIO timing slowdown for faster Pis (0–10). Panels on `row_address_type` `5` (SM5368 row drivers) can need 6–8 on a Pi 4 — lower values make rows jump |
+| `gpio_slowdown` | int, `3` | GPIO timing slowdown for faster Pis (0–10). On a Pi 5 in PIO mode start at `1` (`0` acts as `1`) and raise it if the image flickers or shows garbage. Panels on `row_address_type` `5` (SM5368 row drivers) can need 6–8 on a Pi 4 — lower values make rows jump |
 | `rp1_rio` | int, `0` | Pi 5 only: `0` = PIO (less CPU), `1` = RIO (higher refresh; `gpio_slowdown` effect inverted). Applied only if the installed matrix library supports it |
 
 ## `display.double_sided`
@@ -134,8 +139,8 @@ Read by `src/vegas_mode/config.py` (`VegasScrollConfig.from_config`). See
 | `dynamic_duration_enabled` | bool, `true` |
 | `min_cycle_duration` | int, `60` |
 | `max_cycle_duration` | int, `240` |
-| `frame_based_scrolling` | bool, `true` — frame-count-based scroll stepping |
+| `frame_based_scrolling` | bool, `true` — does not step or set a frame rate; motion is by elapsed time either way. When `true`, `scroll_speed` passes through a clamp of 0.1–5 px per `scroll_delay` (see next row) |
-| `scroll_delay` | float, `0.02` — seconds between scroll updates (~50 FPS) |
+| `scroll_delay` | float, `0.02` — not a frame period. Only used with `frame_based_scrolling`: the applied speed is `clamp(scroll_speed × scroll_delay, 0.1, 5) / scroll_delay` px/s, so at `0.02` speeds under 5 px/s run at 5, and at `0.001` nothing runs slower than 100 px/s |
 | `live_in_ticker` | bool, `false` — keep scrolling during live games instead of handing the display to a full-screen scoreboard |
 | `live_weight` | int, `3` (1–10) — slots per cycle for a plugin with live content |
 | `favorite_live_weight` | int, `5` (1–10) — slots per cycle when a plugin reports a favorite team is live |
@@ -152,14 +157,12 @@ Read by `src/common/sync_manager.py` and `src/display_controller.py`.
 
 ## `plugin_system`
 
-Read by the plugin loader/manager (`src/plugin_system/`).
-
 | Key | Type / default | Meaning |
 |---|---|---|
-| `plugins_directory` | string, `"plugin-repos"` | Where the Plugin Store installs plugins |
+| `plugins_directory` | string, `"plugin-repos"` | Where the Plugin Store installs plugins and the only directory the plugin loader scans. Read by `PluginManager` and `PluginStoreManager` (`src/plugin_system/`); editable under General settings |
-| `auto_discover` | bool, `true` | Scan the plugins directory at startup |
+| `auto_discover` | bool, `true` | **Unused.** Legacy key, read by nothing. Plugins are always discovered, and every plugin with `enabled: true` is loaded. Not shown in the web UI; may be left in or removed from config.json |
-| `auto_load_enabled` | bool, `true` | Load discovered plugins automatically |
+| `auto_load_enabled` | bool, `true` | **Unused.** Legacy key, read by nothing (see `auto_discover`). To keep a plugin installed but dormant, set its own `enabled` to `false` |
-| `development_mode` | bool, `false` | Development conveniences in the web UI (editable under General settings) |
+| `development_mode` | bool, `false` | **Unused.** Legacy key, read by nothing |
 
 ## Plugin config blocks
 

docs/FONT_MANAGER.md

@@ -12,10 +12,28 @@
 The enhanced FontManager provides comprehensive font management for the LEDMatrix application with support for:
 - Manager font registration and detection
 - Plugin font management
-- Manual font overrides via web interface
+- Programmatic per-element font overrides
 - Performance monitoring and caching
 - Dynamic font discovery
 
+## Getting the FontManager
+
+There is one shared FontManager per display process. The display controller
+creates it and hands it to the `PluginManager`, so a plugin reaches it
+through its `plugin_manager`:
+
+```python
+class MyPlugin(BasePlugin):
+    def __init__(self, plugin_id, config, display_manager, cache_manager, plugin_manager):
+        super().__init__(plugin_id, config, display_manager, cache_manager, plugin_manager)
+        self.font_manager = self._get_font_manager()
+```
+
+`BasePlugin._get_font_manager()` returns `plugin_manager.font_manager`, or a
+standalone FontManager when none is available (test harnesses, mocks).
+`DisplayManager` has **no** `font_manager` attribute —
+`display_manager.font_manager` raises `AttributeError`.
+
 ## Architecture
 
 ### Manager-Centric Design
@@ -40,8 +58,9 @@ Manager requests font → Check manual overrides → Apply manager choice → Ca
 from src.font_manager import FontManager
 
 class MyManager:
-    def __init__(self, config, display_manager, cache_manager):
+    def __init__(self, config, display_manager, cache_manager, plugin_manager):
-        self.font_manager = display_manager.font_manager  # Access shared FontManager
+        self.display_manager = display_manager
+        self.font_manager = plugin_manager.font_manager  # Shared FontManager
         self.manager_id = "my_manager"
         
     def display(self):
@@ -80,8 +99,9 @@ class MyManager:
 
 ```python
 class AdvancedManager:
-    def __init__(self, config, display_manager, cache_manager):
+    def __init__(self, config, display_manager, cache_manager, plugin_manager):
-        self.font_manager = display_manager.font_manager
+        self.display_manager = display_manager
+        self.font_manager = plugin_manager.font_manager
         self.manager_id = "advanced_manager"
         
         # Define your font specifications
@@ -152,19 +172,13 @@ font = self.font_manager.resolve_font(
 > URIs documented below are resolved relative to the plugin's
 > install directory.
 >
-> The **Fonts** tab in the web UI that lists detected
+> The web UI's **Fonts** tab lists, uploads, previews and deletes the
-> manager-registered fonts is still a **placeholder
+> font files in `assets/fonts/`. It does not show fonts registered
-> implementation** — fonts that managers register through
+> through `register_manager_font()` and has no override editor (the
-> `register_manager_font()` do not yet appear there. The
+> override panels and `/api/v3/fonts/overrides` endpoints were removed).
-> programmatic per-element override workflow described in
+> The programmatic override workflow in
-> [Manual Font Overrides](#manual-font-overrides) below
+> [Manual Font Overrides](#manual-font-overrides) below still works.
-> (`set_override()` / `remove_override()` / the
+> Let users pick fonts through your plugin's own config schema.
-> `config/font_overrides.json` store) **does** work today and is
-> the supported way to override a font for an element until the
-> Fonts tab is wired up. If you can't wait and need a workaround
-> right now, you can also just load the font directly with PIL
-> (or `freetype-py` for BDF) inside your plugin's `manager.py`
-> and skip the override system entirely.
 
 ### Plugin Font Registration
 
@@ -200,10 +214,10 @@ In your plugin's `manifest.json`:
 ### Using Plugin Fonts
 
 ```python
-class PluginManager:
+class MyPlugin(BasePlugin):
-    def __init__(self, config, display_manager, cache_manager, plugin_id):
+    def __init__(self, plugin_id, config, display_manager, cache_manager, plugin_manager):
-        self.font_manager = display_manager.font_manager
+        super().__init__(plugin_id, config, display_manager, cache_manager, plugin_manager)
-        self.plugin_id = plugin_id
+        self.font_manager = self._get_font_manager()
         
     def display(self):
         # Use plugin font (automatically namespaced)
@@ -219,17 +233,8 @@ class PluginManager:
 
 ## Manual Font Overrides
 
-Users can override any font through the web interface:
+Overrides are set in code (there is no web UI or REST endpoint for them).
-
+They are stored in `config/font_overrides.json` and persist across restarts.
-1. Navigate to **Fonts** tab
-2. View **Detected Manager Fonts** to see what's currently in use
-3. In **Element Overrides** section:
-   - Select the element (e.g., "nfl.live.score")
-   - Choose a different font family
-   - Choose a different size
-   - Click **Add Override**
-
-Overrides are stored in `config/font_overrides.json` and persist across restarts.
 
 ### Programmatic Overrides
 

docs/MIGRATION_GUIDE.md

@@ -59,9 +59,12 @@ sudo ./scripts/install/install_service.sh
 After updating your scripts, verify they still work:
 
 ```bash
-# Test installation scripts (if needed)
+# Check the installation scripts are at their new paths
 ls scripts/install/*.sh
-sudo ./scripts/install/install_service.sh --help
+./scripts/install/install_service.sh --help   # prints usage only
+# Note: running install_service.sh for real (with sudo, no --help)
+# reinstalls, enables and restarts ledmatrix.service, ledmatrix-web.service
+# and the update-verify units.
 
 # Test permission scripts
 ls scripts/fix_perms/*.sh

docs/MULTI_ROOT_WORKSPACE_SETUP.md

@@ -1,169 +1,154 @@
 # Multi-Root Workspace Setup Guide
 
-This document explains how the LEDMatrix project uses a multi-root workspace to manage plugins as separate Git repositories.
+This document explains how to work on LEDMatrix and the official plugins side
+by side, with one editor workspace and the plugins loaded straight from your
+plugin checkout.
 
 ## Overview
 
-The LEDMatrix project has been migrated from a git submodule implementation to a **multi-root workspace** implementation for managing plugins. This allows:
+Official plugins live in a single repository,
+[ledmatrix-plugins](https://github.com/ChuckBuilds/ledmatrix-plugins), with one
+directory per plugin under `plugins/`. There are no separate per-plugin
+repositories. For development you clone that monorepo **next to** LEDMatrix
+and symlink its plugin directories into LEDMatrix's `plugin-repos/`, which is
+where the plugin loader looks by default.
 
-- ✅ Plugins to exist as independent Git repositories
+- ✅ Plugin code stays in the monorepo checkout, with its own git history
-- ✅ Updates to plugins without modifying the LEDMatrix project
+- ✅ LEDMatrix discovers the plugins through symlinks in `plugin-repos/`
-- ✅ Easy development workflow with all repos in one workspace
+- ✅ `LEDMatrix.code-workspace` opens both repositories in VS Code/Cursor
-- ✅ Plugin system discovers plugins via symlinks in `plugin-repos/`
 
 ## Directory Structure
 
 ```text
-/home/chuck/Github/
+~/Github/
 ├── LEDMatrix/                        # Main project
-│   ├── plugin-repos/             # Symlinks to actual repos (managed automatically)
+│   ├── plugin-repos/                 # Plugin directory the loader scans
-│   │   ├── ledmatrix-clock-simple -> ../../ledmatrix-clock-simple
+│   │   ├── starlark-apps/            # Bundled with LEDMatrix (tracked in git)
-│   │   ├── ledmatrix-weather -> ../../ledmatrix-weather
+│   │   ├── web-ui-info/              # Bundled with LEDMatrix (tracked in git)
+│   │   ├── clock-simple -> ../../ledmatrix-plugins/plugins/clock-simple
+│   │   ├── ledmatrix-weather -> ../../ledmatrix-plugins/plugins/ledmatrix-weather
 │   │   └── ...
-│   ├── LEDMatrix.code-workspace  # Multi-root workspace configuration
+│   ├── LEDMatrix.code-workspace      # Opens LEDMatrix and ../ledmatrix-plugins
 │   └── ...
-├── ledmatrix-clock-simple/       # Plugin repository (actual git repo)
+└── ledmatrix-plugins/                # Plugin monorepo (git repo)
-├── ledmatrix-weather/            # Plugin repository (actual git repo)
+    ├── plugins/
-├── ledmatrix-football-scoreboard/ # Plugin repository (actual git repo)
+    │   ├── clock-simple/
-└── ...                           # Other plugin repos
+    │   ├── ledmatrix-weather/
+    │   └── ...
+    ├── plugins.json                  # Store registry
+    └── update_registry.py
 ```
 
 ## How It Works
 
-### 1. Plugin Repositories
+### 1. The plugin monorepo
 
-All plugin repositories are cloned to `/home/chuck/Github/` (parent directory of LEDMatrix) as regular Git repositories:
+Clone ledmatrix-plugins into the same parent directory as LEDMatrix (the
+scripts below look for `../ledmatrix-plugins` relative to the LEDMatrix
+root):
 
-- `ledmatrix-clock-simple/`
+```bash
-- `ledmatrix-weather/`
+cd ~/Github
-- `ledmatrix-football-scoreboard/`
+git clone https://github.com/ChuckBuilds/ledmatrix-plugins.git
-- etc.
+```
 
 ### 2. Symlinks in plugin-repos/
 
-The `LEDMatrix/plugin-repos/` directory contains symlinks pointing to the actual repositories in the parent directory. This allows the plugin system to discover plugins without modifying the project structure.
+`scripts/setup_plugin_repos.py` creates one symlink per plugin in
+`LEDMatrix/plugin-repos/`, named after the plugin's manifest `id` and pointing
+at `../ledmatrix-plugins/plugins/<dir>`.
 
-### 3. Multi-Root Workspace
+### 3. Multi-root workspace
 
-The `LEDMatrix.code-workspace` file configures VS Code/Cursor to open all plugin repositories as separate workspace roots, allowing easy development across all repos.
+`LEDMatrix.code-workspace` has two roots: LEDMatrix itself and
+`../ledmatrix-plugins`.
 
 ## Setup Scripts
 
 ### Initial Setup
 
-If you already have plugin repositories cloned, use the setup script:
-
 ```bash
-cd /home/chuck/Github/LEDMatrix
+cd ~/Github/LEDMatrix
 python3 scripts/setup_plugin_repos.py
 ```
 
 This script:
-- Reads the workspace configuration
+- Reads each `manifest.json` under `../ledmatrix-plugins/plugins/`
-- Creates symlinks in `plugin-repos/` pointing to actual repos
+- Creates `plugin-repos/<id>` symlinks (relative) to those directories
-- Verifies all links are created correctly
+- Leaves correct links alone, replaces links that point elsewhere, and skips
+  (does not overwrite) a real directory of the same name — for example a
+  plugin you installed from the Plugin Store. Remove that directory first if
+  you want the linked copy.
 
 ### Updating Plugins
 
-To update all plugin repositories:
-
 ```bash
-cd /home/chuck/Github/LEDMatrix
+cd ~/Github/LEDMatrix
 python3 scripts/update_plugin_repos.py
 ```
 
-This script:
+This runs `git pull` in `../ledmatrix-plugins` and prints the result. The
-- Finds all plugins in the workspace
+symlinks pick up the new code; restart the display to load it.
-- Runs `git pull` on each repository
-- Reports which plugins were updated
 
 ## Configuration
 
-The plugin system is configured in `config/config.json`:
+The loader reads plugins from `plugin_system.plugins_directory` in
+`config/config.json`. The default is already right for this setup:
 
 ```json
 {
   "plugin_system": {
-    "plugins_directory": "plugin-repos",
+    "plugins_directory": "plugin-repos"
-    "auto_discover": true,
-    "auto_load_enabled": true
   }
 }
 ```
 
-The `plugins_directory` points to `plugin-repos/`, which contains symlinks to the actual repositories.
-
 ## Workflow
 
 ### Daily Development
 
 1. **Open Workspace**: Open `LEDMatrix.code-workspace` in VS Code/Cursor
-2. **All Repos Available**: All plugin repos appear as separate folders in the workspace
+2. **Edit Plugins**: Edit code under `ledmatrix-plugins/plugins/<plugin>/`
-3. **Edit Plugins**: Edit plugin code directly in their repositories
+3. **Test**: `python3 run.py -e` (emulator) or
-4. **Update Plugins**: Run `update_plugin_repos.py` to pull latest changes
+   `python3 scripts/check_plugin.py --plugin <id>` from LEDMatrix
+4. **Ship**: Bump `version` in the plugin's `manifest.json`, run
+   `python update_registry.py` in ledmatrix-plugins, commit there
 
 ### Adding New Plugins
 
-1. **Clone Repository**: Clone the new plugin repo to `/home/chuck/Github/`
+1. Create `plugins/<your-plugin-id>/` in the monorepo checkout
-2. **Add to Workspace**: Add the plugin folder to `LEDMatrix.code-workspace`
+2. Run `python3 scripts/setup_plugin_repos.py` in LEDMatrix to link it
-3. **Create Symlink**: Run `setup_plugin_repos.py` to create the symlink
-
-### Updating Individual Plugins
-
-Since plugins are regular Git repositories, you can update them individually:
-
-```bash
-cd /home/chuck/Github/ledmatrix-weather
-git pull origin master
-```
-
-Or update all at once:
-
-```bash
-cd /home/chuck/Github/LEDMatrix
-python3 scripts/update_plugin_repos.py
-```
-
-## Benefits
-
-1. **No Submodule Hassle**: No need to update `.gitmodules` or run `git submodule update`
-2. **Independent Updates**: Update plugins independently without touching LEDMatrix
-3. **Clean Separation**: Each plugin is a separate repository with its own history
-4. **Easy Development**: Multi-root workspace makes it easy to work across repos
-5. **Automatic Discovery**: Plugin system automatically discovers plugins via symlinks
 
 ## Troubleshooting
 
-### Symlinks Not Working
+### Plugins not discovered
-
-If plugins aren't being discovered:
 
 ```bash
-cd /home/chuck/Github/LEDMatrix
+cd ~/Github/LEDMatrix
-python3 scripts/setup_plugin_repos.py
+ls -la plugin-repos/                  # links present and not broken?
+python3 scripts/setup_plugin_repos.py # recreate them
 ```
 
-This will recreate all symlinks.
+Also check that `plugin_system.plugins_directory` is `plugin-repos`.
 
-### Missing Plugins
+### "Monorepo plugins directory not found"
 
-If a plugin is in the workspace but not found:
+`setup_plugin_repos.py` expects the monorepo at `../ledmatrix-plugins`. Clone
+it there (or symlink it there).
 
-1. Check if the repo exists in `/home/chuck/Github/`
+### Plugin updates not showing
-2. Check if the symlink exists in `plugin-repos/`
-3. Run `setup_plugin_repos.py` to recreate symlinks
 
-### Plugin Updates Not Showing
+1. Verify the link target: `ls -la plugin-repos/<id>`
-
+2. Check that you're editing the monorepo checkout, not a store-installed copy
-If changes to plugins aren't appearing:
+3. Restart the LEDMatrix service (or `run.py`)
-
-1. Verify the symlink points to the correct directory: `ls -la plugin-repos/ledmatrix-weather`
-2. Check that you're editing in the actual repo, not a copy
-3. Restart the LEDMatrix service if running
 
 ## Notes
 
-- The `plugin-repos/` directory is tracked in git, but only contains symlinks
+- `plugin-repos/` is tracked in git only for the bundled plugins
-- Actual plugin code lives in `/home/chuck/Github/ledmatrix-*/`
+  (`starlark-apps`, `web-ui-info`). The symlinks you create are untracked
-- Each plugin repo can be updated independently via `git pull`
+  files; don't commit them.
-- The LEDMatrix project doesn't need to be updated when plugins change
+- For linking a single plugin into `plugins/` instead (without a sibling
+  checkout), see `scripts/dev/dev_plugin_setup.sh` in the
+  [Plugin Development Guide](PLUGIN_DEVELOPMENT_GUIDE.md).
+- When changing a plugin in the monorepo, bump its manifest `version` and run
+  `python update_registry.py`, or users won't receive the update.

docs/PLUGIN_API_REFERENCE.md

@@ -514,21 +514,59 @@ self.display_manager.draw_text_with_icons(
 
 For plugins that implement scrolling content, use these methods to coordinate with the display system.
 
-#### `set_scrolling_state(is_scrolling: bool) -> None`
+#### `set_scrolling_state(is_scrolling: bool, frame_hold: int = 1) -> None`
 
-Mark the display as scrolling or not scrolling. Call when scrolling starts/stops.
+Mark the display as scrolling or not scrolling, and set this scroll's frame
+pacing. Call it when a scroll starts (calling it on every scroll frame is fine)
+and with `False` when it stops.
 
 **Parameters**:
 - `is_scrolling` (bool): True if currently scrolling, False otherwise
+- `frame_hold` (int, default 1): how many panel refreshes each pushed frame is
+  held for (clamped to 1-255; ignored when `is_scrolling` is False, which
+  resets it to 1). Pass the `frame_hold` of the settings
+  `src.common.scroll_config.configure()` returned. Added in core 3.4.0.
+
+**Why `frame_hold` matters**: `scroll_config.configure()` snaps the speed to
+one the panel can show in whole pixels and sets the `ScrollHelper` to advance a
+fixed number of pixels on every presented frame -- no clock is consulted. The
+panel presents frames at its refresh rate divided by the hold, so the hold is
+part of the speed. Omit it and a 50 px/s scroll (1px every 2nd refresh on a
+100 Hz panel) runs at 100 px/s. The hold is not applied by `configure()`
+because it must not outlive the scroll: plugins share one display manager.
 
 **Example**:
 ```python
+from src.common import scroll_config
+from src.common.scroll_helper import ScrollHelper
+
+def __init__(self, *args, **kwargs):
+    super().__init__(*args, **kwargs)
+    self.scroll_helper = ScrollHelper(
+        self.display_manager.width, self.display_manager.height, self.logger)
+    # ...later, hand it content with self.scroll_helper.set_scrolling_image(img)
+    self.scroll_settings = scroll_config.configure(
+        self.scroll_helper,
+        plugin_config=self.config,
+        global_config=self.global_config,
+        display_manager=self.display_manager,
+        plugin_logger=self.logger,
+    )
+
 def display(self, force_clear=False):
-    self.display_manager.set_scrolling_state(True)
+    self.display_manager.set_scrolling_state(
-    # Scroll content...
+        True, frame_hold=self.scroll_settings.frame_hold)
+    self.scroll_helper.update_scroll_position()
+    self.display_manager.image = self.scroll_helper.get_visible_portion()
+    self.display_manager.update_display()
+    if self.scroll_helper.is_scroll_complete():
         self.display_manager.set_scrolling_state(False)
 ```
 
+Don't pace the loop with `time.sleep()`: `update_display()` blocks on the
+panel's vsync, which is what paces a scroll. See `docs/SCROLL_PERFORMANCE.md`
+for choosing a speed.
+
 #### `is_currently_scrolling() -> bool`
 
 Check if the display is currently in a scrolling state.
@@ -998,9 +1036,10 @@ if "weather" in enabled_plugins:
        self.display_manager.update_display()
    ```
 
-3. **Handle scrolling state**: If your plugin scrolls, use scrolling state methods
+3. **Handle scrolling state**: If your plugin scrolls, use scrolling state methods,
+   passing the frame hold `scroll_config.configure()` returned
    ```python
-   self.display_manager.set_scrolling_state(True)
+   self.display_manager.set_scrolling_state(True, frame_hold=settings.frame_hold)
    # Scroll content...
    self.display_manager.set_scrolling_state(False)
    ```

docs/PLUGIN_ARCHITECTURE_SPEC.md

@@ -8,7 +8,8 @@
 > - Code paths reference `web_interface_v2.py`; the current web UI is
 >   `web_interface/app.py` with v3 Blueprint-based templates.
 > - The example Flask routes use `/api/plugins/*`; the real API
->   blueprint is mounted at `/api/v3` (`web_interface/app.py:199`).
+>   blueprint (`web_interface/blueprints/api_v3/`) is mounted at `/api/v3`
+>   in `web_interface/app.py`.
 > - The default plugin location is `plugin-repos/` (configurable via
 >   `plugin_system.plugins_directory`), not `./plugins/`.
 > - Example imports use `src/plugin_system/base_classes/*_plugin.py`;

docs/PLUGIN_CONFIGURATION_GUIDE.md

@@ -67,9 +67,7 @@ The main configuration file (`config/config.json`) now contains only essential s
         "time_format": "%I:%M %p"
     },
     "plugin_system": {
-        "plugins_directory": "plugin-repos",
+        "plugins_directory": "plugin-repos"
-        "auto_discover": true,
-        "auto_load_enabled": true
     }
 }
 ```
@@ -93,9 +91,9 @@ The main configuration file (`config/config.json`) now contains only essential s
 
 #### 4. Plugin System
 - **plugin_system**: Plugin system configuration
-  - **plugins_directory**: Directory where plugins are stored
+  - **plugins_directory**: Directory where plugins are stored (the only one the loader scans)
-  - **auto_discover**: Automatically discover plugins
+  - `auto_discover`, `auto_load_enabled`, `development_mode` may still appear in
-  - **auto_load_enabled**: Automatically load enabled plugins
+    older configs; nothing reads them (see [CONFIG_REFERENCE.md](CONFIG_REFERENCE.md#plugin_system))
 
 ## Plugin Configuration
 

docs/PLUGIN_CONFIGURATION_TABS.md

@@ -6,7 +6,8 @@
 > in the "Implementation Details" section below still reference the
 > pre-v3 file layout (`web_interface_v2.py`, `templates/index_v2.html`).
 > The current implementation lives in `web_interface/app.py`,
-> `web_interface/blueprints/api_v3.py`, and `web_interface/templates/v3/`.
+> `web_interface/blueprints/api_v3/` (plugin config handlers in
+> `plugins.py`), and `web_interface/templates/v3/`.
 > The user-facing description (Overview, Features, Form Generation
 > Process) is still accurate.
 

docs/PLUGIN_CONFIG_ARCHITECTURE.md

@@ -11,427 +11,179 @@
 ### Component Overview
 
 ```
-┌─────────────────────────────────────────────────────────────────┐
+┌──────────────────────────────────────────────────────────────────┐
-│                         Web Browser                              │
+│ Web browser (templates/v3/base.html, Alpine.js + HTMX)            │
-│  ┌─────────────────────────────────────────────────────────┐   │
-│  │                    Tab Navigation Bar                     │   │
-│  │  [Overview] [General] ... [Plugins] [Plugin X] [Plugin Y]│   │
-│  └─────────────────────────────────────────────────────────┘   │
 │                                                                    │
-│  ┌─────────────────┐  ┌──────────────────────────────────┐     │
+│  Second nav row: one tab per installed plugin                      │
-│  │  Plugins Tab    │  │   Plugin X Configuration Tab     │     │
+│  Clicking a tab: GET /v3/partials/plugin-config/<plugin_id>        │
-│  │                 │  │                                    │     │
+│  → server-rendered form swapped into the tab                       │
-│  │ • Install       │  │  Form Generated from Schema:      │     │
+│                                                                    │
-│  │ • Update        │  │  • Boolean → Toggle               │     │
+│  Save: hx-post="/api/v3/plugins/config?plugin_id=<id>" (form data) │
-│  │ • Uninstall     │  │  • Number → Number Input          │     │
+└──────────────────────────────────────────────────────────────────┘
-│  │ • Enable        │  │  • String → Text Input            │     │
-│  │ • [Configure]──────→  • Array → Comma Input           │     │
-│  │                 │  │  • Enum → Dropdown                │     │
-│  └─────────────────┘  │                                    │     │
-│                        │  [Save] [Back] [Reset]            │     │
-│                        └──────────────────────────────────┘     │
-└─────────────────────────────────────────────────────────────────┘
                                 │
-                                │ HTTP API
                                 ▼
-┌─────────────────────────────────────────────────────────────────┐
+┌──────────────────────────────────────────────────────────────────┐
-│                      Flask Backend                               │
+│ Flask (web_interface/app.py)                                       │
-│  ┌───────────────────────────────────────────────────────┐     │
-│  │         /api/v3/plugins/installed                         │     │
-│  │  • Discover plugins in plugins/ directory              │     │
-│  │  • Load manifest.json for each plugin                  │     │
-│  │  • Load config_schema.json if exists                   │     │
-│  │  • Load current config from config.json                │     │
-│  │  • Return combined data to frontend                    │     │
-│  └───────────────────────────────────────────────────────┘     │
 │                                                                    │
-│  ┌───────────────────────────────────────────────────────┐     │
+│  pages_v3 blueprint (blueprints/pages_v3.py)                       │
-│  │         /api/v3/plugins/config                            │     │
+│   _load_plugin_config_partial(plugin_id)                           │
-│  │  • Receive key-value pair                              │     │
+│    • SchemaManager.load_schema() → config_schema.json              │
-│  │  • Update config.json                                  │     │
+│    • config.json section for the plugin                            │
-│  │  • Return success/error                                │     │
+│    • masks x-secret fields                                         │
-│  └───────────────────────────────────────────────────────┘     │
+│    • renders partials/plugin_config.html (render_field macros)     │
-└─────────────────────────────────────────────────────────────────┘
+│                                                                    │
+│  api_v3 blueprint (blueprints/api_v3/plugins.py)                   │
+│   save_plugin_config()   POST /api/v3/plugins/config               │
+│   get_plugin_config()    GET  /api/v3/plugins/config               │
+│   get_plugin_schema()    GET  /api/v3/plugins/schema               │
+│   reset_plugin_config()  POST /api/v3/plugins/config/reset         │
+└──────────────────────────────────────────────────────────────────┘
                                 │
-                                │ File System
                                 ▼
-┌─────────────────────────────────────────────────────────────────┐
+┌──────────────────────────────────────────────────────────────────┐
-│                      File System                                 │
+│ Files                                                              │
-│                                                                   │
+│  plugin-repos/<id>/config_schema.json   JSON Schema (Draft-7)      │
-│  plugins/                                                         │
+│  config/config.json                     { "<id>": { ... } }        │
-│  ├── hello-world/                                                │
+│  config/config_secrets.json             { "<id>": { secrets } }    │
-│  │   ├── manifest.json ───┐                                     │
+└──────────────────────────────────────────────────────────────────┘
-│  │   ├── config_schema.json ─┼─→ Defines UI structure           │
-│  │   ├── manager.py          │                                   │
-│  │   └── requirements.txt    │                                   │
-│  └── clock-simple/            │                                   │
-│      ├── manifest.json        │                                   │
-│      └── config_schema.json ──┘                                  │
-│                                                                   │
-│  config/                                                          │
-│  └── config.json ────────────→ Stores configuration values       │
-│      {                                                            │
-│        "hello-world": {                                           │
-│          "enabled": true,                                         │
-│          "message": "Hello!",                                     │
-│          ...                                                      │
-│        }                                                          │
-│      }                                                            │
-└─────────────────────────────────────────────────────────────────┘
 ```
 
+The plugins directory is `plugin_system.plugins_directory` in
+`config/config.json` (default `plugin-repos/`). Plugin configuration lives in
+`config/config.json`, not in the plugin directory, so it survives reinstalls.
+
 ## Data Flow
 
-### 1. Page Load Sequence
+### 1. Rendering a plugin's tab
 
 ```
-User Opens Web Interface
+User opens the plugin's tab
         │
         ▼
-DOMContentLoaded Event
+GET /v3/partials/plugin-config/<plugin_id>        (pages_v3)
         │
-         ▼
+        ├─→ Load schema (SchemaManager, no cache)
-refreshPlugins()
+        ├─→ Load config.json[<plugin_id>]
+        ├─→ Mask "x-secret" values (fails closed if the schema is unusable)
+        └─→ render partials/plugin_config.html
                 │
-         ▼
+                └─→ render_field() per property, recursively:
-GET /api/v3/plugins/installed
+                      boolean → toggle, number/integer → input or slider,
-         │
+                      string → input / textarea / select (enum),
-         ├─→ For each plugin directory:
+                      array → list or table widget,
-         │   ├─→ Read manifest.json
+                      object → collapsible nested section,
-         │   ├─→ Read config_schema.json (if exists)
+                      "x-widget" → a registered widget
-         │   └─→ Read config from config.json
+                               (static/v3/js/widgets/, or one the plugin ships)
-         │
-         ▼
-Return JSON Array:
-[{
-  id: "hello-world",
-  name: "Hello World",
-  config: { enabled: true, message: "Hello!" },
-  config_schema_data: {
-    properties: {
-      enabled: { type: "boolean", ... },
-      message: { type: "string", ... }
-    }
-  }
-}, ...]
-         │
-         ▼
-generatePluginTabs(plugins)
-         │
-         ├─→ For each plugin:
-         │   ├─→ Create tab button
-         │   ├─→ Create tab content div
-         │   └─→ generatePluginConfigForm(plugin)
-         │           │
-         │           ├─→ Read schema properties
-         │           ├─→ Get current config values
-         │           └─→ Generate HTML form inputs
-         │
-         ▼
-Tabs Rendered in UI
 ```
 
-### 2. Configuration Save Sequence
+Nested objects are supported: a nested field is posted with a dotted name
+(e.g. `transition.type`).
+
+### 2. Saving
 
 ```
-User Modifies Form
+User clicks Save
         │
         ▼
-User Clicks "Save"
+validatePluginConfigForm() (client-side checks)
         │
         ▼
-savePluginConfiguration(pluginId)
+POST /api/v3/plugins/config?plugin_id=<id>   (form data, all fields of the form)
-         │
-         ├─→ Get form data
-         ├─→ For each field:
-         │   ├─→ Get schema type
-         │   ├─→ Convert value to correct type
-         │   │   • boolean: checkbox.checked
-         │   │   • integer: parseInt()
-         │   │   • number: parseFloat()
-         │   │   • array: split(',')
-         │   │   • string: as-is
-         │   │
-         │   └─→ POST /api/v3/plugins/config
-         │       {
-         │         plugin_id: "hello-world",
-         │         key: "message",
-         │         value: "Hello, World!"
-         │       }
         │
         ▼
-Backend Updates config.json
+save_plugin_config()                          (api_v3/plugins.py)
+        ├─→ Start from the stored config.json[<id>]
+        ├─→ Apply form fields: dotted names → nested keys, "[]" checkbox
+        │   groups → lists, values coerced to the schema's types
+        ├─→ Merge schema defaults for keys that are still missing
+        ├─→ Validate against the schema (plus core per-plugin properties);
+        │   invalid → 400 with the validation errors, nothing saved
+        ├─→ Split "x-secret" fields out; masked/blank secrets are dropped so
+        │   an untouched secret keeps its stored value
+        ├─→ Deep-merge regular fields into config.json[<id>] (atomic save)
+        ├─→ Merge secrets into config_secrets.json[<id>]
+        └─→ Call the loaded plugin's on_config_change() (and
+            on_enable/on_disable if "enabled" changed)
         │
         ▼
-Return Success
+One response for the whole form → notification in the UI
-         │
-         ▼
-Show Notification
-         │
-         ▼
-Refresh Plugins
 ```
 
-## Class and Function Hierarchy
+The display service picks up the new config through its config hot reload
+(ConfigService) without a restart.
 
-### Frontend (JavaScript)
+JSON clients can post `{"plugin_id": ..., "config": {...}}` instead; the keys
+sent are merged onto the stored config the same way. See
+[REST_API_REFERENCE.md](REST_API_REFERENCE.md#save-plugin-configuration).
 
-```
+### 3. Reset
-Window Load
-  └── DOMContentLoaded
-      └── refreshPlugins()
-          ├── fetch('/api/v3/plugins/installed')
-          ├── renderInstalledPlugins(plugins)
-          └── generatePluginTabs(plugins)
-              └── For each plugin:
-                  ├── Create tab button
-                  ├── Create tab content
-                  └── generatePluginConfigForm(plugin)
-                      ├── Read config_schema_data
-                      ├── Read current config
-                      └── Generate form HTML
-                          ├── Boolean → Toggle switch
-                          ├── Number → Number input
-                          ├── String → Text input
-                          ├── Array → Comma-separated input
-                          └── Enum → Select dropdown
 
-User Interactions
+`POST /api/v3/plugins/config/reset` replaces the plugin's section with the
-  ├── configurePlugin(pluginId)
+schema defaults (keeping secrets unless `preserve_secrets` is false).
-  │   └── showTab(`plugin-${pluginId}`)
-  │
-  ├── savePluginConfiguration(pluginId)
-  │   ├── Process form data
-  │   ├── Convert types per schema
-  │   └── For each field:
-  │       └── POST /api/v3/plugins/config
-  │
-  └── resetPluginConfig(pluginId)
-      ├── Get schema defaults
-      └── For each field:
-          └── POST /api/v3/plugins/config
-```
-
-### Backend (Python)
-
-```
-Flask Routes
-  ├── /api/v3/plugins/installed (GET)
-  │   └── api_plugins_installed()
-  │       ├── PluginManager.discover_plugins()
-  │       ├── For each plugin:
-  │       │   ├── PluginManager.get_plugin_info()
-  │       │   ├── Load config_schema.json
-  │       │   └── Load config from config.json
-  │       └── Return JSON response
-  │
-  └── /api/v3/plugins/config (POST)
-      └── api_plugin_config()
-          ├── Parse request JSON
-          ├── Load current config
-          ├── Update config[plugin_id][key] = value
-          └── Save config.json
-```
-
-## File Structure
-
-```
-LEDMatrix/
-│
-├── web_interface_v2.py
-│   └── Flask backend with plugin API endpoints
-│
-├── templates/
-│   └── index_v2.html
-│       └── Frontend with dynamic tab generation
-│
-├── config/
-│   └── config.json
-│       └── Stores all plugin configurations
-│
-├── plugins/
-│   ├── hello-world/
-│   │   ├── manifest.json           ← Plugin metadata
-│   │   ├── config_schema.json      ← UI schema definition
-│   │   ├── manager.py              ← Plugin logic
-│   │   └── requirements.txt
-│   │
-│   └── clock-simple/
-│       ├── manifest.json
-│       ├── config_schema.json
-│       └── manager.py
-│
-└── docs/
-    ├── PLUGIN_CONFIGURATION_TABS.md       ← Full documentation
-    ├── PLUGIN_CONFIG_TABS_SUMMARY.md      ← Implementation summary
-    ├── PLUGIN_CONFIG_QUICK_START.md       ← Quick start guide
-    └── PLUGIN_CONFIG_ARCHITECTURE.md      ← This file
-```
 
 ## Key Design Decisions
 
-### 1. Dynamic Tab Generation
+### 1. Server-side rendered forms
 
-**Why**: Plugins are installed/uninstalled dynamically  
+**Why**: One renderer for every plugin, no per-plugin frontend code
-**How**: JavaScript creates/removes tab elements on plugin list refresh  
+**How**: Jinja macros in `partials/plugin_config.html` walk the schema
-**Benefit**: No server-side template rendering needed
+**Benefit**: The settings search index is built from the same rendered HTML
+(`/v3/settings/search-index`)
 
-### 2. JSON Schema as Source of Truth
+### 2. JSON Schema as source of truth
 
 **Why**: Standard, well-documented, validation-ready
-**How**: Frontend interprets schema to generate forms  
+**How**: The same schema drives the form, the defaults and server-side validation
-**Benefit**: Plugin developers use familiar format
+**Benefit**: Plugin developers use a familiar format
 
-### 3. Individual Config Updates
+### 3. Whole-form saves that merge
 
-**Why**: Simplifies backend API  
+**Why**: A partial form (or a field the form doesn't show) must not wipe
-**How**: Each field saved separately via `/api/v3/plugins/config`  
+stored values
-**Benefit**: Atomic updates, easier error handling
+**How**: The handler starts from the stored section and merges what was posted
+**Benefit**: One request per save, atomic write
 
-### 4. Type Conversion in Frontend
+### 4. Secrets kept out of config.json
 
-**Why**: HTML forms only return strings  
+**Why**: `config.json` is shown in the raw editor and returned by the API
-**How**: JavaScript converts based on schema type before sending  
+**How**: `"x-secret": true` fields go to `config_secrets.json`, which is
-**Benefit**: Backend receives correctly-typed values
+deep-merged back into the plugin's config at load time
-
+**Benefit**: Plugins read secrets with plain `config.get(...)`
-### 5. No Nested Objects
-
-**Why**: Keeps UI simple  
-**How**: Only flat property structures supported  
-**Benefit**: Easy form generation, clear to users
 
 ## Extension Points
 
-### Adding New Input Types
+### Custom input widgets
 
-Location: `generatePluginConfigForm()` in `index_v2.html`
+Set `"x-widget": "<name>"` on a property. Core widgets are in
+`web_interface/static/v3/js/widgets/` (see its README); a plugin can ship its
+own widget script, served from `/static/plugin-widgets/<plugin_id>/<name>.js`.
+See [widget-guide.md](widget-guide.md).
 
-```javascript
+### Custom actions
-if (type === 'your-new-type') {
-    formHTML += `
-        <!-- Your custom input HTML -->
-    `;
-}
-```
 
-### Custom Validation
+Buttons that run plugin scripts are declared in the manifest's
+`web_ui_actions`. See [PLUGIN_WEB_UI_ACTIONS.md](PLUGIN_WEB_UI_ACTIONS.md).
 
-Location: `savePluginConfiguration()` in `index_v2.html`
+### Reacting to changes
 
-```javascript
+Implement `on_config_change(new_config)` in the plugin (see
-// Add validation before sending
+[PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md)).
-if (!validateCustomConstraint(value, propSchema)) {
-    throw new Error('Validation failed');
-}
-```
 
-### Backend Hook
+## Where to Look
 
-Location: `api_plugin_config()` in `web_interface_v2.py`
+| Concern | File |
-
+|---------|------|
-```python
+| Tab partial loader | `web_interface/blueprints/pages_v3.py` (`_load_plugin_config_partial`) |
-# Add custom logic before saving
+| Form template and field macros | `web_interface/templates/v3/partials/plugin_config.html` |
-if plugin_id == 'special-plugin':
+| Save / get / schema / reset handlers | `web_interface/blueprints/api_v3/plugins.py` |
-    value = transform_value(value)
+| Schema loading, defaults, validation | `src/plugin_system/schema_manager.py` |
-```
+| Secret masking and splitting | `src/web_interface/secret_helpers.py` |
-
+| Widgets | `web_interface/static/v3/js/widgets/` |
-## Performance Considerations
-
-### Frontend
-
-- **Tab Generation**: O(n) where n = number of plugins (typically < 20)
-- **Form Generation**: O(m) where m = number of config properties (typically < 10)
-- **Memory**: Each plugin tab ~5KB HTML
-- **Total Impact**: Negligible for typical use cases
-
-### Backend
-
-- **Schema Loading**: Cached after first load
-- **Config Updates**: Single file write (atomic)
-- **API Calls**: One per config field on save (sequential)
-- **Optimization**: Could batch updates in single API call
-
-## Security Considerations
-
-1. **Input Validation**: Schema constraints enforced client-side (UX) and should be enforced server-side
-2. **Path Traversal**: Plugin paths validated against known plugin directory
-3. **XSS**: All user inputs escaped before rendering in HTML
-4. **CSRF**: Flask CSRF tokens should be used in production
-5. **File Permissions**: config.json requires write access
 
 ## Error Handling
 
-### Frontend
+- Unknown plugin or unreadable schema: the partial renders an error message
-
+- Validation failure: `400` with `details` and `context.validation_errors`;
-- Network errors: Show notification, don't crash
+  the form shows them and nothing is saved
-- Schema errors: Graceful fallback to no config tab
+- Save failure: `500` with an error message; config.json is written
-- Type errors: Log to console, continue processing other fields
+  atomically, so a failed save leaves the previous file intact
-
-### Backend
-
-- Invalid plugin_id: 400 Bad Request
-- Schema not found: Return null, frontend handles gracefully
-- Config save error: 500 Internal Server Error with message
-
-## Testing Strategy
-
-### Unit Tests
-
-- `generatePluginConfigForm()` for each schema type
-- Type conversion logic in `savePluginConfiguration()`
-- Backend schema loading logic
-
-### Integration Tests
-
-- Full save flow: form → API → config.json
-- Tab generation from API response
-- Reset to defaults
-
-### E2E Tests
-
-- Install plugin → verify tab appears
-- Configure plugin → verify config saved
-- Uninstall plugin → verify tab removed
-
-## Monitoring
-
-### Frontend Metrics
-
-- Time to generate tabs
-- Form submission success rate
-- User interactions (configure, save, reset)
-
-### Backend Metrics
-
-- API response times
-- Config update success rate
-- Schema loading errors
-
-### User Feedback
-
-- Are users finding the configuration interface?
-- Are validation errors clear?
-- Are default values sensible?
-
-## Future Roadmap
-
-### Phase 2: Enhanced Validation
-- Real-time validation feedback
-- Custom error messages
-- Dependent field validation
-
-### Phase 3: Advanced Inputs
-- Color pickers for RGB arrays
-- File upload for assets
-- Rich text editor for descriptions
-
-### Phase 4: Configuration Management
-- Export/import configurations
-- Configuration presets
-- Version history/rollback
-
-### Phase 5: Developer Tools
-- Schema editor in web UI
-- Live preview while editing schema
-- Validation tester
-

docs/PLUGIN_DEPENDENCY_GUIDE.md

@@ -2,234 +2,160 @@
 
 ## Overview
 
-The LEDMatrix system has smart dependency installation that adapts based on who is running it. This guide explains how it works and potential pitfalls.
+A plugin lists its Python packages in its `requirements.txt`. LEDMatrix
+installs them for you when a plugin is installed, updated or loaded. This
+guide explains where they end up and what to do when a plugin can't import a
+package.
 
-## How It Works
+The rule to remember: **packages must be importable by `ledmatrix.service`,
+which runs as root.** Anything installed only into another user's
+`~/.local/` is invisible to it.
 
-### Execution Context Detection
+## Who Runs What
 
-The plugin manager checks if it's running as root:
+| Service | Runs as | Set by |
-```python
+|---------|---------|--------|
-running_as_root = os.geteuid() == 0
+| `ledmatrix.service` (display) | `root` | `systemd/ledmatrix.service` |
+| `ledmatrix-web.service` (web UI) | the user who ran the installer (e.g. `ledpi`) | `User=__USER__` in `systemd/ledmatrix-web.service`, filled in by `scripts/install/install_service.sh` |
+
+## How Dependencies Get Installed
+
+### 1. Installing or updating a plugin from the web UI
+
+The web interface is not root, so it installs through a narrow sudo helper:
+
+1. `PluginStoreManager._install_dependencies()`
+   (`src/plugin_system/store_manager.py`) calls
+   `install_requirements_file()` (`src/common/permission_utils.py`).
+2. That runs `sudo -n bash scripts/fix_perms/safe_pip_install.sh <plugin>/requirements.txt`.
+   The helper checks the path is the project's own `requirements.txt` or a
+   `requirements.txt` under `plugin-repos/` or `plugins/`, then runs
+   `python3 -m pip install --break-system-packages --ignore-installed -r ...`
+   **as root**, so the display service can import the packages.
+3. The sudoers rule that allows this is written by the installer
+   (`first_time_install.sh`) or by `scripts/install/configure_web_sudo.sh`.
+
+If sudo refuses (the rule isn't installed), `install_requirements_file()`
+falls back to installing with the web process's own interpreter, as the web
+user, and prefixes the pip output with a note like:
+
+```
+[Root install unavailable (...); installed for the current process's user only.
+Packages may not be visible to ledmatrix.service if it runs as a different
+user — run scripts/install/configure_web_sudo.sh to fix this.]
 ```
 
-Based on this, it chooses the appropriate installation method:
+Fix it by running `./scripts/install/configure_web_sudo.sh` as the web
+user (not with `sudo`; it asks for your password itself), then
+reinstall the plugin (or use the manual install below).
 
-| Running As | Installation Method | Location | Accessible To |
+The **Reinstall Plugin Deps** button on the web UI's Tools tab goes
-|------------|-------------------|----------|---------------|
+through the same helper for every installed plugin.
-| **root** (systemd service) | System-wide (`--break-system-packages`) | `/usr/local/lib/python3.X/dist-packages/` | All users |
+
-| **ledpi** or other user | User-specific (`--user`) | `~/.local/lib/python3.X/site-packages/` | Only that user |
+### 2. Loading a plugin
+
+When a plugin loads, `PluginLoader.install_dependencies()`
+(`src/plugin_system/plugin_loader.py`) checks its `requirements.txt`. If the
+requirements are already satisfied it does nothing; otherwise it runs
+`python3 -m pip install --break-system-packages -r requirements.txt` with the
+interpreter of the process doing the loading (retrying with
+`--ignore-installed` when a system package without a pip RECORD file is in
+the way).
+
+In `ledmatrix.service` that process is root, so restarting the display
+service installs anything missing system-wide:
+
+```bash
+sudo systemctl restart ledmatrix
+```
+
+If you run `python3 run.py` by hand as a normal user instead, pip cannot
+write to the system site-packages and installs into your `~/.local/`. That
+works for your manual run but not for the service.
 
 ## Common Scenarios
 
-### ✅ Scenario 1: Normal Production Use (Recommended)
+### Installing plugins from the web UI (recommended)
 
-**What:** Services running via systemd
+Use the **Plugin Manager** tab. Dependencies are installed as root through
+the sudo helper and the display service can use them.
+
+### Running the display manually for debugging
 
 ```bash
-sudo systemctl start ledmatrix
+cd ~/LEDMatrix
-sudo systemctl start ledmatrix-web
+sudo python3 run.py        # same user as the service
 ```
 
-- **Runs as:** root (configured in .service files)
+Running as your own user works for plugins whose packages are already
-- **Installs to:** System-wide
+installed system-wide, but any *missing* package lands in `~/.local/`.
-- **Result:** ✅ Works perfectly, all dependencies accessible
 
-### ✅ Scenario 2: Web Interface Plugin Installation
+### A plugin works when run manually but fails in the service
 
-**What:** Installing/enabling plugins via web interface at `http://pi-ip:5000`
+Its packages were installed for your user only. Install them as root (see
+below) and restart the service.
 
-- **Web service runs as:** root (ledmatrix-web.service)
+## Manual Installation
-- **Installs to:** System-wide
-- **Result:** ✅ Works perfectly, systemd service can access them
 
-### ✅ Scenario 3: Manual Testing as ledpi (Read-only)
+### All plugins
-
-**What:** Running display manually as ledpi to test/debug
 
 ```bash
-# As ledpi user
+sudo ~/LEDMatrix/scripts/install_plugin_dependencies.sh
-cd /home/ledpi/LEDMatrix
-python3 run.py
-```
-
-- **Runs as:** ledpi
-- **Can import:** ✅ System-wide packages (installed by root)
-- **Result:** ✅ Works! Can use existing plugins with root-installed dependencies
-
-### ⚠️ Scenario 4: Manual Plugin Installation as ledpi (Problematic)
-
-**What:** Enabling a NEW plugin and running manually as ledpi
-
-```bash
-# As ledpi user
-cd /home/ledpi/LEDMatrix
-# Edit config to enable new plugin
-nano config/config.json
-# Run display - will try to install new plugin dependencies
-python3 run.py
-```
-
-**What Happens:**
-1. Plugin manager runs as `ledpi`
-2. Installs dependencies with `--user` flag
-3. Dependencies go to `~/.local/lib/python3.X/site-packages/`
-4. ⚠️ **Warning logged:** "Installing plugin dependencies for current user (not root)"
-
-**Problem:**
-- When systemd service restarts (as root), it **can't see** `~/.local/` packages
-- Plugin will fail to load for the systemd service
-
-**Solution:**
-After testing, restart the service to install dependencies system-wide:
-```bash
 sudo systemctl restart ledmatrix
 ```
 
-## Best Practices
+The script installs every `requirements.txt` found in the plugins directory
+configured by `plugin_system.plugins_directory` in `config/config.json`
+(default `plugin-repos/`). Run it with `sudo` so the packages are installed
+system-wide.
 
-### For Production/Normal Use
+### One plugin
 
-1. **Always use the web interface** to install/enable plugins
-2. **Or restart the systemd service** after config changes:
 ```bash
+cd ~/LEDMatrix/plugin-repos/PLUGIN-NAME     # or your configured plugins directory
+sudo python3 -m pip install --break-system-packages --no-cache-dir -r requirements.txt
 sudo systemctl restart ledmatrix
 ```
 
-### For Development/Testing
+`--no-cache-dir` avoids errors about `/root/.cache/pip` not being writable.
-
-1. **Read existing plugins:** Safe to run as `ledpi` - can import system packages
-2. **Test new plugins:** Use sudo or restart service to install dependencies:
-   ```bash
-   # Option 1: Run as root
-   sudo python3 run.py
-   
-   # Option 2: Install deps manually
-   sudo pip3 install --break-system-packages -r plugins/my-plugin/requirements.txt
-   python3 run.py
-   
-   # Option 3: Let service install them
-   sudo systemctl restart ledmatrix
-   ```
-
-## Warning Messages
-
-### If you see this warning:
-```
-Installing plugin dependencies for current user (not root).
-These will NOT be accessible to the systemd service.
-For production use, install plugins via the web interface or restart the ledmatrix service.
-```
-
-**What it means:**
-- You're running as a non-root user
-- Dependencies were installed to your user directory only
-- The systemd service won't be able to use this plugin
-
-**What to do:**
-```bash
-# Restart the service to install dependencies system-wide
-sudo systemctl restart ledmatrix
-```
 
 ## Troubleshooting
 
-### Plugin works when I run manually but fails in systemd service
-
-**Cause:** Dependencies installed to user directory (`~/.local/`) instead of system-wide
-
-**Fix:**
-```bash
-# Check where package is installed
-pip3 list -v | grep <package-name>
-
-# If it shows ~/.local/, reinstall system-wide:
-sudo pip3 install --break-system-packages <package-name>
-
-# Or just restart the service:
-sudo systemctl restart ledmatrix
-```
-
 ### Permission denied when installing dependencies
 
-**If you see errors like:**
 ```
 ERROR: Could not install packages due to an OSError: [Errno 13] Permission denied: '/root/.local'
 WARNING: The directory '/root/.cache/pip' or its parent directory is not owned or is not writable
 ```
 
-**Quick Fix - Use the Helper Script:**
+Use one of the manual installs above (they pass `--no-cache-dir`).
-```bash
-sudo /home/ledpi/LEDMatrix/scripts/install_plugin_dependencies.sh
-sudo systemctl restart ledmatrix
-```
 
-**Manual Fix:**
+### Checking where a package is installed
-```bash
-# Install dependencies with --no-cache-dir to avoid cache permission issues
-cd /home/ledpi/LEDMatrix/plugins/PLUGIN-NAME
-sudo pip3 install --break-system-packages --no-cache-dir -r requirements.txt
-sudo systemctl restart ledmatrix
-```
-
-**For more detailed troubleshooting, see:** [Plugin Dependency Troubleshooting Guide](PLUGIN_DEPENDENCY_TROUBLESHOOTING.md)
-
-## Architecture Summary
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    LEDMatrix Services                        │
-├─────────────────────────────────────────────────────────────┤
-│                                                              │
-│  ledmatrix.service (User=root)                              │
-│  ledmatrix-web.service (User=root)                          │
-│  ├── Install dependencies system-wide                        │
-│  └── Accessible to all users                                 │
-│                                                              │
-├─────────────────────────────────────────────────────────────┤
-│                                                              │
-│  Manual execution as ledpi                                   │
-│  ├── Can READ system-wide packages ✅                        │
-│  ├── WRITES go to ~/.local/ ⚠️                               │
-│  └── Not accessible to root service                          │
-│                                                              │
-└─────────────────────────────────────────────────────────────┘
-```
-
-## Recommendations
-
-1. **For end users:** Always use the web interface for plugin management
-2. **For developers:** Be aware of the user context when testing
-3. **For plugin authors:** Test with `sudo systemctl restart ledmatrix` to ensure dependencies install correctly
-4. **For CI/CD:** Always run installation as root or use the service
-
-## Helper Scripts
-
-### Install Plugin Dependencies Script
-
-Located at: `scripts/install_plugin_dependencies.sh`
-
-This script automatically finds and installs dependencies for all plugins:
 
 ```bash
-# Run as root (recommended for production)
+# How the service sees it
-sudo /home/ledpi/LEDMatrix/scripts/install_plugin_dependencies.sh
+sudo python3 -c "import package_name; print(package_name.__file__)"
 
-# Make executable if needed
+# A path under /home/<user>/.local/ means it was installed for that user only
-chmod +x /home/ledpi/LEDMatrix/scripts/install_plugin_dependencies.sh
+python3 -m pip show -f package_name
 ```
 
-Features:
+For more, see the [Plugin Dependency Troubleshooting Guide](PLUGIN_DEPENDENCY_TROUBLESHOOTING.md).
-- Auto-detects all plugins with requirements.txt
+
-- Uses correct installation method (system-wide vs user)
+## For Plugin Authors
-- Bypasses pip cache to avoid permission issues
+
-- Provides detailed logging and error messages
+1. Keep `requirements.txt` minimal and pin only what you need.
+2. Test that it installs the way the Pi will install it:
+   ```bash
+   sudo python3 -m pip install --break-system-packages --no-cache-dir -r requirements.txt
+   ```
+3. Note any `apt` packages your plugin needs in its README.
 
 ## Files to Reference
 
-- Service configs: `ledmatrix.service`, `ledmatrix-web.service`
+- Service units: `systemd/ledmatrix.service`, `systemd/ledmatrix-web.service`
-- Plugin manager: `src/plugin_system/plugin_manager.py`
+- Store installs: `src/plugin_system/store_manager.py` (`_install_dependencies`)
-- Installation script: `first_time_install.sh`
+- Root install helper: `src/common/permission_utils.py` (`install_requirements_file`), `scripts/fix_perms/safe_pip_install.sh`
-- Dependency installer: `scripts/install_plugin_dependencies.sh`
+- Load-time installs: `src/plugin_system/plugin_loader.py` (`install_dependencies`)
-- Troubleshooting guide: `PLUGIN_DEPENDENCY_TROUBLESHOOTING.md`
+- Sudo rules: `scripts/install/configure_web_sudo.sh`
-
+- Manual installer: `scripts/install_plugin_dependencies.sh`

docs/PLUGIN_DEPENDENCY_TROUBLESHOOTING.md

@@ -1,6 +1,7 @@
 # Plugin Dependency Installation Troubleshooting
 
-This guide helps resolve issues with automatic plugin dependency installation in the LEDMatrix system.
+This guide helps resolve problems installing a plugin's Python packages. For
+how installation works, see the [Plugin Dependency Guide](PLUGIN_DEPENDENCY_GUIDE.md).
 
 ## Common Error Symptoms
 
@@ -10,109 +11,118 @@ ERROR: Could not install packages due to an OSError: [Errno 13] Permission denie
 WARNING: The directory '/root/.cache/pip' or its parent directory is not owned or is not writable
 ```
 
-### Context Mismatch
+### Installed for the wrong user
+The pip output shown after a web-UI install starts with:
 ```
-WARNING: Installing plugin dependencies for current user (not root). 
+[Root install unavailable (...); installed for the current process's user only.
-These will NOT be accessible to the systemd service.
+Packages may not be visible to ledmatrix.service if it runs as a different
+user — run scripts/install/configure_web_sudo.sh to fix this.]
 ```
 
+### Plugin fails to load with `ModuleNotFoundError`
+The display service can't see a package the plugin needs.
+
 ## Root Cause
 
-Plugin dependencies must be installed in a context accessible to the LEDMatrix systemd service, which runs as root. Permission errors typically occur when:
+Plugin packages must be importable by `ledmatrix.service`, which runs as
+root. The web interface (`ledmatrix-web.service`) runs as the user who
+installed LEDMatrix, so it installs through a sudo helper
+(`scripts/fix_perms/safe_pip_install.sh`). Problems usually come from:
 
-1. The pip cache directory has incorrect permissions
+1. The sudoers rule for that helper missing, so the web UI installed the
-2. The process tries to install to user directories without proper permissions
+   packages for its own user only
-3. Environment variables (like HOME) are not set correctly for the service context
+2. Running `python3 run.py` by hand as a normal user, which installs missing
+   packages into `~/.local/`
+3. pip's cache directory not being writable for root
 
 ## Solutions
 
-### Solution 1: Use the Manual Installation Script (Recommended)
+### Solution 1: Restore the sudo rule, then reinstall
-
-We provide a helper script that handles dependency installation correctly:
 
 ```bash
-# Run as root to install system-wide (for production)
+cd ~/LEDMatrix
-sudo /home/ledpi/LEDMatrix/scripts/install_plugin_dependencies.sh
+./scripts/install/configure_web_sudo.sh   # as the web user, not with sudo
+```
 
-# After installation, restart the service
+Then reinstall the plugin from the **Plugin Manager** tab, or click
+**Reinstall Plugin Deps** on the **Tools** tab.
+
+### Solution 2: Install every plugin's dependencies from the terminal
+
+```bash
+sudo ~/LEDMatrix/scripts/install_plugin_dependencies.sh
 sudo systemctl restart ledmatrix
 ```
 
-This script:
+The script finds each `requirements.txt` in the plugins directory set by
-- Detects all plugins with requirements.txt files
+`plugin_system.plugins_directory` in `config/config.json` (default
-- Installs dependencies with correct permissions
+`plugin-repos/`), installs with `--no-cache-dir`, and reports what it found.
-- Uses `--no-cache-dir` to avoid cache permission issues
-- Provides detailed logging for troubleshooting
 
-### Solution 2: Manual Installation per Plugin
+### Solution 3: Install one plugin's dependencies
-
-If you need to install dependencies for a specific plugin:
 
 ```bash
-# Navigate to the plugin directory
+# Your configured plugins directory; plugin-repos/ by default
-cd /home/ledpi/LEDMatrix/plugins/PLUGIN-NAME
+cd ~/LEDMatrix/plugin-repos/PLUGIN-NAME
 
-# Install as root (system-wide)
+sudo python3 -m pip install --break-system-packages --no-cache-dir -r requirements.txt
-sudo pip3 install --break-system-packages --no-cache-dir -r requirements.txt
 
-# Restart the service
 sudo systemctl restart ledmatrix
 ```
 
-### Solution 3: Fix Cache Directory Permissions
+### Solution 4: Let the display service install them
 
-If you specifically have cache permission issues:
+When a plugin loads, the display service installs any missing requirements
+itself, as root:
+
+```bash
+sudo systemctl restart ledmatrix
+sudo journalctl -u ledmatrix -f     # watch for "Installing dependencies for plugin ..."
+```
+
+### Solution 5: Fix pip cache permissions
 
 ```bash
 # Option A: Skip the cache (recommended)
-sudo pip3 install --no-cache-dir --break-system-packages -r requirements.txt
+sudo python3 -m pip install --no-cache-dir --break-system-packages -r requirements.txt
 
-# Option B: Fix cache permissions (if needed)
+# Option B: Fix cache permissions
 sudo mkdir -p /root/.cache/pip
 sudo chown -R root:root /root/.cache
 sudo chmod -R 755 /root/.cache
 ```
 
-### Solution 4: Install via Web Interface
-
-The web interface handles dependency installation correctly in the service context:
-
-1. Access the web interface (`http://ledpi:5000` or `http://your-pi-ip:5000`)
-2. Open the **Plugin Manager** tab (use the **Plugin Store** section to
-   find the plugin, or **Install from GitHub**)
-3. Install the plugin through the web UI
-4. The system automatically handles dependency installation in the
-   service context (which has the right permissions)
-
 ## Prevention
 
 ### For Plugin Developers
 
-When creating plugins with dependencies:
-
 1. **Keep requirements minimal**: Only include essential packages
-2. **Test installation**: Verify your requirements.txt works with:
+2. **Test installation** the way the Pi does it:
    ```bash
-   sudo pip3 install --break-system-packages --no-cache-dir -r requirements.txt
+   sudo python3 -m pip install --break-system-packages --no-cache-dir -r requirements.txt
    ```
 3. **Document dependencies**: Note any system packages needed (via apt)
 
 ### For Users
 
-1. **Use web interface**: Install plugins via the web UI when possible
+1. **Use the web interface** to install plugins
-2. **Install as root**: When using SSH/terminal, use sudo for plugin installations
+2. **Use sudo** for installs from SSH/terminal
-3. **Restart service**: After manual installations, restart the ledmatrix service
+3. **Restart the service** after manual installations
 
 ## Technical Details
 
-### How Dependency Installation Works
+### Where installs happen
 
-The `PluginManager._install_plugin_dependencies()` method:
+- **Web UI install/update:** `PluginStoreManager._install_dependencies()`
-
+  → `install_requirements_file()` in `src/common/permission_utils.py`, which
-1. Detects if running as root using `os.geteuid() == 0`
+  runs `sudo -n bash scripts/fix_perms/safe_pip_install.sh <requirements.txt>`.
-2. If root: Uses system-wide installation with `--break-system-packages --no-cache-dir`
+  The helper only accepts the project's `requirements.txt` or one under
-3. If not root: Uses user installation with `--user --break-system-packages --no-cache-dir`
+  `plugin-repos/` or `plugins/`, and runs
-4. The `--no-cache-dir` flag prevents cache-related permission issues
+  `pip install --break-system-packages --ignore-installed` as root. If sudo
+  refuses, it falls back to a pip install as the web user and says so.
+- **Plugin load:** `PluginLoader.install_dependencies()` in
+  `src/plugin_system/plugin_loader.py` skips satisfied requirements and
+  otherwise runs `pip install --break-system-packages` with the loading
+  process's interpreter — root in `ledmatrix.service`.
 
 ### Why `--break-system-packages`?
 
@@ -120,26 +130,20 @@ Debian 12+ (Bookworm) and Raspberry Pi OS based on it implement PEP 668, which p
 
 ### Service Context
 
-The ledmatrix.service runs as:
+- `ledmatrix.service` runs as **root** with `/usr/bin/python3`
-- **User**: root
+- `ledmatrix-web.service` runs as **the installing user**
-- **WorkingDirectory**: /home/ledpi/LEDMatrix
-- **Python**: /usr/bin/python3
 
-Dependencies must be installed in root's Python environment or system-wide to be accessible.
+Dependencies must be installed system-wide (as root) to be visible to the
+display service.
 
 ## Checking Installation
 
-Verify dependencies are installed correctly:
-
 ```bash
 # Check as root (how the service sees it)
-sudo python3 -c "import package_name"
+sudo python3 -c "import package_name; print(package_name.__file__)"
 
-# List installed packages
+# A path under /home/<user>/.local/ means a user-only install
-pip3 list
+python3 -m pip show -f package_name
-
-# Check specific package
-pip3 show package_name
 ```
 
 ## Getting Help
@@ -151,19 +155,11 @@ If you continue to experience issues:
    sudo journalctl -u ledmatrix -f
    ```
 
-2. Check pip logs (created by manual script):
+2. Verify the plugin manifest and requirements (default plugins directory
+   shown):
    ```bash
-   cat /tmp/pip_install_*.log
+   cat ~/LEDMatrix/plugin-repos/PLUGIN-NAME/manifest.json
-   ```
+   cat ~/LEDMatrix/plugin-repos/PLUGIN-NAME/requirements.txt
-
-3. Verify plugin manifest is correct:
-   ```bash
-   cat /home/ledpi/LEDMatrix/plugins/PLUGIN-NAME/manifest.json
-   ```
-
-4. Check plugin requirements:
-   ```bash
-   cat /home/ledpi/LEDMatrix/plugins/PLUGIN-NAME/requirements.txt
    ```
 
 ## Related Documentation
@@ -171,4 +167,3 @@ If you continue to experience issues:
 - [Plugin Dependency Guide](PLUGIN_DEPENDENCY_GUIDE.md)
 - [Plugin Development Guide](PLUGIN_DEVELOPMENT_GUIDE.md)
 - [Troubleshooting](TROUBLESHOOTING.md)
-

docs/PLUGIN_DEVELOPMENT_GUIDE.md

@@ -3,8 +3,10 @@
 This guide explains how to set up a development workflow for plugins that are maintained in separate Git repositories while still being able to test them within the LEDMatrix project.
 
 > **Rendering guidance:** plugins should read the display size dynamically
-> (`self.display_manager.matrix.width/height`) rather than hardcoding one
+> (`self.display_manager.width/height`) rather than hardcoding one
-> panel. For plugins that want to *scale* their layout to any panel, the
+> panel. Don't read `display_manager.matrix.width/height`: `matrix` is
+> `None` when hardware init fails, while the `width`/`height` properties
+> fall back to the canvas size. For plugins that want to *scale* their layout to any panel, the
 > opt-in adaptive layout system ([ADAPTIVE_LAYOUT.md](ADAPTIVE_LAYOUT.md))
 > provides the shared helpers — fonts, images, and composite layouts that
 > scale. Existing plugins keep their classic rendering unless they adopt
@@ -43,28 +45,45 @@ The solution uses **symbolic links** to connect plugin repositories to the `plug
 
 ## Quick Start
 
-### 1. Link a Plugin from GitHub
+Official plugins all live in one repository,
+[ledmatrix-plugins](https://github.com/ChuckBuilds/ledmatrix-plugins), with
+one directory per plugin under `plugins/` (there are no per-plugin
+`ledmatrix-<name>` repositories). The helper script links a plugin directory
+from a checkout of that monorepo into LEDMatrix's `plugins/` directory.
 
-The easiest way to link a plugin that's already on GitHub:
+### 1. Link an Official Plugin
 
 ```bash
-./scripts/dev/dev_plugin_setup.sh link-github music
+./scripts/dev/dev_plugin_setup.sh link-github football-scoreboard
 ```
 
 This will:
-- Clone `https://github.com/ChuckBuilds/ledmatrix-music.git` to `~/.ledmatrix-dev-plugins/ledmatrix-music`
+- Clone `https://github.com/ChuckBuilds/ledmatrix-plugins.git` to
-- Create a symbolic link from `plugins/music` to the cloned repository
+  `~/.ledmatrix-dev-plugins/ledmatrix-plugins` (or `git pull` it if it is
-- Validate that the plugin has a proper `manifest.json`
+  already there)
+- Find `plugins/football-scoreboard` in it (also accepted:
+  `plugins/ledmatrix-<name>`, or a plugin whose manifest `id` is the name)
+- Validate that it has a `manifest.json`
+- Create a symbolic link named after the plugin's manifest id, e.g.
+  `plugins/football-scoreboard` → `~/.ledmatrix-dev-plugins/ledmatrix-plugins/plugins/football-scoreboard`
 
-### 2. Link a Local Plugin Repository
+`link-github music` finds the monorepo's `plugins/ledmatrix-music` directory
+and links it into LEDMatrix as `plugins/ledmatrix-music`, because
+`ledmatrix-music` is that plugin's manifest id.
 
-If you already have a plugin repository cloned locally:
+To work from your fork of the monorepo, set `github_user` in
+`dev_plugins.json` (see [Configuration](#configuration)).
+
+### 2. Link a Local Plugin Directory
+
+If you already have the monorepo (or a third-party plugin repository) cloned
+locally:
 
 ```bash
-./scripts/dev/dev_plugin_setup.sh link music ../ledmatrix-music
+./scripts/dev/dev_plugin_setup.sh link hello-world ../ledmatrix-plugins/plugins/hello-world
 ```
 
-This creates a symlink from `plugins/music` to your local repository path.
+This creates a symlink from `plugins/hello-world` to that directory.
 
 ### 3. Check Status
 
@@ -77,13 +96,17 @@ See which plugins are linked and their git status:
 ### 4. Work on Your Plugin
 
 ```bash
-cd plugins/music  # Actually editing the linked repository
+cd plugins/football-scoreboard  # Actually editing the monorepo checkout
-# Make your changes
+# Make your changes, then bump "version" in manifest.json
 git add .
-git commit -m "feat: add new feature"
+git commit -m "feat(football-scoreboard): add new feature"
-git push origin main
+git push   # to your fork, then open a PR against ledmatrix-plugins
 ```
 
+In the monorepo, every plugin change must bump `version` in the plugin's
+`manifest.json` and run `python update_registry.py`, or users won't receive
+the update.
+
 ### 5. Update Plugins
 
 Pull latest changes from remote:
@@ -116,7 +139,7 @@ Links a local plugin repository to the plugins directory.
 
 **Example:**
 ```bash
-./scripts/dev/dev_plugin_setup.sh link football-scoreboard ../ledmatrix-football-scoreboard
+./scripts/dev/dev_plugin_setup.sh link football-scoreboard ../ledmatrix-plugins/plugins/football-scoreboard
 ```
 
 **Notes:**
@@ -129,23 +152,25 @@ Links a local plugin repository to the plugins directory.
 Clones a plugin from GitHub and links it.
 
 **Arguments:**
-- `plugin-name`: The name of the plugin (will be the directory name in `plugins/`)
+- `plugin-name`: Without `repo-url`, the plugin to link from the monorepo: a
-- `repo-url`: (Optional) Full GitHub repository URL. If omitted, constructs from pattern: `https://github.com/ChuckBuilds/ledmatrix-<plugin-name>.git`
+  directory under `plugins/` (`<name>` or `ledmatrix-<name>`) or a manifest
+  id. The link is named after the plugin's manifest id. With `repo-url`, the
+  name of the link in `plugins/`.
+- `repo-url`: (Optional) A plugin that has its own repository (e.g. a
+  third-party plugin). The repository root is linked.
 
 **Examples:**
 ```bash
-# Auto-construct URL from plugin name
+# Official plugin, from the ledmatrix-plugins monorepo
-./scripts/dev/dev_plugin_setup.sh link-github music
+./scripts/dev/dev_plugin_setup.sh link-github stocks
 
-# Use explicit URL
+# Third-party plugin with its own repository
-./scripts/dev/dev_plugin_setup.sh link-github stocks https://github.com/ChuckBuilds/ledmatrix-stocks.git
-
-# Link from a different GitHub user
 ./scripts/dev/dev_plugin_setup.sh link-github custom-plugin https://github.com/OtherUser/custom-plugin.git
 ```
 
 **Notes:**
 - Repositories are cloned to `~/.ledmatrix-dev-plugins/` by default (configurable)
+- The monorepo is cloned once and shared by every plugin you link from it
 - If the repository already exists, it will be updated with `git pull` instead of re-cloning
 - The cloned repository is preserved when you unlink the plugin
 
@@ -217,30 +242,28 @@ Updates plugin(s) by running `git pull` in their repositories.
 
 ### Custom Development Directory
 
-By default, GitHub repositories are cloned to `~/.ledmatrix-dev-plugins/`. You can customize this by creating a `dev_plugins.json` file:
+By default, GitHub repositories are cloned to `~/.ledmatrix-dev-plugins/`
+and official plugins come from `ChuckBuilds/ledmatrix-plugins`. To change
+either, copy `dev_plugins.json.example` (in the LEDMatrix root) to
+`dev_plugins.json` and edit it. `dev_plugins.json` is git-ignored.
 
 ```json
 {
-  "dev_plugins_dir": "/path/to/your/dev/plugins",
+  "dev_plugins_dir": "~/.ledmatrix-dev-plugins",
-  "github_user": "ChuckBuilds",
+  "github_user": "your-github-user",
-  "github_pattern": "ledmatrix-",
+  "plugins_repo": "ledmatrix-plugins",
-  "plugins": {
+  "plugins_branch": "main"
-    "music": {
-      "source": "github",
-      "url": "https://github.com/ChuckBuilds/ledmatrix-music.git",
-      "branch": "main"
-    }
-  }
 }
 ```
 
-**Configuration options:**
+**Configuration options** (all optional):
 - `dev_plugins_dir`: Where to clone GitHub repositories (default: `~/.ledmatrix-dev-plugins`)
-- `github_user`: Default GitHub username for auto-constructing URLs
+- `github_user`: Owner of the plugin monorepo that `link-github <name>` clones — set it to use your fork (default: `ChuckBuilds`)
-- `github_pattern`: Pattern for repository names (default: `ledmatrix-`)
+- `plugins_repo`: Name of that monorepo (default: `ledmatrix-plugins`)
-- `plugins`: Plugin definitions (optional, for future auto-discovery features)
+- `plugins_branch`: Branch to clone it at (default: the repository's default branch). Only applies when the clone is first made.
 
-**Note:** Copy `dev_plugins.json.example` to `dev_plugins.json` and customize it. The `dev_plugins.json` file is git-ignored.
+`github_pattern` from older versions of this guide is no longer used (the
+script warns if it is set).
 
 ## Development Workflow
 
@@ -248,43 +271,46 @@ By default, GitHub repositories are cloned to `~/.ledmatrix-dev-plugins/`. You c
 
 1. **Link your plugin for development:**
    ```bash
-   ./scripts/dev/dev_plugin_setup.sh link-github music
+   ./scripts/dev/dev_plugin_setup.sh link-github clock-simple
    ```
 
 2. **Test in LEDMatrix:**
    ```bash
-   # Run LEDMatrix with your plugin
+   # Run LEDMatrix with your plugin (emulator shown)
-   python run.py
+   python3 run.py -e
    ```
 
 3. **Make changes:**
    ```bash
-   cd plugins/music
+   cd plugins/clock-simple
    # Edit files...
    # Test changes...
    ```
 
-4. **Commit to plugin repository:**
+4. **Commit to the plugin repository:**
    ```bash
-   cd plugins/music  # This is actually your repo
+   cd plugins/clock-simple  # This is inside your monorepo checkout
+   # bump "version" in manifest.json, then from the monorepo root:
+   # python update_registry.py
    git add .
-   git commit -m "feat: add new feature"
+   git commit -m "feat(clock-simple): add new feature"
-   git push origin main
+   git push
    ```
 
 5. **Update from remote (if needed):**
    ```bash
-   ./scripts/dev/dev_plugin_setup.sh update music
+   ./scripts/dev/dev_plugin_setup.sh update clock-simple
    ```
 
 6. **When done developing:**
    ```bash
-   ./scripts/dev/dev_plugin_setup.sh unlink music
+   ./scripts/dev/dev_plugin_setup.sh unlink clock-simple
    ```
 
 ### Working with Multiple Plugins
 
-You can have multiple plugins linked simultaneously:
+You can have multiple plugins linked simultaneously. Plugins linked from the
+monorepo share one checkout:
 
 ```bash
 ./scripts/dev/dev_plugin_setup.sh link-github music
@@ -294,7 +320,7 @@ You can have multiple plugins linked simultaneously:
 # Check status of all
 ./scripts/dev/dev_plugin_setup.sh status
 
-# Update all at once
+# Update all at once (the shared monorepo checkout is pulled once)
 ./scripts/dev/dev_plugin_setup.sh update
 ```
 
@@ -409,7 +435,7 @@ If you have conflicts when updating:
 
 1. **Manually resolve in the plugin repository:**
    ```bash
-   cd ~/.ledmatrix-dev-plugins/ledmatrix-music
+   cd ~/.ledmatrix-dev-plugins/ledmatrix-plugins
    git pull
    # Resolve conflicts...
    git add .
@@ -470,18 +496,19 @@ You can mix local and GitHub plugins:
 
 The development workflow is separate from the plugin store installation:
 
-- **Plugin Store:** Installs plugins to `plugins/` as regular directories
+- **Plugin Store:** Installs plugins as regular directories in the configured
-- **Development Setup:** Links plugin repositories as symlinks
+  plugins directory (`plugin-repos/` by default)
+- **Development Setup:** Links plugin directories as symlinks in `plugins/`
 
-If you install a plugin via the store, you can still link it for development:
+The plugin loader scans only one directory, so while developing set
+`plugin_system.plugins_directory` to `plugins` (see the note at the top of
+this guide). If `plugins/` already holds a regular directory of the same
+name, `link`/`link-github` offers to rename it to
+`<name>.backup.<timestamp>` before linking.
 
-```bash
+`unlink` removes only the symlink. To switch back to the store version, set
-# Store installs to plugins/music (regular directory)
+`plugins_directory` back to `plugin-repos` (or reinstall the plugin from the
-# Link for development (will prompt to replace)
+store).
-./scripts/dev/dev_plugin_setup.sh link-github music
-```
-
-When you unlink, the directory is removed. If you want to switch back to the store version, re-install it via the plugin store.
 
 ## API Reference
 
@@ -525,7 +552,7 @@ Want to create and share your own plugin? Here's everything you need to know.
    - [Advanced Plugin Development](ADVANCED_PLUGIN_DEVELOPMENT.md) - Patterns and examples
 
 2. **Start with a template**:
-   - Use the [Hello World plugin](https://github.com/ChuckBuilds/ledmatrix-hello-world) as a starting point
+   - Use the [Hello World plugin](https://github.com/ChuckBuilds/ledmatrix-plugins/tree/main/plugins/hello-world) as a starting point
    - Or fork an existing plugin and modify it
 
 3. **Follow the plugin structure**:
@@ -589,24 +616,16 @@ Your plugin must:
 ### Versioning Best Practices
 
 - **Use semantic versioning**: `MAJOR.MINOR.PATCH` (e.g., `1.2.3`)
-- **GitHub as source of truth**: the plugin store resolves versions in this
+- **Bump `version` in `manifest.json` by hand** for every change you ship.
-  order: GitHub Releases → GitHub Tags → manifest from branch → git commit hash
+  There is no automatic version-bump hook or bump script.
-- **Automatic version bumping**: install the self-contained pre-push hook in
+- **Official (monorepo) plugins**: after bumping the manifest, run
-  your plugin repo and patch versions bump themselves on push (a git tag
+  `python update_registry.py` in the `ledmatrix-plugins` checkout. It copies
-  `v{version}` is created and `manifest.json` staged automatically):
+  each manifest's version into `plugins.json` as `latest_version`, which is
-
+  what the store compares installed versions against. Without it, users
-  ```bash
+  won't be offered the update.
-  # From your plugin repository directory
+- **Plugins in their own repository**: still bump the manifest `version`,
-  cp /path/to/LEDMatrix/scripts/git-hooks/pre-push-plugin-version .git/hooks/pre-push
+  so users can see which version they run; tagging releases (`v1.2.3`) to
-  chmod +x .git/hooks/pre-push
+  match is a good habit.
-  ```
-
-  Set `SKIP_TAG=1` in the environment to skip auto-tagging for one push.
-- **Manual versioning**: only needed for major/minor bumps, CI pipelines that
-  bypass hooks, or forks without the hook — use
-  `scripts/bump_plugin_version.py`.
-- **Registry stores no versions**: `plugins.json` holds only metadata (name,
-  description, repo URL).
 
 ### Submitting to Official Registry
 
@@ -618,12 +637,14 @@ To have your plugin added to the official plugin store:
    - Follows best practices
    - Tested on Raspberry Pi hardware
 
-2. **Create GitHub repository**:
+2. **Choose where it lives** (see `SUBMISSION.md` in
-   - Repository name: `ledmatrix-<plugin-name>`
+   [ledmatrix-plugins](https://github.com/ChuckBuilds/ledmatrix-plugins)):
-   - Public repository
+   - **In the monorepo (preferred):** fork ledmatrix-plugins, add
-   - Proper README.md with installation instructions
+     `plugins/<your-plugin-id>/`, and open a pull request
+   - **In your own public repository** (conventionally
+     `ledmatrix-<plugin-name>`), with a README that covers installation
 
-3. **Contact maintainers**:
+3. **Contact maintainers** (own-repository plugins):
    - Open a GitHub issue in the [ledmatrix-plugins](https://github.com/ChuckBuilds/ledmatrix-plugins) repository
    - Or reach out on Discord: https://discord.gg/uW36dVAtcT
    - Include: Repository URL, plugin description, why it's useful

docs/PLUGIN_QUICK_REFERENCE.md

@@ -127,7 +127,8 @@ git push origin v1.0.0
 
 ### REST API
 
-The API is mounted at `/api/v3` (`web_interface/app.py:199`).
+The API is mounted at `/api/v3` (the `api_v3` blueprint in
+`web_interface/blueprints/api_v3/`, registered in `web_interface/app.py`).
 
 ```bash
 # Install plugin from the registry

docs/PLUGIN_REGISTRY_SETUP_GUIDE.md

@@ -103,6 +103,7 @@ All plugins can be installed through the LEDMatrix web interface:
 Or via API:
 ```bash
 curl -X POST http://your-pi-ip:5000/api/v3/plugins/install \
+  -H "Content-Type: application/json" \
   -d '{"plugin_id": "clock-simple"}'
 ```
 
@@ -153,6 +154,7 @@ Before submitting, ensure your plugin:
    ```bash
    # Install via URL on your Pi
    curl -X POST http://your-pi:5000/api/v3/plugins/install-from-url \
+     -H "Content-Type: application/json" \
      -d '{"repo_url": "https://github.com/you/ledmatrix-your-plugin"}'
    ```
 
@@ -312,6 +314,7 @@ git push
 # 2. Review using VERIFICATION.md checklist
 # 3. Test installation:
 curl -X POST http://pi:5000/api/v3/plugins/install-from-url \
+  -H "Content-Type: application/json" \
   -d '{"repo_url": "https://github.com/contributor/plugin"}'
 
 # 4. If approved, merge PR

docs/PLUGIN_STORE_GUIDE.md

@@ -131,13 +131,13 @@ else:
 **Via REST API:**
 ```bash
 # Search by query
-curl "http://your-pi-ip:5000/api/v3/plugins/store/search?q=hockey"
+curl "http://your-pi-ip:5000/api/v3/plugins/store/list?query=hockey"
 
 # Filter by category
-curl "http://your-pi-ip:5000/api/v3/plugins/store/search?category=sports"
+curl "http://your-pi-ip:5000/api/v3/plugins/store/list?category=sports"
 
 # Filter by tags
-curl "http://your-pi-ip:5000/api/v3/plugins/store/search?tags=nhl&tags=hockey"
+curl "http://your-pi-ip:5000/api/v3/plugins/store/list?tags=nhl&tags=hockey"
 ```
 
 **Via Python:**
@@ -351,8 +351,7 @@ All API endpoints return JSON with this structure:
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| GET | `/api/v3/plugins/store/list` | List all plugins in store |
+| GET | `/api/v3/plugins/store/list` | List plugins in store; `?query=`, `?category=`, `?tags=` search and filter |
-| GET | `/api/v3/plugins/store/search` | Search for plugins |
 | GET | `/api/v3/plugins/installed` | List installed plugins |
 | POST | `/api/v3/plugins/install` | Install from registry |
 | POST | `/api/v3/plugins/install-from-url` | Install from GitHub URL |

docs/SCROLL_PERFORMANCE.md

@@ -83,8 +83,9 @@ 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
+the ladder, sets the helper to advance that entry's whole-pixel step on every
-hold: the hold belongs to a scroll, not to a plugin's lifetime, and plugins
+presented frame (`ScrollHelper.set_pixels_per_frame`), 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:
 
@@ -102,10 +103,18 @@ 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
+`set_scrolling_state(True, frame_hold=...)` call is the mistake that matters.
-resolves, but the panel keeps presenting a new frame every refresh, so a slow
+The helper consults no clock in this mode -- it moves the fixed step once per
-snapped speed falls back to fractional pixels. Pass `snap_to_crisp=False` to
+`update_scroll_position()` call, and `SwapOnVSync` is what paces those calls --
-keep an exact requested speed and accept the artefacts.
+so without the hold the panel presents a new frame every refresh and the scroll
+runs `frame_hold` times too fast: 50 px/s (hold 2) plays at 100 px/s.
+
+Pass `snap_to_crisp=False` to keep an exact requested speed and accept the
+artefacts. The helper then paces off elapsed time instead of stepping, and the
+hold is 1.
+
+The General tab's `target_fps` ("Scroll Frame Rate") plays no part in any of
+this: frames are presented at the panel refresh divided by the hold.
 
 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
@@ -123,9 +132,12 @@ 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),
+    display_manager=self.display_manager,
     plugin_logger=self.logger,
 )
+
+# each frame of a scroll (or at least when it starts):
+self.display_manager.set_scrolling_state(True, frame_hold=settings.frame_hold)
 ```
 
 It resolves every config shape in one place, applies the speed, and returns
@@ -154,6 +166,14 @@ 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).
 
+The flip side: a `scroll_pixels_per_second` you add by hand is ignored whenever
+the plugin's config also carries the pair, which it does whenever the pair has
+a schema default. Set the speed through the pair instead.
+
+The sports scoreboards (`src.common.sports_scroll`) are the exception to all of
+the above: they read `scroll_settings.scroll_speed` per league as px/s directly,
+and their `scroll_delay` is kept for compatibility but ignored for pacing.
+
 If you are writing a plugin: do not give a deprecated key a schema default.
 
 ## What was actually wrong
@@ -198,8 +218,16 @@ 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
+A crisp speed configured through `scroll_config` no longer consults a clock at
-configured speed, so position stays proportional to real time.
+all. Once `SwapOnVSync` blocks until the panel has taken the frame, the frame
+count is a truer clock than `time.time()`, so the helper advances a fixed whole
+number of pixels per presented frame (`set_pixels_per_frame`) and the display
+manager holds each frame for `frame_hold` refreshes. Every frame moves the eye
+by the same amount.
+
+The time-based path remains only for callers that set a speed directly or pass
+`snap_to_crisp=False`. There, frame-based mode no longer steps either: it
+advances by elapsed time at `scroll_speed / scroll_delay` px/s.
 
 ## Diagnosing a juddery scroller
 
@@ -222,11 +250,17 @@ p95 10.11ms max 12.03ms min 7.98ms | stalls 0 (0.0%) skips 0 (0.0%)
 
 Reading it, on a 100 Hz panel:
 
+A healthy median is the refresh period times the scroll's frame hold: 10 ms
+for a hold of 1 (100 px/s), **20 ms for 50 px/s** (hold 2), 30 ms for 33.3 px/s.
+A 20 ms median on a 50 px/s scroll is the hold doing its job, not missed
+refreshes. The `Scroll configured:` log line gives the hold (`1px every 2
+refreshes`).
+
 | you see | it means |
 |---|---|
-| median 10 ms, p95 within ~0.5 ms of it | healthy — locked to the panel |
+| median = refresh period × hold, p95 within ~0.5 ms of it | healthy — locked to the panel |
-| p95 or max at 20/30/50 ms | frames missing refreshes — per-frame work is overrunning, or a background thread is holding the GIL |
+| p95 or max a whole refresh period or more above that median | frames missing refreshes — per-frame work is overrunning, or a background thread is holding the GIL |
-| non-zero **skips**, or a median *below* 10 ms | **duplicate frames** — the swap was skipped because the image did not change, so the frame never waited on vsync. The scroller is advancing less than one pixel per frame. |
+| non-zero **skips**, or a median *below* the expected one | **duplicate frames** — the swap was skipped because the image did not change, so the frame never waited on vsync. The scroller is advancing less than one pixel per frame, which a crisp fixed-step scroll never does; look for a plugin pacing off time or not passing the hold. |
 | non-zero **stalls** | frames past 1.5× the median, which is the measure of judder that survives averaging |
 
 `stalls` and `skips` are both counted against that window's own median, so they

docs/SPORTS_UNIFICATION.md

@@ -218,6 +218,14 @@ The one behavior the upstreamed version adds is native
 Part A threaded it through each copy by hand, and this makes that threading
 legacy compatibility rather than the mechanism.
 
+> **Superseded.** Once presentation became frame-locked (#545) the helper
+> steps a fixed whole-pixel amount per presented frame and the panel presents
+> at its own refresh, so honouring `target_fps` only turned it into a speed
+> multiplier (60 doubled a scoreboard's speed, 200 halved it). `sports_scroll`
+> no longer reads it: the crisp-speed ladder uses the panel refresh
+> (`display_manager.refresh_hz`), and speed comes from
+> `scroll_settings.scroll_speed` alone. See `docs/SCROLL_PERFORMANCE.md`.
+
 ## Phases
 
 B0–B3 are merged and shipping in core 3.2.0. Everything that remains is
@@ -464,8 +472,9 @@ After adoption plus the frozen legacy copies it was 10,610; removing the dead
 inline duplication (plugins #252) brought it to roughly 8,620. B6 would take it
 to about 3,300 including the shared core module — some 2,400 fewer than before
 this project started. **Until B6 runs, the adoption is net negative on disk**,
-and its one delivered user-visible gain is that adopted plugins honour the
+and its one delivered user-visible gain was that adopted plugins honoured the
-global `target_fps` instead of hardcoding ~100 FPS.
+global `target_fps` instead of hardcoding ~100 FPS (since withdrawn: see the
+note under the B3 design above).
 
 ### Decision: stop adopting further modules until B6 closes
 

docs/SSH_UNAVAILABLE_AFTER_INSTALL.md

@@ -158,9 +158,11 @@ This script will check:
 - Python dependencies
 - Configuration files
 - File permissions
-- Web interface availability
+- Web interface availability (`ledmatrix-web` listening on port 5000)
 - Network connectivity
 
+Once it passes, the web interface is at `http://<pi-ip>:5000`.
+
 ## Quick Reference Commands
 
 ```bash

docs/TROUBLESHOOTING.md

@@ -273,7 +273,7 @@ sudo systemctl cat ledmatrix-web | grep User
 1. **Verify file structure:**
    ```bash
    ls -l web_interface/app.py
-   ls -l web_interface/blueprints/api_v3.py
+   ls -ld web_interface/blueprints/api_v3/
    ls -l web_interface/blueprints/pages_v3.py
    ```
 
@@ -531,7 +531,7 @@ sudo systemctl cat ledmatrix-web | grep User
 
    ```bash
    # Clear the cache with the helper script
-   sudo python3 scripts/utils/clear_cache.py
+   sudo python3 scripts/utils/clear_cache.py --clear-all
 
    # Or remove files manually from the cache dir in use, e.g.:
    sudo rm -rf /var/cache/ledmatrix/*

docs/WEB_INTERFACE_GUIDE.md

@@ -102,7 +102,9 @@ Configure basic system settings:
   check are shown under the toggle, and anything other than success raises a
   banner on **Overview**.
   - *Checks first:* the code update is skipped, with the reason shown, if
-    tracked files were edited locally, the checkout has local commits, a
+    tracked files were edited locally (permission-only changes and edits under
+    `plugins/` or `plugin-repos/` don't count; the pull carries those across
+    and puts them back), the checkout has local commits, a
     rebase/merge is in progress, the branch has no upstream, less than 300 MB
     is free, or the newest version already failed once. A failed fetch is
     retried the next day.
@@ -206,11 +208,11 @@ Manage fonts for your display:
 - See font previews
 - Check font sizes and styles
 
-**Font Overrides:**
+**Font Preview:**
-- Overrides are set per display *element* (e.g. a specific score or
+- Render sample text in any TTF/OTF font at a chosen size
-  clock text element), not per plugin
+
-- Override default font choices for individual elements
+Fonts used by a plugin are chosen in that plugin's own settings tab; the
-- Preview font changes
+Fonts tab has no per-element override editor.
 
 **Delete Fonts:**
 - Remove unused fonts
@@ -327,9 +329,8 @@ The web interface is built on a REST API that you can access programmatically:
 http://your-pi-ip:5000/api/v3
 ```
 
-The API blueprint mounts at `/api/v3` (see
+The API blueprint (`web_interface/blueprints/api_v3/`) is registered at
-`web_interface/app.py:199`). All endpoints below are relative to that
+`/api/v3` in `web_interface/app.py`.
-base.
 
 **Common Endpoints:**
 - `GET /api/v3/config/main` — Get main configuration

docs/plugin-safety-harness.md

@@ -10,7 +10,8 @@ plugin without breaking a size or screen you didn't think to test.
 There is **no fixed set of supported panel sizes** — an RGB matrix build can be
 any width/height and configuration (square, rectangle, 2×2, 4×4, 8×2, long
 strips, tall stacks). Plugins are expected to read dimensions dynamically
-(`self.display_manager.matrix.width/height`) and lay themselves out
+(`self.display_manager.width/height` — not `matrix.width/height`, since
+`matrix` is `None` when hardware init fails) and lay themselves out
 accordingly, so a hardcoded coordinate or unscaled font shows up as a failure
 here.
 

integrations/mqtt_bridge/README.md

@@ -114,5 +114,10 @@ python3 integrations/mqtt_bridge/ledmatrix_mqtt_bridge.py --config integrations/
   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`.
+- Brightness writes `display.hardware.brightness` by posting
-  The display service picks it up on its next restart, not instantly.
+  `{"brightness": N}` to `/api/v3/config/main`. A JSON save changes only the
+  keys it sends, so the other display settings are left as they were. The
+  display service's config hot reload notices the change within a few seconds
+  and applies it without a restart (unless `LEDMATRIX_HOT_RELOAD=false`; while
+  a dim schedule is dimming the panel, the dim level wins until the dim period
+  ends).

plugin-repos/starlark-apps/manager.py

@@ -239,7 +239,7 @@ class StarlarkAppsPlugin(BasePlugin):
         # Calculate optimal magnification based on display size
         self.calculated_magnify = self._calculate_optimal_magnify()
         if self.calculated_magnify > 1:
-            self.logger.info(f"Display size: {self.display_manager.matrix.width}x{self.display_manager.matrix.height}, "
+            self.logger.info(f"Display size: {self.display_manager.width}x{self.display_manager.height}, "
                            f"recommended magnify: {self.calculated_magnify}")
 
         # Load installed apps
@@ -323,8 +323,8 @@ class StarlarkAppsPlugin(BasePlugin):
             Recommended magnify value (1-8)
         """
         try:
-            display_width = self.display_manager.matrix.width
+            display_width = self.display_manager.width
-            display_height = self.display_manager.matrix.height
+            display_height = self.display_manager.height
 
             # Tronbyte native resolution
             NATIVE_WIDTH = 64
@@ -362,8 +362,8 @@ class StarlarkAppsPlugin(BasePlugin):
             Dictionary with recommendation details
         """
         try:
-            display_width = self.display_manager.matrix.width
+            display_width = self.display_manager.width
-            display_height = self.display_manager.matrix.height
+            display_height = self.display_manager.height
 
             NATIVE_WIDTH = 64
             NATIVE_HEIGHT = 32
@@ -852,8 +852,8 @@ class StarlarkAppsPlugin(BasePlugin):
 
             # Scale frames if needed
             if self.config.get("scale_output", True):
-                width = self.display_manager.matrix.width
+                width = self.display_manager.width
-                height = self.display_manager.matrix.height
+                height = self.display_manager.height
 
                 # Get scaling method from config
                 scale_method_str = self.config.get("scale_method", "nearest")

scripts/debug/debug_web_manual.py

@@ -54,8 +54,13 @@ def main():
         config = config_manager.load_config()
         print("   ✅ Config loaded")
 
-        autostart = config.get('web_display_autostart', False)
+        # Same rule ledmatrix-web.service applies: only an explicit false/off
-        print(f"   🔧 web_display_autostart: {autostart}")
+        # keeps the web interface down; a missing key means on.
+        sys.path.insert(0, str(project_root / 'scripts' / 'utils'))
+        from start_web_conditionally import autostart_enabled
+        raw = config.get('web_display_autostart', '(not set, defaults to on)')
+        state = 'starts' if autostart_enabled(config) else 'will NOT start'
+        print(f"   🔧 web_display_autostart: {raw} (web interface {state})")
     except Exception as e:
         print(f"   ❌ Config check failed: {e}")
         traceback.print_exc()

scripts/dev/README.md

@@ -12,9 +12,19 @@ This directory contains scripts and utilities for development and testing.
 
 ### Plugin Development Setup
 ```bash
+# Official plugin: clones ChuckBuilds/ledmatrix-plugins (once) and links
+# its plugins/<plugin-name> into plugins/
 ./scripts/dev/dev_plugin_setup.sh link-github <plugin-name>
+
+# Plugin with its own repository
+./scripts/dev/dev_plugin_setup.sh link-github <plugin-name> <repo-url>
 ```
 
+Set `plugin_system.plugins_directory` to `plugins` so the loader finds the
+links. To use a fork or another clone location, copy
+`dev_plugins.json.example` to `dev_plugins.json`. Details:
+[docs/PLUGIN_DEVELOPMENT_GUIDE.md](../../docs/PLUGIN_DEVELOPMENT_GUIDE.md).
+
 ### Running Emulator
 ```bash
 ./scripts/dev/run_emulator.sh

scripts/dev/dev_plugin_setup.sh

@@ -10,8 +10,14 @@ PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 PLUGINS_DIR="$PROJECT_ROOT/plugins"
 CONFIG_FILE="$PROJECT_ROOT/dev_plugins.json"
 DEFAULT_DEV_DIR="$HOME/.ledmatrix-dev-plugins"
-GITHUB_USER="ChuckBuilds"
+# Official plugins live in one monorepo: <github_user>/<plugins_repo>, one
-GITHUB_PATTERN="ledmatrix-"
+# directory per plugin under plugins/. Both can be overridden in
+# dev_plugins.json (e.g. to work from a fork).
+DEFAULT_GITHUB_USER="ChuckBuilds"
+DEFAULT_PLUGINS_REPO="ledmatrix-plugins"
+GITHUB_USER="$DEFAULT_GITHUB_USER"
+PLUGINS_REPO="$DEFAULT_PLUGINS_REPO"
+PLUGINS_BRANCH=""
 
 # Colors for output
 RED='\033[0;31m'
@@ -37,18 +43,55 @@ log_error() {
     echo -e "${RED}[ERROR]${NC} $1"
 }
 
+# Print a top-level string field of a JSON file, or nothing if it is absent.
+# Uses jq when installed, else python3.
+json_field() {
+    local file="$1"
+    local key="$2"
+    if command -v jq >/dev/null 2>&1; then
+        jq -r --arg k "$key" '.[$k] // empty | select(type == "string")' "$file" 2>/dev/null || true
+    elif command -v python3 >/dev/null 2>&1; then
+        python3 - "$file" "$key" <<'PY' 2>/dev/null || true
+import json, sys
+try:
+    with open(sys.argv[1], encoding="utf-8") as f:
+        value = json.load(f).get(sys.argv[2])
+except Exception:
+    value = None
+if isinstance(value, str):
+    print(value)
+PY
+    fi
+}
+
 # Load configuration file
 load_config() {
+    DEV_PLUGINS_DIR="$DEFAULT_DEV_DIR"
     if [[ -f "$CONFIG_FILE" ]]; then
-        DEV_PLUGINS_DIR=$(jq -r '.dev_plugins_dir // "'"$DEFAULT_DEV_DIR"'"' "$CONFIG_FILE" 2>/dev/null || echo "$DEFAULT_DEV_DIR")
+        local value
+        value=$(json_field "$CONFIG_FILE" dev_plugins_dir)
+        [[ -n "$value" ]] && DEV_PLUGINS_DIR="$value"
+        value=$(json_field "$CONFIG_FILE" github_user)
+        [[ -n "$value" ]] && GITHUB_USER="$value"
+        value=$(json_field "$CONFIG_FILE" plugins_repo)
+        [[ -n "$value" ]] && PLUGINS_REPO="$value"
+        value=$(json_field "$CONFIG_FILE" plugins_branch)
+        [[ -n "$value" ]] && PLUGINS_BRANCH="$value"
+        if [[ -n "$(json_field "$CONFIG_FILE" github_pattern)" ]]; then
+            log_warn "dev_plugins.json: github_pattern is no longer used (official plugins are in the $PLUGINS_REPO monorepo)"
+        fi
+    fi
     # Expand ~ in path
     DEV_PLUGINS_DIR="${DEV_PLUGINS_DIR/#\~/$HOME}"
-    else
-        DEV_PLUGINS_DIR="$DEFAULT_DEV_DIR"
-    fi
     mkdir -p "$DEV_PLUGINS_DIR"
 }
 
+# Top level of the git checkout containing a path, or nothing.
+# A monorepo plugin is a subdirectory, so its .git is not in the plugin dir.
+git_root_of() {
+    git -C "$1" rev-parse --show-toplevel 2>/dev/null || true
+}
+
 # Validate plugin structure
 validate_plugin() {
     local plugin_path="$1"
@@ -63,7 +106,7 @@ validate_plugin() {
 get_plugin_id() {
     local plugin_path="$1"
     if [[ -f "$plugin_path/manifest.json" ]]; then
-        jq -r '.id // empty' "$plugin_path/manifest.json" 2>/dev/null || echo ""
+        json_field "$plugin_path/manifest.json" id
     fi
 }
 
@@ -176,9 +219,55 @@ clone_from_github() {
     return 0
 }
 
+# Clone a repository into DEV_PLUGINS_DIR, or update the existing clone.
+# Prints the clone's path on stdout (log output goes to stderr).
+ensure_clone() {
+    local repo_url="$1"
+    local branch="${2:-}"
+    local repo_name
+    repo_name=$(basename "$repo_url" .git)
+    local target_dir="$DEV_PLUGINS_DIR/$repo_name"
+
+    if [[ -d "$target_dir" ]]; then
+        log_info "Repository already exists at $target_dir" >&2
+        if [[ -d "$target_dir/.git" ]]; then
+            log_info "Updating repository..." >&2
+            (cd "$target_dir" && git pull --rebase) >&2 || true
+        fi
+    else
+        if ! clone_from_github "$repo_url" "$target_dir" "$branch" >&2; then
+            return 1
+        fi
+    fi
+    echo "$target_dir"
+}
+
+# Find a plugin's directory inside a monorepo clone: plugins/<name>,
+# plugins/ledmatrix-<name>, or the directory whose manifest id is <name>.
+find_monorepo_plugin() {
+    local repo_dir="$1"
+    local name="$2"
+    local candidate
+    for candidate in "$repo_dir/plugins/$name" "$repo_dir/plugins/ledmatrix-$name"; do
+        if [[ -f "$candidate/manifest.json" ]]; then
+            echo "$candidate"
+            return 0
+        fi
+    done
+    for candidate in "$repo_dir"/plugins/*/; do
+        candidate="${candidate%/}"
+        [[ -f "$candidate/manifest.json" ]] || continue
+        if [[ "$(get_plugin_id "$candidate")" == "$name" ]]; then
+            echo "$candidate"
+            return 0
+        fi
+    done
+    return 1
+}
+
 # Link plugin from GitHub
 link_github_plugin() {
-    local plugin_name="$1"
+    local plugin_name="${1:-}"
     local repo_url="${2:-}"
 
     if [[ -z "$plugin_name" ]]; then
@@ -188,38 +277,46 @@ link_github_plugin() {
 
     load_config
 
-    # Construct repo URL if not provided
+    if [[ -n "$repo_url" ]]; then
-    if [[ -z "$repo_url" ]]; then
+        # A plugin with its own repository (e.g. a third-party plugin): the
-        repo_url="https://github.com/${GITHUB_USER}/${GITHUB_PATTERN}${plugin_name}.git"
+        # repository root is the plugin.
-        log_info "Using default GitHub URL: $repo_url"
+        local target_dir
-    fi
+        if ! target_dir=$(ensure_clone "$repo_url"); then
-    
-    # Determine target directory name from URL
-    local repo_name=$(basename "$repo_url" .git)
-    local target_dir="$DEV_PLUGINS_DIR/$repo_name"
-    
-    # Check if already cloned
-    if [[ -d "$target_dir" ]]; then
-        log_info "Repository already exists at $target_dir"
-        if [[ -d "$target_dir/.git" ]]; then
-            log_info "Updating repository..."
-            (cd "$target_dir" && git pull --rebase) || true
-        fi
-    else
-        # Clone the repository
-        if ! clone_from_github "$repo_url" "$target_dir"; then
             exit 1
         fi
-    fi
-    
-    # Validate plugin structure
         if ! validate_plugin "$target_dir"; then
             log_error "Cloned repository does not appear to be a valid plugin"
             exit 1
         fi
-    
-    # Link the plugin
         link_plugin "$plugin_name" "$target_dir"
+        return
+    fi
+
+    # Official plugins: clone the monorepo once, link plugins/<dir> from it.
+    repo_url="https://github.com/${GITHUB_USER}/${PLUGINS_REPO}.git"
+    log_info "Using plugin monorepo: $repo_url"
+    local repo_dir
+    if ! repo_dir=$(ensure_clone "$repo_url" "$PLUGINS_BRANCH"); then
+        exit 1
+    fi
+
+    local plugin_dir
+    if ! plugin_dir=$(find_monorepo_plugin "$repo_dir" "$plugin_name"); then
+        log_error "No plugin named '$plugin_name' in $repo_dir/plugins"
+        log_info "Plugins are the directory names under $repo_dir/plugins, or their manifest ids"
+        exit 1
+    fi
+
+    # Link under the manifest id: that is the name the plugin loader and
+    # config.json use, and it can differ from the directory name
+    # (plugins/ledmatrix-music has id ledmatrix-music, not music).
+    local link_name
+    link_name=$(get_plugin_id "$plugin_dir")
+    [[ -n "$link_name" ]] || link_name=$(basename "$plugin_dir")
+    if [[ "$link_name" != "$plugin_name" ]]; then
+        log_info "Linking as '$link_name' (the plugin's manifest id)"
+    fi
+    link_plugin "$link_name" "$plugin_dir"
 }
 
 # Unlink a plugin
@@ -274,7 +371,7 @@ list_plugins() {
             echo "  → $target"
             
             # Check git status if it's a git repo
-            if [[ -d "$target/.git" ]]; then
+            if [[ -n "$(git_root_of "$target")" ]]; then
                 local branch=$(cd "$target" && git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
                 local status=$(cd "$target" && git status --porcelain 2>/dev/null | head -1)
                 if [[ -n "$status" ]]; then
@@ -327,7 +424,7 @@ check_status() {
             echo -e "${GREEN}✓${NC} ${BLUE}$plugin_name${NC}"
             echo "  Path: $target"
             
-            if [[ -d "$target/.git" ]]; then
+            if [[ -n "$(git_root_of "$target")" ]]; then
                 local branch=$(cd "$target" && git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
                 local remote=$(cd "$target" && git remote get-url origin 2>/dev/null || echo "no remote")
                 local commits_behind=$(cd "$target" && git rev-list --count HEAD..@{upstream} 2>/dev/null || echo "0")
@@ -360,9 +457,13 @@ check_status() {
     done
     
     echo "Summary:"
-    echo "  ${GREEN}Clean: $clean_count${NC}"
+    echo -e "  ${GREEN}Clean: $clean_count${NC}"
-    echo "  ${YELLOW}Needs attention: $dirty_count${NC}"
+    echo -e "  ${YELLOW}Needs attention: $dirty_count${NC}"
-    [[ $broken_count -gt 0 ]] && echo -e "  ${RED}Broken: $broken_count${NC}"
+    # An if, not `[[ ]] &&`: as the function's last command a false test made
+    # `status` exit 1 whenever nothing was broken.
+    if [[ $broken_count -gt 0 ]]; then
+        echo -e "  ${RED}Broken: $broken_count${NC}"
+    fi
 }
 
 # Update plugin(s)
@@ -384,20 +485,24 @@ update_plugins() {
         fi
         
         local target=$(get_symlink_target "$plugin_name")
+        local root
+        root=$(git_root_of "$target")
 
-        if [[ ! -d "$target/.git" ]]; then
+        if [[ -z "$root" ]]; then
             log_error "Plugin repository is not a git repository: $target"
             exit 1
         fi
 
-        log_info "Updating $plugin_name from $target"
+        log_info "Updating $plugin_name from $root"
-        (cd "$target" && git pull --rebase)
+        (cd "$root" && git pull --rebase)
         log_success "Updated $plugin_name"
     else
-        # Update all linked plugins
+        # Update all linked plugins. Plugins linked from the monorepo share one
+        # checkout, which is pulled once.
         log_info "Updating all linked plugins..."
         local updated=0
         local failed=0
+        local pulled_roots=" "
 
         for item in "$PLUGINS_DIR"/*; do
             [[ -e "$item" ]] || continue
@@ -408,17 +513,20 @@ update_plugins() {
 
             if is_symlink "$item"; then
                 local target=$(get_symlink_target "$name")
-                if [[ -d "$target/.git" ]]; then
+                local root
-                    log_info "Updating $name..."
+                root=$(git_root_of "$target")
-                    if (cd "$target" && git pull --rebase); then
+                [[ -n "$root" ]] || continue
-                        log_success "Updated $name"
+                [[ "$pulled_roots" == *" $root "* ]] && continue
+                pulled_roots="$pulled_roots$root "
+                log_info "Updating $root (for $name)..."
+                if (cd "$root" && git pull --rebase); then
+                    log_success "Updated $root"
                     updated=$((updated + 1))
                 else
-                        log_error "Failed to update $name"
+                    log_error "Failed to update $root"
                     failed=$((failed + 1))
                 fi
             fi
-            fi
         done
         
         echo
@@ -439,7 +547,12 @@ Commands:
     
   link-github <plugin-name> [repo-url]
       Clone and link a plugin from GitHub
-      If repo-url is not provided, uses: https://github.com/${GITHUB_USER}/${GITHUB_PATTERN}<plugin-name>.git
+      Without repo-url: clones (or updates) the official plugin monorepo,
+      https://github.com/${DEFAULT_GITHUB_USER}/${DEFAULT_PLUGINS_REPO}.git, and links its
+      plugins/<plugin-name> (or plugins/ledmatrix-<plugin-name>) under the
+      plugin's manifest id
+      With repo-url: clones a plugin that has its own repository and links
+      the repository root
     
   unlink <plugin-name>
       Remove symlink for a plugin (preserves repository)
@@ -458,14 +571,14 @@ Commands:
       Show this help message
 
 Examples:
-  # Link a local plugin
+  # Link an official plugin from the monorepo
-  $0 link music ../ledmatrix-music
+  $0 link-github football-scoreboard
 
-  # Link from GitHub (auto-detects URL)
+  # Link a plugin from a local monorepo checkout
-  $0 link-github music
+  $0 link hello-world ../ledmatrix-plugins/plugins/hello-world
 
-  # Link from GitHub with custom URL
+  # Link a third-party plugin from its own repository
-  $0 link-github stocks https://github.com/ChuckBuilds/ledmatrix-stocks.git
+  $0 link-github my-plugin https://github.com/OtherUser/ledmatrix-my-plugin.git
 
   # Check status
   $0 status
@@ -474,9 +587,14 @@ Examples:
   $0 update
 
 Configuration:
-  Create dev_plugins.json in project root to customize:
+  Copy dev_plugins.json.example to dev_plugins.json (git-ignored) to customize:
   - dev_plugins_dir: Where to clone GitHub repos (default: ~/.ledmatrix-dev-plugins)
-  - plugins: Plugin definitions (optional, for auto-discovery)
+  - github_user:     Owner of the plugin monorepo, e.g. your fork (default: ${DEFAULT_GITHUB_USER})
+  - plugins_repo:    Name of the plugin monorepo (default: ${DEFAULT_PLUGINS_REPO})
+  - plugins_branch:  Branch to clone the monorepo at (default: its default branch)
+
+  Symlinks are created in plugins/. Set plugin_system.plugins_directory to
+  "plugins" in config/config.json so the plugin loader discovers them.
 
 EOF
 }

scripts/dev_server.py

@@ -142,17 +142,18 @@ 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."""
+    """Extract default values from config_schema.json.
+
+    The same extraction a device and the plugin harness use
+    (src/plugin_system/testing/loading.py), nested defaults included.
+    """
+    from src.plugin_system.testing.loading import (
+        load_config_defaults as _load_config_defaults,
+    )
     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:
+    return _load_config_defaults(schema_path.parent)
-        schema = json.load(f)
-    defaults: Dict[str, Any] = {}
-    for key, prop in schema.get('properties', {}).items():
-        if 'default' in prop:
-            defaults[key] = prop['default']
-    return defaults
 
 
 # --------------------------------------------------------------------------
@@ -303,10 +304,13 @@ def _parse_render_request(data):
     with open(manifest_path, 'r') as f:
         manifest = json.load(f)
 
-    # Build config: schema defaults + user overrides
+    # Build config the way a device would: schema defaults under a forced
-    config = {'enabled': True}
+    # enabled, with the user's overrides deep-merged on top
-    config.update(load_config_defaults(trusted_dir))
+    from src.plugin_system.testing.loading import build_config
-    config.update(data.get('config', {}))
+    overrides = data.get('config') or {}
+    if not isinstance(overrides, dict):
+        raise ValueError('config must be a JSON object')
+    config = build_config(trusted_dir, overrides)
 
     return trusted_dir, manifest, config, data.get('mock_data', {}), data.get('skip_update', False)
 

scripts/diagnose_web_interface.sh

@@ -20,6 +20,38 @@ PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 
 cd "$PROJECT_DIR"
 
+# Report web_display_autostart the way scripts/utils/start_web_conditionally.py
+# (what ledmatrix-web.service runs) decides it: only an explicit false/off keeps
+# the web interface down; a missing key or an unreadable config starts it.
+# Prints "on <value>", "off <value>", "default" (key not set) or "unreadable".
+web_autostart_state() {
+    (cd "$1" && python3 - 2>/dev/null <<'PY'
+import json, os, sys
+sys.path.insert(0, os.path.join(os.getcwd(), "scripts", "utils"))
+try:
+    from start_web_conditionally import autostart_enabled
+except Exception:
+    def autostart_enabled(config):
+        value = config.get("web_display_autostart", True)
+        if isinstance(value, str):
+            return value.strip().lower() not in ("off", "false", "no", "0")
+        return bool(value)
+try:
+    with open(os.path.join("config", "config.json"), encoding="utf-8") as f:
+        config = json.load(f)
+except Exception:
+    config = None
+if not isinstance(config, dict):
+    print("unreadable")
+elif "web_display_autostart" not in config:
+    print("default")
+else:
+    raw = json.dumps(config["web_display_autostart"])
+    print(("on " if autostart_enabled(config) else "off ") + raw)
+PY
+    ) || echo "unknown"
+}
+
 echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
 echo -e "${BLUE}1. SERVICE STATUS${NC}"
 echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
@@ -41,14 +73,26 @@ if [ -f "$PROJECT_DIR/config/config.json" ]; then
     echo -e "${GREEN}✓ Config file found${NC}"
     
     # Check web_display_autostart setting
-    AUTOSTART=$(grep -o '"web_display_autostart"[[:space:]]*:[[:space:]]*[a-z]*' "$PROJECT_DIR/config/config.json" | grep -o '[a-z]*$')
+    AUTOSTART=$(web_autostart_state "$PROJECT_DIR")
 
-    if [ "$AUTOSTART" == "true" ]; then
+    case "$AUTOSTART" in
-        echo -e "${GREEN}✓ web_display_autostart: true${NC}"
+        on\ *)
-    else
+            echo -e "${GREEN}✓ web_display_autostart: ${AUTOSTART#on }${NC}"
-        echo -e "${YELLOW}⚠ web_display_autostart: ${AUTOSTART:-not set}${NC}"
+            ;;
-        echo -e "${YELLOW}  Web interface will not start unless this is set to true${NC}"
+        off\ *)
-    fi
+            echo -e "${YELLOW}⚠ web_display_autostart: ${AUTOSTART#off }${NC}"
+            echo -e "${YELLOW}  Web interface will not start with this value${NC}"
+            ;;
+        default)
+            echo -e "${GREEN}✓ web_display_autostart: not set (defaults to on)${NC}"
+            ;;
+        unreadable)
+            echo -e "${YELLOW}⚠ config.json could not be parsed (the web interface still starts so it can be repaired)${NC}"
+            ;;
+        *)
+            echo -e "${YELLOW}⚠ web_display_autostart: could not be evaluated (python3 unavailable?)${NC}"
+            ;;
+    esac
 else
     echo -e "${RED}✗ Config file not found at: $PROJECT_DIR/config/config.json${NC}"
 fi
@@ -63,7 +107,7 @@ declare -a REQUIRED_FILES=(
     "web_interface/app.py"
     "web_interface/start.py"
     "web_interface/requirements.txt"
-    "web_interface/blueprints/api_v3.py"
+    "web_interface/blueprints/api_v3/__init__.py"
     "web_interface/blueprints/pages_v3.py"
     "scripts/utils/start_web_conditionally.py"
 )
@@ -134,8 +178,8 @@ if ! sudo systemctl is-active --quiet ledmatrix-web; then
     echo "   sudo systemctl start ledmatrix-web"
 fi
 
-if [ "$AUTOSTART" != "true" ]; then
+if [ "${AUTOSTART%% *}" = "off" ]; then
-    echo -e "${YELLOW}→ Enable web_display_autostart in config/config.json${NC}"
+    echo -e "${YELLOW}→ Set web_display_autostart to true in config/config.json (or remove it; missing means on)${NC}"
 fi
 
 if [ "$ALL_FILES_OK" = false ]; then

scripts/diagnose_web_ui.sh

@@ -22,6 +22,38 @@ fi
 
 PROJECT_DIR="${HOME}/LEDMatrix"
 
+# Report web_display_autostart the way scripts/utils/start_web_conditionally.py
+# (what ledmatrix-web.service runs) decides it: only an explicit false/off keeps
+# the web interface down; a missing key or an unreadable config starts it.
+# Prints "on <value>", "off <value>", "default" (key not set) or "unreadable".
+web_autostart_state() {
+    (cd "$1" && python3 - 2>/dev/null <<'PY'
+import json, os, sys
+sys.path.insert(0, os.path.join(os.getcwd(), "scripts", "utils"))
+try:
+    from start_web_conditionally import autostart_enabled
+except Exception:
+    def autostart_enabled(config):
+        value = config.get("web_display_autostart", True)
+        if isinstance(value, str):
+            return value.strip().lower() not in ("off", "false", "no", "0")
+        return bool(value)
+try:
+    with open(os.path.join("config", "config.json"), encoding="utf-8") as f:
+        config = json.load(f)
+except Exception:
+    config = None
+if not isinstance(config, dict):
+    print("unreadable")
+elif "web_display_autostart" not in config:
+    print("default")
+else:
+    raw = json.dumps(config["web_display_autostart"])
+    print(("on " if autostart_enabled(config) else "off ") + raw)
+PY
+    ) || echo "unknown"
+}
+
 echo "1. Checking service status..."
 echo "------------------------------"
 if systemctl is-active --quiet ledmatrix-web 2>/dev/null || sudo systemctl is-active --quiet ledmatrix-web 2>/dev/null; then
@@ -47,16 +79,25 @@ echo "3. Checking configuration file..."
 echo "------------------------------"
 if [ -f "${PROJECT_DIR}/config/config.json" ]; then
     echo -e "${GREEN}✓ Config file exists${NC}"
-    AUTOSTART=$(grep -o '"web_display_autostart":\s*\(true\|false\)' "${PROJECT_DIR}/config/config.json" | grep -o '\(true\|false\)' || echo "not found")
+    AUTOSTART=$(web_autostart_state "$PROJECT_DIR")
-    if [ "$AUTOSTART" = "true" ]; then
+    case "$AUTOSTART" in
-        echo -e "${GREEN}✓ web_display_autostart is set to TRUE${NC}"
+        on\ *)
-    elif [ "$AUTOSTART" = "false" ]; then
+            echo -e "${GREEN}✓ web_display_autostart is ${AUTOSTART#on } (web UI starts)${NC}"
-        echo -e "${RED}✗ web_display_autostart is set to FALSE (web UI won't start!)${NC}"
+            ;;
+        off\ *)
+            echo -e "${RED}✗ web_display_autostart is ${AUTOSTART#off } (web UI won't start!)${NC}"
             echo "   Fix: Edit config.json and set 'web_display_autostart': true"
-    else
+            ;;
-        echo -e "${YELLOW}⚠ web_display_autostart setting not found (defaults to false)${NC}"
+        default)
-        echo "   Fix: Add 'web_display_autostart': true to config.json"
+            echo -e "${GREEN}✓ web_display_autostart is not set (defaults to on; web UI starts)${NC}"
-    fi
+            ;;
+        unreadable)
+            echo -e "${YELLOW}⚠ config.json could not be parsed (the web UI still starts so it can be repaired)${NC}"
+            ;;
+        *)
+            echo -e "${YELLOW}⚠ Could not evaluate web_display_autostart (python3 unavailable?)${NC}"
+            ;;
+    esac
 else
     echo -e "${RED}✗ Config file NOT FOUND at ${PROJECT_DIR}/config/config.json${NC}"
 fi
@@ -82,7 +123,7 @@ FILES_TO_CHECK=(
     "web_interface/start.py"
     "web_interface/app.py"
     "web_interface/requirements.txt"
-    "web_interface/blueprints/api_v3.py"
+    "web_interface/blueprints/api_v3/__init__.py"
     "web_interface/blueprints/pages_v3.py"
 )
 
@@ -175,7 +216,7 @@ echo "Diagnostic Summary"
 echo "=========================================="
 echo ""
 echo "Most common issues:"
-echo "  1. web_display_autostart is false or missing in config.json"
+echo "  1. web_display_autostart is set to false in config.json (a missing key means on)"
 echo "  2. Service not enabled or not started"
 echo "  3. Missing dependencies (Flask, etc.)"
 echo "  4. Import errors in web_interface/app.py"

scripts/fix_perms/README.md

@@ -7,8 +7,10 @@ install as the wrong user, after a manual file copy that didn't preserve
 ownership, or after a permissions-related error from the display or
 web service.
 
-Most of these scripts require `sudo` since they touch directories
+Most of these scripts require `sudo` since they touch directories owned
-owned by the `ledmatrix` service user or by `root`.
+by `root` (the display service's user) or by the user you installed
+LEDMatrix as (the web service's user). There is no dedicated `ledmatrix`
+system user.
 
 ## Scripts
 
@@ -16,11 +18,12 @@ owned by the `ledmatrix` service user or by `root`.
   permissions on the `assets/` tree so plugins can download and cache
   team logos, fonts, and other static content.
 
-- **`fix_cache_permissions.sh`** — Fixes permissions on every cache
+- **`fix_cache_permissions.sh`** — Creates (if missing) and fixes
-  directory the project may use (`/var/cache/ledmatrix/`,
+  permissions on `/var/cache/ledmatrix/` and `~/.ledmatrix_cache/` of the
-  `~/.cache/ledmatrix/`, `/opt/ledmatrix/cache/`, project-local
+  user running `sudo`, and creates
-  `cache/`). Also creates placeholder logo subdirectories used by the
+  `/var/cache/ledmatrix/placeholder_logos/` for the sports plugins. It does
-  sports plugins.
+  not touch the cache manager's other fallbacks (`/opt/ledmatrix/cache`,
+  `$TMPDIR/ledmatrix_cache`).
 
 - **`fix_plugin_permissions.sh`** — Fixes ownership on the plugins
   directory so both the root display service and the web service user
@@ -31,6 +34,11 @@ owned by the `ledmatrix` service user or by `root`.
   systemd journal access, and the sudoers entries the web interface
   needs to control the display service.
 
+- **`safe_pip_install.sh`** — Installs a `requirements.txt` as root
+  after checking it is the project's own or one under `plugin-repos/` or
+  `plugins/`. Used by the web interface (via sudo) to install plugin
+  dependencies where `ledmatrix.service` can import them.
+
 - **`safe_plugin_rm.sh`** — Validates that a plugin removal path is
   inside an allowed base directory before deleting it. Used by the web
   interface (via sudo) when a user clicks **Uninstall** on a plugin —

scripts/fix_perms/safe_pip_install.sh

@@ -1,6 +1,7 @@
 #!/bin/bash
 # safe_pip_install.sh — Install a requirements.txt as root after validating
-# that the resolved path is the project's own requirements.txt or a plugin's
+# that the resolved path is one of the project's own requirements files
+# (requirements.txt, web_interface/requirements.txt) or a plugin's
 # requirements.txt under plugin-repos/ or plugins/.
 #
 # This script is intended to be called via sudo from the web interface, so
@@ -25,9 +26,17 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 
 # Allowed locations (resolved, no trailing slash):
-#   - the project's own requirements.txt
+#   - the project's own requirements files. Update Code, the automatic
+#     update's health check and Install Base Requirements install both, so
+#     one missing here is refused on every device -- and the automatic
+#     updater rolls back any update that changes it.
+#     Only their folders are resolved: resolving the files too would follow
+#     a requirements.txt symlinked out of the project and allow its target.
 #   - any requirements.txt under plugin-repos/ or plugins/
-ALLOWED_EXACT="$(realpath --canonicalize-missing "$PROJECT_ROOT/requirements.txt")"
+ALLOWED_EXACT=(
+    "$(realpath --canonicalize-missing "$PROJECT_ROOT")/requirements.txt"
+    "$(realpath --canonicalize-missing "$PROJECT_ROOT/web_interface")/requirements.txt"
+)
 ALLOWED_BASES=(
     "$(realpath --canonicalize-missing "$PROJECT_ROOT/plugin-repos")"
     "$(realpath --canonicalize-missing "$PROJECT_ROOT/plugins")"
@@ -43,9 +52,13 @@ if [ "$(basename "$RESOLVED_TARGET")" != "requirements.txt" ]; then
 fi
 
 ALLOWED=false
-if [ "$RESOLVED_TARGET" = "$ALLOWED_EXACT" ]; then
+for EXACT in "${ALLOWED_EXACT[@]}"; do
+    if [ "$RESOLVED_TARGET" = "$EXACT" ]; then
         ALLOWED=true
-else
+        break
+    fi
+done
+if [ "$ALLOWED" = false ]; then
     for BASE in "${ALLOWED_BASES[@]}"; do
         if [[ "$RESOLVED_TARGET" == "$BASE/"* ]]; then
             ALLOWED=true
@@ -56,7 +69,7 @@ fi
 
 if [ "$ALLOWED" = false ]; then
     echo "DENIED: $RESOLVED_TARGET is not an allowed requirements.txt location" >&2
-    echo "Allowed: $ALLOWED_EXACT, or any requirements.txt under: ${ALLOWED_BASES[*]}" >&2
+    echo "Allowed: ${ALLOWED_EXACT[*]}, or any requirements.txt under: ${ALLOWED_BASES[*]}" >&2
     exit 2
 fi
 

scripts/install/README.md

@@ -7,14 +7,18 @@ This directory contains scripts for installing and configuring the LEDMatrix sys
 - **`one-shot-install.sh`** - Single-command installer; clones the
   repo, checks prerequisites, then runs `first_time_install.sh`.
   Invoked via `curl ... | bash` from the project root README.
-- **`install_service.sh`** - Installs the main LED Matrix display service (systemd)
+- **`install_service.sh`** - Installs, enables and starts the display
-- **`install_web_service.sh`** - Installs the web interface service (systemd)
+  service (`ledmatrix.service`), the web interface service
+  (`ledmatrix-web.service`) and the update-verify units (systemd)
+- **`install_web_service.sh`** - Installs only the web interface service
+  and the update-verify units (systemd)
 - **`install_wifi_monitor.sh`** - Installs the WiFi monitor daemon service
 - **`setup_cache.sh`** - Sets up persistent cache directory with proper permissions
 - **`configure_web_sudo.sh`** - Configures passwordless sudo access for web interface actions
-- **`configure_wifi_permissions.sh`** - Grants the `ledmatrix` user
+- **`configure_wifi_permissions.sh`** - Grants the web interface's user
-  the WiFi management permissions needed by the web interface and
+  (the user who runs the script, i.e. the one you installed LEDMatrix as;
-  the WiFi monitor service
+  there is no `ledmatrix` system user) the passwordless `nmcli` and related
+  WiFi permissions the web interface needs
 - **`migrate_config.sh`** - Migrates configuration files to new formats (if needed)
 - **`debug_install.sh`** - Diagnostic helper used when an install
   fails; collects environment info and recent logs

scripts/install/install_service.sh

@@ -3,6 +3,41 @@
 # Exit on error
 set -e
 
+usage() {
+    cat <<'USAGE'
+Usage: sudo ./scripts/install/install_service.sh [-h|--help]
+
+Installs (or reinstalls) the LEDMatrix systemd units from the templates in
+systemd/, then enables and starts them:
+  - ledmatrix.service                  main display (runs as root)
+  - ledmatrix-web.service              web interface (runs as the invoking user)
+  - ledmatrix-update-verify.service    automatic-update health check
+  - ledmatrix-update-verify.path
+
+Existing unit files in /etc/systemd/system are overwritten. The script takes
+no other options; run it with no arguments to install.
+
+Options:
+  -h, --help    Show this help and exit without changing anything.
+USAGE
+}
+
+# Parse arguments before touching anything: this script rewrites and restarts
+# services, so an unrecognised option must not fall through to a full install.
+for arg in "$@"; do
+    case "$arg" in
+        -h|--help)
+            usage
+            exit 0
+            ;;
+        *)
+            echo "ERROR: unknown option: $arg" >&2
+            usage >&2
+            exit 2
+            ;;
+    esac
+done
+
 # Get the actual user who invoked sudo
 if [ -n "$SUDO_USER" ]; then
     ACTUAL_USER="$SUDO_USER"

scripts/install_plugin_dependencies.sh

@@ -3,6 +3,8 @@
 # Use this if automatic dependency installation fails
 
 set -e
+# A failed pip must fail the `pip ... | tee` pipeline below, not be hidden by tee.
+set -o pipefail
 
 # Colors for output
 RED='\033[0;31m'
@@ -28,15 +30,50 @@ echo ""
 # Get the directory where this script is located
 SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 LEDMATRIX_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
-PLUGINS_DIR="$LEDMATRIX_DIR/plugins"
+CONFIG_FILE="$LEDMATRIX_DIR/config/config.json"
+
+# The Plugin Store installs into plugin_system.plugins_directory from
+# config.json (default plugin-repos), resolved against the project root like
+# the display and web services do. plugins/ is also scanned: it holds the
+# symlinks scripts/dev/dev_plugin_setup.sh creates.
+CONFIGURED_DIR="plugin-repos"
+if [ -f "$CONFIG_FILE" ] && command -v python3 >/dev/null 2>&1; then
+    CONFIGURED_DIR="$(LEDMATRIX_CONFIG_FILE="$CONFIG_FILE" python3 -c '
+import json, os
+try:
+    with open(os.environ["LEDMATRIX_CONFIG_FILE"], encoding="utf-8") as f:
+        value = (json.load(f).get("plugin_system") or {}).get("plugins_directory")
+except Exception:
+    value = None
+print(value if isinstance(value, str) and value.strip() else "plugin-repos")
+' 2>/dev/null)" || CONFIGURED_DIR="plugin-repos"
+    [ -n "$CONFIGURED_DIR" ] || CONFIGURED_DIR="plugin-repos"
+fi
+case "$CONFIGURED_DIR" in
+    /*) PLUGINS_DIR="$CONFIGURED_DIR" ;;
+    *)  PLUGINS_DIR="$LEDMATRIX_DIR/$CONFIGURED_DIR" ;;
+esac
+DEV_PLUGINS_DIR="$LEDMATRIX_DIR/plugins"
 
 echo "LEDMatrix directory: $LEDMATRIX_DIR"
-echo "Plugins directory: $PLUGINS_DIR"
+echo "Plugins directory: $PLUGINS_DIR (plugin_system.plugins_directory)"
+
+SCAN_DIRS=()
+PLUGINS_DIR_REAL=""
+if [ -d "$PLUGINS_DIR" ]; then
+    SCAN_DIRS+=("$PLUGINS_DIR")
+    PLUGINS_DIR_REAL="$(cd "$PLUGINS_DIR" && pwd -P)"
+fi
+if [ -d "$DEV_PLUGINS_DIR" ] && [ "$(cd "$DEV_PLUGINS_DIR" && pwd -P)" != "$PLUGINS_DIR_REAL" ]; then
+    echo "Also scanning dev plugins: $DEV_PLUGINS_DIR"
+    SCAN_DIRS+=("$DEV_PLUGINS_DIR")
+fi
 echo ""
 
-# Check if plugins directory exists
+# Check if a plugins directory exists
-if [ ! -d "$PLUGINS_DIR" ]; then
+if [ ${#SCAN_DIRS[@]} -eq 0 ]; then
     echo -e "${RED}Error: Plugins directory not found at $PLUGINS_DIR${NC}"
+    echo "Install a plugin from the Plugin Store first, or check plugin_system.plugins_directory in $CONFIG_FILE"
     exit 1
 fi
 
@@ -47,12 +84,21 @@ echo ""
 PLUGINS_FOUND=0
 PLUGINS_INSTALLED=0
 PLUGINS_FAILED=0
+SEEN_PLUGIN_PATHS=" "
 
-for plugin_dir in "$PLUGINS_DIR"/*/ ; do
+for scan_dir in "${SCAN_DIRS[@]}"; do
+for plugin_dir in "$scan_dir"/*/ ; do
     if [ -d "$plugin_dir" ]; then
         plugin_name=$(basename "$plugin_dir")
         requirements_file="$plugin_dir/requirements.txt"
 
+        # A dev symlink can point at a plugin already scanned; install it once.
+        real_plugin_dir="$(cd "$plugin_dir" && pwd -P)"
+        case "$SEEN_PLUGIN_PATHS" in
+            *" $real_plugin_dir "*) continue ;;
+        esac
+        SEEN_PLUGIN_PATHS="$SEEN_PLUGIN_PATHS$real_plugin_dir "
+
         if [ -f "$requirements_file" ]; then
             PLUGINS_FOUND=$((PLUGINS_FOUND + 1))
             echo -e "${GREEN}Found plugin: ${plugin_name}${NC}"
@@ -79,6 +125,7 @@ for plugin_dir in "$PLUGINS_DIR"/*/ ; do
         fi
     fi
 done
+done
 
 # Summary
 echo ""

scripts/scroll_speeds.py

@@ -47,52 +47,47 @@ from src.common import scroll_config  # noqa: E402
 CONFIG = Path(__file__).resolve().parent.parent / "config" / "config.json"
 
 
-def load_hardware():
+def load_config():
+    """The whole config.json, or {} when it is missing or unreadable."""
     try:
         with open(CONFIG, encoding="utf-8") as handle:
-            return (json.load(handle).get("display") or {}).get("hardware") or {}
+            config = json.load(handle)
     except (OSError, ValueError):
         return {}
+    return config if isinstance(config, dict) else {}
 
 
-def build_options(hardware, refresh_override=None):
+def hardware_of(config):
-    from rgbmatrix import RGBMatrixOptions
+    return (config.get("display") or {}).get("hardware") or {}
-
-    o = RGBMatrixOptions()
-    from src.display_geometry import (
-        DEFAULT_CHAIN_LENGTH, DEFAULT_COLS, DEFAULT_PARALLEL, DEFAULT_ROWS,
-    )
-    o.rows = int(hardware.get("rows", DEFAULT_ROWS))
-    o.cols = int(hardware.get("cols", DEFAULT_COLS))
-    o.chain_length = int(hardware.get("chain_length", DEFAULT_CHAIN_LENGTH))
-    o.parallel = int(hardware.get("parallel", DEFAULT_PARALLEL))
-    o.brightness = int(hardware.get("brightness", 80))
-    o.hardware_mapping = hardware.get("hardware_mapping", "regular")
-    o.pwm_bits = int(hardware.get("pwm_bits", 11))
-    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):
+def build_options(config, refresh_override=None):
+    """The matrix options the display service would use for this config.
+
+    Built by DisplayManager.apply_matrix_options, not a copy of it, so the
+    measurement and the demo drive the panel exactly as the service does
+    (runtime gpio_slowdown, rp1_rio, panel_type, orientation, defaults).
+    ``refresh_override`` replaces limit_refresh_rate_hz; 0 means uncapped.
+    """
+    from src.display_manager import DisplayManager, RGBMatrixOptions
+
+    options = DisplayManager.apply_matrix_options(RGBMatrixOptions(), config)
+    if refresh_override is not None:
+        options.limit_refresh_rate_hz = int(refresh_override)
+    return options
+
+
+def open_matrix(config, 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
+        from src.display_manager import RGBMatrix
-    except ImportError:
+    except ImportError as exc:
-        sys.exit("rgbmatrix is not installed on this machine")
+        sys.exit("could not load the display stack ({}); is rgbmatrix "
+                 "installed on this machine?".format(exc))
     try:
-        return RGBMatrix(options=build_options(hardware, refresh_override))
+        return RGBMatrix(options=build_options(config, refresh_override))
     except Exception as exc:  # pragma: no cover - hardware dependent
         sys.exit(
             "could not open the panel ({}).\n"
@@ -101,7 +96,7 @@ def open_matrix(hardware, refresh_override=None):
         )
 
 
-def measure_refresh(hardware, seconds=6.0):
+def measure_refresh(config, seconds=6.0):
     """Actual refresh rate, by running uncapped and timing the swaps.
 
     SwapOnVSync blocks until the panel's next refresh, so an unthrottled loop
@@ -109,7 +104,7 @@ def measure_refresh(hardware, seconds=6.0):
     chain will really give you, as opposed to whatever limit_refresh_rate_hz
     optimistically asks for.
     """
-    matrix = open_matrix(hardware, refresh_override=0)
+    matrix = open_matrix(config, refresh_override=0)
     canvas = matrix.CreateFrameCanvas()
     canvas = matrix.SwapOnVSync(canvas)  # discard the first, it includes setup
     frames = 0
@@ -122,17 +117,17 @@ def measure_refresh(hardware, seconds=6.0):
     return measured
 
 
-def demo(hardware, target, seconds):
+def demo(config, 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)
+    hz = scroll_config.refresh_hz_from_config(config)
     choice = scroll_config.solve_crisp(target, hz)
     print("asked for {:.0f} px/s -> {}".format(target, choice.describe()))
 
-    matrix = open_matrix(hardware)
+    matrix = open_matrix(config)
     canvas = matrix.CreateFrameCanvas()
     W, H = canvas.width, canvas.height
 
@@ -195,9 +190,38 @@ def print_ladder(hz, highlight=None):
         ) else ""
         print("  " + entry.describe() + mark)
     print("")
-    print("Set one in config.json as pixels per second, e.g.")
+    print_config_advice(scroll_config.solve_crisp(highlight if highlight else hz / 2, hz))
-    print('  "display_options": {{"scroll_pixels_per_second": {:.0f}}}'.format(
+
-        scroll_config.solve_crisp(highlight if highlight else hz / 2, hz).pixels_per_second))
+
+def config_advice(choice):
+    """The config that selects ``choice``, in the keys the resolver honours.
+
+    Tickers take a ``scroll_speed`` (px per step) + ``scroll_delay`` (seconds)
+    pair, and scroll_config ranks that pair ABOVE ``scroll_pixels_per_second``
+    -- deliberately, because some plugins give the flat key a schema default.
+    Many schemas default the pair too, so a flat key added by hand is usually
+    ignored. Advise the pair: pixels_per_frame every frame_hold/refresh
+    seconds is exactly the crisp speed.
+    """
+    pair = {
+        "scroll_speed": choice.pixels_per_frame,
+        "scroll_delay": round(choice.frame_hold / choice.refresh_hz, 6),
+    }
+    scoreboard = {"scroll_speed": round(choice.pixels_per_second, 2)}
+    return pair, scoreboard
+
+
+def print_config_advice(choice):
+    pair, scoreboard = config_advice(choice)
+    print("To use {:.1f} px/s, set it where the plugin keeps its scroll speed.".format(
+        choice.pixels_per_second))
+    print("Tickers take a scroll_speed (px per step) + scroll_delay (seconds) pair:")
+    print('  "display_options": {}'.format(json.dumps(pair)))
+    print("(some plugins keep the pair at the top level or under \"display\").")
+    print("The pair outranks scroll_pixels_per_second, which is ignored whenever the")
+    print("pair is present -- and schema defaults usually put it there.")
+    print("Sports scoreboards take pixels per second per league instead:")
+    print('  "scroll_settings": {}'.format(json.dumps(scoreboard)))
 
 
 def main():
@@ -214,15 +238,15 @@ def main():
                     help="highlight the entry nearest this speed")
     args = ap.parse_args()
 
-    hardware = load_hardware()
+    config = load_config()
-    configured = float(hardware.get("limit_refresh_rate_hz") or 0)
+    configured = float(hardware_of(config).get("limit_refresh_rate_hz") or 0)
 
     if args.demo is not None:
-        demo(hardware, args.demo, args.seconds)
+        demo(config, args.demo, args.seconds)
         return
 
     if args.measure:
-        measured = measure_refresh(hardware)
+        measured = measure_refresh(config)
         print("measured panel refresh: {:.1f}Hz".format(measured))
         if configured:
             print("configured limit_refresh_rate_hz: {:.0f}".format(configured))

scripts/utils/auto_update_verify.py

@@ -42,10 +42,30 @@ HEALTH_TIMEOUT_SECONDS = 180
 #: loop look healthy between attempts, so a single "is-active" proves nothing.
 STABLE_SECONDS = 45
 POLL_SECONDS = 5
+WEB_CHECK_TIMEOUT_SECONDS = 5
+SYSTEMCTL_QUERY_TIMEOUT_SECONDS = 10
+RESTART_TIMEOUT_SECONDS = 90
+GIT_TIMEOUT_SECONDS = 60
+GIT_RESET_TIMEOUT_SECONDS = 120
 PIP_TIMEOUT_SECONDS = 600
+#: All of a rollback's dependency reinstalls together. A pip that times out
+#: or fails is not retried: systemd stops this unit at TimeoutStartSec, and a
+#: rollback killed half-way leaves the update reported as still verifying.
+PIP_BUDGET_SECONDS = 600
 #: sudoers matches the exact command line, so bash is named by path, the same
-#: candidates src/common/permission_utils.install_requirements_file tries.
+#: candidates src/common/permission_utils.install_requirements_file tries...
 BASH_CANDIDATES = ('/usr/bin/bash', '/bin/bash')
+#: ...and, like it, moves to the next one only when sudo refused the command
+#: line (permission_utils.SUDO_REFUSAL_PHRASES), never after pip itself ran.
+SUDO_REFUSAL_PHRASES = ('a password is required', 'is not allowed to run', 'no tty present')
+
+#: The longest one health check can take: restart and wait, roll back
+#: (diff, reset, reinstalls), restart and wait again. A wait's last poll can
+#: start just before its deadline and run every query to its timeout.
+_WAIT_WORST_SECONDS = (HEALTH_TIMEOUT_SECONDS + STABLE_SECONDS + WEB_CHECK_TIMEOUT_SECONDS
+                       + 2 * SYSTEMCTL_QUERY_TIMEOUT_SECONDS + POLL_SECONDS)
+WORST_CASE_SECONDS = (2 * (2 * RESTART_TIMEOUT_SECONDS + _WAIT_WORST_SECONDS)
+                      + GIT_TIMEOUT_SECONDS + GIT_RESET_TIMEOUT_SECONDS + PIP_BUDGET_SECONDS)
 
 #: What a command that could not run at all reports: its callers only read
 #: these three fields, the same ones a completed subprocess has.
@@ -83,7 +103,7 @@ def write_pending(path, data):
 
 def _web_responds(url=WEB_HEALTH_URL):
     try:
-        with urllib.request.urlopen(url, timeout=5) as resp:  # nosec B310 - fixed loopback URL
+        with urllib.request.urlopen(url, timeout=WEB_CHECK_TIMEOUT_SECONDS) as resp:  # nosec B310 - fixed loopback URL
             return resp.status == 200
     except (urllib.error.URLError, OSError, ValueError):
         return False
@@ -104,7 +124,7 @@ class Verifier:
         self.web_responds = web_responds
         self.log = log or (lambda msg: print(f'[auto-update-verify] {msg}', flush=True))
 
-    def _run(self, args, timeout=60):
+    def _run(self, args, timeout=GIT_TIMEOUT_SECONDS):
         try:
             return self.run(args, cwd=str(self.project_root), capture_output=True,
                             text=True, timeout=timeout)
@@ -114,15 +134,17 @@ class Verifier:
     # -- services ---------------------------------------------------------
 
     def service_active(self, unit):
-        return self._run(['systemctl', 'is-active', unit], timeout=10).stdout.strip() == 'active'
+        return self._run(['systemctl', 'is-active', unit],
+                         timeout=SYSTEMCTL_QUERY_TIMEOUT_SECONDS).stdout.strip() == 'active'
 
     def restart_count(self, unit):
         out = self._run(['systemctl', 'show', '-p', 'NRestarts', '--value', unit],
-                        timeout=10).stdout.strip()
+                        timeout=SYSTEMCTL_QUERY_TIMEOUT_SECONDS).stdout.strip()
         return int(out) if out.isdigit() else None
 
     def restart(self, unit):
-        result = self._run(['sudo', '-n', 'systemctl', 'restart', f'{unit}.service'], timeout=90)
+        result = self._run(['sudo', '-n', 'systemctl', 'restart', f'{unit}.service'],
+                           timeout=RESTART_TIMEOUT_SECONDS)
         if result.returncode != 0:
             self.log(f'restarting {unit} failed: {(result.stderr or "").strip()}')
         return result.returncode == 0
@@ -173,16 +195,28 @@ class Verifier:
         changed = set(result.stdout.split()) if result.returncode == 0 else set(REQUIREMENT_FILES)
         return [rel for rel in REQUIREMENT_FILES if rel in changed]
 
-    def install_requirements(self, rel):
+    def install_requirements(self, rel, deadline=None):
+        """Install one requirements file through the root wrapper, by ``deadline``."""
         wrapper = self.project_root / 'scripts' / 'fix_perms' / 'safe_pip_install.sh'
         req = self.project_root / rel
         if not req.exists():
             return True
         for bash in BASH_CANDIDATES:
-            result = self._run(['sudo', '-n', bash, str(wrapper), str(req)],
+            timeout = PIP_TIMEOUT_SECONDS
-                               timeout=PIP_TIMEOUT_SECONDS)
+            if deadline is not None:
+                timeout = min(timeout, deadline - self.clock())
+                if timeout <= 0:
+                    self.log(f'no time left to reinstall {rel}')
+                    return False
+            result = self._run(['sudo', '-n', bash, str(wrapper), str(req)], timeout=timeout)
             if result.returncode == 0:
                 return True
+            # Only a refused command line is worth the next candidate. A pip
+            # that ran and failed, or timed out, would just do it again.
+            if not any(phrase in (result.stderr or '') for phrase in SUDO_REFUSAL_PHRASES):
+                # Not pip's output: it can echo an index URL's credentials.
+                self.log(f'reinstalling {rel} failed (exit {result.returncode})')
+                return False
         return False
 
     def rollback(self, pending):
@@ -191,13 +225,17 @@ class Verifier:
         if not old:
             return False, 'the commit to roll back to is unknown'
         requirements = self.changed_requirements(old, new) if new else list(REQUIREMENT_FILES)
-        # Safe to --hard: the updater refuses to run with local edits to
+        # --hard: the updater refuses to run with local edits to tracked core
-        # tracked files, so the only thing this discards is the update.
+        # files (web_interface/auto_update.local_changes), so outside the
-        result = self._run(['git', 'reset', '--hard', old], timeout=120)
+        # plugin folders the only thing this discards is the update. Edits
+        # under plugins/ and plugin-repos/, which that check leaves to the
+        # pull's --autostash, are reset along with it.
+        result = self._run(['git', 'reset', '--hard', old], timeout=GIT_RESET_TIMEOUT_SECONDS)
         if result.returncode != 0:
             return False, (f'"git reset --hard {old}" failed: '
                            f'{(result.stderr or result.stdout or "").strip()}')
-        failed = [rel for rel in requirements if not self.install_requirements(rel)]
+        deadline = self.clock() + PIP_BUDGET_SECONDS
+        failed = [rel for rel in requirements if not self.install_requirements(rel, deadline)]
         if failed:
             return True, ('reinstalling the previous dependencies from ' + ', '.join(failed)
                           + ' failed; run Install Base Requirements from the Tools tab')

scripts/verify_installation.sh

@@ -121,19 +121,24 @@ fi
 echo ""
 
 # 5. Check web interface
+# ledmatrix-web.service runs scripts/utils/start_web_conditionally.py, which
+# starts web_interface/start.py; the app binds port 5000 (web_interface/start.py).
 echo "=== Web Interface ==="
-if [ -f "$PROJECT_ROOT/web_interface_v2.py" ]; then
+WEB_PORT=5000
-    check_pass "web_interface_v2.py exists"
+for web_file in scripts/utils/start_web_conditionally.py web_interface/start.py web_interface/app.py; do
+    if [ -f "$PROJECT_ROOT/$web_file" ]; then
+        check_pass "$web_file exists"
     else
-    check_fail "web_interface_v2.py is missing"
+        check_fail "$web_file is missing"
     fi
+done
 
 # Check if web service is listening
 if systemctl is-active --quiet ledmatrix-web.service 2>/dev/null; then
-    if netstat -tuln 2>/dev/null | grep -q ":5001" || ss -tuln 2>/dev/null | grep -q ":5001"; then
+    if netstat -tuln 2>/dev/null | grep -qE ":${WEB_PORT}([^0-9]|$)" || ss -tuln 2>/dev/null | grep -qE ":${WEB_PORT}([^0-9]|$)"; then
-        check_pass "Web interface is listening on port 5001"
+        check_pass "Web interface is listening on port $WEB_PORT"
     else
-        check_warn "Web service is running but port 5001 may not be listening"
+        check_warn "Web service is running but port $WEB_PORT may not be listening"
     fi
 else
     check_warn "Web service is not running (cannot check port)"
@@ -204,7 +209,7 @@ if [ "$ALL_PASSED" = true ]; then
     echo -e "${GREEN}Installation verification PASSED${NC}"
     echo ""
     echo "Next steps:"
-    echo "1. Access the web interface at: http://$(hostname -I | awk '{print $1}'):5001"
+    echo "1. Access the web interface at: http://$(hostname -I | awk '{print $1}'):$WEB_PORT"
     echo "2. Check service status: sudo systemctl status ledmatrix.service"
     echo "3. View logs: journalctl -u ledmatrix.service -f"
     exit 0

scripts/verify_web_ui.sh

@@ -8,6 +8,10 @@ echo "Web UI Verification"
 echo "=========================================="
 echo ""
 
+# The web interface binds port 5000 (web_interface/start.py).
+WEB_PORT=5000
+PORT_PATTERN=":${WEB_PORT}([^0-9]|$)"
+
 # Colors
 GREEN='\033[0;32m'
 RED='\033[0;31m'
@@ -32,25 +36,25 @@ else
 fi
 echo ""
 
-# 2. Check if port 5001 is listening
+# 2. Check if port $WEB_PORT is listening
-echo "2. Checking if port 5001 is listening..."
+echo "2. Checking if port $WEB_PORT is listening..."
 if command -v ss >/dev/null 2>&1; then
-    if ss -tuln 2>/dev/null | grep -q ":5001"; then
+    if ss -tuln 2>/dev/null | grep -qE "$PORT_PATTERN"; then
-        echo -e "${GREEN}✓${NC} Port 5001 is listening"
+        echo -e "${GREEN}✓${NC} Port $WEB_PORT is listening"
         echo ""
-        echo "Active connections on port 5001:"
+        echo "Active connections on port $WEB_PORT:"
-        ss -tuln | grep ":5001"
+        ss -tuln | grep -E "$PORT_PATTERN"
     else
-        echo -e "${RED}✗${NC} Port 5001 is NOT listening"
+        echo -e "${RED}✗${NC} Port $WEB_PORT is NOT listening"
     fi
 elif command -v netstat >/dev/null 2>&1; then
-    if netstat -tuln 2>/dev/null | grep -q ":5001"; then
+    if netstat -tuln 2>/dev/null | grep -qE "$PORT_PATTERN"; then
-        echo -e "${GREEN}✓${NC} Port 5001 is listening"
+        echo -e "${GREEN}✓${NC} Port $WEB_PORT is listening"
         echo ""
-        echo "Active connections on port 5001:"
+        echo "Active connections on port $WEB_PORT:"
-        netstat -tuln | grep ":5001"
+        netstat -tuln | grep -E "$PORT_PATTERN"
     else
-        echo -e "${RED}✗${NC} Port 5001 is NOT listening"
+        echo -e "${RED}✗${NC} Port $WEB_PORT is NOT listening"
     fi
 else
     echo -e "${YELLOW}⚠${NC} Cannot check port (ss/netstat not available)"
@@ -59,15 +63,15 @@ echo ""
 
 # 3. Test HTTP connection
 echo "3. Testing HTTP connection..."
-if curl -s -o /dev/null -w "%{http_code}" --max-time 5 http://localhost:5001 > /dev/null 2>&1; then
+if curl -s -o /dev/null -w "%{http_code}" --max-time 5 http://localhost:$WEB_PORT > /dev/null 2>&1; then
-    HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" --max-time 5 http://localhost:5001 2>/dev/null)
+    HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" --max-time 5 http://localhost:$WEB_PORT 2>/dev/null)
     if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "302" ] || [ "$HTTP_CODE" = "301" ]; then
         echo -e "${GREEN}✓${NC} Web interface is responding (HTTP $HTTP_CODE)"
     else
         echo -e "${YELLOW}⚠${NC} Web interface responded with HTTP $HTTP_CODE"
     fi
 else
-    echo -e "${RED}✗${NC} Cannot connect to web interface on port 5001"
+    echo -e "${RED}✗${NC} Cannot connect to web interface on port $WEB_PORT"
 fi
 echo ""
 
@@ -79,7 +83,7 @@ if [ -n "$IP_ADDRESSES" ]; then
     echo ""
     echo "Access web interface at:"
     for ip in $IP_ADDRESSES; do
-        echo "  http://$ip:5001"
+        echo "  http://$ip:$WEB_PORT"
     done
 else
     echo -e "${YELLOW}⚠${NC} Could not determine IP address"
@@ -118,12 +122,12 @@ if systemctl is-active --quiet ledmatrix-web.service 2>/dev/null; then
     SERVICE_RUNNING=true
 fi
 
-if (ss -tuln 2>/dev/null | grep -q ":5001") || (netstat -tuln 2>/dev/null | grep -q ":5001"); then
+if (ss -tuln 2>/dev/null | grep -qE "$PORT_PATTERN") || (netstat -tuln 2>/dev/null | grep -qE "$PORT_PATTERN"); then
     PORT_LISTENING=true
 fi
 
-if curl -s -o /dev/null -w "%{http_code}" --max-time 5 http://localhost:5001 > /dev/null 2>&1; then
+if curl -s -o /dev/null -w "%{http_code}" --max-time 5 http://localhost:$WEB_PORT > /dev/null 2>&1; then
-    HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" --max-time 5 http://localhost:5001 2>/dev/null)
+    HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" --max-time 5 http://localhost:$WEB_PORT 2>/dev/null)
     if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "302" ] || [ "$HTTP_CODE" = "301" ]; then
         HTTP_RESPONDING=true
     fi
@@ -134,7 +138,7 @@ if [ "$SERVICE_RUNNING" = true ] && [ "$PORT_LISTENING" = true ] && [ "$HTTP_RES
     echo ""
     echo "You can access it at:"
     for ip in $IP_ADDRESSES; do
-        echo "  http://$ip:5001"
+        echo "  http://$ip:$WEB_PORT"
     done
     exit 0
 elif [ "$SERVICE_RUNNING" = false ]; then
@@ -145,7 +149,7 @@ elif [ "$SERVICE_RUNNING" = false ]; then
     echo "  sudo systemctl enable ledmatrix-web.service  # to start on boot"
     exit 1
 elif [ "$PORT_LISTENING" = false ]; then
-    echo -e "${RED}✗ Service is running but port 5001 is not listening${NC}"
+    echo -e "${RED}✗ Service is running but port $WEB_PORT is not listening${NC}"
     echo ""
     echo "Check logs for errors:"
     echo "  sudo journalctl -u ledmatrix-web.service -f"

src/background_data_service.py

@@ -25,7 +25,14 @@ from enum import Enum
 import queue
 from concurrent.futures import ThreadPoolExecutor
 from src.cache_manager import CacheManager
-from src.common.espn_dates import clamp_espn_limit, fetch_espn_date_chunks
+from src.common.espn_dates import (
+    RANGE_RETRY_SECONDS,
+    _note_range_rejected,
+    _ranges_known_rejected,
+    clamp_espn_limit,
+    fetch_espn_date_chunks,
+    parse_espn_date_range,
+)
 # Configure logging
 logger = logging.getLogger(__name__)
 
@@ -350,13 +357,32 @@ class BackgroundDataService:
             
             logger.info(f"Starting background fetch for {request.sport} {request.year}")
             
-            # Perform HTTP request with retry logic
-            response = self._make_request_with_retry(request)
-
             # ESPN stopped accepting dates=YYYYMMDD-YYYYMMDD on 2026-09-15 and
             # answers 400 for every sport. Re-ask in months and days rather
             # than let a whole season fail. See src/common/espn_dates.py.
-            if response.status_code == 400:
+            # The "ranges are rejected" memo is shared with
+            # fetch_espn_scoreboard(): once either path has seen a range
+            # rejected, the other skips the doomed range request too.
+            is_range = parse_espn_date_range(request.params.get("dates")) is not None
+            data = None
+            chunks_tried = False
+            if is_range and _ranges_known_rejected():
+                data = self._fetch_in_date_chunks(request)
+                # Every chunk failed: ask for the range itself below so the
+                # failure carries a real HTTP error, without re-spending chunks.
+                chunks_tried = data is None
+
+            if data is None:
+                # Perform HTTP request with retry logic
+                response = self._make_request_with_retry(request)
+                if is_range and response.status_code == 400 and not chunks_tried:
+                    _note_range_rejected()
+                    logger.warning(
+                        "ESPN rejected the date range %s (400); fetching it as "
+                        "month/day chunks, and fetching ranges that way for the "
+                        "next %d hours",
+                        request.params.get("dates"), RANGE_RETRY_SECONDS // 3600,
+                    )
                     data = self._fetch_in_date_chunks(request)
                     if data is None:
                         response.raise_for_status()

src/common/permission_utils.py

@@ -373,6 +373,14 @@ def sudo_remove_directory(path: Path, allowed_bases: Optional[list] = None) -> b
         return False
 
 
+#: What sudo prints when it refuses a command line outright (not in sudoers for
+#: that exact argv, or it wants a password). Only then is another bash path
+#: worth trying: after pip itself ran, a retry just repeats the failure. The
+#: automatic update's health check keeps its own copy of this list
+#: (scripts/utils/auto_update_verify.py runs without importing src/).
+SUDO_REFUSAL_PHRASES = ("a password is required", "is not allowed to run", "no tty present")
+
+
 def install_requirements_file(req_file: Path, timeout: int = 300) -> subprocess.CompletedProcess:
     """
     Install a requirements.txt file for a plugin (or the project itself).
@@ -434,10 +442,7 @@ def install_requirements_file(req_file: Path, timeout: int = 300) -> subprocess.
             # Distinguish "sudo rejected this exact command line" (worth
             # trying the next bash candidate) from "sudo ran it but pip
             # itself failed" (a real error — stop and surface it).
-            denied = any(
+            denied = any(phrase in result.stderr for phrase in SUDO_REFUSAL_PHRASES)
-                phrase in result.stderr
-                for phrase in ("a password is required", "is not allowed to run", "no tty present")
-            )
             if not denied:
                 # Deliberately don't interpolate req_file or the pip output here:
                 # this log line is scanner-visible, and a static analyzer can't

src/common/scroll_config.py

@@ -22,12 +22,27 @@ 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
+How the speed is applied
-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
+:func:`configure` snaps the requested speed to a :class:`CrispSpeed` -- a whole
-period, which puts that comparison exactly on its own threshold and makes the
+number of pixels per presented frame, with each frame held for ``frame_hold``
-step count flip on sub-millisecond jitter. Accumulating elapsed time keeps
+panel refreshes -- and puts the helper in fixed-step mode
-position proportional to real time instead.
+(``ScrollHelper.set_pixels_per_frame``). In that mode the helper consults no
+clock: every ``update_scroll_position()`` call moves exactly that many pixels.
+``SwapOnVSync`` blocks until the panel has taken each frame, so the frame count
+is the clock, and the speed on the panel is::
+
+    px/s = refresh_hz / frame_hold * pixels_per_frame
+
+That makes the hold part of the speed. The caller must pass
+``settings.frame_hold`` to ``display_manager.set_scrolling_state(True, ...)``;
+a caller that omits it is presented every refresh and scrolls ``frame_hold``
+times too fast. The refresh is the panel's (``display_manager.refresh_hz``,
+i.e. ``display.hardware.limit_refresh_rate_hz``) -- never the global
+``target_fps``, which no longer paces anything.
+
+With ``snap_to_crisp=False`` there is no fixed step: the helper is set to
+px/s and advances by elapsed time, and the hold is 1.
 """
 
 from __future__ import annotations
@@ -330,17 +345,18 @@ def configure(
 ) -> ScrollSettings:
     """Resolve the config and apply it to ``scroll_helper``.
 
-    Applied in time-based mode: see the module docstring for why frame-based
+    Frame-based mode is switched off, the (snapped) speed is set, and with
-    stepping is not used. ``hasattr`` guards keep this usable against older
+    ``snap_to_crisp`` the helper steps a fixed whole-pixel amount per presented
-    ScrollHelper builds that a plugin may be running on.
+    frame -- see the module docstring. ``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
+        ...)`` when it scrolls. The helper moves its fixed step on every call,
-        a new frame every refresh and the motion falls back to fractional
+        so without the hold each step is presented every refresh and the
-        pixels.
+        scroll runs ``frame_hold`` times faster than the resolved speed.
     :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.
@@ -357,7 +373,8 @@ def configure(
     # 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.
+    # the settings and the helper's (informational) target_fps said 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))
@@ -399,6 +416,9 @@ def configure(
     if hasattr(scroll_helper, "set_pixels_per_frame"):
         scroll_helper.set_pixels_per_frame(
             choice.pixels_per_frame if choice else None)
+    # Informational only: nothing in the helper paces off target_fps. It is
+    # still recorded because plugins read it back (ledmatrix-elections'
+    # test_scroll_pacing.py asserts it equals the crisp presentation rate).
     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"):

src/common/scroll_helper.py

@@ -22,13 +22,6 @@ from typing import Optional, Dict, Any
 from PIL import Image
 import numpy as np
 
-# Try to import scipy for sub-pixel interpolation, fallback to simpler method if not available
-try:
-    from scipy.ndimage import shift
-    HAS_SCIPY = True
-except ImportError:
-    HAS_SCIPY = False
-
 
 # How often the frame-stats line is emitted, and therefore also the ceiling
 # on a believable frame time: a scroll that renders at all cannot take this
@@ -138,21 +131,22 @@ class ScrollHelper:
         # 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
         #: 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.fixed_pixels_per_frame = None
-        self.last_step_time = 0.0  # Track last step time for frame-based throttling
+        self.last_step_time = 0.0  # Time of the last position update
 
         # Time tracking for scroll updates
         self.last_update_time: Optional[float] = None
 
-        # High FPS settings
+        #: Informational only: the presentation rate scroll_config chose
-        self.target_fps = 120  # Target 120 FPS for smooth scrolling
+        #: (panel refresh / frame hold). Nothing paces off it -- the helper
-        self.frame_time_target = 1.0 / self.target_fps
+        #: steps per call and SwapOnVSync paces the calls. Kept because
+        #: plugins and their tests read it back.
+        self.target_fps = 120
         
         # Dynamic duration settings
         self.dynamic_duration_enabled = True
@@ -288,7 +282,14 @@ class ScrollHelper:
     
     def update_scroll_position(self) -> None:
         """
-        Update scroll position with high FPS control and handle wrap-around.
+        Advance the scroll by one presented frame and handle wrap-around.
+
+        With a fixed per-frame step (set_pixels_per_frame, which
+        scroll_config.configure sets for a crisp speed) every call moves
+        exactly that many pixels and no clock is read; the caller's
+        vsync-blocking swap, held for ``frame_hold`` refreshes, sets the rate.
+        Otherwise the position advances by elapsed time at the configured
+        speed.
         """
         if not self.cached_image:
             return
@@ -461,10 +462,9 @@ class ScrollHelper:
         Linear blend between the frames at ``start_x`` and ``start_x + 1``.
 
         Implemented with numpy rather than scipy.ndimage.shift: scipy is not
-        installed on the target devices (HAS_SCIPY is False there), which is why
+        installed on the target devices, and the old scipy-based sub-pixel path
-        the pre-existing sub-pixel path was dead code — get_visible_portion never
+        was dead code -- get_visible_portion never consulted the flag. The scipy
-        consulted the flag, and the scipy fallback would not have interpolated
+        import was removed with it; installing scipy has no effect.
-        anyway.
 
         Args:
             start_x: Left column of the earlier of the two frames
@@ -830,10 +830,12 @@ class ScrollHelper:
     
     def set_scroll_speed(self, speed: float) -> None:
         """
-        Set the scroll speed.
+        Set the scroll speed, and leave fixed-step mode.
 
-        In time-based mode: pixels per second (typically 10-200)
+        In time-based mode: pixels per second (clamped to 1-500).
-        In frame-based mode: pixels per frame (typically 0.5-5 for smooth scrolling)
+        In frame-based mode: pixels per ``scroll_delay`` seconds (clamped to
+        0.1-5), still applied by elapsed time as scroll_speed / scroll_delay
+        px/s.
 
         Args:
             speed: Scroll speed (interpretation depends on frame_based_scrolling mode)
@@ -896,14 +898,19 @@ class ScrollHelper:
 
     def set_target_fps(self, fps: float) -> None:
         """
-        Set the target frames per second for scrolling.
+        Record the presentation rate, for diagnostics only.
+
+        Nothing paces off this value: with a fixed per-frame step the helper
+        advances once per call, and without one it advances by elapsed time.
+        The rate frames are shown at is the panel refresh divided by the frame
+        hold passed to ``display_manager.set_scrolling_state``. scroll_config
+        sets it to that rate so it can be read back.
 
         Args:
-            fps: Target FPS (typically 30-200, default 120)
+            fps: Frames per second (clamped to 30-200)
         """
         self.target_fps = max(30.0, min(200.0, fps))
-        self.frame_time_target = 1.0 / self.target_fps
+        self.logger.debug("Target FPS recorded: %s FPS (informational)", self.target_fps)
-        self.logger.debug(f"Target FPS set to: {self.target_fps} FPS (frame_time_target: {self.frame_time_target:.4f}s)")
     
     def set_sub_pixel_scrolling(self, enabled: bool) -> None:
         """
@@ -914,7 +921,7 @@ class ScrollHelper:
         When disabled, uses integer pixel positioning (faster but may skip pixels).
         
         Args:
-            enabled: True to enable sub-pixel scrolling (default: True)
+            enabled: True to enable sub-pixel scrolling (default: False)
         """
         self.sub_pixel_scrolling = enabled
         self.logger.debug(f"Sub-pixel scrolling {'enabled' if enabled else 'disabled'}")
@@ -923,9 +930,11 @@ class ScrollHelper:
         """
         Enable or disable frame-based scrolling.
         
-        When enabled, update_scroll_position() respects scroll_delay and moves
+        This does not step. When enabled, ``scroll_speed`` is read as pixels
-        scroll_speed pixels per step. This provides a "stepped" look similar to
+        per ``scroll_delay`` seconds (set_scroll_speed clamps it to 0.1-5), and
-        traditional tickers and can be visually smoother on LED matrices.
+        update_scroll_position() still advances by elapsed time at
+        ``scroll_speed / scroll_delay`` px/s. A fixed per-frame step set by
+        set_pixels_per_frame() takes precedence over both modes.
 
         Args:
             enabled: True to enable frame-based scrolling (default: False)
@@ -985,11 +994,7 @@ class ScrollHelper:
         # the real stall rates being measured, so the number could not be
         # trusted at all. Seed the clock and take no sample.
         if self.last_frame_time is None:
-            self.last_frame_time = current_time
+            self._restart_stats_window(current_time)
-            # Restart the window with the scroll. Otherwise the boundary is
-            # already long overdue when the second frame arrives, and the new
-            # scroll opens by reporting a window of exactly one frame.
-            self.last_fps_log_time = current_time
             return
 
         # Calculate instantaneous frame time
@@ -998,9 +1003,10 @@ class ScrollHelper:
         # A caller that scrolls without ever calling reset_scroll() never arms
         # the sentinel above, so catch the same gap by its size. Nothing that
         # renders a scroll produces a frame longer than the log interval; a
-        # sample that large is an idle period, not a frame.
+        # sample that large is an idle period, not a frame. It starts a new
+        # scroll exactly as the sentinel does, window timer included.
         if frame_time >= FPS_LOG_INTERVAL:
-            self.last_frame_time = current_time
+            self._restart_stats_window(current_time)
             return
 
         self.frame_times.append(frame_time)
@@ -1035,6 +1041,16 @@ class ScrollHelper:
         self.last_frame_time = current_time
         self.frame_count += 1
 
+    def _restart_stats_window(self, current_time: float) -> None:
+        """Seed the frame clock at the start of a scroll, taking no sample.
+
+        The window timer restarts with it. Otherwise the 5s boundary is
+        already long overdue when the next frame arrives, and the new scroll
+        opens by reporting a window of exactly one frame.
+        """
+        self.last_frame_time = current_time
+        self.last_fps_log_time = current_time
+
     def clear_cache(self) -> None:
         """
         Clear the cached scrolling image.

src/common/sports_scroll.py

@@ -18,10 +18,15 @@ Promoting the content layer would be exactly the mistake
 ``docs/SPORTS_UNIFICATION.md`` warns against — merging on the intuition that
 same-named methods are the same method. Same name, different job.
 
-The one behavior this module adds over the plugin copies is native support for
+What this module adds over the plugin copies is pacing through
-``global_config['target_fps']``: the bundled copies hardcode ~100 FPS via
+:mod:`src.common.scroll_config`, the resolver every other scroller uses: the
-``scroll_delay=0.01`` and never consult the global smooth-scrolling target. A
+configured px/s is snapped to a whole-pixel speed for the panel's refresh, the
-plugin inheriting from here gets it for free.
+helper steps a fixed number of pixels per presented frame, and each drawn frame
+publishes the frame hold to the display manager. Speed depends only on
+``scroll_speed`` and the panel refresh
+(``display.hardware.limit_refresh_rate_hz``) -- not on the global
+``target_fps``, and not on ``scroll_delay``, which is kept in the settings for
+compatibility only.
 
 Usage::
 
@@ -94,9 +99,9 @@ class SportsScrollDisplay:
         :param display_manager: the core display manager
         :param config: the plugin's configuration
         :param custom_logger: the plugin's logger, so scroll lines are attributed
-        :param global_config: the LEDMatrix global config — the source of
+        :param global_config: the LEDMatrix global config, consulted for the
-            ``target_fps``. Optional so an older caller that does not pass it
+            panel refresh when the display manager cannot report one.
-            keeps working at the config-derived pacing.
+            Optional so an older caller that does not pass it keeps working.
         """
         self.display_manager = display_manager
         self.config = config
@@ -196,21 +201,6 @@ class SportsScrollDisplay:
                 return {**settings, **override}
         return settings
 
-    def _resolve_target_fps(self) -> Optional[float]:
-        """The global smooth-scrolling FPS target, or None to keep config pacing.
-
-        Coerced before use: a malformed value in the global config must degrade
-        to the existing ``scroll_delay`` pacing, never raise on a display path.
-        """
-        raw = self.global_config.get("target_fps") or self.global_config.get(
-            "scroll_target_fps"
-        )
-        try:
-            return float(raw) if raw is not None else None
-        except (TypeError, ValueError):
-            self.logger.debug("Ignoring unusable target_fps: %r", raw)
-            return None
-
     def _coerce_float(self, value: Any, default: float) -> float:
         """A usable float from config, or ``default``.
 
@@ -246,8 +236,8 @@ class SportsScrollDisplay:
         # 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
+        #   sports_scroll: scroll_speed is px/SECOND; scroll_delay is ignored
-        #                  frame period used to reach px/frame.
+        #                  for pacing (see _resolve_pixels_per_second).
         #   scroll_config: scroll_speed is px per STEP, so px/s = speed/delay.
         #
         # Passing {"scroll_speed": 50.0, "scroll_delay": 0.01} straight through
@@ -276,8 +266,13 @@ class SportsScrollDisplay:
     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
+        ``scroll_speed`` is already px/s here, and it is the whole answer.
-        when a caller supplied px/frame instead, which the 0 case covers.
+        ``scroll_delay`` is kept in the settings for compatibility but is
+        ignored for pacing: the frame rate is the panel refresh divided by the
+        frame hold scroll_config picks, so no positive delay changes the speed.
+        The one exception is a delay of exactly 0 (below every scoreboard
+        schema's minimum), which is read as ``scroll_speed`` being px per
+        frame at ``ASSUMED_FPS_WHEN_UNPACED``.
         """
         scroll_speed = self._coerce_float(settings.get("scroll_speed"), 50.0)
         scroll_delay = self._coerce_float(settings.get("scroll_delay"), 0.01)
@@ -285,19 +280,29 @@ class SportsScrollDisplay:
             return scroll_speed * ASSUMED_FPS_WHEN_UNPACED
         return scroll_speed
 
-    def _resolve_refresh_hz(self) -> Optional[float]:
+    def _resolve_refresh_hz(self) -> float:
         """The panel refresh the crisp ladder should be computed against.
 
-        Prefers the configured hardware refresh. Falls back to the global
+        This has to be the rate frames are actually presented at, because the
-        ``target_fps``/``scroll_target_fps`` this module has always honoured:
+        helper advances a fixed number of whole pixels per presented frame and
-        under the old model that key *was* the rate frames were presented at,
+        the display manager holds each frame for ``frame_hold`` refreshes. A
-        so it is the faithful translation for anyone who set it. Returning
+        ladder built for any other rate plays back at the wrong speed: built
-        None lets scroll_config apply its own default.
+        for 60 Hz and shown on a 100 Hz panel, it runs 100/60 too fast.
+
+        So it is the display manager's ``refresh_hz`` (what the panel is
+        driven at), then ``display.hardware.limit_refresh_rate_hz`` from the
+        global config, then scroll_config's default. The global ``target_fps``
+        is deliberately NOT consulted: before frame-locked presentation it was
+        the rate frames were shown at, but now honouring it only turned the
+        General tab's "Scroll Frame Rate" into a scoreboard speed multiplier.
         """
-        hardware = scroll_config.refresh_hz_from_config(self.global_config)
+        reported = getattr(self.display_manager, "refresh_hz", None)
-        if hardware and hardware != scroll_config.DEFAULT_REFRESH_HZ:
+        # A real number only: a stub or a mock answering for anything must not
-            return hardware
+        # become the refresh rate.
-        return self._resolve_target_fps() or hardware or None
+        if (isinstance(reported, (int, float)) and not isinstance(reported, bool)
+                and reported > 0):
+            return float(reported)
+        return scroll_config.refresh_hz_from_config(self.global_config)
 
     def _scroll_frame_hold(self) -> int:
         """Refreshes to hold each frame for, from the resolved settings."""
@@ -327,11 +332,12 @@ class SportsScrollDisplay:
                 return False
 
             # Tell the core the panel is scrolling, and for how many
-            # refreshes to hold each frame. Without this the frame hold is
+            # refreshes to hold each frame. The helper advances a fixed number
-            # never applied -- so a speed the ladder made crisp still presents
+            # of whole pixels per presented frame, so without the hold a new
-            # a new frame every refresh and judders -- and, because deferred
+            # frame is presented every refresh and the scroll runs frame_hold
-            # updates only run while nothing is scrolling, core would run
+            # times too fast. And because deferred updates only run while
-            # blocking work in the middle of this scroll.
+            # nothing is scrolling, core would otherwise 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())

src/config_manager.py

@@ -29,6 +29,7 @@ import os
 import logging
 from pathlib import Path
 from typing import Dict, Any, Optional, List
+from src.core_config_keys import CORE_CONFIG_KEYS, CORE_SECRETS_KEYS
 from src.exceptions import ConfigError
 from src.logging_config import get_logger
 from src.config_manager_atomic import (
@@ -756,12 +757,13 @@ class ConfigManager:
             
             valid_set = set(valid_plugin_ids)
             
-            # Find orphaned plugins in main config
+            # Find orphaned plugins in main config. Core sections (display,
-            main_plugins = set(main_config.keys())
+            # schedule, auto_update, ...) are not plugins and never orphans.
+            main_plugins = set(main_config.keys()) - CORE_CONFIG_KEYS
             orphaned_main = main_plugins - valid_set
             
             # Find orphaned plugins in secrets config
-            secrets_plugins = set(secrets_config.keys())
+            secrets_plugins = set(secrets_config.keys()) - CORE_CONFIG_KEYS - CORE_SECRETS_KEYS
             orphaned_secrets = secrets_plugins - valid_set
             
             all_orphaned = orphaned_main | orphaned_secrets
@@ -815,8 +817,8 @@ class ConfigManager:
                 if not isinstance(plugin_config, dict):
                     continue
                 
-                # Skip non-plugin config sections
+                # Skip core config sections
-                if plugin_id in ['display', 'schedule', 'timezone', 'plugin_system']:
+                if plugin_id in CORE_CONFIG_KEYS:
                     continue
                 
                 schema = plugin_schema_manager.load_schema(plugin_id, use_cache=True)

src/core_config_keys.py

@@ -41,3 +41,13 @@ CORE_CONFIG_KEYS = frozenset({
     'vegas_excluded_plugins',
     'vegas_scroll_enabled',
 })
+
+#: Top-level keys of ``config_secrets.json`` that belong to the core rather than
+#: to a plugin: the GitHub token the Plugin Store reads, and the historical
+#: ``youtube`` section. Plugin secrets are namespaced by plugin id, so anything
+#: deciding whether a secrets section is a plugin's needs this as well as
+#: ``CORE_CONFIG_KEYS``.
+CORE_SECRETS_KEYS = frozenset({
+    'github',
+    'youtube',
+})

src/display_controller.py

@@ -2976,6 +2976,14 @@ class DisplayController:
                                        _pid: str = plugin_id, _plugin: Any = plugin_instance) -> None:
                 """Callback for plugin config changes."""
                 try:
+                    # ConfigService hands over the raw config.json section.
+                    # Prepare it as loading did (legacy booleans read as
+                    # objects, schema defaults filled in), so the plugin gets
+                    # the same shape it was constructed with.
+                    prepare = getattr(self.plugin_manager, 'prepare_plugin_config', None)
+                    prepared = prepare(_pid, new_config) if callable(prepare) else None
+                    if isinstance(prepared, dict):
+                        new_config = prepared
                     _plugin.on_config_change(new_config)
                     logger.debug("Plugin %s notified of config change", _pid)
                 except Exception as e:

src/display_geometry.py

@@ -1,17 +1,25 @@
-"""Display size from config: the one computation every caller shares.
+"""Display size from config: the one computation the size readers share.
 
 ``DisplayManager`` sizes its canvas from ``display.hardware`` plus
-``display.double_sided``. The web preview, the Starlark magnify default and
+``display.double_sided``. The web preview endpoints (``/display/current``, the
-the multi-display sync handshake used to re-derive that size themselves,
+SSE fallback), the Starlark magnify default and ``scripts/dev/vegas_audit.py``
-each with its own defaults (``chain_length`` fell back to 2 in one place and
+used to re-derive that size themselves, each with its own defaults
-1 in three others) and none of them applying double-sided mode. They now all
+(``chain_length`` fell back to 2 in one place and 1 in others) and none of
-call this module.
+them applying double-sided mode. They now call this module. (The multi-display
+sync handshake doesn't compute a size; it shares only
+``DEFAULT_CHAIN_LENGTH``.)
+
+The size includes what the rgbmatrix library's pixel mappers do to it --
+``orientation`` and ``pixel_mapper_config`` (``Rotate:90`` swaps the axes,
+``U-mapper`` folds the chain) -- because ``RGBMatrix.width``/``height``, which
+``DisplayManager`` reports on hardware, are measured after them.
 
 Kept free of hardware imports on purpose: the web interface imports it, and
 ``display_manager`` pulls in ``rgbmatrix``.
 """
 
 import logging
+import re
 from typing import Any, Dict, Mapping, Optional, Tuple
 
 logger = logging.getLogger(__name__)
@@ -22,6 +30,10 @@ DEFAULT_COLS = 64
 DEFAULT_CHAIN_LENGTH = 2
 DEFAULT_PARALLEL = 1
 
+#: ``display.hardware.orientation`` -> degrees of the ``Rotate`` mapper
+#: DisplayManager appends to ``pixel_mapper_config`` (None: no mapper).
+ORIENTATION_ROTATE_DEGREES = {'normal': None, '90': 90, '180': 180, '270': 270}
+
 
 def _display(config: Optional[Mapping[str, Any]]) -> Mapping[str, Any]:
     # A hand-edited config.json can hold anything here; treat a non-mapping
@@ -35,10 +47,128 @@ def _hardware(config: Optional[Mapping[str, Any]]) -> Mapping[str, Any]:
     return hw if isinstance(hw, Mapping) else {}
 
 
+def compose_pixel_mapper_config(hardware: Mapping[str, Any]) -> str:
+    """The ``pixel_mapper_config`` DisplayManager hands the library.
+
+    ``pixel_mapper_config`` stays a free-form advanced field (e.g. "U-mapper"
+    for chain layouts); ``orientation`` is the user-facing mounting rotation,
+    appended as a trailing ``Rotate:<deg>`` mapper rather than overwriting it.
+    """
+    base = hardware.get('pixel_mapper_config') or ''
+    base = base.strip() if isinstance(base, str) else ''
+    degrees = ORIENTATION_ROTATE_DEGREES.get(hardware.get('orientation', 'normal'))
+    if degrees is None:
+        return base
+    rotate = f'Rotate:{degrees}'
+    return f'{base};{rotate}' if base else rotate
+
+
+def _c_div(a: int, b: int) -> int:
+    """C integer division (truncates toward zero)."""
+    q = abs(a) // abs(b)
+    return q if (a >= 0) == (b >= 0) else -q
+
+
+def _c_strtol(text: str) -> Tuple[int, str]:
+    """strtol(text, &end, 10): the parsed value (0 if none) and the rest."""
+    match = re.match(r'\s*([+-]?\d+)', text)
+    if not match:
+        return 0, text
+    return int(match.group(1)), text[match.end():]
+
+
+def _remap_size(param: Optional[str], width: int, height: int,
+                chain: int, parallel: int) -> Optional[Tuple[int, int]]:
+    """RemapMapper::SetParameters and GetSizeMapping (lib/pixel-mapper.cc)."""
+    if not param:
+        return None
+    new_w, rest = _c_strtol(param)
+    if not rest.startswith(','):
+        return None
+    new_h, rest = _c_strtol(rest[1:])
+    if not rest.startswith('|'):
+        return None
+    rest = rest[1:]
+    tiles = []
+    while rest:
+        x, rest = _c_strtol(rest)
+        if not rest.startswith(','):
+            return None
+        y, rest = _c_strtol(rest[1:])
+        if not rest or rest[0].lower() not in 'neswx':
+            return None
+        tiles.append((x, y, rest[0].lower()))
+        rest = rest[1:]
+        if rest.startswith('|'):
+            rest = rest[1:]
+        elif rest:
+            return None
+    if len(tiles) != chain * parallel:
+        return None
+    panel_w, panel_h = _c_div(width, chain), _c_div(height, parallel)
+    for x, y, kind in tiles:
+        if kind == 'x':
+            continue
+        # MapTile::MapToVisible of the panel's (0, 0) and far corner.
+        x0, y0, x1, y1 = {
+            'n': (x, y, x + panel_w - 1, y + panel_h - 1),
+            'w': (x, y + panel_w - 1, x + panel_h - 1, y),
+            's': (x + panel_w - 1, y + panel_h - 1, x, y),
+            'e': (x + panel_h - 1, y, x, y + panel_w - 1),
+        }[kind]
+        if x1 < 0 or x0 >= new_w or y1 < 0 or y0 >= new_h:
+            return None
+    return new_w, new_h
+
+
+def apply_pixel_mappers(width: int, height: int, mapper_config: str,
+                        chain: int, parallel: int) -> Tuple[int, int]:
+    """The canvas size after the library applies ``mapper_config``.
+
+    Mirrors ``RGBMatrix::Impl::ApplyNamedPixelMappers`` and each built-in
+    mapper's ``SetParameters``/``GetSizeMapping`` in the pinned
+    ``lib/pixel-mapper.cc``: mappers apply left to right, and one the library
+    doesn't know or can't configure is skipped and leaves the size alone.
+    ``multiplexing`` isn't modelled: its mappers give back the configured
+    size for the panel sizes they are made for.
+    """
+    for entry in (mapper_config or '').split(';'):
+        name, colon, param = entry.partition(':')
+        name = name.lower()
+        param = param if colon else None
+        if name == 'rotate':
+            if not param:
+                continue
+            angle, rest = _c_strtol(param)
+            if rest or angle % 90:
+                continue
+            if angle % 180:
+                width, height = height, width
+        elif name == 'u-mapper':
+            if chain < 2 or chain % 2 or height % parallel:
+                continue
+            width, height = _c_div(width, 64) * 32, 2 * height
+        elif name == 'v-mapper':
+            width, height = (_c_div(width * parallel, chain),
+                             _c_div(height * chain, parallel))
+        elif name == 'stacktorow':
+            if param and any(c not in 'ZzFf, ' for c in param):
+                continue
+            width, height = width * parallel, _c_div(height, parallel)
+        elif name == 'remap':
+            size = _remap_size(param, width, height, chain, parallel)
+            if size is not None:
+                width, height = size
+        # "mirror" keeps the size; the library skips names it doesn't know.
+    return width, height
+
+
 def physical_size(config: Optional[Mapping[str, Any]]) -> Tuple[int, int]:
     """Width and height of the whole panel chain, in pixels.
 
-    ``cols * chain_length`` by ``rows * parallel``. Raises ``ValueError`` or
+    ``cols * chain_length`` by ``rows * parallel``, then through the pixel
+    mappers ``orientation`` and ``pixel_mapper_config`` set up -- what
+    ``RGBMatrix.width``/``height`` report. Raises ``ValueError`` or
     ``TypeError`` on a non-numeric value, as ``DisplayManager`` does; callers
     decide their own fallback.
 
@@ -54,7 +184,11 @@ def physical_size(config: Optional[Mapping[str, Any]]) -> Tuple[int, int]:
         parallel = int(hw.get('parallel', DEFAULT_PARALLEL))
     except OverflowError as e:
         raise ValueError(f"display.hardware size is not finite: {e}") from e
-    return max(1, cols * chain_length), max(1, rows * parallel)
+    width, height = max(1, cols * chain_length), max(1, rows * parallel)
+    if chain_length >= 1 and parallel >= 1:
+        width, height = apply_pixel_mappers(
+            width, height, compose_pixel_mapper_config(hw), chain_length, parallel)
+    return max(1, width), max(1, height)
 
 
 def resolve_double_sided(physical_width: int, physical_height: int,

src/display_manager.py

@@ -37,9 +37,11 @@ from PIL import Image, ImageDraw, ImageFont
 from src.common.font_layout import crisp_size, load_truetype, resolve_asset_path
 from src.display_geometry import (
     DEFAULT_CHAIN_LENGTH, DEFAULT_COLS, DEFAULT_PARALLEL, DEFAULT_ROWS,
-    physical_size, resolve_double_sided,
+    ORIENTATION_ROTATE_DEGREES, compose_pixel_mapper_config, physical_size,
+    resolve_double_sided,
 )
-from src.pi5_matrix_support import is_raspberry_pi_5, pi5_unsupported_settings
+from src.matrix_support import MatrixSettingsRefused, library_refusals, refusal_message
+from src.pi5_matrix_support import is_raspberry_pi_5
 import threading
 import time
 from collections import OrderedDict
@@ -91,9 +93,11 @@ class _LogicalMatrix:
     """Proxy that reports a logical (per-screen) size for a physical matrix.
 
     In double-sided mode the physical panel chain shows N identical copies of a
-    smaller logical screen. Plugins size themselves from ``matrix.width`` /
+    smaller logical screen. Plugins size themselves from
-    ``matrix.height`` (the documented convention, used at 30+ call sites), so
+    ``display_manager.width`` / ``height`` (the documented convention), which
-    this proxy reports the logical dimensions while delegating every real
+    defer to ``matrix.width`` / ``matrix.height`` -- and many older plugins read
+    ``matrix.width`` directly -- so this proxy reports the logical dimensions
+    while delegating every real
     operation — ``CreateFrameCanvas``, ``SwapOnVSync``, ``brightness``,
     ``Clear`` and so on — to the underlying physical matrix. The duplication
     itself happens once per frame in :meth:`DisplayManager.update_display`.
@@ -247,28 +251,41 @@ class DisplayManager:
         # Calendar manager is now initialized by DisplayController
         
     # Orientation setting -> rpi-rgb-led-matrix "Rotate:<deg>" pixel-mapper suffix.
-    # "normal" needs no suffix since 0 degrees is the identity transform.
+    _ORIENTATION_ROTATE_DEGREES = ORIENTATION_ROTATE_DEGREES
-    _ORIENTATION_ROTATE_DEGREES = {'normal': None, '90': 90, '180': 180, '270': 270}
 
     def _build_pixel_mapper_config(self, hardware_config: dict) -> str:
-        """Compose the raw pixel_mapper_config string with the orientation setting.
+        """Compose pixel_mapper_config with the orientation setting.
 
-        `pixel_mapper_config` stays available as a free-form advanced field (e.g.
+        See :func:`src.display_geometry.compose_pixel_mapper_config`, which the
-        for "U-mapper" chain layouts); `orientation` is the user-facing dropdown
+        web preview shares so it sizes the canvas the same way.
-        for physical mounting (e.g. panels mounted upside down) and is appended as
-        a "Rotate:<deg>" mapper rather than overwriting any existing config.
         """
-        base_mapper = (hardware_config.get('pixel_mapper_config') or '').strip()
+        return compose_pixel_mapper_config(hardware_config)
-        orientation = hardware_config.get('orientation', 'normal')
+
-        degrees = self._ORIENTATION_ROTATE_DEGREES.get(orientation)
+    @staticmethod
-        if degrees is None:
+    def _fallback_advice(cause: str, error: Exception) -> str:
-            return base_mapper
+        """What to do about a failed matrix init, for the log.
-        rotate_mapper = f'Rotate:{degrees}'
+
-        return f'{base_mapper};{rotate_mapper}' if base_mapper else rotate_mapper
+        Only a library failure gets the rebuild hint: advice about the build
+        or GPIO timing sends someone whose settings were refused the wrong way.
+        """
+        if cause == "settings":
+            return (f"{error} Change these in the web interface's Display tab "
+                    "(or display.hardware / display.runtime in config.json) "
+                    "and restart the display service.")
+        if cause == "forced":
+            return f"Error: {error}."
+        advice = (f"Error: {error}. If the rgbmatrix library printed a message "
+                  "just before this, it names the problem.")
+        if is_raspberry_pi_5():
+            advice += (" On a Raspberry Pi 5, an mmap error means the library was "
+                       "built without Pi 5 support: sudo RPI_RGB_FORCE_REBUILD=1 "
+                       "./first_time_install.sh")
+        return advice
 
     def _setup_matrix(self):
         """Initialize the RGB matrix with configuration settings."""
         _init_error_str = None
+        _init_cause = None
         try:
             # Allow callers (e.g., web UI) to force non-hardware fallback mode
             if getattr(self, '_force_fallback', False):
@@ -279,62 +296,24 @@ class DisplayManager:
             hardware_config = self.config.get('display', {}).get('hardware', {})
             runtime_config = self.config.get('display', {}).get('runtime', {})
 
-            # Basic hardware settings
+            # The library has no error path for many settings it can't use:
-            options.rows = hardware_config.get('rows', DEFAULT_ROWS)
+            # it returns no matrix (which the binding doesn't check, so the
-            options.cols = hardware_config.get('cols', DEFAULT_COLS)
+            # process crashes on its next call) or calls abort(), and systemd
-            options.chain_length = hardware_config.get('chain_length', DEFAULT_CHAIN_LENGTH)
+            # restarts the service into the same crash. Refuse those first so
-            options.parallel = hardware_config.get('parallel', DEFAULT_PARALLEL)
+            # they become a logged, reported fallback (src/matrix_support.py).
-            options.hardware_mapping = hardware_config.get('hardware_mapping', 'adafruit-hat-pwm')
+            refused = refusal_message(library_refusals(
+                hardware_config, runtime_config, pi5=is_raspberry_pi_5()))
+            if refused:
+                if os.getenv("EMULATOR", "false") != "true":
+                    raise MatrixSettingsRefused(refused)
+                logger.warning("Emulator mode: continuing, but on a real panel the display would not start. %s", refused)
             
-            # Performance and stability settings
+            # Every option comes from display.hardware / display.runtime, in
-            options.brightness = hardware_config.get('brightness', 90)
+            # one place that scripts/scroll_speeds.py shares.
-            options.pwm_bits = hardware_config.get('pwm_bits', 10)
+            self.apply_matrix_options(options, self.config)
-            options.pwm_lsb_nanoseconds = hardware_config.get('pwm_lsb_nanoseconds', 150)
-            options.led_rgb_sequence = hardware_config.get('led_rgb_sequence', 'RGB')
-            options.pixel_mapper_config = self._build_pixel_mapper_config(hardware_config)
-            options.row_address_type = hardware_config.get('row_address_type', 0)
-            options.multiplexing = hardware_config.get('multiplexing', 0)
-            options.panel_type = hardware_config.get('panel_type', '')
-            options.disable_hardware_pulsing = hardware_config.get('disable_hardware_pulsing', False)
-            options.show_refresh_rate = hardware_config.get('show_refresh_rate', False)
-            options.limit_refresh_rate_hz = hardware_config.get('limit_refresh_rate_hz', 90)
-            options.gpio_slowdown = runtime_config.get('gpio_slowdown', 3)
-            
-            # Disable internal privilege dropping - we manage this via systemd or remain root
-            # This prevents the library from dropping to 'daemon' user which breaks file permissions
-            options.drop_privileges = False
-            
-            # Additional settings from config
-            if 'scan_mode' in hardware_config:
-                options.scan_mode = hardware_config.get('scan_mode')
-            if 'pwm_dither_bits' in hardware_config:
-                options.pwm_dither_bits = hardware_config.get('pwm_dither_bits')
-            if 'inverse_colors' in hardware_config:
-                options.inverse_colors = hardware_config.get('inverse_colors')
-            # Pi 5 only: 0=PIO/RP1 coprocessor (default, less CPU),
-            # 1=RIO/Registered IO (faster; gpio_slowdown effect is inverted in this mode)
-            if 'rp1_rio' in runtime_config:
-                if hasattr(options, 'rp1_rio'):
-                    options.rp1_rio = runtime_config.get('rp1_rio')
-                else:
-                    logger.warning(
-                        "rp1_rio is set in config but the installed rgbmatrix library does "
-                        "not support it — the library was likely built without Pi 5 RP1 "
-                        "support (mmap to 0x3f000000 instead of RP1 chip). "
-                        "Fix: sudo RPI_RGB_FORCE_REBUILD=1 ./first_time_install.sh"
-                    )
             
             logger.info(f"Initializing RGB Matrix with settings: rows={options.rows}, cols={options.cols}, chain_length={options.chain_length}, parallel={options.parallel}, hardware_mapping={options.hardware_mapping}")
             
-            # On a Pi 5 the library hands back no matrix for settings its RP1
-            # path can't drive, and the binding doesn't check -- the process
-            # would crash on its next call instead of reaching the fallback
-            # below. Raise first so it is a logged, reported init failure.
-            if os.getenv("EMULATOR", "false") != "true" and is_raspberry_pi_5():
-                unsupported = pi5_unsupported_settings(hardware_config)
-                if unsupported:
-                    raise RuntimeError(unsupported)
-
             # Initialize the matrix
             self.matrix = RGBMatrix(options=options)
             logger.info("RGB Matrix initialized successfully")
@@ -379,6 +358,11 @@ class DisplayManager:
             
         except Exception as e:
             _init_error_str = str(e)
+            if isinstance(e, MatrixSettingsRefused):
+                _init_cause = "settings"
+                logger.error("Failed to initialize RGB Matrix: %s", e)
+            else:
+                _init_cause = "forced" if getattr(self, '_force_fallback', False) else "library"
                 logger.error(f"Failed to initialize RGB Matrix: {e}", exc_info=True)
             # Create a fallback image for web preview using configured dimensions when available
             self.matrix = None
@@ -406,15 +390,18 @@ class DisplayManager:
                 # Best-effort; ignore drawing errors in fallback
                 pass
             logger.error(
-                f"Matrix initialization failed — running in fallback/simulation mode "
+                "Matrix initialization failed — running in fallback/simulation mode "
-                f"(size {fallback_width}x{fallback_height}). Error: {e}. "
+                "(size %dx%d). %s",
-                "On Raspberry Pi 5: ensure rpi-rgb-led-matrix was built from the latest "
+                fallback_width, fallback_height, self._fallback_advice(_init_cause, e))
-                "submodule (re-run first_time_install.sh). gpio_slowdown of 2–3 is typical for Pi 5 PIO mode."
-            )
             # Do not raise here; allow fallback mode so web preview and non-hardware environments work
 
         # Write hardware status file so the web UI can surface init failures
-        _hw_status = {"ok": self.matrix is not None, "error": _init_error_str}
+        # cause: None when ok; "settings" when LEDMatrix refused the config
+        # (fix the named settings), "library" when the library itself failed,
+        # "forced" for a caller-requested fallback. The Display tab keys its
+        # advice on it.
+        _hw_status = {"ok": self.matrix is not None, "error": _init_error_str,
+                      "cause": None if self.matrix is not None else _init_cause}
         _status_path = "/tmp/led_matrix_hw_status.json"  # nosec B108
         try:
             if os.path.islink(_status_path):
@@ -682,8 +669,10 @@ class DisplayManager:
     def render_size(self, width: int, height: Optional[int] = None):
         """Temporarily present a smaller logical canvas to plugins.
 
-        Plugins lay out against ``display_manager.matrix.width`` (and the
+        Plugins lay out against the ``display_manager.width``/``height``
-        ``width``/``height`` properties, which defer to it), so the only way to
+        properties (which defer to ``matrix.width`` when hardware is present,
+        and to the canvas when it is not; some older plugins read
+        ``matrix.width`` directly), so the only way to
         get a *narrower layout* rather than a cropped one is to tell the plugin
         the screen is narrower while it renders. Trimming after the fact cannot
         fix a forecast spread across five columns or a progress bar drawn at
@@ -1370,6 +1359,68 @@ class DisplayManager:
         
         return dt.strftime(f"%b %-d{suffix}") 
 
+    @classmethod
+    def apply_matrix_options(cls, options, config: Dict[str, Any]):
+        """Fill ``options`` (an ``RGBMatrixOptions``) from the LEDMatrix config.
+
+        This is exactly what the display service drives the panel with, so a
+        tool that opens the matrix itself (``scripts/scroll_speeds.py``) gets
+        the same panel -- same runtime ``gpio_slowdown``, ``rp1_rio``,
+        ``panel_type``, orientation and defaults -- rather than a private copy
+        that drifts. Does not open the matrix. Returns ``options``.
+        """
+        display = config.get('display', {}) if isinstance(config, dict) else {}
+        hardware_config = display.get('hardware', {})
+        runtime_config = display.get('runtime', {})
+
+        # Basic hardware settings
+        options.rows = hardware_config.get('rows', DEFAULT_ROWS)
+        options.cols = hardware_config.get('cols', DEFAULT_COLS)
+        options.chain_length = hardware_config.get('chain_length', DEFAULT_CHAIN_LENGTH)
+        options.parallel = hardware_config.get('parallel', DEFAULT_PARALLEL)
+        options.hardware_mapping = hardware_config.get('hardware_mapping', 'adafruit-hat-pwm')
+
+        # Performance and stability settings
+        options.brightness = hardware_config.get('brightness', 90)
+        options.pwm_bits = hardware_config.get('pwm_bits', 10)
+        options.pwm_lsb_nanoseconds = hardware_config.get('pwm_lsb_nanoseconds', 150)
+        options.led_rgb_sequence = hardware_config.get('led_rgb_sequence', 'RGB')
+        # _build_pixel_mapper_config reads only class attributes, so the class
+        # stands in for an instance here.
+        options.pixel_mapper_config = cls._build_pixel_mapper_config(cls, hardware_config)
+        options.row_address_type = hardware_config.get('row_address_type', 0)
+        options.multiplexing = hardware_config.get('multiplexing', 0)
+        options.panel_type = hardware_config.get('panel_type', '')
+        options.disable_hardware_pulsing = hardware_config.get('disable_hardware_pulsing', False)
+        options.show_refresh_rate = hardware_config.get('show_refresh_rate', False)
+        options.limit_refresh_rate_hz = hardware_config.get('limit_refresh_rate_hz', 90)
+        options.gpio_slowdown = runtime_config.get('gpio_slowdown', 3)
+
+        # Disable internal privilege dropping - we manage this via systemd or remain root
+        # This prevents the library from dropping to 'daemon' user which breaks file permissions
+        options.drop_privileges = False
+
+        # Additional settings from config
+        if 'scan_mode' in hardware_config:
+            options.scan_mode = hardware_config.get('scan_mode')
+        if 'pwm_dither_bits' in hardware_config:
+            options.pwm_dither_bits = hardware_config.get('pwm_dither_bits')
+        if 'inverse_colors' in hardware_config:
+            options.inverse_colors = hardware_config.get('inverse_colors')
+        # Pi 5 only: 0=PIO/RP1 coprocessor (default, less CPU),
+        # 1=RIO/Registered IO (faster; gpio_slowdown effect is inverted in this mode)
+        if 'rp1_rio' in runtime_config:
+            if hasattr(options, 'rp1_rio'):
+                options.rp1_rio = runtime_config.get('rp1_rio')
+            else:
+                logger.warning(
+                    "rp1_rio is set in config but the installed rgbmatrix library does "
+                    "not support it — the library was likely built without Pi 5 RP1 "
+                    "support (mmap to 0x3f000000 instead of RP1 chip). "
+                    "Fix: sudo RPI_RGB_FORCE_REBUILD=1 ./first_time_install.sh"
+                )
+        return options
+
     @property
     def refresh_hz(self) -> float:
         """The panel's refresh rate in Hz, from the hardware config.
@@ -1415,6 +1466,12 @@ class DisplayManager:
         pixel every second refresh, which is how a scroll runs at half the
         refresh rate without fractional pixel positions.
 
+        The hold is part of the scroll's speed. A ScrollHelper configured by
+        ``scroll_config.configure()`` advances a fixed whole-pixel step per
+        presented frame and reads no clock, so pass the returned
+        ``settings.frame_hold`` here: a scroll that leaves it at 1 is
+        presented every refresh and runs ``frame_hold`` times too fast.
+
         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

src/matrix_support.py

@@ -0,0 +1,205 @@
+"""Display settings the pinned rgbmatrix library refuses, on every board.
+
+The library does not raise on a setting it can't use. For most it returns no
+matrix -- ``RGBMatrix::CreateFromOptions()`` gives back NULL when
+``Options::Validate()`` (``lib/options-initialize.cc``) or its GPIO slowdown
+check (``lib/led-matrix.cc``) fails -- and the Python binding stores that
+pointer without checking, so the display process crashes on its first call
+into the matrix. For two it calls ``abort()``: an unknown hardware mapping
+name, and more parallel chains than the mapping has outputs
+(``Framebuffer::InitHardwareMapping()`` and the ``Framebuffer`` constructor in
+``lib/framebuffer.cc``). Either way systemd restarts the service into the same
+crash, and no fallback or hardware status is ever reported.
+
+``DisplayManager`` runs :func:`library_refusals` before creating the matrix,
+turning those crashes into a logged error and the usual fallback mode. The
+config API uses the same rules to refuse the settings up front, and
+:data:`INT_SETTING_LIMITS` is the one place the numeric ranges live.
+
+Pi 5-only limits come from :mod:`src.pi5_matrix_support` and are added when
+``pi5=True``.
+
+**Re-check this when the submodule is bumped** (pinned at 1ee4f76): the
+ranges in ``Options::Validate()``, the mapping table in
+``lib/hardware-mapping.c`` and the setter types in
+``bindings/python/rgbmatrix/core.pyx``. A stale rule here blocks settings a
+new library accepts; a missing one lets the display service crash-loop.
+"""
+
+from typing import Any, Dict, List, Mapping, NamedTuple, Optional, Tuple
+
+from src.pi5_matrix_support import pi5_unsupported_settings
+
+#: The binding's setters for rows, chain_length, parallel and the other small
+#: integers are declared ``uint8_t`` (``core.pyx``), cols ``uint32_t``, and
+#: limit_refresh_rate_hz lands in a C ``int``; a larger value raises
+#: ``OverflowError`` before the library sees it.
+UINT8_MAX = 255
+UINT32_MAX = 2 ** 32 - 1
+INT32_MAX = 2 ** 31 - 1
+
+#: field -> (config section, lowest, highest, must be even). The library's own
+#: ranges where it has one, otherwise the binding's integer type.
+INT_SETTING_LIMITS: Dict[str, Tuple[str, int, int, bool]] = {
+    'rows': ('hardware', 8, 64, True),
+    'cols': ('hardware', 16, UINT32_MAX, False),
+    'chain_length': ('hardware', 1, UINT8_MAX, False),
+    # 3 is the most any mapping in the default build has (see MAPPING_OUTPUTS).
+    'parallel': ('hardware', 1, 3, False),
+    'brightness': ('hardware', 1, 100, False),
+    'scan_mode': ('hardware', 0, 1, False),
+    'pwm_bits': ('hardware', 1, 11, False),
+    'pwm_dither_bits': ('hardware', 0, 2, False),
+    'pwm_lsb_nanoseconds': ('hardware', 50, 3000, False),
+    # 0 = no cap; the library has no upper bound.
+    'limit_refresh_rate_hz': ('hardware', 0, INT32_MAX, False),
+    'row_address_type': ('hardware', 0, 5, False),
+    # 22 registered multiplexers (lib/multiplex-mappers.cc).
+    'multiplexing': ('hardware', 0, 22, False),
+    'gpio_slowdown': ('runtime', 0, 10, False),
+    'rp1_rio': ('runtime', 0, 1, False),
+}
+
+#: Hardware mapping name -> parallel chains it has outputs for, as
+#: ``lib/hardware-mapping.c`` defines them. ``compute-module`` exists only when
+#: the library is built with ENABLE_WIDE_GPIO_COMPUTE_MODULE, which the pinned
+#: Makefile leaves commented out and the installer does not set, so the library
+#: LEDMatrix installs aborts on it like any other unknown name.
+MAPPING_OUTPUTS: Dict[str, int] = {
+    'regular': 3,
+    'adafruit-hat': 1,
+    'adafruit-hat-pwm': 1,
+    'regular-pi1': 1,
+    'classic': 3,
+    'classic-pi1': 1,
+}
+
+#: What DisplayManager passes when a key is missing from display.hardware /
+#: display.runtime. Config migration normally fills these from
+#: config/config.template.json first, so they rarely apply.
+DISPLAY_MANAGER_DEFAULTS: Dict[str, Any] = {
+    'rows': 32, 'cols': 64, 'chain_length': 2, 'parallel': 1,
+    'hardware_mapping': 'adafruit-hat-pwm', 'brightness': 90, 'pwm_bits': 10,
+    'pwm_lsb_nanoseconds': 150, 'led_rgb_sequence': 'RGB',
+    'row_address_type': 0, 'multiplexing': 0, 'limit_refresh_rate_hz': 90,
+    'gpio_slowdown': 3,
+}
+
+
+class Refusal(NamedTuple):
+    """One reason the library can't start with a config.
+
+    ``fields`` are the settings involved; the config API reports a refusal
+    only when the request sets one of them, so a problem already stored
+    doesn't block an unrelated save.
+    """
+    fields: Tuple[str, ...]
+    message: str
+    #: A Raspberry Pi 5-only limit, whose message is already a full sentence.
+    pi5: bool = False
+
+
+class MatrixSettingsRefused(RuntimeError):
+    """Raised by DisplayManager instead of handing the library such a config."""
+
+
+def _as_int(value: Any) -> Optional[int]:
+    """The integer the binding would receive, or None if it isn't one.
+
+    A value that isn't a number is left to the binding, which raises a
+    ``TypeError`` DisplayManager already turns into fallback mode.
+    """
+    try:
+        return int(value)
+    except (TypeError, ValueError, OverflowError):
+        return None
+
+
+def _setting(hardware: Mapping[str, Any], runtime: Mapping[str, Any], field: str) -> Any:
+    section = runtime if INT_SETTING_LIMITS.get(field, ('hardware',))[0] == 'runtime' else hardware
+    if field in section:
+        return section[field]
+    return DISPLAY_MANAGER_DEFAULTS.get(field)
+
+
+def describe_range(low: int, high: int, even: bool = False) -> str:
+    kind = "an even integer" if even else "an integer"
+    if high >= INT32_MAX:
+        return f"{kind} of at least {low}"
+    return f"{kind} from {low} to {high}"
+
+
+def library_refusals(hardware: Optional[Mapping[str, Any]],
+                     runtime: Optional[Mapping[str, Any]] = None,
+                     pi5: bool = False) -> List[Refusal]:
+    """Every reason the pinned library would refuse (NULL, abort or overflow)
+    to start with this ``display.hardware`` / ``display.runtime`` config.
+
+    Missing keys take DisplayManager's defaults. ``pi5`` adds the Raspberry
+    Pi 5 limits from :func:`pi5_unsupported_settings`.
+    """
+    hardware = hardware if isinstance(hardware, Mapping) else {}
+    runtime = runtime if isinstance(runtime, Mapping) else {}
+    refusals: List[Refusal] = []
+
+    for field, (section, low, high, even) in INT_SETTING_LIMITS.items():
+        # DisplayManager sets these only when present, and scan_mode /
+        # pwm_dither_bits / rp1_rio have no default of its own.
+        source = runtime if section == 'runtime' else hardware
+        if field not in source and field not in DISPLAY_MANAGER_DEFAULTS:
+            continue
+        value = _as_int(_setting(hardware, runtime, field))
+        if value is None:
+            continue
+        if not low <= value <= high or (even and value % 2):
+            refusals.append(Refusal(
+                (field,), f"{field} {value} (must be {describe_range(low, high, even)})"))
+
+    mapping = _setting(hardware, runtime, 'hardware_mapping')
+    outputs = None
+    if not isinstance(mapping, str):
+        refusals.append(Refusal(
+            ('hardware_mapping',), f"hardware mapping {mapping!r} (must be a mapping name)"))
+    else:
+        # The library matches names case-insensitively and reads an empty
+        # name as "regular".
+        outputs = MAPPING_OUTPUTS.get((mapping or 'regular').lower())
+        if outputs is None:
+            refusals.append(Refusal(
+                ('hardware_mapping',),
+                f'hardware mapping "{mapping}" (the installed library has '
+                + ", ".join(MAPPING_OUTPUTS) + ")"))
+
+    parallel = _as_int(_setting(hardware, runtime, 'parallel'))
+    if outputs is not None and parallel is not None and 1 <= parallel <= 3 and parallel > outputs:
+        refusals.append(Refusal(
+            ('parallel', 'hardware_mapping'),
+            f'parallel {parallel} with hardware mapping "{mapping}", which has '
+            f'{outputs} output{"s" if outputs != 1 else ""}'))
+
+    sequence = _setting(hardware, runtime, 'led_rgb_sequence')
+    if isinstance(sequence, str) and not (
+            len(sequence) == 3 and set(sequence.upper()) == {'R', 'G', 'B'}):
+        refusals.append(Refusal(
+            ('led_rgb_sequence',),
+            f'LED RGB sequence "{sequence}" (must be R, G and B in some order)'))
+
+    if pi5:
+        unsupported = pi5_unsupported_settings(hardware)
+        if unsupported:
+            refusals.append(Refusal(
+                ('row_address_type', 'parallel', 'hardware_mapping'), unsupported, pi5=True))
+
+    return refusals
+
+
+def refusal_message(refusals: List[Refusal]) -> Optional[str]:
+    """One sentence naming every refusal, or None when there are none."""
+    general = [r.message for r in refusals if not r.pi5]
+    pi5 = [r.message for r in refusals if r.pi5]
+    parts = []
+    if general:
+        parts.append("The installed rgbmatrix library can't start with these "
+                     "display settings: " + "; ".join(general) + ".")
+    parts.extend(pi5)
+    return " ".join(parts) or None

src/plugin_system/plugin_manager.py

@@ -22,7 +22,10 @@ from src.logging_config import get_logger
 from src.plugin_system.plugin_loader import PluginLoader
 from src.plugin_system.plugin_executor import PluginExecutor
 from src.plugin_system.plugin_state import PluginStateManager, PluginState
-from src.plugin_system.schema_manager import SchemaManager, normalize_legacy_booleans
+from src.plugin_system.schema_manager import (
+    CORE_VEGAS_TUNING_KEYS, SchemaManager, normalize_legacy_booleans,
+)
+from src.common.path_safety import safe_path_component
 from src.common.permission_utils import (
     ensure_directory_permissions,
     get_plugin_dir_mode
@@ -369,32 +372,11 @@ class PluginManager:
                         f"The schema may be invalid. Please verify the schema file at: {schema_path}"
                     )
 
-            # A plugin that turned an on/off boolean into an {enabled, ...}
+            # Legacy booleans read as objects, then schema defaults: the same
-            # object still finds the boolean in config.json until the user saves
+            # preparation saves, GET /plugins/config and hot reload apply
-            # its settings form, which carries it over (plugin_config.html).
+            # (prepare_plugin_config). In memory only: config.json is written
-            # Read it the same way here, before the defaults fill in the rest
+            # by saves, never by loading a plugin.
-            # of the object and before schema validation, so the plugin doesn't
+            config = self.prepare_plugin_config(plugin_id, config, schema=schema)
-            # start with a schema warning and a degraded flag. In memory only:
-            # config.json is written by saves, never by loading a plugin.
-            if schema:
-                upgraded: List[str] = []
-                config = normalize_legacy_booleans(config, schema, upgraded)
-                if upgraded:
-                    self.logger.info(
-                        "Plugin %s: reading legacy boolean setting %s as "
-                        "{\"enabled\": ...}; saving the plugin's settings "
-                        "stores the new shape",
-                        plugin_id, ", ".join(upgraded),
-                    )
-
-            # Merge config with schema defaults to ensure all defaults are applied
-            try:
-                defaults = self.schema_manager.generate_default_config(plugin_id, use_cache=True)
-                config = self.schema_manager.merge_with_defaults(config, defaults)
-                self.logger.debug(f"Merged config with schema defaults for {plugin_id}")
-            except Exception as e:
-                self.logger.warning(f"Could not apply schema defaults for {plugin_id}: {e}")
-                # Continue with original config if defaults can't be applied
             
             # Use PluginLoader to load plugin
             plugin_instance, module = self.plugin_loader.load_plugin(
@@ -489,11 +471,57 @@ class PluginManager:
     #:
     #: Read by: ``vegas_mode/plugin_adapter.py`` (``vegas_width_pct``,
     #: ``vegas_overflow``) and ``base_plugin.py`` (``vegas_max_width_screens``).
-    CORE_OWNED_CONFIG_KEYS = frozenset({
+    #:
-        'vegas_width_pct',
+    #: The list itself lives with the other core-owned per-plugin properties in
-        'vegas_overflow',
+    #: ``schema_manager.CORE_PLUGIN_PROPERTIES``, which the web save path also
-        'vegas_max_width_screens',
+    #: uses to keep these keys.
-    })
+    CORE_OWNED_CONFIG_KEYS = CORE_VEGAS_TUNING_KEYS
+
+    def prepare_plugin_config(self, plugin_id: str, config: Any,
+                              schema: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """The config a plugin runs with, built from its raw config.json section.
+
+        A plugin that turned an on/off boolean into an ``{enabled, ...}``
+        object still finds the boolean in config.json until its settings are
+        next saved; it is read as the object, and schema defaults fill in the
+        rest (``SchemaManager.prepare_plugin_config``). Used when loading a
+        plugin and on hot reload (DisplayController), so ``on_config_change``
+        receives the same shape the plugin was constructed with.
+
+        Never raises: on failure the legacy-boolean pass alone is applied, or
+        failing that the section is returned as it was.
+        """
+        if schema is None:
+            try:
+                schema = self.schema_manager.load_schema(plugin_id)
+            except Exception as e:
+                self.logger.debug("Could not load schema for %s: %s", plugin_id, e)
+                schema = None
+        upgraded: List[str] = []
+        try:
+            prepared = self.schema_manager.prepare_plugin_config(
+                plugin_id, config, schema=schema, changed_paths=upgraded)
+            self.logger.debug("Merged config with schema defaults for %s", plugin_id)
+        except Exception as e:
+            self.logger.warning("Could not apply schema defaults for %s: %s", plugin_id, e)
+            # Continue without defaults if they can't be applied
+            upgraded = []
+            prepared = config if isinstance(config, dict) else {}
+            if schema:
+                try:
+                    prepared = normalize_legacy_booleans(prepared, schema, upgraded)
+                except Exception as legacy_error:
+                    self.logger.warning(
+                        "Could not read legacy boolean settings for %s: %s",
+                        plugin_id, legacy_error)
+        if upgraded:
+            self.logger.info(
+                "Plugin %s: reading legacy boolean setting %s as "
+                "{\"enabled\": ...}; saving the plugin's settings "
+                "stores the new shape",
+                plugin_id, ", ".join(upgraded),
+            )
+        return prepared
 
     def _strip_core_owned_keys(self, config: Dict[str, Any]) -> Dict[str, Any]:
         """A shallow copy of ``config`` without the core's own tuning keys.
@@ -743,11 +771,20 @@ class PluginManager:
             
         Returns:
             Directory path as string or None if not found
+
+        ``plugin_id`` often comes straight from a request, so anything that is
+        not one plain path segment (``..``, ``a/b``, an absolute path) is
+        refused instead of being joined onto ``plugins_dir``. The join is not
+        resolved further: dev plugins are symlinks into ``plugins_dir``.
         """
         with self._discovery_lock:
             if hasattr(self, 'plugin_directories') and plugin_id in self.plugin_directories:
                 return str(self.plugin_directories[plugin_id])
 
+        plugin_id = safe_path_component(plugin_id)
+        if plugin_id is None:
+            return None
+
         plugin_dir = self.plugins_dir / plugin_id
         if plugin_dir.exists():
             return str(plugin_dir)

src/plugin_system/schema_manager.py

@@ -13,6 +13,8 @@ from typing import Any, Dict, List, Optional, Tuple
 import jsonschema
 from jsonschema import Draft7Validator, ValidationError
 
+from src.core_config_keys import CORE_CONFIG_KEYS
+
 
 def _renders_as_object(prop: Dict[str, Any]) -> bool:
     """``field_type == 'object'`` as ``plugin_config.html`` computes it.
@@ -93,6 +95,222 @@ def normalize_legacy_booleans(config: Any, schema: Any,
     return result
 
 
+#: Per-plugin settings the **core** owns: it reads them out of each plugin's
+#: config section, so they are allowed in every plugin's config whether or not
+#: the plugin's schema declares them. The one list for validation, for the web
+#: save filter and for the load-time checks -- a private copy is how JSON saves
+#: came to drop ``skin`` and the ``vegas_*`` keys while the validator accepted
+#: them.
+#:
+#: Values are the schema used when the plugin does not declare the property.
+CORE_PLUGIN_PROPERTIES: Dict[str, Dict[str, Any]] = {
+    # Defaults match BasePlugin behavior: enabled=True, display_duration=15,
+    # live_priority=False.
+    "enabled": {
+        "type": "boolean",
+        "default": True,
+        "description": "Enable or disable this plugin"
+    },
+    "display_duration": {
+        "type": "number",
+        "default": 15,
+        "minimum": 1,
+        "maximum": 300,
+        "description": "How long to display this plugin in seconds"
+    },
+    "live_priority": {
+        "type": "boolean",
+        "default": False,
+        "description": "Enable live priority takeover when plugin has live content"
+    },
+    # Skin selection (docs/SKIN_SYSTEM.md). Deliberately NOT an enum here:
+    # validation must keep passing when a configured skin gets uninstalled
+    # (rendering falls back to built-in). The install-dependent enum is
+    # injected only at serve time (inject_skin_selector) for the web UI
+    # dropdown.
+    "skin": {
+        "type": ["string", "object", "null"],
+        "description": "Visual skin id, or a per-mode mapping like {\"live\": \"my-skin\"}"
+    },
+    "skin_options": {
+        "type": "object",
+        "description": "Options passed through to the selected skin"
+    },
+    # Vegas tuning read by vegas_mode/plugin_adapter.py and base_plugin.py.
+    # Left untyped: the adapter validates them itself and ignores a bad
+    # value with a log line, so a stored one must never block a save.
+    "vegas_width_pct": {
+        "description": "Vegas mode: width of this plugin's card, as a percentage of the panel"
+    },
+    "vegas_overflow": {
+        "description": "Vegas mode: 'rotate' or 'truncate' when this plugin's content overflows"
+    },
+    "vegas_max_width_screens": {
+        "description": "Vegas mode: widest this plugin's card may be, in screens"
+    },
+}
+
+#: The keys of CORE_PLUGIN_PROPERTIES that are Vegas tuning rather than plugin
+#: state. PluginManager strips these before its soft validation (see
+#: PluginManager.CORE_OWNED_CONFIG_KEYS).
+CORE_VEGAS_TUNING_KEYS = frozenset({
+    'vegas_width_pct', 'vegas_overflow', 'vegas_max_width_screens',
+})
+
+
+def with_core_plugin_properties(schema: Dict[str, Any]) -> Dict[str, Any]:
+    """A deep copy of a plugin schema with CORE_PLUGIN_PROPERTIES allowed.
+
+    Properties the plugin declares itself are left as declared. Core
+    properties are removed from ``required``: they are system-managed.
+    """
+    enhanced = copy.deepcopy(schema) if isinstance(schema, dict) else {}
+    properties = enhanced.setdefault("properties", {})
+    for name, definition in CORE_PLUGIN_PROPERTIES.items():
+        if name not in properties:
+            properties[name] = copy.deepcopy(definition)
+    if "required" in enhanced:
+        enhanced["required"] = [field for field in enhanced["required"]
+                                if field not in CORE_PLUGIN_PROPERTIES]
+    return enhanced
+
+
+def extract_schema_defaults(schema: Dict[str, Any]) -> Dict[str, Any]:
+    """Default values of a JSON Schema's properties, recursively.
+
+    A property's own ``default`` wins; otherwise a nested object contributes
+    its children's defaults, and an array contributes ``[]`` (or a one-item
+    list of its ``items`` default). This is what a device runs with, so the
+    dev tools use it too (src/plugin_system/testing/loading.py).
+    """
+    defaults: Dict[str, Any] = {}
+    properties = schema.get('properties', {}) if isinstance(schema, dict) else {}
+    if not isinstance(properties, dict):
+        return defaults
+
+    for key, prop_schema in properties.items():
+        if not isinstance(prop_schema, dict):
+            continue
+        # If property has a default, use it
+        if 'default' in prop_schema:
+            defaults[key] = prop_schema['default']
+            continue
+
+        # Handle nested objects
+        if prop_schema.get('type') == 'object' and 'properties' in prop_schema:
+            nested_defaults = extract_schema_defaults(prop_schema)
+            if nested_defaults:
+                defaults[key] = nested_defaults
+
+        # Handle arrays with object items
+        elif prop_schema.get('type') == 'array' and 'items' in prop_schema:
+            items_schema = prop_schema['items']
+            if items_schema.get('type') == 'object' and 'properties' in items_schema:
+                # For arrays of objects, use empty array as default
+                # Individual objects will use their defaults when created
+                defaults[key] = []
+            elif 'default' in items_schema:
+                # Array with default item value
+                defaults[key] = [items_schema['default']]
+            else:
+                # Empty array as default
+                defaults[key] = []
+
+        # For other types without defaults, don't add to defaults dict
+        # This allows plugins to handle missing values as needed
+
+    return defaults
+
+
+def plugin_config_defaults(schema: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    """Every default a plugin's config gets: the schema's plus the core ones.
+
+    A plugin with no schema gets the minimal ``enabled: False,
+    display_duration: 15``. Device location is not applied here; that needs a
+    config manager (SchemaManager.generate_default_config).
+    """
+    if not schema:
+        return {
+            'enabled': False,
+            'display_duration': 15
+        }
+
+    defaults = extract_schema_defaults(schema)
+
+    # Ensure core properties have defaults (they may not be in the schema)
+    # These match BasePlugin behavior
+    for name in ('enabled', 'display_duration', 'live_priority'):
+        if name not in defaults:
+            defaults[name] = CORE_PLUGIN_PROPERTIES[name]['default']
+    return defaults
+
+
+def merge_config_defaults(config: Dict[str, Any], defaults: Dict[str, Any]) -> Dict[str, Any]:
+    """Merge configuration with defaults, preserving user values.
+
+    Also replaces None values with defaults so a config never starts with
+    None where a default exists. Neither argument is mutated.
+    """
+    merged = copy.deepcopy(defaults)
+
+    def deep_merge(target: Dict[str, Any], source: Dict[str, Any], default_dict: Dict[str, Any]) -> None:
+        """Recursively merge source into target, replacing None with defaults."""
+        for key, value in source.items():
+            default_value = default_dict.get(key)
+
+            if key in target and isinstance(target[key], dict) and isinstance(value, dict):
+                # Both are dicts, recursively merge
+                if isinstance(default_value, dict):
+                    deep_merge(target[key], value, default_value)
+                else:
+                    deep_merge(target[key], value, {})
+            elif value is None and default_value is not None:
+                # Value is None and we have a default, use the default
+                target[key] = copy.deepcopy(default_value) if isinstance(default_value, (dict, list)) else default_value
+            else:
+                # Normal merge: user value takes precedence (copy if dict/list)
+                if isinstance(value, (dict, list)):
+                    target[key] = copy.deepcopy(value)
+                else:
+                    target[key] = value
+
+    deep_merge(merged, config, defaults)
+
+    # Final pass: replace any remaining None values at any level with defaults
+    def replace_none_with_defaults(target: Dict[str, Any], default_dict: Dict[str, Any]) -> None:
+        """Recursively replace None values with defaults."""
+        for key in list(target.keys()):
+            value = target[key]
+            default_value = default_dict.get(key)
+
+            if value is None and default_value is not None:
+                # Replace None with default
+                target[key] = copy.deepcopy(default_value) if isinstance(default_value, (dict, list)) else default_value
+            elif isinstance(value, dict) and isinstance(default_value, dict):
+                # Recursively process nested dicts
+                replace_none_with_defaults(value, default_value)
+
+    replace_none_with_defaults(merged, defaults)
+    return merged
+
+
+def prepare_plugin_config(config: Any, schema: Optional[Dict[str, Any]],
+                          defaults: Dict[str, Any],
+                          changed_paths: Optional[List[str]] = None) -> Dict[str, Any]:
+    """The config a plugin runs with, from its stored (or submitted) section.
+
+    Legacy booleans are read as ``{"enabled": ...}`` objects
+    (normalize_legacy_booleans), then schema defaults fill in whatever is
+    missing. Loading a plugin, both config saves, GET /plugins/config, hot
+    reload and the dev tools all go through this, so a plugin sees the same
+    shape however its config reached it.
+    """
+    config = config if isinstance(config, dict) else {}
+    if schema:
+        config = normalize_legacy_booleans(config, schema, changed_paths)
+    return merge_config_defaults(config, defaults)
+
+
 class SchemaManager:
     """
     Manages plugin configuration schemas with caching and validation.
@@ -263,55 +481,10 @@ class SchemaManager:
         """
         Recursively extract default values from a JSON Schema.
 
-        Handles nested objects, arrays, and all schema types.
+        See :func:`extract_schema_defaults`; ``prefix`` is accepted for
-        
+        compatibility and unused.
-        Args:
-            schema: JSON Schema dictionary
-            prefix: Optional prefix for logging/debugging
-            
-        Returns:
-            Dictionary of default values
         """
-        defaults = {}
+        return extract_schema_defaults(schema)
-        
-        # Handle schema with properties
-        properties = schema.get('properties', {})
-        if not properties:
-            return defaults
-        
-        for key, prop_schema in properties.items():
-            field_path = f"{prefix}.{key}" if prefix else key
-            
-            # If property has a default, use it
-            if 'default' in prop_schema:
-                defaults[key] = prop_schema['default']
-                self.logger.debug(f"Found default for {field_path}: {prop_schema['default']}")
-                continue
-            
-            # Handle nested objects
-            if prop_schema.get('type') == 'object' and 'properties' in prop_schema:
-                nested_defaults = self.extract_defaults_from_schema(prop_schema, field_path)
-                if nested_defaults:
-                    defaults[key] = nested_defaults
-            
-            # Handle arrays with object items
-            elif prop_schema.get('type') == 'array' and 'items' in prop_schema:
-                items_schema = prop_schema['items']
-                if items_schema.get('type') == 'object' and 'properties' in items_schema:
-                    # For arrays of objects, use empty array as default
-                    # Individual objects will use their defaults when created
-                    defaults[key] = []
-                elif 'default' in items_schema:
-                    # Array with default item value
-                    defaults[key] = [items_schema['default']]
-                else:
-                    # Empty array as default
-                    defaults[key] = []
-            
-            # For other types without defaults, don't add to defaults dict
-            # This allows plugins to handle missing values as needed
-        
-        return defaults
 
     def get_device_location(self) -> Optional[Dict[str, Any]]:
         """
@@ -391,24 +564,11 @@ class SchemaManager:
         schema = self.load_schema(plugin_id, use_cache=use_cache)
         if not schema:
             # Return minimal defaults if no schema
-            return {
+            return plugin_config_defaults(None)
-                'enabled': False,
-                'display_duration': 15
-            }
 
-        # Extract defaults from schema
+        # Schema defaults plus the core properties' (they may not be in the
-        defaults = self.extract_defaults_from_schema(schema)
+        # schema)
-        
+        defaults = plugin_config_defaults(schema)
-        # Ensure core properties have defaults (they may not be in the schema)
-        # These match BasePlugin behavior
-        if 'enabled' not in defaults:
-            defaults['enabled'] = schema.get('properties', {}).get('enabled', {}).get('default', True)
-        
-        if 'display_duration' not in defaults:
-            defaults['display_duration'] = schema.get('properties', {}).get('display_duration', {}).get('default', 15)
-        
-        if 'live_priority' not in defaults:
-            defaults['live_priority'] = schema.get('properties', {}).get('live_priority', {}).get('default', False)
 
         # Cache the defaults *before* the device location is layered on, so a
         # later change to the device location is picked up by the next call.
@@ -416,6 +576,27 @@ class SchemaManager:
         
         return self.apply_device_location(defaults)
     
+    def prepare_plugin_config(self, plugin_id: str, config: Any,
+                              schema: Optional[Dict[str, Any]] = None,
+                              changed_paths: Optional[List[str]] = None) -> Dict[str, Any]:
+        """
+        The config a plugin runs with: see :func:`prepare_plugin_config`.
+
+        Args:
+            plugin_id: Plugin identifier
+            config: The plugin's stored or submitted config section
+            schema: The plugin's schema, when the caller already has it
+            changed_paths: Receives the dotted path of each legacy boolean
+                read as an object
+
+        Returns:
+            A new dict; ``config`` is not mutated
+        """
+        if schema is None:
+            schema = self.load_schema(plugin_id, use_cache=True)
+        defaults = self.generate_default_config(plugin_id, use_cache=True)
+        return prepare_plugin_config(config, schema, defaults, changed_paths)
+
     def validate_config_against_schema(self, config: Dict[str, Any], schema: Dict[str, Any], 
                                       plugin_id: Optional[str] = None) -> Tuple[bool, List[str]]:
         """
@@ -436,78 +617,16 @@ class SchemaManager:
         errors = []
         
         try:
-            # Core plugin properties that should always be allowed
+            # Core plugin properties (CORE_PLUGIN_PROPERTIES) are handled by
-            # These are handled by the base plugin system and should not cause validation failures
+            # the base plugin system and should not cause validation failures:
-            # Defaults match BasePlugin behavior: enabled=True, display_duration=15, live_priority=False
+            # they are allowed even when the plugin's schema doesn't declare
-            core_properties = {
+            # them, and never required.
-                "enabled": {
+            enhanced_schema = with_core_plugin_properties(schema)
-                    "type": "boolean",
+            if plugin_id:
-                    "default": True,
+                declared = schema.get("properties", {}) if isinstance(schema, dict) else {}
-                    "description": "Enable or disable this plugin"
-                },
-                "display_duration": {
-                    "type": "number",
-                    "default": 15,
-                    "minimum": 1,
-                    "maximum": 300,
-                    "description": "How long to display this plugin in seconds"
-                },
-                "live_priority": {
-                    "type": "boolean",
-                    "default": False,
-                    "description": "Enable live priority takeover when plugin has live content"
-                },
-                # Skin selection (docs/SKIN_SYSTEM.md). Deliberately NOT an
-                # enum here: validation must keep passing when a configured
-                # skin gets uninstalled (rendering falls back to built-in).
-                # The install-dependent enum is injected only at serve time
-                # (inject_skin_selector) for the web UI dropdown.
-                "skin": {
-                    "type": ["string", "object", "null"],
-                    "description": "Visual skin id, or a per-mode mapping like {\"live\": \"my-skin\"}"
-                },
-                "skin_options": {
-                    "type": "object",
-                    "description": "Options passed through to the selected skin"
-                }
-            }
-            
-            # Create a deep copy of the schema to modify (to avoid mutating the original)
-            enhanced_schema = copy.deepcopy(schema)
-            if "properties" not in enhanced_schema:
-                enhanced_schema["properties"] = {}
-            
-            # Inject core properties if they're not already defined in the schema
-            # This ensures core properties are always allowed even if not in the plugin's schema
-            properties_added = []
-            for prop_name, prop_def in core_properties.items():
-                if prop_name not in enhanced_schema["properties"]:
-                    enhanced_schema["properties"][prop_name] = copy.deepcopy(prop_def)
-                    properties_added.append(prop_name)
-            
-            # Log if we added any core properties (for debugging)
-            if properties_added and plugin_id:
                 self.logger.debug(
-                    f"Injected core properties into schema for {plugin_id}: {properties_added}"
+                    "Injected core properties into schema for %s: %s", plugin_id,
-                )
+                    [name for name in CORE_PLUGIN_PROPERTIES if name not in declared]
-            
-            # Remove core properties from required array (they're system-managed)
-            # Core properties should be allowed but not required for validation
-            if "required" in enhanced_schema:
-                core_prop_names = list(core_properties.keys())
-                removed_from_required = [
-                    field for field in enhanced_schema["required"]
-                    if field in core_prop_names
-                ]
-                enhanced_schema["required"] = [
-                    field for field in enhanced_schema["required"] 
-                    if field not in core_prop_names
-                ]
-                
-                # Log if we removed any core properties from required (for debugging)
-                if removed_from_required and plugin_id:
-                    self.logger.debug(
-                        f"Removed core properties from required array for {plugin_id}: {removed_from_required}"
                 )
 
             # Create validator with enhanced schema
@@ -634,47 +753,7 @@ class SchemaManager:
         Returns:
             Merged configuration with defaults applied where missing or None
         """
-        merged = copy.deepcopy(defaults)
+        return merge_config_defaults(config, defaults)
-        
-        def deep_merge(target: Dict[str, Any], source: Dict[str, Any], default_dict: Dict[str, Any]) -> None:
-            """Recursively merge source into target, replacing None with defaults."""
-            for key, value in source.items():
-                default_value = default_dict.get(key)
-                
-                if key in target and isinstance(target[key], dict) and isinstance(value, dict):
-                    # Both are dicts, recursively merge
-                    if isinstance(default_value, dict):
-                        deep_merge(target[key], value, default_value)
-                    else:
-                        deep_merge(target[key], value, {})
-                elif value is None and default_value is not None:
-                    # Value is None and we have a default, use the default
-                    target[key] = copy.deepcopy(default_value) if isinstance(default_value, (dict, list)) else default_value
-                else:
-                    # Normal merge: user value takes precedence (copy if dict/list)
-                    if isinstance(value, (dict, list)):
-                        target[key] = copy.deepcopy(value)
-                    else:
-                        target[key] = value
-        
-        deep_merge(merged, config, defaults)
-        
-        # Final pass: replace any remaining None values at any level with defaults
-        def replace_none_with_defaults(target: Dict[str, Any], default_dict: Dict[str, Any]) -> None:
-            """Recursively replace None values with defaults."""
-            for key in list(target.keys()):
-                value = target[key]
-                default_value = default_dict.get(key)
-                
-                if value is None and default_value is not None:
-                    # Replace None with default
-                    target[key] = copy.deepcopy(default_value) if isinstance(default_value, (dict, list)) else default_value
-                elif isinstance(value, dict) and isinstance(default_value, dict):
-                    # Recursively process nested dicts
-                    replace_none_with_defaults(value, default_value)
-        
-        replace_none_with_defaults(merged, defaults)
-        return merged
 
     def detect_config_key_collisions(
         self,
@@ -698,10 +777,11 @@ class SchemaManager:
         """
         collisions = []
 
-        # Reserved top-level config keys that plugins should not use as IDs
+        # Reserved top-level config keys that plugins should not use as IDs:
-        reserved_keys = {
+        # every core section (src/core_config_keys.py), plus a few names that
-            'display', 'schedule', 'timezone', 'plugin_system',
+        # read as core even though no current section uses them.
-            'display_modes', 'system', 'hardware', 'debug',
+        reserved_keys = set(CORE_CONFIG_KEYS) | {
+            'display_modes', 'hardware', 'debug',
             'log_level', 'emulator', 'web_interface'
         }
 

src/plugin_system/testing/harness.py

@@ -27,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, merge_config
+from .loading import build_config, load_manifest
 from .sizes import DEFAULT_TEST_SIZES, safe_mode_filename, size_label
 
 logger = get_logger("[Plugin Harness]")
@@ -305,9 +305,7 @@ 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 = merge_config(
+    config = build_config(plugin_dir, config)
-        merge_config({"enabled": True}, load_config_defaults(plugin_dir)),
-        config or {})
     sizes = sizes or DEFAULT_TEST_SIZES
     results: List[RenderResult] = []
 

src/plugin_system/testing/loading.py

@@ -42,29 +42,6 @@ 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.
 
@@ -81,14 +58,45 @@ def merge_config(base: Dict[str, Any], override: Dict[str, Any]) -> Dict[str, An
     return merged
 
 
-def load_config_defaults(plugin_dir: Union[str, Path]) -> Dict[str, Any]:
+def load_schema(plugin_dir: Union[str, Path]) -> Optional[Dict[str, Any]]:
-    """Extract default values from a plugin's config_schema.json (empty if none)."""
+    """A plugin's config_schema.json, or None when it has none."""
     schema_path = Path(plugin_dir) / 'config_schema.json'
     if not schema_path.exists():
-        return {}
+        return None
     with open(schema_path, 'r', encoding='utf-8') as f:
-        schema = json.load(f)
+        return json.load(f)
-    return _defaults_from_properties(schema.get('properties', {}))
+
+
+def load_config_defaults(plugin_dir: Union[str, Path]) -> Dict[str, Any]:
+    """Default values from a plugin's config_schema.json (empty if none).
+
+    The device's own extraction (schema_manager.extract_schema_defaults), so a
+    harness run starts from the config an install would have: nested objects
+    contribute their children's defaults (organised-by-league configs lost
+    thousands of them when only the top level was read), and arrays without a
+    default start as [].
+    """
+    from src.plugin_system.schema_manager import extract_schema_defaults
+    schema = load_schema(plugin_dir)
+    return extract_schema_defaults(schema) if schema else {}
+
+
+def build_config(plugin_dir: Union[str, Path],
+                 overrides: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """The config a device would give this plugin, with ``overrides`` applied.
+
+    Starts from a forced ``enabled: True``, deep-merges ``overrides`` onto it
+    (merge_config), then prepares the result exactly as the device does when it
+    loads a plugin: legacy booleans read as objects, and schema plus core
+    defaults filled in (schema_manager.prepare_plugin_config). Used by the
+    harness, check_plugin, render_plugin and the dev preview server.
+    """
+    from src.plugin_system.schema_manager import (
+        plugin_config_defaults, prepare_plugin_config,
+    )
+    schema = load_schema(plugin_dir)
+    requested = merge_config({"enabled": True}, overrides or {})
+    return prepare_plugin_config(requested, schema, plugin_config_defaults(schema))
 
 
 def load_harness_spec(plugin_dir: Union[str, Path]) -> Dict[str, Any]:
@@ -143,16 +151,14 @@ def build_full_config(
 
     Merge order: config_schema.json defaults, then a forced ``enabled: True``,
     then harness.json's config overlay, then the caller's explicit config --
-    most specific wins. `enabled` is re-asserted *after* the schema defaults
+    most specific wins, and each layer deep-merges (a nested override such as
-    so a plugin that reasonably ships `enabled: false` (e.g. a seasonal or
+    ``{"nhl": {"enabled": true}}`` keeps the other nhl defaults). `enabled` is
-    opt-in plugin) can't silently make every harness run test "disabled, do
+    asserted over the schema defaults so a plugin that reasonably ships
-    nothing" by accident -- callers that genuinely want to test the disabled
+    `enabled: false` (e.g. a seasonal or opt-in plugin) can't silently make
-    path can still do so via `cli_config={"enabled": False}`.
+    every harness run test "disabled, do nothing" by accident -- callers that
+    genuinely want to test the disabled path can still do so via
+    `cli_config={"enabled": False}`. See build_config.
     """
     spec = spec or {}
-    config: Dict[str, Any] = {}
+    overrides = merge_config(spec.get("config", {}) or {}, cli_config or {})
-    config.update(load_config_defaults(plugin_dir))
+    return build_config(plugin_dir, overrides)
-    config["enabled"] = True
-    config.update(spec.get("config", {}))
-    config.update(cli_config or {})
-    return config

src/startup_validator.py

@@ -8,6 +8,7 @@ Fails fast with clear error messages to prevent runtime issues.
 import os
 from typing import Any, List, Optional, Tuple
 from pathlib import Path
+from src.core_config_keys import CORE_CONFIG_KEYS
 from src.exceptions import ConfigError, PluginError, CacheError
 from src.logging_config import get_logger
 
@@ -275,8 +276,9 @@ class StartupValidator:
             
             # Check for enabled plugins that don't exist
             for plugin_id, plugin_config in config.items():
-                # Skip non-plugin config sections
+                # Skip core sections: auto_update and dim_schedule have an
-                if plugin_id in ['display', 'schedule', 'timezone', 'plugin_system']:
+                # 'enabled' key too, and are not plugins that went missing.
+                if plugin_id in CORE_CONFIG_KEYS:
                     continue
                 
                 if not isinstance(plugin_config, dict):

src/vegas_mode/config.py

@@ -155,9 +155,14 @@ class VegasModeConfig:
     target_fps: int = 125  # Target frame rate
     buffer_ahead: int = 2  # Number of plugins to buffer ahead
 
-    # Scroll behavior
+    # Scroll behavior. Neither key steps the scroll or sets a frame rate:
+    # motion is always by elapsed time at scroll_speed px/s. With
+    # frame_based_scrolling the speed is first converted to px per
+    # scroll_delay and clamped to 0.1-5 (ScrollHelper.set_scroll_speed), so
+    # the speed actually applied is clamp(scroll_speed * scroll_delay, 0.1, 5)
+    # / scroll_delay -- at the 0.02 default, speeds under 5 px/s run at 5.
     frame_based_scrolling: bool = True
-    scroll_delay: float = 0.02  # 50 FPS effective scroll updates
+    scroll_delay: float = 0.02  # only feeds the clamp above; not a frame period
 
     # Dynamic duration
     dynamic_duration_enabled: bool = True

src/vegas_mode/render_pipeline.py

@@ -127,12 +127,14 @@ class RenderPipeline:
         self.scroll_helper.set_sub_pixel_scrolling(self.config.smooth_scroll)
 
         # Config scroll_speed is always pixels per second, but ScrollHelper
-        # interprets it differently based on frame_based_scrolling mode:
+        # takes it in different units depending on frame_based_scrolling:
-        # - Frame-based: pixels per frame step
+        # - Frame-based: pixels per scroll_delay seconds (clamped to 0.1-5)
-        # - Time-based: pixels per second
+        # - Time-based: pixels per second (clamped to 1-500)
+        # Both modes then advance by elapsed time; frame-based mode does not
+        # step. So frame-based with scroll_delay only adds the clamp: the
+        # applied speed is clamp(scroll_speed * scroll_delay, 0.1, 5) /
+        # scroll_delay px/s.
         if self.config.frame_based_scrolling:
-            # Convert pixels/second to pixels/frame
-            # pixels_per_frame = pixels_per_second * seconds_per_frame
             pixels_per_frame = self.config.scroll_speed * self.config.scroll_delay
             self.scroll_helper.set_scroll_speed(pixels_per_frame)
         else:

systemd/README.md

@@ -52,9 +52,11 @@ This directory contains systemd service unit files for LEDMatrix services.
 ## Installation
 
 These service files are installed by the installation scripts in `scripts/install/`:
-- `install_service.sh` installs `ledmatrix.service`
+- `install_service.sh` installs `ledmatrix.service`, `ledmatrix-web.service`
-- `install_web_service.sh` installs `ledmatrix-web.service` and the
+  and the `ledmatrix-update-verify` service and path units, then enables and
-  `ledmatrix-update-verify` service and path units
+  starts them
+- `install_web_service.sh` installs only `ledmatrix-web.service` and the
+  `ledmatrix-update-verify` units
 - `install_wifi_monitor.sh` installs `ledmatrix-wifi-monitor.service`
 - `install_dns_fix.sh` installs `ledmatrix-dns-fix.service` (opt-in, not run
   by the normal installer)

test/js/README.md

@@ -35,11 +35,12 @@ nothing is listening, so it stays useful in a bare checkout.
 | 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_update_all.js` | no | `PluginInstallManager.updateAll` from `plugins/install_manager.js`: Check & Update All sends only plugin ids (never `starlark:` app entries), and re-sends a request that got no HTTP answer (web service restarting) instead of skipping that plugin. Also run by `test/web_interface/test_update_all_plugins.py` so CI covers it |
+| `unit/test_update_all.js` | no | `PluginInstallManager.updateAll` from `plugins/install_manager.js`: Check & Update All sends only plugin ids (never `starlark:` app entries), re-sends a request that got no HTTP answer (web service restarting) instead of skipping that plugin, never re-sends one that got any HTTP answer (the real `api_client.js` classifies a proxy 502 or a JSON error without `error_code` as `API_ERROR`), and counts a no-op update as already up to date in the summary. Also run by `test/web_interface/test_update_all_plugins.py` so CI covers it |
 | `unit/test_render_cards.js` | no | `renderInstalledCards` markup, both empty states, and HTML-escaping of hostile plugin metadata |
 | `unit/test_style_editor_element_keys.js` | no | `elementKeys()`/`styleRows()`/`positionRows()` from `widgets/style-editor.js`: every `customization.layout` entry gets exactly one row -- paired with its style element through core's `x-layout-key` (so `score` belongs to `score_text`, not a second row), or a position row of its own, leaves included -- since the widget claims the whole `layout` block from the generic fallback renderer |
 | `unit/test_style_editor_layout_leaf_columns.js` | no | `columnsFor()` from `widgets/style-editor.js`: a layout-only key whose own value is a leaf (no x/y sub-object, e.g. a `show_logo` toggle) gets a self-keyed column instead of a blank, uneditable row |
 | `unit/test_style_editor_layout_leaf_collision.js` | no | `columnsFor()` from `widgets/style-editor.js`: a layout-only leaf key still gets its own column even when its name collides with an unrelated element's style sub-field or another layout axis's sub-field |
+| `unit/test_inline_handler_escaping.js` | no | The store, saved-repository and custom-registry inline `onclick` handlers and the live `window.updateImageList` from `plugins_manager.js`: a registry id, URL or uploaded file name carrying `'`, `"` or entities adds no attributes and reaches the handler intact, and the store's View button opens only http(s) links |
 | `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` |

test/js/run_all.js

@@ -18,7 +18,7 @@ const UNIT = ['unit/test_list_filter.js', 'unit/test_render_cards.js',
               'unit/test_html_escaping.js', 'unit/test_style_editor_element_keys.js',
               'unit/test_style_editor_layout_leaf_columns.js',
               'unit/test_style_editor_layout_leaf_collision.js',
-              'unit/test_update_all.js'];
+              'unit/test_update_all.js', 'unit/test_inline_handler_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'];
 

test/js/unit/test_inline_handler_escaping.js

@@ -0,0 +1,215 @@
+// Registry- and upload-supplied strings must not escape the inline handlers
+// plugins_manager.js builds for them.
+//
+// The store, saved-repository and custom-registry renderers wrote
+//
+//     <button onclick='... installFromCustomRegistry(${JSON.stringify(id)}) ...'>
+//
+// JSON.stringify makes a valid JS string but leaves `'` alone, so an entry id
+// of  x' onmouseover='alert(1)  closed the single-quoted attribute and added a
+// handler of its own. The live window.updateImageList (plugins_manager.js loads
+// last, so its copy beats the file-upload widget's) put the uploaded file's
+// original name into the markup unescaped.
+//
+// Each case renders with the shipped function, parses the tag the way a browser
+// does (quoted attribute values, entities decoded), and checks two things: no
+// attribute appeared that the template did not write, and the decoded handler
+// runs and passes the hostile value through intact as data.
+
+const fs = require('fs');
+const path = require('path');
+
+const SRC = fs.readFileSync(
+  path.resolve(__dirname, '../../../web_interface/static/v3/plugins_manager.js'), 'utf8');
+
+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, 400) : '')));
+
+function extract(opener) {
+  const start = SRC.indexOf(opener);
+  if (start < 0) { console.error('FAIL: cannot find ' + JSON.stringify(opener)); process.exit(1); }
+  let depth = 0;
+  for (let j = SRC.indexOf('{', start); j < SRC.length; j++) {
+    if (SRC[j] === '{') depth++;
+    else if (SRC[j] === '}' && --depth === 0) return SRC.slice(start, j + 1);
+  }
+  console.error('FAIL: unbalanced braces after ' + opener); process.exit(1);
+}
+
+// ── DOM shim ───────────────────────────────────────────────────────────────
+class FakeEl {
+  constructor() { this.innerHTML = ''; this.value = ''; this.textContent = ''; }
+}
+class TextEl {
+  set textContent(v) { this._t = String(v == null ? '' : v); }
+  get innerHTML() {
+    return (this._t || '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+  }
+}
+const els = {};
+global.document = {
+  getElementById: id => (els[id] ||= new FakeEl()),
+  createElement: () => new TextEl(),
+};
+global.window = global;
+global.pluginLog = () => {};
+global.isStorePluginInstalled = () => false;
+global.isNewPlugin = () => false;
+global.formatDate = () => '';
+global.setGridHtmlIfChanged = (container, html) => { container.innerHTML = html; };
+
+// eslint-disable-next-line no-eval
+eval([
+  'function escapeHtml(text) {', 'function escapeAttribute(text) {', 'function jsStringAttr(value) {',
+  'function renderPluginStore(plugins) {', 'function renderSavedRepositories(repositories) {',
+  'function renderCustomRegistryPlugins(plugins, registryUrl) {',
+].map(extract).join('\n') + '\nglobal.jsStringAttr = jsStringAttr; global.escapeHtml = escapeHtml;'
+  + '\nglobal.renderPluginStore = renderPluginStore; global.renderSavedRepositories = renderSavedRepositories;'
+  + '\nglobal.renderCustomRegistryPlugins = renderCustomRegistryPlugins; global.escapeAttribute = escapeAttribute;');
+// eslint-disable-next-line no-eval
+eval(extract('window.updateImageList = function(fieldId, images) {'));
+
+// ── minimal HTML start-tag tokenizer ───────────────────────────────────────
+function decodeEntities(s) {
+  return s.replace(/&(#x[0-9a-f]+|#\d+|quot|amp|lt|gt|apos);/gi, (m, e) => {
+    const k = e.toLowerCase();
+    if (k === 'quot') return '"';
+    if (k === 'amp') return '&';
+    if (k === 'lt') return '<';
+    if (k === 'gt') return '>';
+    if (k === 'apos') return "'";
+    return String.fromCodePoint(k[1] === 'x' ? parseInt(k.slice(2), 16) : parseInt(k.slice(1), 10));
+  });
+}
+function tags(html, name) {
+  const out = [];
+  let i = 0;
+  while ((i = html.indexOf('<' + name, i)) >= 0) {
+    let j = i + name.length + 1;
+    const attrs = [];
+    for (;;) {
+      while (/\s/.test(html[j])) j++;
+      if (html[j] === '>' || j >= html.length) break;
+      if (html[j] === '/') { j++; continue; }
+      let n = '';
+      while (j < html.length && !/[\s=>]/.test(html[j])) n += html[j++];
+      let v = '';
+      while (/\s/.test(html[j])) j++;
+      if (html[j] === '=') {
+        j++;
+        while (/\s/.test(html[j])) j++;
+        const q = html[j];
+        if (q === '"' || q === "'") {
+          const end = html.indexOf(q, j + 1);
+          v = html.slice(j + 1, end); j = end + 1;
+        } else {
+          while (j < html.length && !/[\s>]/.test(html[j])) v += html[j++];
+        }
+      }
+      attrs.push([n.toLowerCase(), decodeEntities(v)]);
+    }
+    out.push(attrs);
+    i = j;
+  }
+  return out;
+}
+const names = attrs => attrs.map(a => a[0]);
+const attr = (attrs, n) => (attrs.find(a => a[0] === n) || [])[1];
+
+// Run a decoded inline handler with window/document stubs; return the calls.
+function runHandler(code) {
+  const calls = [];
+  const win = new Proxy({}, {
+    get: (_, prop) => (...args) => { calls.push([prop, ...args]); },
+    has: () => true,
+  });
+  const doc = { getElementById: () => ({ value: '' }) };
+  // eslint-disable-next-line no-new-func
+  new Function('window', 'document', 'console', code)(win, doc, { error() {} });
+  return calls;
+}
+
+const SQ = "x' onmouseover='alert(1)";
+const DQ = 'x" onmouseover="alert(1)';
+const AMP = 'x&#39; onmouseover=&#39;alert(1)';
+
+console.log('\n1. custom registry install button');
+for (const hostile of [SQ, DQ, AMP]) {
+  renderCustomRegistryPlugins([{ id: hostile, name: 'n', plugin_path: hostile }], hostile);
+  const buttons = tags(els['custom-registry-grid'].innerHTML, 'button');
+  const b = buttons.find(a => attr(a, 'onclick'));
+  ok(`${JSON.stringify(hostile)}: only onclick and class attributes`,
+     b && names(b).join(',') === 'onclick,class', b && names(b));
+  let calls = [];
+  try { calls = runHandler(attr(b, 'onclick')); } catch (e) { calls = [['threw', String(e)]]; }
+  ok(`${JSON.stringify(hostile)}: handler passes id, url and path intact`,
+     calls.length === 1 && calls[0][0] === 'installFromCustomRegistry'
+       && calls[0][1] === hostile && calls[0][2] === hostile && calls[0][3] === hostile, calls);
+}
+
+console.log('\n2. store install and view buttons');
+for (const hostile of [SQ, DQ, AMP]) {
+  renderPluginStore([{ id: hostile, name: 'n', repo: 'https://github.com/o/r', plugin_path: 'p' }]);
+  const buttons = tags(els['plugin-store-grid'].innerHTML, 'button');
+  ok(`${JSON.stringify(hostile)}: two buttons, no extra attributes`,
+     buttons.length === 2 && buttons.every(b => names(b).every(n => ['onclick', 'class', 'disabled'].includes(n))),
+     buttons.map(names));
+  let calls = [];
+  try { calls = runHandler(attr(buttons[0], 'onclick')); } catch (e) { calls = [['threw', String(e)]]; }
+  ok(`${JSON.stringify(hostile)}: install handler gets the id intact`,
+     calls.length === 1 && calls[0][0] === 'installPlugin' && calls[0][1] === hostile, calls);
+}
+
+console.log('\n3. store view button only opens http(s) links');
+renderPluginStore([{ id: 'a', name: 'n', repo: 'https://github.com/o/r', plugin_path: 'plugins/a' }]);
+{
+  const view = tags(els['plugin-store-grid'].innerHTML, 'button')[1];
+  const calls = runHandler(attr(view, 'onclick'));
+  ok('https repo opens the plugin tree',
+     calls.length === 1 && calls[0][0] === 'open' && calls[0][1] === 'https://github.com/o/r/tree/main/plugins/a', calls);
+}
+renderPluginStore([{ id: 'a', name: 'n', repo: 'javascript:alert(document.domain)//' }]);
+{
+  const view = tags(els['plugin-store-grid'].innerHTML, 'button')[1];
+  const calls = runHandler(attr(view, 'onclick'));
+  ok('javascript: repo opens nothing', calls.length === 0, calls);
+  ok('javascript: repo button is disabled', names(view).includes('disabled'), names(view));
+}
+
+console.log('\n4. saved repository remove button');
+for (const hostile of [SQ, DQ, AMP]) {
+  renderSavedRepositories([{ url: hostile, name: hostile }]);
+  const b = tags(els['saved-repositories-list'].innerHTML, 'button')[0];
+  ok(`${JSON.stringify(hostile)}: no extra attributes`,
+     b && names(b).join(',') === 'onclick,class,title,aria-label', b && names(b));
+  let calls = [];
+  try { calls = runHandler(attr(b, 'onclick')); } catch (e) { calls = [['threw', String(e)]]; }
+  ok(`${JSON.stringify(hostile)}: handler gets the url intact`,
+     calls.length === 1 && calls[0][0] === 'removeSavedRepository' && calls[0][1] === hostile, calls);
+}
+
+console.log('\n5. live window.updateImageList escapes the uploaded file name');
+window.getUploadConfig = () => ({ plugin_id: SQ });
+window.currentPluginConfig = null;
+{
+  const name = '<img src=x onerror=alert(1)>' + DQ + '.png';
+  window.updateImageList('f', [{ id: SQ, path: 'assets/x".png', filename: DQ, original_filename: name, size: 1 }]);
+  const html = els['f_image_list'].innerHTML;
+  ok('no raw markup from original_filename', !html.includes('<img src=x onerror'), html);
+  const imgs = tags(html, 'img');
+  ok('one <img>, only the template attributes',
+     imgs.length === 1 && names(imgs[0]).join(',') === 'src,alt,loading,decoding,class,onerror', imgs.map(names));
+  ok('alt carries the stored filename as text', attr(imgs[0], 'alt') === DQ, imgs[0]);
+  const buttons = tags(html, 'button');
+  ok('two buttons, no extra attributes',
+     buttons.length === 2 && buttons.every(b => names(b).join(',') === 'type,onclick,class,title,aria-label'),
+     buttons.map(names));
+  const del = runHandler(attr(buttons[1], 'onclick'));
+  ok('delete handler gets field, image and plugin ids intact',
+     del.length === 1 && del[0][0] === 'deleteUploadedImage' && del[0][1] === 'f' && del[0][2] === SQ && del[0][3] === SQ, del);
+}
+
+console.log(`\n${pass} passed, ${fail} failed\n`);
+process.exit(fail ? 1 : 0);

test/js/unit/test_update_all.js

@@ -146,6 +146,89 @@ const noSleep = { sleep: async () => {} };
     ok('...and is reported as a failure', results.find(x => x.pluginId === 'static-image').success === false);
   }
 
+  console.log('\nthe real api_client.js: only a missing HTTP answer is retried');
+  {
+    // The fake PluginAPI above decides error_code itself. This runs the shipped
+    // client so its classification is what gets tested: a proxy's 502 page or
+    // a JSON 500 without error_code used to come back as NETWORK_ERROR and be
+    // re-sent five more times.
+    const PluginAPI = require(path.join(V3, 'js/plugins/api_client.js'));
+    const run = async (makeFetch) => {
+      let requests = 0, sleeps = 0;
+      global.fetch = async () => { requests++; return makeFetch(requests); };
+      global.window = { PluginAPI, installedPlugins: [{ id: 'stock-news' }] };
+      const results = await Manager.updateAll(null, { sleep: async () => { sleeps++; }, retryDelaysMs: [1, 1, 1] });
+      return { requests, sleeps, result: results[0] };
+    };
+    const httpAnswer = (status, json) => ({ ok: status < 400, status, json });
+
+    let r = await run(() => httpAnswer(502, async () => { throw new SyntaxError('Unexpected token <'); }));
+    ok('a 502 with an HTML body is sent once', r.requests === 1 && r.sleeps === 0, r);
+    ok('...and is an API_ERROR carrying the status, not NETWORK_ERROR',
+       r.result.success === false && r.result.error.error_code === 'API_ERROR' && r.result.error.status === 502, r.result.error);
+
+    r = await run(() => httpAnswer(500, async () => ({ status: 'error', message: 'boom' })));
+    ok('a JSON 500 without error_code is sent once', r.requests === 1 && r.sleeps === 0, r);
+    ok('...and keeps the server message', r.result.error.message === 'boom', r.result.error);
+
+    r = await run(() => httpAnswer(500, async () => ({ status: 'error', error_code: 'PLUGIN_UPDATE_FAILED', message: 'x' })));
+    ok('a structured error is passed through unchanged',
+       r.requests === 1 && r.result.error.error_code === 'PLUGIN_UPDATE_FAILED', r.result.error);
+
+    r = await run((n) => {
+      if (n === 1) throw new TypeError('Failed to fetch');
+      return httpAnswer(200, async () => ({ status: 'success', message: 'ok', data: { update_status: 'updated' } }));
+    });
+    ok('a fetch() that rejects is NETWORK_ERROR and re-sent', r.requests === 2 && r.sleeps === 1 && r.result.success, r);
+
+    r = await run(() => httpAnswer(200, async () => { throw new SyntaxError('Unexpected end of JSON input'); }));
+    ok('an unreadable 200 is not retried either', r.requests === 1 && r.result.error.error_code === 'API_ERROR', r);
+
+    // Every endpoint is one of the client's own API paths; one that could
+    // leave baseURL never reaches fetch(), and plugin ids are encoded.
+    const urls = [];
+    global.fetch = async (url) => { urls.push(url); return httpAnswer(200, async () => ({ status: 'success' })); };
+    const refusal = async (endpoint) => {
+      try { await PluginAPI.request(endpoint, 'POST'); return null; } catch (e) { return e.error_code; }
+    };
+    const bad = ['//evil.example/x', '/plugins/../../x', '/a\b', '/a b', 'plugins', null];
+    const codes = [];
+    for (const endpoint of bad) codes.push(await refusal(endpoint));
+    ok('an endpoint that could leave the API path is refused before fetch()',
+       codes.every(c => c === 'INVALID_ENDPOINT') && urls.length === 0, { codes, urls });
+    await PluginAPI.resetPluginConfig('a/../b&x=1');
+    ok('a plugin id is encoded into the URL, not spliced into it',
+       urls[0] === '/api/v3/plugins/config/reset?plugin_id=a%2F..%2Fb%26x%3D1', urls);
+    delete global.fetch;
+  }
+
+  console.log('\nsummary: a no-op update is not counted as updated');
+  {
+    const answer = (update_status, message) => ({ success: true, result: { status: 'success', message, data: { update_status } } });
+    const results = [
+      answer('updated', 'Plugin a updated to version 2.8.0'),
+      // ZIP-installed monorepo plugin already at the registry version: the
+      // route used to call this "updated successfully".
+      answer('up_to_date', 'Plugin stock-news already up to date (version 2.8.0)'),
+      answer('up_to_date', 'Plugin clock already up to date (commit abcdef1)'),
+      answer('local_only', 'Plugin mine is managed locally and does not receive registry updates'),
+      { success: false, error: { error_code: 'PLUGIN_UPDATE_FAILED' } },
+    ];
+    const s = Manager.summarizeUpdateResults(results);
+    ok('counts come from update_status',
+       s.updated === 1 && s.upToDate === 2 && s.localOnly === 1 && s.failed === 1, s);
+    ok('toast text names each outcome',
+       s.text === '1 updated, 2 already up to date, 1 managed locally, 1 failed', s.text);
+    ok('a failure alongside an update is a warning', s.type === 'warning', s.type);
+    ok('an older server that only says so in the message is still up to date',
+       Manager.updateOutcome({ success: true, result: { message: 'Plugin x already up to date (commit 1234567)' } }) === 'up_to_date');
+    ok('a success without a status or telltale message counts as updated',
+       Manager.updateOutcome({ success: true, result: { message: 'Plugin x updated successfully' } }) === 'updated');
+    const allNoop = Manager.summarizeUpdateResults([answer('up_to_date', ''), answer('up_to_date', '')]);
+    ok('nothing to do is a success toast with no "updated"',
+       allNoop.type === 'success' && allNoop.text === '2 already up to date', allNoop);
+  }
+
   console.log(`\n${pass} passed, ${fail} failed`);
   process.exit(fail ? 1 : 0);
 })().catch(e => { console.error(e); process.exit(1); });

test/test_api_v3_display_hardware.py

@@ -1,9 +1,10 @@
 """Display hardware settings accept what the rgbmatrix library accepts.
 
-Held to the ranges in the pinned library (RGBMatrix::Options::Validate in
+Held to what the pinned library and its Python binding accept
-lib/options-initialize.cc, the gpio_slowdown check in lib/led-matrix.cc), with
+(src/matrix_support.py: RGBMatrix::Options::Validate in
-one deliberate exception: rows has no upper bound here, although the library
+lib/options-initialize.cc, the gpio_slowdown check in lib/led-matrix.cc, the
-currently rejects more than 64 per panel. Two ways this used to go wrong:
+mapping table in lib/hardware-mapping.c and the binding's uint8_t setters).
+Ways this used to go wrong:
 
 - The Display form capped cols at 128, chain_length at 24 and
   pwm_lsb_nanoseconds at 500, and its submit handler (fixInvalidNumberInputs)
@@ -11,6 +12,10 @@ currently rejects more than 64 per panel. Two ways this used to go wrong:
   a long chain silently saved as the wrong size.
 - The API checked none of these, so a value the library rejects (odd rows,
   parallel 4, pwm_dither_bits 3) saved, and the matrix then refused to start.
+- After that, rows above 64, chain_length above 255, a misspelled hardware
+  mapping and parallel 2-3 on a single-output HAT mapping still saved. The
+  library answers those with no matrix or abort(), not an error, so the
+  display service crash-looped instead of falling back.
 
 Row address type 5 is the SM5368 / B707 row shift register the Waveshare 96x48
 V2 needs (Waveshare's own "96X48_1_24_SM5368" panel type in their library fork
@@ -102,10 +107,9 @@ def test_waveshare_96x48_v2_settings_all_save(api_v3_client, saved, as_strings):
 
 
 @pytest.mark.parametrize('field,value', [
-    ('rows', 8), ('rows', 64), ('rows', 96), ('rows', 128),
+    ('rows', 8), ('rows', 64),
     ('cols', 16), ('cols', 192), ('cols', 512),
-    ('chain_length', 1), ('chain_length', 32),
+    ('chain_length', 1), ('chain_length', 32), ('chain_length', 255),
-    ('parallel', 3),
     ('row_address_type', 0), ('row_address_type', 5), ('row_address_type', 5.0),
     ('multiplexing', 0), ('multiplexing', 22),
     ('gpio_slowdown', 0), ('gpio_slowdown', 10),
@@ -123,9 +127,9 @@ def test_values_in_range_are_saved(api_v3_client, saved, field, value):
 
 
 @pytest.mark.parametrize('field,value', [
-    ('rows', 6), ('rows', 47), ('rows', 97), ('rows', '48.5'),
+    ('rows', 6), ('rows', 47), ('rows', 66), ('rows', 96), ('rows', 128), ('rows', '48.5'),
     ('cols', 15), ('cols', 96.5), ('cols', True), ('cols', 'wide'),
-    ('chain_length', 0),
+    ('chain_length', 0), ('chain_length', 256), ('chain_length', 300),
     ('parallel', 0), ('parallel', 4),
     ('row_address_type', -1), ('row_address_type', 6),
     ('row_address_type', True), ('row_address_type', 5.5),
@@ -146,6 +150,69 @@ def test_values_out_of_range_are_refused(api_v3_client, saved, field, value):
     assert 'config' not in saved
 
 
+@pytest.mark.parametrize('body', [
+    {'hardware_mapping': 'regular', 'parallel': 3},
+    {'hardware_mapping': 'classic', 'parallel': 2},
+    {'hardware_mapping': 'Regular', 'parallel': 3},
+    {'hardware_mapping': 'classic-pi1'},
+    {'hardware_mapping': 'adafruit-hat', 'parallel': 1},
+])
+def test_mappings_the_library_has_are_saved(api_v3_client, saved, body):
+    response = _post(api_v3_client, body)
+    assert response.status_code == 200, response.get_data(as_text=True)[:200]
+    for field, value in body.items():
+        assert saved['config']['display']['hardware'][field] == value
+
+
+@pytest.mark.parametrize('body,named', [
+    # Framebuffer() abort()s: the HAT mappings define one output.
+    ({'hardware_mapping': 'adafruit-hat-pwm', 'parallel': 2}, 'parallel 2'),
+    ({'hardware_mapping': 'adafruit-hat', 'parallel': 3}, 'parallel 3'),
+    ({'hardware_mapping': 'regular-pi1', 'parallel': 2}, 'parallel 2'),
+    # InitHardwareMapping() abort()s on a name it doesn't have; compute-module
+    # isn't compiled into the default build.
+    ({'hardware_mapping': 'adafruit-hat-pwn'}, 'adafruit-hat-pwn'),
+    ({'hardware_mapping': 'compute-module'}, 'compute-module'),
+    ({'hardware_mapping': 5}, 'hardware mapping'),
+])
+def test_combinations_the_library_aborts_on_are_refused(api_v3_client, saved, body, named):
+    response = _post(api_v3_client, body)
+    assert response.status_code == 400
+    assert named in response.get_json()['message']
+    assert 'config' not in saved
+
+
+def test_parallel_is_checked_against_the_stored_mapping(api_v3_client, api_v3_module, saved):
+    api_v3_module.api_v3.config_manager.load_config.return_value = {
+        'display': {'hardware': {'hardware_mapping': 'adafruit-hat'}}}
+    response = _post(api_v3_client, {'parallel': 2})
+    assert response.status_code == 400
+    assert 'adafruit-hat' in response.get_json()['message']
+    assert 'config' not in saved
+
+
+def test_stored_refusal_does_not_block_unrelated_saves(api_v3_client, api_v3_module, saved):
+    api_v3_module.api_v3.config_manager.load_config.return_value = {
+        'display': {'hardware': {'hardware_mapping': 'adafruit-hat', 'parallel': 2}}}
+    response = _post(api_v3_client, {'brightness': 70})
+    assert response.status_code == 200, response.get_data(as_text=True)[:200]
+
+
+def test_a_request_value_is_checked_not_the_stored_one(api_v3_client, api_v3_module, saved):
+    """Fixing a stored bad value in the same save as a mapping change must work."""
+    api_v3_module.api_v3.config_manager.load_config.return_value = {
+        'display': {'hardware': {'rows': 128, 'parallel': 2}}}
+    response = _post(api_v3_client, {'rows': 64, 'hardware_mapping': 'regular'})
+    assert response.status_code == 200, response.get_data(as_text=True)[:200]
+
+
+@pytest.mark.parametrize('orientation', ['normal', '90', '180', '270'])
+def test_every_orientation_display_manager_applies_is_saved(api_v3_client, saved, orientation):
+    response = _post(api_v3_client, {'orientation': orientation})
+    assert response.status_code == 200, response.get_data(as_text=True)[:200]
+    assert saved['config']['display']['hardware']['orientation'] == orientation
+
+
 @pytest.fixture
 def display_page(monkeypatch):
     """Render the Display settings partial for a given config."""
@@ -231,6 +298,38 @@ def test_waveshare_96x48_v2_config_renders_back_unchanged(display_page):
         assert _attr(_input_tag(body, input_id), 'value') == str(WAVESHARE_96X48_V2[input_id]), input_id
 
 
+@pytest.mark.parametrize('hardware,select_id,expected', [
+    ({'hardware_mapping': 'classic'}, 'hardware_mapping', 'classic'),
+    ({'hardware_mapping': 'classic-pi1'}, 'hardware_mapping', 'classic-pi1'),
+    ({'hardware_mapping': 'adafruit-hat'}, 'hardware_mapping', 'adafruit-hat'),
+    ({'hardware_mapping': 'Regular'}, 'hardware_mapping', 'regular'),
+    ({'hardware_mapping': ''}, 'hardware_mapping', 'regular'),
+    ({'orientation': '90'}, 'orientation', '90'),
+    ({'orientation': '270'}, 'orientation', '270'),
+])
+def test_stored_mapping_and_orientation_render_back_unchanged(display_page, hardware, select_id, expected):
+    """With nothing selected the browser posts the first option, so one unrelated
+    Display save turned classic into adafruit-hat-pwm and 90 degrees into normal."""
+    body = display_page(_config_with(hardware=hardware))
+    assert _selected_option(body, select_id) == [expected]
+    assert "saved hardware mapping" not in body
+
+
+def test_missing_mapping_renders_display_managers_default(display_page):
+    config = _config_with()
+    del config['display']['hardware']['hardware_mapping']
+    assert _selected_option(display_page(config), 'hardware_mapping') == ['adafruit-hat-pwm']
+
+
+@pytest.mark.parametrize('stored', ['compute-module', 'adafruit-hat-pwn'])
+def test_unusable_stored_mapping_renders_selected_with_a_warning(display_page, stored):
+    """Kept selected rather than silently swapped for the first option; the API
+    refuses it on save, and the warning says why."""
+    body = display_page(_config_with(hardware={'hardware_mapping': stored}))
+    assert _selected_option(body, 'hardware_mapping') == [stored]
+    assert f'Your saved hardware mapping ("{stored}")' in body
+
+
 @pytest.mark.parametrize('field,section', [
     ('gpio_slowdown', 'runtime'), ('pwm_dither_bits', 'hardware'),
     ('limit_refresh_rate_hz', 'hardware'),
@@ -248,7 +347,7 @@ def test_a_stored_zero_renders_as_zero(display_page, field, section):
 
 @pytest.mark.parametrize('body', [
     {'row_address_type': 5}, {'row_address_type': '1'},
-    {'hardware_mapping': 'compute-module'},
+    {'hardware_mapping': 'classic-pi1'},
 ])
 def test_pi5_refuses_what_its_library_cannot_drive(api_v3_client, saved, board, body):
     board(PI5_MODEL)
@@ -296,6 +395,15 @@ def test_pi5_form_offers_only_supported_row_address_types(display_page, board):
     assert "can't be used on this Raspberry Pi 5" not in body
 
 
+def test_pi5_form_offers_only_mappings_it_can_drive(display_page, board):
+    board(PI5_MODEL)
+    body = display_page(_config_with())
+    assert 'classic-pi1' not in _option_values(body, 'hardware_mapping')
+    body = display_page(_config_with(hardware={'hardware_mapping': 'classic-pi1'}))
+    assert _selected_option(body, 'hardware_mapping') == ['classic-pi1']
+    assert 'can use on a Raspberry Pi 5' in body
+
+
 def test_other_boards_offer_every_row_address_type(display_page):
     body = display_page(_config_with())
     assert _option_values(body, 'row_address_type') == ['0', '1', '2', '3', '4', '5']

test/test_api_v3_lazy_plugin_discovery.py

@@ -31,6 +31,7 @@ sys.path.insert(0, str(Path(__file__).parent.parent))
 
 from src.config_manager import ConfigManager  # noqa: E402
 from src.plugin_system.plugin_manager import PluginManager  # noqa: E402
+from src.plugin_system.schema_manager import SchemaManager  # noqa: E402
 from test._api_v3_test_helpers import api_v3_client, api_v3_module  # noqa: F401,E402
 
 PLUGIN_ID = 'ledmatrix-stocks'
@@ -142,7 +143,10 @@ def test_toggle_finds_the_plugin(api_v3_client, api_v3_module, fresh_web_process
 
 
 def test_main_config_save_keeps_a_plugin_secret_out_of_config_json(
-        api_v3_client, api_v3_module, fresh_web_process, tmp_path):
+        api_v3_client, api_v3_module, fresh_web_process, plugins_dir, tmp_path):
+    # /config/main validates a plugin section like POST /plugins/config does,
+    # so it needs a real schema manager rather than the helper's mock.
+    api_v3_module.api_v3.schema_manager = SchemaManager(plugins_dir=plugins_dir)
     config_file = tmp_path / 'config.json'
     config_file.write_text('{}')
     secrets_file = tmp_path / 'config_secrets.json'

test/test_api_v3_partial_main_save.py

@@ -0,0 +1,288 @@
+"""POST /config/main: a partial JSON body changes only what it sends.
+
+The settings forms post every field, and a browser leaves an unchecked box out,
+so for a form a missing checkbox means False. JSON API clients send only what
+they change. Treating their missing keys as unchecked meant:
+
+- the MQTT bridge's Home Assistant brightness slider (``{"brightness": N}``)
+  turned off disable_hardware_pulsing, inverse_colors, show_refresh_rate and
+  use_short_date_format on every change;
+- the documented timezone/location update turned off web_display_autostart and
+  weekly automatic updates.
+
+The v3 forms post JSON as well (htmx json-enc), so they mark themselves with a
+hidden ``__form_section`` input; these tests pin both halves of that contract.
+
+Also here: the Vegas cycle-time fields no longer land in display_durations
+(and a blank one no longer 400s the Display save), the Raw JSON editor starts
+auto-update setup like the General form does, and both schedule POSTs accept
+the per-day shape their GETs return.
+"""
+
+import copy
+import json
+import re
+from pathlib import Path
+
+import pytest
+
+from test._api_v3_test_helpers import api_v3_client, api_v3_module  # noqa: F401
+
+REPO = Path(__file__).resolve().parent.parent
+PARTIALS = REPO / 'web_interface' / 'templates' / 'v3' / 'partials'
+
+STORED = {
+    'web_display_autostart': True,
+    'auto_update': {'enabled': True},
+    'timezone': 'America/Chicago',
+    'plugin_system': {'auto_discover': True, 'auto_load_enabled': True,
+                      'development_mode': True},
+    'display': {
+        'hardware': {'rows': 32, 'cols': 64, 'chain_length': 2, 'brightness': 90,
+                     'disable_hardware_pulsing': True, 'inverse_colors': True,
+                     'show_refresh_rate': True},
+        'runtime': {'gpio_slowdown': 4},
+        'use_short_date_format': True,
+        'double_sided': {'enabled': True, 'copies': 2, 'axis': 'horizontal'},
+        'vegas_scroll': {'enabled': True, 'auto_trim': True,
+                         'dynamic_duration_enabled': True,
+                         'continuous_scroll': True, 'smooth_scroll': True},
+    },
+}
+
+
+@pytest.fixture
+def saved(api_v3_module, monkeypatch):
+    captured = {}
+    api_v3_module.api_v3.config_manager.load_config.side_effect = \
+        lambda *a, **k: copy.deepcopy(STORED)
+
+    def fake_save(_manager, config, **_kwargs):
+        captured['config'] = config
+        return True, ''
+
+    monkeypatch.setattr(api_v3_module, '_save_config_atomic', fake_save)
+    from web_interface import auto_update
+    monkeypatch.setattr(auto_update, 'start_setup_if_needed', lambda *a, **k: None)
+    return captured
+
+
+def _post_json(client, body):
+    return client.post('/api/v3/config/main', data=json.dumps(body),
+                       content_type='application/json')
+
+
+class TestJsonPartialSaves:
+    def test_mqtt_bridge_brightness_changes_only_brightness(self, api_v3_client, saved):
+        # integrations/mqtt_bridge/ledmatrix_mqtt_bridge.py set_brightness
+        resp = _post_json(api_v3_client, {'brightness': 40})
+        assert resp.status_code == 200, resp.get_json()
+        display = saved['config']['display']
+        assert display['hardware']['brightness'] == 40
+        assert display['hardware']['disable_hardware_pulsing'] is True
+        assert display['hardware']['inverse_colors'] is True
+        assert display['hardware']['show_refresh_rate'] is True
+        assert display['use_short_date_format'] is True
+
+    def test_timezone_only_keeps_autostart_and_auto_update(self, api_v3_client, saved):
+        resp = _post_json(api_v3_client, {'timezone': 'UTC'})
+        assert resp.status_code == 200, resp.get_json()
+        config = saved['config']
+        assert config['timezone'] == 'UTC'
+        assert config['web_display_autostart'] is True
+        assert config['auto_update'] == {'enabled': True}
+
+    def test_location_only_keeps_autostart_and_auto_update(self, api_v3_client, saved):
+        resp = _post_json(api_v3_client, {'city': 'Paris', 'country': 'FR'})
+        assert resp.status_code == 200, resp.get_json()
+        config = saved['config']
+        assert config['location'] == {'city': 'Paris', 'country': 'FR'}
+        assert config['web_display_autostart'] is True
+        assert config['auto_update'] == {'enabled': True}
+
+    @pytest.mark.parametrize('key', ['auto_discover', 'auto_load_enabled', 'development_mode'])
+    def test_a_legacy_plugin_system_toggle_is_not_a_general_save(self, api_v3_client, saved, key):
+        # These left the General form; a client still sending one must not
+        # have the general-settings checkboxes treated as unchecked.
+        resp = api_v3_client.post('/api/v3/config/main', data={key: 'on'},
+                                  content_type='application/x-www-form-urlencoded')
+        assert resp.status_code == 200, resp.get_json()
+        assert saved['config']['web_display_autostart'] is True
+        assert saved['config']['auto_update'] == {'enabled': True}
+
+    def test_vegas_speed_only_keeps_vegas_toggles(self, api_v3_client, saved):
+        resp = _post_json(api_v3_client, {'vegas_scroll_speed': 80})
+        assert resp.status_code == 200, resp.get_json()
+        vegas = saved['config']['display']['vegas_scroll']
+        assert vegas['scroll_speed'] == 80
+        for key in ('enabled', 'auto_trim', 'dynamic_duration_enabled',
+                    'continuous_scroll', 'smooth_scroll'):
+            assert vegas[key] is True, key
+
+    def test_double_sided_axis_only_keeps_enabled(self, api_v3_client, saved):
+        resp = _post_json(api_v3_client, {'double_sided_axis': 'horizontal'})
+        assert resp.status_code == 200, resp.get_json()
+        assert saved['config']['display']['double_sided']['enabled'] is True
+
+    def test_json_can_still_turn_a_checkbox_off(self, api_v3_client, saved):
+        resp = _post_json(api_v3_client, {'inverse_colors': False, 'auto_update_enabled': False})
+        assert resp.status_code == 200, resp.get_json()
+        assert saved['config']['display']['hardware']['inverse_colors'] is False
+        assert saved['config']['display']['hardware']['disable_hardware_pulsing'] is True
+        assert saved['config']['auto_update'] == {'enabled': False}
+
+    def test_json_with_charset_is_still_json(self, api_v3_client, saved):
+        resp = api_v3_client.post('/api/v3/config/main', data=json.dumps({'brightness': 41}),
+                                  content_type='application/json; charset=utf-8')
+        assert resp.status_code == 200, resp.get_json()
+        assert saved['config']['display']['hardware']['brightness'] == 41
+        assert saved['config']['display']['hardware']['inverse_colors'] is True
+
+    def test_a_non_object_body_is_refused(self, api_v3_client, saved):
+        assert _post_json(api_v3_client, [1, 2]).status_code == 400
+
+
+class TestFormSavesStillUncheck:
+    """Unchecking a box in the UI must still save false."""
+
+    def test_marked_json_form_post_unchecks_missing_display_boxes(self, api_v3_client, saved):
+        resp = _post_json(api_v3_client, {'__form_section': 'display', 'brightness': '40',
+                                          'vegas_scroll_speed': '50'})
+        assert resp.status_code == 200, resp.get_json()
+        display = saved['config']['display']
+        for key in ('disable_hardware_pulsing', 'inverse_colors', 'show_refresh_rate'):
+            assert display['hardware'][key] is False, key
+        assert display['use_short_date_format'] is False
+        assert display['vegas_scroll']['enabled'] is False
+        assert '__form_section' not in saved['config']
+
+    def test_marked_json_form_post_keeps_checked_boxes(self, api_v3_client, saved):
+        resp = _post_json(api_v3_client, {'__form_section': 'display', 'brightness': '40',
+                                          'inverse_colors': 'on'})
+        assert resp.status_code == 200, resp.get_json()
+        assert saved['config']['display']['hardware']['inverse_colors'] is True
+        assert saved['config']['display']['hardware']['show_refresh_rate'] is False
+
+    def test_marked_general_form_unchecks_autostart_and_auto_update(self, api_v3_client, saved):
+        resp = _post_json(api_v3_client, {'__form_section': 'general', 'timezone': 'UTC'})
+        assert resp.status_code == 200, resp.get_json()
+        assert saved['config']['web_display_autostart'] is False
+        assert saved['config']['auto_update'] == {'enabled': False}
+
+    def test_form_encoded_post_unchecks_missing_boxes(self, api_v3_client, saved):
+        resp = api_v3_client.post('/api/v3/config/main', data={'brightness': '40'},
+                                  content_type='application/x-www-form-urlencoded')
+        assert resp.status_code == 200, resp.get_json()
+        assert saved['config']['display']['hardware']['inverse_colors'] is False
+
+    @pytest.mark.parametrize('partial', ['general.html', 'display.html', 'durations.html'])
+    def test_every_config_main_form_carries_the_marker(self, partial):
+        html = (PARTIALS / partial).read_text(encoding='utf-8')
+        form = re.search(r'<form hx-post="/api/v3/config/main".*?</form>', html, re.S)
+        assert form, f'{partial} no longer posts to /config/main'
+        assert re.search(r'<input type="hidden" name="__form_section" value="\w+">',
+                         form.group(0)), f'{partial} form lost its __form_section marker'
+
+
+class TestVegasCycleDurations:
+    def test_cycle_durations_are_not_display_durations(self, api_v3_client, saved):
+        resp = api_v3_client.post('/api/v3/config/main', data={
+            'vegas_scroll_enabled': 'on', 'vegas_min_cycle_duration': '90',
+            'vegas_max_cycle_duration': '300'})
+        assert resp.status_code == 200, resp.get_json()
+        display = saved['config']['display']
+        assert display['vegas_scroll']['min_cycle_duration'] == 90
+        assert display['vegas_scroll']['max_cycle_duration'] == 300
+        durations = display.get('display_durations', {})
+        assert 'vegas_min_cycle_duration' not in durations
+        assert 'vegas_max_cycle_duration' not in durations
+        assert 'vegas_min_cycle_duration' not in saved['config']
+
+    def test_blank_cycle_duration_does_not_reject_the_save(self, api_v3_client, saved):
+        resp = api_v3_client.post('/api/v3/config/main', data={
+            'vegas_scroll_enabled': 'on', 'vegas_scroll_speed': '60',
+            'vegas_min_cycle_duration': ''})
+        assert resp.status_code == 200, resp.get_json()
+        assert saved['config']['display']['vegas_scroll']['scroll_speed'] == 60
+
+    def test_real_display_durations_still_save(self, api_v3_client, saved):
+        resp = _post_json(api_v3_client, {'clock_duration': '45'})
+        assert resp.status_code == 200, resp.get_json()
+        assert saved['config']['display']['display_durations']['clock_duration'] == 45
+
+
+class TestRawSaveStartsAutoUpdateSetup:
+    @pytest.fixture
+    def raw_env(self, api_v3_module, monkeypatch):
+        cm = api_v3_module.api_v3.config_manager
+        cm.get_raw_file_content.return_value = {'timezone': 'UTC', 'auto_update': {'enabled': False}}
+        calls = []
+        from web_interface import auto_update
+        monkeypatch.setattr(auto_update, 'start_setup_if_needed',
+                            lambda was, config: calls.append((was, config)) or 'Setup note.')
+        return cm, calls
+
+    def test_enabling_from_raw_json_calls_setup(self, api_v3_client, raw_env):
+        cm, calls = raw_env
+        body = {'timezone': 'UTC', 'auto_update': {'enabled': True}}
+        resp = api_v3_client.post('/api/v3/config/raw/main', json=body)
+        assert resp.status_code == 200, resp.get_json()
+        cm.save_raw_file_content.assert_called_once_with('main', body)
+        assert calls == [(False, body)]
+        assert 'Setup note.' in resp.get_json()['message']
+
+    def test_previously_enabled_is_passed_through(self, api_v3_client, raw_env):
+        cm, calls = raw_env
+        cm.get_raw_file_content.return_value = {'auto_update': {'enabled': True}}
+        body = {'auto_update': {'enabled': True}}
+        assert api_v3_client.post('/api/v3/config/raw/main', json=body).status_code == 200
+        assert calls == [(True, body)]
+
+
+class TestSchedulesAcceptTheirGetShape:
+    PER_DAY = {
+        'enabled': True, 'mode': 'per-day', 'dim_brightness': 20,
+        'days': {
+            'monday': {'enabled': True, 'start_time': '21:15', 'end_time': '06:45'},
+            'tuesday': {'enabled': False},
+            'wednesday': {'enabled': True, 'start_time': '22:00', 'end_time': '05:30'},
+            'thursday': {'enabled': True, 'start_time': '20:00', 'end_time': '07:00'},
+            'friday': {'enabled': True, 'start_time': '23:00', 'end_time': '08:00'},
+            'saturday': {'enabled': True, 'start_time': '23:30', 'end_time': '09:00'},
+            'sunday': {'enabled': True, 'start_time': '21:00', 'end_time': '07:00'},
+        },
+    }
+
+    @pytest.fixture
+    def store(self, api_v3_module, monkeypatch):
+        state = {'config': {}}
+        api_v3_module.api_v3.config_manager.load_config.side_effect = \
+            lambda *a, **k: copy.deepcopy(state['config'])
+
+        def fake_save(_manager, config, **_kwargs):
+            state['config'] = copy.deepcopy(config)
+            return True, ''
+
+        monkeypatch.setattr(api_v3_module, '_save_config_atomic', fake_save)
+        return state
+
+    @pytest.mark.parametrize('route,section,extra', [
+        ('/api/v3/config/dim-schedule', 'dim_schedule', {'dim_brightness': 20}),
+        ('/api/v3/config/schedule', 'schedule', {}),
+    ])
+    def test_get_output_posts_back_unchanged(self, api_v3_client, store, route, section, extra):
+        body = {k: v for k, v in self.PER_DAY.items() if k != 'dim_brightness'}
+        body.update(extra)
+        store['config'] = {section: copy.deepcopy(body)}
+        read = api_v3_client.get(route).get_json()['data']
+        resp = api_v3_client.post(route, json=read)
+        assert resp.status_code == 200, resp.get_json()
+        assert store['config'][section]['days'] == body['days']
+
+    def test_flat_form_keys_still_work(self, api_v3_client, store):
+        body = {'enabled': True, 'mode': 'per-day', 'dim_brightness': 25,
+                'monday_enabled': 'on', 'monday_start': '19:00', 'monday_end': '06:00'}
+        resp = api_v3_client.post('/api/v3/config/dim-schedule', json=body)
+        assert resp.status_code == 200, resp.get_json()
+        assert store['config']['dim_schedule']['days']['monday'] == {
+            'enabled': True, 'start_time': '19:00', 'end_time': '06:00'}

test/test_auto_update.py

@@ -72,7 +72,7 @@ class Repo:
 
 
 def real_pull(device, **extra):
-    def core_update():
+    def core_update(**kwargs):
         before = git(device, 'rev-parse', 'HEAD')
         r = subprocess.run(['git', 'pull', '-q', '--rebase', '--autostash'],
                            cwd=str(device), capture_output=True, text=True)
@@ -339,6 +339,145 @@ class TestPreflightRefuses:
         assert repo.head() == old and h.sudo == []
 
 
+# -- what counts as a local change ---------------------------------------------
+
+def _device_with_plugin_and_script(tmp_path):
+    """A clone carrying a bundled plugin and an executable script, as LEDMatrix does."""
+    repo = Repo(tmp_path)
+    for rel, text in (('plugin-repos/web-ui-info/manager.py', 'x = 1\n'),
+                      ('web_interface/static/v3/js/plugins/store.js', 'var a;\n'),
+                      ('scripts/run.sh', 'echo hi\n')):
+        (repo.seed / rel).parent.mkdir(parents=True, exist_ok=True)
+        (repo.seed / rel).write_text(text)
+    # Executable on disk too, not only in the index: Repo.publish() commits
+    # with -a, which on Linux would otherwise record run.sh as 100644 upstream
+    # and hide the device's own mode change behind the pull.
+    import os
+    os.chmod(repo.seed / 'scripts' / 'run.sh', 0o755)
+    git(repo.seed, 'add', '.')
+    git(repo.seed, 'update-index', '--chmod=+x', 'scripts/run.sh')
+    git(repo.seed, 'commit', '-qm', 'layout')
+    git(repo.seed, 'push', '-q', 'origin', 'main')
+    git(repo.device, 'pull', '-q')
+    return repo
+
+
+def _chmod_like_the_installer(device):
+    """first_time_install.sh sets tracked 100755 files to 644: a mode-only change.
+
+    Windows has no exec bit, so there core.fileMode=true alone shows it."""
+    import os
+    git(device, 'config', 'core.fileMode', 'true')
+    os.chmod(device / 'scripts' / 'run.sh', 0o644)
+    assert 'mode change 100755 => 100644 scripts/run.sh' in git(device, 'diff', '--summary')
+
+
+@needs_git
+class TestLocalChangesAreCountedOnce:
+    """The preflight promises the pull will not stash. That holds only if both
+    count local changes the same way (auto_update.local_changes)."""
+
+    def test_mode_changes_and_plugin_folders_do_not_count(self, tmp_path):
+        repo = _device_with_plugin_and_script(tmp_path)
+        _chmod_like_the_installer(repo.device)
+        (repo.device / 'plugin-repos/web-ui-info/manager.py').write_text('x = 2  # store update\n')
+        assert au.local_changes(repo.device) == []
+
+    def test_a_core_folder_named_plugins_still_counts(self, tmp_path):
+        """The old filter matched 'plugins/' anywhere in the line."""
+        repo = _device_with_plugin_and_script(tmp_path)
+        (repo.device / 'web_interface/static/v3/js/plugins/store.js').write_text('var mine;\n')
+        assert au.local_changes(repo.device) == ['web_interface/static/v3/js/plugins/store.js']
+
+    def test_a_staged_rename_is_reported_by_its_new_name(self, tmp_path):
+        repo = Repo(tmp_path)
+        git(repo.device, 'mv', 'app.py', 'main.py')
+        assert au.local_changes(repo.device) == ['main.py']
+
+    def test_the_preflight_refuses_a_core_edit_under_a_plugins_folder(self, tmp_path):
+        repo = _device_with_plugin_and_script(tmp_path)
+        old = repo.head()
+        repo.publish()
+        (repo.device / 'web_interface/static/v3/js/plugins/store.js').write_text('var mine;\n')
+        result = Harness(tmp_path, repo).updater.run()
+        assert result['core_outcome'] == 'blocked'
+        assert 'store.js' in result['core_message']
+        assert repo.head() == old
+
+    @pytest.fixture
+    def core_update(self, monkeypatch):
+        """The real perform_core_update, pointed at a test clone."""
+        from web_interface.blueprints import api_v3 as pkg
+        from web_interface.blueprints.api_v3 import system
+
+        def point_at(device):
+            monkeypatch.setattr(system, 'PROJECT_ROOT', device)
+            monkeypatch.setattr(pkg.api_v3, 'plugin_store_manager', None, raising=False)
+            monkeypatch.setattr(system, '_pip_install_requirements',
+                                lambda *a, **k: pytest.fail('no requirements changed'))
+            return system.perform_core_update
+        return point_at
+
+    @pytest.mark.parametrize('change', [
+        'bundled_plugin_edit',
+        pytest.param('installer_chmod', marks=pytest.mark.skipif(
+            sys.platform == 'win32',
+            reason='no exec bit: the reset inside --autostash cannot clear a mode change, '
+                   'so git will not reapply it (on Linux it reapplies cleanly)')),
+    ])
+    def test_an_update_that_passed_the_preflight_leaves_no_stash(self, tmp_path, core_update, change):
+        """Found by audit: a bundled-plugin edit or the installer's chmods
+        passed the preflight, then perform_core_update stashed them for good.
+        Now --autostash carries them across the pull and puts them back."""
+        repo = _device_with_plugin_and_script(tmp_path)
+        new = repo.publish()
+        if change == 'installer_chmod':
+            _chmod_like_the_installer(repo.device)
+        else:
+            (repo.device / 'plugin-repos/web-ui-info/manager.py').write_text('x = 2  # store update\n')
+        h = Harness(tmp_path, repo, core_update=core_update(repo.device))
+        assert h.updater.preflight({})[0] == 'ready'
+
+        result = h.updater.run()
+        assert result['core_outcome'] == 'verifying', result['core_message']
+        assert repo.head() == new
+        assert git(repo.device, 'stash', 'list') == ''
+        if change == 'installer_chmod':
+            assert 'mode change 100755 => 100644 scripts/run.sh' in git(repo.device, 'diff', '--summary')
+        else:
+            assert 'store update' in (repo.device / 'plugin-repos/web-ui-info/manager.py').read_text()
+
+    def test_edits_made_after_the_preflight_are_refused_not_stashed(self, tmp_path, core_update):
+        repo = Repo(tmp_path)
+        old = repo.head()
+        repo.publish()
+        perform = core_update(repo.device)
+
+        def edit_then_update(**kwargs):
+            (repo.device / 'app.py').write_text('mine\n')
+            return perform(**kwargs)
+        result = Harness(tmp_path, repo, core_update=edit_then_update).updater.run()
+        assert result['core_outcome'] == 'blocked'
+        assert 'app.py' in result['core_message'] and 'will not stash' in result['core_message']
+        assert repo.head() == old
+        assert git(repo.device, 'stash', 'list') == ''
+        assert (repo.device / 'app.py').read_text() == 'mine\n'
+
+    def test_update_code_still_stashes_core_edits_but_not_plugin_folders(self, tmp_path, core_update):
+        repo = _device_with_plugin_and_script(tmp_path)
+        new = repo.publish()
+        (repo.device / 'scripts/run.sh').write_text('echo mine\n')
+        (repo.device / 'plugin-repos/web-ui-info/manager.py').write_text('x = 2  # store update\n')
+        payload = core_update(repo.device)()
+        assert payload['status'] == 'success', payload['message']
+        assert 'stashed' in payload['message']
+        assert repo.head() == new
+        assert 'LEDMatrix auto-stash before update' in git(repo.device, 'stash', 'list')
+        stashed = git(repo.device, 'stash', 'show', '--name-only', 'stash@{0}')
+        assert stashed.split() == ['scripts/run.sh']
+        assert 'store update' in (repo.device / 'plugin-repos/web-ui-info/manager.py').read_text()
+
+
 # -- the update and its hand-off to the health check ---------------------------
 
 @needs_git
@@ -395,7 +534,7 @@ class TestUpdateIsVerified:
         old = repo.head()
         repo.publish()
         h = Harness(tmp_path, repo,
-                    core_update=lambda: {'status': 'error', 'message': 'Update failed: network'})
+                    core_update=lambda **kw: {'status': 'error', 'message': 'Update failed: network'})
         result = h.updater.run()
         assert result['core_outcome'] == 'error'
         assert repo.head() == old
@@ -407,13 +546,43 @@ class TestUpdateIsVerified:
         repo.publish()
         pull = real_pull(repo.device)
 
-        def half_failed():
+        def half_failed(**kwargs):
             pull()
             return {'status': 'error', 'message': 'Update failed: interrupted'}
         result = Harness(tmp_path, repo, core_update=half_failed).updater.run()
         assert repo.head() == old
         assert 'rolled back' in result['core_message']
 
+    @pytest.mark.parametrize('how', ['partial_pull', 'check_never_started'])
+    def test_a_failed_rollback_leaves_plugins_and_the_display_alone(self, tmp_path, how):
+        """update_core returns rollback_failed itself on two paths. The device
+        is then in an unknown state, exactly as when the health check reports
+        rollback_failed, so no plugin updates and no restart may follow."""
+        repo = Repo(tmp_path)
+        repo.publish()
+        store = FakeStore(tmp_path / 'plugins', {'clock': '1.0.0'}, bump={'clock'})
+        pull = real_pull(repo.device)
+
+        def half_failed(**kwargs):
+            pull()
+            return {'status': 'error', 'message': 'Update failed: interrupted'}
+        h = Harness(tmp_path, repo, store=store, pickup=how != 'check_never_started',
+                    core_update=half_failed if how == 'partial_pull' else None)
+        real_run = h.updater.run_command
+
+        def reset_fails(args, **kwargs):
+            if args[:3] == ['git', 'reset', '--hard']:
+                return subprocess.CompletedProcess(args, 1, stdout='', stderr='index.lock exists')
+            return real_run(args, **kwargs)
+        h.updater.run_command = reset_fails
+
+        result = h.updater.run()
+        assert result['core_outcome'] == 'rollback_failed'
+        assert store.updated_calls == [], "plugins must not pile onto a core in an unknown state"
+        assert h.restarts == []
+        assert h.state['plugins_pending'] is False and result['plugins_deferred'] is False
+        assert h.state['alert']
+
 
 # -- reporting the health check's outcome --------------------------------------
 
@@ -668,7 +837,9 @@ class TestSettingsSave:
 
     def test_unchecked_toggle_on_general_save_disables(self, api_client):
         client, cm, setup_calls = api_client
-        resp = client.post('/api/v3/config/main', json={'timezone': 'UTC'})
+        # The General form marks its posts; an unchecked box is then absent.
+        resp = client.post('/api/v3/config/main',
+                           json={'__form_section': 'general', 'timezone': 'UTC'})
         assert resp.status_code == 200
         assert self._saved(cm)['auto_update'] == {'enabled': False}
         assert setup_calls == [True]

test/test_auto_update_verify.py

@@ -69,6 +69,8 @@ class FakeHost:
         self.running_head = None  # not restarted yet: still the old, healthy code
         self.restarts = []        # (unit, commit it was restarted onto)
         self.pip_installs = []
+        self.pip_timeouts = []
+        self.pip = None  # optional (args, host) -> result, or raises, instead of pip_ok
         self.now = 0.0
         self.nrestarts = 0
 
@@ -90,6 +92,9 @@ class FakeHost:
             return done(args, f'{self.nrestarts}\n')
         if args[0] == 'sudo' and any(a.endswith('safe_pip_install.sh') for a in args):
             self.pip_installs.append(args[-1])
+            self.pip_timeouts.append(kwargs.get('timeout'))
+            if self.pip:
+                return self.pip(args, self)
             return done(args, rc=0 if self.pip_ok else 1)
         if args[:4] == ['sudo', '-n', 'systemctl', 'restart']:
             if self.restart_failures:
@@ -171,6 +176,77 @@ def test_a_failed_dependency_reinstall_is_reported(tmp_path):
     assert 'Install Base Requirements' in result['detail']
 
 
+def _rollback_with_pip(tmp_path, pip, web_requirements_too=False):
+    """Roll back an update that changed the requirements, with pip faked by ``pip``."""
+    repo, old, new = updated_repo(tmp_path, new_requirements=True)
+    if web_requirements_too:
+        (repo / 'web_interface').mkdir()
+        (repo / 'web_interface' / 'requirements.txt').write_text('flask\n')
+        git(repo, 'add', '.')
+        git(repo, 'commit', '-qm', 'web reqs')
+        (repo / 'web_interface' / 'requirements.txt').write_text('flask\nnew\n')
+        (repo / 'requirements.txt').write_text('requests\nnewer\n')
+        git(repo, 'commit', '-qam', 'bump both')
+        old, new = git(repo, 'rev-parse', 'HEAD~1'), git(repo, 'rev-parse', 'HEAD')
+    host = FakeHost(repo, new)
+    host.pip = pip
+    ok, detail = host.verifier().rollback({'old_head': old, 'new_head': new})
+    return ok, detail, host
+
+
+def test_a_failed_pip_is_not_run_again_with_the_other_bash(tmp_path):
+    """Retrying after pip itself ran only repeats it, and every repeat can
+    take PIP_TIMEOUT_SECONDS of the unit's time limit."""
+    ok, detail, host = _rollback_with_pip(
+        tmp_path, lambda args, h: subprocess.CompletedProcess(args, 1, '', 'ERROR: No matching distribution'))
+    assert ok and 'requirements.txt' in detail
+    assert len(host.pip_installs) == 1
+
+
+def test_a_pip_timeout_is_not_retried(tmp_path):
+    def slow(args, h):
+        h.now += h.pip_timeouts[-1]
+        raise subprocess.TimeoutExpired(args, h.pip_timeouts[-1])
+    ok, detail, host = _rollback_with_pip(tmp_path, slow)
+    assert ok and 'Install Base Requirements' in detail
+    assert len(host.pip_installs) == 1
+
+
+def test_a_sudo_refusal_tries_the_next_bash(tmp_path):
+    def refused_once(args, h):
+        if len(h.pip_installs) == 1:
+            return subprocess.CompletedProcess(args, 1, '', 'sudo: a password is required')
+        return done(args)
+    ok, detail, host = _rollback_with_pip(tmp_path, refused_once)
+    assert ok and detail == ''
+    assert len(host.pip_installs) == 2
+
+
+def test_reinstalls_share_one_time_budget(tmp_path):
+    def hangs(args, h):
+        h.now += h.pip_timeouts[-1]
+        raise subprocess.TimeoutExpired(args, h.pip_timeouts[-1])
+    ok, detail, host = _rollback_with_pip(tmp_path, hangs, web_requirements_too=True)
+    assert ok and 'requirements.txt' in detail and 'web_interface/requirements.txt' in detail
+    assert sum(host.pip_timeouts) <= av.PIP_BUDGET_SECONDS
+    assert len(host.pip_installs) == 1, "the first file used the whole budget"
+
+
+def test_the_worst_case_fits_the_unit_time_limit():
+    """systemd kills the check at TimeoutStartSec, mid-rollback, and the update
+    then sits in "verifying" until the web interface calls it lost."""
+    from web_interface import auto_update as au
+    service = (ROOT / 'systemd' / 'ledmatrix-update-verify.service').read_text(encoding='utf-8')
+    minutes = int(re.search(r'^TimeoutStartSec=(\d+)min$', service, re.M).group(1))
+    assert av.WORST_CASE_SECONDS < minutes * 60
+    assert minutes * 60 < au.VERIFY_LOST_SECONDS, "the web UI must not call a running check lost"
+
+
+def test_sudo_refusal_wording_matches_permission_utils():
+    from src.common import permission_utils
+    assert set(av.SUDO_REFUSAL_PHRASES) == set(permission_utils.SUDO_REFUSAL_PHRASES)
+
+
 def test_still_broken_after_rolling_back_is_rollback_failed(tmp_path):
     code, result, host, head, old, new = check(tmp_path, 'always')
     assert code == 1 and result['status'] == 'rollback_failed'

test/test_background_data_service_espn_ranges.py

@@ -13,7 +13,12 @@ from unittest.mock import MagicMock, patch
 import pytest
 
 from src.background_data_service import BackgroundDataService
-from src.common.espn_dates import ESPN_MAX_LIMIT, parse_espn_date_range
+from src.common import espn_dates
+from src.common.espn_dates import (
+    ESPN_MAX_LIMIT,
+    fetch_espn_scoreboard,
+    parse_espn_date_range,
+)
 
 URL = "https://site.api.espn.com/apis/site/v2/sports/football/nfl/scoreboard"
 
@@ -50,6 +55,12 @@ class RangeRejectingSession:
         return FakeResponse(200, {"events": self.events_by_chunk.get(dates, [])})
 
 
+@pytest.fixture(autouse=True)
+def ranges_not_yet_rejected(monkeypatch):
+    # The "ranges are rejected" memo is process-wide; every test starts clean.
+    monkeypatch.setattr(espn_dates, "_ranges_rejected_until", 0.0)
+
+
 @pytest.fixture
 def cache():
     manager = MagicMock()
@@ -161,3 +172,42 @@ def test_a_400_on_a_single_day_is_still_a_failure(service, cache):
     assert not result.success
     assert len(session.calls) == 1
     cache.set.assert_not_called()
+
+
+def test_a_rejection_seen_by_the_service_is_remembered_for_scoreboards(service):
+    submit_and_wait(service, RangeRejectingSession({"202609": [{"id": "a"}]}),
+                    "20260901-20260930")
+
+    # A live scoreboard asking for a range next must not spend a doomed 400.
+    session = RangeRejectingSession({"202609": [{"id": "a"}]})
+    data = fetch_espn_scoreboard(session, URL, params={"dates": "20260901-20260930"})
+    assert [call["dates"] for call in session.calls] == ["202609"]
+    assert [event["id"] for event in data["events"]] == ["a"]
+
+
+def test_a_rejection_seen_by_a_scoreboard_skips_the_range_in_the_service(service, cache):
+    fetch_espn_scoreboard(RangeRejectingSession(), URL,
+                          params={"dates": "20260901-20260930"})
+
+    session = RangeRejectingSession({"202609": [{"id": "a"}]})
+    result = submit_and_wait(service, session, "20260901-20261001")
+    assert result.success, result.error
+    assert [call["dates"] for call in session.calls] == ["202609", "20261001"]
+
+
+def test_known_rejection_with_every_chunk_failing_asks_the_range_once(service, cache):
+    espn_dates._note_range_rejected()
+    session = RangeRejectingSession(fail_chunks={"202609"})
+    result = submit_and_wait(service, session, "20260901-20260930")
+
+    assert not result.success
+    # Chunks once, then the range for a real error -- not the chunks again.
+    assert [call["dates"] for call in session.calls] == ["202609", "20260901-20260930"]
+    cache.set.assert_not_called()
+
+
+def test_ranges_are_tried_again_once_the_memo_expires(service, monkeypatch):
+    monkeypatch.setattr(espn_dates, "_ranges_rejected_until", time.monotonic() - 1)
+    session = RangeRejectingSession({"202609": [{"id": "a"}]})
+    submit_and_wait(service, session, "20260901-20260930")
+    assert [call["dates"] for call in session.calls] == ["20260901-20260930", "202609"]

test/test_core_config_key_adopters.py

@@ -0,0 +1,108 @@
+"""Every "is this top-level key a plugin?" decision uses src/core_config_keys.py.
+
+#589 moved plugin-state reconciliation onto the shared list, but three private
+copies stayed behind and did not know about auto_update, dim_schedule, sync,
+location, target_fps, ...:
+
+- StartupValidator warned "Plugin 'auto_update' is enabled but not found in
+  plugins directory" on every display start with auto-update or a dim
+  schedule switched on;
+- SchemaManager.detect_config_key_collisions let a plugin id collide with
+  those sections silently;
+- ConfigManager.cleanup_orphaned_plugin_configs deleted display, schedule,
+  auto_update, ... as orphans, and validate_all_plugin_configs validated core
+  sections as plugins.
+"""
+
+import json
+import re
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+
+from src.config_manager import ConfigManager
+from src.core_config_keys import CORE_CONFIG_KEYS, CORE_SECRETS_KEYS
+from src.plugin_system.schema_manager import SchemaManager
+from src.startup_validator import StartupValidator
+
+REPO = Path(__file__).resolve().parent.parent
+
+
+class TestStartupValidator:
+    def test_enabled_core_sections_are_not_missing_plugins(self):
+        config = {
+            'display': {'hardware': {}},
+            'auto_update': {'enabled': True},
+            'dim_schedule': {'enabled': True},
+            'schedule': {'enabled': True},
+            'gone-plugin': {'enabled': True},
+        }
+        cm = MagicMock()
+        cm.get_config.return_value = config
+        pm = MagicMock()
+        pm.discover_plugins.return_value = []
+        validator = StartupValidator(cm, plugin_manager=pm, cache_manager=MagicMock())
+        validator.warnings = []
+        validator.errors = []
+        validator._validate_plugins()
+        missing = [w for w in validator.warnings if 'not found in plugins directory' in w]
+        assert missing == ["Plugin 'gone-plugin' is enabled but not found in plugins directory"]
+
+
+class TestReservedPluginIds:
+    @pytest.mark.parametrize('key', sorted(CORE_CONFIG_KEYS))
+    def test_every_core_key_is_reserved(self, key):
+        collisions = SchemaManager().detect_config_key_collisions([key])
+        assert [c['type'] for c in collisions] == ['reserved_key_collision']
+
+    def test_an_ordinary_plugin_id_is_not(self):
+        assert SchemaManager().detect_config_key_collisions(['clock-simple']) == []
+
+
+class TestConfigManagerHelpers:
+    @pytest.fixture
+    def manager(self, tmp_path):
+        config = {key: {'enabled': True} for key in ('display', 'schedule', 'auto_update',
+                                                      'dim_schedule', 'sync', 'location')}
+        config.update({'timezone': 'UTC', 'installed': {'enabled': True},
+                       'orphan': {'enabled': True}})
+        secrets = {'github': {'token': 't'}, 'youtube': {'api_key': 'k'},
+                   'installed': {'api_key': 'a'}, 'orphan': {'api_key': 'o'}}
+        (tmp_path / 'config.json').write_text(json.dumps(config))
+        (tmp_path / 'secrets.json').write_text(json.dumps(secrets))
+        manager = ConfigManager(config_path=str(tmp_path / 'config.json'),
+                                secrets_path=str(tmp_path / 'secrets.json'))
+        manager.template_path = str(tmp_path / 'no-template.json')
+        return manager
+
+    def test_cleanup_removes_only_real_orphans(self, manager, tmp_path):
+        removed = manager.cleanup_orphaned_plugin_configs(['installed'])
+        assert removed == ['orphan']
+        config = json.loads((tmp_path / 'config.json').read_text())
+        assert {'display', 'schedule', 'auto_update', 'dim_schedule', 'sync',
+                'location', 'timezone', 'installed'} == set(config)
+        secrets = json.loads((tmp_path / 'secrets.json').read_text())
+        assert set(secrets) == {'github', 'youtube', 'installed'}
+
+    def test_validate_all_skips_core_sections(self, manager):
+        schema_manager = MagicMock()
+        schema_manager.load_schema.return_value = None
+        results = manager.validate_all_plugin_configs(schema_manager)
+        assert set(results) == {'installed', 'orphan'}
+
+
+def test_core_secrets_keys_are_not_core_config_keys():
+    assert not (CORE_SECRETS_KEYS & CORE_CONFIG_KEYS)
+
+
+@pytest.mark.parametrize('relpath', [
+    'src/startup_validator.py',
+    'src/config_manager.py',
+    'src/plugin_system/schema_manager.py',
+])
+def test_no_private_copy_of_the_list_remains(relpath):
+    """The old copies all started with this literal; a new copy likely would too."""
+    source = (REPO / relpath).read_text(encoding='utf-8')
+    assert not re.search(r"""\[\s*['"]display['"]\s*,\s*['"]schedule['"]""", source), \
+        f'{relpath} has a private core-key list again; use src/core_config_keys.py'

test/test_display_geometry.py

@@ -142,3 +142,54 @@ def test_preview_callers_do_not_rederive_the_size():
         assert "get('chain_length', 1)" not in source, rel
         assert 'get("chain_length", 1)' not in source, rel
         assert 'cols * chain_length' not in source, rel
+
+
+# --- Pixel mappers ----------------------------------------------------------
+# RGBMatrix.width/height are measured after the library's pixel mappers
+# (lib/pixel-mapper.cc), so the preview has to apply them too. This used to
+# report 128x32 for a Rotate:90 chain the panel drew at 32x128.
+
+@pytest.mark.parametrize('hardware,expected', [
+    ({'pixel_mapper_config': 'Rotate:90'}, (32, 128)),
+    ({'pixel_mapper_config': 'Rotate:270'}, (32, 128)),
+    ({'pixel_mapper_config': 'Rotate:-90'}, (32, 128)),
+    ({'pixel_mapper_config': 'Rotate:180'}, (128, 32)),
+    ({'orientation': '90'}, (32, 128)),
+    ({'orientation': '270'}, (32, 128)),
+    ({'orientation': '180'}, (128, 32)),
+    # Two quarter turns cancel out.
+    ({'pixel_mapper_config': 'Rotate:90', 'orientation': '270'}, (128, 32)),
+    # U-mapper folds a chain of 4 into two rows: (256 / 64) * 32 by 2 * 32.
+    ({'chain_length': 4, 'pixel_mapper_config': 'U-mapper'}, (128, 64)),
+    ({'chain_length': 4, 'pixel_mapper_config': 'u-mapper;Rotate:90'}, (64, 128)),
+    # U-mapper needs an even chain of at least 2, or the library skips it.
+    ({'chain_length': 3, 'pixel_mapper_config': 'U-mapper'}, (192, 32)),
+    ({'cols': 32, 'chain_length': 4, 'pixel_mapper_config': 'V-mapper'}, (32, 128)),
+    ({'chain_length': 1, 'parallel': 2, 'pixel_mapper_config': 'StackToRow:Z'}, (128, 32)),
+    ({'pixel_mapper_config': 'Remap:64,64|0,0n|0,32n'}, (64, 64)),
+    # A Remap panel entirely outside the visible area: the library skips it.
+    ({'pixel_mapper_config': 'Remap:64,64|0,0n|0,99n'}, (128, 32)),
+    ({'pixel_mapper_config': 'Mirror:H'}, (128, 32)),
+    # Unknown or unusable mappers are skipped by the library.
+    ({'pixel_mapper_config': 'Bogus;Rotate:45;Rotate:ninety'}, (128, 32)),
+])
+def test_pixel_mappers_change_the_size_as_the_library_does(hardware, expected):
+    hw = {'rows': 32, 'cols': 64, 'chain_length': 2, 'parallel': 1}
+    hw.update(hardware)
+    assert physical_size(_config(hw)) == expected
+    assert logical_size(_config(hw)) == expected
+
+
+def test_double_sided_splits_the_mapped_size():
+    cfg = _config({'rows': 32, 'cols': 64, 'chain_length': 2, 'parallel': 1, 'orientation': '90'},
+                  {'enabled': True, 'copies': 2, 'axis': 'vertical'})
+    assert logical_size(cfg) == (32, 64)
+
+
+def test_display_manager_composes_the_mapper_config_it_sizes_from():
+    from src.display_geometry import compose_pixel_mapper_config
+    assert compose_pixel_mapper_config({}) == ''
+    assert compose_pixel_mapper_config({'orientation': '90'}) == 'Rotate:90'
+    assert compose_pixel_mapper_config(
+        {'pixel_mapper_config': ' U-mapper ', 'orientation': '180'}) == 'U-mapper;Rotate:180'
+    assert compose_pixel_mapper_config({'orientation': 'sideways'}) == ''

test/test_display_manager.py

@@ -265,6 +265,14 @@ class TestDisplayManagerOrientation:
             options = mock_rgb_matrix['options_class'].return_value
             assert options.pixel_mapper_config == ''
 
+    @pytest.mark.parametrize('orientation', ['90', '270'])
+    def test_sideways_orientation_appends_rotate_mapper(self, mock_rgb_matrix, orientation):
+        DisplayManager._instance = None
+        with patch.dict('os.environ', {'EMULATOR': 'false'}):
+            DisplayManager(self._config(orientation=orientation), suppress_test_pattern=True)
+            options = mock_rgb_matrix['options_class'].return_value
+            assert options.pixel_mapper_config == f'Rotate:{orientation}'
+
     def test_orientation_180_appends_rotate_mapper(self, mock_rgb_matrix):
         DisplayManager._instance = None
         with patch.dict('os.environ', {'EMULATOR': 'false'}):
@@ -281,10 +289,11 @@ class TestDisplayManagerOrientation:
             assert options.pixel_mapper_config == 'U-mapper;Rotate:180'
 
 
-class TestDisplayManagerPi5Guard:
+class TestDisplayManagerLibraryGuard:
-    """On a Pi 5 the library returns no matrix for settings its RP1 path can't
+    """For many settings it can't use the library returns no matrix (which the
-    drive, and the binding doesn't check, so the process would crash on its next
+    binding doesn't check, so the process crashes on its next call) or calls
-    call. DisplayManager has to refuse before creating the matrix and fall back."""
+    abort() -- on every board, with more on a Pi 5. DisplayManager has to refuse
+    before creating the matrix and fall back, reporting why."""
 
     def _config(self, **hardware_overrides):
         config = {
@@ -327,10 +336,95 @@ class TestDisplayManagerPi5Guard:
         mock_rgb_matrix['matrix_class'].assert_called_once()
         assert dm.matrix is not None
 
-    def test_other_boards_are_left_to_the_library(self, mock_rgb_matrix, board):
+    def test_pi5_only_limits_do_not_apply_to_other_boards(self, mock_rgb_matrix, board):
         board('Raspberry Pi 4 Model B Rev 1.5')
         DisplayManager._instance = None
         with patch.dict('os.environ', {'EMULATOR': 'false'}):
             dm = DisplayManager(self._config(row_address_type=5), suppress_test_pattern=True)
         mock_rgb_matrix['matrix_class'].assert_called_once()
         assert dm.matrix is not None
+
+    @pytest.fixture
+    def hw_status(self, tmp_path, monkeypatch):
+        """What DisplayManager writes to /tmp/led_matrix_hw_status.json."""
+        import json as _json
+        import tempfile as _tempfile
+        from src import display_manager as dm_module
+        written = {}
+        real_replace = os.replace
+        real_mkstemp = _tempfile.mkstemp
+
+        def fake_mkstemp(dir=None, prefix=None):
+            return real_mkstemp(dir=str(tmp_path), prefix=prefix)
+
+        def fake_replace(src, dst):
+            if str(dst).endswith('led_matrix_hw_status.json'):
+                with open(src) as f:
+                    written.update(_json.load(f))
+                os.remove(src)
+            else:
+                real_replace(src, dst)
+
+        monkeypatch.setattr(dm_module.tempfile, 'mkstemp', fake_mkstemp)
+        monkeypatch.setattr(dm_module.os, 'replace', fake_replace)
+        monkeypatch.setattr(dm_module.os.path, 'islink', lambda _p: False)
+        return written
+
+    @pytest.mark.parametrize('overrides,named', [
+        ({'hardware_mapping': 'adafruit-hat-pwm', 'parallel': 2}, 'parallel 2'),
+        ({'hardware_mapping': 'adafruit-hat', 'parallel': 3}, 'parallel 3'),
+        ({'hardware_mapping': 'adafruit-hat-pwn'}, 'adafruit-hat-pwn'),
+        ({'rows': 128}, 'rows 128'),
+        ({'chain_length': 300}, 'chain_length 300'),
+    ])
+    def test_hand_edited_setting_the_library_refuses_falls_back_on_any_board(
+            self, mock_rgb_matrix, board, hw_status, overrides, named):
+        board('Raspberry Pi 4 Model B Rev 1.5')
+        DisplayManager._instance = None
+        with patch.dict('os.environ', {'EMULATOR': 'false'}):
+            dm = DisplayManager(self._config(**overrides), suppress_test_pattern=True)
+        mock_rgb_matrix['matrix_class'].assert_not_called()
+        assert dm.matrix is None
+        assert hw_status['ok'] is False
+        assert hw_status['cause'] == 'settings'
+        assert named in hw_status['error']
+
+    def test_library_failure_is_reported_as_the_library(self, mock_rgb_matrix, board, hw_status):
+        board('Raspberry Pi 4 Model B Rev 1.5')
+        mock_rgb_matrix['matrix_class'].side_effect = RuntimeError('boom')
+        DisplayManager._instance = None
+        with patch.dict('os.environ', {'EMULATOR': 'false'}):
+            dm = DisplayManager(self._config(), suppress_test_pattern=True)
+        assert dm.matrix is None
+        assert hw_status == {'ok': False, 'error': 'boom', 'cause': 'library'}
+
+    def test_success_reports_no_cause(self, mock_rgb_matrix, board, hw_status):
+        board('Raspberry Pi 4 Model B Rev 1.5')
+        DisplayManager._instance = None
+        with patch.dict('os.environ', {'EMULATOR': 'false'}):
+            DisplayManager(self._config(), suppress_test_pattern=True)
+        assert hw_status == {'ok': True, 'error': None, 'cause': None}
+
+    def test_emulator_warns_but_still_starts(self, mock_rgb_matrix, board, caplog):
+        board('Raspberry Pi 4 Model B Rev 1.5')
+        DisplayManager._instance = None
+        with patch.dict('os.environ', {'EMULATOR': 'true'}):
+            dm = DisplayManager(self._config(rows=128), suppress_test_pattern=True)
+        mock_rgb_matrix['matrix_class'].assert_called_once()
+        assert dm.matrix is not None
+        assert 'rows 128' in caplog.text
+
+    def test_refused_settings_advice_does_not_send_users_to_rebuild(self, board):
+        """The Pi 5 rebuild / GPIO slowdown hint used to follow every failure,
+        including settings LEDMatrix itself refused."""
+        from src.matrix_support import MatrixSettingsRefused
+        board('Raspberry Pi 5 Model B Rev 1.0')
+        advice = DisplayManager._fallback_advice(
+            'settings', MatrixSettingsRefused('row address type 5'))
+        assert 'Display tab' in advice
+        assert 'first_time_install' not in advice and 'slowdown' not in advice
+        library = DisplayManager._fallback_advice('library', RuntimeError('mmap failed'))
+        assert 'RPI_RGB_FORCE_REBUILD=1' in library
+        board('Raspberry Pi 4 Model B Rev 1.5')
+        assert 'RPI_RGB_FORCE_REBUILD' not in DisplayManager._fallback_advice(
+            'library', RuntimeError('boom'))

test/test_matrix_support.py

@@ -0,0 +1,125 @@
+"""The library-refusal rules in src/matrix_support.py mirror the pinned library.
+
+rpi-rgb-led-matrix-master at 1ee4f76: RGBMatrix::Options::Validate in
+lib/options-initialize.cc, the runtime checks in RGBMatrix::CreateFromOptions
+(lib/led-matrix.cc), the mapping table in lib/hardware-mapping.c with the
+abort()s in lib/framebuffer.cc, and the setter types in
+bindings/python/rgbmatrix/core.pyx. When the submodule is bumped and those
+change, these are the cases to revisit.
+"""
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from src import matrix_support as ms  # noqa: E402
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+
+
+def _messages(hardware, runtime=None, pi5=False):
+    return [r.message for r in ms.library_refusals(hardware, runtime, pi5=pi5)]
+
+
+def test_the_config_template_starts():
+    template = json.loads((REPO_ROOT / 'config' / 'config.template.json').read_text(encoding='utf-8'))
+    display = template['display']
+    assert ms.library_refusals(display['hardware'], display['runtime']) == []
+    assert ms.library_refusals(display['hardware'], display['runtime'], pi5=True) == []
+
+
+def test_display_manager_defaults_start():
+    assert ms.library_refusals({}) == []
+
+
+@pytest.mark.parametrize('hardware', [
+    {'rows': 8}, {'rows': 64}, {'cols': 16}, {'cols': 1024},
+    {'chain_length': 1}, {'chain_length': 255},
+    {'hardware_mapping': 'regular', 'parallel': 3},
+    {'hardware_mapping': 'classic', 'parallel': 3},
+    {'hardware_mapping': 'REGULAR', 'parallel': 2},
+    {'hardware_mapping': '', 'parallel': 3},  # empty reads as "regular"
+    {'hardware_mapping': 'classic-pi1'},
+    {'hardware_mapping': 'regular-pi1', 'parallel': 1},
+    {'pwm_bits': 11}, {'pwm_dither_bits': 2}, {'pwm_lsb_nanoseconds': 3000},
+    {'row_address_type': 5}, {'multiplexing': 22}, {'scan_mode': 1},
+    {'brightness': 1}, {'limit_refresh_rate_hz': 0},
+    {'led_rgb_sequence': 'bgr'}, {'led_rgb_sequence': 'GBR'},
+    # Not a number: left to the binding, which raises a TypeError.
+    {'rows': 'thirty-two'},
+])
+def test_what_the_library_starts_with(hardware):
+    assert ms.library_refusals(hardware) == []
+
+
+@pytest.mark.parametrize('hardware,runtime,named', [
+    ({'rows': 66}, None, 'rows 66'),
+    ({'rows': 128}, None, 'rows 128'),
+    ({'rows': 31}, None, 'rows 31'),
+    ({'cols': 8}, None, 'cols 8'),
+    ({'chain_length': 0}, None, 'chain_length 0'),
+    ({'chain_length': 256}, None, 'chain_length 256'),  # uint8_t setter
+    ({'hardware_mapping': 'regular', 'parallel': 4}, None, 'parallel 4'),
+    ({'hardware_mapping': 'adafruit-hat-pwm', 'parallel': 2}, None, 'which has 1 output'),
+    ({'hardware_mapping': 'adafruit-hat', 'parallel': 3}, None, 'which has 1 output'),
+    ({'hardware_mapping': 'regular-pi1', 'parallel': 2}, None, 'which has 1 output'),
+    ({'hardware_mapping': 'classic-pi1', 'parallel': 2}, None, 'which has 1 output'),
+    ({'parallel': 2}, None, 'adafruit-hat-pwm'),  # DisplayManager's default mapping
+    ({'hardware_mapping': 'adafruit-hat-pwn'}, None, '"adafruit-hat-pwn"'),
+    ({'hardware_mapping': 'compute-module'}, None, '"compute-module"'),
+    ({'hardware_mapping': None}, None, 'hardware mapping None'),
+    ({'brightness': 0}, None, 'brightness 0'),
+    ({'pwm_bits': 12}, None, 'pwm_bits 12'),
+    ({'pwm_dither_bits': 3}, None, 'pwm_dither_bits 3'),
+    ({'pwm_lsb_nanoseconds': 49}, None, 'pwm_lsb_nanoseconds 49'),
+    ({'row_address_type': 6}, None, 'row_address_type 6'),
+    ({'multiplexing': 23}, None, 'multiplexing 23'),
+    ({'scan_mode': 2}, None, 'scan_mode 2'),
+    ({'led_rgb_sequence': 'RGBW'}, None, 'LED RGB sequence'),
+    ({'led_rgb_sequence': 'RRB'}, None, 'LED RGB sequence'),
+    ({}, {'gpio_slowdown': 11}, 'gpio_slowdown 11'),
+    ({}, {'gpio_slowdown': -1}, 'gpio_slowdown -1'),
+    ({}, {'rp1_rio': 2}, 'rp1_rio 2'),
+])
+def test_what_it_refuses(hardware, runtime, named):
+    messages = _messages(hardware, runtime)
+    assert any(named in m for m in messages), messages
+
+
+def test_pi5_limits_apply_only_on_a_pi5():
+    assert ms.library_refusals({'row_address_type': 5}) == []
+    refusals = ms.library_refusals({'row_address_type': 5}, pi5=True)
+    assert len(refusals) == 1 and refusals[0].pi5
+    assert set(refusals[0].fields) == {'row_address_type', 'parallel', 'hardware_mapping'}
+
+
+def test_refusal_names_the_fields_involved():
+    (refusal,) = ms.library_refusals({'hardware_mapping': 'adafruit-hat', 'parallel': 2})
+    assert set(refusal.fields) == {'parallel', 'hardware_mapping'}
+    (refusal,) = ms.library_refusals({'rows': 128})
+    assert refusal.fields == ('rows',)
+
+
+def test_message_names_every_problem():
+    message = ms.refusal_message(ms.library_refusals(
+        {'rows': 128, 'row_address_type': 5}, {'gpio_slowdown': 11}, pi5=True))
+    assert message.startswith("The installed rgbmatrix library can't start")
+    assert 'rows 128' in message and 'gpio_slowdown 11' in message
+    assert 'Raspberry Pi 5' in message and 'row address type 5' in message
+    assert ms.refusal_message([]) is None
+
+
+def test_non_mapping_sections_are_treated_as_empty():
+    assert ms.library_refusals('oops', ['a']) == []
+
+
+def test_display_manager_defaults_match_display_manager():
+    """The guard fills missing keys the way DisplayManager._setup_matrix does."""
+    source = (REPO_ROOT / 'src' / 'display_manager.py').read_text(encoding='utf-8')
+    for field, value in ms.DISPLAY_MANAGER_DEFAULTS.items():
+        if field in ('rows', 'cols', 'chain_length', 'parallel'):
+            continue  # read through display_geometry's DEFAULT_* constants
+        assert f"get('{field}', {value!r})" in source, field

test/test_path_traversal_guards.py

@@ -315,3 +315,202 @@ class TestPluginVersionLookup:
             assert module._get_plugin_version("..") == ""
         finally:
             module.api_v3.plugin_store_manager = original
+
+
+PNG = b"\x89PNG\r\n\x1a\n" + b"0" * 20
+
+
+class TestPluginAssetRoutes:
+    """/api/v3/plugins/assets/upload, /list and /delete
+
+    All three joined a request-supplied plugin_id straight onto
+    assets/plugins, so '../../config' created an uploads directory under
+    config/, wrote images and .metadata.json there, listed it, and deleted
+    whatever file a metadata entry's path named. #561 fixed only the route
+    that serves the uploaded files.
+    """
+
+    @pytest.fixture
+    def project(self, tmp_path, api_v3_module, monkeypatch):
+        import web_interface.blueprints.api_v3.plugins as plugins_module
+
+        monkeypatch.setattr(plugins_module, "PROJECT_ROOT", tmp_path)
+        (tmp_path / "config").mkdir()
+        secrets = tmp_path / "config" / "config_secrets.json"
+        secrets.write_text('{"api_key":"hunter2"}', encoding="utf-8")
+        return tmp_path, secrets
+
+    def _upload(self, client, plugin_id):
+        import io
+
+        return client.post(
+            "/api/v3/plugins/assets/upload",
+            data={"plugin_id": plugin_id, "files": (io.BytesIO(PNG), "x.png")},
+            content_type="multipart/form-data",
+        )
+
+    def _tree(self, root):
+        return sorted(str(p.relative_to(root)) for p in root.rglob("*"))
+
+    def test_an_ordinary_upload_list_and_delete_still_work(self, api_v3_client, project):
+        root, _ = project
+        response = self._upload(api_v3_client, "static-image")
+        assert response.status_code == 200, response.get_json()
+        uploaded = response.get_json()["uploaded_files"][0]
+        assert uploaded["path"].startswith("assets/plugins/static-image/uploads/")
+        stored = root / uploaded["path"]
+        assert stored.exists()
+
+        listed = api_v3_client.get(
+            "/api/v3/plugins/assets/list", query_string={"plugin_id": "static-image"}
+        )
+        assert listed.status_code == 200
+        assert [a["id"] for a in listed.get_json()["data"]["assets"]] == [uploaded["id"]]
+
+        deleted = api_v3_client.post(
+            "/api/v3/plugins/assets/delete",
+            json={"plugin_id": "static-image", "image_id": uploaded["id"]},
+        )
+        assert deleted.status_code == 200
+        assert not stored.exists()
+
+    @pytest.mark.parametrize("plugin_id", [
+        "../../config", "..", "a/b", "/abs", "x" + BACKSLASH + "y", "C:",
+    ])
+    def test_a_traversing_upload_writes_nothing(self, api_v3_client, project, plugin_id):
+        root, _ = project
+        before = self._tree(root)
+        response = self._upload(api_v3_client, plugin_id)
+        assert response.status_code == 400
+        assert self._tree(root) == before
+
+    def test_a_traversing_list_reads_nothing(self, api_v3_client, project):
+        root, _ = project
+        outside = root / "config" / "uploads"
+        outside.mkdir()
+        (outside / ".metadata.json").write_text(
+            json.dumps({"i": {"id": "i", "path": "leaked"}}), encoding="utf-8"
+        )
+        response = api_v3_client.get(
+            "/api/v3/plugins/assets/list", query_string={"plugin_id": "../../config"}
+        )
+        assert response.status_code == 400
+        assert b"leaked" not in response.data
+
+    def test_a_traversing_delete_deletes_nothing(self, api_v3_client, project):
+        root, secrets = project
+        outside = root / "config" / "uploads"
+        outside.mkdir()
+        (outside / ".metadata.json").write_text(
+            json.dumps({"i": {"id": "i", "path": "config/config_secrets.json"}}),
+            encoding="utf-8",
+        )
+        response = api_v3_client.post(
+            "/api/v3/plugins/assets/delete",
+            json={"plugin_id": "../../config", "image_id": "i"},
+        )
+        assert response.status_code == 400
+        assert secrets.exists(), "file outside assets/plugins was deleted"
+
+    @pytest.mark.parametrize("stored_path", [
+        "config/config_secrets.json",
+        "assets/plugins/static-image/uploads/../../../../config/config_secrets.json",
+        "assets/plugins/other/uploads/x.png",
+        None,
+    ])
+    def test_a_metadata_path_outside_the_uploads_is_never_unlinked(
+        self, api_v3_client, project, stored_path
+    ):
+        root, secrets = project
+        uploads = root / "assets" / "plugins" / "static-image" / "uploads"
+        uploads.mkdir(parents=True)
+        other = root / "assets" / "plugins" / "other" / "uploads"
+        other.mkdir(parents=True)
+        (other / "x.png").write_bytes(PNG)
+        (uploads / ".metadata.json").write_text(
+            json.dumps({"i": {"id": "i", "path": stored_path}}), encoding="utf-8"
+        )
+        response = api_v3_client.post(
+            "/api/v3/plugins/assets/delete",
+            json={"plugin_id": "static-image", "image_id": "i"},
+        )
+        assert response.status_code == 200
+        assert secrets.exists(), "file named by tampered metadata was deleted"
+        assert (other / "x.png").exists(), "another plugin's upload was deleted"
+        # The bad entry is still dropped, so the UI can get rid of it.
+        assert json.loads((uploads / ".metadata.json").read_text(encoding="utf-8")) == {}
+
+
+class TestPluginActionDirectory:
+    """POST /api/v3/plugins/action runs a script named by the manifest in
+    get_plugin_directory(plugin_id), and plugin_id is the request body's.
+    get_plugin_directory joined it onto plugins_dir unchecked, so
+    '../elsewhere' ran a script from any directory holding a manifest.
+    """
+
+    @pytest.fixture
+    def tree(self, tmp_path):
+        import threading
+
+        from src.plugin_system.plugin_manager import PluginManager
+
+        plugins = tmp_path / "plugin-repos"
+        (plugins / "demo").mkdir(parents=True)
+        (plugins / "ledmatrix-legacy").mkdir()
+        outside = tmp_path / "elsewhere"
+        outside.mkdir()
+        (outside / "manifest.json").write_text(json.dumps({
+            "web_ui_actions": [{"id": "go", "type": "script", "script": "s.py"}],
+        }), encoding="utf-8")
+        marker = tmp_path / "PWNED"
+        (outside / "s.py").write_text(
+            "open(%r, 'w').write('ran')\n" % str(marker), encoding="utf-8"
+        )
+        manager = MagicMock()
+        manager.plugins_dir = plugins
+        manager._discovery_lock = threading.Lock()
+        manager.plugin_directories = {}
+        manager.get_plugin_directory = (
+            lambda pid: PluginManager.get_plugin_directory(manager, pid)
+        )
+        return manager, plugins, marker
+
+    def test_real_plugin_directories_are_still_found(self, tree):
+        manager, plugins, _ = tree
+        assert manager.get_plugin_directory("demo") == str(plugins / "demo")
+        assert manager.get_plugin_directory("legacy") == str(plugins / "ledmatrix-legacy")
+        assert manager.get_plugin_directory("nope") is None
+
+    def test_a_discovered_plugin_is_returned_from_the_registry(self, tree, tmp_path):
+        manager, _, _ = tree
+        manager.plugin_directories = {"linked": tmp_path / "somewhere"}
+        assert manager.get_plugin_directory("linked") == str(tmp_path / "somewhere")
+
+    @pytest.mark.parametrize("plugin_id", [
+        "..", "../elsewhere", "a/b", "/abs", "x" + BACKSLASH + "..", "",
+    ])
+    def test_get_plugin_directory_refuses_anything_but_a_plain_name(self, tree, plugin_id):
+        manager, _, _ = tree
+        assert manager.get_plugin_directory(plugin_id) is None
+
+    def test_the_action_endpoint_runs_nothing_outside_the_plugins_dir(
+        self, api_v3_client, api_v3_module, tree
+    ):
+        manager, _, marker = tree
+        api_v3_module.api_v3.plugin_manager = manager
+        response = api_v3_client.post(
+            "/api/v3/plugins/action",
+            json={"plugin_id": "../elsewhere", "action_id": "go", "params": {}},
+        )
+        assert response.status_code == 400
+        assert not marker.exists(), "script outside the plugins directory ran"
+
+    def test_the_fallback_without_a_plugin_manager_is_guarded_too(
+        self, api_v3_client, api_v3_module
+    ):
+        api_v3_module.api_v3.plugin_manager = None
+        response = api_v3_client.post(
+            "/api/v3/plugins/action",
+            json={"plugin_id": "../elsewhere", "action_id": "go", "params": {}},
+        )
+        assert response.status_code == 400

test/test_plugin_config_preparation.py

@@ -0,0 +1,205 @@
+"""One preparation for a plugin's config, wherever the config comes from.
+
+A plugin's stored section becomes the config it runs with through
+schema_manager.prepare_plugin_config: legacy booleans (#588) read as
+``{"enabled": ...}`` objects, then schema and core defaults filled in. Loading
+did that; hot reload handed plugins the raw section instead (a legacy
+``dynamic_duration: true`` came back as a boolean, turning dynamic duration
+off), and the dev tools each built configs their own way:
+
+- dev_server read only top-level defaults and let a schema ``enabled: false``
+  override its forced ``enabled: True``;
+- check_plugin/render_plugin (build_full_config) merged overrides with
+  dict.update, so ``{"nhl": {"enabled": true}}`` dropped every other nhl
+  default;
+- the harness and the device disagreed on object and array defaults.
+
+The web saves and GET are covered in
+test/web_interface/test_plugin_config_json_saves.py.
+"""
+
+import importlib.util
+import json
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+
+from src.plugin_system.plugin_manager import PluginManager
+from src.plugin_system.schema_manager import (
+    CORE_PLUGIN_PROPERTIES, SchemaManager, extract_schema_defaults,
+)
+from src.plugin_system.testing import loading
+
+REPO = Path(__file__).resolve().parent.parent
+
+SCHEMA = {
+    "type": "object",
+    "properties": {
+        "enabled": {"type": "boolean", "default": False},
+        "global": {
+            "type": "object",
+            "properties": {
+                "dynamic_duration": {
+                    "type": "object",
+                    "properties": {
+                        "enabled": {"type": "boolean", "default": True},
+                        "max_duration_seconds": {"type": "integer", "default": 300},
+                    },
+                },
+            },
+        },
+        "nhl": {
+            "type": "object",
+            "properties": {
+                "enabled": {"type": "boolean", "default": False},
+                "favorite_teams": {"type": "array", "default": ["TB"]},
+                "show_records": {"type": "boolean", "default": True},
+            },
+        },
+        "colors": {
+            "type": "object",
+            "default": {"text": [255, 255, 255]},
+            "properties": {"text": {"type": "array", "default": [1, 2, 3]}},
+        },
+        "feeds": {"type": "array", "items": {"type": "string"}},
+    },
+}
+
+
+@pytest.fixture
+def plugin_dir(tmp_path):
+    pdir = tmp_path / "plugins" / "demo"
+    pdir.mkdir(parents=True)
+    (pdir / "config_schema.json").write_text(json.dumps(SCHEMA))
+    (pdir / "manifest.json").write_text(json.dumps({"id": "demo"}))
+    return pdir
+
+
+@pytest.fixture
+def plugin_manager(plugin_dir, tmp_path):
+    manager = PluginManager.__new__(PluginManager)  # skip the heavy constructor
+    manager.logger = MagicMock()
+    manager.schema_manager = SchemaManager(plugins_dir=plugin_dir.parent, project_root=tmp_path)
+    return manager
+
+
+class TestPluginManagerPreparation:
+    def test_legacy_boolean_and_defaults(self, plugin_manager):
+        prepared = plugin_manager.prepare_plugin_config(
+            "demo", {"enabled": True, "global": {"dynamic_duration": True}})
+        assert prepared["global"]["dynamic_duration"] == {
+            "enabled": True, "max_duration_seconds": 300}
+        assert prepared["nhl"]["favorite_teams"] == ["TB"]
+        assert prepared["display_duration"] == 15
+
+    def test_does_not_mutate_the_raw_section(self, plugin_manager):
+        raw = {"global": {"dynamic_duration": True}}
+        plugin_manager.prepare_plugin_config("demo", raw)
+        assert raw == {"global": {"dynamic_duration": True}}
+
+    def test_never_raises(self, plugin_manager):
+        plugin_manager.schema_manager = MagicMock()
+        plugin_manager.schema_manager.load_schema.return_value = SCHEMA
+        plugin_manager.schema_manager.prepare_plugin_config.side_effect = RuntimeError("boom")
+        prepared = plugin_manager.prepare_plugin_config("demo", {"global": {"dynamic_duration": False}})
+        assert prepared["global"]["dynamic_duration"] == {"enabled": False}
+
+
+class TestHotReload:
+    def test_on_config_change_gets_the_prepared_config(self, test_display_controller, plugin_manager):
+        controller = test_display_controller
+        plugin = MagicMock()
+        plugin.modes = ["demo"]
+        pm = controller.plugin_manager
+        pm.discover_plugins.return_value = ["demo"]
+        pm.load_plugin.return_value = True
+        pm.plugin_manifests = {}
+        pm.get_plugin.side_effect = lambda pid: plugin if pid == "demo" else None
+        pm.prepare_plugin_config.side_effect = plugin_manager.prepare_plugin_config
+        controller.config_service.get_config = lambda: {"demo": {"enabled": True}}
+        controller._reconcile_enabled_plugins()
+
+        callback = controller._plugin_config_callbacks["demo"]
+        callback({"enabled": True}, {"enabled": True, "global": {"dynamic_duration": True}})
+
+        new_config = plugin.on_config_change.call_args[0][0]
+        assert new_config["global"]["dynamic_duration"] == {
+            "enabled": True, "max_duration_seconds": 300}
+        assert new_config["nhl"]["show_records"] is True
+
+    def test_raw_section_still_delivered_without_a_preparer(self, test_display_controller):
+        controller = test_display_controller
+        plugin = MagicMock()
+        plugin.modes = ["demo"]
+        pm = controller.plugin_manager
+        pm.discover_plugins.return_value = ["demo"]
+        pm.load_plugin.return_value = True
+        pm.plugin_manifests = {}
+        pm.get_plugin.side_effect = lambda pid: plugin if pid == "demo" else None
+        pm.prepare_plugin_config.return_value = None
+        controller.config_service.get_config = lambda: {"demo": {"enabled": True}}
+        controller._reconcile_enabled_plugins()
+
+        raw = {"enabled": False}
+        controller._plugin_config_callbacks["demo"]({}, raw)
+        plugin.on_config_change.assert_called_once_with(raw)
+
+
+class TestDevToolsMatchTheDevice:
+    def test_harness_defaults_are_the_device_defaults(self, plugin_dir):
+        assert loading.load_config_defaults(plugin_dir) == extract_schema_defaults(SCHEMA)
+        defaults = loading.load_config_defaults(plugin_dir)
+        # An object's own default wins, as on a device; arrays start empty
+        assert defaults["colors"] == {"text": [255, 255, 255]}
+        assert defaults["feeds"] == []
+
+    def test_nested_override_keeps_sibling_defaults(self, plugin_dir):
+        config = loading.build_full_config(plugin_dir, cli_config={"nhl": {"enabled": True}})
+        assert config["nhl"] == {"enabled": True, "favorite_teams": ["TB"], "show_records": True}
+
+    def test_spec_and_cli_overrides_both_deep_merge(self, plugin_dir):
+        config = loading.build_full_config(
+            plugin_dir, spec={"config": {"nhl": {"show_records": False}}},
+            cli_config={"nhl": {"enabled": True}})
+        assert config["nhl"] == {"enabled": True, "favorite_teams": ["TB"], "show_records": False}
+
+    def test_build_config_matches_the_device_load(self, plugin_dir, plugin_manager):
+        overrides = {"enabled": True, "global": {"dynamic_duration": False}}
+        assert loading.build_config(plugin_dir, overrides) == \
+            plugin_manager.prepare_plugin_config("demo", overrides)
+
+    def test_core_defaults_are_present(self, plugin_dir):
+        config = loading.build_full_config(plugin_dir)
+        assert config["enabled"] is True
+        assert config["display_duration"] == CORE_PLUGIN_PROPERTIES["display_duration"]["default"]
+        assert config["live_priority"] is False
+
+    def test_render_plugin_matrix_config(self, plugin_dir, monkeypatch):
+        from src.plugin_system.testing import harness
+        seen = {}
+
+        def fake_render_size(plugin_id, manifest, pdir, config, *args, **kwargs):
+            seen["config"] = config
+            return []
+
+        monkeypatch.setattr(harness, "_render_size", fake_render_size)
+        harness.render_plugin_matrix("demo", plugin_dir, config={"nhl": {"enabled": True}},
+                                     sizes=[(64, 32)], run_update=False)
+        assert seen["config"]["enabled"] is True, "a schema enabled:false must not win"
+        assert seen["config"]["nhl"]["favorite_teams"] == ["TB"]
+
+    def test_dev_server_render_config(self, plugin_dir, monkeypatch):
+        spec = importlib.util.spec_from_file_location("dev_server_under_test",
+                                                      REPO / "scripts" / "dev_server.py")
+        dev_server = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(dev_server)
+        monkeypatch.setattr(dev_server, "find_plugin_dir", lambda pid: plugin_dir)
+        monkeypatch.setattr(dev_server, "_trusted_plugin_dir", lambda d: plugin_dir)
+
+        _, _, config, _, _ = dev_server._parse_render_request(
+            {"plugin_id": "demo", "config": {"nhl": {"enabled": True}}})
+        assert config["enabled"] is True, "a schema enabled:false must not win"
+        assert config["nhl"] == {"enabled": True, "favorite_teams": ["TB"], "show_records": True}
+        assert config["global"]["dynamic_duration"]["max_duration_seconds"] == 300
+        assert dev_server.load_config_defaults(plugin_dir) == extract_schema_defaults(SCHEMA)

test/test_plugin_system_legacy_flags.py

@@ -0,0 +1,70 @@
+"""plugin_system.auto_discover / auto_load_enabled / development_mode.
+
+The General tab offered three toggles for these, with help tips promising
+"plugins installed but dormant" and "verbose logging". Nothing in src/,
+web_interface/ or scripts/ reads them: every enabled plugin is discovered and
+loaded regardless. The toggles are gone; the keys stay tolerated in stored
+configs, and saving the General tab must not rewrite them.
+"""
+import copy
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+PROJECT_ROOT = Path(__file__).parent.parent
+sys.path.insert(0, str(PROJECT_ROOT))
+
+from test._api_v3_test_helpers import api_v3_client, api_v3_module  # noqa: F401,E402
+from test.test_web_settings_ui import REALISTIC_CONFIG, client  # noqa: F401,E402
+
+LEGACY_FLAGS = ('auto_discover', 'auto_load_enabled', 'development_mode')
+
+
+def test_the_general_tab_no_longer_offers_the_toggles(client):
+    body = client.get('/v3/partials/general').get_data(as_text=True)
+    for flag in LEGACY_FLAGS:
+        assert f'name="{flag}"' not in body, flag
+        assert f'setting-general-{flag}' not in body, flag
+    # The setting that does work stays.
+    assert 'name="plugins_directory"' in body
+
+
+@pytest.fixture
+def saved(api_v3_module, monkeypatch):
+    captured = {}
+    stored = copy.deepcopy(REALISTIC_CONFIG)
+    stored['plugin_system'].update(
+        auto_discover=True, auto_load_enabled=True, development_mode=True)
+    api_v3_module.api_v3.config_manager.load_config.return_value = stored
+
+    def fake_save(_manager, config, **_kwargs):
+        captured['config'] = config
+        return True, ''
+
+    monkeypatch.setattr(api_v3_module, '_save_config_atomic', fake_save)
+    return captured
+
+
+def test_saving_the_general_form_leaves_stored_flags_alone(api_v3_client, saved):
+    # What the General form posts now: no checkbox fields for the flags.
+    resp = api_v3_client.post('/api/v3/config/main', data={
+        'timezone': 'America/Chicago', 'city': 'Dallas', 'state': 'Texas',
+        'country': 'US', 'plugins_directory': 'plugin-repos',
+    })
+    assert resp.status_code == 200, resp.get_json()
+    plugin_system = saved['config']['plugin_system']
+    # Missing used to mean "unchecked" and saved all three as false.
+    assert all(plugin_system[flag] is True for flag in LEGACY_FLAGS), plugin_system
+    assert plugin_system['plugins_directory'] == 'plugin-repos'
+
+
+def test_an_api_client_can_still_store_a_flag(api_v3_client, saved):
+    resp = api_v3_client.post('/api/v3/config/main', data=json.dumps({
+        'timezone': 'America/Chicago', 'development_mode': False,
+    }), content_type='application/json')
+    assert resp.status_code == 200, resp.get_json()
+    plugin_system = saved['config']['plugin_system']
+    assert plugin_system['development_mode'] is False
+    assert plugin_system['auto_discover'] is True

test/test_safe_pip_install_allowlist.py

@@ -0,0 +1,128 @@
+"""scripts/fix_perms/safe_pip_install.sh must accept what the updaters install.
+
+Update Code and the automatic update's health check install the core's own
+requirement files through that root wrapper, and the wrapper refuses any path
+it does not list. It used to list only requirements.txt, so an update that
+changed web_interface/requirements.txt failed its dependency install -- and
+the automatic updater rolls back any update whose dependencies did not
+install, on every device, every week.
+
+The real script runs here with only its final pip command swapped for an
+echo, so the path checks under test are the shipped ones.
+"""
+import importlib.util
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT))
+
+WRAPPER_REL = Path('scripts') / 'fix_perms' / 'safe_pip_install.sh'
+PIP_LINE = 'exec "$PYTHON_PATH" -m pip install'
+
+
+def _bash():
+    """A bash whose realpath understands --canonicalize-missing, or None."""
+    candidates = [shutil.which('bash')]
+    if os.name == 'nt':
+        candidates.insert(0, r'C:\Program Files\Git\bin\bash.exe')
+    for bash in candidates:
+        if not bash or not os.path.exists(bash):
+            continue
+        try:
+            probe = subprocess.run([bash, '-c', 'realpath --canonicalize-missing /no/such/x'],
+                                   capture_output=True, text=True, timeout=30)
+        except (OSError, subprocess.SubprocessError):
+            continue
+        if probe.returncode == 0:
+            return bash
+    return None
+
+
+BASH = _bash()
+pytestmark = pytest.mark.skipif(BASH is None, reason='no bash with GNU realpath')
+
+
+@pytest.fixture
+def project(tmp_path):
+    """A project tree holding the real wrapper, with pip stubbed out."""
+    root = tmp_path / 'LEDMatrix'
+    wrapper = root / WRAPPER_REL
+    wrapper.parent.mkdir(parents=True)
+    text = (ROOT / WRAPPER_REL).read_text(encoding='utf-8').replace('\r\n', '\n')
+    lines = text.split('\n')
+    pip = [i for i, line in enumerate(lines) if line.startswith(PIP_LINE)]
+    assert len(pip) == 1, 'the wrapper no longer ends in the pip install this test stubs'
+    lines[pip[0]] = 'echo "WOULD INSTALL $RESOLVED_TARGET"; exit 0'
+    wrapper.write_text('\n'.join(lines), encoding='utf-8', newline='\n')
+    for rel in ('requirements.txt', 'web_interface/requirements.txt',
+                'plugin-repos/clock/requirements.txt', 'src/requirements.txt',
+                'web_interface/extra/requirements.txt'):
+        (root / rel).parent.mkdir(parents=True, exist_ok=True)
+        (root / rel).write_text('requests\n', encoding='utf-8')
+    return root
+
+
+def run_wrapper(root, rel):
+    """Run the wrapper on ``rel``, with the path spelled the way bash sees the tree."""
+    return subprocess.run(
+        [BASH, '-c', 'cd "$1" && bash scripts/fix_perms/safe_pip_install.sh "$PWD/$2"',
+         '_', str(root), rel],
+        capture_output=True, text=True, timeout=60)
+
+
+def _core_requirement_files():
+    from web_interface.blueprints.api_v3 import system
+    spec = importlib.util.spec_from_file_location(
+        'auto_update_verify_for_allowlist', ROOT / 'scripts' / 'utils' / 'auto_update_verify.py')
+    verifier = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(verifier)
+    assert set(verifier.REQUIREMENT_FILES) == set(system.CORE_REQUIREMENT_FILES), (
+        'the rollback must reinstall the same files Update Code installs')
+    return system.CORE_REQUIREMENT_FILES
+
+
+@pytest.mark.parametrize('rel', _core_requirement_files())
+def test_every_core_requirement_file_the_updaters_install_is_allowed(project, rel):
+    result = run_wrapper(project, rel)
+    assert result.returncode == 0, result.stderr
+    assert 'WOULD INSTALL' in result.stdout
+
+
+def test_plugin_requirements_are_still_allowed(project):
+    assert run_wrapper(project, 'plugin-repos/clock/requirements.txt').returncode == 0
+
+
+@pytest.mark.parametrize('rel', [
+    'src/requirements.txt',                    # repo-owned folder, but not listed
+    'web_interface/extra/requirements.txt',    # below an allowed file's folder
+    'web_interface/requirements.txt.bak',      # not a requirements.txt
+])
+def test_other_paths_are_still_refused(project, rel):
+    if rel.endswith('.bak'):
+        (project / rel).write_text('requests\n', encoding='utf-8')
+    result = run_wrapper(project, rel)
+    assert result.returncode == 2, result.stdout + result.stderr
+    assert 'DENIED' in result.stderr
+
+
+@pytest.mark.parametrize('rel', ['requirements.txt', 'web_interface/requirements.txt'])
+def test_a_core_requirement_file_symlinked_out_of_the_project_is_refused(project, tmp_path, rel):
+    """Only the allowed files' folders are resolved, so the link's target is
+    compared, and refused, rather than allowed as the file itself."""
+    outside = tmp_path / 'elsewhere' / 'requirements.txt'
+    outside.parent.mkdir()
+    outside.write_text('evil\n', encoding='utf-8')
+    link = project / rel
+    link.unlink()
+    try:
+        link.symlink_to(outside)
+    except (OSError, NotImplementedError):
+        pytest.skip('symlinks unavailable')
+    result = run_wrapper(project, rel)
+    assert result.returncode == 2, result.stdout + result.stderr

test/test_scroll_helper.py

@@ -460,6 +460,19 @@ class TestIdleGapIsNotAFrame:
         assert not info.called
         assert len(helper._window) == 1
 
+    def test_a_dropped_gap_restarts_the_window_timer_too(self, helper):
+        """The size-guard path is the one scrollers that never call
+        reset_scroll() take, so it must restart the window like the sentinel
+        does, or their next scroll opens with a one-frame stats line."""
+        helper.log_frame_rate()                     # seeds
+        helper.last_frame_time = time.time() - 137.0
+        helper.last_fps_log_time = 0.0              # boundary long overdue
+        with patch.object(helper.logger, "info") as info:
+            helper.log_frame_rate()                 # the gap, dropped
+            helper.log_frame_rate()                 # first real frame
+        assert not info.called, "a one-frame window was reported"
+        assert len(helper._window) == 1
+
     def test_a_normal_frame_still_counts(self, helper):
         helper.last_frame_time = time.time() - 0.010
         helper.log_frame_rate()

test/test_scroll_speeds_script.py

@@ -0,0 +1,144 @@
+"""scripts/scroll_speeds.py must drive the panel the way the service does.
+
+--measure and --demo open the matrix themselves. They used to build the
+options from a private copy of DisplayManager's builder that had drifted: it
+read gpio_slowdown from display.hardware (the service reads display.runtime),
+and skipped rp1_rio, panel_type, orientation and more. On a panel that needs a
+high slowdown that measured -- or garbled -- a panel the service never drives.
+"""
+import importlib.util
+import os
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+os.environ.setdefault("EMULATOR", "true")
+
+import src.display_manager as display_manager  # noqa: E402
+from src.display_manager import DisplayManager  # noqa: E402
+
+SCRIPT = Path(__file__).resolve().parents[1] / "scripts" / "scroll_speeds.py"
+
+
+@pytest.fixture(scope="module")
+def script():
+    spec = importlib.util.spec_from_file_location("scroll_speeds_script", SCRIPT)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+class _Options:
+    """Records what is set; declares rp1_rio like a Pi 5-capable binding."""
+
+    rp1_rio = None
+
+
+CONFIG = {
+    "display": {
+        "hardware": {
+            "rows": 64, "cols": 64, "chain_length": 2, "parallel": 1,
+            "hardware_mapping": "adafruit-hat-pwm",
+            "brightness": 70, "pwm_bits": 9, "pwm_lsb_nanoseconds": 130,
+            "row_address_type": 5, "panel_type": "FM6126A",
+            "limit_refresh_rate_hz": 120, "orientation": "180",
+            "pixel_mapper_config": "U-mapper",
+            "gpio_slowdown": 2,  # a stale key in the wrong block
+        },
+        "runtime": {"gpio_slowdown": 7, "rp1_rio": 1},
+    }
+}
+
+
+def _script_options(script, config, **kwargs):
+    with patch.object(display_manager, "RGBMatrixOptions", _Options):
+        return script.build_options(config, **kwargs)
+
+
+def test_runtime_settings_are_used(script):
+    options = _script_options(script, CONFIG)
+    assert options.gpio_slowdown == 7
+    assert options.rp1_rio == 1
+    assert options.panel_type == "FM6126A"
+    assert options.row_address_type == 5
+    assert options.pixel_mapper_config == "U-mapper;Rotate:180"
+    assert options.limit_refresh_rate_hz == 120
+
+
+def test_the_options_match_the_display_service(script):
+    """Same config in, same options out, attribute for attribute."""
+    service = DisplayManager.apply_matrix_options(_Options(), CONFIG)
+    assert vars(_script_options(script, CONFIG)) == vars(service)
+
+
+def test_measure_runs_uncapped(script):
+    assert _script_options(script, CONFIG, refresh_override=0).limit_refresh_rate_hz == 0
+
+
+def test_an_empty_config_gets_the_service_defaults(script):
+    options = _script_options(script, {})
+    assert vars(options) == vars(DisplayManager.apply_matrix_options(_Options(), {}))
+    assert options.gpio_slowdown == 3
+
+
+def test_the_service_uses_the_shared_builder(test_config):
+    """DisplayManager._setup_matrix fills its options through the same call."""
+    with patch.object(display_manager, "RGBMatrix"), \
+            patch.object(display_manager, "RGBMatrixOptions", _Options), \
+            patch.object(display_manager, "freetype"), \
+            patch.object(DisplayManager, "apply_matrix_options",
+                         wraps=DisplayManager.apply_matrix_options) as shared, \
+            patch.dict(os.environ, {"EMULATOR": "false"}):
+        DisplayManager._instance = None
+        try:
+            DisplayManager(test_config)
+        finally:
+            DisplayManager._instance = None
+    shared.assert_called_once()
+
+
+class TestSpeedAdvice:
+    """The advice must name keys the resolver actually honours."""
+
+    def _advice(self, script, capsys, hz, want):
+        script.print_ladder(hz, want)
+        return capsys.readouterr().out
+
+    def test_advice_is_the_speed_delay_pair(self, script, capsys):
+        out = self._advice(script, capsys, 100.0, 60)
+        assert '"scroll_speed": 2' in out
+        assert '"scroll_delay": 0.03' in out
+
+    @pytest.mark.parametrize("hz,want", [(100.0, 60), (100.0, 50), (120.0, 45),
+                                         (60.0, 30), (100.0, None)])
+    def test_the_advised_pair_resolves_to_the_advised_speed(self, script, capsys,
+                                                            hz, want):
+        """Apply the printed pair over a schema-default pair, as a saved config
+        would carry it, and the resolver must land on the advertised speed."""
+        import json
+        import re
+
+        from src.common import scroll_config
+
+        out = self._advice(script, capsys, hz, want)
+        block = re.search(r'"display_options": (\{[^}]*\})', out)
+        assert block, out
+        advised = json.loads(block.group(1))
+        config = {"display_options": {"scroll_speed": 1.0, "scroll_delay": 0.02,
+                                      "scroll_pixels_per_second": 999,
+                                      **advised}}
+        expected = scroll_config.solve_crisp(want if want else hz / 2, hz)
+        settings = scroll_config.configure(
+            _Helper(), plugin_config=config, refresh_hz=hz)
+        assert settings.pixels_per_second == pytest.approx(expected.pixels_per_second)
+        assert settings.frame_hold == expected.frame_hold
+
+    def test_the_deprecated_key_is_not_recommended(self, script, capsys):
+        out = self._advice(script, capsys, 100.0, 60)
+        assert '"scroll_pixels_per_second":' not in out
+
+
+class _Helper:
+    def set_scroll_speed(self, speed):
+        pass

test/test_sports_scroll.py

@@ -6,8 +6,11 @@ is shared, the content layer is not. Two things are worth asserting beyond
 
 * ``prepare_scroll_content`` must stay an override point — a base class that
   quietly rendered *something* would let a plugin ship a blank scroll.
-* ``target_fps`` must actually reach the helper. That is the whole reason this
+* Speed must depend only on ``scroll_speed`` and the panel refresh. The helper
-  module exists upstream; the bundled plugin copies hardcode ~100 FPS.
+  steps a fixed number of whole pixels per presented frame and the panel
+  presents at its refresh divided by the frame hold, so a ladder computed for
+  any other rate -- the global ``target_fps`` used to be one -- plays back at
+  the wrong speed.
 """
 
 import logging
@@ -221,12 +224,14 @@ class TestConfigureScrollHelper:
         bare = SportsScrollDisplay.__new__(SportsScrollDisplay)
         assert SportsScrollDisplay._scroll_frame_hold(bare) == 1
 
-    def test_stepping_is_time_based(self, build):
+    def test_helper_steps_whole_pixels_per_presented_frame(self, build):
-        """Frame-based mode gated motion on a wall clock at 1/scroll_delay
+        """No wall clock: the helper advances the ladder's whole-pixel step on
-        steps, with scroll_delay set to the frame period -- putting the
+        every presented frame, and the frame hold sets how often that is."""
-        comparison exactly on its own threshold, so it flipped on sub-
+        display = build()
-        millisecond jitter."""
+        helper = display.scroll_helper
-        build().scroll_helper.set_frame_based_scrolling.assert_called_once_with(False)
+        helper.set_frame_based_scrolling.assert_called_once_with(False)
+        helper.set_pixels_per_frame.assert_called_once_with(
+            display._scroll_settings.crisp.pixels_per_frame)
 
     def test_dynamic_duration_settings_are_applied(self, build):
         display = build({"nhl": {"scroll_settings": {
@@ -243,31 +248,65 @@ class TestConfigureScrollHelper:
         applied = display.scroll_helper.set_scroll_speed.call_args[0][0]
         assert applied == pytest.approx(100.0, abs=1.0)
 
-    def test_global_target_fps_sets_the_refresh_the_ladder_uses(self, build):
+    @pytest.mark.parametrize("global_config", [
-        """Under the old model this key was the rate frames were presented at,
+        {},
-        so it is the faithful translation of it into a panel refresh."""
+        {"target_fps": 60},
-        display = build(global_config={"target_fps": 60})
+        {"target_fps": 100},
-        assert display._resolve_refresh_hz() == 60.0
+        {"target_fps": 120},
+        {"target_fps": 200},
+        {"scroll_target_fps": 90},
+        {"target_fps": 120, "scroll_target_fps": 90},
+    ])
+    def test_target_fps_does_not_change_scroll_speed(self, build, global_config):
+        """The General tab's "Scroll Frame Rate" is not a speed control.
 
-    def test_legacy_key_is_honored(self, build):
+        It used to set the refresh the ladder was computed against, while the
-        display = build(global_config={"scroll_target_fps": 90})
+        panel kept presenting at its real 100Hz: 60 doubled every scoreboard's
-        assert display._resolve_refresh_hz() == 90.0
+        speed and 200 halved it."""
+        display = build(global_config=global_config)
+        assert display._resolve_refresh_hz() == 100.0
+        assert display._scroll_settings.pixels_per_second == pytest.approx(50.0)
+        assert display._scroll_settings.frame_hold == 2
+        assert display._scroll_settings.crisp.pixels_per_frame == 1
 
-    def test_modern_key_wins_over_legacy(self, build):
+    def test_configured_hardware_refresh_sets_the_ladder(self, build):
-        display = build(global_config={"target_fps": 120, "scroll_target_fps": 90})
-        assert display._resolve_refresh_hz() == 120.0
-
-    def test_configured_hardware_refresh_wins_over_the_fps_target(self, build):
         display = build(global_config={
             "target_fps": 60,
             "display": {"hardware": {"limit_refresh_rate_hz": 120}}})
         assert display._resolve_refresh_hz() == 120.0
+        assert display._scroll_settings.crisp.refresh_hz == 120.0
+
+    def test_display_manager_refresh_wins_over_global_config(self, build,
+                                                             display_manager):
+        """The display manager reports the rate the panel is driven at."""
+        display_manager.refresh_hz = 60.0
+        display = build(global_config={
+            "target_fps": 200,
+            "display": {"hardware": {"limit_refresh_rate_hz": 120}}})
+        assert display._resolve_refresh_hz() == 60.0
+
+    @pytest.mark.parametrize("reported", [True, 0, -5, "100", None])
+    def test_unusable_display_manager_refresh_falls_back(self, build,
+                                                          display_manager,
+                                                          reported):
+        display_manager.refresh_hz = reported
+        display = build(global_config={
+            "display": {"hardware": {"limit_refresh_rate_hz": 120}}})
+        assert display._resolve_refresh_hz() == 120.0
 
     @pytest.mark.parametrize("bad", ["fast", None, {}, [], "", 0])
-    def test_unusable_target_fps_degrades_instead_of_raising(self, build, bad):
+    def test_unusable_target_fps_is_harmless(self, build, bad):
-        """A malformed global config must cost the FPS target, not the display."""
+        """A malformed global config must not cost the display."""
         display = build(global_config={"target_fps": bad})
-        assert display._scroll_settings.pixels_per_second > 0
+        assert display._scroll_settings.pixels_per_second == pytest.approx(50.0)
+
+    @pytest.mark.parametrize("delay", [0.001, 0.01, 0.05, 0.1])
+    def test_scroll_delay_is_ignored_for_pacing(self, build, delay):
+        """Kept in the settings for compatibility; it does not change speed."""
+        display = build({"nhl": {"scroll_settings": {
+            "scroll_speed": 50.0, "scroll_delay": delay}}})
+        assert display._scroll_settings.pixels_per_second == pytest.approx(50.0)
+        assert display._scroll_settings.frame_hold == 2
 
     @pytest.mark.parametrize("bad", [None, "fast", {}, []])
     def test_unusable_scroll_speed_degrades_instead_of_crashing(self, build, bad):
@@ -475,7 +514,9 @@ class TestLifecycle:
 class TestManager:
     @pytest.fixture
     def manager(self, display_manager):
-        return _Manager(display_manager, {}, LOGGER, global_config={"target_fps": 120})
+        return _Manager(display_manager, {}, LOGGER, global_config={
+            "target_fps": 120,
+            "display": {"hardware": {"limit_refresh_rate_hz": 120}}})
 
     def test_displays_are_created_lazily_and_reused(self, manager):
         first = manager.get_scroll_display("live")
@@ -487,15 +528,13 @@ class TestManager:
             "recent")
 
     def test_global_config_is_threaded_to_children(self, manager):
-        """A missed hand-off here is exactly how the plugin copies ended up
+        """The child needs the global config to find the panel refresh when
-        never honoring target_fps."""
+        the display manager cannot report one."""
         child = manager.get_scroll_display("live")
-        assert child.global_config == {"target_fps": 120}
+        assert child.global_config["target_fps"] == 120
-        # The target is now the refresh the crisp ladder is computed against,
+        # What proves the hand-off is that the child reasons about the 120Hz
-        # so what proves the hand-off is that the child reasons about 120Hz --
+        # hardware refresh from that config (target_fps plays no part).
-        # not the presentation rate, which the chosen hold divides down.
         assert child._resolve_refresh_hz() == 120.0
-        child.scroll_helper.set_target_fps.assert_called_once()
 
     def test_prepare_sets_the_active_type(self, manager):
         assert manager.prepare_and_display([{"id": "g1"}], "live", ["nhl"]) is True
@@ -619,15 +658,17 @@ class TestAgainstTheRealScrollHelper:
     def test_configuration_lands_on_the_real_helper(self, real):
         display = real.get_scroll_display("live")
         helper = display.scroll_helper
-        # 500 px/s on a 120Hz panel snaps to a whole number of pixels per
+        # 500 px/s on the default 100Hz panel is a whole number of pixels per
-        # refresh, and the helper is driven in px/s in time-based mode.
+        # refresh, and the helper steps that many pixels per presented frame.
         assert helper.frame_based_scrolling is False
         assert helper.scroll_speed == pytest.approx(
             display._scroll_settings.pixels_per_second)
         assert helper.scroll_speed == pytest.approx(500.0, abs=25.0)
-        # target_fps is the presentation rate the chosen hold produces.
+        assert helper.fixed_pixels_per_frame == (
+            display._scroll_settings.crisp.pixels_per_frame)
+        # target_fps is informational: the presentation rate the hold gives.
         assert helper.target_fps == pytest.approx(
-            120.0 / display._scroll_settings.frame_hold, abs=1.0)
+            100.0 / display._scroll_settings.frame_hold, abs=1.0)
 
     def test_a_strip_is_built_and_scrolls_to_completion(self, real):
         import time
@@ -638,21 +679,58 @@ class TestAgainstTheRealScrollHelper:
         # 3 cards of 100px + gaps, so the strip is wider than the 128px panel.
         assert display.scroll_helper.cached_image.width > 128
 
-        # Frame-based scrolling is wall-clock gated on scroll_delay, so the
+        # The helper steps a fixed whole-pixel amount per presented frame and
-        # loop has to actually pass time rather than spin.
+        # consults no clock, so the scroll completes in a bounded number of
+        # frames however fast this loop spins.
         deadline = time.time() + 20
-        while not real.is_complete() and time.time() < deadline:
+        frames = 0
+        while not real.is_complete() and time.time() < deadline and frames < 10000:
             real.display_frame()
-            time.sleep(0.0012)
+            frames += 1
 
-        # Asserted separately so a host too slow to sustain the frame rate
+        assert time.time() < deadline, "scroll did not finish within 20s"
-        # reports a timeout rather than looking like a scrolling defect.
-        assert time.time() < deadline, (
-            "scroll did not finish within 20s — the host may be too slow to "
-            "sustain the configured frame rate")
         assert real.is_complete() is True
         assert display.scroll_helper.scroll_position > 128
 
     def test_dynamic_duration_is_a_real_number(self, real):
         real.prepare_and_display([{"id": "a"}], "live", ["nhl"])
         assert real.get_scroll_display("live").get_dynamic_duration() > 0
+
+    @pytest.mark.parametrize("target_fps", [None, 60, 100, 200])
+    def test_presented_speed_is_independent_of_target_fps(self, monkeypatch,
+                                                          target_fps):
+        """End to end: the px/s the panel actually shows.
+
+        The panel is simulated the way SwapOnVSync paces it: each drawn frame
+        occupies ``frame_hold`` refreshes of a 100Hz panel. Ten seconds of
+        refreshes must move the strip 500px at the default 50 px/s, whatever
+        the General tab's target_fps says."""
+        from src.common.scroll_helper import ScrollHelper
+        monkeypatch.setattr("src.common.sports_scroll.ScrollHelper", ScrollHelper)
+
+        class _Panel:
+            matrix = None
+            width, height = 128, 32
+            refresh_hz = 100.0
+            hold = 1
+            image = None
+
+            def set_scrolling_state(self, scrolling, frame_hold=1):
+                self.hold = frame_hold
+
+            def update_display(self):
+                pass
+
+        global_config = {"display": {"hardware": {"limit_refresh_rate_hz": 100}}}
+        if target_fps is not None:
+            global_config["target_fps"] = target_fps
+        panel = _Panel()
+        display = _RealDisplay(panel, {}, LOGGER, global_config=global_config)
+        display.scroll_helper.set_scrolling_image(Image.new("RGB", (5000, 32)))
+
+        refreshes = 0
+        while refreshes < 1000:  # ten seconds at 100Hz
+            assert display.display_scroll_frame() is True
+            refreshes += panel.hold
+        moved = display.scroll_helper.total_distance_scrolled
+        assert moved / 10.0 == pytest.approx(50.0, abs=1.0)

test/web_interface/test_plugin_config_json_saves.py

@@ -0,0 +1,258 @@
+"""JSON plugin-config saves store what the device would load, and only what was sent.
+
+Runs a real ConfigManager and SchemaManager over tmp_path, like
+test_api_v3_secret_roundtrip.py, so assertions are on config.json itself.
+
+- POST /plugins/config with a partial ``config`` reset every unsent setting to
+  its schema default: the JSON path built on defaults, not the stored section.
+- Legacy booleans (#588) were normalized only at load, so posting back what
+  GET /plugins/config returned failed validation.
+- The JSON save's filter kept only enabled/display_duration/live_priority, so
+  a submitted skin, skin_options or vegas_* tuning key was silently dropped.
+- Plugin sections posted to /config/main skipped all of that and were stored
+  verbatim, including values /plugins/config rejects.
+"""
+
+import json
+from unittest.mock import MagicMock
+
+import pytest
+from flask import Flask
+
+from src.config_manager import ConfigManager
+from src.plugin_system.schema_manager import SchemaManager
+from web_interface.blueprints.api_v3 import api_v3
+
+PLUGIN_ID = "demo"
+
+SCHEMA = {
+    "type": "object",
+    "additionalProperties": False,
+    "properties": {
+        "enabled": {"type": "boolean", "default": True},
+        "city": {"type": "string", "default": "Dallas"},
+        "update_interval": {"type": "integer", "default": 300, "minimum": 30},
+        "api_key": {"type": "string", "x-secret": True, "default": ""},
+        "display": {
+            "type": "object",
+            "additionalProperties": False,
+            "properties": {
+                "brightness": {"type": "integer", "default": 50},
+                "show_icons": {"type": "boolean", "default": True},
+            },
+        },
+        "global": {
+            "type": "object",
+            "additionalProperties": False,
+            "properties": {
+                "dynamic_duration": {
+                    "type": "object",
+                    "additionalProperties": False,
+                    "properties": {
+                        "enabled": {"type": "boolean", "default": True},
+                        "min_duration_seconds": {"type": "integer", "default": 30},
+                    },
+                },
+            },
+        },
+    },
+}
+
+STORED = {
+    "enabled": True,
+    "city": "Paris",
+    "update_interval": 600,
+    "display": {"brightness": 80, "show_icons": False},
+    "global": {"dynamic_duration": {"enabled": False, "min_duration_seconds": 45}},
+    "vegas_width_pct": 60,
+    "skin": "neon",
+}
+
+_ATTRS = ('config_manager', 'plugin_manager', 'plugin_store_manager',
+          'plugin_state_manager', 'saved_repositories_manager', 'schema_manager',
+          'operation_queue', 'operation_history', 'cache_manager')
+
+
+@pytest.fixture
+def env(tmp_path):
+    config_file = tmp_path / "config.json"
+    secrets_file = tmp_path / "config_secrets.json"
+    plugins_dir = tmp_path / "plugins"
+    plugin_dir = plugins_dir / PLUGIN_ID
+    plugin_dir.mkdir(parents=True)
+    (plugin_dir / "config_schema.json").write_text(json.dumps(SCHEMA))
+    (plugin_dir / "manifest.json").write_text(json.dumps({"id": PLUGIN_ID}))
+
+    sentinel = object()
+    originals = {name: getattr(api_v3, name, sentinel) for name in _ATTRS}
+
+    config_manager = ConfigManager(config_path=str(config_file),
+                                   secrets_path=str(secrets_file))
+    config_manager.template_path = str(tmp_path / "no-template.json")
+    plugin_manager = MagicMock()
+    plugin_manager.plugin_manifests = {PLUGIN_ID: {"id": PLUGIN_ID}}
+    plugin_manager.plugins_dir = plugins_dir
+    plugin_manager.get_plugin.return_value = None
+
+    for name in _ATTRS:
+        setattr(api_v3, name, MagicMock())
+    api_v3.config_manager = config_manager
+    api_v3.schema_manager = SchemaManager(plugins_dir=plugins_dir, project_root=tmp_path)
+    api_v3.plugin_manager = plugin_manager
+    api_v3.operation_queue = None
+
+    app = Flask(__name__)
+    app.config["TESTING"] = True
+    app.register_blueprint(api_v3, url_prefix="/api/v3")
+
+    class Env:
+        client = app.test_client()
+
+        @staticmethod
+        def store(section):
+            config_file.write_text(json.dumps({"timezone": "UTC", PLUGIN_ID: section}))
+
+        @staticmethod
+        def main():
+            return json.loads(config_file.read_text())
+
+        @staticmethod
+        def stored():
+            return json.loads(config_file.read_text())[PLUGIN_ID]
+
+        @staticmethod
+        def secrets():
+            return json.loads(secrets_file.read_text()) if secrets_file.exists() else {}
+
+        @staticmethod
+        def save(config):
+            return app.test_client().post("/api/v3/plugins/config",
+                                          json={"plugin_id": PLUGIN_ID, "config": config})
+
+    Env.store(json.loads(json.dumps(STORED)))
+    yield Env
+
+    for name, original in originals.items():
+        if original is sentinel:
+            if hasattr(api_v3, name):
+                delattr(api_v3, name)
+        else:
+            setattr(api_v3, name, original)
+
+
+class TestPartialJsonSave:
+    def test_unsent_settings_keep_their_values(self, env):
+        resp = env.save({"enabled": True})
+        assert resp.status_code == 200, resp.get_json()
+        stored = env.stored()
+        assert stored["city"] == "Paris"
+        assert stored["update_interval"] == 600
+        assert stored["display"] == {"brightness": 80, "show_icons": False}
+        assert stored["global"]["dynamic_duration"] == {"enabled": False, "min_duration_seconds": 45}
+
+    def test_a_nested_partial_keeps_its_siblings(self, env):
+        resp = env.save({"display": {"brightness": 20}})
+        assert resp.status_code == 200, resp.get_json()
+        assert env.stored()["display"] == {"brightness": 20, "show_icons": False}
+
+    def test_a_sent_setting_still_changes(self, env):
+        assert env.save({"city": "Lyon", "enabled": False}).status_code == 200
+        stored = env.stored()
+        assert stored["city"] == "Lyon" and stored["enabled"] is False
+
+    def test_an_invalid_sent_value_is_still_rejected(self, env):
+        resp = env.save({"update_interval": 5})
+        assert resp.status_code == 400
+        assert env.stored()["update_interval"] == 600
+
+    def test_config_must_be_an_object(self, env):
+        assert env.save(["city"]).status_code == 400
+
+
+class TestCoreOwnedKeysSurviveTheFilter:
+    def test_submitted_core_keys_are_stored(self, env):
+        env.store({"enabled": True, "city": "Paris"})
+        resp = env.save({
+            "vegas_width_pct": 50, "vegas_overflow": "truncate",
+            "vegas_max_width_screens": 2, "skin": "retro",
+            "skin_options": {"accent": "#ff0000"}, "live_priority": True,
+        })
+        assert resp.status_code == 200, resp.get_json()
+        stored = env.stored()
+        assert stored["vegas_width_pct"] == 50
+        assert stored["vegas_overflow"] == "truncate"
+        assert stored["vegas_max_width_screens"] == 2
+        assert stored["skin"] == "retro"
+        assert stored["skin_options"] == {"accent": "#ff0000"}
+        assert stored["live_priority"] is True
+
+    def test_stored_core_keys_survive_an_unrelated_save(self, env):
+        assert env.save({"city": "Nice"}).status_code == 200
+        stored = env.stored()
+        assert stored["vegas_width_pct"] == 60 and stored["skin"] == "neon"
+
+    def test_a_non_core_unknown_key_is_still_filtered(self, env):
+        assert env.save({"not_in_schema": 1}).status_code == 200
+        assert "not_in_schema" not in env.stored()
+
+
+class TestLegacyBooleans:
+    LEGACY = {"enabled": True, "city": "Paris", "global": {"dynamic_duration": True}}
+
+    def test_get_returns_the_object_shape(self, env):
+        env.store(dict(self.LEGACY))
+        data = env.client.get(f"/api/v3/plugins/config?plugin_id={PLUGIN_ID}").get_json()["data"]
+        assert data["global"]["dynamic_duration"] == {"enabled": True, "min_duration_seconds": 30}
+
+    def test_get_output_posts_back(self, env):
+        env.store(dict(self.LEGACY))
+        data = env.client.get(f"/api/v3/plugins/config?plugin_id={PLUGIN_ID}").get_json()["data"]
+        resp = env.save(data)
+        assert resp.status_code == 200, resp.get_json()
+        assert env.stored()["global"]["dynamic_duration"] == {"enabled": True, "min_duration_seconds": 30}
+
+    def test_an_unrelated_json_save_upgrades_the_stored_boolean(self, env):
+        env.store(dict(self.LEGACY))
+        resp = env.save({"city": "Lyon"})
+        assert resp.status_code == 200, resp.get_json()
+        assert env.stored()["global"]["dynamic_duration"] == {"enabled": True, "min_duration_seconds": 30}
+
+    def test_a_posted_legacy_boolean_is_read_as_the_object(self, env):
+        resp = env.save({"global": {"dynamic_duration": False}})
+        assert resp.status_code == 200, resp.get_json()
+        assert env.stored()["global"]["dynamic_duration"]["enabled"] is False
+
+
+class TestPluginSectionsInConfigMain:
+    def _post(self, env, body):
+        return env.client.post("/api/v3/config/main", json=body)
+
+    def test_a_value_plugins_config_rejects_is_rejected_here_too(self, env):
+        resp = self._post(env, {PLUGIN_ID: {"update_interval": "abc"}})
+        assert resp.status_code == 400
+        assert env.stored()["update_interval"] == 600
+        assert env.save({"update_interval": "abc"}).status_code == 400
+
+    def test_nothing_is_saved_when_a_plugin_section_fails(self, env):
+        resp = self._post(env, {"timezone": "Europe/Paris", PLUGIN_ID: {"update_interval": 1}})
+        assert resp.status_code == 400
+        assert env.main()["timezone"] == "UTC"
+        assert env.stored()["update_interval"] == 600
+
+    def test_partial_section_merges_and_keeps_core_keys(self, env):
+        resp = self._post(env, {PLUGIN_ID: {"city": "Lyon", "vegas_overflow": "rotate"}})
+        assert resp.status_code == 200, resp.get_json()
+        stored = env.stored()
+        assert stored["city"] == "Lyon"
+        assert stored["display"] == {"brightness": 80, "show_icons": False}
+        assert stored["vegas_overflow"] == "rotate"
+        assert stored["vegas_width_pct"] == 60 and stored["skin"] == "neon"
+
+    def test_secrets_still_go_to_the_secrets_file(self, env):
+        resp = self._post(env, {PLUGIN_ID: {"api_key": "s3cret"}})
+        assert resp.status_code == 200, resp.get_json()
+        assert "api_key" not in env.stored() or env.stored()["api_key"] in ("", None)
+        assert env.secrets()[PLUGIN_ID]["api_key"] == "s3cret"
+
+    def test_a_non_object_section_is_rejected(self, env):
+        assert self._post(env, {PLUGIN_ID: "on"}).status_code == 400

test/web_interface/test_update_all_plugins.py

@@ -80,6 +80,67 @@ class TestUpdateRouteRejectsStarlarkIds:
         assert [c.args[0] for c in store.update_plugin.call_args_list] == ['stock-news', 'starlark-apps']
 
 
+class TestUpdateRouteReportsNoOps:
+    """update_plugin() answers True when there was nothing to do.
+
+    A ZIP-installed monorepo plugin (no .git) already at the registry version
+    is the common case for official plugins. The route used to call that
+    "updated successfully", so Check & Update All counted it as updated.
+    """
+
+    def _install(self, tmp_path, pid, version, last_updated='2026-09-01'):
+        (tmp_path / pid).mkdir()
+        (tmp_path / pid / 'manifest.json').write_text(
+            '{"id": "%s", "version": "%s", "last_updated": "%s"}' % (pid, version, last_updated),
+            encoding='utf-8')
+
+    def test_a_zip_plugin_already_at_the_registry_version_is_up_to_date(self, client, store, tmp_path):
+        self._install(tmp_path, 'stock-news', '2.8.0')
+        body = client.post('/api/v3/plugins/update', json={'plugin_id': 'stock-news'}).get_json()
+        assert body['status'] == 'success'
+        assert body['data']['update_status'] == 'up_to_date'
+        assert 'already up to date' in body['message'], body
+        assert 'updated successfully' not in body['message']
+
+    def test_a_zip_plugin_reinstalled_at_a_new_version_is_updated(self, client, store, tmp_path):
+        self._install(tmp_path, 'stock-news', '2.6.2')
+
+        def reinstall(pid):
+            (tmp_path / pid / 'manifest.json').write_text(
+                '{"id": "%s", "version": "2.8.0", "last_updated": "2026-09-01"}' % pid,
+                encoding='utf-8')
+            return True
+        store.update_plugin.side_effect = reinstall
+
+        body = client.post('/api/v3/plugins/update', json={'plugin_id': 'stock-news'}).get_json()
+        assert body['data']['update_status'] == 'updated'
+        assert '2.8.0' in body['message'], body
+
+    def test_a_git_plugin_whose_commit_is_unchanged_is_up_to_date(self, client, store, tmp_path):
+        self._install(tmp_path, 'clock', '1.0.0')
+        store._get_local_git_info.return_value = {'sha': 'abcdef1234567', 'branch': 'main'}
+        body = client.post('/api/v3/plugins/update', json={'plugin_id': 'clock'}).get_json()
+        assert body['data']['update_status'] == 'up_to_date'
+
+    def test_a_git_plugin_that_moved_is_updated(self, client, store, tmp_path):
+        self._install(tmp_path, 'clock', '1.0.0')
+        store._get_local_git_info.side_effect = [
+            {'sha': 'aaaaaaa000', 'branch': 'main'},   # before
+            {'sha': 'aaaaaaa000', 'branch': 'main'},   # is-git check
+            {'sha': 'bbbbbbb111', 'branch': 'main'},   # after
+        ]
+        body = client.post('/api/v3/plugins/update', json={'plugin_id': 'clock'}).get_json()
+        assert body['data']['update_status'] == 'updated', body
+
+    def test_a_local_only_plugin_says_so(self, client, store, tmp_path):
+        (tmp_path / 'mine').mkdir()
+        (tmp_path / 'mine' / 'manifest.json').write_text(
+            '{"id": "mine", "version": "0.1.0", "local_only": true}', encoding='utf-8')
+        body = client.post('/api/v3/plugins/update', json={'plugin_id': 'mine'}).get_json()
+        assert body['data']['update_status'] == 'local_only'
+        store.update_plugin.assert_not_called()
+
+
 class TestInstalledListContract:
     """What update-all filters on is what /plugins/installed publishes."""
 

web_interface/README.md

@@ -20,7 +20,9 @@ web_interface/
 ├── run.sh                    # Shell runner script
 ├── requirements.txt          # Python dependencies
 ├── blueprints/               # Flask blueprints
-│   ├── api_v3.py            # API endpoints
+│   ├── api_v3/              # API endpoints (package: config, display,
+│   │                        #   plugins, system, backup, fonts, misc,
+│   │                        #   wifi, starlark)
 │   └── pages_v3.py          # Page routes
 ├── templates/                # HTML templates
 │   └── v3/
@@ -75,7 +77,8 @@ The web interface reads configuration from:
 
 ## API Documentation
 
-The V3 API is mounted at `/api/v3/` (`app.py:144`). For the complete
+The V3 API is the `api_v3` blueprint, registered at `/api/v3/` in
+`app.py`. For the complete
 list and request/response formats, see
 [`docs/REST_API_REFERENCE.md`](../docs/REST_API_REFERENCE.md). Quick
 reference for the most common endpoints:
@@ -115,9 +118,9 @@ reference for the most common endpoints:
 - `POST /api/v3/plugins/store/refresh` - Refresh registry from GitHub
 
 ### Real-time Streams (SSE)
-SSE stream endpoints are defined directly on the Flask app
+SSE stream endpoints are defined directly on the Flask app in `app.py`
-(`app.py:607-619` — includes the CSRF exemption and rate-limit hookup
+(`stream_stats`, `stream_display`, `stream_logs`, followed by their CSRF
-alongside the three route definitions), not on the api_v3 blueprint:
+exemption and rate-limit hookup), not on the api_v3 blueprint:
 - `GET /api/v3/stream/stats` - System statistics stream
 - `GET /api/v3/stream/display` - Display preview stream
 - `GET /api/v3/stream/logs` - Service logs stream

web_interface/auto_update.py

@@ -263,6 +263,56 @@ def start_setup_if_needed(was_enabled, config):
     return 'Could not restart the display to finish automatic update setup; restart it from the Overview tab.'
 
 
+#: Top-level folders of separately installed plugins. Edits there are not the
+#: core's local changes: the Plugin Store updates plugins in place, including
+#: the bundled ones committed under plugin-repos/, and the pull's --autostash
+#: carries those edits across and reapplies them.
+SEPARATE_INSTALL_DIRS = ('plugins', 'plugin-repos')
+
+
+def local_changes(project_dir, run=None, timeout=30):
+    """Tracked files edited in the checkout, as both code updates count them.
+
+    The one definition shared by the automatic update's preflight and
+    ``perform_core_update`` (Update Code), so the preflight's promise that
+    nothing will be stashed holds for the pull that follows it.
+
+    * Mode-only changes do not count (``core.fileMode=false``): installers
+      chmod tracked scripts, and --autostash carries modes across the pull.
+    * Paths under ``SEPARATE_INSTALL_DIRS`` do not count. The match is on
+      the leading folder, not a substring, so
+      ``web_interface/static/v3/js/plugins/x.js`` is still a core edit.
+
+    Returns the changed paths, or None when git could not tell. Raises what
+    ``run`` raises (e.g. ``subprocess.TimeoutExpired``).
+    """
+    run = run or subprocess.run
+    result = run(['git', '-c', 'core.fileMode=false', 'status', '--porcelain',
+                  '--untracked-files=no', '-z'],
+                 cwd=str(project_dir), capture_output=True, text=True, timeout=timeout)
+    if result.returncode != 0:
+        return None
+    changed = []
+    entries = iter((result.stdout or '').split('\0'))
+    for entry in entries:
+        if len(entry) < 4:
+            continue
+        paths = [entry[3:]]
+        if entry[0] in 'RC' or entry[1] in 'RC':
+            paths.append(next(entries, ''))  # -z puts a rename's source next
+        if any(p and p.split('/', 1)[0] not in SEPARATE_INSTALL_DIRS for p in paths):
+            changed.append(paths[0])
+    return changed
+
+
+def describe_local_changes(changed):
+    """Why an automatic update refused to touch a checkout with local edits."""
+    example = f' (for example {changed[0]})' if changed else ''
+    return (f'{len(changed or ()) or "Some"} tracked file(s) in the LEDMatrix folder were edited '
+            f'locally{example}. Automatic updates will not stash your changes; '
+            'commit or revert them, or update manually with Update Code.')
+
+
 def _load_verifier(path):
     spec = importlib.util.spec_from_file_location('ledmatrix_auto_update_verifier', str(path))
     module = importlib.util.module_from_spec(spec)
@@ -346,11 +396,16 @@ class AutoUpdater:
             core = {'outcome': 'error', 'message': f'The LEDMatrix update failed unexpectedly: {e}'}
 
         deferred = core['outcome'] == 'verifying'
-        updated, failed = ([], []) if deferred else self._update_plugins()
+        # A core whose rollback failed is in an unknown state: as when the
+        # health check reports rollback_failed, plugins are left alone and
+        # nothing is restarted onto it.
+        stranded = core['outcome'] == 'rollback_failed'
+        updated, failed = ([], []) if deferred or stranded else self._update_plugins()
         self._store_run(state, core, updated, failed)
         logger.info("Automatic update: core %s (%s); plugins updated=%s failed=%s%s",
                     core['outcome'], core['message'], updated, failed,
-                    '; plugins wait for the health check' if deferred else '')
+                    '; plugins wait for the health check' if deferred
+                    else '; plugins left alone' if stranded else '')
 
         # Code restarts belong to the health check; this only covers plugins.
         if updated:
@@ -424,17 +479,11 @@ class AutoUpdater:
             return 'blocked', ('The current branch has no upstream to update from (or HEAD is detached). '
                                'Use Update Code once, or Tools -> Switch branch.'), {}
 
-        # Mode-only changes are ignored: older installers chmod tracked
+        # The same predicate perform_core_update refuses on when called from
-        # scripts, and --autostash in the pull carries those across. Plugin
+        # here, so what passes this check is never stashed by the pull.
-        # folders are separate installs, as in perform_core_update.
+        changed = local_changes(self.project_root, run=self.run_command)
-        status = self._git('-c', 'core.fileMode=false', 'status', '--porcelain', '--untracked-files=no')
+        if changed is None or changed:
-        changed = [line[3:] for line in status.stdout.splitlines()
+            return 'blocked', describe_local_changes(changed), {}
-                   if line.strip() and 'plugins/' not in line and 'plugin-repos/' not in line]
-        if status.returncode != 0 or changed:
-            example = f' (for example {changed[0]})' if changed else ''
-            return 'blocked', (f'{len(changed) or "Some"} tracked file(s) in the LEDMatrix folder were edited '
-                               f'locally{example}. Automatic updates will not stash your changes; '
-                               'commit or revert them, or update manually with Update Code.'), {}
 
         free = self.disk_free(str(self.project_root))
         if free < MIN_FREE_BYTES:
@@ -479,11 +528,15 @@ class AutoUpdater:
             return {'outcome': 'error', 'message': f'Could not prepare the update health check: {e}.'}
 
         try:
-            core = self.core_update()
+            # Refuse rather than stash: edits made since the preflight are the
+            # user's, and nothing would ever restore a stash taken here.
+            core = self.core_update(stash_local_changes=False)
         except Exception as e:
             logger.exception("perform_core_update raised")
             core = {'status': 'error', 'message': f'Update failed: {e}'}
         new_head = self._git('rev-parse', 'HEAD').stdout.strip()
+        if core.get('local_changes') is not None and new_head == old_head:
+            return {'outcome': 'blocked', 'message': describe_local_changes(core['local_changes'])}
         pending = {
             'status': 'pending',
             'old_head': old_head,

web_interface/blueprints/api_v3/__init__.py

@@ -1274,8 +1274,13 @@ def _set_missing_booleans_to_false(plugin_config, schema_props, form_keys, prefi
                     )
 def _enhance_schema_with_core_properties(schema):
     """
-    Enhance schema with core plugin properties (enabled, display_duration, live_priority).
+    Enhance schema with the core-owned per-plugin properties.
-    These properties are system-managed and should always be allowed even if not in the plugin's schema.
+
+    ``enabled``, ``display_duration``, ``live_priority``, ``skin``,
+    ``skin_options`` and the ``vegas_*`` tuning keys are system-managed and
+    always allowed, even when the plugin's schema doesn't declare them. The
+    list is ``schema_manager.CORE_PLUGIN_PROPERTIES``, the one validation uses,
+    so the save filter keeps exactly what validation accepts.
 
     Args:
         schema: The original JSON schema dict
@@ -1283,44 +1288,31 @@ def _enhance_schema_with_core_properties(schema):
     Returns:
         Enhanced schema dict with core properties injected
     """
-    import copy
+    from src.plugin_system.schema_manager import with_core_plugin_properties
 
     if not schema:
         return schema
+    return with_core_plugin_properties(schema)
 
-    # Core plugin properties that should always be allowed
-    # These match the definitions in SchemaManager.validate_config_against_schema()
-    core_properties = {
-        "enabled": {
-            "type": "boolean",
-            "default": True,
-            "description": "Enable or disable this plugin"
-        },
-        "display_duration": {
-            "type": "number",
-            "default": 15,
-            "minimum": 1,
-            "maximum": 300,
-            "description": "How long to display this plugin in seconds"
-        },
-        "live_priority": {
-            "type": "boolean",
-            "default": False,
-            "description": "Enable live priority takeover when plugin has live content"
-        }
-    }
 
-    # Create a deep copy of the schema to modify (to avoid mutating the original)
+def _prepared_plugin_config(plugin_id, raw_config):
-    enhanced_schema = copy.deepcopy(schema)
+    """A plugin's config section as the plugin runs with it, for on_config_change.
-    if "properties" not in enhanced_schema:
+
-        enhanced_schema["properties"] = {}
+    Loading a plugin reads legacy booleans as objects and fills in schema
+    defaults (PluginManager.prepare_plugin_config); a save's notification must
+    hand over the same shape. Falls back to the raw section.
+    """
+    prepare = getattr(api_v3.plugin_manager, 'prepare_plugin_config', None)
+    if callable(prepare):
+        try:
+            prepared = prepare(plugin_id, raw_config)
+            if isinstance(prepared, dict):
+                return prepared
+        except Exception:
+            logger.debug("Could not prepare config for %s", plugin_id, exc_info=True)
+    return raw_config
 
-    # Inject core properties if they're not already defined in the schema
-    for prop_name, prop_def in core_properties.items():
-        if prop_name not in enhanced_schema["properties"]:
-            enhanced_schema["properties"][prop_name] = copy.deepcopy(prop_def)
 
-    return enhanced_schema
 def _filter_config_by_schema(config, schema, prefix=''):
     """
     Filter config to only include fields defined in the schema.

web_interface/blueprints/api_v3/config.py

@@ -12,13 +12,37 @@ from web_interface.blueprints.api_v3 import (
     success_response,
 )
 from src.common.path_safety import resolve_under
-from src.pi5_matrix_support import is_raspberry_pi_5, pi5_unsupported_settings
+from src.display_geometry import ORIENTATION_ROTATE_DEGREES
+from src.matrix_support import INT_SETTING_LIMITS, describe_range, library_refusals, refusal_message
+from src.pi5_matrix_support import is_raspberry_pi_5
 import web_interface.blueprints.api_v3 as _pkg
+
 # Read through the module rather than bound by value: tests patch these
 # as module attributes, and a value binding would not see the patch.
 # Several are also called from helpers that live in __init__, so the
 # package is the only patch point that covers every caller.
 
+#: Hidden input the v3 settings forms (general.html, display.html,
+#: durations.html) post to /config/main. Its presence tells save_main_config
+#: that a missing checkbox was unchecked, not merely left out of an API call.
+FORM_SECTION_FIELD = '__form_section'
+
+
+def _day_setting(data, day, flat_key, nested_key):
+    """(present, value) of one per-day schedule setting in a POST body.
+
+    The schedule forms post flat keys (``monday_start``), while GET returns
+    the stored shape, ``days.monday.start_time``. Accept both, so a client can
+    post back what it read; a flat key wins when a body carries both.
+    """
+    if flat_key in data:
+        return True, data[flat_key]
+    days = data.get('days')
+    day_config = days.get(day) if isinstance(days, dict) else None
+    if isinstance(day_config, dict) and nested_key in day_config:
+        return True, day_config[nested_key]
+    return False, None
+
 
 @api_v3.route('/config/main', methods=['GET'])
 def get_main_config():
@@ -123,8 +147,8 @@ def save_schedule_config():
                 end_key = f'{day}_end'
 
                 # Check if day is enabled
-                if enabled_key in data:
+                has_enabled, enabled_val = _day_setting(data, day, enabled_key, 'enabled')
-                    enabled_val = data[enabled_key]
+                if has_enabled:
                     # Handle checkbox values that may come as 'on', True, or False
                     if isinstance(enabled_val, str):
                         day_config['enabled'] = enabled_val.lower() in ('true', 'on', '1')
@@ -140,15 +164,8 @@ def save_schedule_config():
                     start_time = None
                     end_time = None
 
-                    if start_key in data and data[start_key]:
+                    start_time = _day_setting(data, day, start_key, 'start_time')[1] or '07:00'
-                        start_time = data[start_key]
+                    end_time = _day_setting(data, day, end_key, 'end_time')[1] or '23:00'
-                    else:
-                        start_time = '07:00'
-
-                    if end_key in data and data[end_key]:
-                        end_time = data[end_key]
-                    else:
-                        end_time = '23:00'
 
                     # Validate time formats
                     is_valid, error_msg = _validate_time_format(start_time)
@@ -352,8 +369,8 @@ def save_dim_schedule_config():
                 end_key = f'{day}_end'
 
                 # Check if day is enabled
-                if enabled_key in data:
+                has_enabled, enabled_val = _day_setting(data, day, enabled_key, 'enabled')
-                    enabled_val = data[enabled_key]
+                if has_enabled:
                     if isinstance(enabled_val, str):
                         day_config['enabled'] = enabled_val.lower() in ('true', 'on', '1')
                     else:
@@ -364,8 +381,8 @@ def save_dim_schedule_config():
                 # Only add times if day is enabled
                 if day_config.get('enabled', True):
                     enabled_days_count += 1
-                    start_time = data.get(start_key) or '20:00'
+                    start_time = _day_setting(data, day, start_key, 'start_time')[1] or '20:00'
-                    end_time = data.get(end_key) or '07:00'
+                    end_time = _day_setting(data, day, end_key, 'end_time')[1] or '07:00'
 
                     # Validate time formats
                     is_valid, error_msg = _validate_time_format(start_time)
@@ -433,8 +450,10 @@ def save_main_config():
 
         # Try to get JSON data first, fallback to form data
         data = None
-        if request.content_type == 'application/json':
+        if request.is_json:
             data = request.get_json()
+            if data is not None and not isinstance(data, dict):
+                return jsonify({'status': 'error', 'message': 'Request body must be a JSON object'}), 400
         else:
             # Handle form data
             data = request.form.to_dict()
@@ -446,6 +465,24 @@ def save_main_config():
         if not data:
             return jsonify({'status': 'error', 'message': 'No data provided'}), 400
 
+        # A missing checkbox means different things to the two kinds of caller.
+        # The settings forms post every field, and a browser leaves an
+        # unchecked box out entirely, so for them absent means False. A JSON
+        # API client (the MQTT bridge's brightness slider, a curl call from the
+        # REST docs) sends only what it is changing, and there absent means
+        # "leave it alone": treating it as unchecked turned off
+        # disable_hardware_pulsing and three other settings on every
+        # brightness change, and weekly auto-updates on every timezone change.
+        # The v3 forms post JSON too (htmx json-enc), so they identify
+        # themselves with a hidden FORM_SECTION_FIELD input. A form-encoded
+        # post is a form by definition.
+        is_form_submission = bool(data.pop(FORM_SECTION_FIELD, None)) or not request.is_json
+
+        def _set_checkbox(section, key, field):
+            """Store checkbox ``field`` as ``section[key]``, if this request sets it."""
+            if is_form_submission or field in data:
+                section[key] = _coerce_to_bool(data.get(field))
+
         # What arrives here is the config itself, and the headers carry the
         # session cookie -- neither belongs in the journal, least of all at
         # ERROR on every save. The shape of the request is the part with
@@ -461,15 +498,16 @@ def save_main_config():
         # Note: Checkboxes don't send data when unchecked, so we need to check if we're updating general settings
         # If any general setting is present, we're updating the general tab
         is_general_update = any(k in data for k in ['timezone', 'city', 'state', 'country', 'web_display_autostart',
-                                                     'auto_discover', 'auto_load_enabled', 'development_mode', 'plugins_directory',
+                                                     'plugins_directory', 'auto_update_enabled'])
-                                                     'auto_update_enabled'])
 
         if is_general_update:
-            # For checkbox: if not present in data during general update, it means unchecked
+            # For checkbox: if not present in data during a general *form*
-            current_config['web_display_autostart'] = _coerce_to_bool(data.get('web_display_autostart'))
+            # update, it means unchecked (see _set_checkbox)
+            _set_checkbox(current_config, 'web_display_autostart', 'web_display_autostart')
+            if is_form_submission or 'auto_update_enabled' in data:
                 if not isinstance(current_config.get('auto_update'), dict):
                     current_config['auto_update'] = {}
-            current_config['auto_update']['enabled'] = _coerce_to_bool(data.get('auto_update_enabled'))
+                _set_checkbox(current_config['auto_update'], 'enabled', 'auto_update_enabled')
 
         if 'timezone' in data:
             current_config['timezone'] = data['timezone']
@@ -520,10 +558,14 @@ def save_main_config():
             if 'plugin_system' not in current_config:
                 current_config['plugin_system'] = {}
 
-            # Handle plugin system checkboxes - always set to handle unchecked state
+            # auto_discover / auto_load_enabled / development_mode are read by
-            # HTML checkboxes omit the key when unchecked, so missing key = unchecked = False
+            # nothing and no longer have General-tab toggles. The form still
-            for checkbox in ['auto_discover', 'auto_load_enabled', 'development_mode']:
+            # posts plugins_directory, so treating a missing key as an
-                current_config['plugin_system'][checkbox] = _coerce_to_bool(data.get(checkbox))
+            # unchecked box would rewrite stored values to false on every
+            # save; only store what a client actually sends.
+            for legacy_flag in ['auto_discover', 'auto_load_enabled', 'development_mode']:
+                if legacy_flag in data:
+                    current_config['plugin_system'][legacy_flag] = _coerce_to_bool(data.get(legacy_flag))
 
             # Handle plugins_directory
             if 'plugins_directory' in data:
@@ -561,28 +603,20 @@ def save_main_config():
                 return jsonify({'status': 'error', 'message': 'pixel_mapper_config must be a string (e.g. "U-mapper;Rotate:90" or empty)'}), 400
 
             # Validate orientation (physical mounting rotation; composed onto pixel_mapper_config at runtime)
-            ORIENTATION_ALLOWED = {'normal', '180'}
+            ORIENTATION_ALLOWED = set(ORIENTATION_ROTATE_DEGREES)
             if 'orientation' in data and data['orientation'] not in ORIENTATION_ALLOWED:
                 return jsonify({'status': 'error', 'message': f"Invalid orientation '{data['orientation']}'. Allowed values: {', '.join(sorted(ORIENTATION_ALLOWED))}"}), 400
 
-            # Panel geometry, PWM and GPIO timing, held to what the rgbmatrix library
+            # Panel geometry, PWM and GPIO timing, held to what the rgbmatrix
-            # accepts (RGBMatrix::Options::Validate in lib/options-initialize.cc,
+            # library and its Python binding accept (src/matrix_support.py:
-            # the gpio_slowdown check in lib/led-matrix.cc). Outside those ranges
+            # Options::Validate, the gpio_slowdown check, and the binding's
-            # the config used to save, then the matrix refused to start and the
+            # uint8_t setters, which cap chain_length at 255). Outside those
-            # display dropped to fallback mode. cols, chain_length and
+            # ranges the library returns no matrix and the display service
-            # limit_refresh_rate_hz (0 = no cap) have no upper bound in the
+            # crash-loops rather than falling back, so they never save.
-            # library. rows has none here by choice: the library currently
+            def _hardware_int_error(field, low, high, even=False):
-            # rejects more than 64 per panel, and that limit is left to it so a
-            # library that lifts it needs no change here.
-            def _hardware_int_error(field, low, high=None, even=False):
                 """A 400 response if data[field] is not an allowed integer, else None."""
                 raw = data[field]
-                kind = "an even integer" if even else "an integer"
+                rejection = (jsonify({'status': 'error', 'message': f"Invalid {field} '{raw}'. Must be {describe_range(low, high, even)}."}), 400)
-                if high is None:
-                    allowed = f"{kind} of at least {low}"
-                else:
-                    allowed = f"{kind} from {low} to {high}"
-                rejection = (jsonify({'status': 'error', 'message': f"Invalid {field} '{raw}'. Must be {allowed}."}), 400)
                 # int() would quietly turn true into 1 and 48.5 into 48.
                 if isinstance(raw, bool) or (isinstance(raw, float) and not raw.is_integer()):
                     return rejection
@@ -590,34 +624,31 @@ def save_main_config():
                     value = int(raw)
                 except (ValueError, TypeError, OverflowError):
                     return rejection
-                if value < low or (high is not None and value > high) or (even and value % 2):
+                if value < low or value > high or (even and value % 2):
                     return rejection
                 return None
 
-            for field, low, high, even in (('rows', 8, None, True), ('cols', 16, None, False),
+            # rp1_rio has its own check below.
-                                           ('chain_length', 1, None, False), ('parallel', 1, 3, False),
+            for field, (_section, low, high, even) in INT_SETTING_LIMITS.items():
-                                           ('brightness', 1, 100, False), ('scan_mode', 0, 1, False),
+                if field in data and field != 'rp1_rio':
-                                           ('pwm_bits', 1, 11, False), ('pwm_dither_bits', 0, 2, False),
-                                           ('pwm_lsb_nanoseconds', 50, 3000, False),
-                                           ('limit_refresh_rate_hz', 0, None, False),
-                                           ('row_address_type', 0, 5, False), ('multiplexing', 0, 22, False),
-                                           ('gpio_slowdown', 0, 10, False)):
-                if field in data:
                     error = _hardware_int_error(field, low, high, even)
                     if error:
                         return error
 
-            # A Pi 5 can't drive every combination (src/pi5_matrix_support.py),
+            # Combinations the library can't start with: a hardware mapping it
-            # and one it can't crashes the display service instead of falling
+            # doesn't have, more parallel chains than the mapping has outputs,
-            # back. Checked only when this request sets one of those fields, so
+            # and on a Pi 5 its narrower RP1 support. Reported only when this
-            # a combination already stored doesn't block unrelated saves.
+            # request sets one of the settings involved, so a problem already
-            pi5_fields = ('row_address_type', 'parallel', 'hardware_mapping')
+            # stored doesn't block unrelated saves.
-            if any(k in data for k in pi5_fields) and is_raspberry_pi_5():
+            combination_fields = ('hardware_mapping', 'parallel', 'row_address_type')
+            if any(k in data for k in combination_fields):
                 effective = dict(current_config['display']['hardware'])
-                effective.update({k: data[k] for k in pi5_fields if k in data})
+                effective.update({k: v for k, v in data.items()
-                unsupported = pi5_unsupported_settings(effective)
+                                  if k in combination_fields or k in INT_SETTING_LIMITS})
-                if unsupported:
+                refusals = [r for r in library_refusals(effective, pi5=is_raspberry_pi_5())
-                    return jsonify({'status': 'error', 'message': unsupported}), 400
+                            if any(f in data for f in r.fields)]
+                if refusals:
+                    return jsonify({'status': 'error', 'message': refusal_message(refusals)}), 400
 
             # Handle hardware settings
             for field in ['rows', 'cols', 'chain_length', 'parallel', 'brightness', 'hardware_mapping', 'scan_mode',
@@ -646,10 +677,10 @@ def save_main_config():
 
             # Handle checkboxes - coerce to bool to ensure proper JSON types
             for checkbox in ['disable_hardware_pulsing', 'inverse_colors', 'show_refresh_rate']:
-                current_config['display']['hardware'][checkbox] = _coerce_to_bool(data.get(checkbox))
+                _set_checkbox(current_config['display']['hardware'], checkbox, checkbox)
 
-            # Handle display-level checkboxes (always set to handle unchecked state)
+            # Handle display-level checkboxes (unchecked state on form saves)
-            current_config['display']['use_short_date_format'] = _coerce_to_bool(data.get('use_short_date_format'))
+            _set_checkbox(current_config['display'], 'use_short_date_format', 'use_short_date_format')
 
             # Handle dynamic duration settings
             if 'max_dynamic_duration_seconds' in data:
@@ -671,8 +702,11 @@ def save_main_config():
             # checkbox, so when the feature is off we accept the values without
             # rejecting the whole save — otherwise a stale copies/chain_length
             # mismatch locks the user out of every other display setting.
+            if is_form_submission or 'double_sided_enabled' in data:
                 enabled = _coerce_to_bool(data.get('double_sided_enabled'))
                 ds_config['enabled'] = enabled
+            else:
+                enabled = _coerce_to_bool(ds_config.get('enabled'))
 
             def _copies_fits_hardware(copies: int) -> Optional[str]:
                 """Error message if copies doesn't divide the panel evenly, else None."""
@@ -742,15 +776,13 @@ def save_main_config():
             # Handle enabled checkbox
             # HTML checkboxes omit the key entirely when unchecked, so if the form
             # was submitted (any vegas field present) but enabled key is missing,
-            # the checkbox was unchecked and we should set enabled=False
+            # the checkbox was unchecked and we should set enabled=False.
-            vegas_config['enabled'] = _coerce_to_bool(data.get('vegas_scroll_enabled'))
+            # A JSON API call only changes the checkboxes it sends.
-            vegas_config['auto_trim'] = _coerce_to_bool(data.get('vegas_auto_trim'))
+            _set_checkbox(vegas_config, 'enabled', 'vegas_scroll_enabled')
-            vegas_config['dynamic_duration_enabled'] = _coerce_to_bool(
+            _set_checkbox(vegas_config, 'auto_trim', 'vegas_auto_trim')
-                data.get('vegas_dynamic_duration_enabled'))
+            _set_checkbox(vegas_config, 'dynamic_duration_enabled', 'vegas_dynamic_duration_enabled')
-            vegas_config['continuous_scroll'] = _coerce_to_bool(
+            _set_checkbox(vegas_config, 'continuous_scroll', 'vegas_continuous_scroll')
-                data.get('vegas_continuous_scroll'))
+            _set_checkbox(vegas_config, 'smooth_scroll', 'vegas_smooth_scroll')
-            vegas_config['smooth_scroll'] = _coerce_to_bool(
-                data.get('vegas_smooth_scroll'))
 
             # max_plugin_width_ratio is the one fractional setting, so it is
             # handled outside the integer loop below.
@@ -916,8 +948,12 @@ def save_main_config():
         # them AGAIN as bogus top-level config keys (e.g. "clock_duration": 30
         # sitting at config root alongside the correct
         # display.display_durations.clock_duration).
+        # The Vegas cycle-time fields (vegas_min_cycle_duration, ...) share the
+        # suffix but are Vegas settings, already handled above: counting them
+        # here wrote junk mode durations, and a blank one 400'd the save.
         duration_fields = [k for k in list(data.keys())
-                           if k.endswith('_duration') or k in ('default_duration', 'transition_duration')]
+                           if (k.endswith('_duration') and k not in vegas_fields)
+                           or k in ('default_duration', 'transition_duration')]
         if duration_fields:
             if 'display' not in current_config:
                 current_config['display'] = {}
@@ -957,9 +993,14 @@ def save_main_config():
                 current_config['display']['display_durations'][mode_key] = int_value
 
         # Handle plugin configurations dynamically
-        # Any key that matches a plugin ID should be saved as plugin config
+        # Any key that matches a plugin ID is that plugin's settings. They go
-        # This includes proper secret field handling from schema
+        # through the same preparation as POST /plugins/config -- merged onto
+        # the stored section, legacy booleans and schema defaults applied,
+        # filtered, validated, secrets split out -- so this route can't store
+        # a config that one rejects (stored verbatim, it left the plugin
+        # flagged degraded at its next load).
         plugin_keys_to_remove = []
+        plugin_secrets_updates = {}
         # Discovered first: a plugin key not recognised here skips secret
         # separation below and falls through to the generic merge, which wrote
         # the plugin's API key into config.json in plain text whenever nothing
@@ -969,26 +1010,22 @@ def save_main_config():
             # Check if this key is a plugin ID
             if api_v3.plugin_manager and key in plugin_manifests:
                 plugin_id = key
-                plugin_config = data[key]
+                submitted_config = data[key]
+                if not isinstance(submitted_config, dict):
+                    return error_response(
+                        ErrorCode.VALIDATION_ERROR,
+                        f"Settings for plugin '{plugin_id}' must be a JSON object",
+                        status_code=400
+                    )
 
-                # Load plugin schema to identify secret fields (same logic as save_plugin_config)
-                secret_fields = set()
-                if api_v3.plugin_manager:
-                    plugins_dir = api_v3.plugin_manager.plugins_dir
-                else:
-                    plugin_system_config = current_config.get('plugin_system', {})
-                    plugins_dir_name = plugin_system_config.get('plugins_directory', 'plugin-repos')
-                    if os.path.isabs(plugins_dir_name):
-                        plugins_dir = Path(plugins_dir_name)
-                    else:
-                        plugins_dir = PROJECT_ROOT / plugins_dir_name
                 # plugin_id is already known to be a loaded plugin (the
                 # membership test above), so this cannot currently traverse --
                 # but the path is built from a request key, and the guard and
-                # the join are far enough apart that a later edit could
+                # the schema load are far enough apart that a later edit could
-                # separate them. Build it through the shared helper instead.
+                # separate them. Refuse rather than save without knowing which
-                schema_path = resolve_under(plugins_dir, plugin_id, 'config_schema.json')
+                # fields are secrets.
-
+                schema_path = resolve_under(api_v3.plugin_manager.plugins_dir,
+                                            plugin_id, 'config_schema.json')
                 if schema_path is None:
                     return error_response(
                         ErrorCode.VALIDATION_ERROR,
@@ -996,52 +1033,40 @@ def save_main_config():
                         status_code=400
                     )
 
-                if schema_path.exists():
+                schema_mgr = api_v3.schema_manager
-                    try:
+                if not schema_mgr:
-                        with open(schema_path, 'r', encoding='utf-8') as f:
+                    return error_response(
-                            schema = json.load(f)
+                        ErrorCode.SYSTEM_ERROR,
-                            if 'properties' in schema:
+                        'Schema manager not initialized',
-                                secret_fields = find_secret_fields(schema['properties'])
+                        status_code=500
-                    except Exception as e:
+                    )
-                        logger.debug("Error reading schema for secret detection: %s", e)
+                schema = schema_mgr.load_schema(plugin_id, use_cache=False)
 
-                # Separate secrets from regular config (same logic as save_plugin_config)
+                from web_interface.blueprints.api_v3.plugins import (
-                regular_config, secrets_config = separate_secrets(plugin_config, secret_fields)
+                    _merge_onto_stored_plugin_config, _prepare_plugin_config_for_save,
-                # The config form renders secrets masked, so every save posts
+                )
-                # them back blank. Without this the blank is merged over the
+                plugin_config = _merge_onto_stored_plugin_config(
-                # stored value and the credential is destroyed by the act of
+                    plugin_id, submitted_config, current_config)
-                # changing an unrelated setting. A blank means "unchanged".
+                regular_config, secrets_config, error = _prepare_plugin_config_for_save(
-                secrets_config = remove_empty_secrets(secrets_config)
+                    plugin_id, plugin_config, schema, schema_mgr, is_json=True)
-
+                if error:
-                # PRE-PROCESSING: Preserve 'enabled' state if not in regular_config
+                    return error
-                # This prevents overwriting the enabled state when saving config from a form that doesn't include the toggle
-                if 'enabled' not in regular_config:
-                    try:
-                        if plugin_id in current_config and 'enabled' in current_config[plugin_id]:
-                            regular_config['enabled'] = current_config[plugin_id]['enabled']
-                        elif api_v3.plugin_manager:
-                            # Fallback to plugin instance if config doesn't have it
-                            plugin_instance = api_v3.plugin_manager.get_plugin(plugin_id)
-                            if plugin_instance:
-                                regular_config['enabled'] = plugin_instance.enabled
-                        # Final fallback: default to True if plugin is loaded (matches BasePlugin default)
-                        if 'enabled' not in regular_config:
-                            regular_config['enabled'] = True
-                    except Exception as e:
-                        logger.debug("Error preserving enabled state: %s", e)
-                        # Default to True on error to avoid disabling plugins
-                        regular_config['enabled'] = True
-
-                # Get current secrets config
-                current_secrets = api_v3.config_manager.get_raw_file_content('secrets')
 
                 # Deep merge regular config into main config
-                if plugin_id not in current_config:
+                stored_section = current_config.get(plugin_id)
-                    current_config[plugin_id] = {}
+                current_config[plugin_id] = deep_merge(
-                current_config[plugin_id] = deep_merge(current_config[plugin_id], regular_config)
+                    stored_section if isinstance(stored_section, dict) else {}, regular_config)
-
-                # Deep merge secrets into secrets config
                 if secrets_config:
+                    plugin_secrets_updates[plugin_id] = secrets_config
+
+                # Mark for removal from data dict (already processed)
+                plugin_keys_to_remove.append(key)
+
+        # Deep merge secrets into secrets config, once every plugin section
+        # has validated
+        if plugin_secrets_updates:
+            current_secrets = api_v3.config_manager.get_raw_file_content('secrets')
+            for plugin_id, secrets_config in plugin_secrets_updates.items():
                 if plugin_id not in current_secrets:
                     current_secrets[plugin_id] = {}
                 # Lists merge by replacement, so deep_merge here wrote a
@@ -1051,23 +1076,6 @@ def save_main_config():
             # Save secrets file
             api_v3.config_manager.save_raw_file_content('secrets', current_secrets)
 
-                # Mark for removal from data dict (already processed)
-                plugin_keys_to_remove.append(key)
-
-                # Notify plugin of config change if loaded (with merged config including secrets)
-                try:
-                    if api_v3.plugin_manager:
-                        plugin_instance = api_v3.plugin_manager.get_plugin(plugin_id)
-                        if plugin_instance:
-                            # Reload merged config (includes secrets) and pass the plugin-specific section
-                            merged_config = api_v3.config_manager.load_config()
-                            plugin_full_config = merged_config.get(plugin_id, {})
-                            if hasattr(plugin_instance, 'on_config_change'):
-                                plugin_instance.on_config_change(plugin_full_config)
-                except Exception as hook_err:
-                    # Don't fail the save if hook fails
-                    logger.warning("on_config_change failed: %s", hook_err)
-
         # Remove processed plugin keys from data (they're already in current_config)
         for key in plugin_keys_to_remove:
             del data[key]
@@ -1115,6 +1123,19 @@ def save_main_config():
         except ImportError:
             pass
 
+        # Notify saved plugins of their new config (with secrets merged), now
+        # that it is on disk.
+        for plugin_id in plugin_keys_to_remove:
+            try:
+                plugin_instance = api_v3.plugin_manager.get_plugin(plugin_id)
+                if plugin_instance and hasattr(plugin_instance, 'on_config_change'):
+                    merged_config = api_v3.config_manager.load_config()
+                    plugin_instance.on_config_change(_pkg._prepared_plugin_config(
+                        plugin_id, merged_config.get(plugin_id, {})))
+            except Exception as hook_err:
+                # Don't fail the save if hook fails
+                logger.warning("on_config_change failed: %s", hook_err)
+
         message = 'Configuration saved successfully'
         # Switching automatic updates on finishes their setup, which needs
         # the display service to restart (web_interface/auto_update.py).
@@ -1167,10 +1188,27 @@ def save_raw_main_config():
         if not data:
             return jsonify({'status': 'error', 'message': 'No data provided'}), 400
 
+        was_auto_update_enabled = False
+        try:
+            previous = api_v3.config_manager.get_raw_file_content('main') or {}
+            was_auto_update_enabled = bool((previous.get('auto_update') or {}).get('enabled'))
+        except Exception:
+            logger.debug("Could not read the previous auto_update setting", exc_info=True)
+
         # Save the raw config file
         api_v3.config_manager.save_raw_file_content('main', data)
 
-        return jsonify({'status': 'success', 'message': 'Main configuration saved successfully'})
+        message = 'Main configuration saved successfully'
+        # Same hook as save_main_config: switching automatic updates on here
+        # must finish their setup too, not wait for the next service restart.
+        try:
+            from web_interface import auto_update
+            note = auto_update.start_setup_if_needed(was_auto_update_enabled, data)
+            if note:
+                message = f'{message}. {note}'
+        except Exception:
+            logger.warning("Automatic update setup could not be started", exc_info=True)
+        return jsonify({'status': 'success', 'message': message})
     except Exception as e:
         from src.exceptions import ConfigError
         logger.error("Error saving raw main config", exc_info=True)

web_interface/blueprints/api_v3/plugins.py

@@ -792,12 +792,16 @@ def get_plugin_config():
         main_config = api_v3.config_manager.load_config()
         plugin_config = main_config.get(plugin_id, {})
 
-        # Merge with defaults from schema so form shows default values for missing fields
+        # Merge with defaults from schema so form shows default values for
+        # missing fields, reading legacy booleans as objects first: what the
+        # plugin runs with, and what posts back through the JSON save
         schema_mgr = api_v3.schema_manager
         if schema_mgr:
             try:
+                from src.plugin_system.schema_manager import prepare_plugin_config
                 defaults = schema_mgr.generate_default_config(plugin_id, use_cache=True)
-                plugin_config = schema_mgr.merge_with_defaults(plugin_config, defaults)
+                plugin_config = prepare_plugin_config(
+                    plugin_config, schema_mgr.load_schema(plugin_id, use_cache=True), defaults)
             except Exception as e:
                 # Log but don't fail - defaults merge is best effort
                 import logging
@@ -988,6 +992,7 @@ def update_plugin():
             )
 
         current_last_updated = None
+        current_version = None
         current_commit = None
         current_branch = None
 
@@ -997,6 +1002,7 @@ def update_plugin():
                 with open(manifest_path, 'r', encoding='utf-8') as f:
                     manifest = json.load(f)
                     current_last_updated = manifest.get('last_updated')
+                    current_version = manifest.get('version')
                 if manifest.get('local_only'):
                     logger.debug("Skipping update for local-only plugin: %s", plugin_id)
                     if api_v3.operation_history:
@@ -1006,7 +1012,9 @@ def update_plugin():
                             status="skipped",
                             details={"reason": "local_only"}
                         )
-                    return success_response(message=f'Plugin {plugin_id} is managed locally and does not receive registry updates')
+                    return success_response(
+                        data={'update_status': 'local_only'},
+                        message=f'Plugin {plugin_id} is managed locally and does not receive registry updates')
             except Exception as e:
                 logger.debug("Could not read local manifest for plugin: %s", e)
 
@@ -1036,12 +1044,14 @@ def update_plugin():
 
         if success:
             updated_last_updated = current_last_updated
+            updated_version = current_version
             try:
                 if manifest_path.exists():
                     import json
                     with open(manifest_path, 'r', encoding='utf-8') as f:
                         manifest = json.load(f)
                         updated_last_updated = manifest.get('last_updated', current_last_updated)
+                        updated_version = manifest.get('version', current_version)
             except Exception as e:
                 logger.debug("Could not read updated manifest after update: %s", e)
 
@@ -1053,15 +1063,28 @@ def update_plugin():
                     updated_commit = git_info_after.get('sha')
                     updated_branch = git_info_after.get('branch') or updated_branch
 
+            # update_plugin() answers True for "nothing to do" as well as for
+            # a real update (a ZIP-installed monorepo plugin already at the
+            # registry version, a bundled plugin), so what changed is read off
+            # the plugin itself: its git commit, else its manifest.
+            update_status = 'updated'
             message = f'Plugin {plugin_id} updated successfully'
             if current_commit and updated_commit and current_commit == updated_commit:
+                update_status = 'up_to_date'
                 message = f'Plugin {plugin_id} already up to date (commit {updated_commit[:7]})'
             elif updated_commit:
                 message = f'Plugin {plugin_id} updated to commit {updated_commit[:7]}'
                 if updated_branch:
                     message += f' on branch {updated_branch}'
+            elif updated_version and updated_version != current_version:
+                message = f'Plugin {plugin_id} updated to version {updated_version}'
             elif updated_last_updated and updated_last_updated != current_last_updated:
                 message = f'Plugin {plugin_id} refreshed (Last Updated {updated_last_updated})'
+            elif not current_commit:
+                update_status = 'up_to_date'
+                message = f'Plugin {plugin_id} already up to date'
+                if updated_version:
+                    message += f' (version {updated_version})'
 
             remote_commit_short = remote_commit[:7] if remote_commit else None
             if remote_commit_short and updated_commit and remote_commit_short != updated_commit[:7]:
@@ -1093,14 +1116,16 @@ def update_plugin():
                         "version": version,
                         "previous_commit": current_commit[:7] if current_commit else None,
                         "commit": updated_commit[:7] if updated_commit else None,
-                        "branch": updated_branch
+                        "branch": updated_branch,
+                        "update_status": update_status
                     }
                 )
 
             return success_response(
                 data={
                     'last_updated': updated_last_updated,
-                    'commit': updated_commit
+                    'commit': updated_commit,
+                    'update_status': update_status
                 },
                 message=message
             )
@@ -1725,7 +1750,14 @@ def save_plugin_config():
             if error:
                 return error
             plugin_id = data['plugin_id']
-            plugin_config = data.get('config', {})
+            submitted_config = data.get('config', {})
+            if not isinstance(submitted_config, dict):
+                return error_response(
+                    ErrorCode.INVALID_INPUT,
+                    'config must be a JSON object',
+                    status_code=400
+                )
+            plugin_config = _merge_onto_stored_plugin_config(plugin_id, submitted_config)
         else:
             # Form data (HTMX submission)
             # plugin_id comes from query string, config from form fields
@@ -2162,11 +2194,168 @@ def save_plugin_config():
         if 'application/json' in content_type:
             schema = schema_mgr.load_schema(plugin_id, use_cache=False)
 
+        regular_config, secrets_config, error = _prepare_plugin_config_for_save(
+            plugin_id, plugin_config, schema, schema_mgr,
+            is_json='application/json' in content_type)
+        if error:
+            return error
+
+        # Get current configs
+        current_config = api_v3.config_manager.load_config()
+        current_secrets = api_v3.config_manager.get_raw_file_content('secrets')
+
+        # Deep merge plugin configuration in main config (preserves nested structures)
+        if plugin_id not in current_config:
+            current_config[plugin_id] = {}
+
+        current_config[plugin_id] = deep_merge(current_config[plugin_id], regular_config)
+
+        # Deep merge plugin secrets in secrets config
+        if secrets_config:
+            if plugin_id not in current_secrets:
+                current_secrets[plugin_id] = {}
+            # See above -- secrets lists must merge element-wise.
+            current_secrets[plugin_id] = merge_secrets(
+                current_secrets[plugin_id], secrets_config)
+            # Save secrets file
+            try:
+                api_v3.config_manager.save_raw_file_content('secrets', current_secrets)
+            except PermissionError as e:
+                # Log the error with more details
+                import os
+                secrets_path = api_v3.config_manager.secrets_path
+                secrets_dir = os.path.dirname(secrets_path) if secrets_path else None
+                
+                # Check permissions
+                dir_readable = os.access(secrets_dir, os.R_OK) if secrets_dir and os.path.exists(secrets_dir) else False
+                dir_writable = os.access(secrets_dir, os.W_OK) if secrets_dir and os.path.exists(secrets_dir) else False
+                file_writable = os.access(secrets_path, os.W_OK) if secrets_path and os.path.exists(secrets_path) else False
+                
+                logger.error(
+                    f"Permission error saving secrets config for {plugin_id}: {e}\n"
+                    f"Secrets path: {secrets_path}\n"
+                    f"Directory readable: {dir_readable}, writable: {dir_writable}\n"
+                    f"File writable: {file_writable}",
+                    exc_info=True
+                )
+                return error_response(
+                    ErrorCode.CONFIG_SAVE_FAILED,
+                    f"Failed to save secrets configuration: Permission denied. Check file permissions on {secrets_path}",
+                    status_code=500
+                )
+            except Exception as e:
+                # Log the error but don't fail the entire config save
+                import os
+                secrets_path = api_v3.config_manager.secrets_path
+                logger.error("Error saving secrets config for %s (path=%s)", plugin_id, secrets_path, exc_info=True)
+                # Return error response with more context
+                return error_response(
+                    ErrorCode.CONFIG_SAVE_FAILED,
+                    "Failed to save secrets configuration; see logs for details",
+                    status_code=500
+                )
+
+        # Save the updated main config using atomic save
+        success, error_msg = _pkg._save_config_atomic(api_v3.config_manager, current_config, create_backup=True)
+        if not success:
+            return error_response(
+                ErrorCode.CONFIG_SAVE_FAILED,
+                f"Failed to save configuration: {error_msg}",
+                status_code=500
+            )
+
+        # If the plugin is loaded, notify it of the config change with merged config
+        try:
+            if api_v3.plugin_manager:
+                plugin_instance = api_v3.plugin_manager.get_plugin(plugin_id)
+                if plugin_instance:
+                    # Reload merged config (includes secrets) and pass the plugin-specific section
+                    merged_config = api_v3.config_manager.load_config()
+                    plugin_full_config = _pkg._prepared_plugin_config(
+                        plugin_id, merged_config.get(plugin_id, {}))
+                    if hasattr(plugin_instance, 'on_config_change'):
+                        plugin_instance.on_config_change(plugin_full_config)
+
+                    # Update plugin state manager and call lifecycle methods based on enabled state
+                    # This ensures the plugin state is synchronized with the config
+                    enabled = plugin_full_config.get('enabled', plugin_instance.enabled)
+
+                    # Update state manager if available
+                    if api_v3.plugin_state_manager:
+                        api_v3.plugin_state_manager.set_plugin_enabled(plugin_id, enabled)
+
+                    # Call lifecycle methods to ensure plugin state matches config
+                    try:
+                        if enabled:
+                            if hasattr(plugin_instance, 'on_enable'):
+                                plugin_instance.on_enable()
+                        else:
+                            if hasattr(plugin_instance, 'on_disable'):
+                                plugin_instance.on_disable()
+                    except Exception as lifecycle_error:
+                        # Log the error but don't fail the save - config is already saved
+                        import logging
+                        logging.warning(f"Lifecycle method error for {plugin_id}: {lifecycle_error}", exc_info=True)
+        except Exception as hook_err:
+            # Do not fail the save if hook fails; just log
+            logger.warning("on_config_change failed: %s", hook_err)
+
+        secret_count = len(secrets_config)
+        message = f'Plugin {plugin_id} configuration saved successfully'
+        if secret_count > 0:
+            message += f' ({secret_count} secret field(s) saved to config_secrets.json)'
+
+        return success_response(message=message)
+    except Exception as e:
+        from src.web_interface.errors import WebInterfaceError
+        error = WebInterfaceError.from_exception(e, ErrorCode.CONFIG_SAVE_FAILED)
+        if api_v3.operation_history:
+            api_v3.operation_history.record_operation(
+                "configure",
+                plugin_id=data.get('plugin_id') if 'data' in locals() else None,
+                status="failed",
+                error=str(e)
+            )
+        return error_response(
+            error.error_code,
+            error.message,
+            details=error.details,
+            context=error.context,
+            status_code=500
+        )
+def _merge_onto_stored_plugin_config(plugin_id, submitted_config, current_config=None):
+    """A JSON plugin-config body merged onto the plugin's stored section.
+
+    A JSON body carries the settings being changed, as a form post does: the
+    rest keep their stored values. Built from defaults alone, a body such as
+    ``{"enabled": true}`` reset every unsent setting of the plugin.
+    ``current_config`` is the loaded main config when the caller has one.
+    """
+    import copy
+    if current_config is None:
+        current_config = api_v3.config_manager.load_config()
+    stored = current_config.get(plugin_id)
+    base = copy.deepcopy(stored) if isinstance(stored, dict) else {}
+    return deep_merge(base, submitted_config)
+
+
+def _prepare_plugin_config_for_save(plugin_id, plugin_config, schema, schema_mgr, is_json):
+    """Turn a submitted plugin config into what gets stored.
+
+    Fixes array shapes, keeps the enabled state, reads legacy booleans and
+    applies schema defaults, normalizes value types, filters to the schema plus
+    the core-owned per-plugin properties, validates, and splits out secrets.
+    Shared by POST /plugins/config and plugin sections posted to
+    POST /config/main, so both store the same thing.
+
+    Returns ``(regular_config, secrets_config, None)``, or
+    ``(None, None, error_response)`` when validation fails.
+    """
     # JSON path: fix numeric-keyed dicts that should be arrays.
     # JS dotToNested() converts feeds.custom_feeds.0.name → {'0': {name:...}}
     # instead of [{name:...}]. The form-data path has fix_array_structures for this;
     # mirror that logic here for JSON submissions.
-        if 'application/json' in content_type and schema and 'properties' in schema:
+    if is_json and schema and 'properties' in schema:
         def _fix_json_arrays(cfg, props):
             for k, ps in props.items():
                 if not isinstance(cfg, dict) or k not in cfg:
@@ -2240,8 +2429,12 @@ def save_plugin_config():
         preserved_enabled = plugin_config['enabled']
 
     if schema:
+        # Legacy booleans read as {"enabled": ...} objects first (#588), the
+        # same preparation loading applies, so a config the device reads
+        # without complaint also saves.
+        from src.plugin_system.schema_manager import prepare_plugin_config
         defaults = schema_mgr.generate_default_config(plugin_id, use_cache=True)
-            plugin_config = schema_mgr.merge_with_defaults(plugin_config, defaults)
+        plugin_config = prepare_plugin_config(plugin_config, schema, defaults)
 
     # After merging defaults, replace any None array values with their schema defaults.
     # merge_with_defaults gives user config higher priority, so a None submitted by
@@ -2496,19 +2689,8 @@ def save_plugin_config():
         # below -- so logging it wrote live credentials to the journal.
         logger.info(f"Config keys being validated: {list(plugin_config.keys())}")
 
-            # Get enhanced schema keys (including injected core properties)
+        # Schema keys including the injected core properties, for the error
-            # We need to create an enhanced schema to get the actual allowed keys
+        enhanced_schema = _enhance_schema_with_core_properties(schema)
-            import copy
-            enhanced_schema = copy.deepcopy(schema)
-            if "properties" not in enhanced_schema:
-                enhanced_schema["properties"] = {}
-
-            # Core properties that are always injected during validation
-            core_properties = ["enabled", "display_duration", "live_priority"]
-            for prop_name in core_properties:
-                if prop_name not in enhanced_schema["properties"]:
-                    # Add placeholder to get the full list of allowed keys
-                    enhanced_schema["properties"][prop_name] = {"type": "any"}
 
         is_valid, validation_errors = schema_mgr.validate_config_against_schema(
             plugin_config, schema, plugin_id
@@ -2522,13 +2704,9 @@ def save_plugin_config():
             logger.error(f"Schema properties: {list(enhanced_schema.get('properties', {}).keys())}")
 
             # Also print to console for immediate visibility
-                import json
             logger.warning("Config validation failed for plugin (see debug logs)")
 
-                # Log raw form data if this was a form submission
+            return None, None, error_response(
-                if 'application/json' not in (request.content_type or ''):
-                    form_data = request.form.to_dict()
-                return error_response(
                 ErrorCode.CONFIG_VALIDATION_FAILED,
                 'Configuration validation failed',
                 details='; '.join(validation_errors) if validation_errors else 'Unknown validation error',
@@ -2555,128 +2733,9 @@ def save_plugin_config():
     # changing an unrelated setting. A blank means "unchanged".
     secrets_config = remove_empty_secrets(secrets_config)
 
-        # Get current configs
+    return regular_config, secrets_config, None
-        current_config = api_v3.config_manager.load_config()
-        current_secrets = api_v3.config_manager.get_raw_file_content('secrets')
 
-        # Deep merge plugin configuration in main config (preserves nested structures)
-        if plugin_id not in current_config:
-            current_config[plugin_id] = {}
 
-        current_config[plugin_id] = deep_merge(current_config[plugin_id], regular_config)
-
-        # Deep merge plugin secrets in secrets config
-        if secrets_config:
-            if plugin_id not in current_secrets:
-                current_secrets[plugin_id] = {}
-            # See above -- secrets lists must merge element-wise.
-            current_secrets[plugin_id] = merge_secrets(
-                current_secrets[plugin_id], secrets_config)
-            # Save secrets file
-            try:
-                api_v3.config_manager.save_raw_file_content('secrets', current_secrets)
-            except PermissionError as e:
-                # Log the error with more details
-                import os
-                secrets_path = api_v3.config_manager.secrets_path
-                secrets_dir = os.path.dirname(secrets_path) if secrets_path else None
-                
-                # Check permissions
-                dir_readable = os.access(secrets_dir, os.R_OK) if secrets_dir and os.path.exists(secrets_dir) else False
-                dir_writable = os.access(secrets_dir, os.W_OK) if secrets_dir and os.path.exists(secrets_dir) else False
-                file_writable = os.access(secrets_path, os.W_OK) if secrets_path and os.path.exists(secrets_path) else False
-                
-                logger.error(
-                    f"Permission error saving secrets config for {plugin_id}: {e}\n"
-                    f"Secrets path: {secrets_path}\n"
-                    f"Directory readable: {dir_readable}, writable: {dir_writable}\n"
-                    f"File writable: {file_writable}",
-                    exc_info=True
-                )
-                return error_response(
-                    ErrorCode.CONFIG_SAVE_FAILED,
-                    f"Failed to save secrets configuration: Permission denied. Check file permissions on {secrets_path}",
-                    status_code=500
-                )
-            except Exception as e:
-                # Log the error but don't fail the entire config save
-                import os
-                secrets_path = api_v3.config_manager.secrets_path
-                logger.error("Error saving secrets config for %s (path=%s)", plugin_id, secrets_path, exc_info=True)
-                # Return error response with more context
-                return error_response(
-                    ErrorCode.CONFIG_SAVE_FAILED,
-                    "Failed to save secrets configuration; see logs for details",
-                    status_code=500
-                )
-
-        # Save the updated main config using atomic save
-        success, error_msg = _pkg._save_config_atomic(api_v3.config_manager, current_config, create_backup=True)
-        if not success:
-            return error_response(
-                ErrorCode.CONFIG_SAVE_FAILED,
-                f"Failed to save configuration: {error_msg}",
-                status_code=500
-            )
-
-        # If the plugin is loaded, notify it of the config change with merged config
-        try:
-            if api_v3.plugin_manager:
-                plugin_instance = api_v3.plugin_manager.get_plugin(plugin_id)
-                if plugin_instance:
-                    # Reload merged config (includes secrets) and pass the plugin-specific section
-                    merged_config = api_v3.config_manager.load_config()
-                    plugin_full_config = merged_config.get(plugin_id, {})
-                    if hasattr(plugin_instance, 'on_config_change'):
-                        plugin_instance.on_config_change(plugin_full_config)
-
-                    # Update plugin state manager and call lifecycle methods based on enabled state
-                    # This ensures the plugin state is synchronized with the config
-                    enabled = plugin_full_config.get('enabled', plugin_instance.enabled)
-
-                    # Update state manager if available
-                    if api_v3.plugin_state_manager:
-                        api_v3.plugin_state_manager.set_plugin_enabled(plugin_id, enabled)
-
-                    # Call lifecycle methods to ensure plugin state matches config
-                    try:
-                        if enabled:
-                            if hasattr(plugin_instance, 'on_enable'):
-                                plugin_instance.on_enable()
-                        else:
-                            if hasattr(plugin_instance, 'on_disable'):
-                                plugin_instance.on_disable()
-                    except Exception as lifecycle_error:
-                        # Log the error but don't fail the save - config is already saved
-                        import logging
-                        logging.warning(f"Lifecycle method error for {plugin_id}: {lifecycle_error}", exc_info=True)
-        except Exception as hook_err:
-            # Do not fail the save if hook fails; just log
-            logger.warning("on_config_change failed: %s", hook_err)
-
-        secret_count = len(secrets_config)
-        message = f'Plugin {plugin_id} configuration saved successfully'
-        if secret_count > 0:
-            message += f' ({secret_count} secret field(s) saved to config_secrets.json)'
-
-        return success_response(message=message)
-    except Exception as e:
-        from src.web_interface.errors import WebInterfaceError
-        error = WebInterfaceError.from_exception(e, ErrorCode.CONFIG_SAVE_FAILED)
-        if api_v3.operation_history:
-            api_v3.operation_history.record_operation(
-                "configure",
-                plugin_id=data.get('plugin_id') if 'data' in locals() else None,
-                status="failed",
-                error=str(e)
-            )
-        return error_response(
-            error.error_code,
-            error.message,
-            details=error.details,
-            context=error.context,
-            status_code=500
-        )
 @api_v3.route('/plugins/schema', methods=['GET'])
 def get_plugin_schema():
     """Get plugin configuration schema"""
@@ -2832,6 +2891,12 @@ def execute_plugin_action():
                 'received': {'plugin_id': plugin_id, 'action_id': action_id, 'has_params': bool(action_params)}
             }), 400
 
+        # plugin_id comes from the request body and picks the directory whose
+        # manifest names the script to run, so it must be a plain name.
+        plugin_id = safe_path_component(plugin_id)
+        if plugin_id is None:
+            return jsonify({'status': 'error', 'message': 'Invalid plugin_id'}), 400
+
         # Get plugin directory
         if api_v3.plugin_manager:
             plugin_dir = api_v3.plugin_manager.get_plugin_directory(plugin_id)
@@ -3303,6 +3368,15 @@ def authenticate_ytm():
     except Exception as e:
         logger.error('Error in authenticate_ytm', exc_info=True)
         return jsonify({'status': 'error', 'message': 'An error occurred; see logs for details', 'details': describe_exception(e)}), 500
+def _plugin_uploads_dir(plugin_id):
+    """assets/plugins/<plugin_id>/uploads for a request-supplied id, or None.
+
+    Same guard as the serving route in app.py: one plain path segment,
+    resolved and contained under assets/plugins.
+    """
+    return resolve_under(PROJECT_ROOT / 'assets' / 'plugins', plugin_id, 'uploads')
+
+
 @api_v3.route('/plugins/assets/upload', methods=['POST'])
 def upload_plugin_asset():
     """Upload asset files for a plugin"""
@@ -3322,8 +3396,13 @@ def upload_plugin_asset():
         if len(files) > 10:
             return jsonify({'status': 'error', 'message': 'Maximum 10 files per upload'}), 400
 
-        # Setup plugin assets directory
+        # Setup plugin assets directory. plugin_id is a form field: without
-        assets_dir = PROJECT_ROOT / 'assets' / 'plugins' / plugin_id / 'uploads'
+        # the guard '../../config' created, listed and wrote into directories
+        # outside assets/plugins (the serving route was fixed in #561).
+        assets_dir = _plugin_uploads_dir(plugin_id)
+        if assets_dir is None:
+            return jsonify({'status': 'error', 'message': 'Invalid plugin_id'}), 400
+        plugin_id = safe_path_component(plugin_id)
         assets_dir.mkdir(parents=True, exist_ok=True)
 
         # Load metadata file
@@ -3958,7 +4037,9 @@ def delete_plugin_asset():
             return jsonify({'status': 'error', 'message': 'plugin_id and image_id are required'}), 400
 
         # Get asset directory
-        assets_dir = PROJECT_ROOT / 'assets' / 'plugins' / plugin_id / 'uploads'
+        assets_dir = _plugin_uploads_dir(plugin_id)
+        if assets_dir is None:
+            return jsonify({'status': 'error', 'message': 'Invalid plugin_id'}), 400
         metadata_file = assets_dir / '.metadata.json'
 
         if not metadata_file.exists():
@@ -3971,9 +4052,17 @@ def delete_plugin_asset():
         if image_id not in metadata:
             return jsonify({'status': 'error', 'message': 'Image not found'}), 404
 
-        # Delete file
+        # Delete file. The stored path is data, not a trusted location: only
-        file_path = PROJECT_ROOT / metadata[image_id]['path']
+        # unlink it when it resolves to a file directly inside this plugin's
-        if file_path.exists():
+        # uploads. An entry pointing anywhere else is dropped from the
+        # metadata without touching the file it names.
+        entry = metadata[image_id] if isinstance(metadata[image_id], dict) else {}
+        parts = safe_relative_parts(entry.get('path'))
+        file_path = resolve_under(PROJECT_ROOT, *parts) if parts else None
+        if file_path is None or file_path.parent != assets_dir:
+            logger.warning('Asset %s has a path outside its uploads directory; '
+                           'removing the entry without deleting a file', image_id)
+        elif file_path.exists():
             file_path.unlink()
 
         # Remove from metadata
@@ -3997,7 +4086,9 @@ def list_plugin_assets():
             return jsonify({'status': 'error', 'message': 'plugin_id is required'}), 400
 
         # Get asset directory
-        assets_dir = PROJECT_ROOT / 'assets' / 'plugins' / plugin_id / 'uploads'
+        assets_dir = _plugin_uploads_dir(plugin_id)
+        if assets_dir is None:
+            return jsonify({'status': 'error', 'message': 'Invalid plugin_id'}), 400
         metadata_file = assets_dir / '.metadata.json'
 
         if not metadata_file.exists():

web_interface/blueprints/api_v3/system.py

@@ -228,14 +228,24 @@ def _sudo_hint_for(text):
 
 _core_update_lock = threading.Lock()
 
+#: The core's own requirement files, installed after a pull that changes them.
+#: scripts/fix_perms/safe_pip_install.sh must accept every one (it refuses
+#: anything it does not list), and scripts/utils/auto_update_verify.py
+#: reinstalls the same files when it rolls an update back.
+CORE_REQUIREMENT_FILES = ('requirements.txt', 'web_interface/requirements.txt')
 
-def perform_core_update():
+
+def perform_core_update(stash_local_changes=True):
     """Pull the latest LEDMatrix code and sync its dependencies.
 
     Shared by the Overview "Update Code" button and the weekly automatic
     updater (web_interface/auto_update.py), so both take exactly the same
     path. Returns the JSON-able payload the button has always received:
     ``status``, ``message`` and ``restart_required``.
+
+    Update Code stashes local edits before pulling. The automatic updater
+    passes ``stash_local_changes=False``: then local edits make this return
+    an error carrying ``local_changes`` (the edited paths) without pulling.
     """
     # The button and the scheduler can fire together; two pulls racing
     # over one checkout (and one stash) is how local changes get lost.
@@ -243,12 +253,12 @@ def perform_core_update():
         return {'status': 'error', 'restart_required': False,
                 'message': 'An update is already in progress; try again shortly.'}
     try:
-        return _perform_core_update_locked()
+        return _perform_core_update_locked(stash_local_changes)
     finally:
         _core_update_lock.release()
 
 
-def _perform_core_update_locked():
+def _perform_core_update_locked(stash_local_changes=True):
     project_dir = str(PROJECT_ROOT)
 
     # Decide how to pull BEFORE stashing. If this checkout cannot be
@@ -259,37 +269,35 @@ def _perform_core_update_locked():
         logger.warning("git pull not attempted: %s", pull_error)
         return {'status': 'error', 'message': pull_error, 'restart_required': False}
 
-    # Check if there are local changes that need to be stashed
+    # Local changes, counted exactly as the automatic update's preflight
-    # Exclude plugins directory - plugins are separate repos and shouldn't be stashed with base project
+    # counts them (auto_update.local_changes): mode-only changes and the
-    # Use --untracked-files=no to skip untracked files check (much faster with symlinked plugins)
+    # plugin folders don't count, and the pull's --autostash carries those
+    # across and reapplies them.
+    from web_interface import auto_update
     try:
-        status_result = subprocess.run(
+        changed = auto_update.local_changes(project_dir)
-            ['git', 'status', '--porcelain', '--untracked-files=no'],
+    except (subprocess.SubprocessError, OSError) as status_err:
-            capture_output=True,
+        logger.warning("git status failed before pull: %s", status_err)
-            text=True,
+        changed = None
-            timeout=30,
+    # When git cannot say, assume there are changes rather than pull over them.
-            cwd=project_dir
+    has_changes = changed is None or bool(changed)
-        )
+
-        # Filter out any changes in plugins directory - plugins are separate repositories
+    if has_changes and not stash_local_changes:
-        # Git status format: XY filename (where X is status of index, Y is status of work tree)
+        # The automatic updater: it promised not to stash, and nothing would
-        status_lines = [line for line in status_result.stdout.strip().split('\n')
+        # ever restore a stash taken on its behalf.
-                       if line.strip() and 'plugins/' not in line]
+        return {'status': 'error', 'restart_required': False, 'dependency_failures': [],
-        has_changes = bool('\n'.join(status_lines).strip())
+                'local_changes': list(changed or []),
-    except subprocess.TimeoutExpired:
+                'message': auto_update.describe_local_changes(changed)}
-        # If status check times out, assume there might be changes and proceed
-        # This is safer than failing the update
-        has_changes = True
-        status_result = type('obj', (object,), {'stdout': '', 'stderr': 'Status check timed out'})()
 
     stash_info = ""
 
-    # Stash local changes if they exist (excluding plugins)
+    # Stash local changes if they exist. The plugin folders are left out:
-    # Plugins are separate repositories and shouldn't be stashed with base project updates
+    # plugins are separate installs, and --autostash carries their edits.
     if has_changes:
         try:
-            # Use pathspec to exclude plugins directory from stash
             stash_result = subprocess.run(
-                ['git', 'stash', 'push', '-m', 'LEDMatrix auto-stash before update', '--', ':!plugins'],
+                ['git', 'stash', 'push', '-m', 'LEDMatrix auto-stash before update', '--',
+                 *(f':!{folder}' for folder in auto_update.SEPARATE_INSTALL_DIRS)],
                 capture_output=True,
                 text=True,
                 timeout=30,
@@ -369,7 +377,7 @@ def _perform_core_update_locked():
                     ['git', 'diff', '--name-only', f'{old_head}..{new_head}'],
                     capture_output=True, text=True, timeout=15, cwd=project_dir)
                 changed = set(diff.stdout.split()) if diff.returncode == 0 else set()
-                for rel in ('requirements.txt', 'web_interface/requirements.txt'):
+                for rel in CORE_REQUIREMENT_FILES:
                     req_path = PROJECT_ROOT / rel
                     if rel not in changed or not req_path.exists():
                         continue

web_interface/static/v3/js/app-shell.js

@@ -838,8 +838,8 @@
                             // PluginAPI.batch returns already-parsed JSON objects
                             try {
                                 const results = await window.PluginAPI.batch([
-                                    {endpoint: `/plugins/config?plugin_id=${pluginId}`, method: 'GET'},
+                                    {endpoint: `/plugins/config?plugin_id=${encodeURIComponent(pluginId)}`, method: 'GET'},
-                                    {endpoint: `/plugins/schema?plugin_id=${pluginId}`, method: 'GET'},
+                                    {endpoint: `/plugins/schema?plugin_id=${encodeURIComponent(pluginId)}`, method: 'GET'},
                                     {endpoint: '/plugins/installed', method: 'GET'}
                                 ]);
                                 [configData, schemaData, pluginsData] = results;

web_interface/static/v3/js/plugins/api_client.js

@@ -123,6 +123,29 @@ const PluginAPI = {
      */
     baseURL: '/api/v3',
     
+    /**
+     * The endpoint, if it is a path under baseURL; throws INVALID_ENDPOINT
+     * otherwise. Every endpoint is one of this client's own API paths, so
+     * anything that could leave that path -- "//host", a backslash, a ".."
+     * segment, whitespace or control characters -- is a bug, not a request.
+     *
+     * @param {string} endpoint - API endpoint, starting with "/"
+     * @returns {string} The same endpoint
+     */
+    checkEndpoint(endpoint) {
+        const path = typeof endpoint === 'string' ? endpoint.split(/[?#]/)[0] : '';
+        if (!path.startsWith('/') || path.startsWith('//') ||
+                /[\\\s]/.test(endpoint) ||
+                Array.from(endpoint).some(ch => ch.charCodeAt(0) < 0x20 || ch.charCodeAt(0) === 0x7f) ||
+                path.split('/').some(segment => segment === '..' || segment === '.')) {
+            throw {
+                error_code: 'INVALID_ENDPOINT',
+                message: `Not an API endpoint: ${String(endpoint)}`
+            };
+        }
+        return endpoint;
+    },
+
     /**
      * Make an API request with throttling and caching.
      * 
@@ -141,7 +164,7 @@ const PluginAPI = {
         const requestKey = `${method}:${endpoint}:${data ? JSON.stringify(data) : ''}`;
         
         const makeRequest = async () => {
-            const url = `${this.baseURL}${endpoint}`;
+            const url = `${this.baseURL}${this.checkEndpoint(endpoint)}`;
             const options = {
                 method,
                 headers: {
@@ -153,31 +176,56 @@ const PluginAPI = {
                 options.body = JSON.stringify(data);
             }
             
+            // NETWORK_ERROR means only that fetch() itself rejected: no HTTP
+            // answer arrived (connection refused/reset, e.g. the web service
+            // restarting). Callers retry that (install_manager.js updateAll).
+            // Any HTTP response is the server's -- or a proxy's -- answer, so
+            // a 502 HTML page or a JSON error without error_code is API_ERROR
+            // and is not retried.
+            let response;
             try {
-                const response = await fetch(url, options);
+                // url is baseURL plus an endpoint checkEndpoint() accepted: a
-                const responseData = await response.json();
+                // path on this origin's API, never a caller-chosen host.
-                
+                response = await fetch(url, options); // nosemgrep
-                if (!response.ok) {
-                    // Handle structured errors
-                    if (responseData.error_code) {
-                        throw responseData;
-                    }
-                    throw new Error(responseData.message || `HTTP ${response.status}`);
-                }
-                
-                return responseData;
             } catch (error) {
-                // Re-throw structured errors
-                if (error.error_code) {
-                    throw error;
-                }
-                // Wrap network errors
                 throw {
                     error_code: 'NETWORK_ERROR',
-                    message: error.message || 'Network error',
+                    message: (error && error.message) || 'Network error',
                     original_error: error
                 };
             }
+
+            let responseData = null;
+            let parseError = null;
+            try {
+                responseData = await response.json();
+            } catch (error) {
+                parseError = error;
+            }
+
+            if (!response.ok) {
+                // Handle structured errors
+                if (responseData && responseData.error_code) {
+                    throw responseData;
+                }
+                throw {
+                    error_code: 'API_ERROR',
+                    status: response.status,
+                    message: (responseData && responseData.message) || `HTTP ${response.status}`,
+                    original_error: parseError || undefined
+                };
+            }
+
+            if (parseError) {
+                throw {
+                    error_code: 'API_ERROR',
+                    status: response.status,
+                    message: `Unreadable response from the server (HTTP ${response.status})`,
+                    original_error: parseError
+                };
+            }
+
+            return responseData;
         };
         
         // Use throttling for GET requests, immediate execution for POST/PUT/DELETE
@@ -243,7 +291,7 @@ const PluginAPI = {
      * @returns {Promise<Object>} Plugin configuration
      */
     async getPluginConfig(pluginId) {
-        const response = await this.request(`/plugins/config?plugin_id=${pluginId}`);
+        const response = await this.request(`/plugins/config?plugin_id=${encodeURIComponent(pluginId)}`);
         return response.data || {};
     },
     
@@ -268,7 +316,7 @@ const PluginAPI = {
      * @returns {Promise<Object>} Response data
      */
     async resetPluginConfig(pluginId) {
-        return await this.request(`/plugins/config/reset?plugin_id=${pluginId}`, 'POST');
+        return await this.request(`/plugins/config/reset?plugin_id=${encodeURIComponent(pluginId)}`, 'POST');
     },
     
     /**
@@ -278,7 +326,7 @@ const PluginAPI = {
      * @returns {Promise<Object>} Plugin schema
      */
     async getPluginSchema(pluginId) {
-        const response = await this.request(`/plugins/schema?plugin_id=${pluginId}`);
+        const response = await this.request(`/plugins/schema?plugin_id=${encodeURIComponent(pluginId)}`);
         return response.data?.schema || null;
     },
     
@@ -341,7 +389,7 @@ const PluginAPI = {
      */
     async getPluginHealth(pluginId = null) {
         const endpoint = pluginId
-            ? `/plugins/health/${pluginId}`
+            ? `/plugins/health/${encodeURIComponent(pluginId)}`
             : '/plugins/health';
         const response = await this.request(endpoint);
         return response.data || {};
@@ -355,7 +403,7 @@ const PluginAPI = {
      */
     async getPluginMetrics(pluginId = null) {
         const endpoint = pluginId
-            ? `/plugins/metrics/${pluginId}`
+            ? `/plugins/metrics/${encodeURIComponent(pluginId)}`
             : '/plugins/metrics';
         const response = await this.request(endpoint);
         return response.data || {};

web_interface/static/v3/js/plugins/install_manager.js

@@ -168,6 +168,58 @@ const PluginInstallManager = {
         }
 
         return results;
+    },
+
+    /**
+     * Classify one POST /plugins/update answer.
+     *
+     * The route reports what actually happened in `data.update_status`
+     * (`updated`, `up_to_date`, `local_only`). A plugin the updater had
+     * nothing to do for -- e.g. a ZIP-installed monorepo plugin already at the
+     * registry version -- is still a success response, so it must not be
+     * counted as updated. Older servers only say so in the message.
+     *
+     * @param {Object} entry - One element of updateAll()'s results
+     * @returns {string} 'failed' | 'updated' | 'up_to_date' | 'local_only'
+     */
+    updateOutcome(entry) {
+        if (!entry || !entry.success) return 'failed';
+        const result = entry.result || {};
+        const status = result.data && result.data.update_status;
+        if (status === 'up_to_date' || status === 'local_only' || status === 'updated') {
+            return status;
+        }
+        const message = typeof result.message === 'string' ? result.message : '';
+        if (message.includes('already up to date')) return 'up_to_date';
+        if (message.includes('managed locally')) return 'local_only';
+        return 'updated';
+    },
+
+    /**
+     * Summarise updateAll()'s results for the Check & Update All toast.
+     *
+     * @param {Array} results - updateAll()'s results
+     * @returns {{updated: number, upToDate: number, localOnly: number, failed: number, text: string, type: string}}
+     */
+    summarizeUpdateResults(results) {
+        const counts = { updated: 0, up_to_date: 0, local_only: 0, failed: 0 };
+        for (const entry of (Array.isArray(results) ? results : [])) {
+            counts[this.updateOutcome(entry)]++;
+        }
+        const parts = [];
+        if (counts.updated > 0) parts.push(`${counts.updated} updated`);
+        if (counts.up_to_date > 0) parts.push(`${counts.up_to_date} already up to date`);
+        if (counts.local_only > 0) parts.push(`${counts.local_only} managed locally`);
+        if (counts.failed > 0) parts.push(`${counts.failed} failed`);
+        const type = counts.failed > 0 ? (counts.updated > 0 ? 'warning' : 'error') : 'success';
+        return {
+            updated: counts.updated,
+            upToDate: counts.up_to_date,
+            localOnly: counts.local_only,
+            failed: counts.failed,
+            text: parts.join(', '),
+            type
+        };
     }
 };
 

web_interface/static/v3/plugins_manager.js

@@ -1999,22 +1999,21 @@ function runUpdateAllPlugins() {
                 showNotification('No plugins to update.', 'info');
                 return;
             }
-            let updated = 0, upToDate = 0, failed = 0;
+            // Counted by install_manager.js from each answer's update_status:
-            for (const r of results) {
+            // a no-op update is "already up to date", not "updated". A cached
-                if (!r.success) {
+            // install_manager.js from before that helper gets a plain count.
-                    failed++;
+            const manager = window.PluginInstallManager;
-                } else if (r.result && r.result.message && r.result.message.includes('already up to date')) {
+            const summary = (manager && typeof manager.summarizeUpdateResults === 'function')
-                    upToDate++;
+                ? manager.summarizeUpdateResults(results)
-                } else {
+                : (() => {
-                    updated++;
+                    const failed = results.filter(r => !r.success).length;
-                }
+                    const checked = results.length - failed;
-            }
+                    return {
-            const parts = [];
+                        text: `${checked} checked` + (failed ? `, ${failed} failed` : ''),
-            if (updated > 0) parts.push(`${updated} updated`);
+                        type: failed ? (checked ? 'warning' : 'error') : 'success'
-            if (upToDate > 0) parts.push(`${upToDate} already up to date`);
+                    };
-            if (failed > 0) parts.push(`${failed} failed`);
+                })();
-            const type = failed > 0 ? (updated > 0 ? 'warning' : 'error') : 'success';
+            showNotification(summary.text, summary.type);
-            showNotification(parts.join(', '), type);
         })
         .catch(error => {
             console.error('Error updating all plugins:', error);
@@ -3893,13 +3892,15 @@ function renderPluginStore(plugins) {
         return;
     }
 
-    // Helper function to escape for JavaScript strings
+    // JS string literal for an inline handler; see jsStringAttr
     const escapeJs = (text) => {
-        return JSON.stringify(text || '');
+        return jsStringAttr(text || '');
     };
 
     setGridHtmlIfChanged(container, plugins.map(plugin => {
         const installed = isStorePluginInstalled(plugin);
+        // Registry data: only open real web links, never javascript: URLs.
+        const repoLink = plugin.repo && /^https?:\/\//i.test(plugin.repo) ? plugin.repo : '';
         return `
         <div class="plugin-card">
             <div class="flex items-start justify-between mb-4">
@@ -3941,7 +3942,7 @@ function renderPluginStore(plugins) {
                     <button onclick='if(window.installPlugin){const branchInput = document.getElementById("branch-input-${plugin.id.replace(/[^a-zA-Z0-9]/g, '-')}"); window.installPlugin(${escapeJs(plugin.id)}, branchInput?.value?.trim() || null)}else{console.error("installPlugin not available")}' class="btn ${installed ? 'bg-gray-500 hover:bg-gray-600' : 'bg-green-600 hover:bg-green-700'} text-white px-4 py-2 rounded-md text-sm flex-1 font-semibold">
                         <i class="fas ${installed ? 'fa-redo' : 'fa-download'} mr-2"></i>${installed ? 'Reinstall' : 'Install'}
                     </button>
-                    <button onclick='${plugin.repo ? `window.open(${escapeJs(plugin.plugin_path ? plugin.repo + "/tree/" + encodeURIComponent(plugin.default_branch || plugin.branch || "main") + "/" + plugin.plugin_path.split("/").map(encodeURIComponent).join("/") : plugin.repo)}, "_blank")` : `void(0)`}' ${plugin.repo ? '' : 'disabled'} class="btn bg-gray-600 hover:bg-gray-700 text-white px-4 py-2 rounded-md text-sm flex-1 font-semibold${plugin.repo ? '' : ' opacity-50 cursor-not-allowed'}">
+                    <button onclick='${repoLink ? `window.open(${escapeJs(plugin.plugin_path ? repoLink + "/tree/" + encodeURIComponent(plugin.default_branch || plugin.branch || "main") + "/" + plugin.plugin_path.split("/").map(encodeURIComponent).join("/") : repoLink)}, "_blank")` : `void(0)`}' ${repoLink ? '' : 'disabled'} class="btn bg-gray-600 hover:bg-gray-700 text-white px-4 py-2 rounded-md text-sm flex-1 font-semibold${repoLink ? '' : ' opacity-50 cursor-not-allowed'}">
                         <i class="fas fa-external-link-alt mr-2"></i>View
                     </button>
                 </div>
@@ -4102,9 +4103,9 @@ function renderSavedRepositories(repositories) {
         return;
     }
 
-    // Helper function to escape for JavaScript strings
+    // JS string literal for an inline handler; see jsStringAttr
     const escapeJs = (text) => {
-        return JSON.stringify(text || '');
+        return jsStringAttr(text || '');
     };
 
     container.innerHTML = repositories.map(repo => {
@@ -4498,9 +4499,9 @@ function renderCustomRegistryPlugins(plugins, registryUrl) {
             .replace(/'/g, '&#39;');
     };
 
-    // Helper function to escape for JavaScript strings
+    // JS string literal for an inline handler; see jsStringAttr
     const escapeJs = (text) => {
-        return JSON.stringify(text || '');
+        return jsStringAttr(text || '');
     };
 
     container.innerHTML = plugins.map(plugin => {
@@ -4617,6 +4618,15 @@ function escapeAttribute(text) {
         .replace(/>/g, '&gt;');
 }
 
+// A quoted JS string literal that is safe inside an inline handler attribute
+// (onclick='f(${jsStringAttr(id)})' or onclick="..."). JSON.stringify alone
+// makes a valid JS string but leaves ' and & untouched, so a registry entry
+// id containing ' closed a single-quoted attribute and added its own
+// handlers. The browser decodes the entities before the JS is parsed.
+function jsStringAttr(value) {
+    return escapeAttribute(JSON.stringify(value == null ? '' : String(value)));
+}
+
 // Format date for display
 function formatDate(dateString) {
     if (!dateString) return 'Unknown';
@@ -5104,11 +5114,11 @@ window.updateImageList = function(fieldId, images) {
             const scheduleSummary = hasSchedule ? (window.getScheduleSummary ? window.getScheduleSummary(imgSchedule) : 'Scheduled') : 'Always shown';
 
             return `
-            <div id="img_${img.id || idx}" class="bg-gray-50 p-3 rounded-lg border border-gray-200">
+            <div id="img_${escapeAttribute(img.id || idx)}" class="bg-gray-50 p-3 rounded-lg border border-gray-200">
                 <div class="flex items-center justify-between mb-2">
                     <div class="flex items-center space-x-3 flex-1">
-                        <img src="/${img.path || ''}"
+                        <img src="/${escapeAttribute(String(img.path || '').replace(/^\/+/, ''))}"
-                             alt="${img.filename || ''}"
+                             alt="${escapeAttribute(img.filename || '')}"
                              loading="lazy" decoding="async"
                              class="w-16 h-16 object-cover rounded"
                              onerror="this.style.display='none'; this.nextElementSibling.style.display='block';">
@@ -5116,7 +5126,7 @@ window.updateImageList = function(fieldId, images) {
                             <i class="fas fa-image text-gray-400"></i>
                         </div>
                         <div class="flex-1 min-w-0">
-                            <p class="text-sm font-medium text-gray-900 truncate">${img.original_filename || img.filename || 'Image'}</p>
+                            <p class="text-sm font-medium text-gray-900 truncate">${escapeHtml(img.original_filename || img.filename || 'Image')}</p>
                             <p class="text-xs text-gray-500">${window.formatFileSize ? window.formatFileSize(img.size || 0) : (Math.round((img.size || 0) / 1024) + ' KB')} • ${window.formatDate ? window.formatDate(img.uploaded_at) : (img.uploaded_at || '')}</p>
                             <p class="text-xs text-blue-600 mt-1">
                                 <i class="fas fa-clock mr-1"></i>${scheduleSummary}
@@ -5125,14 +5135,14 @@ window.updateImageList = function(fieldId, images) {
                     </div>
                     <div class="flex items-center space-x-2 ml-4">
                         <button type="button"
-                                onclick="window.openImageSchedule('${fieldId}', '${img.id}', ${idx})"
+                                onclick="window.openImageSchedule(${jsStringAttr(fieldId)}, ${jsStringAttr(img.id)}, ${idx})"
                                 class="text-blue-600 hover:text-blue-800 p-2"
                                 title="Schedule this image"
                                 aria-label="Schedule image ${escapeAttribute(img.original_filename || img.filename || '')}">
                             <i class="fas fa-calendar-alt" aria-hidden="true"></i>
                         </button>
                         <button type="button"
-                                onclick="window.deleteUploadedImage('${fieldId}', '${img.id}', '${pluginId}')"
+                                onclick="window.deleteUploadedImage(${jsStringAttr(fieldId)}, ${jsStringAttr(img.id)}, ${jsStringAttr(pluginId)})"
                                 class="text-red-600 hover:text-red-800 p-2"
                                 title="Delete image"
                                 aria-label="Delete image ${escapeAttribute(img.original_filename || img.filename || '')}">
@@ -5141,7 +5151,7 @@ window.updateImageList = function(fieldId, images) {
                     </div>
                 </div>
                 <!-- Schedule widget will be inserted here when opened -->
-                <div id="schedule_${img.id || idx}" class="hidden mt-3 pt-3 border-t border-gray-300"></div>
+                <div id="schedule_${escapeAttribute(img.id || idx)}" class="hidden mt-3 pt-3 border-t border-gray-300"></div>
             </div>
             `;
         }).join('');

web_interface/templates/v3/partials/display.html

@@ -8,21 +8,26 @@
     {{ ui.settings_filter('Filter display settings…') }}
 
     <!-- Hardware status banner: shown when display service is in fallback/simulation mode -->
-    <div x-data="{ show: false, errorMsg: '' }"
+    <div x-data="{ show: false, errorMsg: '', cause: null }"
          x-init="fetch('/api/v3/hardware/status').then(r => r.json()).then(d => {
              const hw = (d && d.data) || {};
-             if (hw.ok === false) { show = true; errorMsg = hw.error || 'Unknown error'; }
+             if (hw.ok === false) { show = true; errorMsg = hw.error || 'Unknown error'; cause = hw.cause || null; }
          }).catch(() => {})"
          x-show="show"
          style="display:none"
          class="bg-yellow-50 border border-yellow-300 rounded-lg p-4 mb-6">
         <p class="font-semibold text-yellow-800"><i class="fas fa-exclamation-triangle mr-2"></i>LED matrix running in simulation mode</p>
         <p class="text-sm text-yellow-700 mt-1">Hardware initialization failed: <span x-text="errorMsg" class="font-mono text-xs break-all"></span></p>
-        <p class="text-sm text-yellow-700 mt-2">
+        <p class="text-sm text-yellow-700 mt-2" x-show="cause === 'settings'">
-            On Raspberry Pi 5: ensure the library was rebuilt from the latest submodule
+            The rgbmatrix library can't start with the settings named above, so LEDMatrix didn't try.
-            (<code class="bg-yellow-100 px-1 rounded">first_time_install.sh</code>)
+            Change them below, save, then restart the display service from the Overview tab.
-            and try adjusting <strong>GPIO Slowdown</strong> (start at 3, reduce if the display looks dim or choppy).
+        </p>
-            Check the <a href="#" @click.prevent="activeTab = 'logs'" class="underline font-medium">Logs tab</a> for the full error.
+        <p class="text-sm text-yellow-700 mt-2" x-show="cause !== 'settings'">
+            {% if is_pi5 %}If the <a href="#" @click.prevent="activeTab = 'logs'" class="underline font-medium">Logs tab</a> shows an
+            <code class="bg-yellow-100 px-1 rounded">mmap</code> error, the library was built without Raspberry Pi 5 support: rebuild it with
+            <code class="bg-yellow-100 px-1 rounded">sudo RPI_RGB_FORCE_REBUILD=1 ./first_time_install.sh</code>.
+            Otherwise the{% else %}The{% endif %}
+            <a href="#" @click.prevent="activeTab = 'logs'" class="underline font-medium">Logs tab</a> has the full error.
         </p>
     </div>
 
@@ -34,6 +39,10 @@
           class="space-y-6"
           novalidate
           onsubmit="fixInvalidNumberInputs(this); return true;">
+        {# Marks this post as the whole form, so an unchecked box saves as
+           false. Without it the save endpoint treats absent keys as unchanged
+           (FORM_SECTION_FIELD in api_v3/config.py). #}
+        <input type="hidden" name="__form_section" value="display">
 
         <!-- Hardware Settings -->
         <div class="bg-gray-50 rounded-lg p-4">
@@ -41,7 +50,7 @@
 
             <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 xl:grid-cols-4 2xl:grid-cols-4 gap-4 mb-4">
                 <div class="form-group" id="setting-display-rows" data-setting-key="display.hardware.rows">
-                    <label for="rows" class="block text-sm font-medium text-gray-700">Rows{{ ui.help_tip('Number of LED rows on a single panel.\nCommon: 16, 32, 48 or 64. Default: 32. Must match your panel and be an even number, at least 8. There is no upper limit here, but the current rgbmatrix library rejects more than 64 rows per panel, and the display will not start.', 'Rows') }}</label>
+                    <label for="rows" class="block text-sm font-medium text-gray-700">Rows{{ ui.help_tip('Number of LED rows on a single panel.\nCommon: 16, 32, 48 or 64. Default: 32. Must match your panel and be an even number from 8 to 64, the most the rgbmatrix library drives per panel.', 'Rows') }}</label>
                     <input type="number"
                            id="rows"
                            name="rows"
@@ -62,7 +71,7 @@
                 </div>
 
                 <div class="form-group" id="setting-display-chain_length" data-setting-key="display.hardware.chain_length">
-                    <label for="chain_length" class="block text-sm font-medium text-gray-700">Chain Length{{ ui.help_tip('How many panels are wired end-to-end in one chain.\nDefault: 2. Example: two 64×32 panels chained make a 128×32 display. No upper limit, but longer chains lower the refresh rate.', 'Chain Length') }}</label>
+                    <label for="chain_length" class="block text-sm font-medium text-gray-700">Chain Length{{ ui.help_tip('How many panels are wired end-to-end in one chain.\nDefault: 2. Example: two 64×32 panels chained make a 128×32 display. 1 to 255; longer chains lower the refresh rate.', 'Chain Length') }}</label>
                     <input type="number"
                            id="chain_length"
                            name="chain_length"
@@ -72,7 +81,7 @@
                 </div>
 
                 <div class="form-group" id="setting-display-parallel" data-setting-key="display.hardware.parallel">
-                    <label for="parallel" class="block text-sm font-medium text-gray-700">Parallel{{ ui.help_tip('Number of separate chains driven in parallel from the HAT.\nDefault: 1. The Raspberry Pi supports up to 3, and the HAT needs that many outputs (e.g. the Adafruit Triple LED Matrix Bonnet).', 'Parallel') }}</label>
+                    <label for="parallel" class="block text-sm font-medium text-gray-700">Parallel{{ ui.help_tip('Number of separate chains driven in parallel from the HAT.\nDefault: 1. Up to 3, and the hardware mapping needs that many outputs: Regular and Classic have 3 (e.g. the Adafruit Triple LED Matrix Bonnet); Adafruit HAT, Adafruit HAT PWM and the Pi1 mappings have 1.', 'Parallel') }}</label>
                     <input type="number"
                            id="parallel"
                            name="parallel"
@@ -107,19 +116,33 @@
 
                 <div class="form-group" id="setting-display-hardware_mapping" data-setting-key="display.hardware.hardware_mapping">
                     <label for="hardware_mapping" class="block text-sm font-medium text-gray-700">Hardware Mapping{{ ui.help_tip('How the LED panel is wired to the Pi.\nUse "Adafruit HAT PWM" for an Adafruit RGB Matrix HAT/Bonnet with the PWM solder mod; "Adafruit HAT" without it (no hardware pulsing, so expect a little more flicker); "Regular" for direct GPIO wiring and for the Adafruit Triple LED Matrix Bonnet.', 'Hardware Mapping') }}</label>
+                    {#- Saving posts what is selected, so a stored value must render selected
+                        even when it isn't one of the usual choices. The library matches
+                        names case-insensitively and reads an empty name as "regular". -#}
+                    {% set stored_mapping = main_config.display.hardware.get('hardware_mapping', 'adafruit-hat-pwm') %}
+                    {% set mapping_key = (stored_mapping or 'regular')|lower if stored_mapping is string else stored_mapping|string %}
+                    {% set mapping_labels = {'adafruit-hat-pwm': 'Adafruit HAT PWM', 'adafruit-hat': 'Adafruit HAT', 'regular': 'Regular', 'regular-pi1': 'Regular Pi1', 'classic': 'Classic (legacy wiring)', 'classic-pi1': 'Classic Pi1 (legacy wiring)'} %}
+                    {% set mapping_values = ['adafruit-hat-pwm', 'adafruit-hat', 'regular', 'regular-pi1', 'classic'] if is_pi5 else ['adafruit-hat-pwm', 'adafruit-hat', 'regular', 'regular-pi1', 'classic', 'classic-pi1'] %}
                     <select id="hardware_mapping" name="hardware_mapping" class="form-control">
-                        <option value="adafruit-hat-pwm" {% if main_config.display.hardware.hardware_mapping == "adafruit-hat-pwm" %}selected{% endif %}>Adafruit HAT PWM</option>
+                        {% for value in mapping_values %}
-                        <option value="adafruit-hat" {% if main_config.display.hardware.hardware_mapping == "adafruit-hat" %}selected{% endif %}>Adafruit HAT</option>
+                        <option value="{{ value }}" {% if mapping_key == value %}selected{% endif %}>{{ mapping_labels[value] }}</option>
-                        <option value="regular" {% if main_config.display.hardware.hardware_mapping == "regular" %}selected{% endif %}>Regular</option>
+                        {% endfor %}
-                        <option value="regular-pi1" {% if main_config.display.hardware.hardware_mapping == "regular-pi1" %}selected{% endif %}>Regular Pi1</option>
+                        {% if mapping_key not in mapping_values %}
+                        <option value="{{ stored_mapping }}" selected>{{ stored_mapping }} (saved, can't be used)</option>
+                        {% endif %}
                     </select>
+                    {% if mapping_key not in mapping_values %}
+                    <p class="text-sm text-red-600 mt-1">Your saved hardware mapping ("{{ stored_mapping }}") isn't one the installed rgbmatrix library {% if is_pi5 and mapping_key in mapping_labels %}can use on a Raspberry Pi 5{% else %}has{% endif %}, so the display won't start with it. Choose your board's mapping before saving.</p>
+                    {% endif %}
                 </div>
 
                 <div class="form-group" id="setting-display-orientation" data-setting-key="display.hardware.orientation">
-                    <label for="orientation" class="block text-sm font-medium text-gray-700">Panel Orientation{{ ui.help_tip('Rotates the rendered image to match how the panel is physically mounted.\nUse "Upside Down" if you flipped the panel 180° to move the Raspberry Pi / wiring to a more convenient side.', 'Panel Orientation') }}</label>
+                    <label for="orientation" class="block text-sm font-medium text-gray-700">Panel Orientation{{ ui.help_tip('Rotates the rendered image to match how the panel is physically mounted.\nUse "Upside Down" if you flipped the panel 180° to move the Raspberry Pi / wiring to a more convenient side. 90° and 270° are for a panel mounted on its side, and swap the display width and height.', 'Panel Orientation') }}</label>
                     <select id="orientation" name="orientation" class="form-control">
                         <option value="normal" {% if main_config.display.hardware.get('orientation', 'normal') == "normal" %}selected{% endif %}>Normal</option>
+                        <option value="90" {% if main_config.display.hardware.get('orientation', 'normal') == "90" %}selected{% endif %}>Rotated 90°</option>
                         <option value="180" {% if main_config.display.hardware.get('orientation', 'normal') == "180" %}selected{% endif %}>Upside Down (180°)</option>
+                        <option value="270" {% if main_config.display.hardware.get('orientation', 'normal') == "270" %}selected{% endif %}>Rotated 270°</option>
                     </select>
                 </div>
 
@@ -218,7 +241,7 @@
 
             <div class="grid grid-cols-1 md:grid-cols-3 gap-4">
                 <div class="form-group" id="setting-display-gpio_slowdown" data-setting-key="display.runtime.gpio_slowdown">
-                    <label for="gpio_slowdown" class="block text-sm font-medium text-gray-700">GPIO Slowdown{{ ui.help_tip('Slows GPIO writes so the panel electronics keep up (0–10); higher is more reliable but lowers the refresh rate.\nStarting points: Pi Zero / Pi 1 → 0–1, Pi 2 / Pi 3 → 1–3, Pi 4 → 2–4, Pi 5 (PIO) → 1–3. Panels on Row Address Type 5 (SM5368 row drivers) can need 6–8 on a Pi 4. Raise it if the display shows garbage, jumping rows or flicker; in RIO mode higher values may improve performance.', 'GPIO Slowdown') }}</label>
+                    <label for="gpio_slowdown" class="block text-sm font-medium text-gray-700">GPIO Slowdown{{ ui.help_tip('Slows GPIO writes so the panel electronics keep up (0–10); higher is more reliable but lowers the refresh rate.\nStarting points: Pi Zero / Pi 1 → 0–1, Pi 2 / Pi 3 → 1–3, Pi 4 → 2–4, Pi 5 (PIO) → 1–3, starting at 1 (0 acts as 1 there). Panels on Row Address Type 5 (SM5368 row drivers) can need 6–8 on a Pi 4. Raise it if the display shows garbage, jumping rows or flicker; in RIO mode higher values may improve performance.', 'GPIO Slowdown') }}</label>
                     <input type="number"
                            id="gpio_slowdown"
                            name="gpio_slowdown"
@@ -374,7 +397,9 @@
 
             <script>
                 // Live "Your display: W x H" readout - width = cols x chain_length,
-                // height = rows x parallel (same math as the chain-length tooltip).
+                // height = rows x parallel (same math as the chain-length tooltip),
+                // swapped for a 90/270 orientation. A custom pixel mapper config can
+                // change it further; src/display_geometry.py models those.
                 (function () {
                     const ids = ['rows', 'cols', 'chain_length', 'parallel'];
                     const out = document.getElementById('display-resolution-value');
@@ -389,12 +414,19 @@
                             out.textContent = '—';
                             return;
                         }
-                        out.textContent = (v.cols * v.chain_length) + ' × ' + (v.rows * v.parallel) + ' pixels';
+                        let w = v.cols * v.chain_length, h = v.rows * v.parallel;
+                        const orientation = document.getElementById('orientation');
+                        if (orientation && (orientation.value === '90' || orientation.value === '270')) {
+                            [w, h] = [h, w];
+                        }
+                        out.textContent = w + ' × ' + h + ' pixels';
                     }
                     for (const id of ids) {
                         const el = document.getElementById(id);
                         if (el) el.addEventListener('input', recompute);
                     }
+                    const orientationSelect = document.getElementById('orientation');
+                    if (orientationSelect) orientationSelect.addEventListener('change', recompute);
                     recompute();
                 })();
             </script>

web_interface/templates/v3/partials/durations.html

@@ -15,6 +15,8 @@
           class="space-y-6"
           novalidate
           onsubmit="fixInvalidNumberInputs(this); return true;">
+        {# See general.html: identifies a whole-form post to /config/main. #}
+        <input type="hidden" name="__form_section" value="durations">
 
         <!-- Primary rotation order: drag to reorder which plugin shows first,
              second, ... in the normal display rotation. Saved as