Address review findings on target_fps validation and config resolution

- Reject floats and bools before int() in the target_fps save path. A JSON
  body can carry them, where int(90.5) silently stored 90 and true stored 1.
  Form posts send strings, so '90.5' already failed in int().
- Assert the template's target_fps is 100, not merely an int, so the
  documented default is actually pinned.
- Empty-config precedence: keeping the `and config` check deliberately, now
  spelled out in the comment and covered by a test. Both managers default to
  the same config/config.json, so falling through cannot pick up a different
  file's settings; treating {} as an answer would instead return {} when the
  first manager simply hasn't loaded yet, silently disabling every setting
  read through the property -- the failure this property exists to fix.

Suite 1446 passed. The float-rejection test was checked to fail without the
guard.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KEZK1P1Q1fu5pcuVrkrCFZ

.gitignore

@@ -48,3 +48,4 @@ config/backups/
 
 # Starlark apps runtime storage (installed .star files and cached renders)
 /starlark-apps/
+skin_renders/

CLAUDE.md

@@ -31,6 +31,14 @@
 - Plugin configs stored in `config/config.json`, NOT in plugin directories — safe across reinstalls
 - Third-party plugins can use their own repo URL with empty `plugin_path`
 
+## Skin System (visual overlays for sports scoreboards)
+- Skins live in `skins/<skin-id>/` (skin.json + skin.py), NOT in plugin dirs — plugin reinstall deletes plugin dirs
+- Core: `src/skin_system/` (ScoreboardSkin, SkinContext, runtime); hook: `SportsCore._render_game()` in `src/base_classes/sports.py`
+- Skins render onto `ctx.canvas` only; fallback to built-in renderer on `False`/exception (3 strikes disables for session)
+- View-model guaranteed keys are frozen (see `test/test_skin_system.py::TestViewModelContract`) — renaming keys in `_extract_game_details_common` or sport extractors breaks published skins
+- Validate skins headlessly: `python scripts/validate_skin.py --skin <id>`; docs: `docs/SKIN_SYSTEM.md`, `docs/CREATING_SKINS.md`
+- Skins are NOT monorepo plugins: no manifest bump / update_registry.py needed
+
 ## Common Pitfalls
 - paho-mqtt 2.x needs `callback_api_version=mqtt.CallbackAPIVersion.VERSION1` for v1 compat
 - BasePlugin uses `get_logger()` from `src.logging_config`, not standard `logging.getLogger()`

README.md

@@ -440,6 +440,16 @@ See the [Plugin Store documentation](https://github.com/ChuckBuilds/ledmatrix-pl
 
 For plugin development, check out the [Hello World Plugin](https://github.com/ChuckBuilds/ledmatrix-hello-world) repository as a starter template.
 
+### Visual Skins for Scoreboards
+
+Want a different look for a sports scoreboard without forking the plugin?
+**Skins** restyle the live/recent/upcoming screens while the plugin keeps
+handling data, scheduling, caching, and vegas mode. Install one with
+`git clone <skin repo> skins/<skin-id>`, select it in the plugin's config,
+and you're done — see [docs/SKIN_SYSTEM.md](docs/SKIN_SYSTEM.md) (how it
+works) and [docs/CREATING_SKINS.md](docs/CREATING_SKINS.md) (build your own,
+including a ready-made Claude Code prompt).
+
 2. **Built-in Managers Deprecated**: The built-in managers (hockey, football, stocks, etc.) are now deprecated and have been moved to the plugin system. **You must install replacement plugins from the Plugin Store** in the web interface instead. The plugin system provides the same functionality with better maintainability and extensibility.
 </details>
 

config/config.template.json

@@ -88,6 +88,7 @@
         }
     },
     "timezone": "America/New_York",
+    "target_fps": 100,
     "location": {
         "city": "Tampa",
         "state": "Florida",
@@ -121,6 +122,7 @@
             "axis": "horizontal"
         },
         "display_durations": {},
+        "plugin_rotation_order": [],
         "use_short_date_format": true,
         "vegas_scroll": {
             "enabled": false,
@@ -129,7 +131,25 @@
             "plugin_order": [],
             "excluded_plugins": [],
             "target_fps": 125,
-            "buffer_ahead": 2
+            "buffer_ahead": 2,
+            "intra_plugin_gap": 8,
+            "render_width_pct": 100,
+            "min_content_separation": 24,
+            "min_cut_gap": 6,
+            "continuous_scroll": true,
+            "smooth_scroll": true,
+            "extend_threshold_screens": 2.0,
+            "auto_trim": true,
+            "trim_threshold": 10,
+            "content_padding": 8,
+            "min_plugin_width": 8,
+            "lead_in_width": 0,
+            "plugins_per_cycle": 6,
+            "max_plugin_width_ratio": 3.0,
+            "overflow_mode": "rotate",
+            "dynamic_duration_enabled": true,
+            "min_cycle_duration": 60,
+            "max_cycle_duration": 240
         }
     },
     "sync": {

docs/CREATING_SKINS.md

@@ -0,0 +1,242 @@
+# Creating Skins
+
+A skin restyles a sports scoreboard (live / recent / upcoming) without
+forking the plugin: the plugin keeps fetching data, scheduling, caching, and
+doing vegas mode; your skin only draws. Architecture background:
+[SKIN_SYSTEM.md](SKIN_SYSTEM.md).
+
+## Quick start
+
+```bash
+cp -r skins/example-classic-baseball skins/my-skin
+# edit skins/my-skin/skin.json  -> set id ("my-skin"), name, author, class_name
+# edit skins/my-skin/skin.py    -> rename the class, start restyling
+python scripts/validate_skin.py --skin my-skin
+```
+
+The validator renders your skin against bundled fixture games at several
+panel sizes with **no hardware, no network, no running service**, saves PNGs
+(plus 4x previews) to `skin_renders/`, and fails loudly on errors. Iterate:
+edit → validate → look at the PNGs.
+
+To see it on your matrix, add to your plugin's section in `config/config.json`:
+
+```json
+"baseball-scoreboard": {
+  "skin": "my-skin",
+  "skin_options": { }
+}
+```
+
+or pick it from the **Visual Skin** dropdown in the web UI (it appears once a
+matching skin is installed). `"skin"` also accepts a per-mode mapping:
+`{"live": "my-skin", "recent": "built-in"}`.
+
+## The manifest (`skin.json`)
+
+```json
+{
+  "id": "my-skin",
+  "name": "My Skin",
+  "version": "1.0.0",
+  "author": "you",
+  "description": "What it looks like",
+  "skin_api_version": "1.0.0",
+  "targets": {
+    "sports": ["baseball"],
+    "sport_keys": ["mlb", "milb"],
+    "plugins": []
+  },
+  "entry_point": "skin.py",
+  "class_name": "MySkin",
+  "modes": ["live", "recent", "upcoming"],
+  "preview": "preview.png"
+}
+```
+
+Field notes: `id` must equal the directory name; `skin_api_version`'s major
+version must match the host's `SKIN_API_VERSION` or the skin is refused at
+load; `targets` takes sport families (`sports`), exact sport keys
+(`sport_keys`), and/or exact plugin ids (`plugins`) — any match applies.
+
+## The renderer (`skin.py`)
+
+```python
+from src.skin_system.skin_base import ScoreboardSkin, SkinContext
+
+class MySkin(ScoreboardSkin):
+    def render_live(self, ctx: SkinContext, game: dict) -> bool:
+        score = f"{game.get('away_score', '0')}-{game.get('home_score', '0')}"
+        fit = ctx.layout.fit_text(score, ctx.layout.bounds)
+        ctx.draw_fit(fit, ctx.layout.bounds)
+        return True   # True = "I drew it"; False = use the built-in layout
+```
+
+Implement only the modes you care about — anything else falls back to the
+plugin's built-in rendering. Return `False` to decline a specific game (e.g.
+a layout that only makes sense while a game is live).
+
+### The rules (they keep your skin from breaking the display)
+
+1. **Draw only onto `ctx.canvas`** (via the helpers or `ctx.draw`). Never
+   reassign `ctx.canvas`, never touch the display or call any update method.
+2. **No I/O in render paths.** No network, no file loads per frame —
+   `render_live` runs every display pass, and a slow render stalls the whole
+   matrix (the host warns at >150 ms). Use `ctx.load_logo` (cached) and
+   `cache_key=` for images.
+3. **Derive everything from `(ctx, game)`.** Skins must be stateless: the
+   live/recent/upcoming modes each get their own instance.
+4. **Always `.get()` optional keys.** Only the guaranteed keys below are
+   promised to exist.
+5. **Never hardcode pixel positions for the panel.** Use `ctx.width`/
+   `ctx.height`, `ctx.layout` regions and `fit_text` — your skin will be run
+   at sizes you didn't test (64x32, 128x64, vegas cards).
+6. **No third-party dependencies.** Stdlib + PIL + what `ctx` provides.
+
+A skin that raises 3 renders in a row is disabled until the service restarts
+(the built-in layout takes over), so a bug is cosmetic — but check your logs.
+
+## SkinContext reference
+
+| Member | What it is |
+|---|---|
+| `ctx.canvas` / `ctx.draw` | Fresh RGB `PIL.Image` at display size + its `ImageDraw` (raw-PIL escape hatch) |
+| `ctx.width`, `ctx.height` | Canvas size — the only size truth |
+| `ctx.layout` | `LayoutContext` (see [ADAPTIVE_LAYOUT.md](ADAPTIVE_LAYOUT.md)): `bounds`, `fit_text`, `fit_text_proportional`, `fit_image`, `px`, `by_tier` |
+| `ctx.draw_fit(fit, box, color, align, valign)` | Draw a `fit_text` result aligned in a `Region` (handles BDF fonts) |
+| `ctx.draw_text(text, x, y, color, font)` | Positioned text (handles BDF fonts) |
+| `ctx.draw_image(img, box, mode, align, valign, cache_key)` | Fit + paste an image with alpha; no-ops on `None` |
+| `ctx.load_logo("home" \| "away")` | Team logo as RGBA, or `None` (always handle `None`). Cached after first use; see note below |
+| `ctx.draw_text_outlined(text, (x, y), font, fill, outline_color)` | The classic scorebug outlined text (TTF fonts only) |
+| `ctx.fonts` | The host's font dict — keys `score`, `time`, `team`, `status`, `detail`, `rank` |
+| `ctx.options` | Your user's `skin_options` from config |
+| `ctx.sport`, `ctx.view_model_version`, `ctx.logger` | Context metadata + logger |
+
+**A note on `ctx.load_logo` vs the no-I/O rule:** `load_logo` is the one
+sanctioned exception. It goes through the host's logo cache — after the
+first call per team it's a pure in-memory lookup. If a logo file is missing
+on disk, the *first* call may download it, exactly like the built-in
+renderer does for the same game (a skin is never worse than built-in here).
+Always pass a stable `cache_key` when drawing it, never load image files
+yourself in a render path, and always handle `None`.
+
+The default layout idiom — carve regions, then fit text into them:
+
+```python
+from src.adaptive_layout import scoreboard_regions
+
+regions = scoreboard_regions(ctx.layout.bounds, ctx=ctx.layout)
+ctx.draw_image(ctx.load_logo("away"), regions.away_slot, cache_key=f"logo:{game.get('away_abbr')}")
+ctx.draw_image(ctx.load_logo("home"), regions.home_slot, cache_key=f"logo:{game.get('home_abbr')}")
+fit = ctx.layout.fit_text("3-5", regions.score_area)
+ctx.draw_fit(fit, regions.score_area)
+```
+
+`Region` supports `split_h`/`split_v`/`inset`/`top_band`/`bottom_band`/
+`left_col`/`right_col` for custom carves. Raw `ctx.draw.rectangle/polygon/
+ellipse/...` is always available for custom marks (see the bases diamond in
+the example skin).
+
+## The game view model
+
+Guaranteed for every sport (view model v1.0 — renaming these breaks skins and
+is treated as a breaking change upstream):
+
+| Key | Notes |
+|---|---|
+| `id` | Event id (string) |
+| `status_text` | Display-ready status, e.g. `"Final"`, `"7:30 PM"`, `"Bot 7th"` |
+| `is_live`, `is_final`, `is_upcoming`, `is_halftime` | Booleans |
+| `game_date`, `game_time` | Pre-formatted local date/time strings |
+| `start_time_utc` | UTC `datetime` |
+| `home_abbr`, `away_abbr` | Team abbreviations (can be 2–5 chars — fit, don't assume) |
+| `home_id`, `away_id` | Team ids |
+| `home_score`, `away_score` | **Strings**, not ints |
+| `home_record`, `away_record` | `"58-33"` or `""` (0-0 records are blanked) |
+| `home_logo_path`, `away_logo_path` | Prefer `ctx.load_logo` over touching these |
+
+Sport extras (present for that sport, still `.get()` defensively):
+
+- **baseball**: `inning` (int), `inning_half` (`"top"`/`"bottom"`), `balls`,
+  `strikes`, `outs` (ints), `bases_occupied` (`[first, second, third]`
+  booleans), `series_summary` (str)
+- **football**: `period`, `period_text`, `clock`, `home_timeouts`,
+  `away_timeouts`, `down_distance_text`, `down_distance_text_long`,
+  `is_redzone`, `possession`, `possession_indicator` (`"home"`/`"away"`),
+  `scoring_event`
+- **basketball**: `period`, `period_text`, `clock`
+- **hockey**: `period`, `period_text`, `clock`, `power_play`, `penalties`,
+  `home_shots`, `away_shots`
+
+Optional everywhere (only when the user enabled the feature): `odds` (dict),
+`series_summary`, rankings-related fields.
+
+Fixture copies of these dicts live in `src/skin_system/fixtures/` — that's
+exactly what the validator feeds your skin.
+
+## Vegas mode
+
+You get vegas support for free: vegas captures the normal display output,
+which is already your skin's rendering. Optionally implement
+`render_vegas_card(ctx, game)` to return a purpose-built card at
+`ctx.width x ctx.height` (sizes vary — never assume 128x32).
+
+## Building a skin with Claude Code
+
+Skins are ideal Claude Code projects: small, isolated, and verifiable with
+one command. Paste this to start:
+
+> You are building a **display skin** for LEDMatrix — a visual overlay for a
+> sports scoreboard on a small LED matrix (commonly 128x32 or 64x32 pixels).
+> First read `docs/CREATING_SKINS.md` and the reference skin in
+> `skins/example-classic-baseball/`.
+>
+> Rules:
+> - Create/modify files ONLY under `skins/<my-skin-id>/`. Do NOT modify
+>   anything in `src/`, `scripts/`, the plugins, or any other skin.
+> - Render only from the `game` dict and `ctx` helpers. No network calls, no
+>   per-frame file I/O, no new pip dependencies, no touching the display —
+>   draw onto `ctx.canvas` and return True.
+> - Use `ctx.layout` regions and `fit_text` for positioning so the skin works
+>   at any panel size; use `.get()` for every optional game key.
+> - After every change run
+>   `python scripts/validate_skin.py --skin <my-skin-id>` and LOOK at the
+>   PNGs it writes to `skin_renders/` (the `_x4.png` files are easiest to
+>   read). Iterate until it passes and looks right at both 128x32 and 64x32.
+>
+> What I want it to look like: <describe your layout — where logos, score,
+> status go; colors; what shows during live vs upcoming vs final>
+
+Tips that keep Claude (and you) out of trouble:
+
+- One mode at a time: get `render_live` right before touching the others —
+  unimplemented modes automatically use the built-in look.
+- Ask for edge-case renders: long team abbreviations, missing logos
+  (`ctx.load_logo` returning `None`), 0-0 records, extra innings/OT.
+- If the render looks cramped at 64x32, ask Claude to use
+  `ctx.layout.by_tier(...)` to drop elements on small panels rather than
+  shrinking everything.
+- Never let it "fix" a problem by editing `src/` — if the skin can't do
+  something within its directory, that's a feature request, not a workaround.
+
+## Pre-publish checklist
+
+- [ ] `python scripts/validate_skin.py --skin <id> --size 128x32 --size 64x32 --size 128x64` passes
+- [ ] Looked at every PNG in `skin_renders/` — nothing clipped or overlapping
+- [ ] Handles a missing logo (`None`) without crashing — temporarily point a
+      fixture's logo path at a nonexistent file to test
+- [ ] Long abbreviations (`"TA&M"`, 4–5 chars) don't overflow
+- [ ] No render warning above the time budget
+- [ ] `skin.json`: `id` matches the directory, `version` set,
+      `skin_api_version` matches the host, targets correct
+- [ ] `preview.png` added (grab your favorite `_x4` render)
+- [ ] Tested on real hardware if you have it — a Pi is much slower than your
+      dev machine
+
+Distribute by publishing the directory as a git repo (users
+`git clone <repo> skins/<id>`), or submit it to the plugin registry as an
+entry with `"type": "skin"` (see [SKIN_SYSTEM.md](SKIN_SYSTEM.md) §Distribution).
+
+**Trust note:** a skin is Python running inside the display service — the
+same trust level as a plugin. Review code before installing skins from
+others.

docs/PLUGIN_DEVELOPMENT_GUIDE.md

@@ -10,6 +10,12 @@ This guide explains how to set up a development workflow for plugins that are ma
 > scale. Existing plugins keep their classic rendering unless they adopt
 > those APIs; nothing migrates automatically.
 
+> **Just want a different look for an existing sports scoreboard?** You may
+> not need a plugin at all — a **skin** restyles the live/recent/upcoming
+> rendering while the plugin keeps handling data, scheduling, caching, and
+> vegas mode, in ~100 lines of drawing code. See
+> [CREATING_SKINS.md](CREATING_SKINS.md).
+
 ## Overview
 
 When developing plugins in separate repositories, you need a way to:

docs/SKIN_SYSTEM.md

@@ -0,0 +1,170 @@
+# Skin System Architecture
+
+Skins are user-installable **visual overlays** for the sports scoreboards.
+A skin replaces only the *look* of a scoreboard — the host plugin keeps doing
+data fetching, scheduling, caching, dedup, live-priority takeover, and vegas
+mode. If you only want to **build** a skin, read
+[CREATING_SKINS.md](CREATING_SKINS.md); this document explains how the system
+works and why it is shaped this way.
+
+## Why skins instead of forks
+
+Before skins, changing a scoreboard's layout meant forking the whole plugin
+(e.g. the community MLB scoreboard fork). The fork gets the new look but loses
+everything the maintained plugin keeps earning: duration/scheduling behavior,
+vegas mode support, caching and background-fetch improvements, bug fixes. It
+also silently drifts: every upstream improvement now has to be re-ported by
+hand.
+
+A skin inverts that trade. The plugin remains stock and keeps updating through
+the store; the skin is ~100 lines of pure rendering code that receives the
+plugin's already-fetched data each frame. Uninstalling the skin (or the skin
+crashing) simply restores the built-in look.
+
+```text
+              (unchanged)                        (the skin seam)
+ ESPN API ──► update() ──► game view model ──► _render_game() ──► display
+              fetching        (a dict)          │         │
+              caching                           │         └─ built-in
+              scheduling                        └─ skin.render_<mode>(ctx, game)
+              live priority                        draws onto ctx.canvas
+```
+
+## The render funnel
+
+Every sports scoreboard (baseball, football, basketball, hockey — anything
+built on `src/base_classes/sports.py`) renders through exactly one seam:
+`SportsCore._render_game(game, force_clear)`.
+
+1. The mode class's `display()` (live, `SportsUpcoming`, `SportsRecent`)
+   picks `self.current_game` and calls `_render_game`.
+2. `_render_game` lazily loads the configured skin (once, on first render —
+   a broken skin can never block plugin startup).
+3. If a skin is active, the host builds a `SkinContext` — a fresh black
+   canvas at the current display size plus layout/font/logo helpers — and
+   calls the skin's `render_live` / `render_recent` / `render_upcoming`
+   with a **copy** of the game dict.
+4. If the skin returns `True`, the canvas is composited onto the display.
+   If it returns `False`, isn't implemented for that mode, or raises, the
+   built-in `_draw_scorebug_layout` runs instead.
+
+Key properties that fall out of this design:
+
+- **Per-mode fallback.** A skin that only implements `render_live` gets the
+  stock recent/upcoming screens for free.
+- **Three strikes.** A skin that raises 3 times in a row is disabled for the
+  rest of the session (one loud error log per failure); the display never
+  goes dark. Restarting the service re-arms it.
+- **Copies, not references.** Skins receive a shallow copy of the game dict,
+  so a buggy skin cannot corrupt the plugin's scheduling state.
+- **Vegas mode works untouched.** Vegas capture falls back to grabbing the
+  regular `display()` output, which is already skin-rendered. Skins can
+  additionally implement `render_vegas_card` for purpose-built scroll cards,
+  and hosts can call `SportsCore.render_skin_card(game, size)` to use it.
+- **Hot-loop caution.** `render_live` runs every display-loop pass during a
+  live game. The host logs a warning when a skin render exceeds 150 ms, and
+  `scripts/validate_skin.py` enforces a budget at development time — but
+  Python cannot forcibly time-out a stuck render, so a skin that blocks
+  (network I/O, giant image ops) stalls the display. This is why the rules
+  in CREATING_SKINS.md ban I/O in render paths.
+
+## The view model contract
+
+The `game` dict a skin receives is the plugin's already-extracted view model
+(`SportsCore._extract_game_details_common` plus per-sport extras from
+`src/base_classes/{baseball,basketball,football,hockey}.py`).
+
+- **Guaranteed keys (view model v1.0)** — always present for every sport:
+  `id`, `game_time`, `game_date`, `start_time_utc` (a UTC `datetime`),
+  `status_text`, `is_live`, `is_final`, `is_upcoming`, `is_halftime`,
+  `home_abbr`/`away_abbr`, `home_id`/`away_id`, `home_score`/`away_score`
+  (**strings**), `home_logo_path`/`away_logo_path`, `home_record`/`away_record`.
+- **Sport extras** — documented per sport in CREATING_SKINS.md (e.g. baseball
+  adds `inning`, `inning_half`, `balls`, `strikes`, `outs`, `bases_occupied`).
+- **Optional keys** (`odds`, rankings, `series_summary`, …) are present only
+  when the feature is enabled — skins must always use `.get()`.
+
+Versioning policy: additive changes bump the minor version
+(`VIEW_MODEL_VERSION` in `src/skin_system/skin_base.py`, surfaced to skins as
+`ctx.view_model_version`); renaming or removing a guaranteed key requires a
+major bump plus a compat shim. `test/test_skin_system.py::TestViewModelContract`
+fails CI if a guaranteed key disappears from the extractor.
+
+Separately, `SKIN_API_VERSION` versions the Python API (`ScoreboardSkin`,
+`SkinContext`). The loader refuses a skin whose manifest declares a different
+major version and falls back to the built-in renderer with a clear
+"skin needs an update" log line.
+
+## Package layout and lifecycle
+
+```text
+skins/<skin-id>/
+  skin.json      # manifest (required)
+  skin.py        # ScoreboardSkin subclass (required)
+  preview.png    # optional, shown by the web UI
+  assets/        # optional skin-local images
+  helpers.py ... # optional extra modules (namespaced per skin at import)
+```
+
+Skins live in the central `skins/` directory — deliberately **not** inside the
+plugin's directory, because plugin reinstall/update deletes the whole plugin
+directory and a skin must survive that. One skin can also target several
+plugins (mlb + milb).
+
+Lifecycle: discovered lazily on first render → manifest validated → API major
+version gated → module imported under a namespaced `sys.modules` key (two
+skins can both ship a `helpers.py`, same scheme plugins use) → instantiated
+with `(manifest, options)`. Every failure logs and falls back to built-in.
+
+Skins should be **stateless**: the live, recent, and upcoming mode classes
+each hold their own skin instance, so derive everything from `(ctx, game)`.
+
+## Selection and configuration
+
+Inside the plugin's own config section in `config/config.json`:
+
+```json
+"baseball-scoreboard": {
+  "skin": "retro-baseball",
+  "skin_options": { "accent_color": [255, 80, 0] }
+}
+```
+
+`"skin"` is either one id for all modes or a per-mode mapping
+(`{"live": "retro-baseball", "recent": "built-in"}`). Absent, empty, or
+`"built-in"` means the stock renderer. Because this rides the plugin's config
+section, it persists across plugin reinstalls like every other setting.
+
+The web UI shows a **Visual Skin** dropdown for plugins that have matching
+skins installed: `SchemaManager.inject_skin_selector` adds an enum to the
+*served* schema only. Validation never sees the enum — so a config that
+references an uninstalled skin stays valid (rendering just falls back), and
+the currently-configured value is always kept selectable. `GET /api/v3/skins`
+lists installed skins (optionally filtered by `?plugin_id=`).
+
+## Distribution
+
+- **Manual:** `git clone <skin repo> skins/<skin-id>` — that's the whole
+  install. No manifest bumps, no `update_registry.py`; skins are not monorepo
+  plugins.
+- **Store:** registry entries with `"type": "skin"` install through the same
+  `plugins.json` pipeline; `PluginStoreManager` routes them to `skins/`,
+  validates `skin.json` (including the API major version) instead of
+  `manifest.json`, and never installs dependencies — skins are render-only
+  (stdlib + PIL + the provided context, no third-party packages in v1).
+
+## Trust model
+
+A skin is Python executing inside the display service — **exactly the same
+trust level as a plugin**, even though "skin" sounds cosmetic. Only install
+skins from sources you'd be willing to install a plugin from.
+
+## v2 directions (not in v1)
+
+- A generic `BasePlugin` opt-in (`render_with_skin()`) so non-sports plugins
+  (weather, music) can offer skinnable layouts; `skin_runtime` is already
+  sports-agnostic in anticipation.
+- Store UI: preview gallery, one-click install from the skin browser.
+- An update path for git-cloned skins (today: re-clone or store reinstall).
+- Animation support in skins (today the API is one frame per render call;
+  stateful tricks work but are at-your-own-risk).

docs/widget-guide.md

@@ -206,6 +206,40 @@ To use an existing widget in your plugin's `config_schema.json`, simply add the
 
 The widget will be automatically rendered when the plugin configuration form is loaded.
 
+## Marking Fields as Advanced (`x-advanced`)
+
+Add `"x-advanced": true` to any top-level, non-object property to move it out
+of the main form and into a single collapsed **Advanced Settings** section at
+the bottom of the plugin's configuration page:
+
+```json
+{
+  "properties": {
+    "city": {
+      "type": "string",
+      "title": "City"
+    },
+    "request_timeout": {
+      "type": "integer",
+      "default": 10,
+      "description": "HTTP timeout in seconds",
+      "x-advanced": true
+    }
+  }
+}
+```
+
+Guidelines:
+
+- Use it for fine-tuning knobs most users never touch (timeouts, retry
+  behavior, cache TTLs, styling overrides). Anything a first-time user must
+  set to get the plugin working should stay basic.
+- Nothing is hidden permanently — the section expands on click, and the
+  settings search finds and auto-expands advanced fields like any others.
+- The flag is ignored on `object`-type properties (they already render as
+  their own collapsible sections) and is safely ignored by older cores, so
+  adding it never breaks compatibility.
+
 ## Creating Custom Widgets
 
 ### Step 1: Create Widget File

scripts/dev/vegas_audit.py

@@ -0,0 +1,384 @@
+#!/usr/bin/env python3
+"""
+Vegas Mode Density Audit
+
+Reports how much of the Vegas ticker is actually showing something. Loads the
+real enabled plugins, pulls each one's content through the real
+``PluginAdapter``, composes the strip through the real ``ScrollHelper``, then
+measures the result.
+
+The headline number is the **dead-frame ratio**: the fraction of viewport
+positions across a full cycle that are effectively blank. Because the panel
+only ever shows ``display_width`` columns at a time, a blank stretch wider than
+the viewport is a stretch where the display looks switched off — so this ratio
+tracks perceived dead time rather than just counting unlit pixels.
+
+Runs entirely off-hardware, so it is safe to run alongside a live display.
+
+Usage:
+    # Audit every enabled plugin at the display size from config.json
+    python scripts/dev/vegas_audit.py
+
+    # Specific plugins, dump each segment as a PNG for eyeballing
+    python scripts/dev/vegas_audit.py -p of-the-day,youtube-stats --dump-dir /tmp/vg
+
+    # Machine-readable, for before/after comparison
+    python scripts/dev/vegas_audit.py --json > after.json
+"""
+
+import argparse
+import json
+import logging
+import os
+import sys
+import time
+from pathlib import Path
+from typing import Any, Dict, List
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent
+sys.path.insert(0, str(PROJECT_ROOT))
+
+# Must precede any src import that may reach for hardware.
+os.environ.setdefault('EMULATOR', 'true')
+
+from PIL import Image  # noqa: E402
+
+from src.common.scroll_helper import ScrollHelper  # noqa: E402
+from src.plugin_system.testing.loading import (  # noqa: E402
+    build_full_config,
+    find_plugin_dir,
+    load_manifest,
+)
+from src.vegas_mode.config import VegasModeConfig  # noqa: E402
+from src.vegas_mode.geometry import (  # noqa: E402
+    DEFAULT_INK_THRESHOLD,
+    column_has_ink,
+    content_bounds,
+    dead_window_stats,
+    window_coverage_stats,
+)
+from src.vegas_mode.plugin_adapter import PluginAdapter  # noqa: E402
+
+# Sampling stride for the dead-window scan. A full cycle can be 30,000px wide;
+# 4px granularity keeps the scan instant while staying well under the ~10px a
+# single scroll step ever covers, so no dead stretch is missed.
+DEAD_SCAN_STEP = 4
+
+
+def load_main_config(path: Path) -> Dict[str, Any]:
+    with open(path, 'r') as fh:
+        return json.load(fh)
+
+
+def display_size_from_config(config: Dict[str, Any]) -> tuple:
+    """Derive the logical ticker size the way DisplayManager does."""
+    hw = config.get('display', {}).get('hardware', {})
+    cols = int(hw.get('cols', 64))
+    chain = int(hw.get('chain_length', 1))
+    rows = int(hw.get('rows', 32))
+    parallel = int(hw.get('parallel', 1))
+    return cols * chain, rows * parallel
+
+
+def enabled_plugin_ids(config: Dict[str, Any]) -> List[str]:
+    """Plugin IDs that are enabled in config, excluding non-plugin sections."""
+    ids = []
+    for key, value in config.items():
+        if isinstance(value, dict) and value.get('enabled') is True:
+            ids.append(key)
+    return ids
+
+
+def instantiate(plugin_id: str, display_manager, cache_manager, plugin_manager):
+    """Load one plugin offline. Returns the instance or None."""
+    from src.plugin_system.plugin_loader import PluginLoader
+
+    search_dirs = [
+        str(PROJECT_ROOT / 'plugin-repos'),
+        str(PROJECT_ROOT / 'plugins'),
+    ]
+    plugin_dir = find_plugin_dir(plugin_id, search_dirs)
+    if not plugin_dir:
+        return None
+
+    try:
+        manifest = load_manifest(Path(plugin_dir))
+        cfg = build_full_config(Path(plugin_dir))
+        instance, _ = PluginLoader().load_plugin(
+            plugin_id=plugin_id,
+            manifest=manifest,
+            plugin_dir=Path(plugin_dir),
+            config=cfg,
+            display_manager=display_manager,
+            cache_manager=cache_manager,
+            plugin_manager=plugin_manager,
+            install_deps=False,
+        )
+        return instance
+    except Exception as exc:  # noqa: BLE001 - audit tool must survive any plugin
+        print(f"  ! {plugin_id}: load failed ({type(exc).__name__}: {exc})",
+              file=sys.stderr)
+        return None
+
+
+def join_rows(images: List[Image.Image], gap: int) -> Image.Image:
+    """Concatenate one plugin's rows, matching RenderPipeline._join_plugin_rows."""
+    if len(images) == 1:
+        return images[0]
+    gap = max(0, gap)
+    width = sum(img.width for img in images) + gap * (len(images) - 1)
+    height = max(img.height for img in images)
+    block = Image.new('RGB', (width, height), (0, 0, 0))
+    x = 0
+    for img in images:
+        block.paste(img, (x, 0))
+        x += img.width + gap
+    return block
+
+
+def measure_segment(images: List[Image.Image], display_width: int,
+                    scroll_speed: float, threshold: int) -> Dict[str, Any]:
+    """Geometry of one plugin's contribution to the ticker."""
+    total_width = sum(img.width for img in images)
+    combined = Image.new('RGB', (max(1, total_width), images[0].height))
+    x = 0
+    for img in images:
+        combined.paste(img, (x, 0))
+        x += img.width
+
+    ink = column_has_ink(combined, threshold)
+    bounds = content_bounds(combined, threshold)
+    ink_cols = int(ink.sum())
+
+    return {
+        'images': len(images),
+        'width_px': total_width,
+        'ink_cols': ink_cols,
+        'ink_pct': round(100.0 * ink_cols / total_width, 1) if total_width else 0.0,
+        'lead_black_px': bounds[0] if bounds else total_width,
+        'trail_black_px': (total_width - 1 - bounds[1]) if bounds else 0,
+        'seconds_on_screen': round(total_width / scroll_speed, 1) if scroll_speed else 0.0,
+        'widths': [img.width for img in images],
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description='Audit Vegas mode content density')
+    parser.add_argument('--config', default=str(PROJECT_ROOT / 'config' / 'config.json'),
+                        help='Path to main config.json')
+    parser.add_argument('-p', '--plugins', default=None,
+                        help='Comma-separated plugin IDs (default: all enabled)')
+    parser.add_argument('--width', type=int, default=None,
+                        help='Override display width (default: from config hardware)')
+    parser.add_argument('--height', type=int, default=None,
+                        help='Override display height (default: from config hardware)')
+    parser.add_argument('--dump-dir', default=None,
+                        help='Write each segment and the composed strip as PNGs here')
+    parser.add_argument('--threshold', type=int, default=DEFAULT_INK_THRESHOLD,
+                        help=f'Ink threshold (default: {DEFAULT_INK_THRESHOLD})')
+    parser.add_argument('--per-cycle', type=int, default=None,
+                        help='Plugins composed per cycle '
+                             '(default: buffer_ahead + 1, matching production)')
+    parser.add_argument('--json', action='store_true',
+                        help='Emit JSON instead of a text report')
+    args = parser.parse_args()
+
+    config = load_main_config(Path(args.config))
+    vegas = VegasModeConfig.from_config(config)
+
+    cfg_w, cfg_h = display_size_from_config(config)
+    width = args.width or cfg_w
+    height = args.height or cfg_h
+    speed = vegas.scroll_speed
+
+    if args.plugins:
+        plugin_ids = [p.strip() for p in args.plugins.split(',') if p.strip()]
+    else:
+        plugin_ids = vegas.get_ordered_plugins(enabled_plugin_ids(config))
+
+    dump_dir = Path(args.dump_dir) if args.dump_dir else None
+    if dump_dir:
+        dump_dir.mkdir(parents=True, exist_ok=True)
+
+    from src.plugin_system.testing import (
+        MockCacheManager, MockPluginManager, VisualTestDisplayManager,
+    )
+
+    display_manager = VisualTestDisplayManager(width=width, height=height)
+    cache_manager = MockCacheManager()
+    plugin_manager = MockPluginManager()
+    # Pass the loaded config, exactly as VegasModeCoordinator does. Omitting it
+    # makes PluginAdapter fall back to VegasModeConfig() defaults, so the audit
+    # would silently report trimming and width-budget behaviour that differs
+    # from the user's config.json — the same drift the lead_gap and grouping
+    # arguments below exist to avoid.
+    adapter = PluginAdapter(display_manager, vegas)
+
+    if not args.json:
+        print(f"Vegas audit — display {width}x{height}, scroll {speed:g}px/s, "
+              f"separator {vegas.separator_width}px")
+        print(f"One display width = {width / speed:.1f}s of screen time\n")
+
+    results: List[Dict[str, Any]] = []
+    segments: List[Image.Image] = []
+
+    for plugin_id in plugin_ids:
+        started = time.time()
+        instance = instantiate(plugin_id, display_manager, cache_manager, plugin_manager)
+        if instance is None:
+            results.append({'plugin': plugin_id, 'status': 'load_failed'})
+            continue
+
+        plugin_manager.plugins[plugin_id] = instance
+        adapter.invalidate_cache(plugin_id)
+
+        try:
+            images = adapter.get_content(instance, plugin_id)
+        except Exception as exc:  # noqa: BLE001
+            results.append({'plugin': plugin_id, 'status': 'fetch_error',
+                            'error': f'{type(exc).__name__}: {exc}'})
+            continue
+
+        fetch_ms = round((time.time() - started) * 1000)
+
+        if not images:
+            results.append({'plugin': plugin_id, 'status': 'no_content',
+                            'fetch_ms': fetch_ms})
+            if not args.json:
+                print(f"  {plugin_id:28s} NO CONTENT            ({fetch_ms}ms)")
+            continue
+
+        entry = {'plugin': plugin_id, 'status': 'ok', 'fetch_ms': fetch_ms}
+        entry.update(measure_segment(images, width, speed, args.threshold))
+        results.append(entry)
+        segments.extend(images)
+
+        if dump_dir:
+            for idx, img in enumerate(images):
+                img.save(dump_dir / f"{plugin_id}__{idx:02d}.png")
+
+        if not args.json:
+            print(f"  {plugin_id:28s} {entry['width_px']:>6d}px  "
+                  f"{entry['images']:>2d} img  ink {entry['ink_pct']:>5.1f}%  "
+                  f"lead {entry['lead_black_px']:>4d}  tail {entry['trail_black_px']:>4d}  "
+                  f"{entry['seconds_on_screen']:>6.1f}s  ({fetch_ms}ms)")
+
+    summary: Dict[str, Any] = {
+        'display_width': width,
+        'display_height': height,
+        'scroll_speed': speed,
+        'separator_width': vegas.separator_width,
+        'plugins_audited': len(plugin_ids),
+        'plugins_with_content': sum(1 for r in results if r.get('status') == 'ok'),
+    }
+
+    # Production composes only the plugins sitting in the active buffer, so
+    # measuring one giant strip of every plugin would hide the per-cycle costs
+    # (most importantly the leading gap, which is charged once per cycle).
+    # Group the segments the way the running service does.
+    per_cycle = max(1, args.per_cycle or vegas.plugins_per_cycle)
+
+    cycles: List[Dict[str, Any]] = []
+    with_content = [r for r in results if r.get('status') == 'ok']
+
+    if segments:
+        logger = logging.getLogger('vegas_audit')
+        seg_index = 0
+        for start in range(0, len(with_content), per_cycle):
+            group = with_content[start:start + per_cycle]
+
+            # Mirror RenderPipeline: each plugin's rows are joined by
+            # intra_plugin_gap into one block, and separator_width is applied
+            # only between blocks. Measuring a flat list here would report gaps
+            # the service does not emit.
+            blocks: List[Image.Image] = []
+            for entry in group:
+                count = entry['images']
+                rows = segments[seg_index:seg_index + count]
+                seg_index += count
+                if rows:
+                    blocks.append(join_rows(rows, vegas.intra_plugin_gap))
+            if not blocks:
+                continue
+
+            # ScrollHelper logs unconditionally, so it needs a real logger.
+            helper = ScrollHelper(width, height, logger)
+            helper.create_scrolling_image(
+                content_items=blocks,
+                item_gap=vegas.separator_width,
+                element_gap=0,
+                # Must match RenderPipeline. Omitting this made the audit
+                # measure a full-display-width leading gap the service no
+                # longer emits, overstating dead space by 512px per cycle.
+                lead_gap=vegas.lead_in_width,
+            )
+            composed = helper.cached_image
+            if composed is None:
+                continue
+
+            dead = dead_window_stats(composed, width, args.threshold, step=DEAD_SCAN_STEP)
+            cover = window_coverage_stats(
+                composed, width, args.threshold, step=DEAD_SCAN_STEP)
+
+            if dump_dir:
+                composed.save(dump_dir / f"_cycle{len(cycles):02d}.png")
+
+            cycles.append({
+                'plugins': [e['plugin'] for e in group],
+                'width_px': composed.width,
+                'seconds': round(composed.width / speed, 1) if speed else 0.0,
+                'dead_pct': round(100 * dead.dead_ratio, 1),
+                'longest_dead_seconds': round(
+                    dead.longest_dead_run * DEAD_SCAN_STEP / speed, 1) if speed else 0.0,
+                'mean_ink_pct': round(100 * cover.mean_ink_ratio, 1),
+                'sparse_pct': round(100 * cover.sparse_ratio, 1),
+                'longest_sparse_seconds': round(
+                    cover.longest_sparse_run * DEAD_SCAN_STEP / speed, 1) if speed else 0.0,
+            })
+
+    if cycles:
+        total_px = sum(c['width_px'] for c in cycles)
+        # Weight each cycle by its width so a long cycle counts proportionally.
+        summary.update({
+            'cycles': len(cycles),
+            'total_px': total_px,
+            'full_rotation_seconds': round(total_px / speed, 1) if speed else 0.0,
+            'dead_pct': round(
+                sum(c['dead_pct'] * c['width_px'] for c in cycles) / total_px, 1),
+            'mean_ink_pct': round(
+                sum(c['mean_ink_pct'] * c['width_px'] for c in cycles) / total_px, 1),
+            'sparse_pct': round(
+                sum(c['sparse_pct'] * c['width_px'] for c in cycles) / total_px, 1),
+            'worst_dead_seconds': max(c['longest_dead_seconds'] for c in cycles),
+            'worst_sparse_seconds': max(c['longest_sparse_seconds'] for c in cycles),
+        })
+
+    if args.json:
+        print(json.dumps({'summary': summary, 'cycles': cycles, 'plugins': results},
+                         indent=2))
+    else:
+        print(f"\n  Cycles ({per_cycle} plugins each, as production composes them):")
+        for idx, cyc in enumerate(cycles):
+            print(f"    [{idx}] {cyc['width_px']:>6d}px {cyc['seconds']:>6.1f}s  "
+                  f"ink {cyc['mean_ink_pct']:>5.1f}%  blank {cyc['dead_pct']:>5.1f}%  "
+                  f"worst blank {cyc['longest_dead_seconds']:>5.1f}s  "
+                  f"| {', '.join(cyc['plugins'])}")
+
+        print(f"\n  {'-' * 66}")
+        print(f"  full rotation        {summary.get('full_rotation_seconds', 0):>7.1f}s "
+              f"over {summary.get('cycles', 0)} cycles")
+        print(f"  mean ink coverage    {summary.get('mean_ink_pct', 0):>7.1f}%  "
+              f"(higher is better; target >25%)")
+        print(f"  fully blank          {summary.get('dead_pct', 0):>7.1f}%  (target <2%)")
+        print(f"  reads as empty       {summary.get('sparse_pct', 0):>7.1f}%  (target <15%)")
+        print(f"  worst blank stretch  {summary.get('worst_dead_seconds', 0):>7.1f}s  "
+              f"(target <1.5s)")
+        print(f"  plugins w/ content   {summary.get('plugins_with_content', 0):>7d}"
+              f" of {summary['plugins_audited']}")
+
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

scripts/validate_skin.py

@@ -0,0 +1,248 @@
+#!/usr/bin/env python3
+"""
+Headless skin validator — render a skin against bundled fixture games at
+multiple panel sizes without hardware, a network, or a running service.
+
+    python scripts/validate_skin.py --skin my-skin
+    python scripts/validate_skin.py --skin my-skin --sport baseball \
+        --size 128x32 --size 64x32 --output-dir /tmp/skin_renders
+
+For each (mode x size) it checks: the manifest loads and its API version
+matches, the render raises no exception, the canvas isn't blank, and the
+render finishes inside a time budget (warn — the live renderer runs every
+display-loop pass, and a Pi is far slower than your dev machine). PNGs are
+saved (native plus 4x nearest-neighbor previews) so you can eyeball the
+result. Exit code is non-zero when any check fails.
+"""
+
+import argparse
+import json
+import logging
+import sys
+import time
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(PROJECT_ROOT))
+
+from PIL import Image, ImageDraw, ImageFont  # noqa: E402
+
+FIXTURES_DIR = PROJECT_ROOT / "src" / "skin_system" / "fixtures"
+MODES = ("live", "recent", "upcoming")
+SPORTS = ("baseball", "basketball", "football", "hockey")
+RENDER_BUDGET_S = 0.100
+
+
+class FixtureHost:
+    """Stands in for a SportsCore instance: fonts, logger, logo loading,
+    outlined text — everything build_context needs, no network."""
+
+    def __init__(self, sport: str, skin_options: dict) -> None:
+        self.sport = sport
+        self.sport_key = sport
+        self.skin_options = skin_options
+        self.logger = logging.getLogger(f"validate_skin.{sport}")
+        self.fonts = self._load_fonts()
+        self._logo_cache = {}
+        self.display_manager = None  # build_context is always given a size
+
+    def _load_fonts(self) -> dict:
+        """Load the SportsCore font set (TTF, with PIL default fallback)."""
+        fonts = {}
+        try:
+            press = str(PROJECT_ROOT / "assets/fonts/PressStart2P-Regular.ttf")
+            small = str(PROJECT_ROOT / "assets/fonts/4x6-font.ttf")
+            fonts['score'] = ImageFont.truetype(press, 10)
+            fonts['time'] = ImageFont.truetype(press, 8)
+            fonts['team'] = ImageFont.truetype(press, 8)
+            fonts['status'] = ImageFont.truetype(small, 6)
+            fonts['detail'] = ImageFont.truetype(small, 6)
+            fonts['rank'] = ImageFont.truetype(press, 10)
+        except IOError:
+            default = ImageFont.load_default()
+            for key in ('score', 'time', 'team', 'status', 'detail', 'rank'):
+                fonts[key] = default
+        return fonts
+
+    def _load_and_resize_logo(self, team_id: str, team_abbrev: str,
+                              logo_path, logo_url) -> "Image.Image | None":
+        """Load a fixture logo from disk (no downloads), cached per team."""
+        if team_abbrev in self._logo_cache:
+            return self._logo_cache[team_abbrev]
+        path = Path(logo_path)
+        if not path.is_absolute():
+            path = PROJECT_ROOT / path
+        if not path.exists():
+            return None
+        logo = Image.open(path).convert('RGBA')
+        self._logo_cache[team_abbrev] = logo
+        return logo
+
+    def _draw_text_with_outline(self, draw: "ImageDraw.ImageDraw", text: str,
+                                position: tuple, font,
+                                fill: tuple = (255, 255, 255),
+                                outline_color: tuple = (0, 0, 0)) -> None:
+        """Classic outlined scorebug text, same as SportsCore's helper."""
+        x, y = position
+        for dx, dy in [(-1, -1), (-1, 0), (-1, 1), (0, -1), (0, 1),
+                       (1, -1), (1, 0), (1, 1)]:
+            draw.text((x + dx, y + dy), text, font=font, fill=outline_color)
+        draw.text((x, y), text, font=font, fill=fill)
+
+
+def load_fixture(sport: str, mode: str) -> dict:
+    with open(FIXTURES_DIR / f"{sport}_{mode}.json", encoding="utf-8") as f:
+        game = json.load(f)
+    # Real view models carry start_time_utc as a UTC datetime, not a string.
+    if isinstance(game.get("start_time_utc"), str):
+        from datetime import datetime
+        game["start_time_utc"] = datetime.fromisoformat(game["start_time_utc"])
+    return game
+
+
+def parse_size(value: str) -> "tuple[int, int]":
+    try:
+        w_text, h_text = value.lower().split("x")
+        w, h = int(w_text), int(h_text)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(f"size must look like 128x32, got {value!r}") from exc
+    if w <= 0 or h <= 0:
+        raise argparse.ArgumentTypeError(f"size dimensions must be positive, got {value!r}")
+    return w, h
+
+
+def parse_options(value: str) -> dict:
+    try:
+        options = json.loads(value)
+    except json.JSONDecodeError as exc:
+        raise argparse.ArgumentTypeError(f"options must be valid JSON: {exc.msg}") from exc
+    if not isinstance(options, dict):
+        raise argparse.ArgumentTypeError("options must be a JSON object")
+    return options
+
+
+def display_path(path: Path) -> str:
+    """Repo-relative when inside the repo, absolute otherwise (--output-dir
+    may point anywhere, e.g. /tmp/skin_renders)."""
+    try:
+        return str(path.relative_to(PROJECT_ROOT))
+    except ValueError:
+        return str(path)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__,
+                                     formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--skin", required=True, help="skin id (directory name under skins/)")
+    parser.add_argument("--sport", choices=SPORTS,
+                        help="fixture sport (default: first sport the skin targets, else baseball)")
+    parser.add_argument("--size", action="append", type=parse_size, dest="sizes",
+                        metavar="WxH", help="panel size to render at (repeatable; default 128x32 and 64x32)")
+    parser.add_argument("--output-dir", type=Path,
+                        default=PROJECT_ROOT / "skin_renders",
+                        help="where rendered PNGs are written")
+    parser.add_argument("--options", type=parse_options, default={},
+                        help="skin_options JSON to pass the skin")
+    args = parser.parse_args()
+    sizes = args.sizes or [(128, 32), (64, 32)]
+
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+
+    from src.skin_system import skin_runtime
+    from src.skin_system.skin_base import SKIN_API_VERSION
+
+    skins = skin_runtime.discover_skins()
+    manifest = skins.get(args.skin)
+    if manifest is None:
+        print(f"FAIL: skin '{args.skin}' not found under {skin_runtime.get_skins_directory()}")
+        if skins:
+            print(f"      installed skins: {', '.join(sorted(skins))}")
+        return 1
+
+    sport = args.sport
+    if sport is None:
+        declared = skin_runtime.skin_targets(manifest)[0]
+        sport = next((s for s in declared if s in SPORTS), "baseball")
+
+    skin = skin_runtime.load_skin(args.skin, sport=sport, sport_key=sport,
+                                  options=args.options)
+    if skin is None:
+        print(f"FAIL: skin '{args.skin}' did not load "
+              f"(see log above; host API is {SKIN_API_VERSION})")
+        return 1
+
+    host = FixtureHost(sport, args.options)
+    args.output_dir.mkdir(parents=True, exist_ok=True)
+    failures = 0
+    rendered = 0
+
+    for mode in MODES:
+        game = load_fixture(sport, mode)
+        render = getattr(skin, f"render_{mode}")
+        for width, height in sizes:
+            label = f"{mode}@{width}x{height}"
+            try:
+                # Warm-up render absorbs one-time font/image loads, second
+                # render is the one timed against the budget.
+                ctx = skin_runtime.build_context(host, game, size=(width, height))
+                handled = render(ctx, dict(game))
+                if handled:
+                    ctx = skin_runtime.build_context(host, game, size=(width, height))
+                    started = time.monotonic()
+                    handled = render(ctx, dict(game))
+                    elapsed = time.monotonic() - started
+                else:
+                    elapsed = 0.0
+            except Exception as e:
+                print(f"FAIL {label}: render raised {type(e).__name__}: {e}")
+                import traceback
+                traceback.print_exc()
+                failures += 1
+                continue
+
+            if not handled:
+                print(f"skip {label}: render_{mode} returned False (built-in renderer would be used)")
+                continue
+
+            if ctx.canvas.size != (width, height):
+                print(f"FAIL {label}: canvas was replaced/resized to {ctx.canvas.size} — draw onto ctx.canvas, never reassign it")
+                failures += 1
+                continue
+            if ctx.canvas.convert("L").getbbox() is None:
+                print(f"FAIL {label}: canvas is blank — render returned True but drew nothing")
+                failures += 1
+                continue
+            if elapsed > RENDER_BUDGET_S:
+                print(f"WARN {label}: render took {elapsed * 1000:.0f}ms "
+                      f"(budget {RENDER_BUDGET_S * 1000:.0f}ms; a Pi is much slower than this machine)")
+
+            out = args.output_dir / f"{args.skin}_{sport}_{mode}_{width}x{height}.png"
+            ctx.canvas.save(out)
+            preview = ctx.canvas.resize((width * 4, height * 4), Image.NEAREST)
+            preview.save(out.with_name(out.stem + "_x4.png"))
+            print(f"ok   {label}: {elapsed * 1000:.0f}ms -> {display_path(out)}")
+            rendered += 1
+
+        # Vegas card, once per mode at the first size (optional API)
+        try:
+            width, height = sizes[0]
+            ctx = skin_runtime.build_context(host, game, size=(width, height))
+            card = skin.render_vegas_card(ctx, dict(game))
+            if card is not None:
+                out = args.output_dir / f"{args.skin}_{sport}_{mode}_vegas.png"
+                card.save(out)
+                print(f"ok   {mode} vegas card -> {display_path(out)}")
+        except Exception as e:
+            print(f"FAIL {mode} vegas card: {type(e).__name__}: {e}")
+            failures += 1
+
+    if rendered == 0 and failures == 0:
+        print(f"FAIL: skin '{args.skin}' rendered nothing — no render_<mode> returned True")
+        return 1
+    print(f"\n{'FAILED' if failures else 'PASSED'}: {rendered} renders, {failures} failures "
+          f"(PNGs in {args.output_dir})")
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

skins/README.md

@@ -0,0 +1,23 @@
+# skins/
+
+User-installable **visual skins** for the sports scoreboards. Each
+subdirectory is one skin:
+
+```text
+skins/<skin-id>/
+  skin.json     # manifest
+  skin.py       # renderer (a ScoreboardSkin subclass)
+  preview.png   # optional
+```
+
+- Install a skin: `git clone <skin repo> skins/<skin-id>` (or via the Plugin
+  Store for registry entries with `"type": "skin"`).
+- Select it: set `"skin": "<skin-id>"` in the plugin's section of
+  `config/config.json`, or use the web UI's Visual Skin dropdown.
+- Build one: start from `example-classic-baseball/` and read
+  [docs/CREATING_SKINS.md](../docs/CREATING_SKINS.md). Validate with
+  `python scripts/validate_skin.py --skin <skin-id>`.
+
+Skins survive plugin reinstalls/updates (that's why they live here and not in
+the plugin's directory). A skin is Python at the same trust level as a
+plugin — review before installing.

skins/example-classic-baseball/skin.json

@@ -0,0 +1,25 @@
+{
+  "id": "example-classic-baseball",
+  "name": "Example: Classic Baseball",
+  "version": "1.0.0",
+  "author": "LEDMatrix",
+  "description": "Reference skin: a restyled baseball scorebug demonstrating the skin API. Copy this directory to start your own skin.",
+  "skin_api_version": "1.0.0",
+  "targets": {
+    "sports": [
+      "baseball"
+    ],
+    "sport_keys": [
+      "mlb",
+      "milb"
+    ]
+  },
+  "entry_point": "skin.py",
+  "class_name": "ClassicBaseballSkin",
+  "modes": [
+    "live",
+    "recent",
+    "upcoming"
+  ],
+  "preview": "preview.png"
+}

skins/example-classic-baseball/skin.py

@@ -0,0 +1,131 @@
+"""
+Example: Classic Baseball — the reference skin.
+
+Shows the whole skin API surface on purpose: adaptive regions
+(scoreboard_regions), fitted text (ctx.layout.fit_text + ctx.draw_fit),
+logos (ctx.load_logo + ctx.draw_image), raw PIL (ctx.draw for the bases
+diamond), and per-user options (ctx.options). Everything is derived from
+ctx and the game dict — a skin holds no state, does no I/O, and never
+touches the display.
+
+Copy this directory to skins/<your-skin-id>/, rename the class and the
+manifest fields, and run:
+
+    python scripts/validate_skin.py --skin <your-skin-id>
+"""
+
+from src.adaptive_layout import LADDER_GRID, scoreboard_regions
+from src.skin_system.skin_base import ScoreboardSkin, SkinContext
+
+DEFAULT_ACCENT = (255, 200, 0)
+
+
+class ClassicBaseballSkin(ScoreboardSkin):
+    """Reference baseball skin: classic scorebug with bases/outs/count."""
+
+    def __init__(self, manifest: dict, options: dict):
+        super().__init__(manifest, options)
+        # Validate user options once at load time (fail fast, fall back
+        # gracefully) rather than surprising every render.
+        accent = self.options.get("accent_color", DEFAULT_ACCENT)
+        if (isinstance(accent, (list, tuple)) and len(accent) == 3
+                and all(isinstance(c, int) and 0 <= c <= 255 for c in accent)):
+            self._accent_color = tuple(accent)
+        else:
+            import logging
+            logging.getLogger(__name__).error(
+                "accent_color must be three 0-255 integers, got %r; using default", accent)
+            self._accent_color = DEFAULT_ACCENT
+
+    # -- shared pieces ----------------------------------------------------
+
+    def _accent(self, ctx: SkinContext) -> tuple:
+        """Users can recolor the skin from config via skin_options."""
+        return self._accent_color
+
+    def _draw_card(self, ctx: SkinContext, game: dict, status: str,
+                   center_lines: list, detail: str) -> None:
+        """The common card: logos left/right, status on top, the given
+        center content, detail along the bottom."""
+        regions = scoreboard_regions(ctx.layout.bounds, ctx=ctx.layout)
+
+        ctx.draw_image(ctx.load_logo("away"), regions.away_slot,
+                       cache_key=f"logo:{game.get('away_abbr')}")
+        ctx.draw_image(ctx.load_logo("home"), regions.home_slot,
+                       cache_key=f"logo:{game.get('home_abbr')}")
+
+        if status:
+            fit = ctx.layout.fit_text(status, regions.status_band, LADDER_GRID)
+            ctx.draw_fit(fit, regions.status_band, color=self._accent(ctx))
+
+        if center_lines:
+            rows = regions.score_area.split_v(*[1] * len(center_lines))
+            for line, row in zip(center_lines, rows):
+                if line:
+                    fit = ctx.layout.fit_text(line, row, LADDER_GRID)
+                    ctx.draw_fit(fit, row)
+
+        if detail:
+            fit = ctx.layout.fit_text(detail, regions.detail_band, LADDER_GRID)
+            ctx.draw_fit(fit, regions.detail_band, color=(160, 160, 160))
+
+    def _draw_bases_and_outs(self, ctx: SkinContext, game: dict) -> None:
+        """Raw-PIL escape hatch: a bases diamond + out dots in the bottom
+        band, sized from the layout scale so it works on any panel."""
+        size = ctx.layout.px(3, minimum=2)     # half-diagonal of one base
+        gap = ctx.layout.px(1)
+        cx = ctx.width // 2
+        cy = ctx.height - (size * 2) - 1
+
+        bases = game.get("bases_occupied") or [False, False, False]
+        # (dx, dy) per base: first (right), second (top), third (left)
+        offsets = [(size + gap, 0), (0, -(size + gap)), (-(size + gap), 0)]
+        for occupied, (dx, dy) in zip(bases, offsets):
+            x, y = cx + dx, cy + dy
+            diamond = [(x, y - size), (x + size, y), (x, y + size), (x - size, y)]
+            if occupied:
+                ctx.draw.polygon(diamond, fill=self._accent(ctx))
+            else:
+                ctx.draw.polygon(diamond, outline=(110, 110, 110))
+
+        outs = min(int(game.get("outs") or 0), 3)
+        r = max(1, size - 1)
+        for i in range(3):
+            x = cx + (i - 1) * (2 * r + 2 * gap)
+            y = ctx.height - r - 1
+            dot = [x - r, y - r, x + r, y + r]
+            if i < outs:
+                ctx.draw.ellipse(dot, fill=(255, 255, 255))
+            else:
+                ctx.draw.ellipse(dot, outline=(110, 110, 110))
+
+    # -- the three modes --------------------------------------------------
+
+    def render_live(self, ctx: SkinContext, game: dict) -> bool:
+        half = "▲" if game.get("inning_half") == "top" else "▼"
+        inning = game.get("inning") or ""
+        status = f"{half}{inning}" if inning else game.get("status_text", "")
+        score = f"{game.get('away_score', '0')}-{game.get('home_score', '0')}"
+        count = f"{game.get('balls', 0)}-{game.get('strikes', 0)}"
+
+        self._draw_card(ctx, game, status, [score], "")
+        self._draw_bases_and_outs(ctx, game)
+
+        # Ball-strike count in the top-left corner, over the away logo.
+        fit = ctx.layout.fit_text(count, (ctx.width // 4, ctx.layout.px(8, minimum=6)), LADDER_GRID)
+        ctx.draw_fit(fit, ctx.layout.bounds.top_band(fit.height + 1).left_col(fit.width + 2),
+                     color=(200, 200, 200))
+        return True
+
+    def render_recent(self, ctx: SkinContext, game: dict) -> bool:
+        score = f"{game.get('away_score', '0')}-{game.get('home_score', '0')}"
+        self._draw_card(ctx, game, game.get("status_text", "Final"),
+                        [score], game.get("series_summary", ""))
+        return True
+
+    def render_upcoming(self, ctx: SkinContext, game: dict) -> bool:
+        matchup = f"{game.get('away_abbr', '')}@{game.get('home_abbr', '')}"
+        self._draw_card(ctx, game, game.get("game_date", ""),
+                        [matchup, game.get("game_time", "")],
+                        f"{game.get('away_record', '')} {game.get('home_record', '')}".strip())
+        return True

src/base_classes/sports.py

@@ -29,6 +29,10 @@ except ImportError:
 
 
 class SportsCore(ABC):
+    # Which ScoreboardSkin render method this class's display path maps to.
+    # SportsLive inherits the default; SportsUpcoming/SportsRecent override.
+    SKIN_MODE = "live"
+
     def __init__(self, config: Dict[str, Any], display_manager: DisplayManager, cache_manager: CacheManager, logger: logging.Logger, sport_key: str):
         self.logger = logger
         self.config = config
@@ -99,6 +103,17 @@ class SportsCore(ABC):
         self.last_update = 0
         self.current_game = None
         self.fonts = self._load_fonts()
+
+        # Optional visual skin (see docs/SKIN_SYSTEM.md). "skin" is either a
+        # skin id applied to all modes, or a per-mode mapping like
+        # {"live": "retro", "recent": "built-in"}. Loaded lazily on first
+        # render so a broken skin can never block startup.
+        self._skin_config = self.mode_config.get("skin")
+        self.skin_options = self.mode_config.get("skin_options", {}) or {}
+        self._skin = None
+        self._skin_load_attempted = False
+        self._skin_failures = 0
+        self._skin_slow_renders = 0
         
         # Initialize dynamic team resolver and resolve favorite teams
         self.dynamic_resolver = DynamicTeamResolver()
@@ -205,6 +220,95 @@ class SportsCore(ABC):
             self.logger.error(f"Error in base _draw_scorebug_layout: {e}", exc_info=True)
 
 
+    def _resolve_skin_id(self) -> Optional[str]:
+        """The skin id configured for this instance's mode, or None for the
+        built-in renderer. Accepts a plain id (all modes) or a per-mode
+        mapping ({"live": "retro-baseball", "recent": "built-in"})."""
+        skin_id = self._skin_config
+        if isinstance(skin_id, dict):
+            skin_id = skin_id.get(self.SKIN_MODE)
+        if not skin_id or not isinstance(skin_id, str) or skin_id == "built-in":
+            return None
+        return skin_id
+
+    def _get_skin(self):
+        """Lazily load the configured skin once. Returns None (built-in
+        renderer) when no skin is configured or loading failed."""
+        if not self._skin_load_attempted:
+            self._skin_load_attempted = True
+            skin_id = self._resolve_skin_id()
+            if skin_id:
+                try:
+                    from src.skin_system import skin_runtime
+                    self._skin = skin_runtime.load_skin(
+                        skin_id, sport=self.sport, sport_key=self.sport_key,
+                        options=self.skin_options)
+                except Exception as e:
+                    self.logger.error(f"Failed to load skin '{skin_id}': {e}", exc_info=True)
+                    self._skin = None
+        return self._skin
+
+    def _render_game(self, game: Dict, force_clear: bool = False) -> None:
+        """Render one game: try the configured skin first, fall back to the
+        built-in _draw_scorebug_layout. A skin that raises 3 times in a row
+        is disabled for the rest of the session."""
+        skin = self._get_skin()
+        if skin is not None and self._skin_failures < 3:
+            try:
+                from src.skin_system import skin_runtime
+                ctx = skin_runtime.build_context(self, game)
+                render = getattr(skin, f"render_{self.SKIN_MODE}")
+                started = time.monotonic()
+                handled = render(ctx, dict(game))
+                elapsed = time.monotonic() - started
+                if elapsed > 0.15 and self._skin_slow_renders < 5:
+                    self._skin_slow_renders += 1
+                    self.logger.warning(
+                        f"Skin '{self._resolve_skin_id()}' took {elapsed * 1000:.0f}ms to "
+                        f"render {self.SKIN_MODE} — slow renders stall the whole display loop")
+                if handled:
+                    self._skin_failures = 0
+                    self.display_manager.image.paste(ctx.canvas, (0, 0))
+                    self.display_manager.update_display()
+                    return
+            except Exception:
+                self._skin_failures += 1
+                outcome = ("disabling skin for this session" if self._skin_failures >= 3
+                           else "falling back to built-in renderer")
+                self.logger.error(
+                    f"Skin '{self._resolve_skin_id()}' failed rendering {self.SKIN_MODE} "
+                    f"({self._skin_failures}/3); {outcome}", exc_info=True)
+        self._draw_scorebug_layout(game, force_clear)
+
+    def render_skin_card(self, game: Dict, size: tuple) -> Optional[Image.Image]:
+        """Render one game as a standalone card via the configured skin —
+        for vegas mode and previews. Tries render_vegas_card at the given
+        size, then the mode renderer on a card-sized canvas. Returns None
+        when no skin is active or the skin declined, so callers can use
+        their default rendering."""
+        skin = self._get_skin()
+        if skin is None or self._skin_failures >= 3:
+            return None
+        try:
+            from src.skin_system import skin_runtime
+            ctx = skin_runtime.build_context(self, game, size=size)
+            card = skin.render_vegas_card(ctx, dict(game))
+            if card is not None:
+                return card
+            ctx = skin_runtime.build_context(self, game, size=size)
+            render = getattr(skin, f"render_{self.SKIN_MODE}")
+            if render(ctx, dict(game)):
+                return ctx.canvas
+        except Exception:
+            # Card failures count toward the same 3-strike session disable
+            # as display failures — a skin broken for vegas shouldn't get
+            # to throw on every scroll tick forever.
+            self._skin_failures += 1
+            self.logger.error(
+                f"Skin '{self._resolve_skin_id()}' card render failed "
+                f"({self._skin_failures}/3)", exc_info=True)
+        return None
+
     def display(self, force_clear: bool = False) -> bool:
         """Common display method for all NCAA FB managers""" # Updated docstring
         if not self.is_enabled: # Check if module is enabled
@@ -229,7 +333,7 @@ class SportsCore(ABC):
             return False
 
         try:
-            self._draw_scorebug_layout(self.current_game, force_clear)
+            self._render_game(self.current_game, force_clear)
             # display_manager.update_display() should be called within subclass draw methods
             # or after calling display() in the main loop. Let's keep it out of the base display.
             return True
@@ -646,6 +750,8 @@ class SportsCore(ABC):
         pass
 
 class SportsUpcoming(SportsCore):
+    SKIN_MODE = "upcoming"
+
     def __init__(self, config: Dict[str, Any], display_manager: DisplayManager, cache_manager: CacheManager, logger: logging.Logger, sport_key: str):
         super().__init__(config, display_manager, cache_manager, logger, sport_key)
         self.upcoming_games = [] # Store all fetched upcoming games initially
@@ -973,7 +1079,7 @@ class SportsUpcoming(SportsCore):
                     self.logger.debug(f"Switched to game index {self.current_game_index}")
 
             if self.current_game:
-                self._draw_scorebug_layout(self.current_game, force_clear)
+                self._render_game(self.current_game, force_clear)
                 return True
             # update_display() is called within _draw_scorebug_layout for upcoming
             return False
@@ -984,6 +1090,7 @@ class SportsUpcoming(SportsCore):
 
 
 class SportsRecent(SportsCore):
+    SKIN_MODE = "recent"
 
     def __init__(self, config: Dict[str, Any], display_manager: DisplayManager, cache_manager: CacheManager, logger: logging.Logger, sport_key: str):
         super().__init__(config, display_manager, cache_manager, logger, sport_key)
@@ -1274,7 +1381,7 @@ class SportsRecent(SportsCore):
                     self.logger.debug(f"Switched to game index {self.current_game_index}")
 
             if self.current_game:
-                self._draw_scorebug_layout(self.current_game, force_clear)
+                self._render_game(self.current_game, force_clear)
                 return True
             # update_display() is called within _draw_scorebug_layout for recent
             return False

src/common/scroll_helper.py

@@ -110,20 +110,30 @@ class ScrollHelper:
         self.is_scrolling = False
         self.scroll_complete = False
         
-    def create_scrolling_image(self, content_items: list, 
+    def create_scrolling_image(self, content_items: list,
                              item_gap: int = 32,
-                             element_gap: int = 16) -> Image.Image:
+                             element_gap: int = 16,
+                             lead_gap: Optional[int] = None) -> Image.Image:
         """
         Create a wide image containing all content items for scrolling.
-        
+
         Args:
             content_items: List of PIL Images to include in scroll
             item_gap: Gap between different items
             element_gap: Gap between elements within an item
-            
+            lead_gap: Blank columns before the first item. Defaults to a full
+                display width, which makes a standalone ticker scroll in from
+                off-screen. Callers that loop many plugins back-to-back (Vegas
+                mode) pass a smaller value, since a full display width of black
+                reads as the panel being switched off at the start of every
+                cycle.
+
         Returns:
             PIL Image containing all content arranged horizontally
         """
+        if lead_gap is None:
+            lead_gap = self.display_width
+        lead_gap = max(0, int(lead_gap))
         if not content_items:
             # Create empty image if no content
             # Still set total_scroll_width to 0 to indicate no scrollable content
@@ -144,13 +154,13 @@ class ScrollHelper:
         total_width += element_gap * len(content_items)
         
         # Add initial gap before first item
-        total_width += self.display_width
-        
+        total_width += lead_gap
+
         # Create the full scrolling image
         full_image = Image.new('RGB', (total_width, self.display_height), (0, 0, 0))
-        
+
         # Position items
-        current_x = self.display_width  # Start with initial gap
+        current_x = lead_gap  # Start with initial gap
         
         for i, img in enumerate(content_items):
             # Paste the item image
@@ -338,13 +348,72 @@ class ScrollHelper:
         """
         if not self.cached_image or self.cached_array is None:
             return None
-        
-        # Use integer pixel positioning for high FPS scrolling (like stock ticker)
+
         start_x_int = int(self.scroll_position)
         end_x_int = start_x_int + self.display_width
-        
-        # Fast integer pixel path (no interpolation - high frame rate provides smoothness)
+
+        # Integer positioning quantises motion to whole pixels, so the number of
+        # distinct frames per second equals the scroll speed in px/s, no matter
+        # how fast the loop renders. At 50px/s and 78fps that made 36% of frames
+        # identical: the extra frames cost work and bought nothing. Blending
+        # between the two neighbouring positions gives motion at the frame rate
+        # instead of the step rate.
+        if self.sub_pixel_scrolling:
+            fractional = self.scroll_position - start_x_int
+            if fractional > 0.0:
+                return self._blend_visible_portion(start_x_int, fractional)
+
         return self._get_visible_portion_integer(start_x_int, end_x_int)
+
+    def _blend_visible_portion(self, start_x: int, fractional: float) -> Image.Image:
+        """
+        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
+        the pre-existing sub-pixel path was dead code — get_visible_portion never
+        consulted the flag, and the scipy fallback would not have interpolated
+        anyway.
+
+        Args:
+            start_x: Left column of the earlier of the two frames
+            fractional: How far between the two, in [0, 1)
+
+        Returns:
+            The blended frame
+        """
+        width = self.display_width
+        strip_width = self.cached_array.shape[1]
+
+        if start_x + width + 1 <= strip_width:
+            # Slice the backing array directly. Going via
+            # _get_visible_portion_integer would build two PIL images only for
+            # them to be converted straight back to arrays, which measured 15x
+            # the cost of the integer path.
+            near = self.cached_array[:, start_x:start_x + width]
+            far = self.cached_array[:, start_x + 1:start_x + 1 + width]
+        else:
+            # Close enough to the end that one of the slices wraps; let the
+            # integer path handle that and pay the conversion. Continuous mode
+            # extends the strip before reaching here, so this is the rare case.
+            near = np.asarray(
+                self._get_visible_portion_integer(start_x, start_x + width))
+            far = np.asarray(
+                self._get_visible_portion_integer(start_x + 1, start_x + 1 + width))
+
+        # Fixed-point rather than float32: integer multiply-add on uint16 is
+        # markedly faster than float maths on the Pi's ARM cores, and 8 bits of
+        # weight is finer than the panel can show.
+        weight = int(fractional * 256.0)
+        blended = (
+            (near.astype(np.uint16) * (256 - weight)
+             + far.astype(np.uint16) * weight) >> 8
+        ).astype(np.uint8)
+
+        return Image.frombytes(
+            'RGB', (width, self.display_height),
+            np.ascontiguousarray(blended).tobytes()
+        )
     
     def _get_visible_portion_integer(self, start_x: int, end_x: int) -> Image.Image:
         """Fast integer pixel extraction (no interpolation).
@@ -638,6 +707,128 @@ class ScrollHelper:
         """
         return self.scroll_complete
     
+    def append_content(self, content_items: list,
+                       item_gap: int = 32,
+                       element_gap: int = 0) -> bool:
+        """
+        Append items to the right of the existing strip, preserving scroll state.
+
+        Lets a caller keep one continuous strip instead of replacing it. Vegas
+        mode uses this so the next group of plugins scrolls in from the right
+        rather than the strip being swapped out underneath the viewer — a swap
+        shows as a flash and a hard cut to already-full-screen content.
+
+        ``scroll_position`` and ``total_distance_scrolled`` are untouched, so
+        motion continues uninterrupted; only the strip gets longer. Because
+        completion is measured against ``total_scroll_width``, extending the
+        strip also defers completion, which is the intent.
+
+        Args:
+            content_items: Images to append, in order
+            item_gap: Gap between appended items, and between the existing
+                content and the first appended item
+            element_gap: Extra gap after each item, mirroring
+                create_scrolling_image
+
+        Returns:
+            True if content was appended
+        """
+        if not content_items:
+            return False
+
+        if self.cached_image is None or self.cached_array is None:
+            # Nothing to extend yet — this is just the first build.
+            self.create_scrolling_image(
+                content_items, item_gap=item_gap, element_gap=element_gap, lead_gap=0)
+            return True
+
+        gap = max(0, item_gap)
+        addition_width = (
+            sum(img.width for img in content_items)
+            + gap * len(content_items)          # one leading gap per item
+            + element_gap * len(content_items)
+        )
+
+        addition = Image.new('RGB', (addition_width, self.display_height), (0, 0, 0))
+        x = 0
+        for img in content_items:
+            x += gap                            # separate from whatever precedes
+            addition.paste(img, (x, 0))
+            x += img.width + element_gap
+
+        # numpy concatenate then one conversion back, rather than allocating a
+        # full-width PIL image and pasting twice: the strip can be tens of
+        # thousands of columns wide and this runs on the render path.
+        self.cached_array = np.concatenate(
+            (self.cached_array, np.array(addition)), axis=1)
+        self.cached_image = Image.fromarray(self.cached_array)
+        self.total_scroll_width = self.cached_image.width
+        self.scroll_complete = False
+
+        self.logger.info(
+            "Appended %d item(s) (%dpx) to scroll strip: now %dpx, position %.0f",
+            len(content_items), addition_width, self.total_scroll_width,
+            self.scroll_position
+        )
+        return True
+
+    def drop_scrolled_prefix(self, keep_before: int = 0) -> int:
+        """
+        Discard columns that have already scrolled past, to bound memory.
+
+        A continuously extended strip would otherwise grow without limit. All
+        the positional state is shifted by the amount removed so the visible
+        frame and the completion arithmetic are unchanged:
+        ``total_distance_scrolled`` and ``total_scroll_width`` both shrink by the
+        same amount, preserving their difference.
+
+        Args:
+            keep_before: Columns to retain behind the current position, as a
+                safety margin against a caller reading slightly behind it
+
+        Returns:
+            Number of columns actually removed
+        """
+        if self.cached_image is None or self.cached_array is None:
+            return 0
+
+        # While the viewport wraps, get_visible_portion fills its right-hand side
+        # from the *head* of the strip, so trimming the head would change what
+        # is on screen. Continuous mode extends before ever reaching that state;
+        # refusing here keeps "trimming is invisible" true unconditionally.
+        if self.scroll_position + self.display_width > self.cached_image.width:
+            return 0
+
+        cut = int(self.scroll_position) - max(0, keep_before)
+        if cut <= 0:
+            return 0
+        # Never trim so far that the remaining strip is narrower than the
+        # viewport, or get_visible_portion has nothing to slice.
+        cut = min(cut, max(0, self.cached_image.width - self.display_width))
+        if cut <= 0:
+            return 0
+
+        # .copy() so the original buffer is released rather than kept alive by
+        # a numpy view.
+        self.cached_array = self.cached_array[:, cut:].copy()
+        self.cached_image = Image.fromarray(self.cached_array)
+        self.total_scroll_width = self.cached_image.width
+        self.scroll_position -= cut
+        self.total_distance_scrolled = max(0.0, self.total_distance_scrolled - cut)
+
+        self.logger.debug(
+            "Dropped %dpx of scrolled strip: now %dpx, position %.0f",
+            cut, self.total_scroll_width, self.scroll_position
+        )
+        return cut
+
+    def remaining_unscrolled(self) -> int:
+        """Columns of strip still to the right of the viewport."""
+        if self.cached_image is None:
+            return 0
+        return max(0, self.total_scroll_width - int(self.scroll_position)
+                   - self.display_width)
+
     def reset_scroll(self) -> None:
         """
         Reset scroll position to beginning.

src/display_controller.py

@@ -381,6 +381,10 @@ class DisplayController:
                 logger.debug("%d plugin(s) disabled in config", disabled_count)
 
             logger.info("Plugin system initialized in %.3f seconds", time.time() - plugin_time)
+            # Parallel loading appends modes in load-completion order, which
+            # varies between restarts; apply the user's configured rotation
+            # order (no-op when not configured).
+            self._apply_plugin_rotation_order()
             logger.info("Total available modes: %d", len(self.available_modes))
             logger.info("Available modes: %s", self.available_modes)
             
@@ -1133,6 +1137,29 @@ class DisplayController:
         remaining = self.on_demand_expires_at - time.time()
         return max(0.0, remaining)
 
+    def _publish_current_mode_state(self) -> None:
+        """Publish the currently active display mode/plugin to cache for the web UI."""
+        try:
+            state = {
+                'mode': self.current_display_mode,
+                'plugin_id': self.mode_to_plugin_id.get(self.current_display_mode),
+                'mode_index': self.current_mode_index,
+                'total_modes': len(self.available_modes),
+                'on_demand_active': self.on_demand_active,
+                'is_display_active': self.is_display_active,
+                'last_updated': time.time(),
+            }
+            self.cache_manager.set('display_current_state', state)
+            self._last_published_mode = self.current_display_mode
+        except (OSError, RuntimeError, ValueError, TypeError) as err:
+            logger.error("Failed to publish current display state: %s", err, exc_info=True)
+
+    def _publish_current_mode_state_if_changed(self) -> None:
+        """Publish current mode state only when it actually changed, to avoid
+        writing to the shared cache on every render tick."""
+        if self.current_display_mode != getattr(self, '_last_published_mode', None):
+            self._publish_current_mode_state()
+
     def _publish_on_demand_state(self) -> None:
         """Publish current on-demand state to cache for external consumers."""
         try:
@@ -1652,6 +1679,7 @@ class DisplayController:
             logger.info("Starting display with cached data (fast startup mode)")
             self.current_display_mode = self.available_modes[self.current_mode_index] if self.available_modes else 'none'
             logger.info(f"Initial mode set to: {self.current_display_mode} (index: {self.current_mode_index}, total modes: {len(self.available_modes)})")
+            self._publish_current_mode_state()
             
             while True:
                 # Apply plugin enable/disable edits saved via the web UI. The
@@ -1712,9 +1740,11 @@ class DisplayController:
                         logger.debug(f"Error clearing display when inactive: {e}")
                     
                     logger.info(f"Display not active (is_display_active={self.is_display_active}), sleeping...")
+                    self._publish_current_mode_state()
                     self._sleep_with_plugin_updates(60)
                     continue
                 
+                self._publish_current_mode_state_if_changed()
                 logger.debug("Display active, processing mode: %s", self.current_display_mode)
                 
                 # Plugins update on their own schedules - no forced sync updates needed
@@ -2843,11 +2873,52 @@ class DisplayController:
             except Exception as e:
                 logger.error("Plugin reconcile: error enabling %s: %s", plugin_id, e, exc_info=True)
 
+        # Newly enabled plugins were appended at the end; put them in the
+        # configured rotation slot before resyncing the index.
+        self._apply_plugin_rotation_order()
         self._resync_mode_index_after_change(previous_mode)
-        logger.info("Plugin reconcile complete: +%s -%s (%d modes)",
+        logger.info("[DisplayController] Plugin reconcile complete: +%s -%s (%d modes)",
                     sorted(to_add), sorted(to_remove), len(self.available_modes))
         return True
 
+    def _apply_plugin_rotation_order(self) -> None:
+        """Reorder available_modes to follow display.plugin_rotation_order.
+
+        The configured value is a list of plugin ids; their modes rotate in
+        that order (each plugin's own modes keep their declared order), with
+        any enabled-but-unlisted plugins appended afterwards in their current
+        relative order. An empty/missing list leaves available_modes exactly
+        as built (today's behavior). Mirrors vegas_mode/config.py's
+        get_ordered_plugins() semantics for the primary rotation.
+        """
+        configured = (self.config.get("display", {}) or {}).get("plugin_rotation_order", []) or []
+        # Defensive: hand-edited or migrated configs may hold a non-list or
+        # non-string entries; keep the existing rotation rather than applying
+        # a garbage order.
+        if not isinstance(configured, list):
+            logger.warning("[DisplayController] Ignoring invalid plugin_rotation_order (not a list): %r",
+                           type(configured).__name__)
+            return
+        configured = [p for p in configured if isinstance(p, str)]
+        if not configured or not self.available_modes:
+            return
+
+        ordered_ids = [p for p in configured if p in self.plugin_display_modes]
+        new_modes: List[str] = []
+        for plugin_id in ordered_ids:
+            for mode in self.plugin_display_modes[plugin_id]:
+                if mode in self.available_modes and mode not in new_modes:
+                    new_modes.append(mode)
+        # Unlisted plugins' modes (and any mode not attributable to a plugin)
+        # follow in their existing relative order.
+        for mode in self.available_modes:
+            if mode not in new_modes:
+                new_modes.append(mode)
+        if new_modes != self.available_modes:
+            self.available_modes = new_modes
+            logger.info("[DisplayController] Applied plugin rotation order %s -> modes: %s",
+                        configured, self.available_modes)
+
     def _resync_mode_index_after_change(self, previous_mode: Optional[str]) -> None:
         """Clamp rotation state after available_modes changed. Stays on the
         previous mode if it survived, otherwise restarts cleanly within range."""

src/display_manager.py

@@ -186,8 +186,14 @@ class DisplayManager:
         self.config = config or {}
         self._force_fallback = force_fallback
         self._suppress_test_pattern = suppress_test_pattern
-        # When True, update_display() and clear() skip hardware writes (used during off-screen content capture)
-        self._capture_mode_active = False
+        # Per-thread capture state. update_display() and clear() skip hardware
+        # writes while the *calling* thread is capturing content off-screen.
+        #
+        # Thread-local rather than a plain flag because Vegas mode prepares
+        # upcoming content on a background thread: a shared flag set there would
+        # suppress the render loop's own frame pushes for the duration, freezing
+        # the panel exactly when the point was to avoid a freeze.
+        self._capture_state = threading.local()
         # Double-sided mode state (resolved in _setup_matrix). When disabled,
         # the logical image is blitted to the matrix unchanged.
         self._double_sided = None  # dict {copies, axis, logical_width, logical_height} or None
@@ -520,6 +526,15 @@ class DisplayManager:
         except Exception as e:
             logger.error(f"Error drawing test pattern: {e}", exc_info=True)
 
+    @property
+    def _capture_mode_active(self) -> bool:
+        """True while the calling thread is capturing content off-screen."""
+        return getattr(self._capture_state, 'active', False)
+
+    @_capture_mode_active.setter
+    def _capture_mode_active(self, value: bool) -> None:
+        self._capture_state.active = bool(value)
+
     @contextmanager
     def capture_mode(self):
         """Suppress hardware output during off-screen content capture.
@@ -536,6 +551,59 @@ class DisplayManager:
         finally:
             self._capture_mode_active = False
 
+    @contextmanager
+    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
+        ``width``/``height`` properties, which defer to it), 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
+        100% width — those need the plugin to make different layout decisions.
+
+        Vegas mode uses this so a plugin can occupy a fraction of a wide panel
+        and still look deliberately composed. Reuses the same _LogicalMatrix
+        indirection that double-sided mode relies on, so plugins see a
+        consistent size from every accessor.
+
+        Only meaningful inside :meth:`capture_mode` — this swaps the shared
+        image buffer, so the render loop must not be writing to it concurrently.
+
+        Args:
+            width: Logical width to report, clamped to at least 1 and to the
+                real panel width (a larger canvas would overflow the hardware).
+            height: Logical height, defaulting to the current height.
+        """
+        real_matrix = self.matrix
+        prev_image = getattr(self, 'image', None)
+        prev_draw = getattr(self, 'draw', None)
+
+        current_w = self.width
+        current_h = self.height
+        target_w = max(1, min(int(width), current_w))
+        target_h = max(1, min(int(height) if height else current_h, current_h))
+
+        if target_w == current_w and target_h == current_h:
+            # Nothing to do; avoid pointless wrapping and buffer churn.
+            yield
+            return
+
+        try:
+            if real_matrix is not None:
+                self.matrix = _LogicalMatrix(real_matrix, target_w, target_h)
+            # With no hardware, the width/height properties fall through to
+            # self.image, so swapping the buffer below is enough on its own.
+            self.image = Image.new('RGB', (target_w, target_h))
+            self.draw = ImageDraw.Draw(self.image)
+            yield
+        finally:
+            self.matrix = real_matrix
+            if prev_image is not None:
+                self.image = prev_image
+            if prev_draw is not None:
+                self.draw = prev_draw
+
     def _composite_double_sided(self):
         """Tile the logical screen across the full physical chain.
 

src/logging_config.py

@@ -139,23 +139,41 @@ def setup_logging(
             sys.stderr.write(f"Warning: Could not set up file logging to {log_file}: {e}\n")
 
 
-def get_logger(name: str, plugin_id: Optional[str] = None) -> logging.Logger:
+class PluginLoggerAdapter(logging.LoggerAdapter):
+    """LoggerAdapter that stamps every record with its plugin_id.
+
+    A plain `logging.Logger` attribute (the old approach) is never copied
+    onto individual `LogRecord`s, so `ContextualFormatter`/`StructuredFormatter`
+    only ever saw `plugin_id` on calls that explicitly passed
+    `extra={'plugin_id': ...}` (i.e. `log_with_context`). This adapter injects
+    it into `extra` on every call, so `self.logger.info(...)` in plugin code
+    is tagged automatically.
+    """
+
+    def process(self, msg, kwargs):
+        extra = dict(kwargs.get('extra') or {})
+        extra.setdefault('plugin_id', self.extra.get('plugin_id'))
+        kwargs['extra'] = extra
+        return msg, kwargs
+
+
+def get_logger(name: str, plugin_id: Optional[str] = None):
     """
     Get a logger with consistent configuration.
-    
+
     Args:
         name: Logger name (typically __name__)
         plugin_id: Optional plugin ID for automatic context
-        
+
     Returns:
-        Configured logger instance
+        Configured logger instance (or a PluginLoggerAdapter when plugin_id
+        is given, which supports the same .debug/.info/.warning/.error API)
     """
     logger = logging.getLogger(name)
-    
-    # Add plugin_id as attribute for formatters
+
     if plugin_id:
-        logger.plugin_id = plugin_id
-    
+        return PluginLoggerAdapter(logger, {'plugin_id': plugin_id})
+
     return logger
 
 

src/plugin_system/base_plugin.py

@@ -86,7 +86,9 @@ class BasePlugin(ABC):
         self.display_manager: Any = display_manager
         self.cache_manager: Any = cache_manager
         self.plugin_manager: Any = plugin_manager
-        self.logger: logging.Logger = get_logger(f"plugin.{plugin_id}", plugin_id=plugin_id)
+        # get_logger returns a PluginLoggerAdapter here (plugin_id given), which
+        # stamps every record with plugin_id so it survives into formatted output.
+        self.logger = get_logger(f"plugin.{plugin_id}", plugin_id=plugin_id)
         self.enabled: bool = config.get("enabled", True)
 
         self.logger.info("Initialized plugin: %s", plugin_id)
@@ -143,6 +145,77 @@ class BasePlugin(ABC):
         """
         raise NotImplementedError("Plugins must implement display()")
 
+    # -------------------------------------------------------------------------
+    # Global (whole-device) configuration
+    # -------------------------------------------------------------------------
+    @property
+    def global_config(self) -> Dict[str, Any]:
+        """
+        The full LEDMatrix configuration, for reading device-wide settings.
+
+        ``self.config`` is only this plugin's own slice, so cross-cutting
+        settings — ``target_fps``, ``timezone``, ``location`` — were previously
+        unreachable from a plugin without reaching into a manager by hand.
+
+        Resolution order mirrors the timezone helpers the sports plugins
+        already ship: ``plugin_manager.config_manager`` first (the cores that
+        hang it there), then ``cache_manager.config_manager``. Returns ``{}``
+        when neither is available, so callers can use plain ``.get()`` without
+        guarding, and a plugin on a core that predates this property still
+        loads — ``getattr(self, 'global_config', {})`` simply yields the
+        default.
+
+        Treat as read-only: the returned dict is the live config the core is
+        using, so mutating it edits every other consumer's view and can be
+        persisted back to disk.
+
+        Assignment is still allowed and wins over the resolved value. Several
+        shipped plugins (news, stock-news, ledmatrix-stocks, ledmatrix-
+        elections, ledmatrix-leaderboard, nfl-draft) set
+        ``self.global_config`` to their own ``config['global']`` sub-dict; a
+        property without a setter would raise AttributeError and stop those
+        plugins loading.
+
+        Example:
+            fps = self.global_config.get('target_fps')
+        """
+        override = getattr(self, '_global_config_override', None)
+        if override is not None:
+            return override
+        for owner in (self.plugin_manager, self.cache_manager):
+            config_manager = getattr(owner, 'config_manager', None)
+            if config_manager is None:
+                continue
+            try:
+                config = config_manager.get_config()
+            except Exception:
+                # A broken or unreadable config must never stop a plugin from
+                # loading; fall through to the next source, then to {}.
+                self.logger.debug(
+                    "Could not read global config from %s",
+                    type(owner).__name__, exc_info=True,
+                )
+                continue
+            # Only a real mapping is usable: callers do .get() on this and feed
+            # the result to numeric code, so handing back whatever a stub or a
+            # half-built manager returned would fail later and further away.
+            #
+            # An empty dict is treated as "nothing here yet" rather than a
+            # valid answer, so resolution continues to the next source. Both
+            # managers default to the same config/config.json, so falling
+            # through cannot pick up a different file's settings -- but it does
+            # rescue the case where the first manager simply hasn't loaded yet,
+            # which would otherwise return {} and silently disable every
+            # setting read through this property.
+            if isinstance(config, dict) and config:
+                return config
+        return {}
+
+    @global_config.setter
+    def global_config(self, value: Dict[str, Any]) -> None:
+        """Let a plugin substitute its own view (see the getter's docstring)."""
+        self._global_config_override = value
+
     # -------------------------------------------------------------------------
     # Adaptive layout support (opt-in)
     # -------------------------------------------------------------------------
@@ -503,6 +576,40 @@ class BasePlugin(ABC):
     # -------------------------------------------------------------------------
     # Vegas scroll mode support
     # -------------------------------------------------------------------------
+    def get_vegas_render_width(self) -> int:
+        """
+        Width the Vegas ticker wants this plugin's content to occupy.
+
+        On a wide panel a layout built to fill the screen reads as sparse in a
+        ticker — a forecast spread over five columns, a progress bar drawn at
+        100% width, a stat block with the panel's whole width between its
+        elements. Vegas asks for a narrower render so the plugin can choose a
+        tighter arrangement instead of being cropped afterwards.
+
+        Vegas also narrows ``display_manager`` for the duration of the call, so
+        a plugin that already sizes itself from ``matrix.width`` needs no
+        changes. Read this only when you size content some other way.
+
+        Controlled by the plugin's own ``vegas_width_pct`` config value, else
+        the global ``display.vegas_scroll.render_width_pct``.
+
+        Returns:
+            Target width in pixels. Outside a Vegas content request, the full
+            display width.
+        """
+        requested = getattr(self, '_vegas_render_width', None)
+        if isinstance(requested, int) and requested > 0:
+            return requested
+
+        display_manager = getattr(self, 'display_manager', None)
+        matrix = getattr(display_manager, 'matrix', None)
+        if matrix is not None and getattr(matrix, 'width', None):
+            return int(matrix.width)
+        width = getattr(display_manager, 'width', None)
+        if callable(width):
+            width = width()
+        return int(width) if width else 128
+
     def get_vegas_content(self) -> Optional[Any]:
         """
         Get content for Vegas-style continuous scroll mode.

src/plugin_system/schema_manager.py

@@ -284,6 +284,19 @@ class SchemaManager:
                     "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"
                 }
             }
             
@@ -354,6 +367,53 @@ class SchemaManager:
             self.logger.error(error_msg)
             return False, [error_msg]
     
+    def inject_skin_selector(self, schema: Dict[str, Any], plugin_id: str,
+                             current_value: Any = None) -> Dict[str, Any]:
+        """Return a copy of a plugin's schema with a "skin" dropdown added
+        when installed skins target this plugin (docs/SKIN_SYSTEM.md).
+
+        Serve-time only — validation never sees this enum, so a config
+        referencing an uninstalled skin stays valid (rendering falls back
+        to the built-in layout). The currently-configured value is always
+        included in the enum for the same reason: the dropdown must be able
+        to display a selection whose skin was removed.
+        """
+        # A per-mode mapping ({"live": ..., "recent": ...}) can't be edited
+        # through a string dropdown — injecting one would let the form save
+        # a string over the mapping. Leave the schema alone; per-mode users
+        # edit via the raw JSON config editor.
+        if isinstance(current_value, dict):
+            return schema
+
+        try:
+            from src.skin_system import skin_runtime
+            matching = skin_runtime.skins_for_plugin(plugin_id)
+        except Exception as e:
+            self.logger.debug(f"Skin discovery failed for {plugin_id}: {e}")
+            return schema
+
+        choices = sorted(matching.keys())
+        if isinstance(current_value, str) and current_value and \
+                current_value != "built-in" and current_value not in choices:
+            choices.append(current_value)
+        if not choices:
+            return schema
+
+        enhanced = copy.deepcopy(schema)
+        enhanced.setdefault("properties", {})
+        if "skin" not in enhanced["properties"]:
+            names = {sid: (matching.get(sid, {}).get("name") or sid) for sid in choices}
+            enhanced["properties"]["skin"] = {
+                "type": "string",
+                "title": "Visual Skin",
+                "description": "Replace this scoreboard's look with an installed skin "
+                               "(data, scheduling, and vegas mode are unaffected)",
+                "enum": ["built-in", *choices],
+                "enumNames": ["Built-in", *(names[sid] for sid in choices)],
+                "default": "built-in"
+            }
+        return enhanced
+
     def _format_validation_error(self, error: ValidationError, plugin_id: Optional[str] = None) -> str:
         """
         Format a validation error into a readable message.

src/plugin_system/store_manager.py

@@ -1214,6 +1214,11 @@ class PluginStoreManager:
             self.logger.error(f"Plugin not found in registry: {plugin_id}")
             return False
 
+        # Visual skins share the registry but install to skins/, not to a
+        # plugin directory (docs/SKIN_SYSTEM.md)
+        if (plugin_info.get('type') or 'plugin') == 'skin':
+            return self._install_skin_from_info(plugin_id, plugin_info, branch)
+
         repo_url = plugin_info.get('repo')
         if not repo_url:
             self.logger.error(f"Plugin {plugin_id} missing repository URL")
@@ -2254,19 +2259,171 @@ class PluginStoreManager:
         
         return None
     
+    _SKIN_ID_PATTERN = re.compile(r'^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$')
+
+    def _resolve_skin_target(self, skin_id: str) -> Optional[Path]:
+        """Validate an externally-supplied skin id and resolve it to a path
+        strictly inside the skins directory. Returns None (after logging)
+        for ids that are malformed or would escape the directory — registry
+        entries and manifests are external input and must not be able to
+        write or delete outside skins/."""
+        from src.skin_system import skin_runtime
+
+        if not isinstance(skin_id, str) or not self._SKIN_ID_PATTERN.match(skin_id) \
+                or '..' in skin_id:
+            self.logger.error(f"Rejecting unsafe skin id: {skin_id!r}")
+            return None
+        skins_dir = skin_runtime.get_skins_directory().resolve()
+        target = (skins_dir / skin_id).resolve()
+        if target.parent != skins_dir:
+            self.logger.error(f"Skin id {skin_id!r} escapes the skins directory; rejecting")
+            return None
+        return target
+
+    def _install_skin_from_info(self, skin_id: str, skin_info: Dict,
+                                branch: Optional[str] = None) -> bool:
+        """Install a registry entry of type "skin" into skins/<id>/.
+
+        Reuses the plugin download machinery (git / monorepo zip / archive)
+        but validates skin.json instead of manifest.json and never installs
+        dependencies — skins are render-only (stdlib + PIL + the provided
+        SkinContext), which is also what keeps them safe to iterate on.
+
+        Downloads into a staging directory and validates there; the
+        existing installation is only replaced after the new one passes,
+        so a failed download or bad manifest can't destroy a working skin.
+        """
+        from src.skin_system import skin_runtime
+        from src.skin_system.skin_base import SKIN_API_VERSION
+
+        repo_url = skin_info.get('repo')
+        if not repo_url:
+            self.logger.error(f"Skin {skin_id} missing repository URL")
+            return False
+
+        target = self._resolve_skin_target(skin_id)
+        if target is None:
+            return False
+        skins_dir = target.parent
+        skins_dir.mkdir(parents=True, exist_ok=True)
+        # Leading "_" keeps staging invisible to skin discovery
+        staging = skins_dir / f"_staging-{skin_id}"
+        if staging.exists() and not self._safe_remove_directory(staging):
+            return False
+
+        subpath = skin_info.get('plugin_path')
+        branch_candidates = self._distinct_sequence([
+            branch,
+            skin_info.get('branch'),
+            skin_info.get('default_branch'),
+            skin_info.get('last_commit_branch'),
+            'main',
+            'master'
+        ])
+
+        try:
+            branch_used = None
+            if subpath:
+                for candidate in branch_candidates:
+                    download_url = f"{repo_url}/archive/refs/heads/{candidate}.zip"
+                    if self._install_from_monorepo(download_url, subpath, staging):
+                        branch_used = candidate
+                        break
+            else:
+                branch_used = self._install_via_git(repo_url, staging, branch_candidates)
+                if branch_used is None and not staging.exists():
+                    for candidate in branch_candidates:
+                        download_url = f"{repo_url}/archive/refs/heads/{candidate}.zip"
+                        if self._install_via_download(download_url, staging):
+                            branch_used = candidate
+                            break
+
+            if branch_used is None and not staging.exists():
+                self.logger.error(f"Failed to install skin {skin_id} via git or archive download")
+                return False
+
+            try:
+                with open(staging / 'skin.json', 'r', encoding='utf-8') as f:
+                    manifest = json.load(f)
+            except (OSError, json.JSONDecodeError) as e:
+                self.logger.error(f"Skin {skin_id} has no valid skin.json: {e}")
+                return False
+
+            missing = [k for k in ('id', 'name', 'version', 'skin_api_version', 'class_name')
+                       if not manifest.get(k)]
+            if missing:
+                self.logger.error(f"Skin {skin_id} manifest missing fields: {missing}")
+                return False
+
+            # Unlike plugins, a mismatched id is rejected rather than
+            # renamed: the manifest id is external input, and the registry
+            # id is what the user asked to install.
+            if manifest['id'] != skin_id:
+                self.logger.error(
+                    f"Skin manifest id {manifest['id']!r} doesn't match registry id "
+                    f"{skin_id!r}; not installing")
+                return False
+
+            def _api_major(v):
+                try:
+                    return int(str(v).split('.')[0])
+                except (ValueError, IndexError):
+                    return None
+
+            if _api_major(manifest['skin_api_version']) != _api_major(SKIN_API_VERSION):
+                self.logger.error(
+                    f"Skin {skin_id} targets skin API {manifest['skin_api_version']} but this "
+                    f"LEDMatrix provides {SKIN_API_VERSION}; not installing")
+                return False
+
+            # Validated — swap into place
+            if target.exists() and not self._safe_remove_directory(target):
+                self.logger.error(f"Could not replace existing skin directory: {target}")
+                return False
+            shutil.move(str(staging), str(target))
+            skin_runtime.discover_skins(force_refresh=True)
+            self.logger.info(f"Successfully installed skin: {skin_id} (branch: {branch_used})")
+            return True
+        finally:
+            if staging.exists():
+                self._safe_remove_directory(staging)
+
+    def uninstall_skin(self, skin_id: str) -> bool:
+        """Remove an installed skin. Plugin configs referencing it keep
+        validating; rendering falls back to the built-in layout."""
+        from src.skin_system import skin_runtime
+
+        target = self._resolve_skin_target(skin_id)
+        if target is None:
+            return False
+        if not target.exists():
+            self.logger.info(f"Skin {skin_id} not found (already uninstalled)")
+            return True
+        if self._safe_remove_directory(target):
+            skin_runtime.discover_skins(force_refresh=True)
+            self.logger.info(f"Successfully uninstalled skin: {skin_id}")
+            return True
+        return False
+
     def uninstall_plugin(self, plugin_id: str) -> bool:
         """
         Uninstall a plugin by removing its directory.
-        
+
         Args:
             plugin_id: Plugin identifier
-            
+
         Returns:
             True if uninstalled successfully (or already not installed)
         """
         plugin_path = self._find_plugin_path(plugin_id)
-        
+
         if plugin_path is None or not plugin_path.exists():
+            # A skin id passed to the plugin uninstall path (the store UI
+            # uses one uninstall flow) removes the skin instead
+            skin_target = self._resolve_skin_target(plugin_id) \
+                if self._SKIN_ID_PATTERN.match(str(plugin_id)) else None
+            if skin_target is not None and skin_target.exists():
+                return self.uninstall_skin(plugin_id)
             self.logger.info(f"Plugin {plugin_id} not found (already uninstalled)")
             return True  # Already uninstalled, consider this success
         

src/plugin_system/testing/visual_display_manager.py

@@ -15,6 +15,7 @@ PIL Image canvas and draws text using the actual project fonts.
 import math
 import os
 import time
+from contextlib import contextmanager
 from pathlib import Path
 from typing import Any, List, Optional, Tuple
 
@@ -62,6 +63,9 @@ class VisualTestDisplayManager:
         # Matrix proxy (plugins access display_manager.matrix.width/height)
         self.matrix = _MatrixProxy(width, height)
 
+        # Set while inside capture_mode(); mirrors DisplayManager's flag.
+        self._capture_mode_active = False
+
         # Scrolling state (interface compat, no-op)
         self._scrolling_state = {
             'is_scrolling': False,
@@ -174,6 +178,50 @@ class VisualTestDisplayManager:
         """No-op for hardware; marks that display was updated."""
         self.update_called = True
 
+    @contextmanager
+    def render_size(self, width: int, height: Optional[int] = None):
+        """
+        Interface parity with DisplayManager.render_size().
+
+        Vegas mode narrows the canvas so plugins lay out compactly instead of
+        being cropped. The harness must offer the same context or that path
+        cannot be exercised offline — and because the adapter catches broadly,
+        a missing method shows up as "no content" rather than an error.
+        """
+        prev_image = self.image
+        prev_draw = self.draw
+        prev_w, prev_h = self._width, self._height
+
+        target_w = max(1, min(int(width), prev_w))
+        target_h = max(1, min(int(height) if height else prev_h, prev_h))
+
+        try:
+            self._width, self._height = target_w, target_h
+            self.matrix = _MatrixProxy(target_w, target_h)
+            self.image = Image.new('RGB', (target_w, target_h), (0, 0, 0))
+            self.draw = ImageDraw.Draw(self.image)
+            yield
+        finally:
+            self._width, self._height = prev_w, prev_h
+            self.matrix = _MatrixProxy(prev_w, prev_h)
+            self.image = prev_image
+            self.draw = prev_draw
+
+    @contextmanager
+    def capture_mode(self):
+        """
+        Interface parity with DisplayManager.capture_mode().
+
+        There is no hardware to suppress here, but Vegas mode's PluginAdapter
+        wraps every off-screen content fetch in this context, so the harness
+        must provide it for that code path to be exercisable in tests.
+        """
+        self._capture_mode_active = True
+        try:
+            yield
+        finally:
+            self._capture_mode_active = False
+
     def draw_text(self, text: str, x: Optional[int] = None, y: Optional[int] = None,
                   color: Tuple[int, int, int] = (255, 255, 255), small_font: bool = False,
                   font: Optional[Any] = None, centered: bool = False) -> None:

src/skin_system/__init__.py

@@ -0,0 +1,31 @@
+"""
+Skin system: user-installable visual overlays for sports scoreboards.
+
+A skin replaces only the rendering of a scoreboard (live / recent /
+upcoming) while the host plugin keeps doing data fetching, scheduling,
+caching, live priority, and vegas mode. See docs/SKIN_SYSTEM.md.
+"""
+
+from src.skin_system.skin_base import (
+    SKIN_API_VERSION,
+    VIEW_MODEL_VERSION,
+    ScoreboardSkin,
+    SkinContext,
+)
+from src.skin_system.skin_runtime import (
+    build_context,
+    discover_skins,
+    get_skins_directory,
+    load_skin,
+)
+
+__all__ = [
+    "SKIN_API_VERSION",
+    "VIEW_MODEL_VERSION",
+    "ScoreboardSkin",
+    "SkinContext",
+    "build_context",
+    "discover_skins",
+    "get_skins_directory",
+    "load_skin",
+]

src/skin_system/fixtures/baseball_live.json

@@ -0,0 +1,39 @@
+{
+  "id": "401570001",
+  "game_time": "7:05PM",
+  "game_date": "Jul 16th",
+  "start_time_utc": "2026-07-16T23:05:00+00:00",
+  "status_text": "Bot 7th",
+  "is_live": true,
+  "is_final": false,
+  "is_upcoming": false,
+  "is_halftime": false,
+  "is_period_break": false,
+  "home_abbr": "LAD",
+  "home_id": "19",
+  "home_score": "5",
+  "home_logo_path": "src/skin_system/fixtures/placeholder_home.png",
+  "home_logo_url": null,
+  "home_record": "58-33",
+  "away_abbr": "SF",
+  "away_id": "26",
+  "away_score": "3",
+  "away_logo_path": "src/skin_system/fixtures/placeholder_away.png",
+  "away_logo_url": null,
+  "away_record": "49-42",
+  "is_within_window": true,
+  "status": "STATUS_IN_PROGRESS",
+  "status_state": "in",
+  "inning": 7,
+  "inning_half": "bottom",
+  "balls": 3,
+  "strikes": 2,
+  "outs": 2,
+  "bases_occupied": [
+    true,
+    true,
+    true
+  ],
+  "start_time": "2026-07-16T23:05:00Z",
+  "series_summary": "LAD leads 2-1"
+}

src/skin_system/fixtures/baseball_recent.json

@@ -0,0 +1,39 @@
+{
+  "id": "401570001",
+  "game_time": "7:05PM",
+  "game_date": "Jul 16th",
+  "start_time_utc": "2026-07-16T23:05:00+00:00",
+  "status_text": "Final",
+  "is_live": false,
+  "is_final": true,
+  "is_upcoming": false,
+  "is_halftime": false,
+  "is_period_break": false,
+  "home_abbr": "LAD",
+  "home_id": "19",
+  "home_score": "5",
+  "home_logo_path": "src/skin_system/fixtures/placeholder_home.png",
+  "home_logo_url": null,
+  "home_record": "58-33",
+  "away_abbr": "SF",
+  "away_id": "26",
+  "away_score": "3",
+  "away_logo_path": "src/skin_system/fixtures/placeholder_away.png",
+  "away_logo_url": null,
+  "away_record": "49-42",
+  "is_within_window": true,
+  "status": "STATUS_FINAL",
+  "status_state": "post",
+  "inning": 9,
+  "inning_half": "top",
+  "balls": 0,
+  "strikes": 0,
+  "outs": 3,
+  "bases_occupied": [
+    false,
+    false,
+    false
+  ],
+  "start_time": "2026-07-16T23:05:00Z",
+  "series_summary": "Series tied 2-2"
+}

src/skin_system/fixtures/baseball_upcoming.json

@@ -0,0 +1,39 @@
+{
+  "id": "401570001",
+  "game_time": "7:05PM",
+  "game_date": "Jul 16th",
+  "start_time_utc": "2026-07-16T23:05:00+00:00",
+  "status_text": "7:05 PM",
+  "is_live": false,
+  "is_final": false,
+  "is_upcoming": true,
+  "is_halftime": false,
+  "is_period_break": false,
+  "home_abbr": "LAD",
+  "home_id": "19",
+  "home_score": "0",
+  "home_logo_path": "src/skin_system/fixtures/placeholder_home.png",
+  "home_logo_url": null,
+  "home_record": "58-33",
+  "away_abbr": "SF",
+  "away_id": "26",
+  "away_score": "0",
+  "away_logo_path": "src/skin_system/fixtures/placeholder_away.png",
+  "away_logo_url": null,
+  "away_record": "49-42",
+  "is_within_window": true,
+  "status": "STATUS_SCHEDULED",
+  "status_state": "pre",
+  "inning": 0,
+  "inning_half": "top",
+  "balls": 0,
+  "strikes": 0,
+  "outs": 0,
+  "bases_occupied": [
+    false,
+    false,
+    false
+  ],
+  "start_time": "2026-07-16T23:05:00Z",
+  "series_summary": ""
+}

src/skin_system/fixtures/basketball_live.json

@@ -0,0 +1,28 @@
+{
+  "id": "401570001",
+  "game_time": "7:05PM",
+  "game_date": "Jul 16th",
+  "start_time_utc": "2026-07-16T23:05:00+00:00",
+  "status_text": "Q4 2:34",
+  "is_live": true,
+  "is_final": false,
+  "is_upcoming": false,
+  "is_halftime": false,
+  "is_period_break": false,
+  "home_abbr": "OKC",
+  "home_id": "19",
+  "home_score": "5",
+  "home_logo_path": "src/skin_system/fixtures/placeholder_home.png",
+  "home_logo_url": null,
+  "home_record": "",
+  "away_abbr": "MIN",
+  "away_id": "26",
+  "away_score": "3",
+  "away_logo_path": "src/skin_system/fixtures/placeholder_away.png",
+  "away_logo_url": null,
+  "away_record": "",
+  "is_within_window": true,
+  "period": 4,
+  "period_text": "Q4",
+  "clock": "2:34"
+}

src/skin_system/fixtures/basketball_recent.json

@@ -0,0 +1,28 @@
+{
+  "id": "401570001",
+  "game_time": "7:05PM",
+  "game_date": "Jul 16th",
+  "start_time_utc": "2026-07-16T23:05:00+00:00",
+  "status_text": "Final",
+  "is_live": false,
+  "is_final": true,
+  "is_upcoming": false,
+  "is_halftime": false,
+  "is_period_break": false,
+  "home_abbr": "OKC",
+  "home_id": "19",
+  "home_score": "5",
+  "home_logo_path": "src/skin_system/fixtures/placeholder_home.png",
+  "home_logo_url": null,
+  "home_record": "",
+  "away_abbr": "MIN",
+  "away_id": "26",
+  "away_score": "3",
+  "away_logo_path": "src/skin_system/fixtures/placeholder_away.png",
+  "away_logo_url": null,
+  "away_record": "",
+  "is_within_window": true,
+  "period": 4,
+  "period_text": "Final",
+  "clock": "0:00"
+}

src/skin_system/fixtures/basketball_upcoming.json

@@ -0,0 +1,28 @@
+{
+  "id": "401570001",
+  "game_time": "7:05PM",
+  "game_date": "Jul 16th",
+  "start_time_utc": "2026-07-16T23:05:00+00:00",
+  "status_text": "7:05 PM",
+  "is_live": false,
+  "is_final": false,
+  "is_upcoming": true,
+  "is_halftime": false,
+  "is_period_break": false,
+  "home_abbr": "OKC",
+  "home_id": "19",
+  "home_score": "0",
+  "home_logo_path": "src/skin_system/fixtures/placeholder_home.png",
+  "home_logo_url": null,
+  "home_record": "",
+  "away_abbr": "MIN",
+  "away_id": "26",
+  "away_score": "0",
+  "away_logo_path": "src/skin_system/fixtures/placeholder_away.png",
+  "away_logo_url": null,
+  "away_record": "",
+  "is_within_window": true,
+  "period": 0,
+  "period_text": "",
+  "clock": "0:00"
+}

src/skin_system/fixtures/football_live.json

@@ -0,0 +1,36 @@
+{
+  "id": "401570001",
+  "game_time": "7:05PM",
+  "game_date": "Jul 16th",
+  "start_time_utc": "2026-07-16T23:05:00+00:00",
+  "status_text": "Q3 8:12",
+  "is_live": true,
+  "is_final": false,
+  "is_upcoming": false,
+  "is_halftime": false,
+  "is_period_break": false,
+  "home_abbr": "KC",
+  "home_id": "19",
+  "home_score": "21",
+  "home_logo_path": "src/skin_system/fixtures/placeholder_home.png",
+  "home_logo_url": null,
+  "home_record": "58-33",
+  "away_abbr": "BUF",
+  "away_id": "26",
+  "away_score": "17",
+  "away_logo_path": "src/skin_system/fixtures/placeholder_away.png",
+  "away_logo_url": null,
+  "away_record": "49-42",
+  "is_within_window": true,
+  "period": 3,
+  "period_text": "Q3",
+  "clock": "8:12",
+  "home_timeouts": 2,
+  "away_timeouts": 3,
+  "down_distance_text": "3rd & 4",
+  "down_distance_text_long": "3rd & 4 at KC 22",
+  "is_redzone": true,
+  "possession": "12",
+  "possession_indicator": "away",
+  "scoring_event": null
+}

src/skin_system/fixtures/football_recent.json

@@ -0,0 +1,36 @@
+{
+  "id": "401570001",
+  "game_time": "7:05PM",
+  "game_date": "Jul 16th",
+  "start_time_utc": "2026-07-16T23:05:00+00:00",
+  "status_text": "Final",
+  "is_live": false,
+  "is_final": true,
+  "is_upcoming": false,
+  "is_halftime": false,
+  "is_period_break": false,
+  "home_abbr": "KC",
+  "home_id": "19",
+  "home_score": "21",
+  "home_logo_path": "src/skin_system/fixtures/placeholder_home.png",
+  "home_logo_url": null,
+  "home_record": "58-33",
+  "away_abbr": "BUF",
+  "away_id": "26",
+  "away_score": "17",
+  "away_logo_path": "src/skin_system/fixtures/placeholder_away.png",
+  "away_logo_url": null,
+  "away_record": "49-42",
+  "is_within_window": true,
+  "period": 4,
+  "period_text": "Final",
+  "clock": "0:00",
+  "home_timeouts": 0,
+  "away_timeouts": 0,
+  "down_distance_text": "",
+  "down_distance_text_long": "",
+  "is_redzone": false,
+  "possession": null,
+  "possession_indicator": null,
+  "scoring_event": null
+}

src/skin_system/fixtures/football_upcoming.json

@@ -0,0 +1,36 @@
+{
+  "id": "401570001",
+  "game_time": "7:05PM",
+  "game_date": "Jul 16th",
+  "start_time_utc": "2026-07-16T23:05:00+00:00",
+  "status_text": "7:05 PM",
+  "is_live": false,
+  "is_final": false,
+  "is_upcoming": true,
+  "is_halftime": false,
+  "is_period_break": false,
+  "home_abbr": "KC",
+  "home_id": "19",
+  "home_score": "0",
+  "home_logo_path": "src/skin_system/fixtures/placeholder_home.png",
+  "home_logo_url": null,
+  "home_record": "58-33",
+  "away_abbr": "BUF",
+  "away_id": "26",
+  "away_score": "0",
+  "away_logo_path": "src/skin_system/fixtures/placeholder_away.png",
+  "away_logo_url": null,
+  "away_record": "49-42",
+  "is_within_window": true,
+  "period": 0,
+  "period_text": "",
+  "clock": "0:00",
+  "home_timeouts": 3,
+  "away_timeouts": 3,
+  "down_distance_text": "",
+  "down_distance_text_long": "",
+  "is_redzone": false,
+  "possession": null,
+  "possession_indicator": null,
+  "scoring_event": null
+}

src/skin_system/fixtures/hockey_live.json

@@ -0,0 +1,32 @@
+{
+  "id": "401570001",
+  "game_time": "7:05PM",
+  "game_date": "Jul 16th",
+  "start_time_utc": "2026-07-16T23:05:00+00:00",
+  "status_text": "P3 14:55",
+  "is_live": true,
+  "is_final": false,
+  "is_upcoming": false,
+  "is_halftime": false,
+  "is_period_break": false,
+  "home_abbr": "COL",
+  "home_id": "19",
+  "home_score": "2",
+  "home_logo_path": "src/skin_system/fixtures/placeholder_home.png",
+  "home_logo_url": null,
+  "home_record": "58-33",
+  "away_abbr": "VGK",
+  "away_id": "26",
+  "away_score": "2",
+  "away_logo_path": "src/skin_system/fixtures/placeholder_away.png",
+  "away_logo_url": null,
+  "away_record": "49-42",
+  "is_within_window": true,
+  "period": 3,
+  "period_text": "P3",
+  "clock": "14:55",
+  "power_play": true,
+  "penalties": [],
+  "home_shots": 27,
+  "away_shots": 31
+}

src/skin_system/fixtures/hockey_recent.json

@@ -0,0 +1,32 @@
+{
+  "id": "401570001",
+  "game_time": "7:05PM",
+  "game_date": "Jul 16th",
+  "start_time_utc": "2026-07-16T23:05:00+00:00",
+  "status_text": "Final/OT",
+  "is_live": false,
+  "is_final": true,
+  "is_upcoming": false,
+  "is_halftime": false,
+  "is_period_break": false,
+  "home_abbr": "COL",
+  "home_id": "19",
+  "home_score": "3",
+  "home_logo_path": "src/skin_system/fixtures/placeholder_home.png",
+  "home_logo_url": null,
+  "home_record": "58-33",
+  "away_abbr": "VGK",
+  "away_id": "26",
+  "away_score": "2",
+  "away_logo_path": "src/skin_system/fixtures/placeholder_away.png",
+  "away_logo_url": null,
+  "away_record": "49-42",
+  "is_within_window": true,
+  "period": 5,
+  "period_text": "Final/OT",
+  "clock": "0:00",
+  "power_play": false,
+  "penalties": [],
+  "home_shots": 35,
+  "away_shots": 33
+}

src/skin_system/fixtures/hockey_upcoming.json

@@ -0,0 +1,32 @@
+{
+  "id": "401570001",
+  "game_time": "7:05PM",
+  "game_date": "Jul 16th",
+  "start_time_utc": "2026-07-16T23:05:00+00:00",
+  "status_text": "7:05 PM",
+  "is_live": false,
+  "is_final": false,
+  "is_upcoming": true,
+  "is_halftime": false,
+  "is_period_break": false,
+  "home_abbr": "COL",
+  "home_id": "19",
+  "home_score": "0",
+  "home_logo_path": "src/skin_system/fixtures/placeholder_home.png",
+  "home_logo_url": null,
+  "home_record": "58-33",
+  "away_abbr": "VGK",
+  "away_id": "26",
+  "away_score": "0",
+  "away_logo_path": "src/skin_system/fixtures/placeholder_away.png",
+  "away_logo_url": null,
+  "away_record": "49-42",
+  "is_within_window": true,
+  "period": 0,
+  "period_text": "",
+  "clock": "0:00",
+  "power_play": false,
+  "penalties": [],
+  "home_shots": 0,
+  "away_shots": 0
+}

src/skin_system/skin_base.py

@@ -0,0 +1,171 @@
+"""
+Skin API: the classes a skin author works with.
+
+A skin is a directory under skins/<skin-id>/ containing a skin.json
+manifest and a Python module exposing a ScoreboardSkin subclass. The
+host (a sports scoreboard's base classes) builds a SkinContext per
+render and calls render_live / render_recent / render_upcoming with the
+game view model. The skin draws onto ctx.canvas and returns True; the
+host composites the canvas onto the display. A skin never talks to the
+display, the network, or the plugin directly.
+
+Skin API Version: 1.0.0
+View Model Version: 1.0
+"""
+
+from abc import ABC
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Optional, Tuple, Union
+
+from PIL import Image, ImageDraw
+
+try:
+    import freetype
+except ImportError:  # pragma: no cover - freetype ships with the project deps
+    freetype = None
+
+from src.adaptive_layout import FitResult, LayoutContext, Region
+
+# Major must match a skin manifest's skin_api_version major or the skin
+# is refused at load time (renames/removals bump major; additions minor).
+SKIN_API_VERSION = "1.0.0"
+
+# Version of the guaranteed `game` dict keys (see docs/CREATING_SKINS.md).
+VIEW_MODEL_VERSION = "1.0"
+
+
+def _draw_bdf_text_on(draw: ImageDraw.ImageDraw, text: str, x: int, y: int,
+                      color: Tuple[int, int, int], face: Any,
+                      clip_w: int, clip_h: int) -> None:
+    """Render a freetype BDF face glyph-by-glyph onto an arbitrary canvas.
+
+    DisplayManager._draw_bdf_text only draws onto the panel image; skins
+    draw onto their own canvas, so the fitted-font path (fit_text can
+    return freetype faces) needs this standalone equivalent.
+    """
+    try:
+        ascender_px = face.size.ascender >> 6
+    except Exception:
+        ascender_px = 0
+    baseline_y = y + ascender_px
+    for char in text:
+        face.load_char(char)
+        bitmap = face.glyph.bitmap
+        glyph_left = face.glyph.bitmap_left
+        glyph_top = face.glyph.bitmap_top
+        for i in range(bitmap.rows):
+            for j in range(bitmap.width):
+                byte_index = i * bitmap.pitch + (j // 8)
+                if byte_index < len(bitmap.buffer) and \
+                        bitmap.buffer[byte_index] & (1 << (7 - (j % 8))):
+                    px = x + glyph_left + j
+                    py = baseline_y - glyph_top + i
+                    if 0 <= px < clip_w and 0 <= py < clip_h:
+                        draw.point((px, py), fill=color)
+        x += face.glyph.advance.x >> 6
+
+
+@dataclass
+class SkinContext:
+    """Everything a skin may touch during one render call.
+
+    The canvas is a fresh RGB image sized to the current display (or
+    vegas card). Draw onto it via the helpers below or raw ``draw``;
+    never call display/update methods — the host composites the canvas.
+    """
+
+    canvas: Image.Image
+    draw: ImageDraw.ImageDraw
+    layout: LayoutContext
+    width: int
+    height: int
+    fonts: Dict[str, Any]
+    options: Dict[str, Any]
+    logger: Any
+    sport: Optional[str] = None
+    view_model_version: str = VIEW_MODEL_VERSION
+    # load_logo("home") / load_logo("away") -> RGBA PIL image or None.
+    # Bound to the current game; hits the host's logo cache (never loads
+    # from disk twice), downloads missing logos like the built-in layout.
+    load_logo: Callable[[str], Optional[Image.Image]] = field(default=lambda side: None)
+    # draw_text_outlined(text, (x, y), font, fill=..., outline_color=...)
+    # — the classic scorebug outlined text, drawn onto this canvas.
+    # TTF fonts only (ctx.fonts values are TTF); for ladder-fitted fonts
+    # use draw_fit / draw_text, which handle BDF faces too.
+    draw_text_outlined: Callable[..., None] = field(default=lambda *a, **k: None)
+
+    def draw_text(self, text: str, x: int, y: int,
+                  color: Tuple[int, int, int] = (255, 255, 255),
+                  font: Any = None) -> None:
+        """Draw text at a top-left position, handling both PIL fonts and
+        the freetype BDF faces that layout.fit_text can return."""
+        if font is None:
+            font = self.fonts.get('time')
+        if freetype is not None and isinstance(font, freetype.Face):
+            _draw_bdf_text_on(self.draw, text, int(x), int(y), color, font,
+                              self.width, self.height)
+        else:
+            self.draw.text((int(x), int(y)), text, font=font, fill=color)
+
+    def draw_fit(self, fit: FitResult, box: Union[Region, Tuple[int, int]],
+                 color: Tuple[int, int, int] = (255, 255, 255),
+                 align: str = "center", valign: str = "center") -> None:
+        """Draw a layout.fit_text() result aligned within a Region — the
+        canvas-local equivalent of adaptive_layout.draw_fitted_text."""
+        region = box if isinstance(box, Region) else Region(0, 0, box[0], box[1])
+        x, y = region.align_xy(fit.width, fit.height, align, valign)
+        self.draw_text(fit.text, x, y - fit.y_offset, color=color, font=fit.font)
+
+    def draw_image(self, img: Optional[Image.Image],
+                   box: Union[Region, Tuple[int, int]], *,
+                   mode: str = "contain", align: str = "center",
+                   valign: str = "center", cache_key: Any = None) -> None:
+        """Fit an image (a logo, art) into a Region and paste it, honoring
+        alpha. Silently no-ops on None so `ctx.draw_image(ctx.load_logo(
+        'home'), ...)` stays safe when a logo is missing."""
+        if img is None:
+            return
+        region = box if isinstance(box, Region) else Region(0, 0, box[0], box[1])
+        fitted = self.layout.fit_image(img, region, mode=mode,
+                                       cache_key=cache_key)
+        result = fitted.image  # fit_image returns an ImageFitResult (always RGBA)
+        if result is None:
+            return
+        x, y = region.align_xy(result.width, result.height, align, valign)
+        self.canvas.paste(result, (int(x), int(y)), result)
+
+
+class ScoreboardSkin(ABC):
+    """Base class for scoreboard skins.
+
+    Override only the modes you want to restyle; any mode you leave
+    unimplemented (or return False from) falls back to the plugin's
+    built-in renderer, so a live-only skin still gets recent/upcoming
+    screens for free.
+
+    Skins should be stateless: three host instances (live, recent,
+    upcoming) each hold their own skin instance, and a render must be
+    derivable from (ctx, game) alone.
+    """
+
+    SKIN_API_VERSION = SKIN_API_VERSION
+
+    def __init__(self, manifest: Dict[str, Any], options: Dict[str, Any]):
+        self.manifest = manifest
+        self.options = options or {}
+
+    def render_live(self, ctx: SkinContext, game: Dict[str, Any]) -> bool:
+        return False
+
+    def render_recent(self, ctx: SkinContext, game: Dict[str, Any]) -> bool:
+        return False
+
+    def render_upcoming(self, ctx: SkinContext, game: Dict[str, Any]) -> bool:
+        return False
+
+    def render_vegas_card(self, ctx: SkinContext,
+                          game: Dict[str, Any]) -> Optional[Image.Image]:
+        """Render one vegas scroll card at ctx.width x ctx.height. Return
+        the finished image, or None to let the host use its default vegas
+        rendering (which captures the regular display output)."""
+        return None

src/skin_system/skin_runtime.py

@@ -0,0 +1,352 @@
+"""
+Skin runtime: discovery, validation, loading, and context building.
+
+Deliberately generic — this module knows nothing about sports beyond
+passing a `sport` label through; the sports flavor lives in skin_base
+(ScoreboardSkin) and in the hosts that call build_context.
+
+Every failure path here logs and returns None: a broken or missing skin
+must never take down the plugin that references it — the host falls
+back to its built-in renderer.
+"""
+
+import importlib.util
+import json
+import sys
+import threading
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple
+
+from PIL import Image, ImageDraw
+
+from src.adaptive_layout import LayoutContext
+from src.logging_config import get_logger
+from src.skin_system.skin_base import (
+    SKIN_API_VERSION,
+    ScoreboardSkin,
+    SkinContext,
+)
+
+logger = get_logger(__name__)
+
+_REQUIRED_MANIFEST_FIELDS = ("id", "name", "version", "skin_api_version", "class_name")
+_DEFAULT_ENTRY_POINT = "skin.py"
+
+_lock = threading.RLock()
+# skins_dir -> (fingerprint, {skin_id: manifest+path})
+_discovery_cache: Dict[str, Tuple[Tuple, Dict[str, Dict[str, Any]]]] = {}
+
+_shared_layout_font_manager: Optional[Any] = None
+
+
+def _get_font_manager() -> Any:
+    """Shared FontManager for skin LayoutContexts. SportsCore hosts don't
+    carry a plugin_manager, so skins share one module-level FontManager —
+    the same shape as base_plugin._fallback_font_manager, constructed
+    directly so rendering never has to import the whole plugin system."""
+    global _shared_layout_font_manager
+    if _shared_layout_font_manager is None:
+        from src.font_manager import FontManager
+        _shared_layout_font_manager = FontManager({})
+    return _shared_layout_font_manager
+
+
+def get_skins_directory() -> Path:
+    """Central skins directory: <project_root>/skins. Lives outside the
+    plugin directories on purpose — plugin reinstall/update deletes the
+    whole plugin directory, and a skin must survive that."""
+    return Path(__file__).resolve().parents[2] / "skins"
+
+
+def _major(version: str) -> Optional[int]:
+    try:
+        return int(str(version).split(".")[0])
+    except (ValueError, AttributeError, IndexError):
+        return None
+
+
+def _read_manifest(skin_dir: Path) -> Optional[Dict[str, Any]]:
+    manifest_path = skin_dir / "skin.json"
+    if not manifest_path.is_file():
+        return None
+    try:
+        with open(manifest_path, "r", encoding="utf-8") as f:
+            manifest = json.load(f)
+    except (OSError, json.JSONDecodeError) as e:
+        logger.error("Skin manifest %s is unreadable: %s", manifest_path, e)
+        return None
+    missing = [k for k in _REQUIRED_MANIFEST_FIELDS if not manifest.get(k)]
+    if missing:
+        logger.error("Skin manifest %s missing required fields: %s",
+                     manifest_path, ", ".join(missing))
+        return None
+    if manifest["id"] != skin_dir.name:
+        logger.warning("Skin manifest id %r does not match directory name %r",
+                       manifest["id"], skin_dir.name)
+    manifest["_skin_dir"] = str(skin_dir)
+    return manifest
+
+
+def _discovery_fingerprint(skins_dir: Path) -> Optional[Tuple]:
+    """Cache key for a skins directory: its mtime plus every skin.json's
+    (path, mtime). The directory mtime alone misses in-place manifest edits
+    (a skin updated without adding/removing entries)."""
+    try:
+        parts = [skins_dir.stat().st_mtime]
+        for manifest_path in sorted(skins_dir.glob("*/skin.json")):
+            parts.append((str(manifest_path), manifest_path.stat().st_mtime))
+        return tuple(parts)
+    except OSError:
+        return None
+
+
+def discover_skins(skins_dir: Optional[Path] = None,
+                   force_refresh: bool = False) -> Dict[str, Dict[str, Any]]:
+    """Return {skin_id: manifest} for every valid skin package installed.
+
+    Cached per directory and invalidated when the directory or any
+    skin.json changes; pass force_refresh to bypass.
+    """
+    skins_dir = Path(skins_dir) if skins_dir else get_skins_directory()
+    cache_key = str(skins_dir)
+    fingerprint = _discovery_fingerprint(skins_dir)
+    if fingerprint is None:
+        return {}
+
+    with _lock:
+        cached = _discovery_cache.get(cache_key)
+        if cached and not force_refresh and cached[0] == fingerprint:
+            return dict(cached[1])
+
+        skins: Dict[str, Dict[str, Any]] = {}
+        for entry in sorted(skins_dir.iterdir()):
+            if not entry.is_dir() or entry.name.startswith((".", "_")):
+                continue
+            manifest = _read_manifest(entry)
+            if manifest:
+                skins[manifest["id"]] = manifest
+        _discovery_cache[cache_key] = (fingerprint, skins)
+        return dict(skins)
+
+
+def skin_targets(manifest: Dict[str, Any]) -> Tuple[list, list]:
+    """(sports, sport_keys) a skin declares it supports."""
+    targets = manifest.get("targets") or {}
+    return (list(targets.get("sports") or []),
+            list(targets.get("sport_keys") or []))
+
+
+def skin_matches_target(manifest: Dict[str, Any], sport: Optional[str],
+                        sport_key: Optional[str]) -> bool:
+    """True when the skin declares support for this sport family or exact
+    sport key. A skin with no targets at all matches everything."""
+    sports, sport_keys = skin_targets(manifest)
+    if not sports and not sport_keys:
+        return True
+    if sport and sport in sports:
+        return True
+    if sport_key and sport_key in sport_keys:
+        return True
+    return False
+
+
+def skins_for_plugin(plugin_id: str,
+                     skins: Optional[Dict[str, Dict[str, Any]]] = None) -> Dict[str, Dict[str, Any]]:
+    """Installed skins that plausibly apply to a plugin, for UI dropdowns.
+
+    A skin matches when the plugin id is listed in targets.plugins, or any
+    declared sport / sport_key appears as a token of the plugin id (so a
+    skin targeting sports=["baseball"] matches "baseball-scoreboard", and
+    sport_keys=["milb"] matches "milb-scoreboard")."""
+    if skins is None:
+        skins = discover_skins()
+    tokens = set(str(plugin_id).lower().replace("-", "_").split("_"))
+    matched = {}
+    for skin_id, manifest in skins.items():
+        targets = manifest.get("targets") or {}
+        if plugin_id in (targets.get("plugins") or []):
+            matched[skin_id] = manifest
+            continue
+        sports, sport_keys = skin_targets(manifest)
+        if any(str(t).lower() in tokens for t in sports + sport_keys):
+            matched[skin_id] = manifest
+    return matched
+
+
+def _load_skin_module(skin_id: str, skin_dir: Path, entry_point: str) -> Optional[Any]:
+    """Import the skin's entry module under a namespaced sys.modules key,
+    namespacing its sibling .py files the same way — the collision-
+    avoidance scheme plugins use (plugin_loader._namespace_plugin_modules),
+    so two skins can both ship a helpers.py.
+
+    The entry module is cached: the live/recent/upcoming hosts all load
+    the same skin, and only the first load executes any code. (A skin
+    whose *code* changed on disk needs a service restart to take effect —
+    Python modules can't be safely hot-swapped.)
+    """
+    entry_path = skin_dir / entry_point
+    if not entry_path.is_file():
+        logger.error("Skin '%s' entry point not found: %s", skin_id, entry_path)
+        return None
+
+    module_name = f"_skin_{skin_id}_{Path(entry_point).stem}"
+    with _lock:
+        cached_entry = sys.modules.get(module_name)
+        if cached_entry is not None:
+            return cached_entry
+
+        # Import siblings under their namespaced alias, and *bind* the bare
+        # name (cached or fresh) so `import helpers` inside the entry module
+        # resolves to this skin's copy. The bare bindings are transient —
+        # restored below so another skin's identically-named sibling can't
+        # be shadowed by ours.
+        replaced_bare: Dict[str, Any] = {}
+        try:
+            for sibling in skin_dir.glob("*.py"):
+                if sibling.name == entry_point:
+                    continue
+                alias = f"_skin_{skin_id}_{sibling.stem}"
+                module = sys.modules.get(alias)
+                if module is None:
+                    spec = importlib.util.spec_from_file_location(alias, sibling)
+                    if not spec or not spec.loader:
+                        continue
+                    module = importlib.util.module_from_spec(spec)
+                    sys.modules[alias] = module
+                    replaced_bare.setdefault(sibling.stem, sys.modules.get(sibling.stem))
+                    sys.modules[sibling.stem] = module
+                    try:
+                        spec.loader.exec_module(module)
+                    except Exception as e:
+                        logger.error("Skin '%s' sibling module %s failed to import: %s",
+                                     skin_id, sibling.name, e, exc_info=True)
+                        sys.modules.pop(alias, None)
+                        return None
+                else:
+                    replaced_bare.setdefault(sibling.stem, sys.modules.get(sibling.stem))
+                    sys.modules[sibling.stem] = module
+
+            try:
+                spec = importlib.util.spec_from_file_location(module_name, entry_path)
+                if not spec or not spec.loader:
+                    logger.error("Skin '%s': could not create import spec for %s",
+                                 skin_id, entry_path)
+                    return None
+                module = importlib.util.module_from_spec(spec)
+                sys.modules[module_name] = module
+                spec.loader.exec_module(module)
+                return module
+            except Exception as e:
+                sys.modules.pop(module_name, None)
+                logger.error("Skin '%s' failed to import: %s", skin_id, e, exc_info=True)
+                return None
+        finally:
+            for bare_name, previous in replaced_bare.items():
+                if previous is None:
+                    sys.modules.pop(bare_name, None)
+                else:
+                    sys.modules[bare_name] = previous
+
+
+def load_skin(skin_id: str, sport: Optional[str] = None,
+              sport_key: Optional[str] = None,
+              options: Optional[Dict[str, Any]] = None,
+              skins_dir: Optional[Path] = None) -> Optional[ScoreboardSkin]:
+    """Load and instantiate a skin. Returns None (after logging why) on
+    any failure — callers treat None as 'use the built-in renderer'."""
+    skins = discover_skins(skins_dir)
+    manifest = skins.get(skin_id)
+    if manifest is None:
+        logger.warning("Skin '%s' is configured but not installed under %s; "
+                       "using built-in renderer",
+                       skin_id, skins_dir or get_skins_directory())
+        return None
+
+    manifest_major = _major(manifest.get("skin_api_version"))
+    api_major = _major(SKIN_API_VERSION)
+    if manifest_major != api_major:
+        logger.error("Skin '%s' targets skin API %s but this LEDMatrix "
+                     "provides %s — the skin needs an update; using "
+                     "built-in renderer",
+                     skin_id, manifest.get("skin_api_version"), SKIN_API_VERSION)
+        return None
+
+    if not skin_matches_target(manifest, sport, sport_key):
+        # Soft: the user explicitly configured it, so warn but load anyway
+        # (a baseball skin may render an acceptable generic scoreboard).
+        logger.warning("Skin '%s' does not declare support for sport=%r / "
+                       "sport_key=%r; loading anyway", skin_id, sport, sport_key)
+
+    skin_dir = Path(manifest["_skin_dir"])
+    module = _load_skin_module(skin_id, skin_dir,
+                               manifest.get("entry_point", _DEFAULT_ENTRY_POINT))
+    if module is None:
+        return None
+
+    class_name = manifest["class_name"]
+    skin_class = getattr(module, class_name, None)
+    if skin_class is None or not isinstance(skin_class, type) or \
+            not issubclass(skin_class, ScoreboardSkin):
+        logger.error("Skin '%s': %s is missing or not a ScoreboardSkin subclass",
+                     skin_id, class_name)
+        return None
+
+    try:
+        return skin_class(manifest, options or {})
+    except Exception as e:
+        logger.error("Skin '%s' failed to instantiate: %s", skin_id, e, exc_info=True)
+        return None
+
+
+def build_context(host: Any, game: Dict[str, Any],
+                  size: Optional[Tuple[int, int]] = None) -> SkinContext:
+    """Build a SkinContext for one render call.
+
+    `host` is a SportsCore-style object: display_manager, fonts, logger,
+    sport, skin_options, _load_and_resize_logo, _draw_text_with_outline.
+    `size` overrides the canvas size (vegas cards); default is the
+    current display size read live from the display manager.
+    """
+    if size is not None:
+        width, height = int(size[0]), int(size[1])
+    else:
+        dm = host.display_manager
+        width = getattr(dm, "width", None) or dm.matrix.width
+        height = getattr(dm, "height", None) or dm.matrix.height
+
+    canvas = Image.new("RGB", (width, height), (0, 0, 0))
+    draw = ImageDraw.Draw(canvas)
+    layout = LayoutContext(width, height, _get_font_manager())
+
+    def load_logo(side: str) -> Optional[Image.Image]:
+        if side not in ("home", "away"):
+            return None
+        try:
+            logo_path = game.get(f"{side}_logo_path")
+            if logo_path is not None and not isinstance(logo_path, Path):
+                logo_path = Path(logo_path)
+            return host._load_and_resize_logo(
+                game.get(f"{side}_id"), game.get(f"{side}_abbr"),
+                logo_path, game.get(f"{side}_logo_url"))
+        except Exception as e:
+            host.logger.warning("Skin logo load failed for %s: %s", side, e)
+            return None
+
+    def draw_text_outlined(text, position, font, fill=(255, 255, 255),
+                           outline_color=(0, 0, 0)):
+        host._draw_text_with_outline(draw, text, position, font,
+                                     fill=fill, outline_color=outline_color)
+
+    return SkinContext(
+        canvas=canvas,
+        draw=draw,
+        layout=layout,
+        width=width,
+        height=height,
+        fonts=dict(host.fonts),
+        options=dict(getattr(host, "skin_options", {}) or {}),
+        logger=host.logger,
+        sport=getattr(host, "sport", None),
+        load_logo=load_logo,
+        draw_text_outlined=draw_text_outlined,
+    )

src/vegas_mode/config.py

@@ -21,6 +21,94 @@ class VegasModeConfig:
     scroll_speed: float = 50.0  # Pixels per second
     separator_width: int = 32  # Gap between plugins (pixels)
 
+    # Fraction of the panel width a plugin is told it has while rendering for
+    # the ticker, as a percentage. Trimming can only remove blank margins; it
+    # cannot compact a layout that genuinely spans the display — a five-column
+    # forecast, a full-width progress bar, a centred stat block with the panel's
+    # whole width between its elements. Rendering at a narrower size makes the
+    # plugin choose a tighter layout instead. 100 disables it.
+    render_width_pct: int = 100
+
+    # Minimum blank columns guaranteed between adjacent content, measured from
+    # actual ink rather than added blindly. A flat additive gap leaves
+    # card-style content nearly touching when the cards are drawn flush to their
+    # own edges, while padding out content that already has wide margins.
+    min_content_separation: int = 24
+
+    # Gap between rows contributed by the *same* plugin. separator_width marks
+    # the handoff from one plugin to the next; applying it between every image
+    # forced a 32px chasm between each row of a per-row ticker (the F1
+    # scoreboard renders its own rows 4px apart), which both looked wrong and
+    # silently inflated the width that plugin occupied.
+    intra_plugin_gap: int = 8
+
+    # Content density
+    #
+    # Plugins that render onto a full-display canvas contribute that whole
+    # canvas to the ticker, blank margins included. On a wide panel that is the
+    # dominant source of dead air: a plugin drawing 35px of text on a 512px
+    # canvas otherwise buys 9.5s of black at 50px/s. Trimming reclaims it.
+    auto_trim: bool = True
+    trim_threshold: int = 10  # Per-channel value a pixel must exceed to be "ink"
+    content_padding: int = 8  # Blank columns kept either side of trimmed content
+    min_plugin_width: int = 8  # Segments narrower than this after trim are dropped
+
+    # Columns of blank lead-in before the first item of a cycle. ScrollHelper
+    # defaults this to a full display width, which reads as the display being
+    # switched off at the start of every cycle.
+    lead_in_width: int = 0
+
+    # Blend between neighbouring pixel positions so motion happens at the frame
+    # rate rather than the scroll speed. With integer positioning the number of
+    # distinct frames per second equals scroll_speed, so at 50px/s the motion is
+    # 50 discrete 1px steps however fast the loop runs. The trade is a slight
+    # horizontal softening of text, since each frame is a blend of two positions.
+    smooth_scroll: bool = True
+
+    # Keep one continuous strip, extending it with the next group of plugins as
+    # the scroll approaches the end, instead of composing a fresh strip and
+    # swapping it in. A swap stops the motion, substitutes every pixel at once
+    # and restarts with the viewport already full — read as a freeze, a flash
+    # and a jump. Extending means the next group simply scrolls in from the
+    # right. Set false to restore the swap behaviour.
+    continuous_scroll: bool = True
+
+    # Extend once the unscrolled remainder falls below this many screen widths.
+    # Needs to be more than one so the join is prepared before it is on screen.
+    extend_threshold_screens: float = 2.0
+
+    # How many plugins are composed into one scroll cycle. Kept separate from
+    # buffer_ahead (which is only a prefetch low-water mark) because the two
+    # were previously the same number: a buffer_ahead of 2 meant just 3 plugins
+    # per cycle, so a 20-plugin install took seven cycles to come around.
+    plugins_per_cycle: int = 6
+
+    # Minimum run of blank columns that counts as a boundary between items when
+    # an oversized segment has to be narrowed. Measured on rendered text, the
+    # gaps between characters are a single column while gaps between items are
+    # 8px and up, so anything above 1 stops a cut landing inside a word. Cutting
+    # mid-word orphaned the tail into the next cycle, which showed up as a lone
+    # letter floating between two unrelated plugins.
+    min_cut_gap: int = 6
+
+    # What to do when a plugin's content exceeds its width budget.
+    #
+    #   "rotate"   — advance a window each cycle so everything is seen eventually.
+    #                Right for interchangeable items: news headlines, odds, stocks.
+    #   "truncate" — always show the start. Right for ordered content, where a
+    #                window into the middle is meaningless: a league table that
+    #                shows ranks 1-6 then resumes at 7 two rotations later reads
+    #                as out of order and out of context.
+    #
+    # Override per plugin with vegas_overflow.
+    overflow_mode: str = "rotate"
+
+    # Cap on one plugin's share of a cycle, as a multiple of display width.
+    # A single ticker returning 7,000px would otherwise hold the panel for over
+    # two minutes. Overflow is deferred to later cycles rather than discarded.
+    # 0 disables the cap.
+    max_plugin_width_ratio: float = 3.0
+
     # Plugin management
     plugin_order: List[str] = field(default_factory=list)
     excluded_plugins: Set[str] = field(default_factory=set)
@@ -55,6 +143,24 @@ class VegasModeConfig:
             enabled=vegas_config.get('enabled', False),
             scroll_speed=float(vegas_config.get('scroll_speed', 50.0)),
             separator_width=int(vegas_config.get('separator_width', 32)),
+            intra_plugin_gap=int(vegas_config.get('intra_plugin_gap', 8)),
+            render_width_pct=int(vegas_config.get('render_width_pct', 100)),
+            min_content_separation=int(
+                vegas_config.get('min_content_separation', 24)),
+            min_cut_gap=int(vegas_config.get('min_cut_gap', 6)),
+            smooth_scroll=vegas_config.get('smooth_scroll', True),
+            continuous_scroll=vegas_config.get('continuous_scroll', True),
+            extend_threshold_screens=float(
+                vegas_config.get('extend_threshold_screens', 2.0)),
+            auto_trim=vegas_config.get('auto_trim', True),
+            trim_threshold=int(vegas_config.get('trim_threshold', 10)),
+            content_padding=int(vegas_config.get('content_padding', 8)),
+            min_plugin_width=int(vegas_config.get('min_plugin_width', 8)),
+            lead_in_width=int(vegas_config.get('lead_in_width', 0)),
+            plugins_per_cycle=int(vegas_config.get('plugins_per_cycle', 6)),
+            max_plugin_width_ratio=float(
+                vegas_config.get('max_plugin_width_ratio', 3.0)),
+            overflow_mode=str(vegas_config.get('overflow_mode', 'rotate')),
             plugin_order=list(vegas_config.get('plugin_order', [])),
             excluded_plugins=set(vegas_config.get('excluded_plugins', [])),
             target_fps=int(vegas_config.get('target_fps', 125)),
@@ -72,6 +178,21 @@ class VegasModeConfig:
             'enabled': self.enabled,
             'scroll_speed': self.scroll_speed,
             'separator_width': self.separator_width,
+            'intra_plugin_gap': self.intra_plugin_gap,
+            'render_width_pct': self.render_width_pct,
+            'min_content_separation': self.min_content_separation,
+            'min_cut_gap': self.min_cut_gap,
+            'smooth_scroll': self.smooth_scroll,
+            'continuous_scroll': self.continuous_scroll,
+            'extend_threshold_screens': self.extend_threshold_screens,
+            'auto_trim': self.auto_trim,
+            'trim_threshold': self.trim_threshold,
+            'content_padding': self.content_padding,
+            'min_plugin_width': self.min_plugin_width,
+            'lead_in_width': self.lead_in_width,
+            'plugins_per_cycle': self.plugins_per_cycle,
+            'max_plugin_width_ratio': self.max_plugin_width_ratio,
+            'overflow_mode': self.overflow_mode,
             'plugin_order': self.plugin_order,
             'excluded_plugins': list(self.excluded_plugins),
             'target_fps': self.target_fps,
@@ -157,6 +278,74 @@ class VegasModeConfig:
         if self.buffer_ahead > 5:
             errors.append(f"buffer_ahead must be <= 5, got {self.buffer_ahead}")
 
+        if not 10 <= self.render_width_pct <= 100:
+            errors.append(
+                "render_width_pct must be between 10 and 100, "
+                f"got {self.render_width_pct}")
+
+        if not 0 <= self.min_content_separation <= 256:
+            errors.append(
+                "min_content_separation must be between 0 and 256, "
+                f"got {self.min_content_separation}")
+
+        if not 1.0 <= self.extend_threshold_screens <= 10.0:
+            errors.append(
+                "extend_threshold_screens must be between 1.0 and 10.0, "
+                f"got {self.extend_threshold_screens}")
+
+        if not 1 <= self.min_cut_gap <= 128:
+            errors.append(
+                "min_cut_gap must be between 1 and 128, "
+                f"got {self.min_cut_gap}")
+
+        if self.intra_plugin_gap < 0:
+            errors.append(
+                f"intra_plugin_gap must be >= 0, got {self.intra_plugin_gap}")
+        if self.intra_plugin_gap > 128:
+            errors.append(
+                f"intra_plugin_gap must be <= 128, got {self.intra_plugin_gap}")
+
+        if not 0 <= self.trim_threshold <= 254:
+            errors.append(
+                f"trim_threshold must be between 0 and 254, got {self.trim_threshold}")
+
+        if self.content_padding < 0:
+            errors.append(
+                f"content_padding must be >= 0, got {self.content_padding}")
+        if self.content_padding > 128:
+            errors.append(
+                f"content_padding must be <= 128, got {self.content_padding}")
+
+        if self.min_plugin_width < 0:
+            errors.append(
+                f"min_plugin_width must be >= 0, got {self.min_plugin_width}")
+        # Bounded because every segment narrower than this is dropped — an
+        # unbounded value would discard every plugin and leave a blank ticker.
+        if self.min_plugin_width > 512:
+            errors.append(
+                f"min_plugin_width must be <= 512, got {self.min_plugin_width}")
+
+        if self.lead_in_width < 0:
+            errors.append(
+                f"lead_in_width must be >= 0, got {self.lead_in_width}")
+
+        if self.plugins_per_cycle < 1:
+            errors.append(
+                f"plugins_per_cycle must be >= 1, got {self.plugins_per_cycle}")
+        if self.plugins_per_cycle > 50:
+            errors.append(
+                f"plugins_per_cycle must be <= 50, got {self.plugins_per_cycle}")
+
+        if self.overflow_mode not in ('rotate', 'truncate'):
+            errors.append(
+                "overflow_mode must be 'rotate' or 'truncate', "
+                f"got {self.overflow_mode!r}")
+
+        if self.max_plugin_width_ratio < 0:
+            errors.append(
+                "max_plugin_width_ratio must be >= 0 "
+                f"(0 disables the cap), got {self.max_plugin_width_ratio}")
+
         return errors
 
     def update(self, new_config: Dict[str, Any]) -> None:
@@ -174,6 +363,39 @@ class VegasModeConfig:
             self.scroll_speed = float(vegas_config['scroll_speed'])
         if 'separator_width' in vegas_config:
             self.separator_width = int(vegas_config['separator_width'])
+        if 'intra_plugin_gap' in vegas_config:
+            self.intra_plugin_gap = int(vegas_config['intra_plugin_gap'])
+        if 'render_width_pct' in vegas_config:
+            self.render_width_pct = int(vegas_config['render_width_pct'])
+        if 'min_content_separation' in vegas_config:
+            self.min_content_separation = int(
+                vegas_config['min_content_separation'])
+        if 'min_cut_gap' in vegas_config:
+            self.min_cut_gap = int(vegas_config['min_cut_gap'])
+        if 'smooth_scroll' in vegas_config:
+            self.smooth_scroll = vegas_config['smooth_scroll']
+        if 'continuous_scroll' in vegas_config:
+            self.continuous_scroll = vegas_config['continuous_scroll']
+        if 'extend_threshold_screens' in vegas_config:
+            self.extend_threshold_screens = float(
+                vegas_config['extend_threshold_screens'])
+        if 'auto_trim' in vegas_config:
+            self.auto_trim = vegas_config['auto_trim']
+        if 'trim_threshold' in vegas_config:
+            self.trim_threshold = int(vegas_config['trim_threshold'])
+        if 'content_padding' in vegas_config:
+            self.content_padding = int(vegas_config['content_padding'])
+        if 'min_plugin_width' in vegas_config:
+            self.min_plugin_width = int(vegas_config['min_plugin_width'])
+        if 'lead_in_width' in vegas_config:
+            self.lead_in_width = int(vegas_config['lead_in_width'])
+        if 'plugins_per_cycle' in vegas_config:
+            self.plugins_per_cycle = int(vegas_config['plugins_per_cycle'])
+        if 'max_plugin_width_ratio' in vegas_config:
+            self.max_plugin_width_ratio = float(
+                vegas_config['max_plugin_width_ratio'])
+        if 'overflow_mode' in vegas_config:
+            self.overflow_mode = str(vegas_config['overflow_mode'])
         if 'plugin_order' in vegas_config:
             self.plugin_order = list(vegas_config['plugin_order'])
         if 'excluded_plugins' in vegas_config:

src/vegas_mode/coordinator.py

@@ -64,7 +64,7 @@ class VegasModeCoordinator:
         self.plugin_manager = plugin_manager
 
         # Initialize components
-        self.plugin_adapter = PluginAdapter(display_manager)
+        self.plugin_adapter = PluginAdapter(display_manager, self.vegas_config)
         self.stream_manager = StreamManager(
             self.vegas_config,
             plugin_manager,
@@ -233,6 +233,11 @@ class VegasModeCoordinator:
             self._should_stop = False
             self._start_time = time.time()
 
+        # Line up the next group immediately, so the first extension is already
+        # warm rather than stalling the scroll to fetch it.
+        if self.vegas_config.continuous_scroll:
+            self.render_pipeline.start_prefetch()
+
         logger.info("Vegas mode started")
         return True
 
@@ -301,16 +306,43 @@ class VegasModeCoordinator:
         if has_pending_update:
             self._apply_pending_config()
 
-        # Check if we need to start a new cycle
-        if self.render_pipeline.is_cycle_complete():
-            if not self.render_pipeline.start_new_cycle():
-                logger.warning("Failed to start new Vegas cycle")
-                return False
-            self.stats['cycles_completed'] += 1
+        if self.vegas_config.continuous_scroll:
+            # Drop cached content for plugins whose data just changed, so the
+            # next time each comes round it is composed from current data. The
+            # swap path's hot_swap_content() does this via process_updates(),
+            # but it also rebuilds and repositions the whole strip, which is
+            # the freeze-and-jump this mode exists to avoid. Without this the
+            # pending-update flags are never consumed and a segment keeps
+            # rendering whatever it was first built from — last night's live
+            # game still shown as live the next morning.
+            self.render_pipeline.refresh_updated_plugins()
 
-        # Check for hot-swap opportunities
-        if self.render_pipeline.should_recompose():
-            self.render_pipeline.hot_swap_content()
+            # Extend the strip before the scroll can reach its end, so the next
+            # group arrives from the right and motion never stops. No cycle
+            # boundary, so no freeze, no substitution and no restart with the
+            # viewport already full.
+            # Trickle in the plugins that can only be fetched here, one per
+            # frame, before considering a further extension.
+            if self.render_pipeline.has_deferred():
+                self.render_pipeline.drain_deferred()
+            elif self.render_pipeline.needs_extension():
+                if self.render_pipeline.extend_scroll_content():
+                    self.stats['cycles_completed'] += 1
+                elif self.render_pipeline.is_cycle_complete():
+                    # Extension failed and the strip has run out: fall back to
+                    # the swap rather than sitting on a dead frame.
+                    self.render_pipeline.start_new_cycle()
+        else:
+            # Check if we need to start a new cycle
+            if self.render_pipeline.is_cycle_complete():
+                if not self.render_pipeline.start_new_cycle():
+                    logger.warning("Failed to start new Vegas cycle")
+                    return False
+                self.stats['cycles_completed'] += 1
+
+            # Check for hot-swap opportunities
+            if self.render_pipeline.should_recompose():
+                self.render_pipeline.hot_swap_content()
 
         # Render frame
         return self.render_pipeline.render_frame()
@@ -337,7 +369,14 @@ class VegasModeCoordinator:
         self._update_static_mode_plugins()
 
         frame_interval = self.vegas_config.get_frame_interval()
-        duration = self.render_pipeline.get_dynamic_duration()
+        if self.vegas_config.continuous_scroll:
+            # The strip is continuously extended and trimmed, so its width says
+            # nothing about how long to run. This is only how often control
+            # returns to the display controller; interrupts are still checked
+            # every few frames, so it costs nothing to make it a fixed period.
+            duration = float(self.vegas_config.max_cycle_duration)
+        else:
+            duration = self.render_pipeline.get_dynamic_duration()
         start_time = time.time()
         frame_count = 0
         fps_log_interval = 5.0  # Log FPS every 5 seconds
@@ -347,6 +386,8 @@ class VegasModeCoordinator:
         logger.info("Starting Vegas iteration for %.1fs", duration)
 
         while True:
+            frame_started = time.time()
+
             # Check for STATIC mode plugin that should pause scroll
             static_plugin = self._check_static_plugin_trigger()
             if static_plugin:
@@ -367,8 +408,14 @@ class VegasModeCoordinator:
                         # Paused for live priority - let caller handle
                         return False
 
-            # Sleep for frame interval
-            time.sleep(frame_interval)
+            # Sleep only the remainder of the frame budget. This used to sleep
+            # the whole interval on top of however long the frame took, so at a
+            # measured 31.6ms per frame a fixed 8ms of that was pure idle — a
+            # quarter of the budget spent not rendering. Subtracting the work
+            # already done keeps the pacing target while reclaiming that time,
+            # and yields the GIL either way so other threads still run.
+            frame_elapsed = time.time() - frame_started
+            time.sleep(max(0.0, frame_interval - frame_elapsed))
 
             # Increment frame count and check for interrupt periodically
             frame_count += 1
@@ -505,6 +552,10 @@ class VegasModeCoordinator:
             # Update components
             self.render_pipeline.update_config(new_vegas_config)
             self.stream_manager.config = new_vegas_config
+            self.plugin_adapter.config = new_vegas_config
+            # Cached segments were trimmed under the old settings, so drop them
+            # or a changed trim/padding value would not visibly take effect.
+            self.plugin_adapter.invalidate_cache()
 
             # Force refresh of stream manager to pick up plugin_order/buffer changes
             self.stream_manager._last_refresh = 0

src/vegas_mode/geometry.py

@@ -0,0 +1,474 @@
+"""
+Geometry primitives for Vegas Mode.
+
+Pure, side-effect-free measurements over PIL images. Two consumers:
+
+- ``PluginAdapter`` trims the blank margins plugins bake into their content
+  before it enters the ticker (see ``trim_to_content``).
+- ``scripts/dev/vegas_audit.py`` reports how much of the composed ticker is
+  dead space (see ``dead_window_stats``).
+
+Keeping both on the same primitives means the number the audit reports is the
+number the trimmer acted on.
+
+All column scans go through numpy: a Python-level per-column loop over a
+17,000px-wide ticker image takes seconds, which is far too slow for the render
+path.
+"""
+
+from typing import List, NamedTuple, Optional, Tuple
+
+import numpy as np
+from PIL import Image
+
+# A pixel counts as "ink" when any channel exceeds this. Chosen to ignore the
+# 1-2/255 noise that JPEG-sourced logos and alpha compositing leave behind in
+# nominally black areas, while still treating any deliberately drawn dark grey
+# as real content.
+DEFAULT_INK_THRESHOLD = 10
+
+# A window counts as "dead" when this fraction of its columns carry no ink.
+DEFAULT_DEAD_WINDOW_RATIO = 0.95
+
+
+def column_has_ink(img: Image.Image, threshold: int = DEFAULT_INK_THRESHOLD) -> np.ndarray:
+    """
+    Return a boolean array, one entry per image column, True where the column
+    contains at least one pixel brighter than ``threshold`` in any channel.
+
+    Args:
+        img: Image to scan (converted to RGB internally)
+        threshold: Per-channel value a pixel must exceed to count as ink
+
+    Returns:
+        Bool array of shape (width,)
+    """
+    arr = np.asarray(img if img.mode == 'RGB' else img.convert('RGB'))
+    if arr.ndim != 3:
+        # Degenerate/empty image — treat every column as blank.
+        return np.zeros(img.width, dtype=bool)
+    # Collapse rows and channels: a column is ink if any pixel in it is bright.
+    return arr.max(axis=(0, 2)) > threshold
+
+
+def content_bounds(
+    img: Image.Image, threshold: int = DEFAULT_INK_THRESHOLD
+) -> Optional[Tuple[int, int]]:
+    """
+    Find the first and last columns containing ink.
+
+    Args:
+        img: Image to measure
+        threshold: Ink threshold
+
+    Returns:
+        (first_col, last_col) inclusive, or None if the image is entirely blank
+    """
+    ink = column_has_ink(img, threshold)
+    if not ink.any():
+        return None
+    first = int(ink.argmax())
+    last = len(ink) - 1 - int(ink[::-1].argmax())
+    return first, last
+
+
+class TrimResult(NamedTuple):
+    """Outcome of a ``trim_to_content`` call."""
+
+    image: Optional[Image.Image]  # None when the source was entirely blank
+    original_width: int
+    trimmed_left: int
+    trimmed_right: int
+
+    @property
+    def is_blank(self) -> bool:
+        """True when the source image carried no ink at all."""
+        return self.image is None
+
+    @property
+    def width(self) -> int:
+        """Width after trimming (0 for a blank source)."""
+        return 0 if self.image is None else self.image.width
+
+    @property
+    def removed(self) -> int:
+        """Total columns removed."""
+        return self.trimmed_left + self.trimmed_right
+
+
+def trim_to_content(
+    img: Image.Image,
+    threshold: int = DEFAULT_INK_THRESHOLD,
+    padding: int = 0,
+) -> TrimResult:
+    """
+    Crop blank columns off the left and right edges of an image.
+
+    Only the outer edges are considered. Blank columns *between* two pieces of
+    content are deliberately preserved — those are the plugin's own layout
+    (e.g. a logo on the left and a score on the right), and closing them up
+    would corrupt the design rather than reclaim dead space.
+
+    A plugin drawing on a non-black background is unaffected: every column of a
+    filled background carries ink, so there is nothing to trim.
+
+    Args:
+        img: Image to trim
+        threshold: Ink threshold
+        padding: Columns of the original blank margin to keep on each side, as
+            breathing room. Capped at what the margin actually contains, so
+            this never widens the image beyond its original bounds.
+
+    Returns:
+        TrimResult. When the image is entirely blank, ``image`` is None and the
+        caller decides whether to skip the plugin.
+    """
+    bounds = content_bounds(img, threshold)
+    if bounds is None:
+        return TrimResult(None, img.width, 0, 0)
+
+    first, last = bounds
+    pad = max(0, padding)
+    left = max(0, first - pad)
+    right = min(img.width, last + 1 + pad)
+
+    if left == 0 and right == img.width:
+        return TrimResult(img, img.width, 0, 0)
+
+    cropped = img.crop((left, 0, right, img.height))
+    return TrimResult(cropped, img.width, left, img.width - right)
+
+
+def edge_blank(
+    img: Image.Image, threshold: int = DEFAULT_INK_THRESHOLD
+) -> Tuple[int, int]:
+    """
+    Blank column counts at the left and right edges of an image.
+
+    Used to space items by *measured* separation rather than a flat added gap.
+    A fixed gap gets this wrong in both directions at once: card-style content
+    drawn flush to its own edges ends up nearly touching its neighbour, while
+    content that already carries wide margins gets pushed even further apart.
+
+    Args:
+        img: Image to measure
+        threshold: Ink threshold
+
+    Returns:
+        (left_blank, right_blank). For an entirely blank image both are the
+        full width, since there is no ink to be close to.
+    """
+    bounds = content_bounds(img, threshold)
+    if bounds is None:
+        return img.width, img.width
+    first, last = bounds
+    return first, img.width - 1 - last
+
+
+def separation_gap(
+    left_img: Image.Image,
+    right_img: Image.Image,
+    target: int,
+    minimum: int = 0,
+    threshold: int = DEFAULT_INK_THRESHOLD,
+) -> int:
+    """
+    Columns to insert between two images so their ink is ``target`` apart.
+
+    Only the shortfall is added: if the two images already carry enough blank
+    at the facing edges, nothing (beyond ``minimum``) is inserted.
+
+    Args:
+        left_img: Image on the left
+        right_img: Image on the right
+        target: Desired blank columns between the two pieces of ink
+        minimum: Floor applied regardless of what the images already have
+        threshold: Ink threshold
+
+    Returns:
+        Number of columns to insert, never negative
+    """
+    existing = edge_blank(left_img, threshold)[1] + edge_blank(right_img, threshold)[0]
+    return max(minimum, target - existing, 0)
+
+
+def blank_runs(
+    img: Image.Image,
+    min_run: int,
+    threshold: int = DEFAULT_INK_THRESHOLD,
+) -> List[Tuple[int, int]]:
+    """
+    Find maximal runs of blank columns at least ``min_run`` wide.
+
+    Distinguishes item boundaries from letter spacing. Measured on real
+    rendered text, the gaps *between characters* are a single column, while the
+    gaps a plugin puts *between items* are 8px and up (the stocks ticker uses
+    32px, baseball 48px). Treating any blank column as a cut point therefore
+    slices words in half; requiring a run excludes letter spacing.
+
+    Args:
+        img: Image to scan
+        min_run: Minimum consecutive blank columns to qualify
+        threshold: Ink threshold
+
+    Returns:
+        List of (start, end) half-open column ranges, in left-to-right order
+    """
+    blank = ~column_has_ink(img, threshold)
+    if not blank.any():
+        return []
+
+    # Vectorised run detection: pad with False so runs touching either edge get
+    # a boundary, then read starts and ends off the first difference. A Python
+    # loop here would be far too slow on a 17,000px ticker strip.
+    padded = np.concatenate(([False], blank, [False]))
+    diff = np.diff(padded.astype(np.int8))
+    starts = np.flatnonzero(diff == 1)
+    ends = np.flatnonzero(diff == -1)
+
+    long_enough = (ends - starts) >= max(1, min_run)
+    return list(zip(starts[long_enough].tolist(), ends[long_enough].tolist()))
+
+
+def find_item_boundary(
+    img: Image.Image,
+    target: int,
+    min_run: int,
+    threshold: int = DEFAULT_INK_THRESHOLD,
+) -> Optional[int]:
+    """
+    Find the column nearest ``target`` that sits inside a gap between items.
+
+    Used to narrow an oversized segment without cutting through a word. Only
+    runs of at least ``min_run`` blank columns are considered, so the
+    single-column gaps between characters are never chosen — cutting there
+    orphaned the tail of a word into the following cycle, which is how a lone
+    "y" from "Wednesday" ended up floating between two unrelated plugins.
+
+    Args:
+        img: Image to cut
+        target: Preferred cut column
+        min_run: Minimum blank-run width that counts as an item boundary
+        threshold: Ink threshold
+
+    Returns:
+        A column inside a qualifying gap, or None when the image has no such
+        gap at all — in which case the caller must not cut it.
+    """
+    runs = blank_runs(img, min_run, threshold)
+    if not runs:
+        return None
+
+    # Nearest point of the nearest run. For a run left of target that is its
+    # end (content resumes just after), for a run right of target its start
+    # (content stopped just before) — the right choice in both directions.
+    def clamp_to_run(run: Tuple[int, int]) -> int:
+        start, end = run
+        return max(start, min(target, end - 1))
+
+    return min((clamp_to_run(r) for r in runs), key=lambda c: abs(c - target))
+
+
+def find_blank_cut(
+    img: Image.Image,
+    target: int,
+    search_radius: int,
+    threshold: int = DEFAULT_INK_THRESHOLD,
+) -> int:
+    """
+    Find a column near ``target`` that carries no ink, so an image can be cut
+    there without slicing through a glyph or logo.
+
+    Used when a single oversized segment has to be narrowed to fit a width
+    budget. Cutting at an arbitrary column would leave half a character
+    hanging at the panel edge; snapping to the nearest gap hides the cut.
+
+    Args:
+        img: Image to cut
+        target: Preferred cut column
+        search_radius: How far either side of ``target`` to look
+        threshold: Ink threshold
+
+    Returns:
+        A blank column within the search window, or ``target`` clamped to the
+        image bounds when the window contains no blank column at all.
+    """
+    width = img.width
+    target = max(0, min(target, width))
+    if search_radius <= 0 or width == 0:
+        return target
+
+    ink = column_has_ink(img, threshold)
+
+    # target may legitimately equal width (a cut after the last column), but
+    # there is no column to inspect there, so both bounds stop at width - 1.
+    lo = max(0, min(target - search_radius, width - 1))
+    hi = max(0, min(target + search_radius, width - 1))
+
+    # Walk outwards from target so the nearest gap wins.
+    for offset in range(0, search_radius + 1):
+        right = target + offset
+        if lo <= right <= hi and not ink[right]:
+            return right
+        left = target - offset
+        if lo <= left <= hi and not ink[left]:
+            return left
+
+    return target
+
+
+class DeadWindowStats(NamedTuple):
+    """How much of a composed ticker reads as blank to a viewer."""
+
+    total_windows: int
+    dead_windows: int
+    longest_dead_run: int  # consecutive dead windows (i.e. scroll steps)
+
+    @property
+    def dead_ratio(self) -> float:
+        """Fraction of viewport positions that are effectively blank."""
+        if self.total_windows <= 0:
+            return 0.0
+        return self.dead_windows / self.total_windows
+
+
+def dead_window_stats(
+    img: Image.Image,
+    viewport_width: int,
+    threshold: int = DEFAULT_INK_THRESHOLD,
+    dead_ratio: float = DEFAULT_DEAD_WINDOW_RATIO,
+    step: int = 1,
+) -> DeadWindowStats:
+    """
+    Slide a viewport across a composed ticker image and count how many
+    positions are effectively blank.
+
+    This models what the viewer actually experiences: the ticker is only ever
+    seen ``viewport_width`` columns at a time, so a stretch of blank wider than
+    the viewport becomes a period where the panel looks switched off. Measuring
+    per-window rather than per-column is what makes the result correspond to
+    perceived dead time.
+
+    Args:
+        img: Composed ticker image
+        viewport_width: Display width in pixels
+        threshold: Ink threshold
+        dead_ratio: Fraction of blank columns for a window to count as dead
+        step: Column stride between sampled windows. 1 is exact; larger values
+            trade precision for speed on very wide images.
+
+    Returns:
+        DeadWindowStats. ``longest_dead_run`` is in units of ``step`` columns,
+        so multiply by ``step`` for pixels.
+    """
+    if viewport_width <= 0 or img.width <= 0:
+        return DeadWindowStats(0, 0, 0)
+
+    ink = column_has_ink(img, threshold)
+    step = max(1, step)
+
+    # Prefix sum of ink counts lets each window be evaluated in constant time,
+    # instead of re-summing viewport_width columns per position.
+    prefix = np.concatenate(([0], np.cumsum(ink)))
+
+    # Only whole windows are sampled; a partial tail window would report
+    # artificially dead because it has fewer columns to draw ink from.
+    last_start = img.width - viewport_width
+    if last_start < 0:
+        # Image narrower than the viewport — evaluate it as a single window.
+        blank_cols = len(ink) - int(prefix[-1])
+        is_dead = blank_cols >= dead_ratio * len(ink)
+        return DeadWindowStats(1, 1 if is_dead else 0, 1 if is_dead else 0)
+
+    starts = np.arange(0, last_start + 1, step)
+    ink_counts = prefix[starts + viewport_width] - prefix[starts]
+    blank_counts = viewport_width - ink_counts
+    dead = blank_counts >= dead_ratio * viewport_width
+
+    longest = _longest_true_run(dead)
+    return DeadWindowStats(len(starts), int(dead.sum()), longest)
+
+
+class CoverageStats(NamedTuple):
+    """How well-filled the viewport stays as the ticker scrolls past."""
+
+    total_windows: int
+    mean_ink_ratio: float       # average fraction of the viewport carrying ink
+    min_ink_ratio: float        # worst viewport position in the cycle
+    sparse_windows: int         # positions below the "looks empty" threshold
+    longest_sparse_run: int     # consecutive sparse positions, in steps
+
+    @property
+    def sparse_ratio(self) -> float:
+        """Fraction of viewport positions that read as near-empty."""
+        if self.total_windows <= 0:
+            return 0.0
+        return self.sparse_windows / self.total_windows
+
+
+def window_coverage_stats(
+    img: Image.Image,
+    viewport_width: int,
+    threshold: int = DEFAULT_INK_THRESHOLD,
+    sparse_ink_ratio: float = 0.10,
+    step: int = 1,
+) -> CoverageStats:
+    """
+    Measure how full the viewport stays across a whole scroll cycle.
+
+    ``dead_window_stats`` only catches viewport positions that are *entirely*
+    blank. That misses the more common complaint: a position holding one narrow
+    sliver of content at the very edge, with the other 90% black. Such a
+    position is not "dead" by that definition but still looks switched off.
+    This function grades every position by how much ink it carries, so
+    "there is always something to see" becomes measurable.
+
+    Args:
+        img: Composed ticker image
+        viewport_width: Display width in pixels
+        threshold: Ink threshold
+        sparse_ink_ratio: A position with less than this fraction of inked
+            columns counts as reading near-empty
+        step: Column stride between sampled positions
+
+    Returns:
+        CoverageStats
+    """
+    if viewport_width <= 0 or img.width <= 0:
+        return CoverageStats(0, 0.0, 0.0, 0, 0)
+
+    ink = column_has_ink(img, threshold)
+    step = max(1, step)
+    prefix = np.concatenate(([0], np.cumsum(ink)))
+
+    last_start = img.width - viewport_width
+    if last_start < 0:
+        ratio = float(prefix[-1]) / viewport_width
+        sparse = ratio < sparse_ink_ratio
+        return CoverageStats(1, ratio, ratio, 1 if sparse else 0, 1 if sparse else 0)
+
+    starts = np.arange(0, last_start + 1, step)
+    ratios = (prefix[starts + viewport_width] - prefix[starts]) / viewport_width
+    sparse_flags = ratios < sparse_ink_ratio
+
+    return CoverageStats(
+        total_windows=len(starts),
+        mean_ink_ratio=float(ratios.mean()),
+        min_ink_ratio=float(ratios.min()),
+        sparse_windows=int(sparse_flags.sum()),
+        longest_sparse_run=_longest_true_run(sparse_flags),
+    )
+
+
+def _longest_true_run(flags: np.ndarray) -> int:
+    """Length of the longest consecutive run of True in a boolean array."""
+    if flags.size == 0 or not flags.any():
+        return 0
+    # Reset a running counter at every False by subtracting the cumulative max
+    # of the counter's value at the preceding False positions.
+    idx = np.arange(len(flags))
+    not_flag = ~flags
+    # For each position, the index of the most recent False at or before it.
+    last_false = np.maximum.accumulate(np.where(not_flag, idx, -1))
+    run_lengths = idx - last_false
+    return int(run_lengths[flags].max())

src/vegas_mode/plugin_adapter.py

@@ -8,9 +8,16 @@ implement get_vegas_content() and fallback capture of display() output.
 import logging
 import threading
 import time
+from contextlib import nullcontext
 from typing import Optional, List, Any, Tuple, Union, TYPE_CHECKING
 from PIL import Image
 
+from src.vegas_mode.geometry import (
+    blank_runs,
+    separation_gap,
+    trim_to_content,
+)
+
 if TYPE_CHECKING:
     from src.plugin_system.base_plugin import BasePlugin
 
@@ -26,14 +33,21 @@ class PluginAdapter:
     2. Fallback: Capture display_manager.image after calling plugin.display()
     """
 
-    def __init__(self, display_manager: Any):
+    def __init__(self, display_manager: Any, config: Optional[Any] = None):
         """
         Initialize the plugin adapter.
 
         Args:
             display_manager: DisplayManager instance for fallback capture
+            config: VegasModeConfig controlling trim behaviour. When omitted,
+                trimming runs with the dataclass defaults, so existing callers
+                and tests keep working unchanged.
         """
         self.display_manager = display_manager
+        if config is None:
+            from src.vegas_mode.config import VegasModeConfig
+            config = VegasModeConfig()
+        self.config = config
         # Handle both property and method access patterns
         self.display_width = (
             display_manager.width() if callable(display_manager.width)
@@ -49,12 +63,18 @@ class PluginAdapter:
         self._cache_lock = threading.Lock()
         self._cache_ttl = 5.0  # Cache for 5 seconds
 
+        # Per-plugin rotation offset, so a plugin whose content exceeds its
+        # width budget shows a different slice on each cycle rather than
+        # always the same opening items.
+        self._item_offsets: dict = {}
+
         logger.info(
             "PluginAdapter initialized: display=%dx%d",
             self.display_width, self.display_height
         )
 
-    def get_content(self, plugin: 'BasePlugin', plugin_id: str) -> Optional[List[Image.Image]]:
+    def get_content(self, plugin: 'BasePlugin', plugin_id: str,
+                    offscreen_only: bool = False) -> Optional[List[Image.Image]]:
         """
         Get scrollable content from a plugin.
 
@@ -63,6 +83,13 @@ class PluginAdapter:
         Args:
             plugin: Plugin instance to get content from
             plugin_id: Plugin identifier for logging
+            offscreen_only: Skip every path that touches the shared display
+                canvas, for callers running off the render thread. The canvas
+                and the matrix proxy are process-wide mutable state, so
+                narrowing or capturing through them from another thread would
+                corrupt the frame the render loop is pushing. Returns None when
+                the plugin can only be served that way, leaving the caller to
+                fetch it on the render thread.
 
         Returns:
             List of PIL Images representing plugin content, or None if no content
@@ -86,32 +113,38 @@ class PluginAdapter:
         has_native = hasattr(plugin, 'get_vegas_content')
         logger.info("[%s] Has get_vegas_content: %s", plugin_id, has_native)
         if has_native:
-            content = self._get_native_content(plugin, plugin_id)
+            content = self._get_native_content(plugin, plugin_id, offscreen_only)
             if content:
                 total_width = sum(img.width for img in content)
                 logger.info(
                     "[%s] Native content SUCCESS: %d images, %dpx total",
                     plugin_id, len(content), total_width
                 )
-                self._cache_content(plugin_id, content)
-                return content
+                return self._finalize(content, plugin_id, 'native', plugin)
             logger.info("[%s] Native content returned None", plugin_id)
 
         # Try to get scroll_helper's cached image (for scrolling plugins like stocks/odds)
         has_scroll_helper = hasattr(plugin, 'scroll_helper')
         logger.info("[%s] Has scroll_helper: %s", plugin_id, has_scroll_helper)
-        content = self._get_scroll_helper_content(plugin, plugin_id)
+        content = self._get_scroll_helper_content(plugin, plugin_id, offscreen_only)
         if content:
             total_width = sum(img.width for img in content)
             logger.info(
                 "[%s] ScrollHelper content SUCCESS: %d images, %dpx total",
                 plugin_id, len(content), total_width
             )
-            self._cache_content(plugin_id, content)
-            return content
+            return self._finalize(content, plugin_id, 'scroll_helper', plugin)
         if has_scroll_helper:
             logger.info("[%s] ScrollHelper content returned None", plugin_id)
 
+        if offscreen_only:
+            # Display capture needs the shared canvas; leave it to the caller.
+            logger.info(
+                "[%s] Needs display capture, deferring to the render thread",
+                plugin_id
+            )
+            return None
+
         # Fall back to display capture
         logger.info("[%s] Trying fallback display capture...", plugin_id)
         content = self._capture_display_content(plugin, plugin_id)
@@ -121,8 +154,7 @@ class PluginAdapter:
                 "[%s] Fallback capture SUCCESS: %d images, %dpx total",
                 plugin_id, len(content), total_width
             )
-            self._cache_content(plugin_id, content)
-            return content
+            return self._finalize(content, plugin_id, 'fallback', plugin)
 
         logger.warning(
             "[%s] NO CONTENT from any method (native=%s, scroll_helper=%s, fallback=tried)",
@@ -130,8 +162,397 @@ class PluginAdapter:
         )
         return None
 
+    def _finalize(
+        self, images: List[Image.Image], plugin_id: str, source: str,
+        plugin: Optional['BasePlugin'] = None
+    ) -> Optional[List[Image.Image]]:
+        """
+        Trim dead space off a segment, then cache it.
+
+        Every content path funnels through here so trimming is applied
+        uniformly. Previously only the scroll_helper path had its margins
+        stripped, which left plugins that render onto a full-display canvas
+        contributing their entire blank canvas to the ticker.
+
+        Each image is trimmed independently because compose_scroll_content()
+        treats every image as its own item and inserts separator_width between
+        them — so a per-image trim is what makes that separator the real gap.
+
+        Args:
+            images: Raw content from one of the fetch paths
+            plugin_id: Plugin identifier for logging
+            source: Which path produced the content, for logging
+
+        Returns:
+            Trimmed image list, or None if nothing worth showing remains
+        """
+        if not self.config.auto_trim:
+            # Trimming is off, but the width budget is a separate concern —
+            # turning off margin cropping should not let one plugin hold the
+            # panel for minutes. Skipping it here previously let a 14,848px
+            # segment through untouched.
+            kept = self._apply_width_budget(list(images), plugin_id, plugin)
+            self._cache_content(plugin_id, kept)
+            return kept
+
+        original_width = sum(img.width for img in images)
+        kept: List[Image.Image] = []
+        dropped_blank = 0
+
+        for img in images:
+            result = trim_to_content(
+                img,
+                threshold=self.config.trim_threshold,
+                padding=self.config.content_padding,
+            )
+            if result.is_blank:
+                dropped_blank += 1
+                continue
+            kept.append(result.image)
+
+        if not kept:
+            logger.info(
+                "[%s] All %d image(s) from %s were blank — contributing nothing",
+                plugin_id, len(images), source
+            )
+            return None
+
+        trimmed_width = sum(img.width for img in kept)
+
+        if trimmed_width < self.config.min_plugin_width:
+            logger.info(
+                "[%s] Trimmed content %dpx is below min_plugin_width %dpx — skipping",
+                plugin_id, trimmed_width, self.config.min_plugin_width
+            )
+            return None
+
+        if trimmed_width != original_width or dropped_blank:
+            logger.info(
+                "[%s] Trimmed %s content: %dpx -> %dpx (%.0f%% reclaimed), "
+                "%d image(s) kept, %d blank dropped",
+                plugin_id, source, original_width, trimmed_width,
+                100.0 * (original_width - trimmed_width) / original_width
+                if original_width else 0.0,
+                len(kept), dropped_blank
+            )
+
+        kept = self._apply_width_budget(kept, plugin_id, plugin)
+
+        self._cache_content(plugin_id, kept)
+        return kept
+
+    def _capture(self):
+        """
+        Context manager suppressing hardware writes while plugin render code runs.
+
+        Degrades to a no-op when the display manager predates capture_mode. As
+        with _render_at, losing the suppression risks a visible flash, whereas
+        raising would be swallowed by the broad handlers upstream and drop the
+        plugin's content entirely — much worse.
+        """
+        capture_mode = getattr(self.display_manager, 'capture_mode', None)
+        if capture_mode is None:
+            logger.debug(
+                "display_manager has no capture_mode(); plugin writes during "
+                "content capture may reach the panel"
+            )
+            return nullcontext()
+        return capture_mode()
+
+    def _render_at(self, width: int):
+        """
+        Context manager narrowing the plugin-facing canvas to ``width``.
+
+        Degrades to a no-op when the display manager predates render_size (a
+        third-party or older test harness). Losing the narrowing is a cosmetic
+        regression; raising here would be caught by the broad handlers upstream
+        and silently drop the plugin's content entirely.
+        """
+        render_size = getattr(self.display_manager, 'render_size', None)
+        if render_size is None:
+            logger.debug(
+                "display_manager has no render_size(); Vegas width requests "
+                "will be ignored"
+            )
+            return nullcontext()
+        return render_size(width)
+
+    def resolve_render_width(self, plugin: 'BasePlugin', plugin_id: str) -> int:
+        """
+        Width to tell a plugin it has while it renders for the ticker.
+
+        Resolution order, most specific first:
+          1. the plugin's own ``vegas_width_pct`` config value
+          2. the global ``vegas_scroll.render_width_pct``
+          3. the full panel width
+
+        A percentage rather than an absolute width so one setting travels
+        across panel sizes.
+
+        Args:
+            plugin: Plugin instance, consulted for a per-plugin override
+            plugin_id: Plugin identifier for logging
+
+        Returns:
+            Target width in pixels, never wider than the panel
+        """
+        pct = self.config.render_width_pct
+
+        plugin_cfg = getattr(plugin, 'config', None)
+        if isinstance(plugin_cfg, dict):
+            raw = plugin_cfg.get('vegas_width_pct')
+            if raw not in (None, ''):
+                try:
+                    candidate = int(raw)
+                except (TypeError, ValueError):
+                    logger.warning(
+                        "[%s] Invalid vegas_width_pct %r, ignoring", plugin_id, raw)
+                else:
+                    if 10 <= candidate <= 100:
+                        pct = candidate
+                    else:
+                        logger.warning(
+                            "[%s] vegas_width_pct %d out of range 10-100, ignoring",
+                            plugin_id, candidate)
+
+        if pct >= 100:
+            return self.display_width
+        return max(1, int(self.display_width * pct / 100))
+
+    def _row_gap(self, left: Image.Image, right: Image.Image) -> int:
+        """
+        Gap the compositor will insert between two of a plugin's rows.
+
+        Mirrors RenderPipeline._join_plugin_rows so the width budget measures
+        what will actually be rendered.
+        """
+        return separation_gap(
+            left, right,
+            target=max(0, self.config.min_content_separation),
+            minimum=max(0, self.config.intra_plugin_gap),
+            threshold=self.config.trim_threshold,
+        )
+
+    def _plugin_setting(self, plugin: 'BasePlugin', key: str):
+        """Read a per-plugin config override, or None if absent."""
+        plugin_cfg = getattr(plugin, 'config', None)
+        if not isinstance(plugin_cfg, dict):
+            return None
+        value = plugin_cfg.get(key)
+        return None if value in (None, '') else value
+
+    def resolve_overflow_mode(self, plugin: 'BasePlugin', plugin_id: str) -> str:
+        """
+        How to handle content that exceeds this plugin's width budget.
+
+        'rotate' advances a window each cycle so everything is seen eventually,
+        which suits interchangeable items. 'truncate' always shows the start,
+        which suits ordered content — a league table that shows ranks 1-6 and
+        then resumes at 7 two rotations later reads as out of order, and nobody
+        needs rank 23 in a ticker anyway.
+
+        Per-plugin ``vegas_overflow`` wins over the global ``overflow_mode``.
+        """
+        raw = self._plugin_setting(plugin, 'vegas_overflow')
+        if raw is not None:
+            candidate = str(raw).strip().lower()
+            if candidate in ('rotate', 'truncate'):
+                return candidate
+            logger.warning(
+                "[%s] Invalid vegas_overflow %r, expected 'rotate' or 'truncate'",
+                plugin_id, raw
+            )
+        return self.config.overflow_mode
+
+    def _width_budget(self, plugin: Optional['BasePlugin'] = None,
+                      plugin_id: str = '') -> int:
+        """
+        Maximum columns one plugin may occupy in a cycle. 0 means unlimited.
+
+        A per-plugin ``vegas_max_width_screens`` overrides the global ratio, so
+        content that has to stay whole can be given room (or uncapped with 0)
+        without lifting the cap on every ticker.
+        """
+        ratio = self.config.max_plugin_width_ratio
+
+        if plugin is not None:
+            raw = self._plugin_setting(plugin, 'vegas_max_width_screens')
+            if raw is not None:
+                try:
+                    candidate = float(raw)
+                except (TypeError, ValueError):
+                    logger.warning(
+                        "[%s] Invalid vegas_max_width_screens %r, ignoring",
+                        plugin_id, raw
+                    )
+                else:
+                    if candidate >= 0:
+                        ratio = candidate
+                    else:
+                        logger.warning(
+                            "[%s] vegas_max_width_screens must be >= 0, got %s",
+                            plugin_id, candidate
+                        )
+
+        if ratio <= 0:
+            return 0
+        return int(self.display_width * ratio)
+
+    def _apply_width_budget(
+        self, images: List[Image.Image], plugin_id: str,
+        plugin: Optional['BasePlugin'] = None
+    ) -> List[Image.Image]:
+        """
+        Hold one plugin to its share of a cycle.
+
+        A ticker returning 7,000px would otherwise own the panel for over two
+        minutes, which defeats the point of a rotation. Overflow is deferred
+        rather than discarded: the starting offset advances each time this
+        plugin is fetched, so later items appear on subsequent cycles instead
+        of never being seen.
+
+        Args:
+            images: Trimmed images for this plugin
+            plugin_id: Plugin identifier, used to track its rotation offset
+
+        Returns:
+            Images that fit the budget, starting from the plugin's current
+            rotation offset.
+        """
+        budget = self._width_budget(plugin, plugin_id)
+        mode = (self.resolve_overflow_mode(plugin, plugin_id)
+                if plugin is not None else self.config.overflow_mode)
+
+        # Count the gaps the compositor will actually insert, not just the
+        # pixels of the rows — otherwise a plugin with many rows quietly
+        # occupies far more of the panel than its budget allows. These must use
+        # the same measured rule as RenderPipeline._join_plugin_rows; assuming
+        # the flat intra_plugin_gap here under-counted by up to
+        # (min_content_separation - intra_plugin_gap) per row.
+        total = sum(img.width for img in images) + sum(
+            self._row_gap(images[i], images[i + 1]) for i in range(len(images) - 1)
+        )
+
+        if not budget or total <= budget:
+            # Fits, so reset rotation — the whole segment is being shown.
+            self._item_offsets.pop(plugin_id, None)
+            return images
+
+        if len(images) == 1:
+            return [self._crop_to_budget(images[0], budget, plugin_id, mode)]
+
+        if mode == 'truncate':
+            # Ordered content: always show from the top. Deliberately does not
+            # advance the offset, so the same opening items appear every time
+            # rather than the viewer being shown the middle of a ranked list.
+            start = 0
+        else:
+            start = self._item_offsets.get(plugin_id, 0) % len(images)
+        selected: List[Image.Image] = []
+        used = 0
+        consumed = 0
+
+        # Walk forward from the rotation offset, taking whole items only, so a
+        # cut never lands in the middle of one.
+        for step in range(len(images)):
+            img = images[(start + step) % len(images)]
+            cost = img.width
+            if selected:
+                cost += self._row_gap(selected[-1], img)
+            if selected and used + cost > budget:
+                break
+            selected.append(img)
+            used += cost
+            consumed += 1
+
+        if mode == 'truncate':
+            logger.info(
+                "[%s] Width budget %dpx: showing the first %d of %d row(s) "
+                "(%dpx incl. gaps); the rest are not shown (overflow=truncate)",
+                plugin_id, budget, len(selected), len(images), used
+            )
+        else:
+            self._item_offsets[plugin_id] = (start + consumed) % len(images)
+            logger.info(
+                "[%s] Width budget %dpx: showing %d of %d row(s) (%dpx incl. gaps) "
+                "from offset %d; remainder deferred to a later cycle",
+                plugin_id, budget, len(selected), len(images), used, start
+            )
+        return selected
+
+    def _crop_to_budget(
+        self, img: Image.Image, budget: int, plugin_id: str,
+        mode: str = 'rotate'
+    ) -> Image.Image:
+        """
+        Narrow a single oversized image to the budget, advancing a window
+        through it across cycles.
+
+        The cut is snapped to the nearest blank column so it does not slice
+        through a glyph or logo and leave half a character at the panel edge.
+        """
+        if mode == 'truncate':
+            # Always the start of the strip, so a ranked table is never entered
+            # from the middle.
+            offset = 0
+        else:
+            offset = self._item_offsets.get(plugin_id, 0)
+            if offset >= img.width:
+                offset = 0
+
+        # Cut only where the plugin left a real gap between items. Snapping to
+        # any blank column used to pick the single-column gaps between
+        # characters, splitting a word and orphaning its tail into the next
+        # cycle — a lone "y" from "Wednesday" floating between two unrelated
+        # plugins. Overshooting the budget is the lesser evil.
+        min_run = max(2, self.config.min_cut_gap)
+        gaps = blank_runs(img, min_run, self.config.trim_threshold)
+
+        if not gaps:
+            # No internal gaps means continuous content — a map, a chart, a
+            # photo — where any column is as good as any other, so cut to the
+            # budget exactly. The gap rule exists to protect discrete items
+            # (words, ticker entries); it would be wrong to let a solid image
+            # escape the cap in its name.
+            end = min(offset + budget, img.width)
+            if mode != 'truncate':
+                self._item_offsets[plugin_id] = 0 if end >= img.width else end
+            logger.info(
+                "[%s] Width budget %dpx: cropped continuous %dpx image to "
+                "[%d:%d] (no item gaps of %dpx+ to align to)%s",
+                plugin_id, budget, img.width, offset, end, min_run,
+                "" if mode != 'truncate' else "; showing the start only"
+            )
+            return img.crop((offset, 0, end, img.height))
+
+        # Cut mid-gap so the content either side keeps some breathing room.
+        cuts = sorted({0, img.width} | {(a + b) // 2 for a, b in gaps})
+
+        start = max((c for c in cuts if c <= offset), default=0)
+        later = [c for c in cuts if c > start]
+        if not later:
+            end = img.width
+        else:
+            within = [c for c in later if c <= start + budget]
+            # No boundary inside the budget: take the next one and overrun,
+            # because the alternative is cutting through an item.
+            end = max(within) if within else min(later)
+
+        if mode != 'truncate':
+            # Next cycle resumes where this one stopped; wrap when the strip ends.
+            self._item_offsets[plugin_id] = 0 if end >= img.width else end
+
+        logger.info(
+            "[%s] Width budget %dpx: cropped single %dpx image to [%d:%d] "
+            "(%dpx) at item boundaries, %s",
+            plugin_id, budget, img.width, start, end, end - start,
+            "showing the start only (overflow=truncate)"
+            if mode == 'truncate' else "window advances next cycle"
+        )
+        return img.crop((start, 0, end, img.height))
+
     def _get_native_content(
-        self, plugin: 'BasePlugin', plugin_id: str
+        self, plugin: 'BasePlugin', plugin_id: str, offscreen_only: bool = False
     ) -> Optional[List[Image.Image]]:
         """
         Get content via plugin's native get_vegas_content() method.
@@ -145,7 +566,40 @@ class PluginAdapter:
         """
         try:
             logger.info("[%s] Native: calling get_vegas_content()", plugin_id)
-            result = plugin.get_vegas_content()
+
+            # Tell the plugin how much width the ticker wants it to use, and
+            # narrow the canvas for the duration of the call. A plugin that
+            # sizes its own images from display_manager.matrix.width picks up
+            # the narrower value with no changes of its own; one that wants to
+            # be explicit can read get_vegas_render_width().
+            render_width = self.resolve_render_width(plugin, plugin_id)
+            if render_width != self.display_width:
+                logger.info(
+                    "[%s] Native: requesting %dpx instead of %dpx",
+                    plugin_id, render_width, self.display_width
+                )
+
+            plugin._vegas_render_width = render_width
+            try:
+                # capture_mode unconditionally, even at full width. Building
+                # Vegas content is an off-screen operation, but a plugin is free
+                # to call update_display() while doing it — and outside
+                # capture_mode that write lands on the hardware, flashing the
+                # panel mid-scroll. The narrowing context is separate because it
+                # is a no-op at full width.
+                if offscreen_only:
+                    # _render_at swaps the shared canvas, so it is unsafe here.
+                    # _vegas_render_width is set regardless: a plugin reading
+                    # get_vegas_render_width() still gets its narrow size, and
+                    # one that only reads matrix.width renders full width and is
+                    # trimmed instead.
+                    with self._capture():
+                        result = plugin.get_vegas_content()
+                else:
+                    with self._capture(), self._render_at(render_width):
+                        result = plugin.get_vegas_content()
+            finally:
+                plugin._vegas_render_width = None
 
             if result is None:
                 logger.info("[%s] Native: get_vegas_content() returned None", plugin_id)
@@ -223,7 +677,7 @@ class PluginAdapter:
             return None
 
     def _get_scroll_helper_content(
-        self, plugin: 'BasePlugin', plugin_id: str
+        self, plugin: 'BasePlugin', plugin_id: str, offscreen_only: bool = False
     ) -> Optional[List[Image.Image]]:
         """
         Get content from plugin's scroll_helper if available.
@@ -257,6 +711,13 @@ class PluginAdapter:
                     "[%s] scroll_helper.cached_image is None, triggering content generation",
                     plugin_id
                 )
+                if offscreen_only:
+                    # Generating it calls display(), which needs the canvas.
+                    logger.info(
+                        "[%s] scroll_helper cache empty; deferring generation "
+                        "to the render thread", plugin_id
+                    )
+                    return None
                 # Try to trigger scroll content generation
                 cached_image = self._trigger_scroll_content_generation(
                     plugin, plugin_id, scroll_helper
@@ -405,7 +866,7 @@ class PluginAdapter:
             # Save display state to restore after
             original_image = self.display_manager.image.copy()
 
-            with self.display_manager.capture_mode():
+            with self._capture():
                 # Method 1: Try _create_scrolling_display (stocks pattern)
                 if hasattr(plugin, '_create_scrolling_display'):
                     logger.info(
@@ -497,7 +958,18 @@ class PluginAdapter:
 
             # Clear and call plugin display — use capture_mode to suppress hardware writes
             # that plugins may trigger internally via update_display().
-            with self.display_manager.capture_mode():
+            #
+            # render_size narrows the canvas the plugin lays out against, so a
+            # plugin that spreads across the whole panel produces a compact
+            # arrangement rather than one that has to be cropped afterwards.
+            render_width = self.resolve_render_width(plugin, plugin_id)
+            if render_width != self.display_width:
+                logger.info(
+                    "[%s] Fallback: rendering at %dpx instead of %dpx",
+                    plugin_id, render_width, self.display_width
+                )
+
+            with self._capture(), self._render_at(render_width):
                 self.display_manager.clear()
                 logger.info("[%s] Fallback: display cleared, calling display()", plugin_id)
 
@@ -531,7 +1003,7 @@ class PluginAdapter:
                     plugin_id
                 )
                 # Try once more with force_clear=True
-                with self.display_manager.capture_mode():
+                with self._capture(), self._render_at(render_width):
                     self.display_manager.clear()
                     plugin.display(force_clear=True)
                     captured = self.display_manager.image.copy()
@@ -663,6 +1135,53 @@ class PluginAdapter:
             else:
                 self._content_cache.clear()
 
+    def invalidate_plugin_scroll_cache(
+        self, plugin: 'BasePlugin', plugin_id: str
+    ) -> bool:
+        """
+        Drop a plugin's own cached scroll image so its visual is rebuilt.
+
+        Invalidating only this adapter's cache is not enough. A plugin that
+        composes a scroll strip hands back the *same* image every time until its
+        own cache is cleared — the sports plugins' ``get_vegas_content()``
+        regenerates only "if the cache is empty" — so without this a segment
+        keeps rendering whatever data it was first built from. That is how a
+        game that was live last night can still be displayed as live the next
+        morning.
+
+        Two layouts to cover: a helper directly on the plugin (stocks, news,
+        odds-ticker) and one owned by a scroll-display manager (the sports
+        scoreboards). ``cached_image`` and ``cached_array`` must be cleared
+        together, since the array is the image's numpy mirror and code paths
+        read whichever is convenient.
+
+        Returns:
+            True if a cache was found and cleared.
+        """
+        cleared = False
+        for owner in (plugin, getattr(plugin, '_scroll_manager', None),
+                      getattr(plugin, 'scroll_manager', None)):
+            if owner is None:
+                continue
+            helper = getattr(owner, 'scroll_helper', None)
+            if helper is None:
+                continue
+            try:
+                if getattr(helper, 'cached_image', None) is not None:
+                    helper.cached_image = None
+                    cleared = True
+                if getattr(helper, 'cached_array', None) is not None:
+                    helper.cached_array = None
+                    cleared = True
+            except Exception:  # pylint: disable=broad-except
+                logger.exception(
+                    "[%s] Could not clear scroll cache on %s",
+                    plugin_id, type(owner).__name__
+                )
+        if cleared:
+            logger.debug("[%s] Cleared plugin scroll cache", plugin_id)
+        return cleared
+
     def get_content_type(self, plugin: 'BasePlugin', plugin_id: str) -> str:
         """
         Get the type of content a plugin provides.

src/vegas_mode/render_pipeline.py

@@ -6,6 +6,7 @@ Uses the existing ScrollHelper for numpy-optimized scroll operations.
 """
 
 import logging
+import os
 import time
 import threading
 from collections import deque
@@ -14,6 +15,7 @@ from PIL import Image
 
 from src.common.scroll_helper import ScrollHelper
 from src.vegas_mode.config import VegasModeConfig
+from src.vegas_mode.geometry import separation_gap
 from src.vegas_mode.stream_manager import StreamManager
 
 if TYPE_CHECKING:
@@ -34,6 +36,10 @@ class RenderPipeline:
     - Track scroll cycle completion
     """
 
+    # Minimum gap between fetches of canvas-bound plugins, so their individual
+    # stalls land in separate moments rather than one run of hitches.
+    DEFERRED_DRAIN_INTERVAL = 2.0
+
     def __init__(
         self,
         config: VegasModeConfig,
@@ -66,10 +72,6 @@ class RenderPipeline:
             else display_manager.height
         )
 
-        # Reusable blank frame for cycle-end pushes (allocated lazily,
-        # re-blacked before each reuse)
-        self._blank_frame = None
-
         # ScrollHelper for optimized scrolling
         self.scroll_helper = ScrollHelper(
             self.display_width,
@@ -85,6 +87,14 @@ class RenderPipeline:
         self._staging_scroll_image: Optional[Image.Image] = None
         self._buffer_lock = threading.Lock()
 
+        # Group prepared off the render thread, waiting to be appended.
+        self._prepared_group = None
+        # Plugins that need the shared canvas, appended one at a time.
+        self._deferred_queue: List[str] = []
+        self._last_drain_time = 0.0
+        self._prefetch_thread: Optional[threading.Thread] = None
+        self._prefetch_lock = threading.Lock()
+
         # Render state
         self._is_rendering = False
         self._cycle_complete = False
@@ -114,6 +124,7 @@ class RenderPipeline:
         """Configure ScrollHelper with current settings."""
         self.scroll_helper.set_frame_based_scrolling(self.config.frame_based_scrolling)
         self.scroll_helper.set_scroll_delay(self.config.scroll_delay)
+        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:
@@ -141,23 +152,37 @@ class RenderPipeline:
             True if composition successful
         """
         try:
-            # Get all buffered content
-            images = self.stream_manager.get_all_content_for_composition()
+            # Content grouped by plugin, so a separator can be placed at the
+            # plugin boundaries only.
+            grouped = self.stream_manager.get_grouped_content_for_composition()
 
-            if not images:
+            if not grouped:
                 logger.warning("No content available for composition")
                 return False
 
-            # Add separator gaps between images
-            content_with_gaps = []
-            for i, img in enumerate(images):
-                content_with_gaps.append(img)
+            # Collapse each plugin's rows into a single block, joined by
+            # intra_plugin_gap. ScrollHelper applies one uniform gap between the
+            # items it is given, so handing it one item per plugin is what makes
+            # separator_width mean "between plugins" instead of "between every
+            # row". Without this, a per-row ticker such as the F1 scoreboard got
+            # the full separator between each of its ~116 rows.
+            blocks = []
+            total_rows = 0
+            for plugin_id, images in grouped:
+                total_rows += len(images)
+                blocks.append(self._join_plugin_rows(images))
 
-            # Create scrolling image via ScrollHelper
+            # Create scrolling image via ScrollHelper.
+            #
+            # lead_gap is explicit because ScrollHelper otherwise prepends a
+            # full display width of black — appropriate for a standalone ticker
+            # scrolling in from off-screen, but in Vegas mode it is charged
+            # once per cycle and reads as the panel switching off.
             self.scroll_helper.create_scrolling_image(
-                content_items=content_with_gaps,
+                content_items=blocks,
                 item_gap=self.config.separator_width,
-                element_gap=0
+                element_gap=0,
+                lead_gap=self.config.lead_in_width
             )
 
             # Verify scroll image was created successfully
@@ -177,11 +202,16 @@ class RenderPipeline:
             self._cycle_complete = False
 
             logger.info(
-                "Composed scroll image: %dx%d, %d plugins, %d items",
+                "Composed scroll image: %dx%d, %d plugin block(s), %d rows, "
+                "separator=%dpx between plugins, rows spaced to %dpx of ink "
+                "(min added %dpx)",
                 self.scroll_helper.cached_image.width if self.scroll_helper.cached_image else 0,
                 self.display_height,
-                len(self._segments_in_scroll),
-                len(images)
+                len(blocks),
+                total_rows,
+                self.config.separator_width,
+                self.config.min_content_separation,
+                self.config.intra_plugin_gap,
             )
 
             return True
@@ -191,6 +221,264 @@ class RenderPipeline:
             logger.exception("Error composing scroll content")
             return False
 
+    def needs_extension(self) -> bool:
+        """
+        Whether the strip should be extended with the next group of plugins.
+
+        Cheap enough to call every frame: it is arithmetic over cached state.
+        """
+        if not self.config.continuous_scroll or not self.scroll_helper.cached_image:
+            return False
+        threshold = int(self.display_width * self.config.extend_threshold_screens)
+        return self.scroll_helper.remaining_unscrolled() <= threshold
+
+    def start_prefetch(self) -> None:
+        """
+        Begin preparing the next group in the background, if not already doing so.
+
+        This is what makes the join seamless rather than merely continuous:
+        fetching a group costs 0.5-4.8s (rendering leaderboard and baseball cards
+        dominates), and doing it on the render thread stalls the scroll for that
+        long. Off the render thread there is a whole group's scroll time to work
+        in, so by the time the strip needs extending the content is already sat
+        waiting.
+
+        Only paths that avoid the shared display canvas run here; anything
+        needing it is marked and picked up on the render thread, where it is
+        safe. Those are the cheap ones — display capture measured 12-14ms
+        against seconds for the native renders.
+        """
+        if not self.config.continuous_scroll:
+            return
+
+        with self._prefetch_lock:
+            if self._prefetch_thread is not None and self._prefetch_thread.is_alive():
+                return
+            if self._prepared_group is not None:
+                return  # already have one waiting
+
+            def _work():
+                # Deprioritise against the render loop. Linux applies nice
+                # per-thread, and the heavy lifting here is PIL and numpy work
+                # that releases the GIL, so the scheduler can actually act on
+                # it — without this the prefetch competes for the same cores and
+                # costs frames.
+                try:
+                    os.nice(10)
+                except (OSError, AttributeError):
+                    pass
+                try:
+                    group = self.stream_manager.take_next_group(offscreen_only=True)
+                except Exception:
+                    logger.exception("Background prefetch failed")
+                    group = []
+                with self._prefetch_lock:
+                    self._prepared_group = group
+
+            self._prefetch_thread = threading.Thread(
+                target=_work, daemon=True, name="vegas-strip-prefetch")
+            self._prefetch_thread.start()
+
+    def drain_deferred(self) -> bool:
+        """
+        Fetch one queued canvas-bound plugin and append it to the strip.
+
+        Called once per frame. These plugins cannot be prepared off the render
+        thread — display capture and scroll-content generation both need the
+        shared canvas — so each costs roughly 290ms here. Doing one at a time
+        spreads that out instead of stalling for the whole group at once, and the
+        strip's lookahead means nothing runs dry while they arrive.
+
+        The cost is that a deferred plugin appears slightly after the group it
+        came with, which is a fair trade for a smooth scroll.
+
+        Returns:
+            True if a plugin was appended
+        """
+        if not self._deferred_queue:
+            return False
+
+        # Space the drains out. Each costs 40-600ms, and taking them back to
+        # back turns one long stall into a train of short ones — barely better.
+        # With a healthy lookahead there is no hurry, so wait a beat between
+        # them; when the strip is actually running short, fetch immediately.
+        threshold = int(self.display_width * self.config.extend_threshold_screens)
+        urgent = self.scroll_helper.remaining_unscrolled() <= threshold
+        if not urgent:
+            now = time.time()
+            if now - self._last_drain_time < self.DEFERRED_DRAIN_INTERVAL:
+                return False
+            self._last_drain_time = now
+        else:
+            self._last_drain_time = time.time()
+
+        plugin_id = self._deferred_queue.pop(0)
+        plugins = getattr(self.stream_manager.plugin_manager, 'plugins', {})
+        plugin = plugins.get(plugin_id)
+        if plugin is None:
+            return False
+
+        try:
+            images = self.stream_manager.plugin_adapter.get_content(plugin, plugin_id)
+        except Exception:
+            logger.exception("[%s] Error fetching deferred content", plugin_id)
+            return False
+
+        if not images:
+            return False
+
+        appended = self.scroll_helper.append_content(
+            content_items=[self._join_plugin_rows(images)],
+            item_gap=self.config.separator_width,
+            element_gap=0,
+        )
+        if appended:
+            with self._buffer_lock:
+                self._active_scroll_image = self.scroll_helper.cached_image
+            logger.info(
+                "[%s] Appended deferred content: strip now %dpx, %dpx ahead",
+                plugin_id, self.scroll_helper.total_scroll_width,
+                self.scroll_helper.remaining_unscrolled()
+            )
+        return appended
+
+    def has_deferred(self) -> bool:
+        """Whether any canvas-bound plugins are still queued."""
+        return bool(self._deferred_queue)
+
+    def _claim_prepared_group(self):
+        """Take the prefetched group, if one is ready."""
+        with self._prefetch_lock:
+            group = self._prepared_group
+            self._prepared_group = None
+        return group
+
+    def extend_scroll_content(self) -> bool:
+        """
+        Append the next group of plugins to the strip, without interrupting motion.
+
+        This is what replaces the swap. Scroll position is untouched, so the new
+        content simply arrives from the right; there is no substitution to see
+        and no restart with the viewport already full.
+
+        Consumed columns behind the viewport are then released, keeping the strip
+        bounded however long Vegas runs.
+
+        Returns:
+            True if the strip was extended
+        """
+        try:
+            grouped = self._claim_prepared_group()
+            if grouped is None:
+                # Nothing prepared (first extension, or prefetch still running).
+                # Fetch inline; the scroll hitches, but content keeps flowing.
+                logger.info("No prepared group ready; fetching inline")
+                grouped = self.stream_manager.take_next_group()
+
+            if not grouped:
+                logger.warning("No content available to extend the scroll strip")
+                return False
+
+            # Plugins the background thread had to defer need the shared canvas,
+            # so they can only be fetched here. Queue them rather than doing all
+            # of them now: measured, six in one go held the render thread for
+            # 1.75s. They are trickled in one per frame by drain_deferred(),
+            # which the strip's lookahead comfortably absorbs.
+            deferred = [pid for pid, images in grouped if images is None]
+            if deferred:
+                self._deferred_queue.extend(deferred)
+                logger.info(
+                    "Queued %d plugin(s) needing the render thread: %s",
+                    len(deferred), ', '.join(deferred)
+                )
+
+            grouped = [(pid, imgs) for pid, imgs in grouped if imgs]
+
+            if not grouped:
+                # Everything in this group is queued; the queue will extend the
+                # strip as it drains, so this is not a failure.
+                logger.info("Whole group deferred; strip will extend as it drains")
+                self.start_prefetch()
+                return bool(deferred)
+
+            blocks = []
+            total_rows = 0
+            for _plugin_id, images in grouped:
+                total_rows += len(images)
+                blocks.append(self._join_plugin_rows(images))
+
+            appended = self.scroll_helper.append_content(
+                content_items=blocks,
+                item_gap=self.config.separator_width,
+                element_gap=0,
+            )
+            if not appended:
+                return False
+
+            # Keep a screen's worth behind the viewport as a safety margin.
+            self.scroll_helper.drop_scrolled_prefix(keep_before=self.display_width)
+
+            with self._buffer_lock:
+                self._active_scroll_image = self.scroll_helper.cached_image
+
+            self._segments_in_scroll = [pid for pid, _ in grouped]
+            self.stats['composition_count'] += 1
+            self.stats['extensions'] = self.stats.get('extensions', 0) + 1
+
+            logger.info(
+                "Extended scroll strip with %d plugin block(s), %d rows: "
+                "strip now %dpx, %dpx still ahead of the viewport",
+                len(blocks), total_rows, self.scroll_helper.total_scroll_width,
+                self.scroll_helper.remaining_unscrolled()
+            )
+
+            # Line up the group after this one straight away, so it is ready
+            # well before the strip runs short again.
+            self.start_prefetch()
+            return True
+
+        except (ValueError, TypeError, OSError, RuntimeError):
+            logger.exception("Error extending scroll content")
+            return False
+
+    def _join_plugin_rows(self, images: List[Image.Image]) -> Image.Image:
+        """
+        Concatenate one plugin's images into a single block.
+
+        Args:
+            images: That plugin's content, in order
+
+        Returns:
+            A single image with the rows laid out left to right, separated by
+            ``intra_plugin_gap``. Returned unchanged when there is only one row,
+            which is the common case and avoids a pointless copy.
+        """
+        if len(images) == 1:
+            return images[0]
+
+        floor = max(0, self.config.intra_plugin_gap)
+        target = max(0, self.config.min_content_separation)
+        threshold = self.config.trim_threshold
+
+        # Space by measured separation, not a flat gap. Rows drawn flush to
+        # their own edges (sports score cards) would otherwise end up nearly
+        # touching, while rows that already carry wide margins would be pushed
+        # needlessly further apart.
+        gaps = [
+            separation_gap(images[i], images[i + 1], target, floor, threshold)
+            for i in range(len(images) - 1)
+        ]
+
+        width = sum(img.width for img in images) + sum(gaps)
+        height = max(img.height for img in images)
+
+        block = Image.new('RGB', (width, height), (0, 0, 0))
+        x = 0
+        for i, img in enumerate(images):
+            block.paste(img, (x, 0))
+            x += img.width + (gaps[i] if i < len(gaps) else 0)
+        return block
+
     def render_frame(self) -> bool:
         """
         Render a single frame to the display.
@@ -211,21 +499,33 @@ class RenderPipeline:
 
             # Determine if the cycle is done.
             #
-            # scroll_helper considers a cycle complete only after
-            # total_distance_scrolled >= total_scroll_width + display_width.
-            # That extra display_width of travel causes a "wrap-around" phase
-            # where scroll_position resets to ~0 and the first plugin's content
-            # re-enters from the right — the user sees this 2-3 s of re-entry
-            # as "a plugin partially displaying before the next one starts."
+            # get_visible_portion wraps: once scroll_position + display_width
+            # passes the end of the strip it fills the right-hand side of the
+            # frame from the *head* of the same strip. So the last
+            # display_width of travel shows the cycle's first plugin re-entering
+            # on the right while its last plugin exits on the left, and the
+            # recompose that follows then replaces both at once. That reads as
+            # the ticker "switching mid-scroll".
             #
-            # We end the cycle as soon as total_distance_scrolled reaches
-            # total_scroll_width (the wrap-around point), before any second-pass
-            # content becomes visible.  The scroll_helper's own is_scroll_complete()
-            # check is kept as a fallback for any edge-cases where that threshold
-            # is never hit.
+            # This used to be hidden because the strip began with a full
+            # display_width of blank, so the wrapped-in region was black.
+            # lead_in_width now defaults to 0 (that blank was 10s of dead panel
+            # at 50px/s), which exposed the wrap — so the cycle has to end
+            # before it, one display width earlier.
+            #
+            # A strip no wider than the display never wraps, and subtracting
+            # would make the cycle complete instantly, so clamp in that case.
+            # In continuous mode there is no cycle to complete: the strip is
+            # extended before the scroll can reach its end, so the wrap is never
+            # entered and motion never stops. The completion path below stays for
+            # the swap behaviour and as a backstop if an extension fails.
+            wrap_point = self.scroll_helper.total_scroll_width
+            if wrap_point > self.display_width:
+                wrap_point -= self.display_width
+
             at_wrap_point = (
                 not self._cycle_complete and
-                self.scroll_helper.total_distance_scrolled >= self.scroll_helper.total_scroll_width
+                self.scroll_helper.total_distance_scrolled >= wrap_point
             )
 
             if at_wrap_point or self.scroll_helper.is_scroll_complete():
@@ -236,24 +536,17 @@ class RenderPipeline:
                         "Scroll cycle complete after %.1fs",
                         time.time() - self._cycle_start_time
                     )
-                    # Push blank immediately so the hardware never shows any
-                    # post-wrap content while the coordinator recomposes the
-                    # next cycle (~100 ms). The blank is allocated once and
-                    # reused across cycle wraps (fresh paste each time in case
-                    # a consumer drew on the previous one).
-                    try:
-                        if self._blank_frame is None or self._blank_frame.size != (
-                                self.display_width, self.display_height):
-                            self._blank_frame = Image.new(
-                                'RGB', (self.display_width, self.display_height))
-                        else:
-                            self._blank_frame.paste(
-                                (0, 0, 0),
-                                (0, 0, self.display_width, self.display_height))
-                        self.display_manager.image = self._blank_frame
-                        self.display_manager.update_display()
-                    except Exception:
-                        logger.exception("Failed to write blank frame to display at cycle end")
+                    # Deliberately leave the last rendered frame on the panel.
+                    #
+                    # This used to push a blank frame so no post-wrap content
+                    # could be seen while the next cycle was composed. But
+                    # recomposing is synchronous and fetches plugin content:
+                    # measured 84ms at best and 4.8s at worst on a 512px panel,
+                    # and every millisecond of it was black. Holding the last
+                    # frame instead turns that into a brief freeze, which reads
+                    # as far less broken than the display switching off. The
+                    # frame is already past the end of the content, so there is
+                    # no second-pass content to leak.
                 return True  # Cycle done; coordinator starts new cycle next frame
 
             # Get visible portion
@@ -336,6 +629,25 @@ class RenderPipeline:
 
         return False
 
+    def refresh_updated_plugins(self) -> bool:
+        """
+        Let changed plugin data reach the strip without interrupting motion.
+
+        Used instead of :meth:`hot_swap_content` when scrolling continuously.
+        The swap rebuilds the whole image and repositions the scroll, which is
+        visible as a freeze and a jump; the strip is extended here rather than
+        replaced, so it is enough to drop the stale caches and let the plugin
+        recompose when it next comes round.
+
+        Returns:
+            True if any plugin's cached content was dropped.
+        """
+        try:
+            return bool(self.stream_manager.invalidate_pending_updates())
+        except Exception:  # pylint: disable=broad-except
+            logger.exception("Failed to refresh updated plugins")
+            return False
+
     def hot_swap_content(self) -> bool:
         """
         Hot-swap to new composed content.
@@ -415,11 +727,12 @@ class RenderPipeline:
         result = self.compose_scroll_content()
 
         if result and self.sync_manager:
-            # When sync is active, start the leader at display_width instead of 0.
-            # This skips the initial black gap so the leader immediately shows content.
-            # The follower starts at position 0 (the gap) which looks like a clean
-            # blank transition rather than near-end content wrapping around.
-            self.scroll_helper.scroll_position = float(self.display_width)
+            # When sync is active, start the leader past the lead-in gap so it
+            # immediately shows content, leaving the follower on the blank gap
+            # for a clean transition rather than near-end content wrapping
+            # around. This tracks lead_in_width rather than assuming a full
+            # display width of gap, which is no longer the default.
+            self.scroll_helper.scroll_position = float(self.config.lead_in_width)
 
         if result and self.sync_manager:
             # Signal follower that a new cycle started (triggers its own rebuild)

src/vegas_mode/stream_manager.py

@@ -14,7 +14,7 @@ Supports three display modes:
 import logging
 import threading
 import time
-from typing import Optional, List, Dict, Any, Deque, TYPE_CHECKING
+from typing import Optional, List, Dict, Any, Deque, Tuple, TYPE_CHECKING
 from collections import deque
 from dataclasses import dataclass, field
 from PIL import Image
@@ -116,8 +116,11 @@ class StreamManager:
             logger.warning("No plugins available for Vegas scroll")
             return False
 
-        # Prefetch initial content
-        self._prefetch_content(count=min(self.config.buffer_ahead + 1, len(self._ordered_plugins)))
+        # Fill the buffer to a whole cycle's worth of plugins. This used to be
+        # buffer_ahead + 1, which conflated prefetch depth with cycle size and
+        # meant a 20-plugin install only showed 3 plugins before recomposing.
+        self._prefetch_content(
+            count=min(self.config.plugins_per_cycle, len(self._ordered_plugins)))
 
         logger.info(
             "StreamManager initialized with %d plugins, %d segments buffered",
@@ -198,6 +201,47 @@ class StreamManager:
 
         logger.debug("Plugin %s marked for update", plugin_id)
 
+    def invalidate_pending_updates(self) -> List[str]:
+        """
+        Drop cached content for plugins whose data changed, without refetching.
+
+        The continuous-scroll counterpart to :meth:`process_updates`. That method
+        belongs to the swap path: it refetches immediately and merges into the
+        active buffer, which continuous mode bypasses entirely, and doing that
+        work on the render thread would hitch the scroll.
+
+        Here it is enough to clear the caches and let the plugin come round in
+        the rotation, which recomposes it from current data a moment later. Left
+        uncalled, ``_pending_updates`` simply accumulates and no visual ever
+        refreshes — a game that was live last night keeps being drawn as live.
+
+        Returns:
+            The plugin ids whose caches were dropped.
+        """
+        with self._buffer_lock:
+            if not self._pending_updates:
+                return []
+            updated = list(self._pending_updates.keys())
+            self._pending_updates.clear()
+
+        plugins = getattr(self.plugin_manager, 'plugins', {})
+        for plugin_id in updated:
+            try:
+                self.plugin_adapter.invalidate_cache(plugin_id)
+                plugin = plugins.get(plugin_id)
+                if plugin is not None:
+                    self.plugin_adapter.invalidate_plugin_scroll_cache(
+                        plugin, plugin_id)
+            except Exception:  # pylint: disable=broad-except
+                logger.exception(
+                    "[%s] Could not invalidate cached content", plugin_id)
+
+        logger.info(
+            "Vegas: dropped cached content for %d updated plugin(s): %s",
+            len(updated), ', '.join(updated)
+        )
+        return updated
+
     def has_pending_updates(self) -> bool:
         """Check if any plugins have pending updates awaiting processing."""
         with self._buffer_lock:
@@ -385,7 +429,7 @@ class StreamManager:
                 return
 
             for _ in range(count):
-                if len(self._active_buffer) >= self.config.buffer_ahead + 1:
+                if len(self._active_buffer) >= self.config.plugins_per_cycle:
                     break
 
                 # Ensure index is valid (guard against empty list)
@@ -521,28 +565,117 @@ class StreamManager:
             logger.debug("Refreshed content for %s in staging buffer", plugin_id)
 
     def _ensure_buffer_filled(self) -> None:
-        """Ensure buffer has enough content prefetched."""
-        if len(self._active_buffer) < self.config.buffer_ahead:
-            needed = self.config.buffer_ahead - len(self._active_buffer)
-            self._prefetch_content(count=needed)
+        """
+        Top the buffer back up after segments have been served.
+
+        buffer_ahead is the low-water mark only; plugins_per_cycle is the
+        ceiling and is enforced inside _prefetch_content.
+        """
+        low_water = min(self.config.buffer_ahead, self.config.plugins_per_cycle)
+        if len(self._active_buffer) < low_water:
+            self._prefetch_content(count=low_water - len(self._active_buffer))
 
     def get_all_content_for_composition(self) -> List[Image.Image]:
         """
         Get all buffered content as a flat list of images.
 
-        Used when composing the full scroll image.
         Skips STATIC segments as they don't have images to compose.
 
+        Prefer get_grouped_content_for_composition(): flattening loses the
+        plugin boundaries, which is what tells the compositor where a
+        separator belongs and where it does not.
+
         Returns:
             List of all images in buffer order
         """
         all_images = []
+        for _plugin_id, images in self.get_grouped_content_for_composition():
+            all_images.extend(images)
+        return all_images
+
+    def get_grouped_content_for_composition(self) -> List[Tuple[str, List[Image.Image]]]:
+        """
+        Get buffered content grouped by the plugin that produced it.
+
+        The grouping matters: separator_width is meant to mark the handoff from
+        one plugin to the next, not to sit between every row a single plugin
+        contributes. A per-row ticker like the F1 scoreboard returns over a
+        hundred images that it renders 4px apart internally, so flattening them
+        into one list and applying a uniform gap forced 32px between each of
+        its rows — both inconsistent with how the plugin looks standalone, and
+        a large hidden addition to the width it occupies.
+
+        Skips STATIC segments, which trigger a pause rather than contributing
+        scroll content, and segments left with no images.
+
+        Returns:
+            List of (plugin_id, images) in buffer order
+        """
+        grouped: List[Tuple[str, List[Image.Image]]] = []
         with self._buffer_lock:
             for segment in self._active_buffer:
-                # Skip STATIC segments - they trigger pauses, not scroll content
-                if segment.display_mode != VegasDisplayMode.STATIC:
-                    all_images.extend(segment.images)
-        return all_images
+                if segment.display_mode == VegasDisplayMode.STATIC:
+                    continue
+                if not segment.images:
+                    continue
+                grouped.append((segment.plugin_id, list(segment.images)))
+        return grouped
+
+    def take_next_group(
+        self, count: Optional[int] = None, offscreen_only: bool = False
+    ) -> List[Tuple[str, Optional[List[Image.Image]]]]:
+        """
+        Fetch and hand over the next slice of the rotation.
+
+        For continuous scrolling, where the strip is extended rather than
+        replaced. Advances the rotation index so plugins come round in order
+        across an unbroken strip, and bypasses the active buffer entirely — that
+        buffer exists to stage a *replacement* cycle, which continuous mode has
+        no use for.
+
+        Args:
+            count: Number of plugins to gather, defaulting to plugins_per_cycle
+            offscreen_only: Only use content paths that avoid the shared display
+                canvas, for use off the render thread
+
+        Returns:
+            Ordered list of (plugin_id, images). ``images`` is None when the
+            plugin could not be served under ``offscreen_only``, so the caller
+            can fetch just those on the render thread while keeping the order.
+        """
+        if count is None:
+            count = self.config.plugins_per_cycle
+
+        self.refresh()
+
+        with self._buffer_lock:
+            if not self._ordered_plugins:
+                return []
+            total = len(self._ordered_plugins)
+            ids = []
+            for _ in range(min(max(1, count), total)):
+                ids.append(self._ordered_plugins[self._prefetch_index])
+                self._prefetch_index = (self._prefetch_index + 1) % total
+
+        plugins = getattr(self.plugin_manager, 'plugins', {})
+        group: List[Tuple[str, Optional[List[Image.Image]]]] = []
+
+        for plugin_id in ids:
+            plugin = plugins.get(plugin_id)
+            if not plugin:
+                continue
+            try:
+                images = self.plugin_adapter.get_content(
+                    plugin, plugin_id, offscreen_only=offscreen_only)
+            except Exception:
+                logger.exception("[%s] ERROR fetching content", plugin_id)
+                self.stats['fetch_errors'] += 1
+                continue
+            if images:
+                self.stats['segments_fetched'] += 1
+            group.append((plugin_id, images if images else None))
+
+        return group
 
     def advance_cycle(self) -> None:
         """

test/test_plugin_system.py

@@ -250,5 +250,125 @@ class TestBasePlugin:
             
         config = {"enabled": True, "live_priority": True}
         plugin = ConcretePlugin("test", config, mock_display_manager, mock_cache_manager, None)
-        
+
         assert plugin.has_live_priority() is True
+
+
+class TestBasePluginGlobalConfig:
+    """global_config exposes device-wide settings that self.config cannot.
+
+    The sports scoreboards read `getattr(self, 'global_config', {})` to find
+    the shared target_fps; before this property existed nothing ever set that
+    attribute, so the lookup silently returned {} and the setting could never
+    take effect on any core.
+    """
+
+    @staticmethod
+    def _plugin(display_manager, cache_manager, plugin_manager=None):
+        from src.plugin_system.base_plugin import BasePlugin
+
+        class ConcretePlugin(BasePlugin):
+            def update(self): pass
+            def display(self, force_clear=False): pass
+
+        return ConcretePlugin(
+            "test", {"enabled": True}, display_manager, cache_manager, plugin_manager
+        )
+
+    @staticmethod
+    def _manager_with(config):
+        """A stand-in manager exposing config_manager.get_config()."""
+        manager = MagicMock()
+        manager.config_manager.get_config.return_value = config
+        return manager
+
+    def test_reads_config_from_plugin_manager(self, mock_display_manager, mock_cache_manager):
+        plugin = self._plugin(
+            mock_display_manager, mock_cache_manager,
+            self._manager_with({"target_fps": 100}),
+        )
+        assert plugin.global_config["target_fps"] == 100
+
+    def test_falls_back_to_cache_manager(self, mock_display_manager):
+        # The core that hangs config_manager off the cache manager instead.
+        cache_manager = self._manager_with({"target_fps": 75})
+        plugin = self._plugin(mock_display_manager, cache_manager, plugin_manager=None)
+        assert plugin.global_config["target_fps"] == 75
+
+    def test_plugin_manager_wins_over_cache_manager(self, mock_display_manager):
+        plugin = self._plugin(
+            mock_display_manager,
+            self._manager_with({"target_fps": 75}),
+            self._manager_with({"target_fps": 100}),
+        )
+        assert plugin.global_config["target_fps"] == 100
+
+    def test_empty_plugin_manager_config_falls_through(self, mock_display_manager):
+        """An empty first source means "not loaded yet", not "the answer".
+
+        Both managers default to the same config/config.json, so falling
+        through cannot pick up a different file. Returning {} here instead
+        would silently disable every setting read through this property --
+        the exact failure this property exists to fix.
+        """
+        plugin = self._plugin(
+            mock_display_manager,
+            self._manager_with({"target_fps": 100}),   # cache_manager
+            self._manager_with({}),                    # plugin_manager: empty
+        )
+        assert plugin.global_config["target_fps"] == 100
+
+    def test_returns_empty_dict_when_no_config_manager(self, mock_display_manager):
+        # Plain objects: no config_manager attribute at all.
+        plugin = self._plugin(mock_display_manager, object(), object())
+        assert plugin.global_config == {}
+
+    def test_unreadable_config_does_not_raise(self, mock_display_manager):
+        # A plugin must still load when the config on disk is broken.
+        broken = MagicMock()
+        broken.config_manager.get_config.side_effect = OSError("unreadable")
+        plugin = self._plugin(mock_display_manager, broken, broken)
+        assert plugin.global_config == {}
+
+    def test_non_dict_config_is_rejected(self, mock_display_manager):
+        # A stub or half-built manager can return a non-mapping; handing that
+        # back would blow up later in numeric code, far from the cause.
+        plugin = self._plugin(
+            mock_display_manager, object(), self._manager_with("not-a-dict")
+        )
+        assert plugin.global_config == {}
+
+    def test_missing_property_degrades_to_default(self, mock_display_manager, mock_cache_manager):
+        # How plugins actually call it, so a plugin written against this core
+        # still loads on one that predates the property.
+        plugin = self._plugin(mock_display_manager, mock_cache_manager, object())
+        assert getattr(plugin, "global_config", {}).get("target_fps") is None
+
+    def test_plugin_may_still_assign_global_config(self, mock_display_manager, mock_cache_manager):
+        # news, stock-news, ledmatrix-stocks, ledmatrix-elections,
+        # ledmatrix-leaderboard and nfl-draft all do exactly this. Without a
+        # setter the property raises "has no setter" and those plugins stop
+        # loading entirely.
+        from src.plugin_system.base_plugin import BasePlugin
+
+        class AssigningPlugin(BasePlugin):
+            def __init__(self, *args, **kwargs):
+                super().__init__(*args, **kwargs)
+                self.global_config = self.config.get("global", {})
+
+            def update(self): pass
+            def display(self, force_clear=False): pass
+
+        plugin = AssigningPlugin(
+            "news", {"enabled": True, "global": {"scroll_speed": 2}},
+            mock_display_manager, mock_cache_manager, self._manager_with({"target_fps": 100}),
+        )
+        # The plugin's own value wins over the resolved config.
+        assert plugin.global_config == {"scroll_speed": 2}
+
+    def test_template_ships_a_global_target_fps(self):
+        # The plumbing is useless if the setting isn't in the shipped config.
+        import json
+        with open("config/config.template.json") as fh:
+            template = json.load(fh)
+        assert template.get("target_fps") == 100

test/test_scroll_helper_continuous.py

@@ -0,0 +1,336 @@
+"""
+Tests for ScrollHelper's continuous-strip primitives.
+
+append_content extends the strip to the right without disturbing motion, and
+drop_scrolled_prefix reclaims what has already gone past. Together they let a
+caller keep one endless strip instead of swapping a new one in, which is what
+shows as a flash and a hard cut to already-full-screen content.
+"""
+
+import numpy as np
+import pytest
+from PIL import Image
+
+from src.common.scroll_helper import ScrollHelper
+from src.vegas_mode.geometry import column_has_ink
+
+W, H = 128, 32
+
+
+def helper():
+    return ScrollHelper(W, H)
+
+
+def block(width, colour=(255, 255, 255), height=H):
+    return Image.new('RGB', (width, height), colour)
+
+
+class TestAppendContent:
+    def test_first_append_builds_the_strip(self):
+        sh = helper()
+        assert sh.append_content([block(100)], item_gap=0)
+        assert sh.cached_image is not None
+        assert sh.total_scroll_width == sh.cached_image.width
+
+    def test_strip_grows_by_content_plus_gaps(self):
+        sh = helper()
+        sh.create_scrolling_image([block(100)], item_gap=0, element_gap=0, lead_gap=0)
+        assert sh.cached_image.width == 100
+
+        sh.append_content([block(50)], item_gap=10, element_gap=0)
+        # one leading gap of 10 then the 50px block
+        assert sh.cached_image.width == 160
+        assert sh.total_scroll_width == 160
+
+    def test_scroll_position_is_preserved(self):
+        sh = helper()
+        sh.create_scrolling_image([block(400)], item_gap=0, element_gap=0, lead_gap=0)
+        sh.scroll_position = 137.0
+        sh.total_distance_scrolled = 137.0
+
+        sh.append_content([block(200)], item_gap=16)
+        assert sh.scroll_position == 137.0
+        assert sh.total_distance_scrolled == 137.0
+
+    def test_appending_defers_completion(self):
+        sh = helper()
+        sh.create_scrolling_image([block(200)], item_gap=0, element_gap=0, lead_gap=0)
+        sh.scroll_complete = True
+
+        sh.append_content([block(200)], item_gap=0)
+        assert not sh.scroll_complete
+        assert sh.total_distance_scrolled < sh.total_scroll_width
+
+    def test_existing_pixels_are_untouched(self):
+        sh = helper()
+        original = block(80, (10, 200, 10))
+        sh.create_scrolling_image([original], item_gap=0, element_gap=0, lead_gap=0)
+        before = sh.cached_image.crop((0, 0, 80, H)).tobytes()
+
+        sh.append_content([block(40, (200, 10, 10))], item_gap=8)
+        assert sh.cached_image.crop((0, 0, 80, H)).tobytes() == before
+
+    def test_appended_content_sits_after_the_gap(self):
+        sh = helper()
+        sh.create_scrolling_image([block(50)], item_gap=0, element_gap=0, lead_gap=0)
+        sh.append_content([block(30)], item_gap=12)
+
+        ink = column_has_ink(sh.cached_image)
+        assert ink[:50].all()
+        assert not ink[50:62].any()      # the 12px gap
+        assert ink[62:92].all()
+
+    def test_array_and_image_stay_consistent(self):
+        # get_visible_portion slices cached_array but bounds-checks against
+        # cached_image.width, so a mismatch corrupts frames.
+        sh = helper()
+        sh.create_scrolling_image([block(200)], item_gap=0, element_gap=0, lead_gap=0)
+        sh.append_content([block(100)], item_gap=8)
+        assert sh.cached_array.shape[1] == sh.cached_image.width
+        assert sh.cached_array.shape[0] == sh.cached_image.height
+
+    def test_visible_portion_still_renders_after_append(self):
+        sh = helper()
+        sh.create_scrolling_image([block(300)], item_gap=0, element_gap=0, lead_gap=0)
+        sh.append_content([block(300)], item_gap=8)
+        sh.scroll_position = 250.0
+        frame = sh.get_visible_portion()
+        assert frame is not None and frame.size == (W, H)
+
+    def test_empty_append_is_a_no_op(self):
+        sh = helper()
+        sh.create_scrolling_image([block(100)], item_gap=0, element_gap=0, lead_gap=0)
+        assert sh.append_content([]) is False
+        assert sh.cached_image.width == 100
+
+    def test_repeated_appends_accumulate(self):
+        sh = helper()
+        sh.append_content([block(100)], item_gap=0)
+        for _ in range(5):
+            sh.append_content([block(100)], item_gap=0)
+        assert sh.cached_image.width == 600
+
+
+class TestDropScrolledPrefix:
+    def test_removes_consumed_columns(self):
+        sh = helper()
+        sh.create_scrolling_image([block(1000)], item_gap=0, element_gap=0, lead_gap=0)
+        sh.scroll_position = 500.0
+        sh.total_distance_scrolled = 500.0
+
+        removed = sh.drop_scrolled_prefix(keep_before=0)
+        assert removed == 500
+        assert sh.cached_image.width == 500
+        assert sh.scroll_position == 0.0
+
+    def test_keeps_the_requested_margin(self):
+        sh = helper()
+        sh.create_scrolling_image([block(1000)], item_gap=0, element_gap=0, lead_gap=0)
+        sh.scroll_position = 500.0
+        sh.drop_scrolled_prefix(keep_before=100)
+        assert sh.scroll_position == 100.0
+        assert sh.cached_image.width == 600
+
+    def test_completion_difference_is_preserved(self):
+        # total_distance_scrolled and total_scroll_width must shift together, or
+        # trimming would spuriously complete or un-complete the cycle.
+        sh = helper()
+        sh.create_scrolling_image([block(1000)], item_gap=0, element_gap=0, lead_gap=0)
+        sh.scroll_position = 600.0
+        sh.total_distance_scrolled = 600.0
+        before = sh.total_scroll_width - sh.total_distance_scrolled
+
+        sh.drop_scrolled_prefix(keep_before=0)
+        assert sh.total_scroll_width - sh.total_distance_scrolled == before
+
+    def test_never_trims_below_the_viewport(self):
+        sh = helper()
+        sh.create_scrolling_image([block(200)], item_gap=0, element_gap=0, lead_gap=0)
+        sh.scroll_position = 190.0
+        sh.drop_scrolled_prefix(keep_before=0)
+        assert sh.cached_image.width >= W
+
+    def test_no_op_before_anything_has_scrolled(self):
+        sh = helper()
+        sh.create_scrolling_image([block(500)], item_gap=0, element_gap=0, lead_gap=0)
+        assert sh.drop_scrolled_prefix(keep_before=0) == 0
+        assert sh.cached_image.width == 500
+
+    def test_no_op_with_no_strip(self):
+        assert helper().drop_scrolled_prefix() == 0
+
+    def test_visible_frame_is_unchanged_by_trimming(self):
+        # The whole point: trimming is invisible. Same pixels on screen before
+        # and after. Position chosen so the viewport is well clear of the end,
+        # i.e. not wrapping.
+        sh = helper()
+        items = [block(200, (255, 0, 0)), block(200, (0, 255, 0)),
+                 block(200, (0, 0, 255))]
+        sh.create_scrolling_image(items, item_gap=20, element_gap=0, lead_gap=0)
+        sh.scroll_position = 300.0
+        before = sh.get_visible_portion().tobytes()
+
+        assert sh.drop_scrolled_prefix(keep_before=0) > 0, "trim should have run"
+        after = sh.get_visible_portion().tobytes()
+        assert after == before
+
+    def test_refuses_to_trim_while_the_viewport_wraps(self):
+        # Wrapping reads the head of the strip into the right of the frame, so
+        # trimming the head there would visibly change the picture.
+        sh = helper()
+        sh.create_scrolling_image([block(200)], item_gap=0, element_gap=0, lead_gap=0)
+        sh.scroll_position = 150.0          # 150 + 128 > 200, so wrapping
+        before = sh.get_visible_portion().tobytes()
+        assert sh.drop_scrolled_prefix(keep_before=0) == 0
+        assert sh.get_visible_portion().tobytes() == before
+
+    def test_array_and_image_stay_consistent_after_trim(self):
+        sh = helper()
+        sh.create_scrolling_image([block(900)], item_gap=0, element_gap=0, lead_gap=0)
+        sh.scroll_position = 400.0
+        sh.drop_scrolled_prefix(keep_before=0)
+        assert sh.cached_array.shape[1] == sh.cached_image.width
+
+
+class TestRemainingUnscrolled:
+    def test_counts_content_right_of_the_viewport(self):
+        sh = helper()
+        sh.create_scrolling_image([block(500)], item_gap=0, element_gap=0, lead_gap=0)
+        assert sh.remaining_unscrolled() == 500 - W
+
+    def test_shrinks_as_the_strip_scrolls(self):
+        sh = helper()
+        sh.create_scrolling_image([block(500)], item_gap=0, element_gap=0, lead_gap=0)
+        sh.scroll_position = 200.0
+        assert sh.remaining_unscrolled() == 500 - 200 - W
+
+    def test_never_negative(self):
+        sh = helper()
+        sh.create_scrolling_image([block(200)], item_gap=0, element_gap=0, lead_gap=0)
+        sh.scroll_position = 500.0
+        assert sh.remaining_unscrolled() == 0
+
+    def test_zero_with_no_strip(self):
+        assert helper().remaining_unscrolled() == 0
+
+    def test_grows_when_content_is_appended(self):
+        sh = helper()
+        sh.create_scrolling_image([block(600)], item_gap=0, element_gap=0, lead_gap=0)
+        sh.scroll_position = 100.0
+        before = sh.remaining_unscrolled()
+        assert before > 0, "fixture should leave content ahead of the viewport"
+        sh.append_content([block(400)], item_gap=0)
+        assert sh.remaining_unscrolled() == before + 400
+
+
+class TestContinuousScrollingEndToEnd:
+    def test_strip_can_be_extended_indefinitely_at_bounded_size(self):
+        """The invariant that makes this viable: extend + trim keeps the strip
+        bounded while motion never stops."""
+        sh = helper()
+        sh.create_scrolling_image([block(600)], item_gap=0, element_gap=0, lead_gap=0)
+
+        widths = []
+        for _ in range(20):
+            sh.scroll_position += 200
+            sh.total_distance_scrolled += 200
+            if sh.remaining_unscrolled() < 2 * W:
+                sh.append_content([block(600)], item_gap=16)
+            sh.drop_scrolled_prefix(keep_before=W)
+            widths.append(sh.cached_image.width)
+            # A frame must always be renderable.
+            assert sh.get_visible_portion() is not None
+
+        assert max(widths) < 3000, f"strip grew unbounded: max {max(widths)}"
+        assert not sh.scroll_complete, "continuous strip should never complete"
+
+
+class TestSubPixelBlending:
+    """
+    Integer positioning quantises motion to whole pixels, so distinct frames per
+    second equals scroll speed regardless of frame rate — at 50px/s and 78fps,
+    36% of frames were identical. Blending between neighbouring positions gives
+    motion at the frame rate instead.
+    """
+
+    def _strip(self, width=2000):
+        rng = np.random.default_rng(0)
+        arr = (rng.random((H, width, 3)) * 255).astype(np.uint8)
+        sh = helper()
+        sh.create_scrolling_image([Image.fromarray(arr)],
+                                  item_gap=0, element_gap=0, lead_gap=0)
+        return sh
+
+    def _frame(self, sh, pos, subpixel):
+        sh.sub_pixel_scrolling = subpixel
+        sh.scroll_position = pos
+        return np.asarray(sh.get_visible_portion()).astype(int)
+
+    def test_integer_mode_ignores_the_fraction(self):
+        sh = self._strip()
+        a = self._frame(sh, 500.0, False)
+        b = self._frame(sh, 500.9, False)
+        assert np.array_equal(a, b), "integer positioning should not move sub-pixel"
+
+    def test_blending_moves_within_a_pixel(self):
+        sh = self._strip()
+        a = self._frame(sh, 500.0, True)
+        b = self._frame(sh, 500.5, True)
+        assert not np.array_equal(a, b)
+
+    def test_zero_fraction_matches_the_integer_frame(self):
+        # No interpolation to do, so it must be pixel-identical and take the
+        # cheap path.
+        sh = self._strip()
+        assert np.array_equal(self._frame(sh, 700.0, True),
+                              self._frame(sh, 700.0, False))
+
+    def test_blend_is_monotonic_between_neighbours(self):
+        # Marching the fraction from 0 to 1 should approach the next integer
+        # frame, not wander.
+        sh = self._strip()
+        target = self._frame(sh, 501.0, False)
+        dists = []
+        for frac in (0.0, 0.25, 0.5, 0.75):
+            f = self._frame(sh, 500.0 + frac, True)
+            dists.append(np.abs(f - target).mean())
+        assert dists == sorted(dists, reverse=True), f"not converging: {dists}"
+
+    def test_blend_endpoints_bracket_the_two_frames(self):
+        sh = self._strip()
+        near = self._frame(sh, 500.0, False)
+        far = self._frame(sh, 501.0, False)
+        mid = self._frame(sh, 500.5, True)
+        # Every blended pixel must lie between its two sources.
+        lo = np.minimum(near, far)
+        hi = np.maximum(near, far)
+        assert (mid >= lo - 1).all() and (mid <= hi + 1).all()
+
+    def test_output_size_and_mode_are_unchanged(self):
+        sh = self._strip()
+        sh.sub_pixel_scrolling = True
+        sh.scroll_position = 300.4
+        frame = sh.get_visible_portion()
+        assert frame.size == (W, H)
+        assert frame.mode == 'RGB'
+
+    def test_works_near_the_end_of_the_strip(self):
+        # One of the two slices wraps here; must not raise or missize.
+        sh = self._strip(width=600)
+        sh.sub_pixel_scrolling = True
+        sh.scroll_position = float(600 - W // 2) + 0.5
+        frame = sh.get_visible_portion()
+        assert frame is not None and frame.size == (W, H)
+
+    def test_works_at_the_very_last_column(self):
+        sh = self._strip(width=600)
+        sh.sub_pixel_scrolling = True
+        sh.scroll_position = 599.5
+        assert sh.get_visible_portion().size == (W, H)
+
+    @pytest.mark.parametrize("frac", [0.01, 0.1, 0.33, 0.5, 0.67, 0.9, 0.99])
+    def test_never_raises_across_the_fraction_range(self, frac):
+        sh = self._strip()
+        sh.sub_pixel_scrolling = True
+        sh.scroll_position = 400.0 + frac
+        assert sh.get_visible_portion().size == (W, H)

test/test_skin_system.py

@@ -0,0 +1,452 @@
+"""Tests for the skin system: discovery, version gating, fallback
+semantics, module isolation, and the view-model contract."""
+
+import json
+import logging
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+from PIL import Image, ImageFont
+
+# src.base_classes.sports transitively imports the hardware matrix driver;
+# stub it so the fallback-semantics tests can import SportsCore off-device.
+sys.modules.setdefault("rgbmatrix", MagicMock())
+
+from src.skin_system import skin_runtime
+from src.skin_system.skin_base import (
+    SKIN_API_VERSION,
+    ScoreboardSkin,
+    SkinContext,
+)
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+FIXTURES_DIR = PROJECT_ROOT / "src" / "skin_system" / "fixtures"
+
+# The v1.0 guaranteed view-model keys (docs/CREATING_SKINS.md). Renaming
+# or removing any of these is a breaking change to every published skin:
+# it requires a VIEW_MODEL_VERSION major bump and a compat shim.
+GUARANTEED_KEYS = [
+    "id", "game_time", "game_date", "start_time_utc", "status_text",
+    "is_live", "is_final", "is_upcoming", "is_halftime",
+    "home_abbr", "home_id", "home_score", "home_logo_path", "home_record",
+    "away_abbr", "away_id", "away_score", "away_logo_path", "away_record",
+]
+
+
+def write_skin(skins_dir: Path, skin_id: str, *, api_version: str = SKIN_API_VERSION,
+               body: str = None, extra_files: dict = None,
+               class_name: str = "TestSkin") -> Path:
+    skin_dir = skins_dir / skin_id
+    skin_dir.mkdir(parents=True)
+    manifest = {
+        "id": skin_id, "name": skin_id, "version": "1.0.0",
+        "skin_api_version": api_version, "class_name": class_name,
+        "targets": {"sports": ["baseball"]},
+    }
+    (skin_dir / "skin.json").write_text(json.dumps(manifest))
+    if body is None:
+        body = (
+            "from src.skin_system.skin_base import ScoreboardSkin\n"
+            f"class {class_name}(ScoreboardSkin):\n"
+            "    def render_live(self, ctx, game):\n"
+            "        ctx.draw.rectangle([0, 0, 4, 4], fill=(255, 0, 0))\n"
+            "        return True\n"
+        )
+    (skin_dir / "skin.py").write_text(body)
+    for name, content in (extra_files or {}).items():
+        (skin_dir / name).write_text(content)
+    return skin_dir
+
+
+class TestDiscovery:
+    def test_discovers_valid_skin(self, tmp_path):
+        write_skin(tmp_path, "my-skin")
+        skins = skin_runtime.discover_skins(tmp_path, force_refresh=True)
+        assert "my-skin" in skins
+        assert skins["my-skin"]["_skin_dir"].endswith("my-skin")
+
+    def test_skips_manifest_missing_required_fields(self, tmp_path):
+        skin_dir = tmp_path / "broken"
+        skin_dir.mkdir()
+        (skin_dir / "skin.json").write_text(json.dumps({"id": "broken"}))
+        assert skin_runtime.discover_skins(tmp_path, force_refresh=True) == {}
+
+    def test_skips_unreadable_manifest_and_non_skin_dirs(self, tmp_path):
+        (tmp_path / "not-a-skin").mkdir()
+        bad = tmp_path / "bad-json"
+        bad.mkdir()
+        (bad / "skin.json").write_text("{nope")
+        write_skin(tmp_path, "good-skin")
+        skins = skin_runtime.discover_skins(tmp_path, force_refresh=True)
+        assert list(skins) == ["good-skin"]
+
+    def test_missing_directory_is_empty(self, tmp_path):
+        assert skin_runtime.discover_skins(tmp_path / "nope") == {}
+
+    def test_example_skin_in_repo_is_discoverable(self):
+        skins = skin_runtime.discover_skins(force_refresh=True)
+        assert "example-classic-baseball" in skins
+
+
+class TestLoadSkin:
+    def test_loads_and_instantiates(self, tmp_path):
+        write_skin(tmp_path, "my-skin")
+        skin = skin_runtime.load_skin("my-skin", sport="baseball",
+                                      skins_dir=tmp_path)
+        assert isinstance(skin, ScoreboardSkin)
+
+    def test_unknown_skin_returns_none(self, tmp_path):
+        assert skin_runtime.load_skin("ghost", skins_dir=tmp_path) is None
+
+    def test_api_major_mismatch_is_refused(self, tmp_path):
+        write_skin(tmp_path, "old-skin", api_version="99.0.0")
+        assert skin_runtime.load_skin("old-skin", skins_dir=tmp_path) is None
+
+    def test_target_mismatch_still_loads(self, tmp_path):
+        write_skin(tmp_path, "my-skin")  # targets baseball
+        skin = skin_runtime.load_skin("my-skin", sport="hockey",
+                                      skins_dir=tmp_path)
+        assert skin is not None  # soft warning, not a hard block
+
+    def test_import_error_returns_none(self, tmp_path):
+        write_skin(tmp_path, "crashy", body="raise RuntimeError('boom')\n")
+        assert skin_runtime.load_skin("crashy", skins_dir=tmp_path) is None
+
+    def test_wrong_class_returns_none(self, tmp_path):
+        write_skin(tmp_path, "classless", body="x = 1\n")
+        assert skin_runtime.load_skin("classless", skins_dir=tmp_path) is None
+
+    def test_options_are_passed_through(self, tmp_path):
+        write_skin(tmp_path, "my-skin")
+        skin = skin_runtime.load_skin("my-skin", skins_dir=tmp_path,
+                                      options={"accent": [1, 2, 3]})
+        assert skin.options == {"accent": [1, 2, 3]}
+
+    def test_sibling_modules_are_isolated_between_skins(self, tmp_path):
+        helper = "VALUE = {!r}\n"
+        body = (
+            "import helpers\n"
+            "from src.skin_system.skin_base import ScoreboardSkin\n"
+            "class TestSkin(ScoreboardSkin):\n"
+            "    def render_live(self, ctx, game):\n"
+            "        ctx.logger.info(helpers.VALUE)\n"
+            "        self.helper_value = helpers.VALUE\n"
+            "        return False\n"
+        )
+        write_skin(tmp_path, "skin-a", body=body,
+                   extra_files={"helpers.py": helper.format("A")})
+        write_skin(tmp_path, "skin-b", body=body,
+                   extra_files={"helpers.py": helper.format("B")})
+        skin_a = skin_runtime.load_skin("skin-a", skins_dir=tmp_path)
+        skin_b = skin_runtime.load_skin("skin-b", skins_dir=tmp_path)
+        ctx = _make_context()
+        skin_a.render_live(ctx, {})
+        skin_b.render_live(ctx, {})
+        assert skin_a.helper_value == "A"
+        assert skin_b.helper_value == "B"
+
+    def test_same_skin_loads_repeatedly_with_siblings(self, tmp_path):
+        """The live/recent/upcoming hosts each load the same skin — the
+        2nd and 3rd loads must still resolve sibling modules (regression:
+        cached siblings used to be skipped without rebinding)."""
+        body = (
+            "import reload_helpers\n"
+            "from src.skin_system.skin_base import ScoreboardSkin\n"
+            "class TestSkin(ScoreboardSkin):\n"
+            "    def render_live(self, ctx, game):\n"
+            "        self.helper_value = reload_helpers.VALUE\n"
+            "        return False\n"
+        )
+        write_skin(tmp_path, "reload-skin", body=body,
+                   extra_files={"reload_helpers.py": "VALUE = 'R'\n"})
+        ctx = _make_context()
+        for _ in range(3):
+            skin = skin_runtime.load_skin("reload-skin", skins_dir=tmp_path)
+            assert skin is not None
+            skin.render_live(ctx, {})
+            assert skin.helper_value == "R"
+
+
+def _make_host(fonts=None):
+    host = MagicMock()
+    host.sport = "baseball"
+    host.sport_key = "mlb"
+    host.skin_options = {"accent": True}
+    host.fonts = fonts or {"time": ImageFont.load_default()}
+    host.logger = logging.getLogger("test_skin_system")
+    host.display_manager.width = 128
+    host.display_manager.height = 32
+    return host
+
+
+def _make_context(width=128, height=32):
+    host = _make_host()
+    return skin_runtime.build_context(host, {}, size=(width, height))
+
+
+class TestBuildContext:
+    def test_context_shape(self):
+        host = _make_host()
+        game = {"home_abbr": "LAD", "away_abbr": "SF"}
+        ctx = skin_runtime.build_context(host, game)
+        assert (ctx.width, ctx.height) == (128, 32)
+        assert ctx.canvas.size == (128, 32)
+        assert ctx.sport == "baseball"
+        assert ctx.options == {"accent": True}
+        assert ctx.layout.bounds.w == 128
+
+    def test_explicit_size_overrides_display(self):
+        ctx = skin_runtime.build_context(_make_host(), {}, size=(64, 64))
+        assert ctx.canvas.size == (64, 64)
+
+    def test_load_logo_binds_game_and_survives_failure(self):
+        host = _make_host()
+        host._load_and_resize_logo.side_effect = RuntimeError("disk gone")
+        ctx = skin_runtime.build_context(
+            host, {"home_id": "1", "home_abbr": "LAD",
+                   "home_logo_path": "x.png", "home_logo_url": None})
+        assert ctx.load_logo("home") is None      # exception swallowed
+        assert ctx.load_logo("elsewhere") is None  # bad side rejected
+
+    def test_draw_helpers_draw_on_canvas(self):
+        ctx = _make_context()
+        ctx.draw_text("HI", 2, 2, font=ImageFont.load_default())
+        fit = ctx.layout.fit_text("42", ctx.layout.bounds)
+        ctx.draw_fit(fit, ctx.layout.bounds)
+        logo = Image.new("RGBA", (16, 16), (255, 0, 0, 255))
+        ctx.draw_image(logo, ctx.layout.bounds.left_col(20))
+        ctx.draw_image(None, ctx.layout.bounds)  # None must no-op
+        assert ctx.canvas.convert("L").getbbox() is not None
+
+
+class _FallbackProbe:
+    """Bare-bones SportsCore stand-in that exercises the real _render_game."""
+
+    def __init__(self, skin):
+        from src.base_classes.sports import SportsCore
+        self._cls = SportsCore
+        self.SKIN_MODE = "live"
+        self.logger = logging.getLogger("test_skin_system")
+        self.sport = "baseball"
+        self.sport_key = "mlb"
+        self.skin_options = {}
+        self.fonts = {"time": ImageFont.load_default()}
+        self._skin = skin
+        self._skin_load_attempted = True
+        self._skin_failures = 0
+        self._skin_slow_renders = 0
+        self._skin_config = "test-skin"
+        self.display_manager = MagicMock()
+        self.display_manager.width = 128
+        self.display_manager.height = 32
+        self.display_manager.image = Image.new("RGB", (128, 32))
+        self.builtin_calls = 0
+
+    def _resolve_skin_id(self):
+        return "test-skin"
+
+    def _draw_scorebug_layout(self, game, force_clear=False):
+        self.builtin_calls += 1
+
+    def _render_game(self, game, force_clear=False):
+        from src.base_classes.sports import SportsCore
+        SportsCore._render_game(self, game, force_clear)
+
+    def _get_skin(self):
+        return self._skin
+
+
+class TestRenderGameFallback:
+    def test_skin_handles_render(self):
+        class GoodSkin(ScoreboardSkin):
+            def render_live(self, ctx, game):
+                ctx.draw.rectangle([0, 0, 10, 10], fill=(0, 255, 0))
+                return True
+
+        probe = _FallbackProbe(GoodSkin({}, {}))
+        probe._render_game({"status_text": "Q1"})
+        assert probe.builtin_calls == 0
+        probe.display_manager.update_display.assert_called_once()
+        assert probe.display_manager.image.convert("L").getbbox() is not None
+
+    def test_skin_declining_falls_back(self):
+        probe = _FallbackProbe(ScoreboardSkin({}, {}))  # all renders -> False
+        probe._render_game({"status_text": "Q1"})
+        assert probe.builtin_calls == 1
+
+    def test_no_skin_falls_back(self):
+        probe = _FallbackProbe(None)
+        probe._render_game({"status_text": "Q1"})
+        assert probe.builtin_calls == 1
+
+    def test_three_strikes_disables_skin(self):
+        class BrokenSkin(ScoreboardSkin):
+            calls = 0
+
+            def render_live(self, ctx, game):
+                BrokenSkin.calls += 1
+                raise ValueError("kaboom")
+
+        probe = _FallbackProbe(BrokenSkin({}, {}))
+        for i in range(5):
+            probe._render_game({"status_text": "Q1"})
+        # every render fell back to the built-in layout...
+        assert probe.builtin_calls == 5
+        # ...and the skin stopped being called after the 3rd failure
+        assert BrokenSkin.calls == 3
+        assert probe._skin_failures == 3
+
+    def test_skin_cannot_mutate_callers_game_dict(self):
+        class MutatingSkin(ScoreboardSkin):
+            def render_live(self, ctx, game):
+                game.clear()
+                game["hacked"] = True
+                return True
+
+        probe = _FallbackProbe(MutatingSkin({}, {}))
+        game = {"status_text": "Q1", "home_score": "3"}
+        probe._render_game(game)
+        assert game == {"status_text": "Q1", "home_score": "3"}
+
+
+class TestSkinModeResolution:
+    def _core(self, skin_config, mode="live"):
+        from src.base_classes.sports import SportsCore
+        probe = _FallbackProbe(None)
+        probe.SKIN_MODE = mode
+        probe._skin_config = skin_config
+        return SportsCore._resolve_skin_id(probe)
+
+    def test_plain_id_applies_to_all_modes(self):
+        assert self._core("retro", "live") == "retro"
+        assert self._core("retro", "recent") == "retro"
+
+    def test_per_mode_mapping(self):
+        cfg = {"live": "retro", "recent": "built-in"}
+        assert self._core(cfg, "live") == "retro"
+        assert self._core(cfg, "recent") is None
+        assert self._core(cfg, "upcoming") is None
+
+    def test_builtin_and_empty_mean_none(self):
+        assert self._core("built-in") is None
+        assert self._core("") is None
+        assert self._core(None) is None
+
+
+class TestViewModelContract:
+    @pytest.mark.parametrize("sport", ["baseball", "basketball", "football", "hockey"])
+    @pytest.mark.parametrize("mode", ["live", "recent", "upcoming"])
+    def test_fixtures_carry_all_guaranteed_keys(self, sport, mode):
+        with open(FIXTURES_DIR / f"{sport}_{mode}.json") as f:
+            game = json.load(f)
+        missing = [k for k in GUARANTEED_KEYS if k not in game]
+        assert not missing, f"{sport}_{mode} fixture missing {missing}"
+
+    def test_extractor_produces_guaranteed_keys(self):
+        """The real extractor's output must be a superset of the documented
+        contract — this is the test that catches accidental renames."""
+        import pytz
+        from src.base_classes.sports import SportsCore
+
+        event = {
+            "id": "401570001",
+            "date": "2026-07-16T23:05:00Z",
+            "competitions": [{
+                "status": {"type": {"name": "STATUS_IN_PROGRESS", "state": "in",
+                                    "shortDetail": "Bot 7th"}},
+                "competitors": [
+                    {"homeAway": "home", "id": "19",
+                     "team": {"abbreviation": "LAD"}, "score": "5",
+                     "records": [{"summary": "58-33"}]},
+                    {"homeAway": "away", "id": "26",
+                     "team": {"abbreviation": "SF"}, "score": "3",
+                     "records": [{"summary": "49-42"}]},
+                ],
+            }],
+        }
+        probe = MagicMock()
+        probe.logger = logging.getLogger("test_skin_system")
+        probe.favorite_teams = []
+        probe.config = {}
+        probe.logo_dir = Path("assets/logos")
+        probe._get_timezone.return_value = pytz.utc
+        probe.display_manager.format_date_with_ordinal.return_value = "Jul 16th"
+
+        details, _, _, _, _ = SportsCore._extract_game_details_common(probe, event)
+        assert details is not None
+        missing = [k for k in GUARANTEED_KEYS if k not in details]
+        assert not missing, (
+            f"_extract_game_details_common no longer emits {missing}. "
+            "These keys are part of the frozen skin view-model contract "
+            "(VIEW_MODEL_VERSION) — renaming or removing them breaks every "
+            "published skin. Add a compat shim or bump the major version.")
+
+
+class TestPluginMatching:
+    def test_matches_by_sport_token_and_sport_key(self, tmp_path):
+        write_skin(tmp_path, "bb-skin")  # targets sports=["baseball"]
+        skins = skin_runtime.discover_skins(tmp_path, force_refresh=True)
+        assert "bb-skin" in skin_runtime.skins_for_plugin("baseball-scoreboard", skins)
+        assert "bb-skin" not in skin_runtime.skins_for_plugin("football-scoreboard", skins)
+
+    def test_matches_by_explicit_plugin_list(self, tmp_path):
+        skin_dir = write_skin(tmp_path, "exact-skin")
+        manifest = json.loads((skin_dir / "skin.json").read_text())
+        manifest["targets"] = {"plugins": ["my-custom-plugin"]}
+        (skin_dir / "skin.json").write_text(json.dumps(manifest))
+        skins = skin_runtime.discover_skins(tmp_path, force_refresh=True)
+        assert "exact-skin" in skin_runtime.skins_for_plugin("my-custom-plugin", skins)
+        assert "exact-skin" not in skin_runtime.skins_for_plugin("baseball-scoreboard", skins)
+
+
+class TestSchemaInjection:
+    def _manager(self):
+        from src.plugin_system.schema_manager import SchemaManager
+        return SchemaManager()
+
+    def test_injects_enum_with_installed_and_configured_skins(self):
+        sm = self._manager()
+        schema = {"type": "object", "properties": {}}
+        out = sm.inject_skin_selector(schema, "baseball-scoreboard",
+                                      current_value="gone-skin")
+        enum = out["properties"]["skin"]["enum"]
+        assert enum[0] == "built-in"
+        assert "example-classic-baseball" in enum
+        # an uninstalled-but-configured skin must stay selectable so the
+        # saved config never becomes invalid in the UI
+        assert "gone-skin" in enum
+        assert "skin" not in schema["properties"]  # source schema untouched
+
+    def test_no_matching_skins_leaves_schema_alone(self):
+        sm = self._manager()
+        schema = {"type": "object", "properties": {}}
+        out = sm.inject_skin_selector(schema, "totally-unrelated-plugin")
+        assert "skin" not in out.get("properties", {})
+
+    def test_validation_accepts_skin_keys_without_enum(self):
+        sm = self._manager()
+        schema = {"type": "object", "properties": {"foo": {"type": "string"}}}
+        ok, errors = sm.validate_config_against_schema(
+            {"skin": "any-id-even-uninstalled", "skin_options": {"x": 1}},
+            schema, "baseball-scoreboard")
+        assert ok, errors
+        ok, errors = sm.validate_config_against_schema(
+            {"skin": {"live": "a", "recent": "built-in"}}, schema, "p")
+        assert ok, errors
+
+
+class TestExampleSkin:
+    @pytest.mark.parametrize("mode", ["live", "recent", "upcoming"])
+    @pytest.mark.parametrize("size", [(128, 32), (64, 32), (128, 64)])
+    def test_renders_all_modes_and_sizes(self, mode, size):
+        skin = skin_runtime.load_skin("example-classic-baseball", sport="baseball")
+        assert skin is not None
+        host = _make_host()
+        host._load_and_resize_logo.return_value = Image.new("RGBA", (32, 32), (200, 0, 0, 255))
+        with open(FIXTURES_DIR / f"baseball_{mode}.json") as f:
+            game = json.load(f)
+        ctx = skin_runtime.build_context(host, game, size=size)
+        assert getattr(skin, f"render_{mode}")(ctx, game) is True
+        assert ctx.canvas.convert("L").getbbox() is not None

test/test_vegas_continuous_refresh.py

@@ -0,0 +1,227 @@
+"""
+Regression tests: changed plugin data must reach the strip in continuous mode.
+
+Two faults combined to freeze Vegas content indefinitely.
+
+PR #291 added a call to ``plugin_adapter.invalidate_plugin_scroll_cache()`` so a
+plugin's *own* cached scroll image would be rebuilt from fresh data. The method
+was never implemented, and ``hot_swap_content()`` wraps the call in a broad
+except, so every hot swap raised AttributeError and was silently swallowed.
+
+Continuous scrolling then removed the only path that reached it at all:
+``should_recompose()``/``hot_swap_content()`` are called from the non-continuous
+branch, while ``continuous_scroll`` defaults to True.
+
+Together, a plugin composed its scroll image once and handed back the same
+picture forever, because the sports plugins' ``get_vegas_content()`` regenerates
+only when its cache is empty. Symptom: a game that was live last night is still
+drawn as live the following morning.
+"""
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+import numpy as np
+from PIL import Image
+
+from src.vegas_mode.config import VegasModeConfig
+from src.vegas_mode.plugin_adapter import PluginAdapter
+from src.vegas_mode.render_pipeline import RenderPipeline
+from src.vegas_mode.stream_manager import StreamManager
+
+
+class FakeDisplayManager:
+    width = 64
+    height = 32
+
+
+def _helper():
+    """A stand-in ScrollHelper holding both halves of its cache."""
+    image = Image.new('RGB', (128, 32), (10, 20, 30))
+    return SimpleNamespace(cached_image=image, cached_array=np.array(image))
+
+
+class TestInvalidatePluginScrollCache:
+    """The method PR #291 called but never defined."""
+
+    def test_method_exists(self):
+        # It was called for months without existing; the broad except in
+        # hot_swap_content() meant nothing ever surfaced.
+        assert hasattr(PluginAdapter, 'invalidate_plugin_scroll_cache')
+
+    def test_clears_helper_attached_to_the_plugin(self):
+        adapter = PluginAdapter(FakeDisplayManager(), VegasModeConfig())
+        helper = _helper()
+        plugin = SimpleNamespace(scroll_helper=helper)
+
+        assert adapter.invalidate_plugin_scroll_cache(plugin, 'stocks') is True
+        assert helper.cached_image is None
+        assert helper.cached_array is None
+
+    def test_clears_helper_owned_by_a_scroll_manager(self):
+        # The sports scoreboards keep theirs on _scroll_manager, which is the
+        # layout that produced the reported stale-scores bug.
+        adapter = PluginAdapter(FakeDisplayManager(), VegasModeConfig())
+        helper = _helper()
+        plugin = SimpleNamespace(_scroll_manager=SimpleNamespace(scroll_helper=helper))
+
+        assert adapter.invalidate_plugin_scroll_cache(plugin, 'baseball') is True
+        assert helper.cached_image is None
+        assert helper.cached_array is None
+
+    def test_clears_both_halves_together(self):
+        # cached_array is the image's numpy mirror; leaving one behind lets a
+        # reader pick up content the other no longer has.
+        adapter = PluginAdapter(FakeDisplayManager(), VegasModeConfig())
+        helper = _helper()
+        adapter.invalidate_plugin_scroll_cache(
+            SimpleNamespace(scroll_helper=helper), 'news')
+        assert (helper.cached_image, helper.cached_array) == (None, None)
+
+    def test_plugin_without_a_helper_is_not_an_error(self):
+        adapter = PluginAdapter(FakeDisplayManager(), VegasModeConfig())
+        assert adapter.invalidate_plugin_scroll_cache(SimpleNamespace(), 'clock') is False
+
+
+class TestInvalidatePendingUpdates:
+    def _manager(self, plugins):
+        stream = StreamManager(
+            VegasModeConfig(),
+            SimpleNamespace(plugins=plugins),
+            MagicMock(),
+        )
+        stream.plugin_adapter = MagicMock()
+        return stream
+
+    def test_drops_caches_for_updated_plugins(self):
+        helper = _helper()
+        plugin = SimpleNamespace(scroll_helper=helper)
+        stream = self._manager({'baseball': plugin})
+        stream.mark_plugin_updated('baseball')
+
+        assert stream.invalidate_pending_updates() == ['baseball']
+        stream.plugin_adapter.invalidate_cache.assert_called_once_with('baseball')
+        stream.plugin_adapter.invalidate_plugin_scroll_cache.assert_called_once_with(
+            plugin, 'baseball')
+
+    def test_pending_flags_are_consumed(self):
+        # Left unconsumed they accumulate forever and nothing ever refreshes.
+        stream = self._manager({'baseball': SimpleNamespace()})
+        stream.mark_plugin_updated('baseball')
+        assert stream.has_pending_updates() is True
+
+        stream.invalidate_pending_updates()
+        assert stream.has_pending_updates() is False
+        assert stream.invalidate_pending_updates() == []
+
+    def test_no_pending_updates_does_no_work(self):
+        stream = self._manager({})
+        assert stream.invalidate_pending_updates() == []
+        stream.plugin_adapter.invalidate_cache.assert_not_called()
+
+    def test_a_failing_plugin_does_not_stop_the_others(self):
+        stream = self._manager({'a': SimpleNamespace(), 'b': SimpleNamespace()})
+        stream.mark_plugin_updated('a')
+        stream.mark_plugin_updated('b')
+        stream.plugin_adapter.invalidate_cache.side_effect = [
+            RuntimeError('boom'), None]
+
+        assert sorted(stream.invalidate_pending_updates()) == ['a', 'b']
+        assert stream.plugin_adapter.invalidate_cache.call_count == 2
+
+
+class TestContinuousModeReachesTheRefresh:
+    def _pipeline(self):
+        stream = MagicMock()
+        stream.get_buffer_status.return_value = {'staging_count': 0}
+        return RenderPipeline(VegasModeConfig(), FakeDisplayManager(), stream), stream
+
+    def test_refresh_delegates_to_the_stream_manager(self):
+        pipeline, stream = self._pipeline()
+        stream.invalidate_pending_updates.return_value = ['baseball']
+        assert pipeline.refresh_updated_plugins() is True
+
+    def test_refresh_reports_false_when_nothing_changed(self):
+        pipeline, stream = self._pipeline()
+        stream.invalidate_pending_updates.return_value = []
+        assert pipeline.refresh_updated_plugins() is False
+
+    def test_refresh_never_raises_into_the_render_loop(self):
+        pipeline, stream = self._pipeline()
+        stream.invalidate_pending_updates.side_effect = RuntimeError('boom')
+        assert pipeline.refresh_updated_plugins() is False
+
+    def test_refresh_does_not_reposition_the_scroll(self):
+        # The whole point of preferring this over hot_swap_content(): that path
+        # rebuilds and repositions, which reads as a freeze then a jump.
+        pipeline, stream = self._pipeline()
+        stream.invalidate_pending_updates.return_value = ['baseball']
+        pipeline.scroll_helper.scroll_position = 1234
+
+        pipeline.refresh_updated_plugins()
+
+        assert pipeline.scroll_helper.scroll_position == 1234
+        stream.swap_buffers.assert_not_called()
+        stream.process_updates.assert_not_called()
+
+
+class TestCoordinatorWiring:
+    """
+    The regression itself: continuous mode has to *call* the refresh.
+
+    should_recompose()/hot_swap_content() sit in the non-continuous branch, and
+    continuous_scroll defaults to True, so before this fix the refresh was
+    simply never reached on a default install.
+    """
+
+    def _coordinator(self, continuous):
+        import threading
+
+        from src.vegas_mode.coordinator import VegasModeCoordinator
+
+        config = VegasModeConfig()
+        config.continuous_scroll = continuous
+        # Built without __init__ so the test exercises run_frame's branching
+        # without standing up a display, stream and render stack.
+        coordinator = VegasModeCoordinator.__new__(VegasModeCoordinator)
+        coordinator.vegas_config = config
+        coordinator.render_pipeline = MagicMock()
+        coordinator.render_pipeline.has_deferred.return_value = False
+        coordinator.render_pipeline.needs_extension.return_value = False
+        coordinator.render_pipeline.is_cycle_complete.return_value = False
+        coordinator.render_pipeline.should_recompose.return_value = False
+        coordinator.stream_manager = MagicMock()
+        coordinator.stats = {'cycles_completed': 0}
+        coordinator._state_lock = threading.Lock()
+        coordinator._is_active = True
+        coordinator._is_paused = False
+        coordinator._should_stop = False
+        coordinator._pending_config_update = False
+        coordinator._live_priority_check = None
+        coordinator._interrupt_check = None
+        coordinator.sync_manager = None
+        return coordinator
+
+    def test_continuous_mode_refreshes_updated_plugins_every_frame(self):
+        coordinator = self._coordinator(continuous=True)
+        coordinator.run_frame()
+        coordinator.render_pipeline.refresh_updated_plugins.assert_called_once()
+
+    def test_continuous_mode_does_not_use_the_disruptive_swap(self):
+        coordinator = self._coordinator(continuous=True)
+        coordinator.run_frame()
+        coordinator.render_pipeline.hot_swap_content.assert_not_called()
+
+    def test_swap_mode_still_uses_hot_swap(self):
+        # The non-continuous path must keep its original behaviour.
+        coordinator = self._coordinator(continuous=False)
+        coordinator.render_pipeline.should_recompose.return_value = True
+        coordinator.run_frame()
+        coordinator.render_pipeline.hot_swap_content.assert_called_once()
+        coordinator.render_pipeline.refresh_updated_plugins.assert_not_called()
+
+    def test_a_frame_is_still_rendered_either_way(self):
+        for continuous in (True, False):
+            coordinator = self._coordinator(continuous=continuous)
+            coordinator.run_frame()
+            coordinator.render_pipeline.render_frame.assert_called_once()

test/test_vegas_geometry.py

@@ -0,0 +1,370 @@
+"""Tests for Vegas mode geometry primitives."""
+
+import numpy as np
+import pytest
+from PIL import Image
+
+from src.vegas_mode.geometry import (
+    DEFAULT_INK_THRESHOLD,
+    column_has_ink,
+    content_bounds,
+    dead_window_stats,
+    edge_blank,
+    find_blank_cut,
+    separation_gap,
+    trim_to_content,
+    window_coverage_stats,
+)
+
+
+def make_img(width, height=8, fill=(0, 0, 0)):
+    return Image.new('RGB', (width, height), fill)
+
+
+def paint(img, x0, x1, color=(255, 255, 255)):
+    """Fill columns [x0, x1) with a colour."""
+    block = Image.new('RGB', (x1 - x0, img.height), color)
+    img.paste(block, (x0, 0))
+    return img
+
+
+class TestColumnHasInk:
+    def test_all_black_has_no_ink(self):
+        assert not column_has_ink(make_img(16)).any()
+
+    def test_marks_only_painted_columns(self):
+        img = paint(make_img(16), 4, 8)
+        ink = column_has_ink(img)
+        assert ink.tolist() == [False] * 4 + [True] * 4 + [False] * 8
+
+    def test_threshold_is_exclusive(self):
+        # A pixel exactly at the threshold is not ink; one above it is.
+        at = paint(make_img(4), 0, 4, (DEFAULT_INK_THRESHOLD,) * 3)
+        above = paint(make_img(4), 0, 4, (DEFAULT_INK_THRESHOLD + 1,) * 3)
+        assert not column_has_ink(at).any()
+        assert column_has_ink(above).all()
+
+    def test_single_bright_channel_counts(self):
+        img = paint(make_img(4), 1, 2, (0, 0, 200))
+        assert column_has_ink(img).tolist() == [False, True, False, False]
+
+    def test_one_lit_pixel_lights_the_column(self):
+        img = make_img(4, height=8)
+        img.putpixel((2, 5), (255, 255, 255))
+        assert column_has_ink(img).tolist() == [False, False, True, False]
+
+
+class TestContentBounds:
+    def test_blank_returns_none(self):
+        assert content_bounds(make_img(16)) is None
+
+    def test_finds_inclusive_bounds(self):
+        assert content_bounds(paint(make_img(20), 5, 12)) == (5, 11)
+
+    def test_full_width_content(self):
+        assert content_bounds(paint(make_img(10), 0, 10)) == (0, 9)
+
+    def test_spans_interior_gap(self):
+        img = paint(make_img(30), 2, 5)
+        paint(img, 20, 25)
+        assert content_bounds(img) == (2, 24)
+
+
+class TestTrimToContent:
+    def test_blank_image_reports_blank(self):
+        result = trim_to_content(make_img(512))
+        assert result.is_blank
+        assert result.image is None
+        assert result.width == 0
+        assert result.original_width == 512
+
+    def test_trims_both_edges(self):
+        result = trim_to_content(paint(make_img(512), 100, 150))
+        assert not result.is_blank
+        assert result.width == 50
+        assert result.trimmed_left == 100
+        assert result.trimmed_right == 362
+        assert result.removed == 462
+
+    def test_preserves_interior_gap(self):
+        # Two content blocks with a wide blank between them: the gap is the
+        # plugin's layout and must survive trimming.
+        img = paint(make_img(400), 50, 80)
+        paint(img, 300, 330)
+        result = trim_to_content(img)
+        assert result.width == 280  # 50..329 inclusive
+        assert column_has_ink(result.image).sum() == 60
+
+    def test_full_width_content_is_returned_unchanged(self):
+        img = paint(make_img(128), 0, 128)
+        result = trim_to_content(img)
+        assert result.image is img
+        assert result.removed == 0
+
+    def test_non_black_background_is_never_trimmed(self):
+        # A plugin drawing on a dark-but-not-black background fills every
+        # column with ink, so there is nothing to reclaim.
+        result = trim_to_content(make_img(256, fill=(0, 0, 40)))
+        assert result.removed == 0
+        assert result.width == 256
+
+    def test_padding_keeps_margin_up_to_what_exists(self):
+        result = trim_to_content(paint(make_img(512), 100, 150), padding=8)
+        assert result.trimmed_left == 92
+        assert result.width == 66  # 50 content + 8 each side
+
+    def test_padding_cannot_widen_beyond_original(self):
+        # Content starts 2px in; padding of 8 can only reclaim the 2 available.
+        result = trim_to_content(paint(make_img(64), 2, 60), padding=8)
+        assert result.trimmed_left == 0
+        assert result.trimmed_right == 0
+        assert result.width == 64
+
+    def test_height_is_preserved(self):
+        result = trim_to_content(paint(make_img(200, height=64), 10, 20))
+        assert result.image.height == 64
+
+    def test_real_world_of_the_day_case(self):
+        # Measured on devpi: "No Data" occupying 35px of a 512px canvas.
+        result = trim_to_content(paint(make_img(512, height=64), 4, 39))
+        assert result.width == 35
+        assert result.removed == 477
+
+
+class TestDeadWindowStats:
+    def test_fully_inked_ticker_has_no_dead_windows(self):
+        stats = dead_window_stats(paint(make_img(400), 0, 400), viewport_width=100)
+        assert stats.dead_windows == 0
+        assert stats.dead_ratio == 0.0
+        assert stats.longest_dead_run == 0
+
+    def test_fully_blank_ticker_is_all_dead(self):
+        stats = dead_window_stats(make_img(400), viewport_width=100)
+        assert stats.total_windows == 301
+        assert stats.dead_windows == 301
+        assert stats.dead_ratio == 1.0
+        assert stats.longest_dead_run == 301
+
+    def test_leading_blank_run_is_measured(self):
+        # 512px of black then solid content: windows fully inside the black
+        # stretch are dead. With a 100px viewport, starts 0..412 exist and a
+        # window is dead while it holds >=95 blank columns.
+        img = paint(make_img(1024), 512, 1024)
+        stats = dead_window_stats(img, viewport_width=100)
+        assert stats.dead_windows == 418  # starts 0..417 keep >=95 blank cols
+        assert stats.longest_dead_run == 418
+
+    def test_narrow_content_island_still_leaves_dead_windows(self):
+        # 35px of content in a 512px field, viewed 100px at a time: no window
+        # can be 95% blank once it overlaps 35 lit columns, but the windows
+        # clear of it are dead.
+        img = paint(make_img(512), 100, 135)
+        stats = dead_window_stats(img, viewport_width=100)
+        assert stats.dead_windows > 0
+        assert stats.dead_ratio == pytest.approx(
+            stats.dead_windows / stats.total_windows
+        )
+
+    def test_step_reduces_sampling(self):
+        img = paint(make_img(1000), 500, 1000)
+        exact = dead_window_stats(img, viewport_width=100, step=1)
+        strided = dead_window_stats(img, viewport_width=100, step=10)
+        assert strided.total_windows < exact.total_windows
+        # Same underlying shape, so the ratios should stay close.
+        assert strided.dead_ratio == pytest.approx(exact.dead_ratio, abs=0.02)
+
+    def test_image_narrower_than_viewport_is_one_window(self):
+        stats = dead_window_stats(make_img(50), viewport_width=100)
+        assert stats.total_windows == 1
+        assert stats.dead_windows == 1
+
+    def test_zero_viewport_is_handled(self):
+        stats = dead_window_stats(make_img(50), viewport_width=0)
+        assert stats.total_windows == 0
+        assert stats.dead_ratio == 0.0
+
+    def test_longest_run_picks_the_larger_of_two_gaps(self):
+        # Short blank gap, content, then a long blank gap.
+        img = make_img(1000)
+        paint(img, 150, 400)
+        paint(img, 500, 520)
+        stats = dead_window_stats(img, viewport_width=100)
+        # The 400..500 gap is only 100 wide; the tail from 520 is 480 wide.
+        assert stats.longest_dead_run >= 380
+
+
+class TestWindowCoverageStats:
+    def test_solid_content_is_fully_covered(self):
+        stats = window_coverage_stats(paint(make_img(600), 0, 600), viewport_width=100)
+        assert stats.mean_ink_ratio == 1.0
+        assert stats.min_ink_ratio == 1.0
+        assert stats.sparse_windows == 0
+
+    def test_blank_strip_is_entirely_sparse(self):
+        stats = window_coverage_stats(make_img(600), viewport_width=100)
+        assert stats.mean_ink_ratio == 0.0
+        assert stats.sparse_ratio == 1.0
+
+    def test_catches_sliver_windows_that_dead_ratio_misses(self):
+        # Narrow content islands separated by more than the viewport. A window
+        # holding one whole 40px island carries 472 blank columns — under the
+        # 486 needed to count as "dead" — yet only 7.8% ink, so it still reads
+        # as an empty panel. Coverage must flag strictly more positions than
+        # the dead-window scan does.
+        img = paint(make_img(2000), 0, 40)
+        paint(img, 1000, 1040)
+        dead = dead_window_stats(img, viewport_width=512)
+        cover = window_coverage_stats(img, viewport_width=512, sparse_ink_ratio=0.10)
+        assert cover.sparse_windows > dead.dead_windows
+        assert cover.min_ink_ratio == 0.0
+
+    def test_adjacent_full_width_segments_stay_partially_covered(self):
+        # Documents why the dead-window scan alone understated the problem:
+        # two 512px segments with mid-canvas content never fully blank the
+        # viewport, they just hold it at a thin ~28%.
+        img = paint(make_img(1024), 185, 330)
+        paint(img, 697, 842)
+        dead = dead_window_stats(img, viewport_width=512)
+        cover = window_coverage_stats(img, viewport_width=512)
+        assert dead.dead_windows == 0
+        assert cover.mean_ink_ratio == pytest.approx(0.283, abs=0.01)
+
+    def test_min_ink_ratio_finds_the_worst_position(self):
+        # A wide blank tail guarantees at least one totally empty viewport.
+        img = paint(make_img(1200), 0, 200)
+        stats = window_coverage_stats(img, viewport_width=200)
+        assert stats.min_ink_ratio == 0.0
+        assert stats.mean_ink_ratio > 0.0
+
+    def test_sparse_threshold_is_respected(self):
+        # 40 inked columns in a 200px viewport = 20% coverage everywhere the
+        # island is fully inside the window.
+        img = paint(make_img(400), 100, 140)
+        lenient = window_coverage_stats(img, viewport_width=200, sparse_ink_ratio=0.05)
+        strict = window_coverage_stats(img, viewport_width=200, sparse_ink_ratio=0.50)
+        assert strict.sparse_windows > lenient.sparse_windows
+
+    def test_step_approximates_exact_scan(self):
+        img = paint(make_img(2000), 300, 500)
+        paint(img, 1200, 1400)
+        exact = window_coverage_stats(img, viewport_width=512, step=1)
+        strided = window_coverage_stats(img, viewport_width=512, step=4)
+        assert strided.mean_ink_ratio == pytest.approx(exact.mean_ink_ratio, abs=0.01)
+
+    def test_zero_viewport_is_handled(self):
+        stats = window_coverage_stats(make_img(50), viewport_width=0)
+        assert stats.total_windows == 0
+        assert stats.sparse_ratio == 0.0
+
+    def test_image_narrower_than_viewport(self):
+        stats = window_coverage_stats(paint(make_img(50), 0, 50), viewport_width=100)
+        assert stats.total_windows == 1
+        assert stats.mean_ink_ratio == pytest.approx(0.5)
+
+
+class TestLongestRunHelper:
+    @pytest.mark.parametrize("flags,expected", [
+        ([], 0),
+        ([False, False], 0),
+        ([True], 1),
+        ([True, True, False, True], 2),
+        ([False, True, True, True, False, True], 3),
+        ([True, True, True], 3),
+    ])
+    def test_run_lengths(self, flags, expected):
+        from src.vegas_mode.geometry import _longest_true_run
+        assert _longest_true_run(np.array(flags, dtype=bool)) == expected
+
+
+class TestEdgeBlank:
+    def test_measures_both_edges(self):
+        assert edge_blank(paint(make_img(100), 20, 60)) == (20, 40)
+
+    def test_flush_content_has_no_blank(self):
+        assert edge_blank(paint(make_img(50), 0, 50)) == (0, 0)
+
+    def test_blank_image_reports_full_width_both_sides(self):
+        # No ink means nothing to be close to.
+        assert edge_blank(make_img(64)) == (64, 64)
+
+
+class TestSeparationGap:
+    def test_flush_edges_get_the_full_target(self):
+        a = paint(make_img(50), 0, 50)
+        b = paint(make_img(50), 0, 50)
+        assert separation_gap(a, b, target=24) == 24
+
+    def test_existing_margins_reduce_the_added_gap(self):
+        # 8px blank on each facing edge already covers 16 of the 24 target.
+        a = paint(make_img(50), 0, 42)
+        b = paint(make_img(50), 8, 50)
+        assert separation_gap(a, b, target=24) == 8
+
+    def test_ample_existing_margin_adds_nothing(self):
+        a = paint(make_img(100), 0, 60)
+        b = paint(make_img(100), 40, 100)
+        assert separation_gap(a, b, target=24) == 0
+
+    def test_minimum_is_a_floor(self):
+        a = paint(make_img(100), 0, 60)
+        b = paint(make_img(100), 40, 100)
+        assert separation_gap(a, b, target=24, minimum=4) == 4
+
+    def test_never_negative(self):
+        a = paint(make_img(200), 0, 10)
+        b = paint(make_img(200), 190, 200)
+        assert separation_gap(a, b, target=8) == 0
+
+    def test_sports_card_case_gets_real_separation(self):
+        # The reported problem: cards drawn edge to edge sat 8px apart under a
+        # flat gap; measured separation lifts them to the 24px target.
+        card = paint(make_img(150), 0, 150)
+        assert separation_gap(card, card, target=24, minimum=8) == 24
+
+
+class TestFindBlankCut:
+    def test_snaps_to_the_nearest_gap(self):
+        img = paint(make_img(200), 0, 90)
+        paint(img, 110, 200)
+        # 100 is inside the 90..110 gap already.
+        assert find_blank_cut(img, 100, 20) == 100
+
+    def test_walks_outwards_to_find_a_gap(self):
+        img = paint(make_img(200), 0, 95)
+        paint(img, 105, 200)
+        cut = find_blank_cut(img, 90, 20)
+        assert 95 <= cut < 105
+
+    def test_solid_ink_returns_the_target(self):
+        assert find_blank_cut(paint(make_img(200), 0, 200), 100, 20) == 100
+
+    def test_target_at_image_width_does_not_index_past_the_end(self):
+        # A cut after the last column is legal. Indexing ink[width] raised
+        # IndexError in the field, losing that plugin's content for the cycle.
+        # Reached once the rotation offset advances so start + budget lands
+        # exactly on the image width.
+        img = paint(make_img(1840), 0, 1840)
+        assert find_blank_cut(img, 1840, 32) == 1840
+
+    def test_target_past_image_width_is_clamped(self):
+        img = paint(make_img(100), 0, 100)
+        assert find_blank_cut(img, 500, 32) == 100
+
+    def test_target_at_width_with_a_trailing_gap_snaps_back(self):
+        # Content 0..179, blank 180..199. The nearest blank column to 200 is
+        # 199, not the start of the gap — nearest is what keeps the cut as
+        # close as possible to the requested budget.
+        img = paint(make_img(200), 0, 180)
+        assert find_blank_cut(img, 200, 32) == 199
+
+    def test_zero_radius_returns_the_target(self):
+        assert find_blank_cut(paint(make_img(100), 0, 100), 50, 0) == 50
+
+    def test_negative_target_is_clamped_to_zero(self):
+        assert find_blank_cut(paint(make_img(100), 0, 100), -20, 8) == 0
+
+    @pytest.mark.parametrize("target", [0, 1, 50, 99, 100])
+    def test_never_raises_across_the_range(self, target):
+        img = paint(make_img(100), 0, 100)
+        cut = find_blank_cut(img, target, 16)
+        assert 0 <= cut <= 100

test/test_web_api.py

@@ -146,6 +146,11 @@ class TestConfigAPI:
 
     def test_save_double_sided_settings(self, client, mock_config_manager):
         """Double-sided form fields are persisted under display.double_sided."""
+        # 2 copies on the vertical axis needs parallel to be a multiple of 2.
+        mock_config_manager.load_config.return_value['display']['hardware'] = {
+            'chain_length': 2, 'parallel': 2,
+        }
+
         response = client.post(
             '/api/v3/config/main',
             data={
@@ -162,6 +167,78 @@ class TestConfigAPI:
             'enabled': True, 'copies': 2, 'axis': 'vertical',
         }
 
+    def test_save_target_fps(self, client, mock_config_manager):
+        """The device-wide scroll frame rate persists as a top-level int."""
+        response = client.post(
+            '/api/v3/config/main',
+            data={'target_fps': '90'},
+            content_type='application/x-www-form-urlencoded',
+        )
+
+        assert response.status_code == 200
+        saved = mock_config_manager.save_config_atomic.call_args[0][0]
+        # Must be the coerced int, not the raw form string -- the generic
+        # remaining-keys loop would otherwise write '90' back over it.
+        assert saved['target_fps'] == 90
+
+    def test_save_target_fps_alone_does_not_reset_other_general_settings(
+            self, client, mock_config_manager):
+        """A target_fps-only POST must not be treated as a full General-tab save.
+
+        The general branch reads web_display_autostart as an unchecked-checkbox
+        (absent means False), so counting target_fps as a general update would
+        silently switch autostart off for anyone setting only the frame rate.
+        """
+        mock_config_manager.load_config.return_value['web_display_autostart'] = True
+
+        response = client.post(
+            '/api/v3/config/main',
+            data={'target_fps': '90'},
+            content_type='application/x-www-form-urlencoded',
+        )
+
+        assert response.status_code == 200
+        saved = mock_config_manager.save_config_atomic.call_args[0][0]
+        assert saved['web_display_autostart'] is True
+
+    @pytest.mark.parametrize('value', [90.5, 90.0, True])
+    def test_save_target_fps_rejects_non_integer_json(self, client, mock_config_manager, value):
+        """int() would truncate silently: 90.5 -> 90, True -> 1.
+
+        Only JSON can carry these; a form post sends '90.5', which int()
+        already rejects.
+        """
+        response = client.post(
+            '/api/v3/config/main',
+            data=json.dumps({'target_fps': value}),
+            content_type='application/json',
+        )
+
+        assert response.status_code == 400
+
+    @pytest.mark.parametrize('value', ['20', '250', 'fast'])
+    def test_save_target_fps_rejects_out_of_range(self, client, mock_config_manager, value):
+        """Values ScrollHelper would silently clamp are reported instead."""
+        response = client.post(
+            '/api/v3/config/main',
+            data={'target_fps': value},
+            content_type='application/x-www-form-urlencoded',
+        )
+
+        assert response.status_code == 400
+
+    def test_save_target_fps_accepts_bounds(self, client, mock_config_manager):
+        """Both endpoints of the documented range are valid."""
+        for value in ('30', '200'):
+            response = client.post(
+                '/api/v3/config/main',
+                data={'target_fps': value},
+                content_type='application/x-www-form-urlencoded',
+            )
+            assert response.status_code == 200, f"{value} should be accepted"
+            saved = mock_config_manager.save_config_atomic.call_args[0][0]
+            assert saved['target_fps'] == int(value)
+
     def test_save_double_sided_unchecked_disables(self, client, mock_config_manager):
         """An omitted 'enabled' checkbox is saved as disabled, not left stale."""
         response = client.post(
@@ -175,6 +252,91 @@ class TestConfigAPI:
         assert ds['enabled'] is False
         assert ds['copies'] == 4
 
+    def test_save_double_sided_disabled_skips_divisibility_check(self, client, mock_config_manager):
+        """A copies/chain_length mismatch must not block saves while disabled.
+
+        The Display form posts copies/axis on every save, so validating them
+        with the feature off locked users out of every other display setting.
+        """
+        mock_config_manager.load_config.return_value['display']['hardware'] = {
+            'chain_length': 3, 'parallel': 1,
+        }
+
+        response = client.post(
+            '/api/v3/config/main',
+            data={
+                'double_sided_copies': '2',
+                'double_sided_axis': 'horizontal',
+                'brightness': '75',
+            },
+            content_type='application/x-www-form-urlencoded',
+        )
+
+        assert response.status_code == 200
+        ds = mock_config_manager.save_config_atomic.call_args[0][0]['display']['double_sided']
+        assert ds['enabled'] is False
+        assert ds['copies'] == 2
+
+    def test_save_double_sided_enabled_enforces_divisibility(self, client, mock_config_manager):
+        """The same mismatch is still rejected once the feature is turned on."""
+        mock_config_manager.load_config.return_value['display']['hardware'] = {
+            'chain_length': 3, 'parallel': 1,
+        }
+
+        response = client.post(
+            '/api/v3/config/main',
+            data={
+                'double_sided_enabled': 'true',
+                'double_sided_copies': '2',
+                'double_sided_axis': 'horizontal',
+            },
+            content_type='application/x-www-form-urlencoded',
+        )
+
+        assert response.status_code == 400
+        assert 'chain length' in response.get_json()['message']
+        mock_config_manager.save_config_atomic.assert_not_called()
+
+    def test_save_double_sided_vertical_checks_parallel(self, client, mock_config_manager):
+        """The vertical axis is checked against parallel, not chain_length."""
+        mock_config_manager.load_config.return_value['display']['hardware'] = {
+            'chain_length': 2, 'parallel': 3,
+        }
+
+        response = client.post(
+            '/api/v3/config/main',
+            data={
+                'double_sided_enabled': 'true',
+                'double_sided_copies': '2',
+                'double_sided_axis': 'vertical',
+            },
+            content_type='application/x-www-form-urlencoded',
+        )
+
+        # chain_length 2 would divide evenly — only parallel 3 rejects this.
+        assert response.status_code == 400
+        assert 'parallel' in response.get_json()['message']
+        mock_config_manager.save_config_atomic.assert_not_called()
+
+    def test_save_double_sided_disabled_ignores_bad_values(self, client, mock_config_manager):
+        """While disabled, unusable copies/axis are dropped rather than rejected."""
+        mock_config_manager.load_config.return_value['display']['double_sided'] = {
+            'enabled': True, 'copies': 2, 'axis': 'horizontal',
+        }
+
+        response = client.post(
+            '/api/v3/config/main',
+            data={'double_sided_copies': 'abc', 'double_sided_axis': 'diagonal'},
+            content_type='application/x-www-form-urlencoded',
+        )
+
+        assert response.status_code == 200
+        ds = mock_config_manager.save_config_atomic.call_args[0][0]['display']['double_sided']
+        assert ds['enabled'] is False
+        # Stored values left untouched rather than overwritten with junk.
+        assert ds['copies'] == 2
+        assert ds['axis'] == 'horizontal'
+
     def test_save_double_sided_invalid_copies_rejected(self, client, mock_config_manager):
         """copies < 2 is rejected with a 400 before any save."""
         response = client.post(
@@ -372,11 +534,71 @@ class TestPluginsAPI:
         }
         
         response = client.get('/api/v3/plugins/installed')
-        
+
         assert response.status_code == 200
         data = json.loads(response.data)
         assert isinstance(data, (list, dict))
-    
+
+    def test_installed_plugins_report_update_available(self, client, mock_plugin_manager):
+        """Installed-plugin entries surface latest_version + update_available
+        by comparing the on-disk manifest version to the registry."""
+        from web_interface.blueprints.api_v3 import api_v3
+        api_v3.plugin_manager = mock_plugin_manager
+        # No on-disk manifest to merge — keep the version we hand in below.
+        mock_plugin_manager.plugins_dir = '/nonexistent-plugins-dir'
+        mock_plugin_manager.get_all_plugin_info.return_value = [
+            {'id': 'weather', 'name': 'Weather', 'version': '1.0.0'}
+        ]
+        # Avoid touching plugin instances (Vegas hooks, enabled fallback).
+        mock_plugin_manager.get_plugin.return_value = None
+        # Registry advertises a newer version than the installed one.
+        api_v3.plugin_store_manager.get_registry_info.return_value = {
+            'verified': True, 'latest_version': '1.2.0'
+        }
+
+        response = client.get('/api/v3/plugins/installed')
+
+        assert response.status_code == 200
+        payload = json.loads(response.data)
+        entry = payload['data']['plugins'][0]
+        assert entry['version'] == '1.0.0'
+        assert entry['latest_version'] == '1.2.0'
+        assert entry['update_available'] is True
+
+    def test_installed_plugins_no_update_when_current(self, client, mock_plugin_manager):
+        """No update is flagged when installed version matches the registry."""
+        from web_interface.blueprints.api_v3 import api_v3
+        api_v3.plugin_manager = mock_plugin_manager
+        mock_plugin_manager.plugins_dir = '/nonexistent-plugins-dir'
+        mock_plugin_manager.get_all_plugin_info.return_value = [
+            {'id': 'weather', 'name': 'Weather', 'version': '1.2.0'}
+        ]
+        mock_plugin_manager.get_plugin.return_value = None
+        api_v3.plugin_store_manager.get_registry_info.return_value = {
+            'verified': True, 'latest_version': '1.2.0'
+        }
+
+        response = client.get('/api/v3/plugins/installed')
+
+        assert response.status_code == 200
+        entry = json.loads(response.data)['data']['plugins'][0]
+        assert entry['latest_version'] == '1.2.0'
+        assert entry['update_available'] is False
+
+    def test_is_plugin_update_available_helper(self):
+        """Unit-level checks for the semver-aware update comparison."""
+        from web_interface.blueprints.api_v3 import _is_plugin_update_available
+        assert _is_plugin_update_available('1.0.0', '1.0.1') is True
+        assert _is_plugin_update_available('1.0.1', '1.0.1') is False
+        # Local build ahead of the registry must not be flagged.
+        assert _is_plugin_update_available('2.0.0', '1.9.9') is False
+        # Missing either side yields no signal.
+        assert _is_plugin_update_available('', '1.0.0') is False
+        assert _is_plugin_update_available('1.0.0', '') is False
+        # Unparseable version differing from the installed one surfaces the
+        # mismatch rather than hiding a possible update.
+        assert _is_plugin_update_available('1.0.0', 'not-a-semver') is True
+
     def test_get_plugin_health(self, client, mock_plugin_manager):
         """Test getting plugin health information."""
         from web_interface.blueprints.api_v3 import api_v3

test/test_web_smoke.py

@@ -0,0 +1,184 @@
+"""
+Web-UI smoke tests: every page, partial, and critical static asset must render.
+
+These boot the pages blueprint with the same dual registration app.py uses
+(un-prefixed primary + /v3 legacy alias) and assert each surface returns 200
+with its load-bearing markers present. They exist to catch, in CI, the class
+of regression that only shows up when a real request renders a real template:
+a broken partial, a missing tab wiring, a renamed element id that JS depends
+on, or a static asset that stopped being served.
+"""
+
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+from flask import Flask
+
+PROJECT_ROOT = Path(__file__).parent.parent
+sys.path.insert(0, str(PROJECT_ROOT))
+
+
+SMOKE_CONFIG = {
+    "web_display_autostart": True,
+    "timezone": "America/Chicago",
+    "location": {"city": "Dallas", "state": "Texas", "country": "US"},
+    "plugin_system": {
+        "auto_discover": True,
+        "auto_load_enabled": True,
+        "development_mode": False,
+        "plugins_directory": "plugin-repos",
+    },
+    "schedule": {},
+    "dim_schedule": {"dim_brightness": 30},
+    "sync": {"role": "standalone", "port": 5765, "follower_position": "left"},
+    "clock": {"enabled": True},
+    "ledmatrix-weather": {"enabled": True},
+    "display": {
+        "hardware": {
+            "rows": 32, "cols": 64, "chain_length": 2, "parallel": 1,
+            "brightness": 95, "hardware_mapping": "adafruit-hat-pwm",
+            "led_rgb_sequence": "RGB", "multiplexing": 0, "panel_type": "",
+            "row_address_type": 0, "scan_mode": 0, "pwm_bits": 9,
+            "pwm_dither_bits": 1, "pwm_lsb_nanoseconds": 130,
+            "limit_refresh_rate_hz": 120, "disable_hardware_pulsing": False,
+            "inverse_colors": False, "show_refresh_rate": False,
+        },
+        "runtime": {"gpio_slowdown": 3, "rp1_rio": 0},
+        "double_sided": {"enabled": False, "copies": 2, "axis": "horizontal"},
+        "use_short_date_format": False,
+        "dynamic_duration": {"max_duration_seconds": 180},
+        "vegas_scroll": {
+            "enabled": False, "scroll_speed": 50, "separator_width": 32,
+            "target_fps": 125, "buffer_ahead": 2,
+            "plugin_order": [], "excluded_plugins": [],
+        },
+        "display_durations": {"stale_saved_mode": 45},
+        "plugin_rotation_order": ["ledmatrix-weather", "clock"],
+    },
+}
+
+PLUGIN_MODES = {
+    "clock": ["clock"],
+    "ledmatrix-weather": ["weather_current", "weather_daily"],
+}
+
+
+@pytest.fixture
+def client():
+    base = PROJECT_ROOT / "web_interface"
+    app = Flask(
+        __name__,
+        template_folder=str(base / "templates"),
+        static_folder=str(base / "static"),
+    )
+    app.config["TESTING"] = True
+
+    from web_interface.blueprints import pages_v3 as pv
+
+    # pages_v3 is a module-level Blueprint singleton shared by the whole test
+    # process (test_web_settings_ui.py mutates the same attributes) - save
+    # the originals and restore them on teardown so this fixture can't leak
+    # its mocks into tests that run afterward.
+    original_config_manager = getattr(pv.pages_v3, "config_manager", None)
+    original_plugin_manager = getattr(pv.pages_v3, "plugin_manager", None)
+
+    mock_cm = MagicMock()
+    mock_cm.load_config.return_value = SMOKE_CONFIG
+    mock_cm.get_raw_file_content.return_value = SMOKE_CONFIG
+    mock_cm.get_config_path.return_value = "config/config.json"
+    mock_cm.get_secrets_path.return_value = "config/config_secrets.json"
+    pv.pages_v3.config_manager = mock_cm
+
+    mock_pm = MagicMock()
+    mock_pm.plugins = {}
+    mock_pm.get_all_plugin_info.return_value = [
+        {"id": "clock", "name": "Clock"},
+        {"id": "ledmatrix-weather", "name": "Weather"},
+    ]
+    mock_pm.get_plugin_display_modes.side_effect = (
+        lambda pid: PLUGIN_MODES.get(pid, [])
+    )
+    pv.pages_v3.plugin_manager = mock_pm
+
+    # Same dual registration as web_interface/app.py: un-prefixed primary,
+    # /v3 kept as a working legacy alias.
+    app.register_blueprint(pv.pages_v3, url_prefix="")
+    app.register_blueprint(pv.pages_v3, url_prefix="/v3", name="pages_v3_legacy")
+    try:
+        yield app.test_client()
+    finally:
+        pv.pages_v3.config_manager = original_config_manager
+        pv.pages_v3.plugin_manager = original_plugin_manager
+
+
+# (path, [markers that must appear in the body])
+PAGES = [
+    ("/", ["site-nav", "mobileNavOpen", 'rel="manifest"',
+           "restart-pending-banner", "activeTab = 'durations'"]),
+    ("/partials/overview", ["getting-started-card", "displayImage"]),
+    ("/partials/general", ["timezone"]),
+    ("/partials/display", ["display-section-advanced-hardware",
+                           "display-resolution-value", "vegas_scroll_label"]),
+    ("/partials/durations", ["rotation_plugin_order", "duration__clock",
+                             "duration__weather_current",
+                             "duration__stale_saved_mode"]),
+    ("/partials/schedule", ["schedule"]),
+]
+
+
+@pytest.mark.parametrize("path,markers", PAGES, ids=[p for p, _ in PAGES])
+def test_page_renders_with_markers(client, path, markers):
+    resp = client.get(path)
+    assert resp.status_code == 200, f"{path} -> {resp.status_code}"
+    body = resp.get_data(as_text=True)
+    for marker in markers:
+        assert marker in body, f"{path}: missing marker {marker!r}"
+
+
+@pytest.mark.parametrize("path", [p for p, _ in PAGES if p != "/"])
+def test_legacy_v3_alias_serves_the_same_partials(client, path):
+    assert client.get("/v3" + path).status_code == 200
+
+
+STATIC_ASSETS = [
+    "/static/v3/app.css",
+    "/static/v3/app.js",
+    "/static/v3/manifest.json",
+    "/static/v3/icons/icon-192.png",
+    "/static/v3/js/app-shell.js",
+    "/static/v3/js/app-early.js",
+    "/static/v3/js/htmx-config.js",
+    "/static/v3/js/widgets/plugin-order-list.js",
+    "/static/v3/js/widgets/notification.js",
+    "/static/v3/vendor/fontawesome/css/all.min.css",
+    "/static/v3/vendor/codemirror/codemirror.min.js",
+]
+
+
+@pytest.mark.parametrize("asset", STATIC_ASSETS)
+def test_static_asset_served(client, asset):
+    resp = client.get(asset)
+    assert resp.status_code == 200, f"{asset} -> {resp.status_code}"
+    assert len(resp.data) > 0
+
+
+def test_durations_page_groups_by_plugin(client):
+    """One duration input per display mode of each enabled plugin, plus the
+    leftover group for saved keys no enabled plugin owns."""
+    body = client.get("/partials/durations").get_data(as_text=True)
+    assert body.count("duration__") >= 2 * len(
+        [m for modes in PLUGIN_MODES.values() for m in modes]
+    )  # each mode: id= and name=
+    assert "Other saved entries" in body
+
+
+def test_display_advanced_section_contains_tuning_fields(client):
+    body = client.get("/partials/display").get_data(as_text=True)
+    adv = body.find('id="display-section-advanced-hardware"')
+    adv_close = body.find("/#display-section-advanced-hardware")
+    assert 0 < adv < adv_close
+    for field in ["multiplexing", "pwm_bits", "inverse_colors"]:
+        pos = body.find(f'name="{field}"')
+        assert adv < pos < adv_close, f"{field} not inside the advanced section"

test/test_web_static_audit.py

@@ -0,0 +1,85 @@
+"""
+Static-analysis audits for the web UI, as tests so CI enforces them.
+
+1. Breakpoint utility audit: app.css hand-maintains a Tailwind-style utility
+   subset, so a template can reference a responsive class (e.g. sm:block)
+   that no CSS rule defines — it silently no-ops. This once left the header
+   search box and system stats invisible at every screen width. The audit
+   diffs classes used in templates against classes defined in app.css.
+
+2. Asset reference audit: every url_for('static', filename=...) in the
+   templates must point to a file that exists, so a renamed/moved asset
+   can't ship as a broken <script>/<link>/<img>.
+
+3. debugLog globals audit: any static JS file calling debugLog() (a global
+   defined in base.html) must declare it in a /* global */ header so linting
+   stays clean and the dependency is explicit.
+"""
+
+import re
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).parent.parent
+WEB = PROJECT_ROOT / "web_interface"
+TEMPLATES = WEB / "templates"
+STATIC = WEB / "static"
+APP_CSS = STATIC / "v3" / "app.css"
+
+BP_PREFIXES = ("sm", "md", "lg", "xl", "2xl")
+
+
+def _template_files():
+    return sorted(TEMPLATES.rglob("*.html"))
+
+
+def test_every_used_breakpoint_class_is_defined():
+    used = set()
+    class_attr = re.compile(r'class="([^"]*)"')
+    bp_class = re.compile(r"\b(%s):[A-Za-z0-9_.-]+" % "|".join(BP_PREFIXES))
+    for path in _template_files():
+        for attr in class_attr.findall(path.read_text()):
+            for m in bp_class.finditer(attr):
+                used.add(m.group(0))
+
+    css = APP_CSS.read_text()
+    defined = {
+        m.group(0).lstrip(".").replace("\\:", ":")
+        for m in re.finditer(
+            r"\.(%s)\\:[A-Za-z0-9_-]+" % "|".join(BP_PREFIXES), css
+        )
+    }
+
+    missing = sorted(used - defined)
+    assert not missing, (
+        "Responsive utility classes referenced in templates but never defined "
+        f"in app.css (they silently no-op): {missing}"
+    )
+
+
+def test_every_static_url_for_points_to_a_real_file():
+    ref = re.compile(
+        r"url_for\(\s*['\"]static['\"]\s*,\s*filename\s*=\s*['\"]([^'\"]+)['\"]"
+    )
+    missing = []
+    for path in _template_files():
+        for filename in ref.findall(path.read_text()):
+            if not (STATIC / filename).is_file():
+                missing.append(f"{path.relative_to(PROJECT_ROOT)}: {filename}")
+    assert not missing, f"Templates reference missing static assets: {missing}"
+
+
+def test_js_files_calling_debuglog_declare_the_global():
+    undeclared = []
+    for path in sorted((STATIC / "v3").rglob("*.js")):
+        if "vendor" in path.parts:
+            continue
+        text = path.read_text()
+        # Calls debugLog( but neither defines it nor declares the global
+        calls = re.search(r"(?<![.\w])debugLog\(", text)
+        defines = "window.debugLog" in text
+        declares = re.search(r"/\*\s*global[^*]*\bdebugLog\b", text)
+        if calls and not defines and not declares:
+            undeclared.append(str(path.relative_to(PROJECT_ROOT)))
+    assert not undeclared, (
+        f"JS files call debugLog() without a /* global debugLog */ header: {undeclared}"
+    )

web_interface/app.py

@@ -59,6 +59,20 @@ except ImportError:
     # flask-limiter not installed, rate limiting disabled
     limiter = None
 
+# Enable gzip/brotli response compression (Flask-Compress skips streaming
+# responses, so the SSE endpoints are unaffected). Optional, like limiter:
+# missing package just means uncompressed responses.
+try:
+    from flask_compress import Compress
+
+    Compress(app)
+except ImportError:
+    logging.getLogger(__name__).warning(
+        "flask-compress not installed - responses will be served uncompressed. "
+        "Install it with the Tools tab's 'Install Base Requirements' button or "
+        "'pip install flask-compress'."
+    )
+
 # Import cache functions from separate module to avoid circular imports
 
 # Initialize plugin managers - read plugins directory from config
@@ -176,7 +190,12 @@ except Exception as _hm_err:  # pragma: no cover - defensive startup guard
         "Could not enable plugin health/metrics for web UI: %s", _hm_err
     )
 
-app.register_blueprint(pages_v3, url_prefix='/v3')
+# Pages are served un-prefixed (the interface lives at /); the /v3 mount is a
+# legacy alias kept so existing bookmarks and the hardcoded /v3/partials/...
+# fetches in templates/JS keep working unchanged. url_for('pages_v3.*')
+# resolves against the primary (un-prefixed) registration.
+app.register_blueprint(pages_v3, url_prefix='')
+app.register_blueprint(pages_v3, url_prefix='/v3', name='pages_v3_legacy')
 app.register_blueprint(api_v3, url_prefix='/api/v3')
 
 # Route to serve plugin asset files (registered on main app, not blueprint, for /assets/... path)
@@ -407,7 +426,11 @@ def captive_portal_redirect():
     
     # List of paths that should NOT be redirected (allow normal operation)
     allowed_paths = [
-        '/v3',  # Main interface and all sub-paths (includes /v3/setup)
+        '/v3',  # Legacy-prefixed interface and all sub-paths
+        '/setup',  # Captive setup page itself (un-prefixed mount)
+        '/partials/',  # HTMX partials (un-prefixed mount)
+        '/settings/',  # Settings search index (un-prefixed mount)
+        '/plugin-ui/',  # Plugin-provided web UI assets (un-prefixed mount)
         '/api/v3/',  # All API endpoints
         '/static/',  # Static files (CSS, JS, images)
         '/hotspot-detect.html',  # iOS/macOS detection
@@ -606,8 +629,6 @@ def system_status_generator():
 def display_preview_generator():
     """Generate display preview updates from snapshot file"""
     import base64
-    from PIL import Image
-    import io
 
     snapshot_path = "/tmp/led_matrix_preview.png"  # nosec B108 - fixed path matches display_manager; only read here
     # Viewer marker: this generator only runs while the broadcaster has
@@ -649,24 +670,26 @@ def display_preview_generator():
                 # Only read if file is new or has been updated
                 if last_modified is None or current_modified > last_modified:
                     try:
-                        # Read and encode the image
-                        with Image.open(snapshot_path) as img:
-                            # Convert to PNG and encode as base64
-                            buffer = io.BytesIO()
-                            img.save(buffer, format='PNG')
-                            img_str = base64.b64encode(buffer.getvalue()).decode('utf-8')
-                            
-                            preview_data = {
-                                'timestamp': time.time(),
-                                'width': width,
-                                'height': height,
-                                'image': img_str
-                            }
-                            last_modified = current_modified
-                            yield preview_data
-                    except Exception:  # nosec B110 - SSE preview file may be mid-write; transient error, skip this update
-                        # File might be being written, skip this update
-                        pass
+                        # The snapshot is already a PNG, written atomically by
+                        # the display service (tmp + os.replace in
+                        # display_manager), so pass the raw bytes straight
+                        # through instead of PIL-decoding and re-encoding —
+                        # identical payload, much less CPU on the Pi.
+                        with open(snapshot_path, 'rb') as f:
+                            img_str = base64.b64encode(f.read()).decode('utf-8')
+
+                        preview_data = {
+                            'timestamp': time.time(),
+                            'width': width,
+                            'height': height,
+                            'image': img_str
+                        }
+                        last_modified = current_modified
+                        yield preview_data
+                    except OSError:
+                        # Transient filesystem race (file rotated/replaced
+                        # between mtime check and read); skip this update.
+                        app.logger.debug("Preview snapshot read failed; skipping frame", exc_info=True)
             else:
                 # No snapshot available
                 yield {
@@ -799,11 +822,8 @@ if limiter:
     limiter.limit("200 per minute")(stream_display)
     limiter.limit("200 per minute")(stream_logs)
 
-# Main route - redirect to v3 interface as default
-@app.route('/')
-def index():
-    """Redirect to v3 interface"""
-    return redirect(url_for('pages_v3.index'))
+# The pages blueprint's index now serves '/' directly (see the un-prefixed
+# blueprint registration above), so no redirect route is needed here.
 
 @app.route('/favicon.ico')
 def favicon():

web_interface/blueprints/api_v3.py

@@ -13,7 +13,7 @@ import uuid
 import logging
 from datetime import datetime
 from pathlib import Path
-from typing import Dict, Any
+from typing import Dict, Any, Optional
 from urllib.parse import urlparse, urlunparse
 
 logger = logging.getLogger(__name__)
@@ -120,6 +120,33 @@ def _get_plugin_version(plugin_id: str) -> str:
         logger.warning("[PluginVersion] Invalid JSON in manifest for %s at %s: %s", plugin_id, manifest_path, e)
     return ''
 
+def _is_plugin_update_available(installed_version: str, latest_version: str) -> bool:
+    """Return True when the registry's ``latest_version`` is strictly newer
+    than the installed version.
+
+    Uses PEP 440 / semver-aware comparison so a locally modified plugin whose
+    version is *ahead* of the published registry is not flagged as needing an
+    update. If either version string can't be parsed, falls back to a plain
+    inequality check (any difference is surfaced so the user can reconcile).
+    """
+    if not installed_version or not latest_version:
+        return False
+    if installed_version == latest_version:
+        return False
+    try:
+        from packaging.version import parse as _parse_version, InvalidVersion
+    except ImportError:
+        # packaging is a core dependency, but if it's somehow unavailable we
+        # can't compare semantically — surface the mismatch we already know
+        # exists (the two strings differ).
+        return True
+    try:
+        return _parse_version(latest_version) > _parse_version(installed_version)
+    except InvalidVersion:
+        # Unparseable version string: we can't tell direction, so surface the
+        # mismatch rather than silently hiding a potential update.
+        return True
+
 def _ensure_cache_manager():
     """Ensure cache manager is initialized."""
     global cache_manager
@@ -720,6 +747,36 @@ def save_main_config():
         if 'timezone' in data:
             current_config['timezone'] = data['timezone']
 
+        # Device-wide scroll frame rate, read by plugins via
+        # BasePlugin.global_config. Bounds match ScrollHelper.set_target_fps,
+        # which clamps silently -- rejecting here instead means a value that
+        # would have been quietly altered is reported rather than appearing to
+        # save and then behaving differently.
+        if 'target_fps' in data and data['target_fps'] not in ('', None):
+            raw_target_fps = data['target_fps']
+            # A JSON body can carry real floats and bools, where int() would
+            # silently truncate: 90.5 would save as 90, and true as 1. Reject
+            # them rather than storing a value the user did not ask for. Form
+            # posts arrive as strings, so '90.5' still fails in int() below.
+            if isinstance(raw_target_fps, (bool, float)):
+                return jsonify({
+                    'status': 'error',
+                    'message': "Invalid value for target_fps: must be an integer"
+                }), 400
+            try:
+                target_fps = int(raw_target_fps)
+            except (ValueError, TypeError):
+                return jsonify({
+                    'status': 'error',
+                    'message': "Invalid value for target_fps: must be an integer"
+                }), 400
+            if not (30 <= target_fps <= 200):
+                return jsonify({
+                    'status': 'error',
+                    'message': "Invalid value for target_fps: must be between 30 and 200"
+                }), 400
+            current_config['target_fps'] = target_fps
+
         # Handle location settings
         if 'city' in data or 'state' in data or 'country' in data:
             if 'location' not in current_config:
@@ -837,16 +894,15 @@ def save_main_config():
             ds_config = current_config['display']['double_sided']
 
             # Enabled checkbox: omitted from the form when unchecked.
-            ds_config['enabled'] = _coerce_to_bool(data.get('double_sided_enabled'))
+            # The Display form posts copies/axis on every save regardless of this
+            # 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.
+            enabled = _coerce_to_bool(data.get('double_sided_enabled'))
+            ds_config['enabled'] = enabled
 
-            if 'double_sided_copies' in data and data['double_sided_copies'] not in ('', None):
-                try:
-                    copies = int(data['double_sided_copies'])
-                except (ValueError, TypeError):
-                    return jsonify({'status': 'error', 'message': "Double-sided copies must be an integer"}), 400
-                if not (2 <= copies <= 8):
-                    return jsonify({'status': 'error', 'message': "Double-sided copies must be between 2 and 8"}), 400
-                # Validate divisibility against the relevant hardware dimension.
+            def _copies_fits_hardware(copies: int) -> Optional[str]:
+                """Error message if copies doesn't divide the panel evenly, else None."""
                 # Use axis from this request if provided, else from stored config.
                 hw = current_config.get('display', {}).get('hardware', {})
                 effective_axis = (data.get('double_sided_axis')
@@ -854,22 +910,53 @@ def save_main_config():
                 if effective_axis == 'horizontal':
                     chain_length = int(hw.get('chain_length', 2) or 2)
                     if chain_length % copies != 0:
-                        return jsonify({'status': 'error', 'message': f"Double-sided copies ({copies}) must divide chain length ({chain_length}) evenly"}), 400
+                        return f"Double-sided copies ({copies}) must divide chain length ({chain_length}) evenly"
                 elif effective_axis == 'vertical':
                     parallel = int(hw.get('parallel', 1) or 1)
                     if parallel % copies != 0:
-                        return jsonify({'status': 'error', 'message': f"Double-sided copies ({copies}) must divide parallel ({parallel}) evenly"}), 400
-                ds_config['copies'] = copies
+                        return f"Double-sided copies ({copies}) must divide parallel ({parallel}) evenly"
+                return None
+
+            if 'double_sided_copies' in data and data['double_sided_copies'] not in ('', None):
+                copies = None
+                try:
+                    copies = int(data['double_sided_copies'])
+                except (ValueError, TypeError):
+                    if enabled:
+                        return jsonify({'status': 'error', 'message': "Double-sided copies must be an integer"}), 400
+                if copies is not None and not (2 <= copies <= 8):
+                    if enabled:
+                        return jsonify({'status': 'error', 'message': "Double-sided copies must be between 2 and 8"}), 400
+                    # Disabled: leave the stored value alone rather than writing junk.
+                    copies = None
+                if copies is not None:
+                    # Divisibility is a hardware-relational check — only meaningful
+                    # when the feature is actually on.
+                    if enabled:
+                        fit_error = _copies_fits_hardware(copies)
+                        if fit_error:
+                            return jsonify({'status': 'error', 'message': fit_error}), 400
+                    ds_config['copies'] = copies
 
             if 'double_sided_axis' in data:
                 axis = data['double_sided_axis']
                 if axis not in ('horizontal', 'vertical'):
-                    return jsonify({'status': 'error', 'message': "Double-sided axis must be 'horizontal' or 'vertical'"}), 400
-                ds_config['axis'] = axis
+                    if enabled:
+                        return jsonify({'status': 'error', 'message': "Double-sided axis must be 'horizontal' or 'vertical'"}), 400
+                else:
+                    ds_config['axis'] = axis
 
         # Handle Vegas scroll mode settings
         vegas_fields = ['vegas_scroll_enabled', 'vegas_scroll_speed', 'vegas_separator_width',
-                       'vegas_target_fps', 'vegas_buffer_ahead', 'vegas_plugin_order', 'vegas_excluded_plugins']
+                       'vegas_target_fps', 'vegas_buffer_ahead', 'vegas_plugin_order', 'vegas_excluded_plugins',
+                       'vegas_auto_trim', 'vegas_trim_threshold', 'vegas_content_padding',
+                       'vegas_min_plugin_width', 'vegas_lead_in_width', 'vegas_plugins_per_cycle',
+                       'vegas_max_plugin_width_ratio', 'vegas_dynamic_duration_enabled',
+                       'vegas_min_cycle_duration', 'vegas_max_cycle_duration',
+                       'vegas_intra_plugin_gap', 'vegas_render_width_pct',
+                       'vegas_min_content_separation', 'vegas_min_cut_gap',
+                       'vegas_continuous_scroll', 'vegas_extend_threshold_screens',
+                       'vegas_smooth_scroll', 'vegas_overflow_mode']
 
         if any(k in data for k in vegas_fields):
             if 'display' not in current_config:
@@ -884,13 +971,85 @@ def save_main_config():
             # was submitted (any vegas field present) but enabled key is missing,
             # the checkbox was unchecked and we should set enabled=False
             vegas_config['enabled'] = _coerce_to_bool(data.get('vegas_scroll_enabled'))
+            vegas_config['auto_trim'] = _coerce_to_bool(data.get('vegas_auto_trim'))
+            vegas_config['dynamic_duration_enabled'] = _coerce_to_bool(
+                data.get('vegas_dynamic_duration_enabled'))
+            vegas_config['continuous_scroll'] = _coerce_to_bool(
+                data.get('vegas_continuous_scroll'))
+            vegas_config['smooth_scroll'] = _coerce_to_bool(
+                data.get('vegas_smooth_scroll'))
 
-            # Handle numeric settings with validation
+            # max_plugin_width_ratio is the one fractional setting, so it is
+            # handled outside the integer loop below.
+            if data.get('vegas_overflow_mode') not in ('', None):
+                mode = str(data['vegas_overflow_mode']).strip().lower()
+                if mode not in ('rotate', 'truncate'):
+                    return jsonify({
+                        'status': 'error',
+                        'message': "Invalid value for vegas_overflow_mode: "
+                                   "must be 'rotate' or 'truncate'"
+                    }), 400
+                vegas_config['overflow_mode'] = mode
+
+            if data.get('vegas_extend_threshold_screens') not in ('', None):
+                try:
+                    screens = float(data['vegas_extend_threshold_screens'])
+                except (ValueError, TypeError):
+                    return jsonify({
+                        'status': 'error',
+                        'message': "Invalid value for vegas_extend_threshold_screens: "
+                                   "must be a number"
+                    }), 400
+                if not (1.0 <= screens <= 10.0):
+                    return jsonify({
+                        'status': 'error',
+                        'message': "Invalid value for vegas_extend_threshold_screens: "
+                                   "must be between 1.0 and 10.0"
+                    }), 400
+                vegas_config['extend_threshold_screens'] = screens
+
+            if data.get('vegas_max_plugin_width_ratio') not in ('', None):
+                try:
+                    ratio = float(data['vegas_max_plugin_width_ratio'])
+                except (ValueError, TypeError):
+                    return jsonify({
+                        'status': 'error',
+                        'message': "Invalid value for vegas_max_plugin_width_ratio: "
+                                   "must be a number"
+                    }), 400
+                if not (0 <= ratio <= 20):
+                    return jsonify({
+                        'status': 'error',
+                        'message': "Invalid value for vegas_max_plugin_width_ratio: "
+                                   "must be between 0 and 20 (0 disables the cap)"
+                    }), 400
+                vegas_config['max_plugin_width_ratio'] = ratio
+
+            # Handle numeric settings with validation.
+            #
+            # These bounds must match VegasModeConfig.validate(), which is what
+            # actually gates Vegas starting. Where they were looser, a value
+            # saved with a 200 and then made VegasModeCoordinator.start() bail
+            # out with only a log line, so the ticker silently never ran.
+            # Where they were tighter (scroll_speed capped at 100 against a
+            # slider that goes to 200), a legitimate value was rejected with a
+            # 400. See test_vegas_api_bounds_match_validate.
             numeric_fields = {
-                'vegas_scroll_speed': ('scroll_speed', 1, 100),
-                'vegas_separator_width': ('separator_width', 0, 500),
-                'vegas_target_fps': ('target_fps', 1, 200),
-                'vegas_buffer_ahead': ('buffer_ahead', 1, 20),
+                'vegas_scroll_speed': ('scroll_speed', 1, 200),
+                'vegas_separator_width': ('separator_width', 0, 128),
+                'vegas_intra_plugin_gap': ('intra_plugin_gap', 0, 128),
+                'vegas_render_width_pct': ('render_width_pct', 10, 100),
+                'vegas_min_content_separation': ('min_content_separation', 0, 256),
+                'vegas_min_cut_gap': ('min_cut_gap', 1, 128),
+                'vegas_target_fps': ('target_fps', 30, 200),
+                'vegas_buffer_ahead': ('buffer_ahead', 1, 5),
+                'vegas_trim_threshold': ('trim_threshold', 0, 254),
+                'vegas_content_padding': ('content_padding', 0, 128),
+                'vegas_min_plugin_width': ('min_plugin_width', 0, 512),
+                'vegas_lead_in_width': ('lead_in_width', 0, 2048),
+                'vegas_plugins_per_cycle': ('plugins_per_cycle', 1, 50),
+                'vegas_min_cycle_duration': ('min_cycle_duration', 5, 3600),
+                'vegas_max_cycle_duration': ('max_cycle_duration', 10, 3600),
             }
             for field_name, (config_key, min_val, max_val) in numeric_fields.items():
                 if field_name in data:
@@ -961,8 +1120,31 @@ def save_main_config():
                     return jsonify({"status": "error", "message": "sync_follower_position must be left or right"}), 400
                 current_config["sync"]["follower_position"] = pos_val
 
-        # Handle display durations
-        duration_fields = [k for k in data.keys() if k.endswith('_duration') or k in ['default_duration', 'transition_duration']]
+        # Handle primary rotation order: must be a JSON array of plugin-id
+        # strings. Reject anything else with a 400 rather than silently
+        # coercing, so a buggy client can't clear or corrupt the saved order.
+        if 'plugin_rotation_order' in data:
+            raw_order = data.pop('plugin_rotation_order')
+            try:
+                parsed = json.loads(raw_order) if isinstance(raw_order, str) else raw_order
+            except (json.JSONDecodeError, TypeError, ValueError):
+                return jsonify({'status': 'error',
+                                'message': 'plugin_rotation_order must be valid JSON'}), 400
+            if not isinstance(parsed, list) or not all(isinstance(p, str) for p in parsed):
+                return jsonify({'status': 'error',
+                                'message': 'plugin_rotation_order must be a list of plugin-id strings'}), 400
+            if 'display' not in current_config:
+                current_config['display'] = {}
+            current_config['display']['plugin_rotation_order'] = parsed
+
+        # Handle display durations. Popped from `data` (not just read) so
+        # they can never also fall through to the generic "remaining keys"
+        # merge near the end of this function, which would otherwise write
+        # 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).
+        duration_fields = [k for k in list(data.keys())
+                           if k.endswith('_duration') or k in ('default_duration', 'transition_duration')]
         if duration_fields:
             if 'display' not in current_config:
                 current_config['display'] = {}
@@ -970,8 +1152,36 @@ def save_main_config():
                 current_config['display']['display_durations'] = {}
 
             for field in duration_fields:
-                if field in data:
-                    current_config['display']['display_durations'][field] = int(data[field])
+                raw_value = data.pop(field)
+                try:
+                    int_value = int(raw_value)
+                except (ValueError, TypeError):
+                    return jsonify({'status': 'error',
+                                    'message': f"Invalid duration for {field}: must be an integer"}), 400
+                current_config['display']['display_durations'][field] = int_value
+
+        # Per-mode durations from the Rotation & Durations page, posted as
+        # duration__<mode_key> (mode keys are arbitrary plugin mode names, so
+        # they can't use the suffix convention above). Same pop-and-validate
+        # treatment, for the same reason.
+        mode_duration_fields = [k for k in list(data.keys()) if k.startswith('duration__')]
+        if mode_duration_fields:
+            if 'display' not in current_config:
+                current_config['display'] = {}
+            if 'display_durations' not in current_config['display']:
+                current_config['display']['display_durations'] = {}
+
+            for field in mode_duration_fields:
+                raw_value = data.pop(field)
+                mode_key = field[len('duration__'):]
+                if not mode_key:
+                    continue
+                try:
+                    int_value = int(raw_value)
+                except (ValueError, TypeError):
+                    return jsonify({'status': 'error',
+                                    'message': f"Invalid duration for mode '{mode_key}': must be an integer"}), 400
+                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
@@ -1102,7 +1312,7 @@ def save_main_config():
             if key in ['timezone', 'city', 'state', 'country',
                        'web_display_autostart', 'auto_discover',
                        'auto_load_enabled', 'development_mode',
-                       'plugins_directory']:
+                       'plugins_directory', 'target_fps']:
                 continue
             # Skip fields that are already handled above in their own named sections.
             # Without this, every form field name lands as a top-level config key too.
@@ -1639,6 +1849,16 @@ def execute_system_action():
                 except subprocess.TimeoutExpired:
                     logger.warning("git stash timed out, proceeding with pull")
 
+            # Record HEAD before the pull so dependency changes can be detected
+            old_head = None
+            try:
+                _pre = subprocess.run(['git', 'rev-parse', 'HEAD'],
+                                      capture_output=True, text=True, timeout=10, cwd=project_dir)
+                if _pre.returncode == 0:
+                    old_head = _pre.stdout.strip()
+            except subprocess.TimeoutExpired:
+                logger.warning("git rev-parse timed out before pull")
+
             # Perform the git pull
             result = subprocess.run(
                 ['git', 'pull', '--rebase'],
@@ -1655,6 +1875,54 @@ def execute_system_action():
                     pull_message = f"Code updated successfully. Local changes were automatically stashed.{stash_info}"
                 if result.stdout and "Already up to date" not in result.stdout:
                     pull_message = f"Code updated successfully.{stash_info}"
+
+                # Keep Python dependencies in sync automatically: if the pull
+                # changed a requirements file, install it now — users updating
+                # from the web UI (most of them) never SSH in to pip install.
+                # Installs go through the same root-visible path as the
+                # Tools-tab buttons (_pip_install_requirements).
+                dep_notes = []
+                try:
+                    _post = subprocess.run(['git', 'rev-parse', 'HEAD'],
+                                           capture_output=True, text=True, timeout=10, cwd=project_dir)
+                    new_head = _post.stdout.strip() if _post.returncode == 0 else None
+                    if old_head and new_head and old_head != new_head:
+                        diff = subprocess.run(
+                            ['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'):
+                            req_path = PROJECT_ROOT / rel
+                            if rel not in changed or not req_path.exists():
+                                continue
+                            # Each file's install is isolated: a timeout or
+                            # OSError (e.g. the sudo wrapper/interpreter
+                            # missing) on one file must not abort the other.
+                            try:
+                                r = _pip_install_requirements(req_path, timeout=180)
+                                if r.returncode == 0:
+                                    dep_notes.append(f"Dependencies from {rel} updated.")
+                                else:
+                                    dep_notes.append(
+                                        f"Dependency install from {rel} failed — "
+                                        "run Install Base Requirements from the Tools tab.")
+                                    logger.warning("post-update pip install failed for %s: %s",
+                                                   rel, _truncate_output(r.stdout, r.stderr))
+                            except subprocess.TimeoutExpired:
+                                dep_notes.append(
+                                    f"Dependency install from {rel} timed out — "
+                                    "run Install Base Requirements from the Tools tab.")
+                                logger.warning("post-update pip install timed out for %s", rel)
+                            except OSError as install_err:
+                                dep_notes.append(
+                                    f"Dependency install from {rel} failed — "
+                                    "run Install Base Requirements from the Tools tab.")
+                                logger.warning("post-update pip install errored for %s: %s",
+                                               rel, install_err)
+                except subprocess.TimeoutExpired:
+                    logger.warning("post-update dependency sync timed out")
+                if dep_notes:
+                    pull_message += " " + " ".join(dep_notes)
                 # A `git pull` restores built-in plugins (committed under
                 # plugin-repos/) even if the user uninstalled them. Re-remove
                 # any the user previously uninstalled so the update doesn't
@@ -1685,14 +1953,36 @@ def execute_system_action():
             result = subprocess.run(['sudo', 'systemctl', 'restart', 'ledmatrix-web.service'],
                                  capture_output=True, text=True, timeout=10)
         elif action == 'install_base_requirements':
-            req_file = PROJECT_ROOT / 'requirements.txt'
-            if not req_file.exists():
+            # Base + web interface requirements: flask-compress and friends
+            # live in web_interface/requirements.txt, not the root file.
+            req_files = [f for f in (PROJECT_ROOT / 'requirements.txt',
+                                     PROJECT_ROOT / 'web_interface' / 'requirements.txt')
+                         if f.exists()]
+            if not req_files:
                 return jsonify({'status': 'error', 'message': 'No requirements.txt found at project root'})
-            result = _pip_install_requirements(req_file, timeout=120)
+            outputs = []
+            all_ok = True
+            for req_file in req_files:
+                label = req_file.relative_to(PROJECT_ROOT)
+                # Isolate each file's install: a timeout or OSError on one
+                # (e.g. requirements.txt) must not abort the rest of the
+                # loop (e.g. web_interface/requirements.txt never attempted).
+                try:
+                    result = _pip_install_requirements(req_file, timeout=120)
+                    all_ok = all_ok and result.returncode == 0
+                    outputs.append(f"== {label} ==\n" + _truncate_output(result.stdout, result.stderr))
+                except subprocess.TimeoutExpired:
+                    all_ok = False
+                    outputs.append(f"== {label} ==\nTimed out after 120s")
+                    logger.warning("install_base_requirements timed out for %s", label)
+                except OSError as install_err:
+                    all_ok = False
+                    outputs.append(f"== {label} ==\nFailed: {install_err}")
+                    logger.warning("install_base_requirements errored for %s: %s", label, install_err)
             return jsonify({
-                'status': 'success' if result.returncode == 0 else 'error',
-                'message': 'Base requirements installed successfully' if result.returncode == 0 else 'pip install failed',
-                'output': _truncate_output(result.stdout, result.stderr)
+                'status': 'success' if all_ok else 'error',
+                'message': 'Base requirements installed successfully' if all_ok else 'pip install failed',
+                'output': "\n".join(outputs)
             })
         elif action == 'install_plugin_requirements':
             active_pm = getattr(api_v3, 'plugin_manager', None)
@@ -2111,9 +2401,12 @@ def get_installed_plugins():
             if enabled is None:
                 enabled = plugin_instance.enabled if plugin_instance else True
 
-            # Verified from registry (no network call)
+            # Verified + latest published version from registry (no network call)
             store_info = api_v3.plugin_store_manager.get_registry_info(plugin_id)
             verified = store_info.get('verified', False) if store_info else False
+            latest_version = store_info.get('latest_version', '') if store_info else ''
+            installed_version = plugin_info.get('version', '')
+            update_available = _is_plugin_update_available(installed_version, latest_version)
 
             # Local git info (single subprocess on cache miss, zero on hit)
             plugin_path = Path(api_v3.plugin_manager.plugins_dir) / plugin_id
@@ -2160,6 +2453,8 @@ def get_installed_plugins():
                 'id': plugin_id,
                 'name': plugin_info.get('name', plugin_id),
                 'version': plugin_info.get('version', ''),
+                'latest_version': latest_version,
+                'update_available': update_available,
                 'author': plugin_info.get('author', 'Unknown'),
                 'category': plugin_info.get('category', 'General'),
                 'description': plugin_info.get('description', 'No description available'),
@@ -5262,6 +5557,18 @@ def get_plugin_schema():
         schema = schema_mgr.load_schema(plugin_id, use_cache=True)
 
         if schema:
+            # Offer installed visual skins as a dropdown (returns a copy;
+            # the cached schema and validation are never enum-restricted)
+            try:
+                current_skin = None
+                if api_v3.config_manager:
+                    config = api_v3.config_manager.load_config()
+                    current_skin = config.get(plugin_id, {}).get('skin')
+                injected = schema_mgr.inject_skin_selector(schema, plugin_id, current_skin)
+                if isinstance(injected, dict):
+                    schema = injected
+            except Exception:
+                logger.debug('Skin selector injection failed for %s', plugin_id, exc_info=True)
             return jsonify({'status': 'success', 'data': {'schema': schema}})
 
         # Return a simple default schema if file not found
@@ -5290,6 +5597,43 @@ def get_plugin_schema():
         logger.error('Error in get_plugin_schema', exc_info=True)
         return jsonify({'status': 'error', 'message': 'An error occurred; see logs for details'}), 500
 
+@api_v3.route('/skins', methods=['GET'])
+def list_skins():
+    """List installed visual skins (docs/SKIN_SYSTEM.md).
+
+    Optional ?plugin_id=... filters to skins matching that plugin.
+    """
+    try:
+        from src.skin_system import skin_runtime
+
+        plugin_id = request.args.get('plugin_id')
+        if plugin_id:
+            skins = skin_runtime.skins_for_plugin(plugin_id)
+        else:
+            # The discovery cache self-invalidates on directory/manifest
+            # mtime changes, so no force_refresh — keeps Pi disk I/O down.
+            skins = skin_runtime.discover_skins()
+
+        payload = []
+        for skin_id, manifest in sorted(skins.items()):
+            skin_dir = Path(manifest['_skin_dir'])
+            preview = manifest.get('preview')
+            payload.append({
+                'id': skin_id,
+                'name': manifest.get('name', skin_id),
+                'version': manifest.get('version'),
+                'author': manifest.get('author'),
+                'description': manifest.get('description', ''),
+                'skin_api_version': manifest.get('skin_api_version'),
+                'targets': manifest.get('targets', {}),
+                'modes': manifest.get('modes', []),
+                'has_preview': bool(preview and (skin_dir / preview).is_file()),
+            })
+        return jsonify({'status': 'success', 'data': {'skins': payload}})
+    except Exception:
+        logger.error('Error in list_skins', exc_info=True)
+        return jsonify({'status': 'error', 'message': 'An error occurred; see logs for details'}), 500
+
 @api_v3.route('/plugins/config/reset', methods=['POST'])
 def reset_plugin_config():
     """Reset plugin configuration to schema defaults"""
@@ -6891,6 +7235,29 @@ def list_plugin_assets():
         logger.error('Unhandled exception', exc_info=True)
         return jsonify({'status': 'error', 'message': 'An error occurred; see logs for details'}), 500
 
+@api_v3.route('/display/current-status', methods=['GET'])
+def get_current_display_status():
+    """Return the display mode/plugin currently intended to be shown.
+
+    Published by the display process (display_controller._publish_current_mode_state)
+    to the shared cache whenever the active mode changes, so the web UI (e.g. the
+    System Logs page) can show what's on screen without querying the display
+    process directly.
+    """
+    try:
+        cache = _ensure_cache_manager()
+        state = cache.get('display_current_state', max_age=120)
+        if state is None:
+            state = {
+                'mode': None,
+                'plugin_id': None,
+                'last_updated': None,
+            }
+        return jsonify({'status': 'success', 'data': state})
+    except Exception:
+        logger.error('Error in get_current_display_status', exc_info=True)
+        return jsonify({'status': 'error', 'message': 'An error occurred; see logs for details'}), 500
+
 @api_v3.route('/logs', methods=['GET'])
 def get_logs():
     """Get system logs from journalctl"""

web_interface/blueprints/pages_v3.py

@@ -397,12 +397,51 @@ def _load_display_partial():
         return "Error loading partial", 500
 
 def _load_durations_partial():
-    """Load display durations partial"""
+    """Load rotation & durations partial.
+
+    Builds one duration entry per display mode of every enabled plugin
+    (falling back to the display controller's 30s default), overlaid with any
+    values saved in display.display_durations. Historically the template only
+    looped over saved keys, and nothing ever populated them, so the page
+    rendered empty.
+    """
     try:
         if pages_v3.config_manager:
             main_config = pages_v3.config_manager.load_config()
+            duration_groups = []
+            covered_keys = set()
+            if pages_v3.plugin_manager:
+                try:
+                    pages_v3.plugin_manager.discover_plugins()
+                    saved = (main_config.get('display', {}) or {}).get('display_durations', {}) or {}
+                    infos = sorted(pages_v3.plugin_manager.get_all_plugin_info(),
+                                   key=lambda i: (i.get('name') or i.get('id') or '').lower())
+                    for info in infos:
+                        pid = info.get('id')
+                        if not pid or not (main_config.get(pid, {}) or {}).get('enabled', False):
+                            continue
+                        modes = pages_v3.plugin_manager.get_plugin_display_modes(pid) or [pid]
+                        covered_keys.update(modes)
+                        duration_groups.append({
+                            'plugin_id': pid,
+                            'plugin_name': info.get('name') or pid,
+                            'modes': [{'key': m, 'value': saved.get(m, 30)} for m in modes],
+                        })
+                    # Saved keys not owned by any enabled plugin (disabled or
+                    # uninstalled plugins) stay visible rather than vanishing.
+                    leftovers = [{'key': k, 'value': v} for k, v in saved.items()
+                                 if k not in covered_keys]
+                    if leftovers:
+                        duration_groups.append({
+                            'plugin_id': '',
+                            'plugin_name': 'Other saved entries',
+                            'modes': leftovers,
+                        })
+                except Exception:
+                    logger.warning("durations: could not enumerate plugin modes", exc_info=True)
             return render_template('v3/partials/durations.html',
-                                 main_config=main_config)
+                                 main_config=main_config,
+                                 duration_groups=duration_groups)
     except Exception as e:
         logger.error("Error loading partial", exc_info=True)
         return "Error loading partial", 500

web_interface/requirements.txt

@@ -7,6 +7,7 @@ flask>=3.1.3,<4.0.0
 werkzeug>=3.1.6,<4.0.0
 flask-wtf>=1.2.0  # CSRF protection (optional for local-only, but recommended)
 flask-limiter>=3.5.0  # Rate limiting (prevent accidental abuse)
+flask-compress>=1.14  # gzip/brotli response compression (big win for the large JS/HTML over WiFi)
 
 # WebSocket support for plugins
 # Note: Web interface uses Server-Sent Events (SSE) for real-time updates, not WebSockets

web_interface/static/v3/app.css

@@ -413,6 +413,9 @@ a, button, input, select, textarea {
 /* Responsive breakpoints */
 @media (min-width: 640px) {
     .sm\:px-6 { padding-left: 1.5rem; padding-right: 1.5rem; }
+    .sm\:block { display: block; }
+    .sm\:grid-cols-2 { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+    .sm\:text-sm { font-size: 0.875rem; line-height: 1.25rem; }
 }
 
 @media (min-width: 768px) {
@@ -421,6 +424,8 @@ a, button, input, select, textarea {
     .md\:grid-cols-4 { grid-template-columns: repeat(4, minmax(0, 1fr)); }
     .md\:flex { display: flex; }
     .md\:hidden { display: none; }
+    .md\:block { display: block; }
+    .md\:w-auto { width: auto; }
 }
 
 @media (min-width: 1024px) {
@@ -431,9 +436,14 @@ a, button, input, select, textarea {
     .lg\:px-8 { padding-left: 2rem; padding-right: 2rem; }
     .lg\:gap-x-3 { column-gap: 0.75rem; }
     .lg\:gap-x-6 { column-gap: 1.5rem; }
+    .lg\:block { display: block; }
+    .lg\:flex { display: flex; }
+    .lg\:w-64 { width: 16rem; }
 }
 
 @media (min-width: 1280px) {
+    .xl\:grid-cols-2 { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+    .xl\:grid-cols-3 { grid-template-columns: repeat(3, minmax(0, 1fr)); }
     .xl\:grid-cols-4 { grid-template-columns: repeat(4, minmax(0, 1fr)); }
     .xl\:grid-cols-5 { grid-template-columns: repeat(5, minmax(0, 1fr)); }
     .xl\:grid-cols-6 { grid-template-columns: repeat(6, minmax(0, 1fr)); }
@@ -446,6 +456,9 @@ a, button, input, select, textarea {
 }
 
 @media (min-width: 1536px) {
+    .2xl\:grid-cols-2 { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+    .2xl\:grid-cols-3 { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+    .2xl\:grid-cols-4 { grid-template-columns: repeat(4, minmax(0, 1fr)); }
     .2xl\:grid-cols-5 { grid-template-columns: repeat(5, minmax(0, 1fr)); }
     .2xl\:grid-cols-6 { grid-template-columns: repeat(6, minmax(0, 1fr)); }
     .2xl\:grid-cols-7 { grid-template-columns: repeat(7, minmax(0, 1fr)); }
@@ -456,6 +469,129 @@ a, button, input, select, textarea {
     .2xl\:space-x-8 > * + * { margin-left: 2rem; }
 }
 
+/* ===== Mobile navigation drawer =====
+   Below md the #site-nav wrapper becomes an off-canvas drawer; at md and up
+   none of these rules apply and the nav renders exactly as before. */
+@media (max-width: 767.98px) {
+    .site-nav {
+        position: fixed;
+        top: 0;
+        left: 0;
+        bottom: 0;
+        z-index: 60;
+        width: min(85vw, 320px);
+        background-color: var(--color-surface);
+        border-right: 1px solid var(--color-border);
+        transform: translateX(-100%);
+        transition: transform 0.25s ease;
+        overflow-y: auto;
+        padding: 1rem;
+        -webkit-overflow-scrolling: touch;
+    }
+    .site-nav.open {
+        transform: translateX(0);
+        box-shadow: 0 0 24px rgba(0, 0, 0, 0.25);
+    }
+    /* Tabs become full-width rows with >=44px touch targets */
+    .site-nav .nav-tab {
+        display: flex;
+        width: 100%;
+        align-items: center;
+        gap: 0.5rem;
+        text-align: left;
+        padding: 0.75rem 1rem;
+        min-height: 44px;
+    }
+    .site-nav nav.-mb-px {
+        display: block;
+    }
+    .nav-backdrop {
+        position: fixed;
+        inset: 0;
+        z-index: 55;
+        background-color: rgba(0, 0, 0, 0.4);
+    }
+    /* Header widgets relocated into the drawer (see placeHeaderWidgets in
+       app.js). The originals carry `hidden`/breakpoint classes tuned for the
+       header, so re-enable them explicitly in the drawer context. */
+    #drawer-widgets #settings-search-wrap {
+        display: block !important;
+        margin-bottom: 1rem;
+    }
+    #drawer-widgets #settings-search-wrap input {
+        width: 100%;
+    }
+    #drawer-widgets #settings-search-results {
+        position: static;
+        width: 100%;
+        max-height: 50vh;
+        margin-top: 0.25rem;
+    }
+    #drawer-widgets #system-stats {
+        display: flex !important;
+        justify-content: space-between;
+        margin-bottom: 1rem;
+    }
+    /* Larger touch targets inside horizontally scrolling tables */
+    .overflow-x-auto table button {
+        min-width: 44px;
+        min-height: 44px;
+    }
+    .overflow-x-auto table input:not([type="checkbox"]),
+    .overflow-x-auto table select {
+        min-height: 40px;
+    }
+    .overflow-x-auto table input[type="checkbox"] {
+        width: 1.25rem;
+        height: 1.25rem;
+    }
+}
+
+@media (min-width: 768px) {
+    /* Hard guards: even if mobileNavOpen was left true when the viewport
+       crossed the breakpoint, the drawer/backdrop must render as plain
+       in-flow nav on desktop. */
+    .site-nav {
+        position: static;
+        transform: none;
+        width: auto;
+        padding: 0;
+        border-right: none;
+        box-shadow: none;
+        background-color: transparent;
+        overflow-y: visible;
+    }
+    .nav-backdrop {
+        display: none !important;
+    }
+    #drawer-widgets {
+        display: none;
+    }
+}
+
+/* Mobile modal sizing: every .modal-content dialog fits the viewport with
+   internal scrolling instead of overflowing it. */
+@media (max-width: 640px) {
+    .modal-content {
+        width: 95vw !important;
+        max-width: 95vw !important;
+        max-height: 90vh;
+        overflow-y: auto;
+    }
+}
+
+/* Edge-fade hint that a container scrolls horizontally (pure CSS,
+   Lea Verou scrolling-shadows technique — backgrounds sit behind content). */
+.overflow-x-auto {
+    background:
+        linear-gradient(90deg, var(--color-surface) 30%, rgba(255, 255, 255, 0)) left / 24px 100%,
+        linear-gradient(270deg, var(--color-surface) 30%, rgba(255, 255, 255, 0)) right / 24px 100%,
+        radial-gradient(farthest-side at 0 50%, rgba(0, 0, 0, 0.18), rgba(0, 0, 0, 0)) left / 12px 100%,
+        radial-gradient(farthest-side at 100% 50%, rgba(0, 0, 0, 0.18), rgba(0, 0, 0, 0)) right / 12px 100%;
+    background-repeat: no-repeat;
+    background-attachment: local, local, scroll, scroll;
+}
+
 /* HTMX loading states */
 .htmx-request .loading {
     display: inline-block;
@@ -1198,6 +1334,21 @@ button.bg-white {
     color: #93c5fd;
 }
 
+/* Installed-plugin "Update" button when a newer version is published.
+   A gentle pulsing ring draws the eye without being noisy. */
+.plugin-update-available {
+    box-shadow: 0 0 0 0 rgba(59, 130, 246, 0.6);
+    animation: plugin-update-pulse 2s ease-out infinite;
+}
+@keyframes plugin-update-pulse {
+    0%   { box-shadow: 0 0 0 0 rgba(59, 130, 246, 0.55); }
+    70%  { box-shadow: 0 0 0 6px rgba(59, 130, 246, 0); }
+    100% { box-shadow: 0 0 0 0 rgba(59, 130, 246, 0); }
+}
+@media (prefers-reduced-motion: reduce) {
+    .plugin-update-available { animation: none; }
+}
+
 /* Under-voltage / throttling warning banner */
 .power-warning-banner {
     background-color: #fef2f2;
@@ -1220,3 +1371,44 @@ button.bg-white {
 [data-theme="dark"] .power-warning-banner-dismiss {
     color: #fca5a5;
 }
+
+/* ===== Floating live preview (all tabs except Overview) ===== */
+.floating-preview {
+    position: fixed;
+    right: 1rem;
+    bottom: 1rem;
+    z-index: 70;
+    background-color: #111827;
+    border: 1px solid #374151;
+    border-radius: 0.5rem;
+    box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);
+    overflow: hidden;
+    /* Desktop: draggable resize handle (bottom-left visually, since the
+       panel is anchored to the right). Touch devices use the size button. */
+    resize: both;
+    min-width: 160px;
+    max-width: 90vw;
+}
+.floating-preview img {
+    background-color: #000;
+}
+.floating-preview-toggle {
+    position: fixed;
+    right: 1rem;
+    bottom: 1rem;
+    z-index: 70;
+    width: 44px;
+    height: 44px;
+    border-radius: 9999px;
+    background-color: var(--color-primary);
+    color: #ffffff;
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.35);
+    align-items: center;
+    justify-content: center;
+}
+@media (max-width: 640px) {
+    /* Whatever size is chosen, never wider than the phone viewport */
+    .floating-preview {
+        max-width: calc(100vw - 2rem);
+    }
+}

web_interface/static/v3/app.js

@@ -1,4 +1,4 @@
-/* global showNotification, updateSystemStats, updateDisplayPreview, htmx */
+/* global showNotification, updateSystemStats, updateDisplayPreview, htmx, debugLog */
 // LED Matrix v3 JavaScript
 // Additional helpers for HTMX and Alpine.js integration
 
@@ -12,8 +12,8 @@ window.showNotification = function(message, type = 'info') {
         });
         document.dispatchEvent(event);
     } else {
-        // Fallback notification
-        console.log(`${type}: ${message}`);
+        // Fallback notification — user-facing last resort, so never gated
+        console.info(`${type}: ${message}`);
     }
 };
 
@@ -49,6 +49,111 @@ document.body.addEventListener('htmx:afterRequest', function(event) {
             // Not JSON, ignore
         }
     }
+
+    // Main-config saves (display hardware, rotation/durations, general) only
+    // take effect after a display-service restart — surface the reminder
+    // banner. Plugin config saves apply live and are deliberately excluded.
+    try {
+        const cfg = event.detail.requestConfig;
+        if (cfg && cfg.verb === 'post' &&
+            (cfg.path || '').includes('/api/v3/config/main') &&
+            response && response.status >= 200 && response.status < 300) {
+            window.showRestartPending();
+        }
+    } catch { /* banner is best-effort */ }
+});
+
+// ===== Unsaved-changes guard =====
+// Plugin config panels are Alpine x-if templates: navigating away DESTROYS
+// the panel and revisiting re-fetches it, silently discarding any edits.
+// (System tabs use x-show + data-loaded and persist, so they're exempt.)
+// Track dirty forms and confirm before a lossy navigation.
+(function() {
+    function markDirty(e) {
+        const form = e.target && e.target.closest ? e.target.closest('form') : null;
+        if (form) form.setAttribute('data-dirty', '');
+    }
+    document.body.addEventListener('input', markDirty);
+    document.body.addEventListener('change', markDirty);
+
+    // A successful submit makes the form clean again
+    document.body.addEventListener('htmx:afterRequest', function(event) {
+        const xhr = event.detail.xhr;
+        const form = event.detail.elt && event.detail.elt.closest ? event.detail.elt.closest('form') : null;
+        if (form && xhr && xhr.status >= 200 && xhr.status < 300) {
+            form.removeAttribute('data-dirty');
+        }
+    });
+
+    // Capture phase so this runs before Alpine's bubbling @click switches tabs
+    document.addEventListener('click', function(e) {
+        const tabBtn = e.target && e.target.closest ? e.target.closest('.nav-tab') : null;
+        if (!tabBtn) return;
+        const lossy = Array.prototype.filter.call(
+            document.querySelectorAll('.plugin-config-tab form[data-dirty]'),
+            function(f) { return f.offsetParent !== null; }
+        );
+        if (lossy.length === 0) return;
+        if (!window.confirm('You have unsaved plugin settings — leaving this page will discard them. Leave anyway?')) {
+            e.stopPropagation();
+            e.preventDefault();
+        }
+    }, true);
+
+    // Full page unload loses every panel's edits
+    window.addEventListener('beforeunload', function(e) {
+        const dirty = Array.prototype.some.call(
+            document.querySelectorAll('form[data-dirty]'),
+            function(f) { return f.offsetParent !== null; }
+        );
+        if (dirty) {
+            e.preventDefault();
+            e.returnValue = '';
+        }
+    });
+})();
+
+// ===== Restart-pending banner =====
+// Shown after restart-requiring saves; persists across tab switches (and
+// reloads, via sessionStorage) until the display restarts or it's dismissed.
+window.showRestartPending = function() {
+    try { sessionStorage.setItem('ledmatrix-restart-pending', '1'); } catch { /* private browsing */ }
+    const banner = document.getElementById('restart-pending-banner');
+    if (banner) banner.style.display = 'block';
+};
+
+window.dismissRestartPending = function() {
+    try { sessionStorage.removeItem('ledmatrix-restart-pending'); } catch { /* no-op */ }
+    const banner = document.getElementById('restart-pending-banner');
+    if (banner) banner.style.display = 'none';
+};
+
+window.restartPendingNow = function() {
+    const btn = document.getElementById('restart-pending-btn');
+    if (btn) btn.disabled = true;
+    fetch('/api/v3/system/action', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ action: 'restart_display_service' })
+    })
+    .then(r => r.json())
+    .then(data => {
+        showNotification(data.message || 'Display restarting…', data.status || 'success');
+        window.dismissRestartPending();
+    })
+    .catch(err => {
+        showNotification('Error restarting display: ' + err.message, 'error');
+    })
+    .finally(() => { if (btn) btn.disabled = false; });
+};
+
+document.addEventListener('DOMContentLoaded', function() {
+    try {
+        if (sessionStorage.getItem('ledmatrix-restart-pending') === '1') {
+            const banner = document.getElementById('restart-pending-banner');
+            if (banner) banner.style.display = 'block';
+        }
+    } catch { /* no-op */ }
 });
 
 // SSE reconnection helper — closes and reopens both SSE streams,
@@ -246,13 +351,13 @@ window.performanceMonitor = {
     logMetrics: function() {
         const metrics = this.getMetrics();
         console.group('Performance Metrics');
-        console.log('DOM Content Loaded:', metrics.domContentLoaded?.toFixed(2) || 'N/A', 'ms');
-        console.log('Load Complete:', metrics.loadComplete?.toFixed(2) || 'N/A', 'ms');
-        console.log('First Paint:', metrics.firstPaint?.toFixed(2) || 'N/A', 'ms');
-        console.log('First Contentful Paint:', metrics.firstContentfulPaint?.toFixed(2) || 'N/A', 'ms');
-        console.log('Resources:', metrics.resourceCount || 0, 'files,', (metrics.totalResourceSize / 1024).toFixed(2) || '0', 'KB');
+        debugLog('DOM Content Loaded:', metrics.domContentLoaded?.toFixed(2) || 'N/A', 'ms');
+        debugLog('Load Complete:', metrics.loadComplete?.toFixed(2) || 'N/A', 'ms');
+        debugLog('First Paint:', metrics.firstPaint?.toFixed(2) || 'N/A', 'ms');
+        debugLog('First Contentful Paint:', metrics.firstContentfulPaint?.toFixed(2) || 'N/A', 'ms');
+        debugLog('Resources:', metrics.resourceCount || 0, 'files,', (metrics.totalResourceSize / 1024).toFixed(2) || '0', 'KB');
         if (Object.keys(metrics.measures || {}).length > 0) {
-            console.log('Custom Measures:', metrics.measures);
+            debugLog('Custom Measures:', metrics.measures);
         }
         console.groupEnd();
     }
@@ -273,3 +378,170 @@ document.addEventListener('DOMContentLoaded', function() {
         }, 100);
     });
 });
+
+// ===== Floating live preview =====
+// A mini preview of the display, available on every tab except Overview
+// (which has the full-size one). Open/closed state persists per browser;
+// frames arrive via the existing SSE stream (updateDisplayPreview in
+// app-shell.js feeds #floating-preview-img).
+window.toggleFloatingPreview = function(open) {
+    try { localStorage.setItem('ledmatrix-floating-preview', open ? '1' : '0'); } catch { /* no-op */ }
+    window.updateFloatingPreviewVisibility();
+};
+
+// Preset widths the size button cycles through (px). Desktop users can also
+// drag the panel's native resize handle (CSS resize: both).
+const FLOATING_PREVIEW_SIZES = [192, 256, 384, 512];
+
+window.applyFloatingPreviewSize = function() {
+    const panel = document.getElementById('floating-preview');
+    if (!panel) return;
+    let size = 256;
+    try { size = parseInt(localStorage.getItem('ledmatrix-floating-preview-size'), 10) || 256; } catch { /* no-op */ }
+    panel.style.width = size + 'px';
+    // Clear any manual drag-resize height so the image's aspect ratio rules
+    panel.style.height = '';
+};
+
+window.cycleFloatingPreviewSize = function() {
+    let size = 256;
+    try { size = parseInt(localStorage.getItem('ledmatrix-floating-preview-size'), 10) || 256; } catch { /* no-op */ }
+    const idx = FLOATING_PREVIEW_SIZES.indexOf(size);
+    const next = FLOATING_PREVIEW_SIZES[(idx + 1) % FLOATING_PREVIEW_SIZES.length];
+    try { localStorage.setItem('ledmatrix-floating-preview-size', String(next)); } catch { /* no-op */ }
+    window.applyFloatingPreviewSize();
+};
+
+window.updateFloatingPreviewVisibility = function(tab) {
+    const panel = document.getElementById('floating-preview');
+    const toggle = document.getElementById('floating-preview-toggle');
+    if (!panel || !toggle) return;
+    let active = tab;
+    if (!active) {
+        const el = document.querySelector('[x-data="app()"]') || document.querySelector('[x-data]');
+        const data = el && el._x_dataStack && el._x_dataStack[0];
+        active = data && data.activeTab;
+    }
+    const onOverview = active === 'overview';
+    let open = false;
+    try { open = localStorage.getItem('ledmatrix-floating-preview') === '1'; } catch { /* no-op */ }
+    const showPanel = !onOverview && open;
+    panel.style.display = showPanel ? 'block' : 'none';
+    toggle.style.display = (!onOverview && !open) ? 'flex' : 'none';
+    if (showPanel) {
+        window.applyFloatingPreviewSize();
+        // Show the last cached frame immediately — SSE only pushes on
+        // display changes, so a freshly opened panel would otherwise stay
+        // empty until the next change.
+        const img = document.getElementById('floating-preview-img');
+        if (img && !img.src && window._lastPreviewFrame) {
+            img.src = 'data:image/png;base64,' + window._lastPreviewFrame;
+        }
+    }
+};
+
+document.addEventListener('DOMContentLoaded', function() {
+    window.updateFloatingPreviewVisibility();
+});
+
+// Run a plugin on the real display for 60s via the existing on-demand API
+// and open the floating preview so the effect is visible while configuring.
+window.previewPluginNow = function(pluginId) {
+    fetch('/api/v3/display/on-demand/start', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ plugin_id: pluginId, duration: 60 })
+    })
+    .then(r => r.json())
+    .then(data => {
+        showNotification(data.message || ('Previewing ' + pluginId + ' for 60 seconds'),
+                         data.status || 'success');
+        if (data.status === 'success') window.toggleFloatingPreview(true);
+    })
+    .catch(err => {
+        showNotification('Preview failed: ' + err.message, 'error');
+    });
+};
+
+// ===== Nav accessibility =====
+// aria-current tracks the active tab. Buttons are matched by their Alpine
+// @click expression ("activeTab = '<tab>'"), which works for both the static
+// system tabs and the dynamically injected plugin tabs.
+window.updateNavAriaCurrent = function(tab) {
+    document.querySelectorAll('.nav-tab').forEach(function(btn) {
+        const expr = btn.getAttribute('@click') || btn.getAttribute('x-on:click') || '';
+        const isCurrent = expr.indexOf("activeTab = '" + tab + "'") !== -1;
+        if (isCurrent) {
+            btn.setAttribute('aria-current', 'page');
+        } else {
+            btn.removeAttribute('aria-current');
+        }
+    });
+};
+
+// Escape closes the mobile nav drawer and returns focus to the hamburger;
+// opening the drawer moves focus to its first tab.
+(function() {
+    function appData() {
+        const el = document.querySelector('[x-data="app()"]') || document.querySelector('[x-data]');
+        return el && el._x_dataStack && el._x_dataStack[0];
+    }
+    document.addEventListener('keydown', function(e) {
+        if (e.key !== 'Escape') return;
+        const data = appData();
+        if (data && data.mobileNavOpen) {
+            data.mobileNavOpen = false;
+            const burger = document.querySelector('[aria-controls="site-nav"]');
+            if (burger) burger.focus();
+        }
+    });
+    document.addEventListener('click', function(e) {
+        const burger = e.target && e.target.closest
+            ? e.target.closest('[aria-controls="site-nav"]') : null;
+        if (!burger) return;
+        // The click handler toggles mobileNavOpen; focus the first tab once
+        // the drawer has slid in (matches the CSS transition timing).
+        setTimeout(function() {
+            const data = appData();
+            if (data && data.mobileNavOpen) {
+                const first = document.querySelector('#site-nav .nav-tab');
+                if (first) first.focus();
+            }
+        }, 120);
+    });
+})();
+
+// ===== Mobile nav: header-widget relocation =====
+// Below the md breakpoint the settings-search box and system-stats block are
+// MOVED (same DOM nodes, listeners intact) from the header into the nav
+// drawer's #drawer-widgets slot; at md and up they move back. Single-instance
+// constraint: settings-search.js and the SSE stats updater both look these
+// elements up by id, so they must never be duplicated.
+window.placeHeaderWidgets = function() {
+    const drawer = document.getElementById('drawer-widgets');
+    const header = document.getElementById('header-widgets');
+    const search = document.getElementById('settings-search-wrap');
+    const stats = document.getElementById('system-stats');
+    if (!drawer || !header) return;
+
+    const desktop = window.matchMedia('(min-width: 768px)').matches;
+    if (desktop) {
+        // Restore original header order: search before the theme toggle,
+        // stats as the last item.
+        const themeToggle = document.getElementById('theme-toggle');
+        if (search && search.parentElement !== header) {
+            header.insertBefore(search, themeToggle || null);
+        }
+        if (stats && stats.parentElement !== header) {
+            header.appendChild(stats);
+        }
+    } else {
+        if (search && search.parentElement !== drawer) drawer.appendChild(search);
+        if (stats && stats.parentElement !== drawer) drawer.appendChild(stats);
+    }
+};
+
+document.addEventListener('DOMContentLoaded', function() {
+    window.placeHeaderWidgets();
+    window.matchMedia('(min-width: 768px)').addEventListener('change', window.placeHeaderWidgets);
+});

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

@@ -0,0 +1,356 @@
+/* global debugLog */
+// Early helpers and the app() stub (must run before Alpine init)
+// Extracted from templates/v3/base.html so browsers cache it as a static asset.
+        // Helper function to get installed plugins with fallback
+        // Must be defined before app() function that uses it
+        async function getInstalledPluginsSafe() {
+            if (window.PluginAPI && window.PluginAPI.getInstalledPlugins) {
+                try {
+                    const plugins = await window.PluginAPI.getInstalledPlugins();
+                    // Ensure plugins is always an array
+                    const pluginsArray = Array.isArray(plugins) ? plugins : [];
+                    return { status: 'success', data: { plugins: pluginsArray } };
+                } catch (error) {
+                    console.error('Error using PluginAPI.getInstalledPlugins, falling back to direct fetch:', error);
+                    // Fall through to direct fetch
+                }
+            }
+            // Fallback to direct fetch if PluginAPI not loaded
+            const response = await fetch('/api/v3/plugins/installed');
+            return await response.json();
+        }
+
+        // Global event listener for pluginsUpdated - works even if Alpine isn't ready yet
+        // This ensures tabs update when plugins_manager.js loads plugins
+        document.addEventListener('pluginsUpdated', function(event) {
+            debugLog('[GLOBAL] Received pluginsUpdated event:', event.detail?.plugins?.length || 0, 'plugins');
+            const plugins = event.detail?.plugins || [];
+            
+            // Update window.installedPlugins
+            window.installedPlugins = plugins;
+            
+            // Try to update Alpine component if it exists (only if using full implementation)
+            if (window.Alpine) {
+                const appElement = document.querySelector('[x-data="app()"]');
+                if (appElement && appElement._x_dataStack && appElement._x_dataStack[0]) {
+                    const appComponent = appElement._x_dataStack[0];
+                    appComponent.installedPlugins = plugins;
+                    // Only call updatePluginTabs if it's the full implementation (has _doUpdatePluginTabs)
+                    if (typeof appComponent.updatePluginTabs === 'function' && 
+                        appComponent.updatePluginTabs.toString().includes('_doUpdatePluginTabs')) {
+                        debugLog('[GLOBAL] Updating plugin tabs via Alpine component (full implementation)');
+                        appComponent.updatePluginTabs();
+                        return; // Full implementation handles it, don't do direct update
+                    }
+                }
+            }
+            
+            // Only do direct DOM update if full implementation isn't available yet
+            const pluginTabsRow = document.getElementById('plugin-tabs-row');
+            const pluginTabsNav = pluginTabsRow?.querySelector('nav');
+            if (pluginTabsRow && pluginTabsNav && plugins.length > 0) {
+                // Clear existing plugin tabs (except Plugin Manager)
+                const existingTabs = pluginTabsNav.querySelectorAll('.plugin-tab');
+                existingTabs.forEach(tab => { tab.remove(); });
+                
+                // Add tabs for each installed plugin
+                plugins.forEach(plugin => {
+                    const tabButton = document.createElement('button');
+                    tabButton.type = 'button';
+                    tabButton.setAttribute('data-plugin-id', plugin.id);
+                    tabButton.className = `plugin-tab nav-tab`;
+                    tabButton.onclick = function() {
+                        // Try to set activeTab via Alpine if available
+                        if (window.Alpine) {
+                            const appElement = document.querySelector('[x-data="app()"]');
+                            if (appElement && appElement._x_dataStack && appElement._x_dataStack[0]) {
+                                appElement._x_dataStack[0].activeTab = plugin.id;
+                                // Only call updatePluginTabStates if it exists
+                                if (typeof appElement._x_dataStack[0].updatePluginTabStates === 'function') {
+                                    appElement._x_dataStack[0].updatePluginTabStates();
+                                }
+                            }
+                        }
+                    };
+                    // Built with DOM APIs (no innerHTML): the icon class and
+                    // name come from plugin manifests, which are only
+                    // semi-trusted input.
+                    const tabIcon = document.createElement('i');
+                    tabIcon.className = plugin.icon || 'fas fa-puzzle-piece';
+                    tabButton.textContent = '';
+                    tabButton.appendChild(tabIcon);
+                    tabButton.appendChild(document.createTextNode(plugin.name || plugin.id));
+                    pluginTabsNav.appendChild(tabButton);
+                });
+                debugLog('[GLOBAL] Updated plugin tabs directly:', plugins.length, 'tabs added');
+            }
+        });
+
+        // Guard flag to prevent duplicate stub-to-full enhancement
+        window._appEnhanced = false;
+
+        // Define app() function early so Alpine can find it when it initializes
+        // This is a complete implementation that will work immediately
+        (function() {
+            const isAPMode = window.location.hostname === '192.168.4.1' || 
+                           window.location.hostname.startsWith('192.168.4.');
+            
+            // Create the app function - will be enhanced by full implementation later
+            window.app = function() {
+                return {
+                    activeTab: isAPMode ? 'wifi' : 'overview',
+                    mobileNavOpen: false,
+                    installedPlugins: [],
+                    
+                    init() {
+                        // Try to enhance immediately with full implementation
+                        const tryEnhance = () => {
+                            if (window._appEnhanced) return true;
+                            if (typeof window.app === 'function') {
+                                const fullApp = window.app();
+                                // Check if this is the full implementation (has updatePluginTabs with proper implementation)
+                                if (fullApp && typeof fullApp.updatePluginTabs === 'function' && fullApp.updatePluginTabs.toString().includes('_doUpdatePluginTabs')) {
+                                    window._appEnhanced = true;
+                                    // Preserve runtime state that should not be reset
+                                    const preservedPlugins = this.installedPlugins;
+                                    const preservedTab = this.activeTab;
+                                    const defaultTab = isAPMode ? 'wifi' : 'overview';
+                                    const wasInitialized = this._initialized;
+                                    Object.assign(this, fullApp);
+                                    // Restore runtime state if non-default
+                                    if (preservedPlugins && preservedPlugins.length > 0) {
+                                        this.installedPlugins = preservedPlugins;
+                                    }
+                                    if (preservedTab && preservedTab !== defaultTab) {
+                                        this.activeTab = preservedTab;
+                                    }
+                                    if (wasInitialized) {
+                                        this._initialized = wasInitialized;
+                                    }
+                                    // Only call init if not already initialized
+                                    if (typeof this.init === 'function' && !this._initialized) {
+                                        this.init();
+                                    }
+                                    return true;
+                                }
+                            }
+                            return false;
+                        };
+                        
+                        // Set up event listener for pluginsUpdated in stub (only if not already enhanced)
+                        // The full implementation will have its own listener, so we only need this for the stub
+                        if (!this._pluginsUpdatedListenerSet) {
+                            const handlePluginsUpdated = (event) => {
+                                debugLog('[STUB] Received pluginsUpdated event:', event.detail?.plugins?.length || 0, 'plugins');
+                                const plugins = event.detail?.plugins || [];
+                                // Only update if we're still in stub mode (not enhanced yet)
+                                if (typeof this.updatePluginTabs === 'function' && !this.updatePluginTabs.toString().includes('_doUpdatePluginTabs')) {
+                                    this.installedPlugins = plugins;
+                                    if (this.$nextTick && typeof this.$nextTick === 'function') {
+                                        this.$nextTick(() => {
+                                            this.updatePluginTabs();
+                                        });
+                                    } else {
+                                        setTimeout(() => {
+                                            this.updatePluginTabs();
+                                        }, 100);
+                                    }
+                                }
+                            };
+                            document.addEventListener('pluginsUpdated', handlePluginsUpdated);
+                            this._pluginsUpdatedListenerSet = true;
+                            debugLog('[STUB] init: Set up pluginsUpdated event listener');
+                        }
+                        
+                        // Try immediately - if full implementation is already loaded, use it right away
+                        if (!tryEnhance()) {
+                            // Full implementation not ready yet, load plugins directly while waiting
+                            this.loadInstalledPluginsDirectly();
+                            // Try again very soon to enhance with full implementation
+                            setTimeout(tryEnhance, 10);
+                            
+                            // Also set up a periodic check to update tabs if plugins get loaded by plugins_manager.js
+                            let retryCount = 0;
+                            const maxRetries = 20; // Check for 2 seconds (20 * 100ms)
+                            const checkAndUpdateTabs = () => {
+                                if (retryCount >= maxRetries) {
+                                    // Fallback: if plugins_manager.js hasn't loaded after 2 seconds, fetch directly
+                                    if (!window.installedPlugins || window.installedPlugins.length === 0) {
+                                        debugLog('[STUB] checkAndUpdateTabs: Fallback - fetching plugins directly after timeout');
+                                        this.loadInstalledPluginsDirectly();
+                                    }
+                                    return;
+                                }
+                                
+                                // Check if plugins are available (either from window or component)
+                                const plugins = window.installedPlugins || this.installedPlugins || [];
+                                if (plugins.length > 0) {
+                                    debugLog('[STUB] checkAndUpdateTabs: Found', plugins.length, 'plugins, updating tabs');
+                                    this.installedPlugins = plugins;
+                                    if (typeof this.updatePluginTabs === 'function') {
+                                        this.updatePluginTabs();
+                                    }
+                                } else {
+                                    retryCount++;
+                                    setTimeout(checkAndUpdateTabs, 100);
+                                }
+                            };
+                            // Start checking after a short delay
+                            setTimeout(checkAndUpdateTabs, 200);
+                        } else {
+                            // Full implementation loaded, but still set up fallback timer
+                            setTimeout(() => {
+                                if (!window.installedPlugins || window.installedPlugins.length === 0) {
+                                    debugLog('[STUB] init: Fallback timer - fetching plugins directly');
+                                    this.loadInstalledPluginsDirectly();
+                                }
+                            }, 2000);
+                        }
+                    },
+                    
+                    // Direct plugin loading for stub (before full implementation loads)
+                    async loadInstalledPluginsDirectly() {
+                        try {
+                            debugLog('[STUB] loadInstalledPluginsDirectly: Starting...');
+                            // Ensure DOM is ready
+                            const ensureDOMReady = () => {
+                                return new Promise((resolve) => {
+                                    if (document.readyState === 'complete' || document.readyState === 'interactive') {
+                                        // Use requestAnimationFrame to ensure DOM is painted
+                                        requestAnimationFrame(() => {
+                                            setTimeout(resolve, 50); // Small delay to ensure rendering
+                                        });
+                                    } else {
+                                        document.addEventListener('DOMContentLoaded', () => {
+                                            requestAnimationFrame(() => {
+                                                setTimeout(resolve, 50);
+                                            });
+                                        });
+                                    }
+                                });
+                            };
+                            
+                            await ensureDOMReady();
+                            
+                            const data = await getInstalledPluginsSafe();
+                            if (data.status === 'success') {
+                                const plugins = data.data.plugins || [];
+                                debugLog('[STUB] loadInstalledPluginsDirectly: Loaded', plugins.length, 'plugins');
+                                
+                                // Update both component and window
+                                this.installedPlugins = plugins;
+                                window.installedPlugins = plugins;
+                                
+                                // Dispatch event so global listener can update tabs
+                                document.dispatchEvent(new CustomEvent('pluginsUpdated', {
+                                    detail: { plugins: plugins }
+                                }));
+                                debugLog('[STUB] loadInstalledPluginsDirectly: Dispatched pluginsUpdated event');
+                                
+                                // Update tabs if we have the method - use $nextTick if available
+                                if (typeof this.updatePluginTabs === 'function') {
+                                    if (this.$nextTick && typeof this.$nextTick === 'function') {
+                                        this.$nextTick(() => {
+                                            this.updatePluginTabs();
+                                        });
+                                    } else {
+                                        // Fallback: wait a bit for DOM
+                                        setTimeout(() => {
+                                            this.updatePluginTabs();
+                                        }, 100);
+                                    }
+                                }
+                            } else {
+                                console.warn('[STUB] loadInstalledPluginsDirectly: Failed to load plugins:', data.message);
+                            }
+                        } catch (error) {
+                            console.error('[STUB] loadInstalledPluginsDirectly: Error loading plugins:', error);
+                        }
+                    },
+                    
+                    // Stub methods that will be replaced by full implementation
+                    loadTabContent: function(tab) {},
+                    loadInstalledPlugins: async function() {
+                        // Try to use global function if available, otherwise use direct loading
+                        if (typeof window.loadInstalledPlugins === 'function') {
+                            await window.loadInstalledPlugins();
+                            // Update tabs after loading (window.installedPlugins should be set by the global function)
+                            if (window.installedPlugins && Array.isArray(window.installedPlugins)) {
+                                this.installedPlugins = window.installedPlugins;
+                                this.updatePluginTabs();
+                            }
+                        } else if (typeof window.pluginManager?.loadInstalledPlugins === 'function') {
+                            await window.pluginManager.loadInstalledPlugins();
+                            // Update tabs after loading
+                            if (window.installedPlugins && Array.isArray(window.installedPlugins)) {
+                                this.installedPlugins = window.installedPlugins;
+                                this.updatePluginTabs();
+                            }
+                        } else {
+                            // Fallback to direct loading (which already calls updatePluginTabs)
+                            await this.loadInstalledPluginsDirectly();
+                        }
+                    },
+                    updatePluginTabs: function() {
+                        // Basic implementation for stub - will be replaced by full implementation
+                        // Debounce to prevent multiple rapid calls
+                        if (this._updatePluginTabsTimeout) {
+                            clearTimeout(this._updatePluginTabsTimeout);
+                        }
+                        
+                        this._updatePluginTabsTimeout = setTimeout(() => {
+                            debugLog('[STUB] updatePluginTabs: Executing with', this.installedPlugins?.length || 0, 'plugins');
+                            const pluginTabsRow = document.getElementById('plugin-tabs-row');
+                            const pluginTabsNav = pluginTabsRow?.querySelector('nav');
+                            if (!pluginTabsRow || !pluginTabsNav) {
+                                console.warn('[STUB] updatePluginTabs: Plugin tabs container not found');
+                                return;
+                            }
+                            if (!this.installedPlugins || this.installedPlugins.length === 0) {
+                                debugLog('[STUB] updatePluginTabs: No plugins to display');
+                                return;
+                            }
+                            
+                            // Check if tabs are already correct by comparing plugin IDs
+                            const existingTabs = pluginTabsNav.querySelectorAll('.plugin-tab');
+                            const existingIds = Array.from(existingTabs).map(tab => tab.getAttribute('data-plugin-id')).sort().join(',');
+                            const currentIds = this.installedPlugins.map(p => p.id).sort().join(',');
+                            
+                            if (existingIds === currentIds && existingTabs.length === this.installedPlugins.length) {
+                                debugLog('[STUB] updatePluginTabs: Tabs already match, skipping update');
+                                return;
+                            }
+                            
+                            // Clear existing plugin tabs (except Plugin Manager)
+                            existingTabs.forEach(tab => { tab.remove(); });
+                            debugLog('[STUB] updatePluginTabs: Cleared', existingTabs.length, 'existing tabs');
+                            
+                            // Add tabs for each installed plugin
+                            this.installedPlugins.forEach(plugin => {
+                                const tabButton = document.createElement('button');
+                                tabButton.type = 'button';
+                                tabButton.setAttribute('data-plugin-id', plugin.id);
+                                tabButton.className = `plugin-tab nav-tab ${this.activeTab === plugin.id ? 'nav-tab-active' : ''}`;
+                                tabButton.onclick = () => {
+                                    this.activeTab = plugin.id;
+                                    if (typeof this.updatePluginTabStates === 'function') {
+                                        this.updatePluginTabStates();
+                                    }
+                                };
+                                // DOM APIs instead of innerHTML: manifest
+                                // icon/name are semi-trusted input.
+                                const tabIcon = document.createElement('i');
+                                tabIcon.className = plugin.icon || 'fas fa-puzzle-piece';
+                                tabButton.textContent = '';
+                                tabButton.appendChild(tabIcon);
+                                tabButton.appendChild(document.createTextNode(plugin.name || plugin.id));
+                                pluginTabsNav.appendChild(tabButton);
+                            });
+                            debugLog('[STUB] updatePluginTabs: Added', this.installedPlugins.length, 'plugin tabs');
+                        }, 100);
+                    },
+                    showNotification: function(message, type) {},
+                    escapeHtml: function(text) { return String(text || '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;'); }
+                };
+            };
+        })();

web_interface/static/v3/js/htmx-config.js

@@ -0,0 +1,256 @@
+/* global debugLog */
+// HTMX swap/script-execution configuration and section toggle helpers
+// Extracted from templates/v3/base.html so browsers cache it as a static asset.
+        // Configure HTMX to evaluate scripts in swapped content and fix insertBefore errors
+        (function() {
+            function setupScriptExecution() {
+                if (document.body) {
+                    // Fix HTMX insertBefore errors by validating targets before swap
+                    document.body.addEventListener('htmx:beforeSwap', function(event) {
+                        try {
+                            const target = event.detail.target;
+                            if (!target) {
+                                console.warn('[HTMX] Target is null, skipping swap');
+                                event.detail.shouldSwap = false;
+                                return false;
+                            }
+                            
+                            // Check if target is a valid DOM element
+                            if (!(target instanceof Element)) {
+                                console.warn('[HTMX] Target is not a valid Element, skipping swap');
+                                event.detail.shouldSwap = false;
+                                return false;
+                            }
+                            
+                            // Check if target has a parent node (required for insertBefore)
+                            if (!target.parentNode) {
+                                console.warn('[HTMX] Target has no parent node, skipping swap');
+                                event.detail.shouldSwap = false;
+                                return false;
+                            }
+                            
+                            // Ensure target is in the DOM
+                            if (!document.body.contains(target) && !document.head.contains(target)) {
+                                console.warn('[HTMX] Target is not in DOM, skipping swap');
+                                event.detail.shouldSwap = false;
+                                return false;
+                            }
+                            
+                            // Additional check: ensure parent is also in DOM
+                            if (target.parentNode && !document.body.contains(target.parentNode) && !document.head.contains(target.parentNode)) {
+                                console.warn('[HTMX] Target parent is not in DOM, skipping swap');
+                                event.detail.shouldSwap = false;
+                                return false;
+                            }
+                            
+                            // All checks passed, allow swap
+                            return true;
+                        } catch (e) {
+                            // If validation fails, cancel swap
+                            console.warn('[HTMX] Error validating target:', e);
+                            event.detail.shouldSwap = false;
+                            return false;
+                        }
+                    });
+                    
+                    // Suppress HTMX insertBefore errors and other noisy errors - they're harmless but noisy
+                    const originalError = console.error;
+                    const originalWarn = console.warn;
+                    
+                    console.error = function(...args) {
+                        const errorStr = args.join(' ');
+                        const errorStack = args.find(arg => arg && typeof arg === 'string' && arg.includes('htmx')) || '';
+                        
+                        // Suppress HTMX insertBefore errors (comprehensive check)
+                        // These occur when HTMX tries to swap content but the target element is null
+                        // Usually happens due to timing/race conditions and is harmless
+                        if (errorStr.includes("insertBefore") || 
+                            errorStr.includes("Cannot read properties of null") ||
+                            errorStr.includes("reading 'insertBefore'")) {
+                            // Check if it's from HTMX by looking at stack trace or error string
+                            // Also check the call stack if available
+                            const isHtmxError = errorStr.includes('htmx') ||
+                                               errorStack.includes('htmx') ||
+                                               args.some(arg => {
+                                                   if (typeof arg === 'string') {
+                                                       return arg.includes('htmx');
+                                                   }
+                                                   // Check error objects for stack traces
+                                                   if (arg && typeof arg === 'object' && arg.stack) {
+                                                       return arg.stack.includes('htmx');
+                                                   }
+                                                   return false;
+                                               });
+                            
+                            if (isHtmxError) {
+                                return; // Suppress - this is a harmless HTMX timing/race condition issue
+                            }
+                        }
+                        
+                        // Suppress script execution errors from malformed HTML
+                        if (errorStr.includes("Failed to execute 'appendChild' on 'Node'") ||
+                            errorStr.includes("Failed to execute 'insertBefore' on 'Node'")) {
+                            if (errorStr.includes('Unexpected token')) {
+                                return; // Suppress malformed HTML errors
+                            }
+                        }
+                        originalError.apply(console, args);
+                    };
+                    
+                    console.warn = function(...args) {
+                        const warnStr = args.join(' ');
+                        // Suppress Permissions-Policy warnings (harmless browser warnings)
+                        if (warnStr.includes('Permissions-Policy header') ||
+                            warnStr.includes('Unrecognized feature') ||
+                            warnStr.includes('Origin trial controlled feature') ||
+                            warnStr.includes('browsing-topics') ||
+                            warnStr.includes('run-ad-auction') ||
+                            warnStr.includes('join-ad-interest-group') ||
+                            warnStr.includes('private-state-token') ||
+                            warnStr.includes('private-aggregation') ||
+                            warnStr.includes('attribution-reporting')) {
+                            return; // Suppress - these are harmless browser feature warnings
+                        }
+                        originalWarn.apply(console, args);
+                    };
+                    
+                    // Handle HTMX errors gracefully with detailed logging
+                    document.body.addEventListener('htmx:responseError', function(event) {
+                        const detail = event.detail;
+                        const xhr = detail.xhr;
+                        const target = detail.target;
+                        
+                        // Enhanced error logging
+                        console.error('HTMX response error:', {
+                            status: xhr?.status,
+                            statusText: xhr?.statusText,
+                            url: xhr?.responseURL,
+                            target: target?.id || target?.tagName,
+                            responseText: xhr?.responseText
+                        });
+                        
+                        // For form submissions, log field names only — values
+                        // may contain API keys, passwords, or other secrets
+                        // that must never reach the console.
+                        if (target && target.tagName === 'FORM') {
+                            const formData = new FormData(target);
+                            const fieldNames = [];
+                            for (const [key] of formData.entries()) {
+                                fieldNames.push(key);
+                            }
+                            console.error('Form fields (values redacted):', fieldNames);
+                            
+                            // Try to parse error response for validation details
+                            if (xhr?.responseText) {
+                                try {
+                                    const errorData = JSON.parse(xhr.responseText);
+                                    console.error('Error details:', {
+                                        message: errorData.message,
+                                        details: errorData.details,
+                                        validation_errors: errorData.validation_errors,
+                                        context: errorData.context
+                                    });
+                                } catch {
+                                    console.error('Error response (non-JSON):', xhr.responseText.substring(0, 500));
+                                }
+                            }
+                        }
+                    });
+                    
+                    document.body.addEventListener('htmx:swapError', function(event) {
+                        // Log but don't break the app
+                        console.warn('HTMX swap error:', event.detail);
+                    });
+
+                    // Execute <script> tags in swapped content ourselves, on
+                    // htmx:afterSwap (synchronous, right after the swap) rather
+                    // than relying on htmx's own script handling, which runs
+                    // during its later "settle" phase (~20ms after swap, per
+                    // htmx's defaultSettleDelay). Alpine's MutationObserver
+                    // processes newly-inserted x-data elements synchronously
+                    // as soon as the swap lands, which is BEFORE htmx's settle
+                    // phase - so any partial whose x-data component function
+                    // (e.g. wifiSetup()) is defined by an inline <script> in
+                    // that same partial would have that script still un-run
+                    // when Alpine evaluates x-data, permanently failing with
+                    // "wifiSetup is not defined" (Alpine does not retry).
+                    // Disable htmx's own native script re-execution so the
+                    // same script doesn't also run a second time via settle.
+                    if (typeof htmx !== 'undefined' && htmx.config) {
+                        htmx.config.allowScriptTags = false;
+                    }
+                    document.body.addEventListener('htmx:afterSwap', function(event) {
+                        const target = event.detail && event.detail.target;
+                        if (!target || !(target instanceof Element)) return;
+                        target.querySelectorAll('script').forEach(function(oldScript) {
+                            const newScript = document.createElement('script');
+                            for (const attr of oldScript.attributes) {
+                                newScript.setAttribute(attr.name, attr.value);
+                            }
+                            newScript.textContent = oldScript.textContent;
+                            oldScript.replaceWith(newScript);
+                        });
+                    });
+
+                    // Mark tab containers as loaded once their content settles, so switching
+                    // away and back doesn't re-fetch. Scoped to the "loadtab" trigger (tab
+                    // containers only) so modals and plugin config panels can still reload.
+                    document.body.addEventListener('htmx:afterSettle', function(event) {
+                        if (event.detail && event.detail.target) {
+                            const target = event.detail.target;
+                            const trigger = target.getAttribute('hx-trigger') || '';
+                            if (trigger.includes('loadtab')) {
+                                target.setAttribute('data-loaded', 'true');
+                            }
+                        }
+                    });
+                } else {
+                    if (document.readyState === 'loading') {
+                        document.addEventListener('DOMContentLoaded', setupScriptExecution);
+                    } else {
+                        setTimeout(setupScriptExecution, 100);
+                    }
+                }
+            }
+            setupScriptExecution();
+            
+            // Section toggle function - define early so it's available for HTMX-loaded content
+            window.toggleSection = function(sectionId) {
+                const section = document.getElementById(sectionId);
+                const icon = document.getElementById(sectionId + '-icon');
+                if (!section) {
+                    console.warn('toggleSection: Could not find section for', sectionId);
+                    return;
+                }
+                if (!icon) {
+                    console.warn('toggleSection: Could not find icon for', sectionId);
+                    return;
+                }
+                
+                // Check if currently hidden by checking both class and computed display
+                const hasHiddenClass = section.classList.contains('hidden');
+                const computedDisplay = window.getComputedStyle(section).display;
+                const isHidden = hasHiddenClass || computedDisplay === 'none';
+                
+                if (isHidden) {
+                    // Show the section - remove hidden class and explicitly set display to block
+                    section.classList.remove('hidden');
+                    section.style.display = 'block';
+                    icon.classList.remove('fa-chevron-right');
+                    icon.classList.add('fa-chevron-down');
+                } else {
+                    // Hide the section - add hidden class and set display to none
+                    section.classList.add('hidden');
+                    section.style.display = 'none';
+                    icon.classList.remove('fa-chevron-down');
+                    icon.classList.add('fa-chevron-right');
+                }
+
+                // Keep assistive tech in sync: any toggle button that declares
+                // aria-controls for this section mirrors the expanded state.
+                const controlBtn = document.querySelector(`[aria-controls="${sectionId}"]`);
+                if (controlBtn) {
+                    controlBtn.setAttribute('aria-expanded', String(isHidden));
+                }
+            };
+        })();

web_interface/static/v3/js/settings-search.js

@@ -173,7 +173,14 @@
 
     function setActiveTab(tab) {
         var data = getAppData();
-        if (data) { data.activeTab = tab; return true; }
+        if (data) {
+            data.activeTab = tab;
+            // Navigating from a search result should also dismiss the mobile
+            // nav drawer (harmless no-op on desktop, where the drawer CSS
+            // doesn't apply).
+            if ('mobileNavOpen' in data) data.mobileNavOpen = false;
+            return true;
+        }
         return false;
     }
 

web_interface/static/v3/js/widgets/custom-feeds.js

@@ -209,6 +209,7 @@
                 const removeButton = document.createElement('button');
                 removeButton.type = 'button';
                 removeButton.className = 'text-red-600 hover:text-red-800 px-2 py-1';
+                removeButton.setAttribute('aria-label', 'Remove feed');
                 removeButton.addEventListener('click', function() {
                     window.removeCustomFeedRow(this);
                 });
@@ -333,6 +334,7 @@
         const removeButton = document.createElement('button');
         removeButton.type = 'button';
         removeButton.className = 'text-red-600 hover:text-red-800 px-2 py-1';
+        removeButton.setAttribute('aria-label', 'Remove feed');
         removeButton.addEventListener('click', function() {
             window.removeCustomFeedRow(this);
         });
@@ -404,9 +406,18 @@
         if (!file) return;
         
         const formData = new FormData();
-        formData.append('file', file);
+        // Backend contract (see api_v3.upload_plugin_asset): the request
+        // field must be named "files" (it does request.files.getlist('files')
+        // and 400s with "No files provided" otherwise), and the response
+        // carries the result in a top-level "uploaded_files" key, not nested
+        // under "data". file-upload-single.js's working upload flow uses this
+        // same contract.
+        // Backend contract (api_v3.upload_plugin_asset): field must be named
+        // "files" (request.files.getlist('files')), and the response carries
+        // results in a top-level "uploaded_files" key, not nested under "data".
+        formData.append('files', file);
         formData.append('plugin_id', pluginId);
-        
+
         fetch('/api/v3/plugins/assets/upload', {
             method: 'POST',
             body: formData
@@ -421,8 +432,8 @@
             return response.json();
         })
         .then(data => {
-            if (data.status === 'success' && data.data && data.data.files && data.data.files.length > 0) {
-                const uploadedFile = data.data.files[0];
+            if (data.status === 'success' && data.uploaded_files && data.uploaded_files.length > 0) {
+                const uploadedFile = data.uploaded_files[0];
                 const row = document.querySelector(`#${fieldId}_tbody tr[data-index="${index}"]`);
                 if (row) {
                     const logoCell = row.querySelector('td:nth-child(3)');
@@ -495,8 +506,6 @@
                     // Append container to logoCell
                     logoCell.appendChild(container);
                 }
-                // Allow re-uploading the same file
-                event.target.value = '';
             } else {
                 const notifyFn = window.showNotification || alert;
                 notifyFn('Upload failed: ' + (data.message || 'Unknown error'), 'error');
@@ -506,6 +515,12 @@
             console.error('Upload error:', error);
             const notifyFn = window.showNotification || alert;
             notifyFn('Upload failed: ' + error.message, 'error');
+        })
+        .finally(() => {
+            // Reset regardless of outcome, so the same file can be re-selected
+            // to retry after a failure (browsers won't fire "change" again
+            // for an input that still holds that exact file).
+            event.target.value = '';
         });
     };
 

web_interface/static/v3/js/widgets/notification.js

@@ -58,6 +58,10 @@
 
     // Track active notifications
     let activeNotifications = [];
+    // onAction callbacks for notifications with an inline action button,
+    // keyed by notification id (cleaned up on dismiss). A Map rather than a
+    // plain object so ids can never collide with prototype properties.
+    const actionCallbacks = new Map();
     let notificationCounter = 0;
 
     /**
@@ -113,6 +117,7 @@
 
         // Remove from tracking array
         activeNotifications = activeNotifications.filter(id => id !== notificationId);
+        actionCallbacks.delete(notificationId);
     }
 
     /**
@@ -158,6 +163,20 @@
 
         html += `<span class="flex-1 text-sm">${escapeHtml(message)}</span>`;
 
+        // Optional inline action button (e.g. "Restart Now" on a restart nudge).
+        // The callback is stored by id and invoked via triggerAction, which
+        // also dismisses the notification.
+        if (options.actionLabel && typeof options.onAction === 'function') {
+            actionCallbacks.set(notificationId, options.onAction);
+            html += `
+                <button type="button"
+                        onclick="window.LEDMatrixWidgets.get('notification').triggerAction('${notificationId}')"
+                        class="flex-shrink-0 ml-2 px-3 py-1 text-xs font-semibold rounded-md bg-white bg-opacity-20 hover:bg-opacity-30 transition-colors duration-150">
+                    ${escapeHtml(options.actionLabel)}
+                </button>
+            `;
+        }
+
         if (dismissible) {
             html += `
                 <button type="button"
@@ -227,6 +246,17 @@
             removeNotification(notificationId);
         },
 
+        /**
+         * Invoke a notification's onAction callback (see options.actionLabel /
+         * options.onAction on show) and dismiss it.
+         * @param {string} notificationId - Notification ID whose action to run
+         */
+        triggerAction: function(notificationId) {
+            const cb = actionCallbacks.get(notificationId);
+            removeNotification(notificationId);
+            if (typeof cb === 'function') cb();
+        },
+
         /**
          * Clear all notifications
          */
@@ -262,9 +292,11 @@
         }
     });
 
-    // Global shorthand function (backwards compatible with existing code)
+    // Global shorthand function (backwards compatible with existing code).
+    // Accepts either the legacy type string or a full options object
+    // ({ type, duration, actionLabel, onAction, ... }).
     window.showNotification = function(message, type = 'info') {
-        return showNotification(message, { type: type });
+        return showNotification(message, typeof type === 'string' ? { type: type } : (type || {}));
     };
 
     // Initialize container on load

web_interface/static/v3/js/widgets/plugin-order-list.js

@@ -0,0 +1,225 @@
+/**
+ * Plugin Order List — shared drag-and-drop reorder list of enabled plugins.
+ *
+ * Factored out of the Vegas Scroll section of display.html so both Vegas mode
+ * and the primary rotation (Durations tab) use one implementation. Renders
+ * one draggable row per enabled plugin into a container and keeps a hidden
+ * input's value in sync as a JSON array of plugin ids in display order.
+ *
+ * Usage:
+ *   PluginOrderList.init({
+ *       containerId: 'vegas_plugin_order',        // rows render here
+ *       orderInputId: 'vegas_plugin_order_value', // hidden input, JSON array of ids
+ *       excludedInputId: 'vegas_excluded_plugins_value', // optional: adds an
+ *           // include-checkbox per row; unchecked ids collect here (JSON array)
+ *       showVegasModeBadge: true                  // optional: Scroll/Fixed/Static badge
+ *   });
+ *
+ * The container re-renders from /api/v3/plugins/installed each init; the
+ * hidden input(s) must already hold the saved order/exclusions (JSON).
+ */
+(function() {
+    'use strict';
+
+    const MODE_LABELS = new Map([
+        ['scroll', { label: 'Scroll', icon: 'fa-scroll', color: 'text-blue-600' }],
+        ['fixed',  { label: 'Fixed',  icon: 'fa-square', color: 'text-green-600' }],
+        ['static', { label: 'Static', icon: 'fa-pause',  color: 'text-orange-600' }]
+    ]);
+
+    function init(options) {
+        const container = document.getElementById(options.containerId);
+        const orderInput = document.getElementById(options.orderInputId);
+        const excludedInput = options.excludedInputId ? document.getElementById(options.excludedInputId) : null;
+        if (!container || !orderInput) return;
+
+        function syncInputs() {
+            const order = [];
+            const excluded = [];
+            container.querySelectorAll('.plugin-order-item').forEach(item => {
+                const pluginId = item.dataset.pluginId;
+                order.push(pluginId);
+                const checkbox = item.querySelector('.plugin-order-include');
+                if (checkbox && !checkbox.checked) excluded.push(pluginId);
+            });
+            orderInput.value = JSON.stringify(order);
+            if (excludedInput) excludedInput.value = JSON.stringify(excluded);
+        }
+
+        function setupDragAndDrop() {
+            let draggedItem = null;
+            container.querySelectorAll('.plugin-order-item').forEach(item => {
+                item.addEventListener('dragstart', function(e) {
+                    draggedItem = this;
+                    this.style.opacity = '0.5';
+                    e.dataTransfer.effectAllowed = 'move';
+                });
+                item.addEventListener('dragend', function() {
+                    this.style.opacity = '1';
+                    draggedItem = null;
+                    syncInputs();
+                });
+                item.addEventListener('dragover', function(e) {
+                    e.preventDefault();
+                    e.dataTransfer.dropEffect = 'move';
+                    const rect = this.getBoundingClientRect();
+                    const midY = rect.top + rect.height / 2;
+                    if (e.clientY < midY) {
+                        this.style.borderTop = '2px solid #3b82f6';
+                        this.style.borderBottom = '';
+                    } else {
+                        this.style.borderBottom = '2px solid #3b82f6';
+                        this.style.borderTop = '';
+                    }
+                });
+                item.addEventListener('dragleave', function() {
+                    this.style.borderTop = '';
+                    this.style.borderBottom = '';
+                });
+                item.addEventListener('drop', function(e) {
+                    e.preventDefault();
+                    this.style.borderTop = '';
+                    this.style.borderBottom = '';
+                    if (draggedItem && draggedItem !== this) {
+                        const rect = this.getBoundingClientRect();
+                        const midY = rect.top + rect.height / 2;
+                        if (e.clientY < midY) {
+                            container.insertBefore(draggedItem, this);
+                        } else {
+                            container.insertBefore(draggedItem, this.nextSibling);
+                        }
+                    }
+                });
+            });
+        }
+
+        fetch('/api/v3/plugins/installed')
+            .then(response => response.json())
+            .then(data => {
+                const allPlugins = (data.data && data.data.plugins) || data.plugins || [];
+                const plugins = allPlugins.filter(p => p.enabled);
+                if (plugins.length === 0) {
+                    const empty = document.createElement('p');
+                    empty.className = 'text-sm text-gray-500 italic';
+                    empty.textContent = 'No enabled plugins';
+                    container.textContent = '';
+                    container.appendChild(empty);
+                    return;
+                }
+
+                let currentOrder = [];
+                let excluded = [];
+                try {
+                    currentOrder = JSON.parse(orderInput.value || '[]');
+                    if (excludedInput) excluded = JSON.parse(excludedInput.value || '[]');
+                } catch (e) {
+                    console.error('Error parsing saved plugin order:', e);
+                }
+                // JSON.parse can succeed and still return null/objects
+                // (e.g. a saved value of "null"); normalize to arrays.
+                if (!Array.isArray(currentOrder)) currentOrder = [];
+                if (!Array.isArray(excluded)) excluded = [];
+
+                // Saved order first, then any newly enabled plugins.
+                const orderedPlugins = [];
+                currentOrder.forEach(id => {
+                    const plugin = plugins.find(p => p.id === id);
+                    if (plugin) orderedPlugins.push(plugin);
+                });
+                plugins.forEach(plugin => {
+                    if (!orderedPlugins.find(p => p.id === plugin.id)) orderedPlugins.push(plugin);
+                });
+
+                // Rows are built with DOM APIs rather than innerHTML — plugin
+                // ids/names come from installed manifests (semi-trusted).
+                container.textContent = '';
+                orderedPlugins.forEach(plugin => {
+                    const row = document.createElement('div');
+                    row.className = 'flex items-center p-2 bg-gray-50 rounded border border-gray-200 cursor-move plugin-order-item';
+                    row.dataset.pluginId = plugin.id;
+                    row.draggable = true;
+
+                    const grip = document.createElement('i');
+                    grip.className = 'fas fa-grip-vertical text-gray-400 mr-3';
+                    row.appendChild(grip);
+
+                    if (excludedInput) {
+                        const isExcluded = excluded.includes(plugin.id);
+                        const label = document.createElement('label');
+                        label.className = 'flex items-center flex-1';
+                        const checkbox = document.createElement('input');
+                        checkbox.type = 'checkbox';
+                        checkbox.className = 'plugin-order-include h-4 w-4 text-blue-600 focus:ring-blue-500 border-gray-300 rounded mr-2';
+                        checkbox.checked = !isExcluded;
+                        const name = document.createElement('span');
+                        name.className = 'text-sm font-medium text-gray-700';
+                        name.textContent = plugin.name || plugin.id;
+                        label.appendChild(checkbox);
+                        label.appendChild(name);
+                        row.appendChild(label);
+                    } else {
+                        const name = document.createElement('span');
+                        name.className = 'text-sm font-medium text-gray-700 flex-1';
+                        name.textContent = plugin.name || plugin.id;
+                        row.appendChild(name);
+                    }
+
+                    if (options.showVegasModeBadge) {
+                        const vegasMode = plugin.vegas_mode || plugin.vegas_content_type || 'fixed';
+                        const modeInfo = MODE_LABELS.get(vegasMode) || MODE_LABELS.get('fixed');
+                        const badge = document.createElement('span');
+                        badge.className = `text-xs ${modeInfo.color} ml-2`;
+                        badge.title = `Vegas display mode: ${modeInfo.label}`;
+                        const badgeIcon = document.createElement('i');
+                        badgeIcon.className = `fas ${modeInfo.icon} mr-1`;
+                        badge.appendChild(badgeIcon);
+                        badge.appendChild(document.createTextNode(modeInfo.label));
+                        row.appendChild(badge);
+                    }
+
+                    // Up/down buttons: touch- and keyboard-accessible
+                    // reordering alongside native drag-and-drop (HTML5 drag
+                    // events don't fire on most mobile browsers).
+                    const pluginLabel = plugin.name || plugin.id;
+                    [['up', 'fa-chevron-up', `Move ${pluginLabel} up`],
+                     ['down', 'fa-chevron-down', `Move ${pluginLabel} down`]].forEach(([dir, iconCls, ariaLabel]) => {
+                        const moveBtn = document.createElement('button');
+                        moveBtn.type = 'button';
+                        moveBtn.className = 'plugin-order-move text-gray-400 hover:text-gray-700 px-2 py-1';
+                        moveBtn.setAttribute('aria-label', ariaLabel);
+                        const moveIcon = document.createElement('i');
+                        moveIcon.className = `fas ${iconCls} text-xs`;
+                        moveBtn.appendChild(moveIcon);
+                        moveBtn.addEventListener('click', function() {
+                            if (dir === 'up' && row.previousElementSibling) {
+                                container.insertBefore(row, row.previousElementSibling);
+                            } else if (dir === 'down' && row.nextElementSibling) {
+                                container.insertBefore(row.nextElementSibling, row);
+                            }
+                            syncInputs();
+                            moveBtn.focus();
+                        });
+                        row.appendChild(moveBtn);
+                    });
+
+                    container.appendChild(row);
+                });
+
+                setupDragAndDrop();
+                container.querySelectorAll('.plugin-order-include').forEach(checkbox => {
+                    checkbox.addEventListener('change', syncInputs);
+                });
+                syncInputs();
+            })
+            .catch(error => {
+                console.error('Error fetching plugins:', error);
+                const err = document.createElement('p');
+                err.className = 'text-sm text-red-500';
+                err.textContent = 'Error loading plugins';
+                container.textContent = '';
+                container.appendChild(err);
+            });
+    }
+
+    window.PluginOrderList = { init: init };
+})();

web_interface/static/v3/manifest.json

@@ -0,0 +1,24 @@
+{
+    "name": "LED Matrix Control",
+    "short_name": "LEDMatrix",
+    "description": "Control panel for the LEDMatrix display",
+    "start_url": "/",
+    "scope": "/",
+    "display": "standalone",
+    "background_color": "#111827",
+    "theme_color": "#111827",
+    "icons": [
+        {
+            "src": "/static/v3/icons/icon-192.png",
+            "sizes": "192x192",
+            "type": "image/png",
+            "purpose": "any maskable"
+        },
+        {
+            "src": "/static/v3/icons/icon-512.png",
+            "sizes": "512x512",
+            "type": "image/png",
+            "purpose": "any maskable"
+        }
+    ]
+}

web_interface/static/v3/vendor/codemirror/addon/edit/closebrackets.min.js

@@ -0,0 +1 @@
+!function(e){"object"==typeof exports&&"object"==typeof module?e(require("../../lib/codemirror")):"function"==typeof define&&define.amd?define(["../../lib/codemirror"],e):e(CodeMirror)}(function(P){var t={pairs:"()[]{}''\"\"",closeBefore:")]}'\":;>",triples:"",explode:"[]{}"},S=P.Pos;function k(e,n){return"pairs"==n&&"string"==typeof e?e:("object"==typeof e&&null!=e[n]?e:t)[n]}P.defineOption("autoCloseBrackets",!1,function(e,n,t){t&&t!=P.Init&&(e.removeKeyMap(i),e.state.closeBrackets=null),n&&(r(k(n,"pairs")),e.state.closeBrackets=n,e.addKeyMap(i))});var i={Backspace:function(e){var n=y(e);if(!n||e.getOption("disableInput"))return P.Pass;for(var t=k(n,"pairs"),r=e.listSelections(),i=0;i<r.length;i++){if(!r[i].empty())return P.Pass;var a=s(e,r[i].head);if(!a||t.indexOf(a)%2!=0)return P.Pass}for(i=r.length-1;0<=i;i--){var o=r[i].head;e.replaceRange("",S(o.line,o.ch-1),S(o.line,o.ch+1),"+delete")}},Enter:function(r){var e=y(r),n=e&&k(e,"explode");if(!n||r.getOption("disableInput"))return P.Pass;for(var i=r.listSelections(),t=0;t<i.length;t++){if(!i[t].empty())return P.Pass;var a=s(r,i[t].head);if(!a||n.indexOf(a)%2!=0)return P.Pass}r.operation(function(){var e=r.lineSeparator()||"\n";r.replaceSelection(e+e,null),O(r,-1),i=r.listSelections();for(var n=0;n<i.length;n++){var t=i[n].head.line;r.indentLine(t,null,!0),r.indentLine(t+1,null,!0)}})}};function r(e){for(var n=0;n<e.length;n++){var t=e.charAt(n),r="'"+t+"'";i[r]||(i[r]=function(n){return function(e){return function(i,e){var n=y(i);if(!n||i.getOption("disableInput"))return P.Pass;var t=k(n,"pairs"),r=t.indexOf(e);if(-1==r)return P.Pass;for(var a,o=k(n,"closeBefore"),s=k(n,"triples"),l=t.charAt(r+1)==e,c=i.listSelections(),f=r%2==0,h=0;h<c.length;h++){var u,d=c[h],p=d.head,g=i.getRange(p,S(p.line,p.ch+1));if(f&&!d.empty())u="surround";else if(!l&&f||g!=e)if(l&&1<p.ch&&0<=s.indexOf(e)&&i.getRange(S(p.line,p.ch-2),p)==e+e){if(2<p.ch&&/\bstring/.test(i.getTokenTypeAt(S(p.line,p.ch-2))))return P.Pass;u="addFour"}else if(l){d=0==p.ch?" ":i.getRange(S(p.line,p.ch-1),p);if(P.isWordChar(g)||d==e||P.isWordChar(d))return P.Pass;u="both"}else{if(!f||!(0===g.length||/\s/.test(g)||-1<o.indexOf(g)))return P.Pass;u="both"}else u=l&&function(e,n){var t=e.getTokenAt(S(n.line,n.ch+1));return/\bstring/.test(t.type)&&t.start==n.ch&&(0==n.ch||!/\bstring/.test(e.getTokenTypeAt(n)))}(i,p)?"both":0<=s.indexOf(e)&&i.getRange(p,S(p.line,p.ch+3))==e+e+e?"skipThree":"skip";if(a){if(a!=u)return P.Pass}else a=u}var v=r%2?t.charAt(r-1):e,b=r%2?e:t.charAt(r+1);i.operation(function(){if("skip"==a)O(i,1);else if("skipThree"==a)O(i,3);else if("surround"==a){for(var e=i.getSelections(),n=0;n<e.length;n++)e[n]=v+e[n]+b;i.replaceSelections(e,"around");for(e=i.listSelections().slice(),n=0;n<e.length;n++)e[n]=(t=e[n],r=void 0,r=0<P.cmpPos(t.anchor,t.head),{anchor:new S(t.anchor.line,t.anchor.ch+(r?-1:1)),head:new S(t.head.line,t.head.ch+(r?1:-1))});i.setSelections(e)}else"both"==a?(i.replaceSelection(v+b,null),i.triggerElectric(v+b),O(i,-1)):"addFour"==a&&(i.replaceSelection(v+v+v+v,"before"),O(i,1));var t,r})}(e,n)}}(t))}}function y(e){var n=e.state.closeBrackets;return n&&!n.override&&e.getModeAt(e.getCursor()).closeBrackets||n}function O(e,n){for(var t=[],r=e.listSelections(),i=0,a=0;a<r.length;a++){var o=r[a];o.head==e.getCursor()&&(i=a);o=o.head.ch||0<n?{line:o.head.line,ch:o.head.ch+n}:{line:o.head.line-1};t.push({anchor:o,head:o})}e.setSelections(t,i)}function s(e,n){n=e.getRange(S(n.line,n.ch-1),S(n.line,n.ch+1));return 2==n.length?n:null}r(t.pairs+"`")});

web_interface/static/v3/vendor/codemirror/addon/edit/matchbrackets.min.js

@@ -0,0 +1 @@
+!function(t){"object"==typeof exports&&"object"==typeof module?t(require("../../lib/codemirror")):"function"==typeof define&&define.amd?define(["../../lib/codemirror"],t):t(CodeMirror)}(function(r){var u=/MSIE \d/.test(navigator.userAgent)&&(null==document.documentMode||document.documentMode<8),k=r.Pos,p={"(":")>",")":"(<","[":"]>","]":"[<","{":"}>","}":"{<","<":">>",">":"<<"};function y(t){return t&&t.bracketRegex||/[(){}[\]]/}function f(t,e,n){var r=t.getLineHandle(e.line),i=e.ch-1,c=n&&n.afterCursor;null==c&&(c=/(^| )cm-fat-cursor($| )/.test(t.getWrapperElement().className));var a=y(n),c=!c&&0<=i&&a.test(r.text.charAt(i))&&p[r.text.charAt(i)]||a.test(r.text.charAt(i+1))&&p[r.text.charAt(++i)];if(!c)return null;a=">"==c.charAt(1)?1:-1;if(n&&n.strict&&0<a!=(i==e.ch))return null;r=t.getTokenTypeAt(k(e.line,i+1)),n=o(t,k(e.line,i+(0<a?1:0)),a,r,n);return null==n?null:{from:k(e.line,i),to:n&&n.pos,match:n&&n.ch==c.charAt(0),forward:0<a}}function o(t,e,n,r,i){for(var c=i&&i.maxScanLineLength||1e4,a=i&&i.maxScanLines||1e3,o=[],h=y(i),l=0<n?Math.min(e.line+a,t.lastLine()+1):Math.max(t.firstLine()-1,e.line-a),s=e.line;s!=l;s+=n){var u=t.getLine(s);if(u){var f=0<n?0:u.length-1,m=0<n?u.length:-1;if(!(u.length>c))for(s==e.line&&(f=e.ch-(n<0?1:0));f!=m;f+=n){var g=u.charAt(f);if(h.test(g)&&(void 0===r||(t.getTokenTypeAt(k(s,f+1))||"")==(r||""))){var d=p[g];if(d&&">"==d.charAt(1)==0<n)o.push(g);else{if(!o.length)return{pos:k(s,f),ch:g};o.pop()}}}}}return s-n!=(0<n?t.lastLine():t.firstLine())&&null}function e(t,e,n){for(var r=t.state.matchBrackets.maxHighlightLineLength||1e3,i=n&&n.highlightNonMatching,c=[],a=t.listSelections(),o=0;o<a.length;o++){var h,l=a[o].empty()&&f(t,a[o].head,n);l&&(l.match||!1!==i)&&t.getLine(l.from.line).length<=r&&(h=l.match?"CodeMirror-matchingbracket":"CodeMirror-nonmatchingbracket",c.push(t.markText(l.from,k(l.from.line,l.from.ch+1),{className:h})),l.to&&t.getLine(l.to.line).length<=r&&c.push(t.markText(l.to,k(l.to.line,l.to.ch+1),{className:h})))}if(c.length){u&&t.state.focused&&t.focus();function s(){t.operation(function(){for(var t=0;t<c.length;t++)c[t].clear()})}if(!e)return s;setTimeout(s,800)}}function i(t){t.operation(function(){t.state.matchBrackets.currentlyHighlighted&&(t.state.matchBrackets.currentlyHighlighted(),t.state.matchBrackets.currentlyHighlighted=null),t.state.matchBrackets.currentlyHighlighted=e(t,!1,t.state.matchBrackets)})}function c(t){t.state.matchBrackets&&t.state.matchBrackets.currentlyHighlighted&&(t.state.matchBrackets.currentlyHighlighted(),t.state.matchBrackets.currentlyHighlighted=null)}r.defineOption("matchBrackets",!1,function(t,e,n){n&&n!=r.Init&&(t.off("cursorActivity",i),t.off("focus",i),t.off("blur",c),c(t)),e&&(t.state.matchBrackets="object"==typeof e?e:{},t.on("cursorActivity",i),t.on("focus",i),t.on("blur",c))}),r.defineExtension("matchBrackets",function(){e(this,!0)}),r.defineExtension("findMatchingBracket",function(t,e,n){return f(this,t,e=n||"boolean"==typeof e?n?(n.strict=e,n):e?{strict:!0}:null:e)}),r.defineExtension("scanForBracket",function(t,e,n,r){return o(this,t,e,n,r)})});

web_interface/static/v3/vendor/codemirror/theme/monokai.min.css

@@ -0,0 +1 @@
+.cm-s-monokai.CodeMirror{background:#272822;color:#f8f8f2}.cm-s-monokai div.CodeMirror-selected{background:#49483e}.cm-s-monokai .CodeMirror-line::selection,.cm-s-monokai .CodeMirror-line>span::selection,.cm-s-monokai .CodeMirror-line>span>span::selection{background:rgba(73,72,62,.99)}.cm-s-monokai .CodeMirror-line::-moz-selection,.cm-s-monokai .CodeMirror-line>span::-moz-selection,.cm-s-monokai .CodeMirror-line>span>span::-moz-selection{background:rgba(73,72,62,.99)}.cm-s-monokai .CodeMirror-gutters{background:#272822;border-right:0}.cm-s-monokai .CodeMirror-guttermarker{color:#fff}.cm-s-monokai .CodeMirror-guttermarker-subtle{color:#d0d0d0}.cm-s-monokai .CodeMirror-linenumber{color:#d0d0d0}.cm-s-monokai .CodeMirror-cursor{border-left:1px solid #f8f8f0}.cm-s-monokai span.cm-comment{color:#75715e}.cm-s-monokai span.cm-atom{color:#ae81ff}.cm-s-monokai span.cm-number{color:#ae81ff}.cm-s-monokai span.cm-comment.cm-attribute{color:#97b757}.cm-s-monokai span.cm-comment.cm-def{color:#bc9262}.cm-s-monokai span.cm-comment.cm-tag{color:#bc6283}.cm-s-monokai span.cm-comment.cm-type{color:#5998a6}.cm-s-monokai span.cm-attribute,.cm-s-monokai span.cm-property{color:#a6e22e}.cm-s-monokai span.cm-keyword{color:#f92672}.cm-s-monokai span.cm-builtin{color:#66d9ef}.cm-s-monokai span.cm-string{color:#e6db74}.cm-s-monokai span.cm-variable{color:#f8f8f2}.cm-s-monokai span.cm-variable-2{color:#9effff}.cm-s-monokai span.cm-type,.cm-s-monokai span.cm-variable-3{color:#66d9ef}.cm-s-monokai span.cm-def{color:#fd971f}.cm-s-monokai span.cm-bracket{color:#f8f8f2}.cm-s-monokai span.cm-tag{color:#f92672}.cm-s-monokai span.cm-header{color:#ae81ff}.cm-s-monokai span.cm-link{color:#ae81ff}.cm-s-monokai span.cm-error{background:#f92672;color:#f8f8f0}.cm-s-monokai .CodeMirror-activeline-background{background:#373831}.cm-s-monokai .CodeMirror-matchingbracket{text-decoration:underline;color:#fff!important}

web_interface/templates/v3/captive_setup.html

@@ -87,7 +87,7 @@ select:focus,input:focus{outline:none;border-color:#3b82f6;box-shadow:0 0 0 3px
 </div>
 
 <div class="footer">
-  <a href="/v3">Open Full Interface</a>
+  <a href="/">Open Full Interface</a>
 </div>
 
 <script>

web_interface/templates/v3/partials/display.html

@@ -22,7 +22,7 @@
             On Raspberry Pi 5: ensure the library was rebuilt from the latest submodule
             (<code class="bg-yellow-100 px-1 rounded">first_time_install.sh</code>)
             and try adjusting <strong>GPIO Slowdown</strong> (start at 3, reduce if the display looks dim or choppy).
-            Check the <a href="/v3/logs" class="underline font-medium">Logs tab</a> for the full error.
+            Check the <a href="#" @click.prevent="activeTab = 'logs'" class="underline font-medium">Logs tab</a> for the full error.
         </p>
     </div>
 
@@ -30,7 +30,7 @@
           hx-ext="json-enc"
           hx-headers='{"Content-Type": "application/json"}'
           hx-swap="none"
-          hx-on:htmx:after-request="showNotification(event.detail.xhr.responseJSON?.message || 'Display settings saved', event.detail.xhr.responseJSON?.status || 'success')"
+          hx-on:htmx:after-request="showDisplaySaveResult(event.detail.xhr)"
           class="space-y-6"
           novalidate
           onsubmit="fixInvalidNumberInputs(this); return true;">
@@ -47,7 +47,7 @@
                            name="rows"
                            value="{{ main_config.display.hardware.rows or 32 }}"
                            min="1"
-                           max="64"
+                           max="128"
                            class="form-control">
                 </div>
 
@@ -85,7 +85,14 @@
                 </div>
             </div>
 
-            <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+            <!-- Live total-resolution readout: width = cols x chain_length, height = rows x parallel -->
+            <p id="display-resolution-readout" class="text-sm text-gray-600 mb-4" aria-live="polite">
+                <i class="fas fa-expand-arrows-alt mr-1 text-gray-400"></i>
+                Your display: <strong id="display-resolution-value">&mdash;</strong>
+                <span class="text-gray-400">(columns &times; chain length wide, rows &times; parallel tall)</span>
+            </p>
+
+            <div class="grid grid-cols-1 md:grid-cols-3 gap-4">
                 <div class="form-group" id="setting-display-brightness" data-setting-key="display.hardware.brightness">
                     <label for="brightness" class="block text-sm font-medium text-gray-700">Brightness{{ ui.help_tip('Overall LED brightness (1–100%).\nLower is dimmer, higher is brighter. Recommended: 70–90 indoors, 90–100 in bright rooms.', 'Brightness') }}</label>
                     <div class="flex items-center space-x-2">
@@ -109,9 +116,7 @@
                         <option value="regular-pi1" {% if main_config.display.hardware.hardware_mapping == "regular-pi1" %}selected{% endif %}>Regular Pi1</option>
                     </select>
                 </div>
-            </div>
 
-            <div class="grid grid-cols-1 md:grid-cols-3 gap-4">
                 <div class="form-group" id="setting-display-led_rgb_sequence" data-setting-key="display.hardware.led_rgb_sequence">
                     <label for="led_rgb_sequence" class="block text-sm font-medium text-gray-700">LED RGB Sequence{{ ui.help_tip('Order the panel expects color channels in.\nChange this only if reds/greens/blues look swapped. Default: RGB.', 'LED RGB Sequence') }}</label>
                     <select id="led_rgb_sequence" name="led_rgb_sequence" class="form-control">
@@ -123,7 +128,29 @@
                         <option value="BGR" {% if main_config.display.hardware.get('led_rgb_sequence', 'RGB') == "BGR" %}selected{% endif %}>BGR</option>
                     </select>
                 </div>
+            </div>
 
+            <!-- Advanced hardware settings: niche-panel and deep tuning fields.
+                 Collapsed by default; reuses the same nested-section shell as
+                 plugin config forms, so toggleSection() and the settings
+                 search's auto-expand both work unchanged. -->
+            <div class="nested-section border border-gray-300 rounded-lg mt-4">
+                <button type="button"
+                        class="w-full bg-gray-100 hover:bg-gray-200 px-4 py-3 flex items-center justify-between text-left transition-colors rounded-t-lg"
+                        aria-controls="display-section-advanced-hardware"
+                        aria-expanded="false"
+                        onclick="toggleSection('display-section-advanced-hardware')">
+                    <div class="flex-1">
+                        <h4 class="font-semibold text-gray-900">
+                            <i class="fas fa-sliders-h mr-1 text-gray-500"></i>Advanced Hardware &amp; Display Options (15)
+                        </h4>
+                        <p class="text-sm text-gray-600 mt-1">Multiplexing, panel variants, PWM tuning, and display options &mdash; the defaults work for standard HUB75 panels.</p>
+                    </div>
+                    <i id="display-section-advanced-hardware-icon" class="fas fa-chevron-right text-gray-500 transition-transform"></i>
+                </button>
+                <div id="display-section-advanced-hardware" class="nested-content bg-gray-50 px-4 py-4 space-y-4 hidden" style="display: none;">
+
+            <div class="grid grid-cols-1 md:grid-cols-3 gap-4">
                 <div class="form-group" id="setting-display-multiplexing" data-setting-key="display.hardware.multiplexing">
                     <label for="multiplexing" class="block text-sm font-medium text-gray-700">Multiplexing{{ ui.help_tip('Pixel-mapping scheme used by outdoor/specialty panels.\nLeave at 0 (Direct) for most indoor panels. Only change if the image is scrambled — try values until it looks right.', 'Multiplexing') }}</label>
                     <select id="multiplexing" name="multiplexing" class="form-control">
@@ -255,47 +282,6 @@
                            class="form-control">
                 </div>
             </div>
-        </div>
-
-        <!-- Double-Sided Display -->
-        <div class="bg-gray-50 rounded-lg p-4">
-            <h3 class="text-md font-medium text-gray-900 mb-1">Double-Sided Display</h3>
-            <p class="text-sm text-gray-600 mb-4">Show the same content on every panel in the chain &mdash; e.g. two 64&times;32 panels mirrored, or four panels as two identical screens. Rendered once and duplicated, so it adds no extra CPU. Takes effect after a display restart.</p>
-
-            <div class="grid grid-cols-1 md:grid-cols-3 gap-4">
-                <div class="form-group" id="setting-display-double_sided_enabled" data-setting-key="display.double_sided.enabled">
-                    <label class="flex items-center gap-2">
-                        <input type="checkbox"
-                               id="double_sided_enabled"
-                               name="double_sided_enabled"
-                               value="true"
-                               {% if main_config.display.get('double_sided', {}).get('enabled') %}checked{% endif %}
-                               class="form-control h-4 w-4 text-blue-600 focus:ring-blue-500 border-gray-300 rounded">
-                        <span class="text-sm font-medium text-gray-700">Enabled</span>
-                        {{ ui.help_tip('Show the same content mirrored across every panel in the chain.\nRendered once and duplicated, so it adds no extra CPU. Takes effect after a display restart.', 'Double-Sided Enabled') }}
-                    </label>
-                </div>
-
-                <div class="form-group" id="setting-display-double_sided_copies" data-setting-key="display.double_sided.copies">
-                    <label for="double_sided_copies" class="block text-sm font-medium text-gray-700">Copies{{ ui.help_tip('How many identical screens to split the panel area into (2–8).\nMust divide the panel evenly — e.g. 2 for a two-sided cube.', 'Copies') }}</label>
-                    <input type="number"
-                           id="double_sided_copies"
-                           name="double_sided_copies"
-                           value="{{ main_config.display.get('double_sided', {}).get('copies', 2) }}"
-                           min="2"
-                           max="8"
-                           class="form-control">
-                </div>
-
-                <div class="form-group" id="setting-display-double_sided_axis" data-setting-key="display.double_sided.axis">
-                    <label for="double_sided_axis" class="block text-sm font-medium text-gray-700">Split Axis{{ ui.help_tip('Direction the display is divided into copies.\nHorizontal splits along the chained panels (side by side); Vertical splits along parallel chains (stacked).', 'Split Axis') }}</label>
-                    <select id="double_sided_axis" name="double_sided_axis" class="form-control">
-                        <option value="horizontal" {% if main_config.display.get('double_sided', {}).get('axis', 'horizontal') == 'horizontal' %}selected{% endif %}>Horizontal &mdash; chained panels (side by side)</option>
-                        <option value="vertical" {% if main_config.display.get('double_sided', {}).get('axis', 'horizontal') == 'vertical' %}selected{% endif %}>Vertical &mdash; parallel chains (stacked)</option>
-                    </select>
-                </div>
-            </div>
-        </div>
 
         <!-- Display Options -->
         <div class="bg-gray-50 rounded-lg p-4">
@@ -368,6 +354,36 @@
                 </div>
             </div>
         </div>
+                </div> <!-- /#display-section-advanced-hardware (nested-content) -->
+            </div> <!-- /advanced hardware nested-section -->
+
+            <script>
+                // Live "Your display: W x H" readout - width = cols x chain_length,
+                // height = rows x parallel (same math as the chain-length tooltip).
+                (function () {
+                    const ids = ['rows', 'cols', 'chain_length', 'parallel'];
+                    const out = document.getElementById('display-resolution-value');
+                    if (!out) return;
+                    function recompute() {
+                        const v = {};
+                        for (const id of ids) {
+                            const el = document.getElementById(id);
+                            v[id] = el ? parseInt(el.value, 10) : NaN;
+                        }
+                        if (Object.values(v).some(n => !Number.isFinite(n) || n <= 0)) {
+                            out.textContent = '—';
+                            return;
+                        }
+                        out.textContent = (v.cols * v.chain_length) + ' × ' + (v.rows * v.parallel) + ' pixels';
+                    }
+                    for (const id of ids) {
+                        const el = document.getElementById(id);
+                        if (el) el.addEventListener('input', recompute);
+                    }
+                    recompute();
+                })();
+            </script>
+        </div>
 
         <!-- Vegas Scroll Mode Settings -->
         <div class="bg-gray-50 rounded-lg p-4 mt-6">
@@ -409,7 +425,7 @@
                     </div>
 
                     <div class="form-group" id="setting-display-vegas_separator_width" data-setting-key="display.vegas_scroll.separator_width">
-                        <label for="vegas_separator_width" class="block text-sm font-medium text-gray-700">Separator Width (pixels){{ ui.help_tip('Blank gap inserted between each plugin block in the ticker (0–128 px).\nDefault: 32. Larger values make the boundary between plugins clearer.', 'Separator Width') }}</label>
+                        <label for="vegas_separator_width" class="block text-sm font-medium text-gray-700">Separator Width (pixels){{ ui.help_tip('Blank gap where one plugin hands off to the next (0–128 px).\nDefault: 32. Larger values make the boundary between plugins clearer. This does not apply between rows of the same plugin — see Row Gap for that.', 'Separator Width') }}</label>
                         <input type="number"
                                id="vegas_separator_width"
                                name="vegas_separator_width"
@@ -420,6 +436,44 @@
                     </div>
                 </div>
 
+                <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+                    <div class="form-group" id="setting-display-vegas_intra_plugin_gap" data-setting-key="display.vegas_scroll.intra_plugin_gap">
+                        <label for="vegas_intra_plugin_gap" class="block text-sm font-medium text-gray-700">Row Gap (pixels){{ ui.help_tip('Extra gap always added between rows contributed by the same plugin (0–128 px).\nDefault: 8. This is a floor on top of Row Separation below, which does most of the work. Set both to 0 to butt rows directly together.', 'Row Gap') }}</label>
+                        <input type="number"
+                               id="vegas_intra_plugin_gap"
+                               name="vegas_intra_plugin_gap"
+                               value="{{ main_config.display.get('vegas_scroll', {}).get('intra_plugin_gap', 8) }}"
+                               min="0"
+                               max="128"
+                               class="form-control">
+                    </div>
+
+                    <div class="form-group" id="setting-display-vegas_min_content_separation" data-setting-key="display.vegas_scroll.min_content_separation">
+                        <label for="vegas_min_content_separation" class="block text-sm font-medium text-gray-700">Row Separation (pixels){{ ui.help_tip('Blank space guaranteed between rows of the same plugin, measured from the actual content rather than added blindly (0–256 px).\nDefault: 24. Rows already carrying wide margins get nothing added; rows drawn right up to their own edges — sports score cards, for instance — get the full amount, so they no longer look like they are touching. Raise it if items still feel cramped.', 'Row Separation') }}</label>
+                        <input type="number"
+                               id="vegas_min_content_separation"
+                               name="vegas_min_content_separation"
+                               value="{{ main_config.display.get('vegas_scroll', {}).get('min_content_separation', 24) }}"
+                               min="0"
+                               max="256"
+                               class="form-control">
+                    </div>
+                </div>
+
+                <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+                    <div class="form-group" id="setting-display-vegas_render_width_pct" data-setting-key="display.vegas_scroll.render_width_pct">
+                        <label for="vegas_render_width_pct" class="block text-sm font-medium text-gray-700">Plugin Render Width (%){{ ui.help_tip('How much of the screen width each plugin is told it has while drawing for the ticker (10–100%).\nDefault: 100 (unchanged). Lowering it makes plugins choose a tighter layout rather than being cropped — a weather forecast becomes narrow cards instead of five columns spread across the panel. Useful on wide displays. Override per plugin with the vegas_width_pct setting in that plugin\'s own configuration.', 'Plugin Render Width') }}</label>
+                        <input type="number"
+                               id="vegas_render_width_pct"
+                               name="vegas_render_width_pct"
+                               value="{{ main_config.display.get('vegas_scroll', {}).get('render_width_pct', 100) }}"
+                               min="10"
+                               max="100"
+                               step="5"
+                               class="form-control">
+                    </div>
+                </div>
+
                 <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
                     <div class="form-group" id="setting-display-vegas_target_fps" data-setting-key="display.vegas_scroll.target_fps">
                         <label for="vegas_target_fps" class="block text-sm font-medium text-gray-700">Target FPS{{ ui.help_tip('Frames per second the Vegas ticker aims to render.\nHigher = smoother scrolling but more CPU. Default: 125 (smoothest). Drop to 60/90 if the Pi runs hot.', 'Target FPS') }}</label>
@@ -440,6 +494,194 @@
                     </div>
                 </div>
 
+                <!-- Cycle Pacing -->
+                <div class="mt-4 pt-4 border-t border-gray-200">
+                    <h4 class="text-sm font-medium text-gray-900 mb-3">Cycle Pacing</h4>
+                    <p class="text-sm text-gray-600 mb-3">How long one pass through the ticker lasts, and how many plugins it covers.</p>
+
+                    <div class="form-group mb-4" id="setting-display-vegas_continuous_scroll" data-setting-key="display.vegas_scroll.continuous_scroll">
+                        <label class="flex items-center">
+                            <input type="checkbox"
+                                   id="vegas_continuous_scroll"
+                                   name="vegas_continuous_scroll"
+                                   {% if main_config.display.get('vegas_scroll', {}).get('continuous_scroll', True) %}checked{% endif %}
+                                   class="form-checkbox">
+                            <span class="ml-2 text-sm text-gray-700">Scroll continuously between groups{{ ui.help_tip('Keep one endless strip, extending it with the next group of plugins as the scroll approaches the end, so they simply arrive from the right. Default: on.\nWith this off the ticker builds a fresh strip and swaps it in, which stops the motion, replaces everything at once and restarts with the screen already full — a freeze, a flash and a jump.', 'Continuous Scroll') }}</span>
+                        </label>
+                    </div>
+
+                    <div class="form-group mb-4" id="setting-display-vegas_smooth_scroll" data-setting-key="display.vegas_scroll.smooth_scroll">
+                        <label class="flex items-center">
+                            <input type="checkbox"
+                                   id="vegas_smooth_scroll"
+                                   name="vegas_smooth_scroll"
+                                   {% if main_config.display.get('vegas_scroll', {}).get('smooth_scroll', True) %}checked{% endif %}
+                                   class="form-checkbox">
+                            <span class="ml-2 text-sm text-gray-700">Smooth sub-pixel motion{{ ui.help_tip('Blend between neighbouring pixel positions so the ticker moves once per rendered frame instead of once per pixel. Default: on.\nWithout it, motion happens only as often as the scroll speed in pixels per second — at 50 px/s that is 50 steps a second however fast the display renders, which reads as a slight judder. The trade is that text softens very slightly horizontally, since each frame blends two positions. Turn it off if you prefer maximum crispness.', 'Smooth Scrolling') }}</span>
+                        </label>
+                    </div>
+
+                    <div class="grid grid-cols-1 md:grid-cols-2 gap-4 mb-4">
+                        <div class="form-group" id="setting-display-vegas_extend_threshold_screens" data-setting-key="display.vegas_scroll.extend_threshold_screens">
+                            <label for="vegas_extend_threshold_screens" class="block text-sm font-medium text-gray-700">Extend When (screens left){{ ui.help_tip('How much unscrolled content triggers loading the next group, measured in screen widths (1.0–10.0).\nDefault: 2. Higher loads earlier and leaves more slack, at the cost of holding more content in memory. Only applies when Continuous Scroll is on.', 'Extend Threshold') }}</label>
+                            <input type="number"
+                                   id="vegas_extend_threshold_screens"
+                                   name="vegas_extend_threshold_screens"
+                                   value="{{ main_config.display.get('vegas_scroll', {}).get('extend_threshold_screens', 2.0) }}"
+                                   min="1"
+                                   max="10"
+                                   step="0.5"
+                                   class="form-control">
+                        </div>
+                    </div>
+
+                    <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+                        <div class="form-group" id="setting-display-vegas_plugins_per_cycle" data-setting-key="display.vegas_scroll.plugins_per_cycle">
+                            <label for="vegas_plugins_per_cycle" class="block text-sm font-medium text-gray-700">Plugins Per Cycle{{ ui.help_tip('How many plugins are composed into one pass of the ticker (1–50).\nDefault: 6. Higher means more variety before the ticker restarts, and fewer recompose pauses. Lower means each plugin comes around sooner.', 'Plugins Per Cycle') }}</label>
+                            <input type="number"
+                                   id="vegas_plugins_per_cycle"
+                                   name="vegas_plugins_per_cycle"
+                                   value="{{ main_config.display.get('vegas_scroll', {}).get('plugins_per_cycle', 6) }}"
+                                   min="1"
+                                   max="50"
+                                   class="form-control">
+                        </div>
+
+                        <div class="form-group" id="setting-display-vegas_overflow_mode" data-setting-key="display.vegas_scroll.overflow_mode">
+                            <label for="vegas_overflow_mode" class="block text-sm font-medium text-gray-700">When A Plugin Is Too Wide{{ ui.help_tip('What to do when a plugin has more content than its width allowance.\nRotate through it: show a different slice each time round, so everything is seen eventually. Right for interchangeable items like news headlines, odds or stock prices.\nShow the start only: always display from the beginning and drop the rest. Right for ordered content — a league table that shows ranks 1-6 and then resumes at 7 two rotations later reads as out of order.\nDefault: rotate. Override for one plugin with vegas_overflow in its own settings.', 'Overflow Handling') }}</label>
+                            <select id="vegas_overflow_mode" name="vegas_overflow_mode" class="form-control">
+                                <option value="rotate" {% if main_config.display.get('vegas_scroll', {}).get('overflow_mode', 'rotate') == 'rotate' %}selected{% endif %}>Rotate through it (default)</option>
+                                <option value="truncate" {% if main_config.display.get('vegas_scroll', {}).get('overflow_mode', 'rotate') == 'truncate' %}selected{% endif %}>Show the start only</option>
+                            </select>
+                        </div>
+
+                        <div class="form-group" id="setting-display-vegas_max_plugin_width_ratio" data-setting-key="display.vegas_scroll.max_plugin_width_ratio">
+                            <label for="vegas_max_plugin_width_ratio" class="block text-sm font-medium text-gray-700">Max Plugin Width (screens){{ ui.help_tip('Caps how much of one cycle a single plugin may occupy, measured in screen widths (0–20).\nDefault: 3. A long ticker such as a news feed or leaderboard is trimmed to this and the remainder shown on later cycles, so one plugin cannot hold the display for minutes. Set 0 for no limit.', 'Max Plugin Width') }}</label>
+                            <input type="number"
+                                   id="vegas_max_plugin_width_ratio"
+                                   name="vegas_max_plugin_width_ratio"
+                                   value="{{ main_config.display.get('vegas_scroll', {}).get('max_plugin_width_ratio', 3.0) }}"
+                                   min="0"
+                                   max="20"
+                                   step="0.5"
+                                   class="form-control">
+                        </div>
+                    </div>
+
+                    <div class="form-group mt-4" id="setting-display-vegas_dynamic_duration_enabled" data-setting-key="display.vegas_scroll.dynamic_duration_enabled">
+                        <label class="flex items-center">
+                            <input type="checkbox"
+                                   id="vegas_dynamic_duration_enabled"
+                                   name="vegas_dynamic_duration_enabled"
+                                   {% if main_config.display.get('vegas_scroll', {}).get('dynamic_duration_enabled', True) %}checked{% endif %}
+                                   class="form-checkbox">
+                            <span class="ml-2 text-sm text-gray-700">Size cycle time to the content{{ ui.help_tip('When on, each cycle runs just long enough to scroll all its content past, clamped to the min and max below.\nWhen off, the max is always used. Default: on.', 'Dynamic Cycle Duration') }}</span>
+                        </label>
+                    </div>
+
+                    <div class="grid grid-cols-1 md:grid-cols-2 gap-4 mt-2">
+                        <div class="form-group" id="setting-display-vegas_min_cycle_duration" data-setting-key="display.vegas_scroll.min_cycle_duration">
+                            <label for="vegas_min_cycle_duration" class="block text-sm font-medium text-gray-700">Min Cycle Time (seconds){{ ui.help_tip('Shortest a single ticker pass may last (5–3600 s).\nDefault: 60.', 'Min Cycle Time') }}</label>
+                            <input type="number"
+                                   id="vegas_min_cycle_duration"
+                                   name="vegas_min_cycle_duration"
+                                   value="{{ main_config.display.get('vegas_scroll', {}).get('min_cycle_duration', 60) }}"
+                                   min="5"
+                                   max="3600"
+                                   class="form-control">
+                        </div>
+
+                        <div class="form-group" id="setting-display-vegas_max_cycle_duration" data-setting-key="display.vegas_scroll.max_cycle_duration">
+                            <label for="vegas_max_cycle_duration" class="block text-sm font-medium text-gray-700">Max Cycle Time (seconds){{ ui.help_tip('Longest a single ticker pass may last before it restarts with fresh content (10–3600 s).\nThis is the setting that caps total Vegas scroll time. Default: 240. Lower it if the ticker feels like it takes too long to come back around.', 'Max Cycle Time') }}</label>
+                            <input type="number"
+                                   id="vegas_max_cycle_duration"
+                                   name="vegas_max_cycle_duration"
+                                   value="{{ main_config.display.get('vegas_scroll', {}).get('max_cycle_duration', 240) }}"
+                                   min="10"
+                                   max="3600"
+                                   class="form-control">
+                        </div>
+                    </div>
+                </div>
+
+                <!-- Dead Space -->
+                <div class="mt-4 pt-4 border-t border-gray-200">
+                    <h4 class="text-sm font-medium text-gray-900 mb-3">Dead Space</h4>
+                    <p class="text-sm text-gray-600 mb-3">Plugins that draw onto a full-screen canvas contribute all the empty space around their content. Trimming reclaims it so the ticker stays full.</p>
+
+                    <div class="form-group mb-4" id="setting-display-vegas_auto_trim" data-setting-key="display.vegas_scroll.auto_trim">
+                        <label class="flex items-center">
+                            <input type="checkbox"
+                                   id="vegas_auto_trim"
+                                   name="vegas_auto_trim"
+                                   {% if main_config.display.get('vegas_scroll', {}).get('auto_trim', True) %}checked{% endif %}
+                                   class="form-checkbox">
+                            <span class="ml-2 text-sm text-gray-700">Trim empty edges from plugin content{{ ui.help_tip('Crops blank columns from the left and right of each plugin block before it enters the ticker. Space between two pieces of content inside a block is left alone, so layouts are not altered. Default: on.', 'Auto Trim') }}</span>
+                        </label>
+                    </div>
+
+                    <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+                        <div class="form-group" id="setting-display-vegas_content_padding" data-setting-key="display.vegas_scroll.content_padding">
+                            <label for="vegas_content_padding" class="block text-sm font-medium text-gray-700">Content Padding (pixels){{ ui.help_tip('Blank columns kept either side of trimmed content, so it does not butt against the separator (0–128 px).\nDefault: 8.', 'Content Padding') }}</label>
+                            <input type="number"
+                                   id="vegas_content_padding"
+                                   name="vegas_content_padding"
+                                   value="{{ main_config.display.get('vegas_scroll', {}).get('content_padding', 8) }}"
+                                   min="0"
+                                   max="128"
+                                   class="form-control">
+                        </div>
+
+                        <div class="form-group" id="setting-display-vegas_lead_in_width" data-setting-key="display.vegas_scroll.lead_in_width">
+                            <label for="vegas_lead_in_width" class="block text-sm font-medium text-gray-700">Lead-In Gap (pixels){{ ui.help_tip('Blank space before the first plugin of each cycle (0–2048 px).\nDefault: 0. Anything approaching your screen width reads as the display switching off at the start of every cycle.', 'Lead-In Gap') }}</label>
+                            <input type="number"
+                                   id="vegas_lead_in_width"
+                                   name="vegas_lead_in_width"
+                                   value="{{ main_config.display.get('vegas_scroll', {}).get('lead_in_width', 0) }}"
+                                   min="0"
+                                   max="2048"
+                                   class="form-control">
+                        </div>
+                    </div>
+
+                    <div class="grid grid-cols-1 md:grid-cols-2 gap-4 mt-4">
+                        <div class="form-group" id="setting-display-vegas_trim_threshold" data-setting-key="display.vegas_scroll.trim_threshold">
+                            <label for="vegas_trim_threshold" class="block text-sm font-medium text-gray-700">Trim Threshold{{ ui.help_tip('How bright a pixel must be to count as content rather than empty space (0–254).\nDefault: 10, which ignores the near-black noise left by image compression. Raise it if very dark artwork is being kept; lower it if dark detail is being cropped.', 'Trim Threshold') }}</label>
+                            <input type="number"
+                                   id="vegas_trim_threshold"
+                                   name="vegas_trim_threshold"
+                                   value="{{ main_config.display.get('vegas_scroll', {}).get('trim_threshold', 10) }}"
+                                   min="0"
+                                   max="254"
+                                   class="form-control">
+                        </div>
+
+                        <div class="form-group" id="setting-display-vegas_min_plugin_width" data-setting-key="display.vegas_scroll.min_plugin_width">
+                            <label for="vegas_min_plugin_width" class="block text-sm font-medium text-gray-700">Min Plugin Width (pixels){{ ui.help_tip('Plugin blocks narrower than this after trimming are skipped for that cycle (0–512 px).\nDefault: 8. Raise it to hide plugins showing only a tiny placeholder such as "No Data" until they have real content.', 'Min Plugin Width') }}</label>
+                            <input type="number"
+                                   id="vegas_min_plugin_width"
+                                   name="vegas_min_plugin_width"
+                                   value="{{ main_config.display.get('vegas_scroll', {}).get('min_plugin_width', 8) }}"
+                                   min="0"
+                                   max="512"
+                                   class="form-control">
+                        </div>
+                    </div>
+
+                    <div class="grid grid-cols-1 md:grid-cols-2 gap-4 mt-4">
+                        <div class="form-group" id="setting-display-vegas_min_cut_gap" data-setting-key="display.vegas_scroll.min_cut_gap">
+                            <label for="vegas_min_cut_gap" class="block text-sm font-medium text-gray-700">Min Cut Gap (pixels){{ ui.help_tip('When a plugin is too wide for its share of a cycle and has to be narrowed, the cut is only made where there is at least this much blank space (1–128 px).\nDefault: 6. The gaps between letters are about 1px wide, so a smaller value lets a cut land inside a word and orphan its last letter into the next cycle. Raise it if cuts still land awkwardly. Continuous images such as maps have no gaps and are cut to fit regardless.', 'Min Cut Gap') }}</label>
+                            <input type="number"
+                                   id="vegas_min_cut_gap"
+                                   name="vegas_min_cut_gap"
+                                   value="{{ main_config.display.get('vegas_scroll', {}).get('min_cut_gap', 6) }}"
+                                   min="1"
+                                   max="128"
+                                   class="form-control">
+                        </div>
+                    </div>
+                </div>
+
                 <!-- Plugin Order Section -->
                 <div class="mt-4 pt-4 border-t border-gray-200">
                     <h4 class="text-sm font-medium text-gray-900 mb-3">Plugin Order</h4>
@@ -454,6 +696,52 @@
             </div>
         </div>
 
+        <!-- Double-Sided Display -->
+        <div class="bg-gray-50 rounded-lg p-4">
+            <h3 class="text-md font-medium text-gray-900 mb-1">Double-Sided Display</h3>
+            <p class="text-sm text-gray-600 mb-4">Show the same content on every panel in the chain &mdash; e.g. two 64&times;32 panels mirrored, or four panels as two identical screens. Rendered once and duplicated, so it adds no extra CPU. Takes effect after a display restart.</p>
+
+            <div class="form-group mb-4" id="setting-display-double_sided_enabled" data-setting-key="display.double_sided.enabled">
+                <label class="flex items-center gap-2">
+                    <input type="checkbox"
+                           id="double_sided_enabled"
+                           name="double_sided_enabled"
+                           value="true"
+                           {% if main_config.display.get('double_sided', {}).get('enabled') %}checked{% endif %}
+                           class="form-control h-4 w-4 text-blue-600 focus:ring-blue-500 border-gray-300 rounded">
+                    <span class="text-sm font-medium text-gray-700">Enabled</span>
+                    {{ ui.help_tip('Show the same content mirrored across every panel in the chain.\nRendered once and duplicated, so it adds no extra CPU. Takes effect after a display restart.', 'Double-Sided Enabled') }}
+                </label>
+            </div>
+
+            <!-- Hidden (not disabled) when the feature is off, so the values are
+                 still submitted and round-trip through a save. -->
+            <div id="double_sided_settings"
+                 class="grid grid-cols-1 md:grid-cols-2 gap-4"
+                 {% if not main_config.display.get('double_sided', {}).get('enabled') %}style="display: none;"{% endif %}>
+                <div class="form-group" id="setting-display-double_sided_copies" data-setting-key="display.double_sided.copies">
+                    <label for="double_sided_copies" class="block text-sm font-medium text-gray-700">Copies{{ ui.help_tip('How many identical screens to split the panel area into (2–8).\nWhen enabled, this must divide the panel evenly — e.g. 2 for a two-sided cube.', 'Copies') }}</label>
+                    <input type="number"
+                           id="double_sided_copies"
+                           name="double_sided_copies"
+                           value="{{ main_config.display.get('double_sided', {}).get('copies', 2) }}"
+                           min="2"
+                           max="8"
+                           class="form-control">
+                </div>
+
+                <div class="form-group" id="setting-display-double_sided_axis" data-setting-key="display.double_sided.axis">
+                    <label for="double_sided_axis" class="block text-sm font-medium text-gray-700">Split Axis{{ ui.help_tip('Direction the display is divided into copies.\nHorizontal splits along the chained panels (side by side); Vertical splits along parallel chains (stacked).', 'Split Axis') }}</label>
+                    <select id="double_sided_axis" name="double_sided_axis" class="form-control">
+                        <option value="horizontal" {% if main_config.display.get('double_sided', {}).get('axis', 'horizontal') == 'horizontal' %}selected{% endif %}>Horizontal &mdash; chained panels (side by side)</option>
+                        <option value="vertical" {% if main_config.display.get('double_sided', {}).get('axis', 'horizontal') == 'vertical' %}selected{% endif %}>Vertical &mdash; parallel chains (stacked)</option>
+                    </select>
+                </div>
+            </div>
+        </div>
+
+
+
         <!-- Multi-Display Sync Settings -->
         <div class="bg-gray-50 rounded-lg p-4 mt-6">
             <div class="flex items-center justify-between mb-4">
@@ -549,6 +837,28 @@ if (typeof window.fixInvalidNumberInputs !== 'function') {
     };
 }
 
+// Report the outcome of a display-settings save. XMLHttpRequest has no
+// `responseJSON` (that's a jQuery property) — read `responseText` and the real
+// status code, otherwise a failed save reports success.
+window.showDisplaySaveResult = function(xhr) {
+    // Only 2xx counts as saved. A network failure reports status 0, which any
+    // `>= 400` test would wave through as success.
+    const httpSuccess = xhr.status >= 200 && xhr.status < 300;
+    let message = httpSuccess
+        ? 'Display settings saved'
+        : 'Display settings were not saved. Check your connection and try again.';
+    let status = httpSuccess ? 'success' : 'error';
+    try {
+        const data = JSON.parse(xhr.responseText);
+        if (data.message) message = data.message;
+        // A body can refine a successful verdict but never overturn a failed one.
+        if (httpSuccess && data.status) status = data.status;
+    } catch {
+        // Non-JSON body — fall back to the status-code verdict above.
+    }
+    showNotification(message, status);
+};
+
 // Vegas Scroll Mode Settings
 (function() {
     // Escape HTML to prevent XSS
@@ -573,6 +883,18 @@ if (typeof window.fixInvalidNumberInputs !== 'function') {
         });
     }
 
+    // Double-sided: copies/axis only mean anything while the feature is on.
+    // Hidden rather than disabled so the fields keep submitting and the server
+    // still sees an 'off' state to persist.
+    const doubleSidedCheckbox = document.getElementById('double_sided_enabled');
+    const doubleSidedSettings = document.getElementById('double_sided_settings');
+
+    if (doubleSidedCheckbox && doubleSidedSettings) {
+        doubleSidedCheckbox.addEventListener('change', function() {
+            doubleSidedSettings.style.display = this.checked ? 'grid' : 'none';
+        });
+    }
+
     // Update scroll speed display
     const scrollSpeedSlider = document.getElementById('vegas_scroll_speed');
     const scrollSpeedValue = document.getElementById('vegas_scroll_speed_value');
@@ -583,183 +905,32 @@ if (typeof window.fixInvalidNumberInputs !== 'function') {
         });
     }
 
-    // Initialize plugin order list
-    function initPluginOrderList() {
+    // Initialize plugin order list via the shared drag-and-drop module
+    // (static/v3/js/widgets/plugin-order-list.js) — the same component the
+    // Durations tab uses for the primary rotation order.
+    function initPluginOrderList(attempt) {
         const container = document.getElementById('vegas_plugin_order');
         if (!container) return;
-
-        // Fetch available plugins
-        fetch('/api/v3/plugins/installed')
-            .then(response => response.json())
-            .then(data => {
-                // Handle both {data: {plugins: []}} and {plugins: []} response formats
-                const allPlugins = data.data?.plugins || data.plugins || [];
-                if (!allPlugins || allPlugins.length === 0) {
-                    container.innerHTML = '<p class="text-sm text-gray-500 italic">No plugins available</p>';
-                    return;
-                }
-
-                // Get current order and exclusions
-                const orderInput = document.getElementById('vegas_plugin_order_value');
-                const excludedInput = document.getElementById('vegas_excluded_plugins_value');
-                let currentOrder = [];
-                let excluded = [];
-
-                try {
-                    currentOrder = JSON.parse(orderInput.value || '[]');
-                    excluded = JSON.parse(excludedInput.value || '[]');
-                } catch (e) {
-                    console.error('Error parsing vegas config:', e);
-                }
-
-                // Build ordered plugin list (only enabled plugins)
-                const plugins = allPlugins.filter(p => p.enabled);
-                const orderedPlugins = [];
-
-                // First add plugins in current order
-                currentOrder.forEach(id => {
-                    const plugin = plugins.find(p => p.id === id);
-                    if (plugin) orderedPlugins.push(plugin);
-                });
-
-                // Then add remaining plugins
-                plugins.forEach(plugin => {
-                    if (!orderedPlugins.find(p => p.id === plugin.id)) {
-                        orderedPlugins.push(plugin);
-                    }
-                });
-
-                // Build HTML with display mode indicators
-                let html = '';
-                orderedPlugins.forEach((plugin, index) => {
-                    const isExcluded = excluded.includes(plugin.id);
-                    // Determine display mode (from plugin config or default)
-                    const vegasMode = plugin.vegas_mode || plugin.vegas_content_type || 'fixed';
-                    const modeLabels = {
-                        'scroll': { label: 'Scroll', icon: 'fa-scroll', color: 'text-blue-600' },
-                        'fixed': { label: 'Fixed', icon: 'fa-square', color: 'text-green-600' },
-                        'static': { label: 'Static', icon: 'fa-pause', color: 'text-orange-600' }
-                    };
-                    const modeInfo = modeLabels[vegasMode] || modeLabels['fixed'];
-                    // Escape plugin metadata to prevent XSS
-                    const safePluginId = escapeAttr(plugin.id);
-                    const safePluginName = escapeHtml(plugin.name || plugin.id);
-                    html += `
-                        <div class="flex items-center p-2 bg-gray-50 rounded border border-gray-200 cursor-move vegas-plugin-item"
-                             data-plugin-id="${safePluginId}" draggable="true">
-                            <i class="fas fa-grip-vertical text-gray-400 mr-3"></i>
-                            <label class="flex items-center flex-1">
-                                <input type="checkbox"
-                                       class="vegas-plugin-include h-4 w-4 text-blue-600 focus:ring-blue-500 border-gray-300 rounded mr-2"
-                                       ${!isExcluded ? 'checked' : ''}>
-                                <span class="text-sm font-medium text-gray-700">${safePluginName}</span>
-                            </label>
-                            <span class="text-xs ${modeInfo.color} ml-2" title="Vegas display mode: ${modeInfo.label}">
-                                <i class="fas ${modeInfo.icon} mr-1"></i>${modeInfo.label}
-                            </span>
-                        </div>
-                    `;
-                });
-
-                container.innerHTML = html || '<p class="text-sm text-gray-500 italic">No enabled plugins</p>';
-
-                // Setup drag and drop
-                setupDragAndDrop(container);
-
-                // Setup checkbox handlers
-                container.querySelectorAll('.vegas-plugin-include').forEach(checkbox => {
-                    checkbox.addEventListener('change', updatePluginConfig);
-                });
-
-                // Initialize hidden inputs with current state
-                updatePluginConfig();
-            })
-            .catch(error => {
-                console.error('Error fetching plugins:', error);
-                container.innerHTML = '<p class="text-sm text-red-500">Error loading plugins</p>';
-            });
-    }
-
-    function setupDragAndDrop(container) {
-        let draggedItem = null;
-
-        container.querySelectorAll('.vegas-plugin-item').forEach(item => {
-            item.addEventListener('dragstart', function(e) {
-                draggedItem = this;
-                this.style.opacity = '0.5';
-                e.dataTransfer.effectAllowed = 'move';
-            });
-
-            item.addEventListener('dragend', function() {
-                this.style.opacity = '1';
-                draggedItem = null;
-                updatePluginConfig();
-            });
-
-            item.addEventListener('dragover', function(e) {
-                e.preventDefault();
-                e.dataTransfer.dropEffect = 'move';
-
-                const rect = this.getBoundingClientRect();
-                const midY = rect.top + rect.height / 2;
-
-                if (e.clientY < midY) {
-                    this.style.borderTop = '2px solid #3b82f6';
-                    this.style.borderBottom = '';
-                } else {
-                    this.style.borderBottom = '2px solid #3b82f6';
-                    this.style.borderTop = '';
-                }
-            });
-
-            item.addEventListener('dragleave', function() {
-                this.style.borderTop = '';
-                this.style.borderBottom = '';
-            });
-
-            item.addEventListener('drop', function(e) {
-                e.preventDefault();
-                this.style.borderTop = '';
-                this.style.borderBottom = '';
-
-                if (draggedItem && draggedItem !== this) {
-                    const rect = this.getBoundingClientRect();
-                    const midY = rect.top + rect.height / 2;
-
-                    if (e.clientY < midY) {
-                        container.insertBefore(draggedItem, this);
-                    } else {
-                        container.insertBefore(draggedItem, this.nextSibling);
-                    }
-                }
-            });
-        });
-    }
-
-    function updatePluginConfig() {
-        const container = document.getElementById('vegas_plugin_order');
-        const orderInput = document.getElementById('vegas_plugin_order_value');
-        const excludedInput = document.getElementById('vegas_excluded_plugins_value');
-
-        if (!container || !orderInput || !excludedInput) return;
-
-        const order = [];
-        const excluded = [];
-
-        container.querySelectorAll('.vegas-plugin-item').forEach(item => {
-            const pluginId = item.dataset.pluginId;
-            const checkbox = item.querySelector('.vegas-plugin-include');
-
-            order.push(pluginId);
-            if (checkbox && !checkbox.checked) {
-                excluded.push(pluginId);
+        if (!window.PluginOrderList) {
+            // Widget script is deferred; retry briefly, then surface a real
+            // error instead of waiting forever.
+            if ((attempt || 0) < 50) {
+                setTimeout(function() { initPluginOrderList((attempt || 0) + 1); }, 100);
+            } else {
+                container.textContent = 'Could not load the reorder widget — reload the page to try again.';
+                container.className = 'text-sm text-red-500';
             }
+            return;
+        }
+        window.PluginOrderList.init({
+            containerId: 'vegas_plugin_order',
+            orderInputId: 'vegas_plugin_order_value',
+            excludedInputId: 'vegas_excluded_plugins_value',
+            showVegasModeBadge: true
         });
-
-        orderInput.value = JSON.stringify(order);
-        excludedInput.value = JSON.stringify(excluded);
     }
 
+
     // Initialize on DOM ready
     if (document.readyState === 'loading') {
         document.addEventListener('DOMContentLoaded', initPluginOrderList);

web_interface/templates/v3/partials/durations.html

@@ -1,8 +1,8 @@
 {% import 'v3/partials/_macros.html' as ui %}
 <div class="bg-white rounded-lg shadow p-6">
     <div class="border-b border-gray-200 pb-4 mb-6">
-        <h2 class="text-lg font-semibold text-gray-900">Display Durations</h2>
-        <p class="mt-1 text-sm text-gray-600">Configure how long each screen is shown before switching. Values in seconds.</p>
+        <h2 class="text-lg font-semibold text-gray-900">Rotation &amp; Durations</h2>
+        <p class="mt-1 text-sm text-gray-600">Set the order plugins rotate on the display and how long each screen is shown. Durations are in seconds.</p>
     </div>
 
     {{ ui.settings_filter() }}
@@ -16,22 +16,53 @@
           novalidate
           onsubmit="fixInvalidNumberInputs(this); return true;">
 
-        <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
-            {% for key, value in main_config.display.display_durations.items() %}
-            <div class="form-group" id="setting-durations-{{ key }}" data-setting-key="display.display_durations.{{ key }}">
-                <label for="duration_{{ key }}" class="block text-sm font-medium text-gray-700">
-                    {{ key | replace('_', ' ') | title }}{{ ui.help_tip('How long the ' ~ (key | replace('_', ' ')) ~ ' screen stays on before rotating to the next one, in seconds.\nRange: 5–600. Currently ' ~ value ~ 's.', key | replace('_', ' ') | title) }}
-                </label>
-                <input type="number"
-                       id="duration_{{ key }}"
-                       name="{{ key }}"
-                       value="{{ value }}"
-                       min="5"
-                       max="600"
-                       class="form-control">
+        <!-- Primary rotation order: drag to reorder which plugin shows first,
+             second, ... in the normal display rotation. Saved as
+             display.plugin_rotation_order and applied by the display
+             controller on startup and live plugin enable/disable. -->
+        <div class="bg-gray-50 rounded-lg p-4">
+            <h3 class="text-md font-medium text-gray-900 mb-1">Rotation Order</h3>
+            <p class="text-sm text-gray-600 mb-3">Drag plugins to set the order they rotate on the display. Each plugin's screens keep their own order within its turn. Takes effect after saving and restarting the display.</p>
+            <div id="rotation_plugin_order" class="space-y-2 bg-white rounded-lg p-3 border border-gray-200">
+                <p class="text-sm text-gray-500 italic">Loading plugins…</p>
+            </div>
+            <input type="hidden" id="rotation_plugin_order_value" name="plugin_rotation_order"
+                   value='{{ main_config.display.get("plugin_rotation_order", [])|tojson }}'>
+        </div>
+
+        {% if duration_groups %}
+        <div class="bg-gray-50 rounded-lg p-4 space-y-5">
+            <div>
+                <h3 class="text-md font-medium text-gray-900 mb-1">Screen Durations</h3>
+                <p class="text-sm text-gray-600">How long each screen stays on before rotating to the next one, in seconds (5&ndash;600, default 30).</p>
+            </div>
+            {% for group in duration_groups %}
+            <div>
+                <h4 class="text-sm font-semibold text-gray-800 mb-2">{{ group.plugin_name }}</h4>
+                <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+                    {% for mode in group.modes %}
+                    <div class="form-group" id="setting-durations-{{ mode.key }}" data-setting-key="display.display_durations.{{ mode.key }}">
+                        <label for="duration__{{ mode.key }}" class="block text-sm font-medium text-gray-700">
+                            {{ mode.key | replace('_', ' ') | title }}{{ ui.help_tip('How long the ' ~ (mode.key | replace('_', ' ')) ~ ' screen stays on before rotating to the next one, in seconds.\nRange: 5–600. Currently ' ~ mode.value ~ 's.', mode.key | replace('_', ' ') | title) }}
+                        </label>
+                        <input type="number"
+                               id="duration__{{ mode.key }}"
+                               name="duration__{{ mode.key }}"
+                               value="{{ mode.value }}"
+                               min="5"
+                               max="600"
+                               class="form-control">
+                    </div>
+                    {% endfor %}
+                </div>
             </div>
             {% endfor %}
         </div>
+        {% else %}
+        <div class="bg-gray-50 rounded-lg p-4">
+            <p class="text-sm text-gray-500 italic">No enabled plugins found &mdash; enable a plugin in the Plugin Manager to set its screen durations here.</p>
+        </div>
+        {% endif %}
 
         <!-- Submit Button -->
         <div class="flex justify-end">
@@ -43,3 +74,34 @@
         </div>
     </form>
 </div>
+
+<script>
+(function () {
+    // Shared drag-and-drop plugin list (static/v3/js/widgets/plugin-order-list.js,
+    // same module the Vegas Scroll section uses).
+    function initRotationOrderList(attempt) {
+        const container = document.getElementById('rotation_plugin_order');
+        if (!container) return;
+        if (!window.PluginOrderList) {
+            // Widget script is deferred; retry briefly, then surface a real
+            // error instead of showing "Loading…" forever.
+            if ((attempt || 0) < 50) {
+                setTimeout(function() { initRotationOrderList((attempt || 0) + 1); }, 100);
+            } else {
+                container.textContent = 'Could not load the reorder widget — reload the page to try again.';
+                container.className = 'text-sm text-red-500';
+            }
+            return;
+        }
+        window.PluginOrderList.init({
+            containerId: 'rotation_plugin_order',
+            orderInputId: 'rotation_plugin_order_value'
+        });
+    }
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', initRotationOrderList);
+    } else {
+        initRotationOrderList();
+    }
+}());
+</script>

web_interface/templates/v3/partials/general.html

@@ -49,6 +49,18 @@
             <label for="timezone" class="block text-sm font-medium text-gray-700">Timezone{{ ui.help_tip('Time zone used for clocks, schedules, and time-based content.\nChoose the zone where the display physically lives so on/off schedules fire at the correct local time.', 'Timezone') }}</label>
             <div id="timezone_container" class="mt-1"></div>
         </div>
+
+        <!-- Scroll frame rate (device-wide) -->
+        <div class="form-group" id="setting-general-target-fps" data-setting-key="target_fps">
+            <label for="target_fps" class="block text-sm font-medium text-gray-700">Scroll Frame Rate{{ ui.help_tip('Frames per second for scrolling content, applied across plugins that scroll.\nHigher is smoother but uses more CPU; lower frees CPU but looks steppier.\nRange 30-200. Default: 100.', 'Scroll Frame Rate') }}</label>
+            <input type="number"
+                   id="target_fps"
+                   name="target_fps"
+                   value="{{ main_config.target_fps or 100 }}"
+                   min="30"
+                   max="200"
+                   class="form-control">
+        </div>
         <script>
         (function() {
             // Track if already initialized to prevent re-render

web_interface/templates/v3/partials/logs.html

@@ -4,6 +4,17 @@
         <p class="mt-1 text-sm text-gray-600">View real-time logs from the LED matrix service for troubleshooting.</p>
     </div>
 
+    <!-- Currently displayed plugin -->
+    <div id="current-plugin-banner" class="hidden mb-4 flex items-center gap-2 text-sm bg-blue-50 border border-blue-200 text-blue-800 rounded-lg px-3 py-2">
+        <i class="fas fa-tv"></i>
+        <span>Now showing: <strong id="current-plugin-mode">-</strong>
+            <span id="current-plugin-id-wrap" class="hidden">(plugin: <code id="current-plugin-id" class="bg-blue-100 px-1 rounded"></code>)</span>
+        </span>
+        <button id="current-plugin-filter-btn" class="hidden ml-auto btn bg-blue-600 hover:bg-blue-700 text-white px-2 py-0.5 rounded text-xs">
+            Filter to this plugin
+        </button>
+    </div>
+
     <!-- Controls -->
     <div class="flex flex-wrap items-center justify-between gap-4 mb-6">
         <div class="flex items-center space-x-4">
@@ -27,6 +38,11 @@
                 <option value="INFO">Info & Above</option>
             </select>
 
+            <!-- Plugin Filter -->
+            <select id="log-plugin-filter" class="form-control text-sm">
+                <option value="">All Plugins</option>
+            </select>
+
             <!-- Search -->
             <div class="relative">
                 <input type="text" id="log-search" placeholder="Search logs..." class="form-control text-sm pl-8 pr-4 py-1 w-48">
@@ -139,6 +155,7 @@ window._filteredLogs = [];
     const realtimeToggle = document.getElementById('log-realtime-toggle');
     const refreshBtn = document.getElementById('refresh-logs-btn');
     const levelFilter = document.getElementById('log-level-filter');
+    const pluginFilter = document.getElementById('log-plugin-filter');
     const searchInput = document.getElementById('log-search');
     const autoscrollToggle = document.getElementById('log-autoscroll');
     const clearBtn = document.getElementById('clear-logs-btn');
@@ -160,6 +177,11 @@ window._filteredLogs = [];
         levelFilter.parentNode.replaceChild(newFilter, levelFilter);
         newFilter.addEventListener('change', filterLogs);
     }
+    if (pluginFilter) {
+        const newFilter = pluginFilter.cloneNode(true);
+        pluginFilter.parentNode.replaceChild(newFilter, pluginFilter);
+        newFilter.addEventListener('change', filterLogs);
+    }
     if (searchInput) {
         const newInput = searchInput.cloneNode(true);
         searchInput.parentNode.replaceChild(newInput, searchInput);
@@ -180,6 +202,24 @@ window._filteredLogs = [];
         downloadBtn.parentNode.replaceChild(newBtn, downloadBtn);
         newBtn.addEventListener('click', downloadLogs);
     }
+    const currentPluginFilterBtn = document.getElementById('current-plugin-filter-btn');
+    if (currentPluginFilterBtn) {
+        const newBtn = currentPluginFilterBtn.cloneNode(true);
+        currentPluginFilterBtn.parentNode.replaceChild(newBtn, currentPluginFilterBtn);
+        newBtn.addEventListener('click', function() {
+            const pluginFilterEl = document.getElementById('log-plugin-filter');
+            if (pluginFilterEl && window._currentPluginId) {
+                pluginFilterEl.value = window._currentPluginId;
+                filterLogs();
+            }
+        });
+    }
+
+    refreshCurrentPluginStatus();
+    if (window._currentPluginPollTimer) {
+        clearInterval(window._currentPluginPollTimer);
+    }
+    window._currentPluginPollTimer = setInterval(refreshCurrentPluginStatus, 5000);
 
     // Handle window resize for responsive height
     window.addEventListener('resize', function() {
@@ -284,37 +324,25 @@ function processLogs(logsText, append = false) {
         // Skip empty lines
         if (!line.trim()) return;
 
-        // Try to parse journalctl format: "MMM DD HH:MM:SS hostname service[pid]: message"
-        // Example: "Oct 13 14:23:45 raspberrypi ledmatrix[1234]: INFO: Starting display"
-        
+        // journalctl (--output=short-iso) emits: "YYYY-MM-DDTHH:MM:SS+ZZZZ hostname service[pid]: message"
+        // Example: "2024-01-15T10:23:45+0000 raspberrypi ledmatrix[1234]: INFO - plugin.nhl_scoreboard - [Plugin: nhl_scoreboard] Updated scores"
+        // Also accept the older syslog-style "MMM DD HH:MM:SS" timestamp for compatibility.
+
         let timestamp = '';
         let level = 'INFO';
         let message = line;
-        
-        // Extract timestamp (first part before hostname)
-        const timestampMatch = line.match(/^([A-Z][a-z]{2}\s+\d{1,2}\s+\d{2}:\d{2}:\d{2})/);
-        if (timestampMatch) {
-            timestamp = timestampMatch[1];
-            
-            // Find the message part (after service name and pid)
-            const messageMatch = line.match(/:\s*(.+)$/);
-            if (messageMatch) {
-                message = messageMatch[1];
-                
-                // Detect log level from message
-                if (message.match(/\b(ERROR|CRITICAL|FATAL)\b/i)) {
-                    level = 'ERROR';
-                } else if (message.match(/\b(WARNING|WARN)\b/i)) {
-                    level = 'WARNING';
-                } else if (message.match(/\bDEBUG\b/i)) {
-                    level = 'DEBUG';
-                } else if (message.match(/\bINFO\b/i)) {
-                    level = 'INFO';
-                }
-                
-                // Clean up level prefix from message if it exists
-                message = message.replace(/^(ERROR|WARNING|WARN|INFO|DEBUG):\s*/i, '');
-            }
+        let plugin = '';
+        let rest = null;
+
+        const isoMatch = line.match(/^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:[+-]\d{2}:?\d{2}|Z))\s+(.*)$/);
+        const syslogMatch = !isoMatch && line.match(/^([A-Z][a-z]{2}\s+\d{1,2}\s+\d{2}:\d{2}:\d{2})\s+(.*)$/);
+
+        if (isoMatch) {
+            timestamp = isoMatch[1];
+            rest = isoMatch[2];
+        } else if (syslogMatch) {
+            timestamp = syslogMatch[1];
+            rest = syslogMatch[2];
         } else {
             // If no timestamp, use current time
             timestamp = new Date().toLocaleString('en-US', {
@@ -327,14 +355,58 @@ function processLogs(logsText, append = false) {
             });
         }
 
+        if (rest !== null) {
+            // Find the message part (after hostname + service name/pid)
+            const messageMatch = rest.match(/:\s*(.+)$/);
+            if (messageMatch) {
+                message = messageMatch[1];
+
+                // Detect log level from message
+                if (message.match(/\b(ERROR|CRITICAL|FATAL)\b/i)) {
+                    level = 'ERROR';
+                } else if (message.match(/\b(WARNING|WARN)\b/i)) {
+                    level = 'WARNING';
+                } else if (message.match(/\bDEBUG\b/i)) {
+                    level = 'DEBUG';
+                } else if (message.match(/\bINFO\b/i)) {
+                    level = 'INFO';
+                }
+
+                // Clean up level prefix from message if it exists
+                message = message.replace(/^(ERROR|WARNING|WARN|INFO|DEBUG)\s*[-:]\s*/i, '');
+
+                // journalctl already carries its own timestamp; strip the app's
+                // internal "YYYY-MM-DD HH:MM:SS.mmm - LEVEL - logger.name - "
+                // prefix (see ContextualFormatter in src/logging_config.py) so
+                // it isn't duplicated in the displayed message.
+                message = message.replace(
+                    /^\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}(?:\.\d+)?\s*-\s*(ERROR|WARNING|WARN|INFO|DEBUG|CRITICAL)\s*-\s*[\w.]+\s*-\s*/i,
+                    ''
+                );
+
+                // Extract the "[Plugin: <id>]" context tag emitted by
+                // ContextualFormatter for every plugin logger (see
+                // src/logging_config.py PluginLoggerAdapter), and pull it out
+                // of the displayed message into its own field.
+                const pluginMatch = message.match(/^\[Plugin:\s*([^\]]+)\]\s*/);
+                if (pluginMatch) {
+                    plugin = pluginMatch[1].trim();
+                    message = message.replace(pluginMatch[0], '');
+                }
+            } else {
+                message = rest;
+            }
+        }
+
         const logEntry = {
             timestamp: timestamp,
             level: level,
+            plugin: plugin,
             message: message,
             raw: line,
             id: Date.now() + Math.random()
         };
-        
+
         // Don't add duplicate entries when appending
         if (!append || !window._allLogs.find(log => log.raw === line)) {
             window._allLogs.push(logEntry);
@@ -346,9 +418,26 @@ function processLogs(logsText, append = false) {
         window._allLogs = window._allLogs.slice(-window._MAX_LOGS);
     }
 
+    updatePluginFilterOptions();
     filterLogs();
 }
 
+function updatePluginFilterOptions() {
+    const pluginFilterEl = document.getElementById('log-plugin-filter');
+    if (!pluginFilterEl) return;
+
+    const previousValue = pluginFilterEl.value;
+    const plugins = Array.from(new Set(window._allLogs.map(log => log.plugin).filter(Boolean))).sort();
+
+    pluginFilterEl.innerHTML = '<option value="">All Plugins</option>' +
+        plugins.map(p => `<option value="${escapeHtml(p)}">${escapeHtml(p)}</option>`).join('');
+
+    // Restore previous selection if it's still a valid option
+    if (previousValue && plugins.includes(previousValue)) {
+        pluginFilterEl.value = previousValue;
+    }
+}
+
 function renderLogs() {
     if (window._filteredLogs.length === 0) {
         showEmptyState();
@@ -364,10 +453,14 @@ function renderLogs() {
     window._filteredLogs.forEach(log => {
         const logElement = document.createElement('div');
         logElement.className = `log-entry py-1 px-2 hover:bg-gray-800 rounded transition-colors duration-150 ${getLogLevelClass(log.level)}`;
+        const pluginBadge = log.plugin
+            ? `<span class="log-plugin flex-shrink-0 px-2 py-0.5 rounded text-xs font-semibold bg-purple-700 text-white" title="Plugin: ${escapeHtml(log.plugin)}">${escapeHtml(log.plugin)}</span>`
+            : '';
         logElement.innerHTML = `
             <div class="flex items-start gap-3 text-xs font-mono">
                 <span class="log-timestamp text-gray-400 flex-shrink-0 w-32">${escapeHtml(log.timestamp)}</span>
                 <span class="log-level flex-shrink-0 px-2 py-0.5 rounded text-xs font-semibold ${getLogLevelBadgeClass(log.level)}">${log.level}</span>
+                ${pluginBadge}
                 <span class="log-message flex-1 ${getLogLevelTextClass(log.level)} break-words">${escapeHtml(log.message)}</span>
             </div>
         `;
@@ -410,10 +503,12 @@ function getLogLevelTextClass(level) {
 
 function filterLogs() {
     const levelFilterEl = document.getElementById('log-level-filter');
+    const pluginFilterEl = document.getElementById('log-plugin-filter');
     const searchEl = document.getElementById('log-search');
     if (!levelFilterEl || !searchEl) return;
-    
+
     const levelFilter = levelFilterEl.value;
+    const pluginFilter = pluginFilterEl ? pluginFilterEl.value : '';
     const searchTerm = searchEl.value.toLowerCase();
 
     window._filteredLogs = window._allLogs.filter(log => {
@@ -430,8 +525,14 @@ function filterLogs() {
             }
         }
 
+        // Plugin filter
+        if (pluginFilter && log.plugin !== pluginFilter) {
+            return false;
+        }
+
         // Search filter
-        if (searchTerm && !log.message.toLowerCase().includes(searchTerm)) {
+        if (searchTerm && !log.message.toLowerCase().includes(searchTerm) &&
+            !(log.plugin && log.plugin.toLowerCase().includes(searchTerm))) {
             return false;
         }
 
@@ -617,10 +718,45 @@ function escapeHtml(text) {
     return div.innerHTML;
 }
 
+function refreshCurrentPluginStatus() {
+    fetch('/api/v3/display/current-status')
+        .then(response => response.json())
+        .then(data => {
+            if (data.status !== 'success' || !data.data) return;
+            const state = data.data;
+            const banner = document.getElementById('current-plugin-banner');
+            const modeEl = document.getElementById('current-plugin-mode');
+            const idWrap = document.getElementById('current-plugin-id-wrap');
+            const idEl = document.getElementById('current-plugin-id');
+            const filterBtn = document.getElementById('current-plugin-filter-btn');
+            if (!banner || !modeEl) return;
+
+            window._currentPluginId = state.plugin_id || null;
+
+            modeEl.textContent = state.mode || 'unknown';
+            if (state.plugin_id) {
+                idEl.textContent = state.plugin_id;
+                idWrap.classList.remove('hidden');
+                if (filterBtn) filterBtn.classList.remove('hidden');
+            } else {
+                idWrap.classList.add('hidden');
+                if (filterBtn) filterBtn.classList.add('hidden');
+            }
+            banner.classList.remove('hidden');
+        })
+        .catch(() => {
+            // Silently ignore - banner just stays hidden/stale
+        });
+}
+
 // Cleanup on page unload
 window.addEventListener('beforeunload', function() {
     if (window._logsEventSource) {
         window._logsEventSource.close();
     }
+    if (window._currentPluginPollTimer) {
+        clearInterval(window._currentPluginPollTimer);
+        window._currentPluginPollTimer = null;
+    }
 });
 </script>

web_interface/templates/v3/partials/overview.html

@@ -61,6 +61,149 @@
 }());
 </script>
 
+<!-- Getting Started checklist: non-gating, dismissible (localStorage), items
+     auto-check from existing config/endpoints — no new persisted state.
+     Known heuristic limits (acceptable, disclosed): values left at legitimate
+     defaults (e.g. a user actually in Tampa) read as "not done". -->
+{% set _hw = main_config.display.hardware if main_config and main_config.display else {} %}
+{% set _hw_done = (_hw.rows or 0) > 0 and (_hw.cols or 0) > 0 and (_hw.chain_length or 0) > 0 %}
+{% set _loc = main_config.location if main_config and main_config.location else {} %}
+{% set _loc_done = (main_config.timezone and main_config.timezone != 'America/New_York')
+                   or (_loc.city and _loc.city != 'Tampa') %}
+<div id="getting-started-card" class="bg-blue-50 border border-blue-200 rounded-lg p-4 mb-4" style="display:none" role="region" aria-label="Getting started checklist">
+    <div class="flex items-start justify-between">
+        <div class="flex-1">
+            <p class="text-sm font-semibold text-blue-900"><i class="fas fa-rocket mr-1"></i>Getting Started</p>
+            <p class="text-xs text-blue-700 mt-0.5 mb-2">A few steps to get your display up and running. Click a step to jump there, or click its checkbox to mark it done yourself. The card hides once everything is checked.</p>
+            <ul class="space-y-1 text-sm" id="getting-started-items">
+                <li><button type="button" class="gs-item text-left w-full" data-done="{{ '1' if _hw_done else '0' }}" data-tab="display">
+                    <i class="far fa-square mr-2"></i>Set your panel size (Display tab)</button></li>
+                <li><button type="button" class="gs-item text-left w-full" data-done="{{ '1' if _loc_done else '0' }}" data-tab="general">
+                    <i class="far fa-square mr-2"></i>Set your timezone and location (General tab)</button></li>
+                <li><button type="button" class="gs-item text-left w-full" data-done="0" data-check="installed" data-tab="plugins">
+                    <i class="far fa-square mr-2"></i>Install a plugin from the Plugin Store</button></li>
+                <li><button type="button" class="gs-item text-left w-full" data-done="0" data-check="enabled" data-tab="plugins">
+                    <i class="far fa-square mr-2"></i>Enable a plugin</button></li>
+                <li><button type="button" class="gs-item text-left w-full" data-done="0" data-check="configured" data-tab="plugins">
+                    <i class="far fa-square mr-2"></i>Configure it (each plugin gets its own tab)</button></li>
+            </ul>
+        </div>
+        <button type="button" onclick="window.dismissGettingStarted()" class="ml-4 flex-shrink-0 text-blue-400 hover:text-blue-600" aria-label="Dismiss getting started checklist">
+            <i class="fas fa-times"></i>
+        </button>
+    </div>
+</div>
+<script>
+(function () {
+    var KEY = 'ledmatrix-getting-started-dismissed';
+    var MANUAL_KEY = 'ledmatrix-getting-started-manual';
+    var card = document.getElementById('getting-started-card');
+    if (!card) return;
+    try { if (localStorage.getItem(KEY) === '1') return; } catch (e) {}
+    card.style.display = 'block';
+
+    // Manual per-item overrides: the auto-detection is heuristic (a value
+    // saved AT its default — e.g. a user genuinely in the default timezone —
+    // reads as "not done"), so clicking an item's checkbox marks it done by
+    // hand, persisted per browser.
+    var manual = {};
+    try { manual = JSON.parse(localStorage.getItem(MANUAL_KEY) || '{}') || {}; } catch (e) {}
+    function saveManual() {
+        try { localStorage.setItem(MANUAL_KEY, JSON.stringify(manual)); } catch (e) {}
+    }
+
+    function setDone(btn, done) {
+        btn.dataset.done = done ? '1' : '0';
+        var icon = btn.querySelector('i');
+        if (icon) { icon.className = done ? 'fas fa-check-square mr-2 text-green-600' : 'far fa-square mr-2'; }
+        btn.classList.toggle('text-gray-500', done);
+        btn.classList.toggle('line-through', done);
+    }
+
+    // Once every step is done (auto-detected or manually checked), the card
+    // has served its purpose — hide it without requiring an explicit dismiss.
+    function maybeAutoHide() {
+        var items = card.querySelectorAll('.gs-item');
+        for (var i = 0; i < items.length; i++) {
+            if (items[i].dataset.done !== '1') return;
+        }
+        card.style.display = 'none';
+    }
+
+    function markDone(btn) {
+        if (!btn) return;
+        setDone(btn, true);
+        maybeAutoHide();
+    }
+
+    // Apply server-derived + manual states, wire deep links (same app-data
+    // access pattern as settings-search.js). Clicking the checkbox icon
+    // toggles manual done; clicking the text deep-links to the tab.
+    Array.prototype.forEach.call(card.querySelectorAll('.gs-item'), function (btn, idx) {
+        if (manual[idx] === 1) btn.dataset.done = '1';
+        if (btn.dataset.done === '1') setDone(btn, true);
+        btn.addEventListener('click', function (ev) {
+            var icon = btn.querySelector('i');
+            if (icon && ev.target === icon) {
+                var nowDone = btn.dataset.done !== '1';
+                setDone(btn, nowDone);
+                manual[idx] = nowDone ? 1 : 0;
+                saveManual();
+                if (nowDone) maybeAutoHide();
+                return;
+            }
+            var appEl = document.querySelector('[x-data="app()"]') || document.querySelector('[x-data]');
+            // Same two-tier resolution as settings-search.js's getAppData():
+            // _x_dataStack on current Alpine, __x.$data as an older-API fallback.
+            var data = appEl && ((appEl._x_dataStack && appEl._x_dataStack[0]) ||
+                                  (appEl.__x && appEl.__x.$data));
+            if (data) {
+                data.activeTab = btn.dataset.tab;
+                if ('mobileNavOpen' in data) data.mobileNavOpen = false;
+            }
+        });
+    });
+    maybeAutoHide();
+
+    // Plugin-derived states from the existing installed-plugins endpoint.
+    fetch('/api/v3/plugins/installed')
+        .then(function (r) { return r.json(); })
+        .then(function (resp) {
+            var plugins = (resp.data && resp.data.plugins) || [];
+            if (plugins.length > 0) markDone(card.querySelector('[data-check="installed"]'));
+            var enabled = plugins.filter(function (p) { return p.enabled; });
+            if (enabled.length > 0) {
+                markDone(card.querySelector('[data-check="enabled"]'));
+                // "Configured" heuristic: the first enabled plugin has at least
+                // one saved value that differs from its schema defaults.
+                var pid = enabled[0].id;
+                Promise.all([
+                    fetch('/api/v3/plugins/config?plugin_id=' + encodeURIComponent(pid)).then(function (r) { return r.json(); }),
+                    fetch('/api/v3/plugins/schema?plugin_id=' + encodeURIComponent(pid)).then(function (r) { return r.json(); })
+                ]).then(function (res) {
+                    // GET /plugins/config returns the config dict directly in .data
+                    var cfg = res[0].data || {};
+                    var props = (res[1].data && res[1].data.schema && res[1].data.schema.properties) || {};
+                    for (var k in cfg) {
+                        if (k === 'enabled' || !(k in props)) continue;
+                        if (props[k] && 'default' in props[k] &&
+                            JSON.stringify(cfg[k]) !== JSON.stringify(props[k]['default'])) {
+                            markDone(card.querySelector('[data-check="configured"]'));
+                            return;
+                        }
+                    }
+                }).catch(function () {});
+            }
+        })
+        .catch(function () {});
+
+    window.dismissGettingStarted = function () {
+        card.style.display = 'none';
+        try { localStorage.setItem(KEY, '1'); } catch (e) {}
+    };
+}());
+</script>
+
 <div class="bg-white rounded-lg shadow p-6">
     <div class="border-b border-gray-200 pb-4 mb-6">
         <h2 class="text-lg font-semibold text-gray-900">System Overview</h2>
@@ -221,7 +364,10 @@
         <h3 class="text-md font-medium text-gray-900 mb-4">
             <i class="fas fa-desktop"></i> Live Display Preview
         </h3>
-        <div class="bg-gray-900 rounded-lg p-6 border border-gray-700" style="position: relative;">
+        <!-- overflow-x-auto: on narrow screens a wide preview scrolls at its
+             true pixel-perfect size instead of being squeezed (fractional
+             downscaling of pixel art reads as blur) -->
+        <div class="bg-gray-900 rounded-lg p-6 border border-gray-700 overflow-x-auto" style="position: relative;">
             <div id="previewStage" class="preview-stage" style="display:none; position:relative; display:inline-block;">
                 <div id="previewMeta" style="position:absolute; top:-28px; left:0; color:#ddd; font-size:12px; opacity:0.85;"></div>
                 <img id="displayImage" style="image-rendering: pixelated; display: block;" alt="LED Matrix Display">

web_interface/templates/v3/partials/plugin_config.html

@@ -893,6 +893,12 @@
                 <p class="mt-1 text-sm text-gray-600">{{ plugin.description or 'Plugin configuration' }}</p>
             </div>
             <div class="flex items-center space-x-4">
+                <button type="button"
+                        onclick="window.previewPluginNow('{{ plugin.id }}')"
+                        class="btn bg-blue-600 hover:bg-blue-700 text-white px-3 py-1.5 text-sm rounded-md"
+                        title="Run this plugin on the display for 60 seconds and open the live preview">
+                    <i class="fas fa-play mr-1"></i>Preview on display
+                </button>
                 <label class="flex items-center cursor-pointer">
                     <input type="checkbox"
                            id="plugin-enabled-{{ plugin.id }}"
@@ -1005,13 +1011,53 @@
                         {# Use property order if defined, otherwise use natural order #}
                         {# Skip 'enabled' field - it's handled by the header toggle #}
                         {% set property_order = schema['x-propertyOrder'] if 'x-propertyOrder' in schema else schema.properties.keys()|list %}
+                        {# Flat (non-object) properties flagged "x-advanced": true are
+                           grouped into one collapsed "Advanced Settings" section after
+                           the basic fields. Object-type properties already render as
+                           their own collapsible sections, so the flag is ignored for
+                           them. Schemas without the flag render exactly as before. #}
+                        {% set tiers = namespace(basic=[], advanced=[]) %}
                         {% for key in property_order %}
                             {% if key in schema.properties and key != 'enabled' %}
                                 {% set prop = schema.properties[key] %}
-                                {% set value = config[key] if key in config else none %}
-                                {{ render_field(key, prop, value, '', plugin.id) }}
+                                {% set is_object = prop.type is defined and 'object' in prop.type %}
+                                {% if prop.get('x-advanced') and not is_object %}
+                                    {% set tiers.advanced = tiers.advanced + [key] %}
+                                {% else %}
+                                    {% set tiers.basic = tiers.basic + [key] %}
+                                {% endif %}
                             {% endif %}
                         {% endfor %}
+                        {% for key in tiers.basic %}
+                            {% set prop = schema.properties[key] %}
+                            {% set value = config[key] if key in config else none %}
+                            {{ render_field(key, prop, value, '', plugin.id) }}
+                        {% endfor %}
+                        {% if tiers.advanced %}
+                            {% set adv_section_id = (plugin.id ~ '-section-advanced-settings')|replace('.', '-')|replace('_', '-') %}
+                            <div class="nested-section border border-gray-300 rounded-lg mb-4">
+                                <button type="button"
+                                        class="w-full bg-gray-100 hover:bg-gray-200 px-4 py-3 flex items-center justify-between text-left transition-colors rounded-t-lg"
+                                        aria-controls="{{ adv_section_id }}"
+                                        aria-expanded="false"
+                                        onclick="toggleSection('{{ adv_section_id }}')">
+                                    <div class="flex-1">
+                                        <h4 class="font-semibold text-gray-900">
+                                            <i class="fas fa-sliders-h mr-1 text-gray-500"></i>Advanced Settings ({{ tiers.advanced|length }})
+                                        </h4>
+                                        <p class="text-sm text-gray-600 mt-1">Optional fine-tuning — the defaults work for most setups.</p>
+                                    </div>
+                                    <i id="{{ adv_section_id }}-icon" class="fas fa-chevron-right text-gray-500 transition-transform"></i>
+                                </button>
+                                <div id="{{ adv_section_id }}" class="nested-content bg-gray-50 px-4 py-4 space-y-3 hidden" style="display: none;">
+                                    {% for key in tiers.advanced %}
+                                        {% set prop = schema.properties[key] %}
+                                        {% set value = config[key] if key in config else none %}
+                                        {{ render_field(key, prop, value, '', plugin.id) }}
+                                    {% endfor %}
+                                </div>
+                            </div>
+                        {% endif %}
                     {% else %}
                         {# No schema - render simple form from config #}
                         {% if config %}

web_interface/templates/v3/partials/plugins.html

@@ -466,65 +466,6 @@
     </div>
     </div>
 
-    <!-- Plugin Configuration Modal -->
-    <div id="plugin-config-modal" class="fixed inset-0 modal-backdrop flex items-center justify-center z-50" style="display: none;">
-        <div class="modal-content p-6 w-full max-w-4xl max-h-[90vh] overflow-y-auto">
-            <div class="flex justify-between items-center mb-4">
-                <h3 id="plugin-config-title" class="text-lg font-semibold">Plugin Configuration</h3>
-                <div class="flex items-center space-x-2">
-                    <!-- View Toggle -->
-                    <div class="flex items-center bg-gray-100 rounded-lg p-1">
-                        <button id="view-toggle-form" class="view-toggle-btn active px-3 py-1 rounded text-sm font-medium transition-colors" data-view="form">
-                            <i class="fas fa-list mr-1"></i>Form
-                        </button>
-                        <button id="view-toggle-json" class="view-toggle-btn px-3 py-1 rounded text-sm font-medium transition-colors" data-view="json">
-                            <i class="fas fa-code mr-1"></i>JSON
-                        </button>
-                    </div>
-                    <!-- Reset Button -->
-                    <button id="reset-to-defaults-btn" class="px-3 py-1 text-sm bg-yellow-500 hover:bg-yellow-600 text-white rounded transition-colors" title="Reset to defaults">
-                        <i class="fas fa-undo mr-1"></i>Reset
-                    </button>
-                    <button id="close-plugin-config" class="text-gray-400 hover:text-gray-600">
-                        <i class="fas fa-times"></i>
-                    </button>
-                </div>
-            </div>
-            <!-- Validation Errors Display -->
-            <div id="plugin-config-validation-errors" class="hidden mb-4 p-3 bg-red-50 border border-red-200 rounded-md">
-                <div class="flex items-start">
-                    <i class="fas fa-exclamation-circle text-red-600 mt-0.5 mr-2"></i>
-                    <div class="flex-1">
-                        <p class="text-sm font-medium text-red-800 mb-2">Configuration Validation Errors</p>
-                        <ul id="validation-errors-list" class="text-sm text-red-700 list-disc list-inside space-y-1"></ul>
-                    </div>
-                </div>
-            </div>
-            <!-- Form View -->
-            <div id="plugin-config-form-view" class="plugin-config-view">
-                <div id="plugin-config-content">
-                    <!-- Plugin config form will be loaded here -->
-                </div>
-            </div>
-            <!-- JSON Editor View -->
-            <div id="plugin-config-json-view" class="plugin-config-view hidden">
-                <div class="mb-2">
-                    <label class="block text-sm font-medium text-gray-700 mb-1">Configuration JSON</label>
-                    <textarea id="plugin-config-json-editor" class="w-full border border-gray-300 rounded-md font-mono text-sm" rows="20"></textarea>
-                </div>
-                <div class="flex justify-end space-x-2 pt-2 border-t border-gray-200">
-                    <button type="button" onclick="closePluginConfigModal()" class="btn bg-gray-600 hover:bg-gray-700 text-white px-4 py-2 rounded-md">
-                        Cancel
-                    </button>
-                    <button type="button" id="save-json-config-btn" class="btn bg-blue-600 hover:bg-blue-700 text-white px-4 py-2 rounded-md">
-                        <i class="fas fa-save mr-2"></i>Save Configuration
-                    </button>
-                </div>
-            </div>
-        </div>
-    </div>
-</div>
-
 <!-- On-Demand Modal moved to base.html so it's always available -->
 
 <style>