refactor(ui): load the capabilities as ES modules (R3a)

The 12 capability <script> tags become type="module". No JS changes — the
capability scripts already self-register on the window.feedBack bus,
version-negotiate (`capabilities.version !== 1` → bail), and self-guard for
idempotency. They never import or call app.js; it is pure pub/sub.

Verified they export nothing by name: no top-level declaration in
capabilities.js or capabilities/*.js is read by any other script, so losing
global scope costs nothing.

This is the first REAL exercise of the ordering fix from #872. A module defers to
after HTML parse, so the capabilities now execute AFTER the document is parsed —
while app.js still calls `window.feedBack.on(...)` at its top level. That only
works because #872 put every classic script into the same deferred queue, where
document order IS execution order: capabilities.js (line 122) still runs before
app.js (line 1237). Had app.js stayed a plain classic script it would have run
during parse, hit a bare `{}`, and died on `.on is not a function`.

A/B against origin/main, 11 probes — capabilities.version, registered
participants (37), compatibility shims (14), the bus, workingTuning, theme,
setViz/showScreen/playSong, mounted plugin screens: IDENTICAL, zero console/page
errors on both. 12 module tags served and executed; pytest 2396, node 1032/1032,
ESLint 0, Codex 0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.specify/memory/constitution.md

@@ -34,7 +34,7 @@ but not the primary supported path.
 
 ### II. Vanilla Frontend — No Frameworks
 
-The frontend (`static/app.js`, `static/highway.js`, `static/index.html`,
+The frontend (`static/app.js`, `static/highway.js`, `static/v3/index.html`,
 `static/style.css`) is plain JavaScript with the `fetch` API, direct DOM
 manipulation, and the Canvas 2D / WebGL2 APIs. The only style framework
 is Tailwind CSS, served as a prebuilt static stylesheet
@@ -284,4 +284,4 @@ no `..`, no absolute paths).
   higher-numbered principle's escape hatch is to live in a plugin
   with its own bundled assets.
 
-**Version**: 1.2.0 | **Ratified**: 2026-05-09 | **Last Amended**: 2026-07-08
+**Version**: 1.3.0 | **Ratified**: 2026-05-09 | **Last Amended**: 2026-07-11

CHANGELOG.md

@@ -7,6 +7,102 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Removed
+- **The classic v2 UI shell is gone — v3 is the only UI (R3a).** `static/index.html`, the
+  `/v2` route, and the `FEEDBACK_UI` v2/legacy opt-out are deleted; `/` and `/v3` both serve
+  `static/v3/index.html`, which has been the default since 0.3.0. This is the first step of
+  the core-frontend ES-module migration (R3a): both shells load the same `static/app.js`, so
+  every subsequent step of that migration would otherwise have to be made, and verified,
+  twice. Removing the fallback now halves that surface before any of it is touched.
+  Incidentally fixes a latent bug in the old `index()` route — its guard read
+  `if getenv_compat("FEEDBACK_UI") or getenv_compat("FEEDBACK_UI") in ("v2", "legacy")`,
+  whose left operand is truthy for *any* non-empty value, so `FEEDBACK_UI=v3` actually served
+  the **v2** shell. `static/tailwind.min.css` is regenerated (the content globs scanned the
+  deleted file, so v2-only utility classes are now purged). Constitution amended to 1.3.0:
+  Principle II's frontend file list now names `static/v3/index.html`.
+  **Migration notes:** if you set `FEEDBACK_UI=v2` (or `=legacy`), or bookmarked `/v2`, there
+  is no longer a classic shell to fall back to — unset the variable and use `/`. The env var
+  itself is no longer read; the `SLOPSMITH_*`→`FEEDBACK_*` compat shim is unaffected. No
+  chart, settings, or plugin data changes, and no plugin API changes: v3 reuses the same
+  engine (`app.js`, `highway.js`, `playSong`, `showScreen`, the capability registry).
+
+### Fixed
+- **The packaged desktop app could not start (`ModuleNotFoundError: No module named
+  'appstate'`).** feedback-desktop's `scripts/bundle-slopsmith.sh` copies a *hardcoded
+  list* of core files into the app bundle — `server.py`, `VERSION`, `lib/`, `data/`,
+  `static/`, `plugins/__init__.py`. The root-level `appstate.py` and `routers/` added in
+  R3 shipped correctly in Docker and passed every test, and were then silently dropped
+  from the packaged app, which died at startup. Both now live under **`lib/`** — the one
+  core directory the Dockerfile (`COPY lib/`), `docker-compose.yml`, and the desktop
+  bundler (`cp -r lib`) all copy wholesale, and that all three put on `sys.path` (on
+  Windows via the embeddable-Python `._pth`, where `PYTHONPATH` is ignored). This needs no
+  change in feedback-desktop and no new release to take effect. Placing them there is also
+  correct under Principle V: with the injection seam, `appstate.py` constructs nothing and
+  does no import-time IO, and a route module only builds an `APIRouter`. The
+  `Dockerfile` / `.dockerignore` / `docker-compose.yml` entries added for the root layout
+  are reverted. New `tests/test_packaging.py` walks `server.py`'s module-level imports and
+  fails if any first-party module resolves outside a directory the packagers copy, so the
+  next root-level module can't ship broken.
+
+### Added
+- **Perf harness now measures 2D-highway frame time (R3c gate).** `scripts/perf-baseline.mjs` gains a `--song` mode that reports per-frame draw-cost p50/p95/p99 (draw-tagged via `highway.addDrawHook`), the metric that gates the `highway.js` split. Maintainer/CI-only; baseline recorded in `docs/perf-baseline.md`.
+- **`routers/` — extracting `server.py`'s route layer, cheapest-first (R3).** Each PR moves a cohesive route group into a `fastapi.APIRouter` under `lib/routers/`, mounted with `app.include_router(...)` at its original site (FastAPI matches in registration order; the full route table stays byte-identical). Bodies are verbatim — only the decorator receiver (`@app` → `@router`) and singleton reads (`meta_db` → `appstate.meta_db`, resolved at call time) change. So far: `audio_effects` (5), `artist_aliases` (5), `loops` (3), `playlists` (12 + covers), `ws_highway` (the 902-line highway chart WebSocket), `chart` (split/unsplit/work/fileinfo — unblocked by the DLC-path substrate), `library_extras`, `wanted`, `shop`, `progression`, `profile`, `stats` (the `/api/stats/{path}` catch-all stays registered last so it can't shadow `/recent` `/best` `/top`), `version` (`/api/version`; VERSION-file lookup adjusted for the router subdir depth), `art` (the `/api/song/{f}/art*` serve/cover-search/candidates/upload/url + `/api/art/{f}/override` routes; the shared `_song_pack_art_exists`/`_art_override_paths`/`_art_safe_name` helpers stay in `server.py` for the song/delete routes and are reached through the `appstate` seam, the CAA/release transport as `enrichment.X`), and `settings` (`GET`/`POST /api/settings`, `/reset`, and the two-phase atomic export/import bundle `/api/settings/export|import`; the shared `_default_settings` builder stays in `server.py` and is reached through the `appstate` seam), and `song` (upload/delete + the metadata write-back, user-meta, overrides, gap-fill, and per-song info routes; the scan/ingest helpers stay in `server.py` and are reached through new `appstate` seams — `kick_scan`, `invalidate_song_caches`, `stat_for_cache`, and a `scan_status()` getter — the `get_song_info` catch-all mounts after the art routes so it can't shadow them), and `library` + collections (the provider list/art/sync endpoints, the library query surface, and collection CRUD → `lib/routers/library.py`; the `LibraryProviderRegistry`/`LocalLibraryProvider`/`SmartCollectionProvider` classes + shared query/collection helpers move to `lib/library_registry.py`, and the registry instance + local provider ride the `appstate` seam — server.py still constructs the singleton and exposes `register_library_provider`/`unregister_library_provider` to plugins via `plugin_context` unchanged), and the `enrichment` route handlers (`/api/enrichment/*`: status, kick/cancel, per-song state, the Match-Review queue, and AcoustID identify → `lib/routers/enrichment.py`; the engine already lives in `lib/enrichment.py` and is reached as `enrichment.X`), and `media` (the file-serving routes — song audio `/audio/{f}`, the local-audio-path resolver `/api/audio-local-path`, and raw sloppak-member serving `/api/sloppak/{f}/file/{rel}` → `lib/routers/media.py`; the cache/static path seams were already in `appstate`), and `artist` (the artist page + external-links payload `/api/artist/{name}/page|links|links/refresh` → `lib/routers/artist.py`; MB link enrichment reached as `enrichment.X`), and `diagnostics` (`/api/diagnostics/export|preview|hardware`; the plugins-root lookup adjusted for the router subdir depth, `_running_version` reached through the `appstate` seam, pure payload-cap helpers re-exported for the `server._diag_*` tests), and `tunings` (`/api/tunings`; the pure `config.json` reader moved to `lib/appconfig.py`, the tuning-provider registry read through the `appstate` seam so plugin-contributed tunings still merge). The DLC library-path resolution (`_get_dlc_dir`, pure `_resolve_dlc_path`) moved to `lib/dlc_paths.py`, reading paths through the seam; `config_dir`/`dlc_dir`/`dlc_dir_env` now ride the `appstate` seam (env-derived, so the pop-and-reimport fixtures reconfigure it for free), and the shared request-field sanitizer `_clean_str` moved to `lib/reqfields.py`. The next cut is picked by a dependency-closure scan that ranks groups by how many `monkeypatch.setattr(server, …)` targets they'd drag along.
+- **`routers/` — the first extracted route module (R3).** The five audio-effects mapping
+  endpoints move out of `server.py` into `lib/routers/audio_effects.py` as a
+  `fastapi.APIRouter`, mounted with `app.include_router(...)` **at the point in the file
+  where they used to be defined** — FastAPI matches routes in registration order, so the
+  mount site preserves it. Verified: the full 143-route table (paths, methods, *and*
+  order) is byte-for-byte identical to `main`. Bodies are verbatim; the only edits are
+  the decorator receiver (`@app.get` → `@router.get`) and the singleton read
+  (`audio_effect_mappings` → `appstate.audio_effect_mappings`, a module attribute
+  resolved at call time). This proves the seam from #833 under a real consumer, including
+  the second slot. The `_demo_mode_guard` middleware still blocks all four moved write
+  routes with 403, and `Query(...)` validation still 422s — both checked against a running
+  server. `server.py`: **9,445 → 9,386 lines**.
+- **`lib/enrichment.py` — the metadata-enrichment subsystem leaves `server.py` (R3, move-only).** MusicBrainz / Cover-Art-Archive / AcoustID transport, the match-scorer glue, and the background enrichment worker (~930 lines, 61 defs) move out as one cohesive unit. Bodies are verbatim; the only changes are seam reads — `meta_db`/`config_dir`/`sloppak_cache_dir`/`art_cache_dir` and the two shared art helpers (`song_pack_art_exists`, `art_override_paths`, which stay in `server.py` for the art/delete routes) are reached through `appstate` at call time, and the User-Agent VERSION lookup is corrected for the module's new depth. `server.py` drives the worker through the module (`import enrichment`; the routes + scan lifecycle call `enrichment.X`); tests that faked the network on `server` now patch the same names on `enrichment` (module attribute resolved at call time, so one `setattr` reaches both the routes and the worker's internal callers). Acyclic — `enrichment` imports no `server`. Route table byte-identical; full suite green. `server.py`: 6,917 → 5,988.
+- **`appstate.py` — the router seam (R3).** Route modules moving out of `server.py`
+  need `meta_db` and friends but must not `import server`, or the import graph goes
+  circular the moment `server` imports them back. So `server.py` keeps *constructing*
+  its singletons and now **injects** them once — `appstate.configure(meta_db=…,
+  audio_effect_mappings=…)` — and a router reads them back as module attributes at call
+  time (`import appstate; appstate.meta_db.…`). This is the Python analogue of the
+  frontend refactor's injected `configureX({…})` seams and of the plugin
+  `setup(app, context)` contract: dependencies flow one way, `server → routers →
+  appstate`. Two properties are load-bearing and pinned by `tests/test_appstate.py`:
+  (1) `import appstate` constructs nothing and touches no disk, so the ~49 test fixtures
+  that `sys.modules.pop("server")` + re-import (to rebuild `meta_db` under a patched
+  `CONFIG_DIR`) keep working untouched — a singleton *owned* by `appstate` would survive
+  that pop and go stale; (2) reads must be late-bound (`appstate.meta_db`, never
+  `from appstate import meta_db`), since a `from` import freezes the binding and defeats
+  both a later `configure()` and `monkeypatch.setattr` — the same read-only-binding trap
+  as ES `import`. `configure()` rejects an unknown slot rather than silently creating a
+  global nothing reads, and the suite asserts `server` actually calls it (a seam whose
+  wiring can no-op undetected is worse than no seam). Lives at `lib/appstate.py`.
+
+### Changed
+- **`AudioEffectsMappingDB` moved out of `server.py` into `lib/audio_effects_db.py`
+  (R3, move-only).** The core-owned song/tone → provider routing index follows
+  `MetadataDB` out of the host file, byte-identical apart from the same constructor
+  seam (`__init__` takes `config_dir`; `audio_effect_mappings = AudioEffectsMappingDB(CONFIG_DIR)`),
+  so the module does no IO at import. The singleton stays in `server.py`; no route,
+  no test and no `monkeypatch.setattr(server, …)` target moves. `server.py`:
+  **9,705 → 9,433 lines**.
+- **`MetadataDB` moved out of `server.py` into `lib/metadata_db.py` (R3, move-only).**
+  The library metadata cache — the `MetadataDB` class (4,018 lines) plus the query
+  helpers it owns (keyset paging cursors, the tuning grouping key, smart-arrangement
+  naming, tag normalisation, the startup DB-restore swap) — now lives in its own flat
+  `lib/` module. `server.py` drops from **14,037 → 9,705 lines** and keeps the
+  `meta_db` singleton, so `server.meta_db` and `server.app` resolve exactly as before
+  and every route is untouched. The only non-verbatim change is the seam that lets the
+  class leave `server.py`: `MetadataDB.__init__` now takes `config_dir` explicitly
+  (`meta_db = MetadataDB(CONFIG_DIR)`) instead of reading the module-level `CONFIG_DIR`,
+  which also means `lib/metadata_db.py` performs no IO at import (Principle V). Logging
+  still goes through the `feedBack.server` logger, so existing log filters and `caplog`
+  assertions resolve to the same logger object. `tests/test_settings_export_library_db.py`
+  now imports `_apply_pending_db_restore` from `metadata_db` (the test moved with its
+  subject); no other test changed. Every moved block is byte-identical to its
+  `server.py` original.
+
 ### Added
 - **Plugins can ship an ES-module `src/` tree (module-migration rails, R0).** The host gains three things so a plugin can move off a single global-scope `screen.js` IIFE onto native ES modules with **no build step**: (1) a new sandboxed `GET /api/plugins/{id}/src/{path}` route that serves a plugin's `src/` source subtree, containment-checked by the same `safe_join` guard as `assets/` (traversal/absolute/NUL → 404); (2) the live-edit cache contract — `Cache-Control: no-cache` + a weak mtime/size `ETag` + `If-None-Match`→`304` — applied to `src/`, `screen.js`, and `assets/` (previously `screen.js` sent no cache headers and `assets/` emitted an ETag but never revalidated), so an edited module reloads on refresh while unchanged ones `304`; and (3) `scriptType`/`minHost` passthrough from `plugin.json` to `/api/plugins`, with the loader injecting a plugin that declares `"scriptType":"module"` as `<script type="module">` (its screen.js becomes `import './src/main.js'`). A `<script type=module>` fires its load event only after its whole static-import graph evaluates, preserving the loader's completion-by-`onload` + `_loadingPluginId` contract. Classic plugins are unaffected; `minHost` is passthrough-only for now (enforcement deferred). Tests: `tests/test_plugin_src_route.py` (serve/media-type/traversal/304/no-stale-304/screen.js+assets conditional), `tests/js/plugin_loader_script_type.test.js` (guarded module injection).
 - **Module-migration governance & rails (R0).** Constitution amended to **v1.2.0**: Principle II now names native ES modules as a first-class, *build-free* extension mechanism (the `scriptType:"module"` load path, both plugins and — over time — core's `static/js/`), keeping the no-bundler/no-transpiler/source-served rule intact; Operating Constraints gains a "Module load contract" clause (a `<script type=module>` load event awaits the whole static-import graph, so completion-by-`onload` is preserved; per-visit re-init comes from the `screen:changed` event, not screen.js re-execution). Mirrored into `CLAUDE.md`. New `docs/plugin-modules.md` (the migration playbook — layering, import-time purity, `import.meta.url` assets, the ETag live-edit loop) and `docs/size-exemptions.md` (the signed 1,500-line size-norm register; Byron signs core/bundled rows, Christian the authored virtuoso row). Adds a **maintainer/CI-only** ESLint gate (`eslint.config.js` + a `lint` CI job): `max-lines` warns at 1,500 as a non-blocking ratchet (ceilings for exempt files mirror the register), and `import-x/no-unresolved` + `import-x/no-cycle` hard-error on ES-module graphs — dormant until module code lands, never on the serve/Docker path.

CLAUDE.md

@@ -125,13 +125,13 @@ Notes:
 
 ### v3 UI (fee[dB]ack v0.3.0) — player-chrome contract
 
-v0.3.0 ships a redesigned UI behind a flag (`FEEDBACK_UI=v3` or the `/v3` route);
-the classic UI (v2) stays the default until 0.3.0 ships, so **plugins must work in
-both**. v3 reuses the same engine (`server.py`, `app.js`, `highway.js`, `playSong`,
+v0.3.0's redesigned UI is **the only UI** — the classic v2 shell and its
+`FEEDBACK_UI` / `/v2` opt-outs are gone, so there is no second shell to support.
+v3 reuses the same engine (`server.py`, `app.js`, `highway.js`, `playSong`,
 `showScreen`, capabilities, library providers, the `window.feedBackViz_<id>` /
 `setRenderer` contract), so a plugin's **backend, capabilities, `nav`/`screen`,
 visualization renderers, diagnostics, and settings export work unchanged** — v3
-surfaces `nav` in its sidebar and mounts screens exactly as v2 does.
+surfaces `nav` in its sidebar and mounts screens as before.
 
 **The only thing that changed is the player chrome.** If your plugin injects a
 control into it, you must adapt:
@@ -157,7 +157,7 @@ control into it, you must adapt:
   popovers 40).
 
 Full guide + the canonical snippet: **[docs/plugin-v3-ui.md](docs/plugin-v3-ui.md)**.
-Verify any player-injecting plugin in **both** `/` (v2) and `/v3`.
+Verify any player-injecting plugin at `/` — it and `/v3` serve the same v3 shell.
 
 ### Performance — never run DOM queries on a per-frame path
 
@@ -566,7 +566,7 @@ a local pointer + code map.
 - **Storage** — `localStorage` for all user preferences
 - **Styling** — Tailwind CSS utility classes, dark theme (`bg-dark-600`, `text-gray-300`, accent `#4080e0`, gold `#e8c040`). Tailwind is served as a **prebuilt** stylesheet (`static/tailwind.min.css`, regenerated by `bash scripts/build-tailwind.sh`), **never** the runtime Play CDN — the CDN's on-the-fly JIT rescanned the DOM on the main thread and dropped ~26% of frames with the 3D highway (feedBack-desktop#110). The committed CSS only contains classes the build scanner saw, so CI (`tailwind-fresh`) rebuilds and diffs it; run the build script and commit when you add new classes. A plugin that uses classes not guaranteed in core (notably arbitrary values like `w-[37px]`) MUST ship its own compiled stylesheet via the `styles` manifest key, built with `corePlugins.preflight = false` (utilities only — core ships the one base reset). Plugins MUST NOT load the Tailwind Play CDN or any runtime CSS JIT. See constitution Principle II.
 - **Naming** — camelCase for JS functions, kebab-case for CSS classes, snake_case for plugin IDs
-- **Text selection (v3)** — the v3 UI defaults to `user-select: none` on `html` (in `static/v3/v3.css`) so accidental drag/double-click selection of chrome never looks broken. Form fields are always re-enabled, and a **plugin's mounted screen subtree (`.screen[id^="plugin-"]`) stays selectable by default**, so a plugin's copy-worthy text (lyrics, chord names, results, diagnostics) is unaffected — *unless your plugin renders copyable content OUTSIDE its `plugin-<id>` screen* (e.g. injected into the player chrome / a HUD overlay), which inherits the non-select default. Opt such content back in with the core-served **`.fb-selectable`** class (it sets `user-select: text` on the element + descendants; works for runtime-installed plugins since it's hand-authored in core CSS, not a scanned Tailwind utility). Never use a `* { user-select: none }` rule (breaks input carets/IME), and never use `user-select: none` to "lock" text — keep errors, IDs, paths, versions, and metadata selectable. (v2 is unchanged.)
+- **Text selection (v3)** — the v3 UI defaults to `user-select: none` on `html` (in `static/v3/v3.css`) so accidental drag/double-click selection of chrome never looks broken. Form fields are always re-enabled, and a **plugin's mounted screen subtree (`.screen[id^="plugin-"]`) stays selectable by default**, so a plugin's copy-worthy text (lyrics, chord names, results, diagnostics) is unaffected — *unless your plugin renders copyable content OUTSIDE its `plugin-<id>` screen* (e.g. injected into the player chrome / a HUD overlay), which inherits the non-select default. Opt such content back in with the core-served **`.fb-selectable`** class (it sets `user-select: text` on the element + descendants; works for runtime-installed plugins since it's hand-authored in core CSS, not a scanned Tailwind utility). Never use a `* { user-select: none }` rule (breaks input carets/IME), and never use `user-select: none` to "lock" text — keep errors, IDs, paths, versions, and metadata selectable.
 - **Player layout** — `#player` is `display:flex; flex-direction:column; position:fixed; inset:0`. `#highway` is `flex:1`. `#player-controls` sits at the bottom. Hiding the highway collapses the layout — use `margin-top: auto` on controls if you need to hide it.
 
 ## Backend Conventions

docs/perf-baseline.md

@@ -37,6 +37,31 @@ the hooks, they just need real songs in `DLC_DIR`.
 
 ## Results
 
+### R3c pre-lift baseline — 2026-07-10 (2D highway draw cost)
+
+The gate for the `highway.js` split. Captured on a seeded library (the 33 MB
+Arcturus feedpak) with the new `--song` mode, which measures **per-frame draw
+cost** — rAF callbacks are tagged via `highway.addDrawHook`, so only frames the
+highway actually painted count (the other ~half are cheap no-op loops that would
+otherwise mask a regression). Any `highway.js` change must re-run this on the
+same machine and stay within noise of these numbers.
+
+```bash
+node scripts/perf-baseline.mjs --base http://127.0.0.1:8300 \
+    --song "Arcturus - The Sham Mirrors - Kinetic.feedpak"
+```
+
+| run | draw frames | p50 | p95 | p99 | max |
+|---|---|---|---|---|---|
+| 1 | 53/106 | 2.2 | 3.2 | 3.6 | 3.6 |
+| 2 | 50/100 | 2.2 | 2.9 | 3.2 | 3.2 |
+| 3 | 53/106 | 2.1 | 2.7 | 3.5 | 3.5 |
+
+**p50 ≈ 2.2 ms · p95 spread 2.7–3.2 ms** (3 runs × 10 s playback, headless
+chromium on the dev box). The `H`-container lift changes each closure-slot read
+to a `H.<slot>` property load; this is the number that proves it doesn't cost the
+hot loop.
+
 ### R0 baseline — 2026-07-08 (branch `feat/r0-plugin-module-rails`)
 
 > ⚠️ A quick capture (`--n 50 --soak 8`) against an **empty** library (no charts

docs/plugin-styles.md

@@ -1,9 +1,9 @@
 # Plugin styling — the `styles` capability
 
-> Building for the redesigned **v3 UI** (`FEEDBACK_UI=v3` / `/v3`)? v3 uses `fb-*`
-> design tokens and a restructured player chrome with a dedicated plugin-control
-> slot. See **[plugin-v3-ui.md](plugin-v3-ui.md)** for the player-chrome contract
-> plugins must follow in v3.
+> The **v3 UI** is the only UI — it uses `fb-*` design tokens and a restructured
+> player chrome with a dedicated plugin-control slot. See
+> **[plugin-v3-ui.md](plugin-v3-ui.md)** for the player-chrome contract plugins
+> must follow.
 
 FeedBack serves Tailwind as a **prebuilt** stylesheet
 (`static/tailwind.min.css`), never the runtime Play CDN. The CDN's on-the-fly

docs/plugin-v3-ui.md

@@ -1,16 +1,16 @@
 # Building plugins for the v3 UI (fee[dB]ack v0.3.0)
 
-v0.3.0 ("fee[dB]ack") ships a redesigned UI **behind a flag** — `FEEDBACK_UI=v3`
-or the `/v3` route. The classic UI (v2) remains the default until 0.3.0 ships, so
-plugins must work in **both**.
+v0.3.0 ("fee[dB]ack") ships a redesigned UI. It is **the only UI** — the classic v2
+shell and its `FEEDBACK_UI` / `/v2` opt-outs have been removed, so there is no
+longer a second shell to support.
 
-The good news: v3 **reuses the same engine** as v2 — same `server.py`, `app.js`,
-`highway.js`, `playSong`, `showScreen`, capability registry, library providers,
-and the `window.feedBackViz_<id>` / `setRenderer` visualization contract. So your
-plugin's **backend, capabilities, library providers, `nav`/`screen`, visualization
-renderers, diagnostics, and settings export all work unchanged in v3.** v3 surfaces
-your `nav` entry in the new sidebar (via `shell.js` `renderPluginNav`) and your
-screen mounts exactly as before.
+The good news: v3 **reuses the same engine** the classic UI did — same `server.py`,
+`app.js`, `highway.js`, `playSong`, `showScreen`, capability registry, library
+providers, and the `window.feedBackViz_<id>` / `setRenderer` visualization contract.
+So your plugin's **backend, capabilities, library providers, `nav`/`screen`,
+visualization renderers, diagnostics, and settings export all work unchanged.** v3
+surfaces your `nav` entry in the new sidebar (via `shell.js` `renderPluginNav`) and
+your screen mounts exactly as before.
 
 **The one thing that changed is the player chrome** — and only if your plugin
 injects controls into it.
@@ -188,4 +188,4 @@ out of the capability graph.
 - [ ] Dropdowns positioned via `getBoundingClientRect()`, not `#player-controls`.
 - [ ] `#player` overlays keep `z-index` ≤ the chrome layers (transport/HUD 20,
       rail 30, popovers 40).
-- [ ] Verify in **both** `/` (v2) and `/v3`.
+- [ ] Verify at `/` — it and `/v3` serve the same (and only) v3 shell.

docs/size-exemptions.md

@@ -54,8 +54,12 @@ without a *signed* exemption" is unenforceable.
 
 ## Planned, NOT exempt (owned by split plans — listed so nothing falls between states)
 
-core `static/app.js` (11,821) · `static/highway.js` (4,154, whole file) · `server.py`
-(13,948) · `static/v3/songs.js` (4,134) · `static/capabilities/audio-session.js`
+core `static/app.js` (11,852) · `static/highway.js` (4,168, whole file) · `server.py`
+(2,413 — was 14,037; ratcheted by the R3 `MetadataDB` + `AudioEffectsMappingDB`
+extractions and twenty-two `routers/` modules, plus lib/library_registry.py for the provider-registry classes (album-art in `lib/routers/art.py`, the settings + export/import bundle in `lib/routers/settings.py`); the ~930-line metadata-enrichment subsystem — MB/CAA/AcoustID transport, matcher, background worker — now lives in `lib/enrichment.py`) ·
+`lib/metadata_db.py` (4,373 — new in R3; the `MetadataDB` class alone is 4,018 lines
+and is a monolith in its own right, to be split per-table once the router train
+lands) · `static/v3/songs.js` (4,134) · `static/capabilities/audio-session.js`
 (2,974) · `plugins/highway_3d/screen.js` (15,656) · `plugins/keys_highway_3d/screen.js`
 (3,780) · `plugins/drum_highway_3d/screen.js` (3,597) — and every monolith with a PR
 train in the refactor plan. Test files (e.g. `tests/test_plugins.py`) are out of scope

lib/appconfig.py

@@ -0,0 +1,28 @@
+"""Reading the app's config.json — the one shared, pure helper (R3).
+
+Extracted verbatim from server.py so route modules that need a config value
+(reference pitch, server_config, …) can read it without reaching back into the
+host file. server.py re-imports it, so its ~11 call sites and any
+`server._load_config` test reference keep resolving unchanged.
+"""
+
+import json
+
+
+def _load_config(config_file):
+    """Read and parse config.json. Returns the parsed dict, or None if
+    the file is missing, unreadable, invalid JSON, or parses to a
+    non-dict (e.g. the file contains `[]` or `42`). Callers treat None
+    as "fall back to defaults". Shared between GET and POST so both
+    handle bad files the same way."""
+    if not config_file.exists():
+        return None
+    try:
+        # Explicit UTF-8: save_settings()/import write config.json as
+        # UTF-8 bytes, so the read must not depend on the platform's
+        # default text encoding (cp1252 on Windows would mojibake or
+        # UnicodeDecodeError on a non-ASCII DLC path).
+        parsed = json.loads(config_file.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+    return parsed if isinstance(parsed, dict) else None

lib/appstate.py

@@ -0,0 +1,143 @@
+"""Shared application state — the seam that lets route modules reach core
+singletons without importing ``server``.
+
+``server.py`` is the host: it owns the FastAPI ``app``, constructs the DB
+singletons, and runs the lifecycle. As routes move out into ``routers/`` (R3),
+those modules need ``meta_db`` and friends — but they must not ``import
+server``, or the import graph goes circular the moment ``server`` imports them
+back.
+
+So ``server`` **injects** its singletons here once, at the point it builds them::
+
+    # server.py
+    meta_db = MetadataDB(CONFIG_DIR)
+    appstate.configure(meta_db=meta_db, ...)
+
+and a router reads them back as **module attributes, at call time**::
+
+    # routers/artists.py
+    import appstate
+
+    @router.get("/api/artist/{name}/page")
+    def artist_page(name):
+        return appstate.meta_db.artist_page(name)
+
+This is the Python analogue of the injected `configureX({...})` seams the
+frontend refactor uses (stems' ``configureStreaming``, studio's
+``configureAudioGraph``, the editor's ``src/host.js``), and of the plugin
+``setup(app, context)`` contract in Principle III: dependencies flow one way,
+``server -> routers -> appstate``, and nothing imports back up.
+
+Two properties this shape buys, both load-bearing:
+
+* **``import appstate`` performs no IO and constructs nothing.** ``server``
+  still owns construction, so the ~49 test fixtures that do
+  ``sys.modules.pop("server")`` + re-import (to rebuild ``meta_db`` under a
+  patched ``CONFIG_DIR``) keep working untouched — a singleton *owned* here
+  would survive that pop and go stale.
+* **Reads are late-bound.** Routers must use ``appstate.meta_db``, never
+  ``from appstate import meta_db`` — a ``from`` import freezes the binding at
+  its current value, so a later ``configure()`` (or a
+  ``monkeypatch.setattr(appstate, "meta_db", fake)``) would not reach the
+  router. This is the same read-only-binding trap as ES ``import``.
+
+Defaults are ``None`` on purpose: they are inert but *type-honest*, so a router
+that runs before ``configure()`` fails loudly on ``NoneType`` instead of
+quietly operating on a stand-in.
+
+Slots are added here only when a router actually needs one — this is a seam,
+not a grab-bag for everything in ``server.py``.
+
+**Why this lives in ``lib/`` and not the repo root.** Because it constructs
+nothing and does no import-time IO, it satisfies Principle V's rule for ``lib/``
+modules — and ``lib/`` is the only core directory every packaging path already
+copies: the Dockerfile (``COPY lib/``), ``docker-compose.yml``, and
+feedback-desktop's ``bundle-slopsmith.sh`` (``cp -r lib``). All three also put
+both the bundle root and ``lib/`` on ``sys.path``. A root-level module ships in
+Docker but is silently dropped from the packaged desktop app, whose bundler
+copies a hardcoded file list — that regression is what moved this file here.
+"""
+
+# The singletons routers may read. Every name here must also be a `_SLOTS` key.
+meta_db = None
+audio_effect_mappings = None
+# The tuning-provider registry instance (built-ins + plugin-contributed). A
+# stable object mutated in place via register()/unregister() — injected here by
+# reference so routers read the same registry plugins populate.
+tuning_providers = None
+# The library-provider registry instance + the local provider, constructed in
+# server.py (LocalLibraryProvider needs meta_db) and injected by reference. The
+# classes live in lib/library_registry.py; plugins register their own providers
+# through the registry via plugin_context.
+library_providers = None
+local_library_provider = None
+
+# Config paths. server.py derives these from the environment (fresh on every
+# import, so the ~49 pop-and-reimport fixtures keep working) and injects them
+# here. Routers read them as `appstate.config_dir` etc. — a module attribute at
+# call time. NOTE: config_dir/dlc_dir are env-derived, so a `setenv`+reimport
+# test reconfigures them for free; STATIC_DIR/SLOPPAK_CACHE_DIR are patched via
+# `setattr(server, …)` in a few tests, so those slots (when added) need their
+# tests retargeted to appstate in the same PR.
+config_dir = None
+dlc_dir = None          # the DLC_DIR env value as a Path (Path("") if unset)
+dlc_dir_env = None      # the raw DLC_DIR env string, "" if unset — distinguishes
+                        # "unset" from Path("")→"." (see dlc_paths._get_dlc_dir)
+# Cache/asset dirs. static_dir + sloppak_cache_dir are patched via
+# `setattr(server, …)` in a few tests, so a router reading them here needs those
+# setattr sites retargeted to `setattr(appstate, …)` in the same PR (ws_highway
+# retargets the 3 test_highway_ws_* SLOPPAK sites). config_dir-derived dirs are
+# reconfigured for free on a setenv+reimport.
+static_dir = None
+sloppak_cache_dir = None
+audio_cache_dir = None
+
+# Injected callables (not values): server owns the impl + its state, routers call
+# through the seam. get_progression_content wraps a lazy content cache that stays
+# in server.py (its `setattr(server, "_progression_content")` test is untouched).
+get_progression_content = None
+builtin_diagnostic_filename = None
+running_version = None
+# Art helpers that stay in server.py (shared with the art/delete routes) but are
+# also called by the enrichment worker in lib/enrichment.py — injected as
+# callables to keep enrichment acyclic. art_cache_dir is server's ART_CACHE_DIR.
+art_cache_dir = None
+song_pack_art_exists = None
+art_override_paths = None
+art_safe_name = None
+# The canonical settings-defaults builder — stays in server.py (shared with the
+# scan/artist-links code) but the settings router calls it through the seam.
+default_settings = None
+# Scan/ingest seam for the song routes (routers/song.py). kick_scan/
+# invalidate_song_caches/stat_for_cache stay in server.py (scan lifecycle owns
+# them); scan_status is a GETTER (the underlying dict is reassigned, so a value
+# would go stale) — call appstate.scan_status() to read the live status.
+kick_scan = None
+invalidate_song_caches = None
+stat_for_cache = None
+scan_status = None
+
+_SLOTS = frozenset({
+    "meta_db", "audio_effect_mappings", "tuning_providers",
+    "library_providers", "local_library_provider",
+    "config_dir", "dlc_dir", "dlc_dir_env",
+    "static_dir", "sloppak_cache_dir", "audio_cache_dir",
+    "get_progression_content", "builtin_diagnostic_filename",
+    "running_version",
+    "art_cache_dir", "song_pack_art_exists", "art_override_paths", "art_safe_name",
+    "default_settings",
+    "kick_scan", "invalidate_song_caches", "stat_for_cache", "scan_status",
+})
+
+
+def configure(**kwargs) -> None:
+    """Publish `server`'s singletons into this module. Called once per
+    `server` import (and again on re-import), so it must be idempotent."""
+    unknown = set(kwargs) - _SLOTS
+    if unknown:
+        raise TypeError(
+            f"appstate.configure() got unknown slot(s): {sorted(unknown)}. "
+            f"Known slots: {sorted(_SLOTS)}. Add the name to _SLOTS if a router "
+            f"genuinely needs it."
+        )
+    globals().update(kwargs)

lib/audio_effects_db.py

@@ -0,0 +1,287 @@
+"""Core-owned song/tone -> audio-effect-provider mapping index.
+
+Extracted verbatim from ``server.py`` (R3). ``server.py`` still owns the
+``audio_effect_mappings`` singleton; this module only supplies the class, so
+nothing here touches config paths at import time — the caller passes
+``config_dir`` in.
+"""
+
+import json
+import sqlite3
+import threading
+from pathlib import Path
+
+
+class AudioEffectsMappingDB:
+    """Core-owned public song/tone -> provider mapping index.
+
+    Providers own the preset/chain rows addressed by provider_ref. Core owns
+    the cross-provider routing index and the active mapping per song/tone.
+    """
+
+    def __init__(self, config_dir: Path):
+        config_dir.mkdir(parents=True, exist_ok=True)
+        self.db_path = str(config_dir / "audio_effects.db")
+        self.conn = sqlite3.connect(self.db_path, check_same_thread=False)
+        self.conn.execute("PRAGMA journal_mode=WAL")
+        self.conn.execute("PRAGMA foreign_keys=ON")
+        self.conn.execute("""
+            CREATE TABLE IF NOT EXISTS audio_effect_mappings (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                song_key TEXT NOT NULL,
+                filename TEXT NOT NULL DEFAULT '',
+                tone_key TEXT NOT NULL,
+                provider_id TEXT NOT NULL,
+                provider_ref TEXT NOT NULL,
+                label TEXT NOT NULL DEFAULT '',
+                source TEXT NOT NULL DEFAULT 'manual',
+                metadata_json TEXT NOT NULL DEFAULT '{}',
+                created_at TEXT NOT NULL DEFAULT (datetime('now')),
+                updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+                UNIQUE(song_key, tone_key, provider_id)
+            )
+        """)
+        self.conn.execute("""
+            CREATE TABLE IF NOT EXISTS audio_effect_active_mappings (
+                song_key TEXT NOT NULL,
+                tone_key TEXT NOT NULL,
+                mapping_id INTEGER NOT NULL,
+                updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+                PRIMARY KEY (song_key, tone_key),
+                FOREIGN KEY (mapping_id) REFERENCES audio_effect_mappings(id) ON DELETE CASCADE
+            )
+        """)
+        self.conn.execute(
+            "CREATE INDEX IF NOT EXISTS idx_audio_effect_mappings_provider "
+            "ON audio_effect_mappings(provider_id)"
+        )
+        self.conn.execute(
+            "CREATE INDEX IF NOT EXISTS idx_audio_effect_mappings_filename "
+            "ON audio_effect_mappings(filename)"
+        )
+        self.conn.commit()
+        self._lock = threading.Lock()
+
+    @staticmethod
+    def _text(value, *, field: str, limit: int, allow_empty: bool = False) -> str:
+        if value is None:
+            text = ""
+        elif not isinstance(value, str):
+            raise ValueError(f"{field} must be a string")
+        else:
+            text = value.strip()
+        if not text and not allow_empty:
+            raise ValueError(f"{field} is required")
+        if len(text) > limit:
+            raise ValueError(f"{field} is too long")
+        return text
+
+    @staticmethod
+    def _mapping_id(value) -> int | None:
+        # Bind only values SQLite can store as an INTEGER; an out-of-range id is a
+        # clean miss (404), not a 500 at bind time.
+        if isinstance(value, int) and not isinstance(value, bool) and -(2 ** 63) <= value < 2 ** 63:
+            return value
+        return None
+
+    @staticmethod
+    def _field(data: dict, *keys):
+        # Select the first present snake/camel alias by key, not by truthiness, so a
+        # falsey non-string value (false/0) still reaches _text() and is rejected
+        # instead of being silently swallowed by an `or` chain.
+        for key in keys:
+            if key in data:
+                return data[key]
+        return None
+
+    @staticmethod
+    def _metadata(value) -> str:
+        if value is None:
+            return "{}"
+        if not isinstance(value, dict):
+            raise ValueError("metadata must be an object")
+        encoded = json.dumps(value, ensure_ascii=True, sort_keys=True)
+        if len(encoded) > 8192:
+            raise ValueError("metadata is too large")
+        return encoded
+
+    @staticmethod
+    def _row(row) -> dict | None:
+        if row is None:
+            return None
+        metadata = {}
+        try:
+            metadata = json.loads(row[8]) if row[8] else {}
+        except Exception:
+            metadata = {}
+        return {
+            "id": int(row[0]),
+            "song_key": row[1],
+            "filename": row[2] or "",
+            "tone_key": row[3],
+            "provider_id": row[4],
+            "provider_ref": row[5],
+            "label": row[6] or "",
+            "source": row[7] or "manual",
+            "metadata": metadata if isinstance(metadata, dict) else {},
+            "created_at": row[9] or "",
+            "updated_at": row[10] or "",
+            "active": bool(row[11]),
+        }
+
+    def _select_sql(self) -> str:
+        return """
+            SELECT m.id, m.song_key, m.filename, m.tone_key, m.provider_id,
+                   m.provider_ref, m.label, m.source, m.metadata_json,
+                   m.created_at, m.updated_at,
+                   CASE WHEN a.mapping_id IS NULL THEN 0 ELSE 1 END AS active
+            FROM audio_effect_mappings m
+            LEFT JOIN audio_effect_active_mappings a
+              ON a.song_key = m.song_key AND a.tone_key = m.tone_key AND a.mapping_id = m.id
+        """
+
+    def list(self, *, song_key: str = "", filename: str = "", tone_key: str = "", provider_id: str = "") -> list[dict]:
+        clauses: list[str] = []
+        params: list[str] = []
+        song_key = self._text(song_key, field="song_key", limit=240, allow_empty=True)
+        filename = self._text(filename, field="filename", limit=500, allow_empty=True)
+        tone_key = self._text(tone_key, field="tone_key", limit=160, allow_empty=True)
+        provider_id = self._text(provider_id, field="provider_id", limit=96, allow_empty=True)
+        if song_key and filename:
+            clauses.append("(m.song_key = ? OR m.filename = ?)")
+            params.extend([song_key, filename])
+        elif song_key:
+            clauses.append("m.song_key = ?")
+            params.append(song_key)
+        elif filename:
+            clauses.append("(m.song_key = ? OR m.filename = ?)")
+            params.extend([filename, filename])
+        if tone_key:
+            clauses.append("m.tone_key = ?")
+            params.append(tone_key)
+        if provider_id:
+            clauses.append("m.provider_id = ?")
+            params.append(provider_id)
+        sql = self._select_sql()
+        if clauses:
+            sql += " WHERE " + " AND ".join(clauses)
+        sql += " ORDER BY m.song_key COLLATE NOCASE, m.tone_key COLLATE NOCASE, m.provider_id COLLATE NOCASE"
+        with self._lock:
+            rows = self.conn.execute(sql, params).fetchall()
+        return [self._row(row) for row in rows]
+
+    def get(self, mapping_id: int) -> dict | None:
+        mapping_id = self._mapping_id(mapping_id)
+        if mapping_id is None:
+            return None
+        with self._lock:
+            row = self.conn.execute(self._select_sql() + " WHERE m.id = ?", (mapping_id,)).fetchone()
+        return self._row(row)
+
+    def upsert(self, data: dict) -> dict:
+        if not isinstance(data, dict):
+            raise ValueError("mapping body must be an object")
+        filename = self._text(data.get("filename", ""), field="filename", limit=500, allow_empty=True)
+        song_key_raw = self._field(data, "song_key", "songKey")
+        if song_key_raw is None or song_key_raw == "":
+            song_key_raw = filename
+        song_key = self._text(song_key_raw, field="song_key", limit=240)
+        tone_key = self._text(self._field(data, "tone_key", "toneKey"), field="tone_key", limit=160, allow_empty=True)
+        provider_id = self._text(self._field(data, "provider_id", "providerId"), field="provider_id", limit=96)
+        provider_ref = self._text(self._field(data, "provider_ref", "providerRef"), field="provider_ref", limit=240)
+        label = self._text(data.get("label", ""), field="label", limit=160, allow_empty=True)
+        source = self._text(data.get("source", "manual"), field="source", limit=40, allow_empty=True) or "manual"
+        metadata_json = self._metadata(data.get("metadata", {}))
+        with self._lock:
+            self.conn.execute(
+                """
+                INSERT INTO audio_effect_mappings
+                    (song_key, filename, tone_key, provider_id, provider_ref, label, source, metadata_json, updated_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, datetime('now'))
+                ON CONFLICT(song_key, tone_key, provider_id) DO UPDATE SET
+                    -- Only overwrite filename when a non-empty one was supplied; an
+                    -- omitted/empty filename must preserve the stored value (it's an
+                    -- alternate lookup key for list(..., filename=...)).
+                    filename=CASE WHEN excluded.filename <> '' THEN excluded.filename ELSE audio_effect_mappings.filename END,
+                    provider_ref=excluded.provider_ref,
+                    label=excluded.label,
+                    source=excluded.source,
+                    metadata_json=excluded.metadata_json,
+                    updated_at=datetime('now')
+                """,
+                (song_key, filename, tone_key, provider_id, provider_ref, label, source, metadata_json),
+            )
+            row = self.conn.execute(
+                "SELECT id FROM audio_effect_mappings WHERE song_key = ? AND tone_key = ? AND provider_id = ?",
+                (song_key, tone_key, provider_id),
+            ).fetchone()
+            if row is None:
+                raise ValueError("failed to create audio-effects mapping")
+            mapping_id = int(row[0])
+            if data.get("active") is True:
+                self.conn.execute(
+                    """
+                    INSERT INTO audio_effect_active_mappings (song_key, tone_key, mapping_id, updated_at)
+                    VALUES (?, ?, ?, datetime('now'))
+                    ON CONFLICT(song_key, tone_key) DO UPDATE SET
+                        mapping_id=excluded.mapping_id,
+                        updated_at=datetime('now')
+                    """,
+                    (song_key, tone_key, mapping_id),
+                )
+            self.conn.commit()
+        return self.get(mapping_id)
+
+    def delete(self, mapping_id: int, *, provider_id: str = "") -> bool:
+        mapping_id = self._mapping_id(mapping_id)
+        if mapping_id is None:
+            return False
+        provider_id = self._text(provider_id, field="provider_id", limit=96, allow_empty=True)
+        with self._lock:
+            if provider_id:
+                cur = self.conn.execute(
+                    "DELETE FROM audio_effect_mappings WHERE id = ? AND provider_id = ?",
+                    (mapping_id, provider_id),
+                )
+            else:
+                cur = self.conn.execute("DELETE FROM audio_effect_mappings WHERE id = ?", (mapping_id,))
+            self.conn.commit()
+            return cur.rowcount > 0
+
+    def activate(self, mapping_id: int, *, provider_id: str = "") -> dict | None:
+        mapping_id = self._mapping_id(mapping_id)
+        if mapping_id is None:
+            return None
+        provider_id = self._text(provider_id, field="provider_id", limit=96, allow_empty=True)
+        with self._lock:
+            row = self.conn.execute(
+                self._select_sql() + " WHERE m.id = ?",
+                (mapping_id,),
+            ).fetchone()
+            mapping = self._row(row)
+            if not mapping or (provider_id and mapping["provider_id"] != provider_id):
+                return None
+            self.conn.execute(
+                """
+                INSERT INTO audio_effect_active_mappings (song_key, tone_key, mapping_id, updated_at)
+                VALUES (?, ?, ?, datetime('now'))
+                ON CONFLICT(song_key, tone_key) DO UPDATE SET
+                    mapping_id=excluded.mapping_id,
+                    updated_at=datetime('now')
+                """,
+                (mapping["song_key"], mapping["tone_key"], mapping_id),
+            )
+            self.conn.commit()
+            selected = self.conn.execute(self._select_sql() + " WHERE m.id = ?", (mapping_id,)).fetchone()
+        return self._row(selected)
+
+    def clear_active(self, *, song_key: str, tone_key: str) -> bool:
+        song_key = self._text(song_key, field="song_key", limit=240)
+        tone_key = self._text(tone_key, field="tone_key", limit=160, allow_empty=True)
+        with self._lock:
+            cur = self.conn.execute(
+                "DELETE FROM audio_effect_active_mappings WHERE song_key = ? AND tone_key = ?",
+                (song_key, tone_key),
+            )
+            self.conn.commit()
+            return cur.rowcount > 0

lib/dlc_paths.py

@@ -0,0 +1,99 @@
+"""DLC library path resolution — where the song files live, plus safe containment.
+
+Extracted from ``server.py`` (R3). ``_resolve_dlc_path`` is pure and moved
+verbatim. ``_get_dlc_dir`` reads the env-derived paths through the ``appstate``
+seam (``server.py`` configures ``dlc_dir``/``dlc_dir_env``/``config_dir`` at
+import, fresh on every re-import), so this module does no import-time IO and the
+pop-and-reimport fixtures keep working. ``server.py`` re-exports both names, so
+existing ``server._get_dlc_dir`` / ``server._resolve_dlc_path`` references
+(tests, other handlers) resolve unchanged.
+"""
+
+import json
+import os
+from pathlib import Path
+
+import appstate
+
+
+def _get_dlc_dir(cfg: dict | None = None) -> Path | None:
+    # Only consider DLC_DIR if the env var was non-empty. `Path("")` collapses
+    # to `.` and reports `.is_dir() == True`, which would silently shadow the
+    # config.json fallback. Checking the raw env string preserves
+    # `DLC_DIR=.` as a valid opt-in for cwd while keeping unset/empty out.
+    if appstate.dlc_dir_env and appstate.dlc_dir.is_dir():
+        return appstate.dlc_dir
+    if cfg is None:
+        config_file = appstate.config_dir / "config.json"
+        if config_file.exists():
+            try:
+                cfg = json.loads(config_file.read_text(encoding="utf-8"))
+            except Exception:
+                pass
+    if isinstance(cfg, dict):
+        raw = str(cfg.get("dlc_dir", "")).strip()
+        if raw:
+            p = Path(raw)
+            if p.is_dir():
+                return p
+    return None
+
+
+def _resolve_dlc_path(dlc: Path, filename: str) -> Path | None:
+    """Resolve `filename` under DLC_DIR and refuse anything that escapes.
+
+    `filename` arrives from `:path` route params and can contain `..`
+    segments. The Sloppak and archive paths happen to fail safely later
+    because their loaders raise on missing/invalid files, but loose-
+    folder format detection (`is_loose_song`) globs and parses XML on
+    disk first, which lets a crafted path trigger filesystem reads
+    outside DLC_DIR before any guard fires. Centralise the containment
+    check so every filename-bound handler validates before touching the
+    filesystem.
+
+    Containment here is LEXICAL (normalize `.`/`..` WITHOUT following
+    symlinks), not `safe_join`'s `.resolve()`-based check — because users
+    commonly mount their song library through a directory JUNCTION/symlink
+    (a library shared across app installs; the desktop app's own mounts).
+    `.resolve()` follows that junction to its real target, sees it sits
+    outside DLC_DIR, and wrongly rejects every song reached through it — the
+    scanner's `rglob` indexes those songs, but art/load then 403/404s (broken
+    covers, unplayable songs). Lexical normalization still rejects the only
+    escapes a `:path` filename can express — `..` traversal and absolute
+    paths — which the traversal tests pin. `safe_join` stays strict (it is
+    the zip-slip / plugin-asset guard, where following a symlink out IS the
+    defense); the loose-folder art handler keeps its own per-file symlink
+    re-check for defence-in-depth.
+
+    Returns the validated Path (not necessarily link-resolved), or None if
+    the filename is empty, contains a NUL, or escapes the DLC root.
+    """
+    if not filename:
+        return None
+    # Backslashes → forward slashes so a Windows-style `..\\x` traversal is
+    # rejected identically on POSIX (mirrors safe_join's normalisation).
+    safe = filename.replace("\\", "/")
+    if "\x00" in safe:
+        return None
+    # Reject drive-letter / absolute paths in BOTH conventions. A POSIX "/x" is
+    # caught by the containment check below (the `/` operator discards `root`),
+    # but a Windows drive-absolute "C:/x" is treated as a relative "C:" dir on
+    # POSIX and would otherwise slip in as `<root>/C:/x` — so the contract must
+    # hold cross-platform (a shared library is reached from either OS).
+    from pathlib import PurePosixPath, PureWindowsPath
+    if (PurePosixPath(safe).is_absolute()
+            or PureWindowsPath(safe).is_absolute()
+            or PureWindowsPath(safe).drive):
+        return None
+    try:
+        root = dlc.resolve()
+        # normpath collapses `.`/`..`/duplicate separators purely lexically —
+        # it never touches the filesystem, so an in-library junction component
+        # is preserved (allowed) while `..`/absolute segments still escape and
+        # get caught by the containment check below.
+        candidate = Path(os.path.normpath(root / safe))
+        if not candidate.is_relative_to(root):
+            return None
+    except (ValueError, OSError):
+        return None
+    return candidate

lib/gp2rs.py

@@ -1114,7 +1114,7 @@ def _build_xml(
     ET.SubElement(root, "arrangement").text = arrangement
     ET.SubElement(root, "offset").text = f"{audio_offset:.3f}"
     ET.SubElement(root, "songLength").text = f"{song_length:.3f}"
-    ET.SubElement(root, "startBeat").text = f"{beats[0].time:.3f}" if beats else "0.000"
+    ET.SubElement(root, "startBeat").text = f"{beats[0].time:.6f}" if beats else "0.000000"
     ET.SubElement(root, "averageTempo").text = str(tempo)
     ET.SubElement(root, "artistName").text = artist
     ET.SubElement(root, "albumName").text = album
@@ -1139,10 +1139,17 @@ def _build_xml(
         tuning_el.set(f"string{i}", str(tuning[i] if i < len(tuning) else 0))
     ET.SubElement(root, "capo").text = "0"
 
-    # Ebeats
+    # Ebeats — write beat times at MICROSECOND (6-decimal) precision, not
+    # millisecond (3-decimal). The editor/timeline DERIVES per-bar BPM from beat
+    # spans (bpm = beats·60/span), which amplifies any rounding: at 3 decimals a
+    # constant-tempo GP (e.g. 140) shows a spurious ±0.05–0.7 BPM per-bar drift
+    # (worse for fast/odd meters) because most bar lengths don't land on a ms
+    # boundary. gp2rs computes these times exactly from the GP tempo map, so the
+    # only loss is this format string — 6 decimals makes the derived tempo match
+    # GP's authored value. (Everything else stays at :.3f; only beats drive tempo.)
     ebeats = ET.SubElement(root, "ebeats", count=str(len(beats)))
     for b in beats:
-        ET.SubElement(ebeats, "ebeat", time=f"{b.time:.3f}", measure=str(b.measure))
+        ET.SubElement(ebeats, "ebeat", time=f"{b.time:.6f}", measure=str(b.measure))
 
     # Sections
     sections_el = ET.SubElement(root, "sections", count=str(len(sections)))

lib/library_registry.py

@@ -0,0 +1,417 @@
+"""The library-provider registry — the plugin extension point for song sources.
+
+`LocalLibraryProvider` wraps the local `MetadataDB`; third-party plugins register
+their own providers (duck-typed: any object with the advertised methods) through
+`LibraryProviderRegistry`, and smart collections are surfaced as
+`SmartCollectionProvider`s over the local one. server.py constructs the singleton
+(`library_providers`), injects it + the local provider into appstate, and exposes
+`register_library_provider`/`unregister_library_provider` to plugins via
+plugin_context (with per-plugin ownership scoping in plugins/__init__.py).
+
+Moved verbatim out of server.py (R3). The shared query/collection helpers live
+here too so routers/library.py can import them without reaching into server.
+"""
+
+import re
+import threading
+from typing import ClassVar
+
+import appstate
+from metadata_db import MetadataDB, _tuning_group_key_sql
+from routers import art as art_router
+
+import logging
+log = logging.getLogger("feedBack.server")
+
+def _safe_art_redirect_url(url: str) -> str | None:
+    """Return the URL if it is safe to redirect to (http/https only), else None."""
+    from urllib.parse import urlparse
+    if not url or not isinstance(url, str):
+        return None
+    try:
+        parsed = urlparse(url)
+        if parsed.scheme.lower() not in ("http", "https"):
+            return None
+        if not parsed.hostname:
+            return None
+        return url
+    except Exception:
+        return None
+
+
+_TUNING_GROUP_KEY_SQL = _tuning_group_key_sql("songs")
+
+
+class LocalLibraryProvider:
+    id = "local"
+    label = "My Library"
+    kind = "local"
+    capabilities = (
+        "library.read",
+        "art.read",
+        "song.play",
+        "favorite.write",
+        "metadata.write",
+    )
+
+    def __init__(self, db: MetadataDB):
+        self._db = db
+
+    def query_page(self, **kwargs) -> tuple[list[dict], int]:
+        return self._db.query_page(**kwargs)
+
+    def query_artists(self, **kwargs) -> tuple[list[dict], int]:
+        return self._db.query_artists(**kwargs)
+
+    def query_albums(self, **kwargs) -> tuple[list[dict], int]:
+        return self._db.query_albums(**kwargs)
+
+    def query_stats(self, **kwargs) -> dict:
+        return self._db.query_stats(**kwargs)
+
+    def tuning_names(self) -> dict:
+        # Group custom tunings on their raw offsets so distinct ones stay
+        # distinct (tuning_name collapses them all to "Custom Tuning"); named
+        # tunings keep grouping by name (stable across the rescan boundary, no
+        # offsets/name split). `key` is the value the client sends back as the
+        # filter selector — equal to the name for named tunings, the offsets
+        # string for customs; offsets also feed the client's custom-pill label.
+        with self._db._lock:
+            rows = self._db.conn.execute(
+                f"SELECT tuning_name, {_TUNING_GROUP_KEY_SQL} AS gkey, "
+                "MIN(tuning_sort_key), COUNT(*), MIN(tuning_offsets) "
+                "FROM songs WHERE title != '' AND COALESCE(tuning_name, '') != '' "
+                "GROUP BY gkey COLLATE NOCASE "
+                "ORDER BY ABS(COALESCE(MIN(tuning_sort_key), 0)), "
+                "COALESCE(MIN(tuning_sort_key), 0) ASC, "
+                "tuning_name COLLATE NOCASE"
+            ).fetchall()
+        return {
+            "tunings": [
+                {"name": name, "key": gkey, "offsets": offs or "",
+                 "sort_key": int(sk or 0), "count": count}
+                for name, gkey, sk, count, offs in rows
+            ],
+        }
+
+    async def get_art(self, song_id: str):
+        return await art_router.get_song_art(song_id)
+
+
+class LibraryProviderRegistry:
+    # Methods required per declared capability — only validated when the
+    # provider advertises the corresponding capability so action-only providers
+    # (e.g. art.read + song.sync without library.read) don't need to implement
+    # unused stubs.
+    _CAPABILITY_METHODS: ClassVar[dict[str, tuple[str, ...]]] = {
+        "library.read": ("query_page", "query_artists", "query_stats", "tuning_names"),
+        "art.read": ("get_art",),
+        "song.sync": ("sync_song",),
+    }
+    _ID_RE: ClassVar[re.Pattern[str]] = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$")
+
+    def __init__(self):
+        self._providers: dict[str, object] = {}
+        # Capabilities inferred at registration for legacy providers that omit
+        # the `capabilities` field.  Merged with provider_capabilities() so that
+        # runtime capability checks see the complete effective capability set.
+        self._inferred_caps: dict[str, set[str]] = {}
+        self._owner_plugin_ids: dict[str, str] = {}
+        self._lock = threading.RLock()
+
+    def register(self, provider: object, *, replace: bool = False, owner_plugin_id: str | None = None) -> object:
+        provider_id = self.provider_id(provider)
+        if not self._ID_RE.match(provider_id):
+            raise ValueError(
+                "library provider id must start with an alphanumeric character "
+                "and contain only letters, digits, _, ., :, or -"
+            )
+        if not self.provider_label(provider):
+            raise ValueError("library provider label must be a non-empty string")
+        # Use declared-only caps during validation — never include stale inferred
+        # caps from a previous provider registered under the same id (replace=True).
+        caps = self._declared_capabilities(provider)
+        # Backward compatibility: providers that predate explicit capability
+        # declarations may omit `capabilities` entirely. If the browse methods
+        # are all present, infer `library.read` so they still work unchanged.
+        # If capabilities are absent but the browse surface is also absent,
+        # raise a clear error rather than letting the provider register and
+        # then fail on every API call with a late 501.
+        inferred: set[str] = set()
+        if not caps:
+            browse_methods = self._CAPABILITY_METHODS["library.read"]
+            if all(callable(self.provider_method(provider, m)) for m in browse_methods):
+                # Legacy provider without explicit capabilities — infer library.read
+                # from the presence of all browse methods.  Store in _inferred_caps
+                # so that runtime capability checks see the full effective set.
+                inferred = {"library.read"}
+                caps = inferred
+            else:
+                raise TypeError(
+                    f"library provider {provider_id!r} must declare at least one capability "
+                    f"(or implement the {browse_methods!r} browse methods for backward compatibility)"
+                )
+        for cap, methods in self._CAPABILITY_METHODS.items():
+            if cap not in caps:
+                continue
+            for method_name in methods:
+                if not callable(self.provider_method(provider, method_name)):
+                    raise TypeError(f"library provider {provider_id!r} declares {cap!r} but is missing callable {method_name}()")
+        with self._lock:
+            if provider_id == "local" and provider_id in self._providers and self._providers[provider_id] is not provider:
+                raise ValueError("the local library provider cannot be replaced")
+            if provider_id in self._providers and not replace:
+                raise ValueError(f"library provider {provider_id!r} is already registered")
+            self._providers[provider_id] = provider
+            # owner_plugin_id is attribution that flows into the browser
+            # capability participant id. The scoped register_library_provider
+            # wrappers force it to the trusted loading plugin id, so the spoof
+            # vector is closed there. Here we only normalize: trim and require a
+            # non-empty string. We deliberately do NOT apply the provider-id
+            # grammar (_ID_RE) — plugin ids aren't constrained to it at load
+            # time, so that would silently drop attribution for valid plugins.
+            owner = owner_plugin_id.strip() if isinstance(owner_plugin_id, str) else ""
+            owner = owner or None
+            if owner:
+                self._owner_plugin_ids[provider_id] = owner
+            else:
+                self._owner_plugin_ids.pop(provider_id, None)
+            if inferred:
+                self._inferred_caps[provider_id] = inferred
+            else:
+                self._inferred_caps.pop(provider_id, None)
+        return provider
+
+    def unregister(self, provider_id: str) -> bool:
+        if provider_id == "local":
+            raise ValueError("the local library provider cannot be unregistered")
+        with self._lock:
+            self._inferred_caps.pop(provider_id, None)
+            self._owner_plugin_ids.pop(provider_id, None)
+            return self._providers.pop(provider_id, None) is not None
+
+    def get(self, provider_id: str = "local") -> object | None:
+        with self._lock:
+            return self._providers.get(provider_id or "local")
+
+    def list(self) -> list[dict]:
+        with self._lock:
+            providers = list(self._providers.values())
+        return [self.describe(provider) for provider in providers]
+
+    def describe(self, provider: object) -> dict:
+        provider_id = self.provider_id(provider)
+        with self._lock:
+            owner_plugin_id = self._owner_plugin_ids.get(provider_id)
+        return {
+            "id": provider_id,
+            "label": self.provider_label(provider),
+            "kind": self.provider_field(provider, "kind", "local" if provider_id == "local" else "remote"),
+            "capabilities": sorted(self.provider_capabilities(provider)),
+            "owner_plugin_id": owner_plugin_id,
+            "default": provider_id == "local",
+        }
+
+    def provider_field(self, provider: object, name: str, default=None):
+        if isinstance(provider, dict):
+            return provider.get(name, default)
+        return getattr(provider, name, default)
+
+    def provider_id(self, provider: object) -> str:
+        provider_id = self.provider_field(provider, "id", "")
+        if not isinstance(provider_id, str) or not provider_id:
+            raise ValueError("library provider id must be a non-empty string")
+        return provider_id
+
+    def provider_label(self, provider: object) -> str:
+        label = self.provider_field(provider, "label", self.provider_field(provider, "name", ""))
+        if not isinstance(label, str):
+            return ""
+        return label.strip()
+
+    def _declared_capabilities(self, provider: object) -> set[str]:
+        """Return only the capabilities explicitly declared on the provider object."""
+        raw = self.provider_field(provider, "capabilities", ())
+        if raw is None:
+            raw = ()
+        if isinstance(raw, str):
+            raw = (raw,) if raw else ()
+        return {str(cap) for cap in raw if cap}
+
+    def provider_capabilities(self, provider: object) -> set[str]:
+        # Guard against a common plugin authoring mistake: passing a single string
+        # instead of a list/tuple. Iterating a string produces individual characters,
+        # none of which would match a valid capability name.
+        declared = self._declared_capabilities(provider)
+        # Merge with any capabilities inferred at registration time for legacy
+        # providers that omit the `capabilities` field but implement browse methods.
+        provider_id = self.provider_id(provider)
+        with self._lock:
+            inferred = self._inferred_caps.get(provider_id, set())
+        return declared | inferred
+
+    def provider_method(self, provider: object, name: str):
+        if isinstance(provider, dict):
+            return provider.get(name)
+        return getattr(provider, name, None)
+
+
+# Keys `_library_filter_args` (and a smart collection's stored `rules`) accept.
+_LIBRARY_FILTER_PARAM_KEYS = frozenset((
+    "q", "favorites", "format", "artist", "album",
+    "arrangements_has", "arrangements_lacks", "stems_has", "stems_lacks",
+    "has_lyrics", "tunings",
+))
+
+
+# Rules mirror the raw /api/library query params (so the provider can feed them
+# straight through `_library_filter_args`, and the frontend can build a rule from
+# the same query string it already constructs). Multi-value filters are CSV
+# strings; `favorites` is 0/1; the rest are plain strings.
+_RULE_CSV_KEYS = frozenset((
+    "tunings", "arrangements_has", "arrangements_lacks", "stems_has", "stems_lacks",
+))
+
+
+_RULE_STR_KEYS = frozenset(("q", "format", "artist", "album", "has_lyrics", "sort"))
+
+
+def _sanitize_collection_rules(raw) -> dict:
+    """Normalize rules to the raw query-param format, keeping only known keys. A
+    list for a multi-value filter is joined to CSV; `favorites` becomes 0/1.
+    Unknown keys are dropped so a rule survives a filter-vocab change rather than
+    500-ing. Applied at API ingress AND when a provider loads a persisted row, so
+    a hand-edited / imported bad value (e.g. an int where a string is expected,
+    or a list for `sort`) can never crash a query."""
+    if not isinstance(raw, dict):
+        return {}
+    out: dict = {}
+    for k, v in raw.items():
+        if k in _RULE_CSV_KEYS:
+            if isinstance(v, list):
+                vals = [str(x) for x in v if isinstance(x, (str, int)) and not isinstance(x, bool)]
+            elif isinstance(v, str):
+                vals = [s for s in (p.strip() for p in v.split(",")) if s]
+            else:
+                continue
+            if vals:
+                out[k] = ",".join(vals)
+        elif k == "favorites":
+            if v:
+                out[k] = 1
+        elif k in _RULE_STR_KEYS:
+            if isinstance(v, (str, int)) and not isinstance(v, bool):
+                s = str(v).strip()
+                if s:
+                    out[k] = s
+    return out
+
+
+class SmartCollectionProvider:
+    """A saved library filter, surfaced as a source (#636 item 2). Browse/stats
+    delegate to the local DB with the collection's stored `rules` applied — so
+    selecting it in the v3 source picker shows exactly that filtered slice with
+    the whole Songs UI (paging, stats, A–Z rail, art) for free. P1: the rules
+    ARE the query (live in-collection search is a P2 nicety). The matched songs
+    are local rows, so `kind="local"` keeps the client's play/art paths on the
+    local (not remote-sync) branch and art delegates straight through."""
+    kind = "local"
+    capabilities = ("library.read", "art.read")
+
+    def __init__(self, collection: dict, local: "LocalLibraryProvider"):
+        self._local = local
+        self.update(collection)
+
+    def update(self, collection: dict) -> None:
+        self.id = f"collection:{collection['id']}"
+        self.collection_id = collection["id"]
+        self.label = collection.get("name") or "Collection"
+        # Re-sanitize on load: persisted JSON may predate the current vocab or
+        # have been hand-edited; never let a bad value reach a query.
+        self._rules = _sanitize_collection_rules(collection.get("rules") or {})
+
+    def _filter_kwargs(self) -> dict:
+        return _library_filter_args(**{k: v for k, v in self._rules.items()
+                                       if k in _LIBRARY_FILTER_PARAM_KEYS})
+
+    def _sort(self, fallback: str) -> str:
+        # A collection may pin its own sort (e.g. "recently added"); query_page
+        # falls back safely for an unknown value, so no validation needed here.
+        return self._rules.get("sort") or fallback
+
+    def query_page(self, *, page=0, size=24, sort="artist", direction="asc",
+                   naming_mode="legacy", **_ignore):
+        return self._local._db.query_page(
+            page=page, size=size, sort=self._sort(sort), direction=direction,
+            naming_mode=naming_mode, **self._filter_kwargs())
+
+    def query_artists(self, *, letter="", page=0, size=50, naming_mode="legacy", **_ignore):
+        return self._local._db.query_artists(
+            letter=letter, page=page, size=size, naming_mode=naming_mode,
+            **self._filter_kwargs())
+
+    def query_albums(self, *, page=0, size=120, naming_mode="legacy", **_ignore):
+        return self._local._db.query_albums(
+            page=page, size=size, naming_mode=naming_mode, **self._filter_kwargs())
+
+    def query_stats(self, *, sort="artist", want_sort_letters=False,
+                    naming_mode="legacy", **_ignore):
+        return self._local._db.query_stats(
+            sort=self._sort(sort), want_sort_letters=want_sort_letters,
+            naming_mode=naming_mode, **self._filter_kwargs())
+
+    def tuning_names(self):
+        return self._local.tuning_names()
+
+    async def get_art(self, song_id: str):
+        return await self._local.get_art(song_id)
+
+
+def _split_csv(raw: str) -> list[str]:
+    """Parse a comma-separated query-string list. Empty / whitespace-only
+    entries are dropped so `arrangements_has=` (no value) and
+    `arrangements_has=,` both mean 'no filter'."""
+    if not raw:
+        return []
+    return [s.strip() for s in raw.split(",") if s.strip()]
+
+
+def _parse_has_lyrics(raw: str) -> int | None:
+    """Tri-state parse for has_lyrics. `1` → require, `0` → exclude,
+    anything else (including empty) → no filter."""
+    if raw == "1":
+        return 1
+    if raw == "0":
+        return 0
+    return None
+
+
+def _library_filter_args(q: str = "", favorites: int = 0, format: str = "",
+                         artist: str = "", album: str = "",
+                         arrangements_has: str = "", arrangements_lacks: str = "",
+                         stems_has: str = "", stems_lacks: str = "",
+                         has_lyrics: str = "", tunings: str = "") -> dict:
+    fmt = format if format in ("archive", "sloppak", "loose") else ""
+    return {
+        "q": q,
+        "favorites_only": bool(favorites),
+        "format_filter": fmt,
+        "artist_filter": (artist or "").strip(),
+        "album_filter": (album or "").strip(),
+        "arrangements_has": _split_csv(arrangements_has),
+        "arrangements_lacks": _split_csv(arrangements_lacks),
+        "stems_has": _split_csv(stems_has),
+        "stems_lacks": _split_csv(stems_lacks),
+        "has_lyrics": _parse_has_lyrics(has_lyrics),
+        "tunings": _split_csv(tunings),
+    }
+
+
+def _sync_collection_provider(collection: dict) -> None:
+    """Register (or replace) the provider for one collection."""
+    appstate.library_providers.register(
+        SmartCollectionProvider(collection, appstate.local_library_provider), replace=True)
+
+
+def _unregister_collection_provider(pid: int) -> None:
+    appstate.library_providers.unregister(f"collection:{pid}")

lib/reqfields.py

@@ -0,0 +1,13 @@
+"""Request-field coercion helpers shared by the raw-`dict` POST handlers.
+
+Extracted verbatim from ``server.py`` (R3). Pure — no IO, no globals — so it
+imports cleanly from both ``server`` and any ``routers/`` module.
+"""
+
+
+def _clean_str(value) -> str:
+    """Trim a request field to a string; non-strings (or missing) → ''.
+    Lets the raw-`dict` POST handlers treat wrong-typed JSON (an int/list/etc.
+    where a string was expected) as "empty" and answer 400, instead of raising
+    AttributeError/TypeError → 500 on a later .strip()/`in`."""
+    return value.strip() if isinstance(value, str) else ""

lib/routers/__init__.py

@@ -0,0 +1,31 @@
+"""FastAPI route modules extracted from ``server.py`` (R3).
+
+Each module here exposes a module-level ``router`` (a ``fastapi.APIRouter``)
+that ``server.py`` mounts with ``app.include_router(...)`` at the point in the
+file where those routes used to be defined — FastAPI matches routes in
+registration order, so keeping the mount site preserves it.
+
+**Routers must never ``import server``.** They reach core singletons through
+the injected seam instead::
+
+    import appstate
+
+    @router.get("/api/thing")
+    def get_thing():
+        return appstate.meta_db.thing()
+
+and always as a **module attribute, at call time** — never
+``from appstate import meta_db``, which freezes the binding and defeats both a
+later ``appstate.configure()`` and ``monkeypatch.setattr``. See ``appstate.py``.
+
+Dependencies flow one way: ``server -> routers -> appstate``.
+
+**Why this lives under ``lib/``.** ``lib/`` is the only core directory every
+packaging path already copies wholesale — the Dockerfile (``COPY lib/``),
+``docker-compose.yml``, and feedback-desktop's ``bundle-slopsmith.sh``
+(``cp -r lib``) — and all three put it on ``sys.path``. A root-level package
+ships in Docker but is silently dropped from the packaged desktop app, whose
+bundler copies a hardcoded file list. Route modules import nothing at module
+scope beyond FastAPI and ``appstate``, so they do no import-time IO and satisfy
+Principle V's rule for ``lib/``.
+"""

lib/routers/art.py

@@ -0,0 +1,513 @@
+"""Album-art routes: serve / cover-search / candidates / upload / url / remove
+(/api/song/{filename}/art*, /api/art/{filename}/override).
+
+Extracted verbatim from server.py (R3). Only the decorators (@app -> @router) and
+the seam reads change: meta_db -> appstate.meta_db, ART_CACHE_DIR ->
+appstate.art_cache_dir, and the three shared art helpers that stay in server.py
+(they are also used by the song/delete routes) -> appstate.<callable>
+(_song_pack_art_exists, _art_override_paths, _art_safe_name). The CAA / release
+search transport lives in lib/enrichment.py and is reached as enrichment.X.
+"""
+
+import asyncio
+import hashlib
+import ipaddress
+from pathlib import Path
+
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import FileResponse, JSONResponse, Response
+
+import appstate
+import enrichment
+import loosefolder as loosefolder_mod
+import sloppak as sloppak_mod
+from dlc_paths import _get_dlc_dir, _resolve_dlc_path
+
+import logging
+log = logging.getLogger("feedBack.server")
+router = APIRouter()
+
+def _if_none_match_hits(header: str | None, etag: str) -> bool:
+    """True if an If-None-Match header matches `etag` (weak comparison).
+
+    Handles the `*` wildcard and comma-separated lists, and ignores a weak
+    `W/` prefix on either side — the standard semantics for a conditional GET.
+    """
+    if not header:
+        return False
+    bare = etag.removeprefix("W/")
+    for tok in header.split(","):
+        t = tok.strip()
+        if t == "*" or t.removeprefix("W/") == bare:
+            return True
+    return False
+
+
+# Album art is served with a strong validator (an ETag on the sloppak byte
+# path; FileResponse's own ETag/Last-Modified on the file paths) and revalidated
+# with `no-cache`. That keeps re-scroll cheap — a conditional GET returns a
+# bodyless 304 — without ever serving a stale cover. A long `immutable` max-age
+# was rejected: the frontend's `?v=<mtime>` buster is only second-resolution, so
+# a same-second cover rewrite would keep the URL and pin the old bytes for the
+# cache lifetime. Validation cost is negligible for a localhost backend.
+_ART_CACHE_HEADERS = {"Cache-Control": "no-cache"}
+
+
+def _art_etag(path: Path) -> str | None:
+    """Strong validator for an art file: nanosecond mtime + size (so a
+    same-second rewrite still changes it). None if the file can't be stat'd."""
+    try:
+        st = path.stat()
+        return f'"{st.st_mtime_ns}-{st.st_size}"'
+    except OSError:
+        return None
+
+
+def _art_conditional(etag: str | None, request: Request | None):
+    """Return (headers, not_modified) for an art response. `not_modified` is
+    True when the client's If-None-Match already matches `etag` → caller should
+    return a bodyless 304. Starlette's FileResponse emits an ETag but does NOT
+    itself evaluate If-None-Match, so every art path routes through here to get
+    real conditional handling."""
+    headers = dict(_ART_CACHE_HEADERS)
+    if etag:
+        headers["ETag"] = etag
+    inm = request.headers.get("if-none-match") if request is not None else None
+    return headers, bool(etag) and _if_none_match_hits(inm, etag)
+
+
+def _file_art_response(path: Path, media_type: str, request: Request | None):
+    """FileResponse for an on-disk art file, with no-cache + ETag and a bodyless
+    304 when the client's validator still matches."""
+    headers, not_modified = _art_conditional(_art_etag(path), request)
+    if not_modified:
+        return Response(status_code=304, headers=headers)
+    return FileResponse(str(path), media_type=media_type, headers=headers)
+
+
+@router.get("/api/song/{filename:path}/art")
+async def get_song_art(filename: str, request: Request = None, source: str = ""):
+    """Serve album art for a song, walking the R3 override chain:
+
+      1. USER OVERRIDE (upload / URL-fetch, {safe_name}.gif|.png in the art
+         cache) — art the user explicitly pinned outranks everything, pack
+         art included. GIF is allowed HERE only: an animated cover is a
+         local-only bonus; packs stay jpg/png/webp and nothing ever writes
+         art into a pack file.
+      2. PACK ART — sloppak cover (single member read, no full unpack) or
+         the loose folder's discovered image.
+      3. COVER ART ARCHIVE cache — fetched by the enrichment art worker for
+         matched songs that lack pack art, keyed by release MBID.
+
+    `?source=pack` narrows the chain to step 2 only (no override, no CAA):
+    the cover picker's "Pack original" tile must show the pack's own art
+    even while a user override is what the plain route serves. 404 when the
+    song ships no art of its own.
+    """
+    dlc = _get_dlc_dir()
+    if not dlc:
+        return JSONResponse({"error": "not configured"}, 404)
+
+    song_path = _resolve_dlc_path(dlc, filename)
+    if song_path is None:
+        return JSONResponse({"error": "forbidden"}, 403)
+    if not song_path.exists():
+        return JSONResponse({"error": "not found"}, 404)
+
+    pack_only = source == "pack"
+
+    # 1. User override — GIF first (it wins over a stale PNG override).
+    if not pack_only:
+        for cached in appstate.art_override_paths(filename):
+            mt = "image/gif" if cached.suffix == ".gif" else "image/png"
+            return _file_art_response(cached, mt, request)
+
+    # 2a. Sloppak: read the cover (manifest-declared or default) straight from
+    # the package. For a zip-form sloppak this opens just the cover member —
+    # NOT the whole archive — so the library grid never triggers a full unpack
+    # of stems just to paint a thumbnail.
+    if sloppak_mod.is_sloppak(song_path):
+        # Read the cover (cheap — single member, no full unpack) and validate by
+        # its CONTENT. A stat-based ETag would be wrong for directory-form
+        # sloppaks: editing cover.jpg in place changes the file's mtime, not the
+        # directory's, so a dir-stat ETag could emit a stale 304. Content hashing
+        # is correct for both dir- and zip-form. Raw byte Response lacks
+        # FileResponse's validators, so we attach the ETag + honor If-None-Match.
+        try:
+            art = await asyncio.to_thread(sloppak_mod.read_cover_bytes, song_path)
+        except Exception:
+            art = None
+        if art is not None:
+            data, mt = art
+            etag = f'"{hashlib.sha1(data).hexdigest()}"'
+            headers, not_modified = _art_conditional(etag, request)
+            if not_modified:
+                return Response(status_code=304, headers=headers)
+            return Response(content=data, media_type=mt, headers=headers)
+
+    # 2b. Loose folder: serve the discovered art file directly.
+    # song_path is already validated against DLC_DIR by _resolve_dlc_path.
+    elif loosefolder_mod.is_loose_song(song_path):
+        art_path = loosefolder_mod.find_art(song_path)
+        if art_path:
+            # Re-resolve in case the matched file is a symlink — a crafted
+            # custom song could put `album_art.jpg` as a symlink to anywhere on
+            # disk. Insist the final target stays inside the song folder.
+            art_resolved = art_path.resolve()
+            try:
+                art_resolved.relative_to(song_path)
+            except ValueError:
+                return JSONResponse({"error": "forbidden"}, 403)
+            if art_resolved.is_file():
+                mt = {
+                    ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
+                    ".png": "image/png", ".webp": "image/webp",
+                }.get(art_resolved.suffix.lower(), "image/jpeg")
+                return _file_art_response(art_resolved, mt, request)
+
+    # 3. Cover Art Archive cache (the enrichment art worker's fetch).
+    if not pack_only:
+        row = appstate.meta_db.get_enrichment(filename)
+        if row and row.get("art_state") == "caa" and row.get("art_cache_path"):
+            caa = Path(row["art_cache_path"])
+            if caa.is_file():
+                return _file_art_response(caa, "image/jpeg", request)
+
+    return JSONResponse({"error": "no art"}, 404)
+
+
+# ── Cover picker (PR-C): candidate assembly ───────────────────────────────────
+# Enumerated ON OPEN, never at scan time (charrette §8), and NO image bytes
+# are fetched here — Cover Art Archive release INDEX jsons only (1-3 throttled
+# calls on a cache miss); the tiles' thumbnails load straight from the archive
+# in the client. Applying a pick never grows a new write path: the client
+# POSTs the chosen thumb URL to the EXISTING …/art/url route (the override
+# lane — never evicted, survives a re-match), "Pack original" DELETEs the
+# override, uploads keep the existing upload route.
+_ART_PICKER_MAX_CAA = 12
+
+
+@router.get("/api/song/{filename:path}/art/cover-search")
+def api_art_cover_search(filename: str, q: str = ""):
+    """Search Cover Art Archive (via MusicBrainz release-groups) for album covers
+    — powers the Change-cover picker's search box, so a cover can be found even
+    for a song with no metadata match (the unmatched city-pop pile, where
+    /art/candidates is empty). `q` defaults to the song's own artist + album/
+    title (romaji fallback applied). Read-only; the picker renders the thumbs and
+    applies a pick through the existing /art/url route."""
+    query = (q or "").strip()
+    if not query:
+        pack = appstate.meta_db.pack_fields(appstate.meta_db._canonical_song_filename(filename))
+        query = " ".join(x for x in (pack.get("artist"), pack.get("album") or pack.get("title")) if x).strip()
+    if not query:
+        return {"query": "", "covers": []}
+    try:
+        return {"query": query, "covers": enrichment._mb_search_release_groups(query, limit=8)}
+    except enrichment.EnrichTransportError:
+        return {"query": query, "covers": [], "error": "unavailable"}
+
+
+@router.get("/api/song/{filename:path}/art/candidates")
+def get_song_art_candidates(filename: str):
+    """Everything the cover picker can offer for one song, without fetching a
+    single image: the current cover (with its provenance), the pack original
+    when the song ships art, and CAA candidates for the matched/manual
+    release plus any distinct releases among the stored review candidates.
+    Sync route on purpose (the CAA index fetch sleeps in the shared
+    throttle — FastAPI runs `def` routes in the threadpool). One response,
+    `pending` always False — the client shows a spinner for the request's own
+    latency; offline / CAA-down just means an empty caa tail (the instant
+    tiles keep working), never an error."""
+    from urllib.parse import quote
+    dlc = _get_dlc_dir()
+    song_path = _resolve_dlc_path(dlc, filename) if dlc else None
+    if song_path is None or not song_path.exists():
+        raise HTTPException(status_code=404, detail="unknown song")
+
+    row = appstate.meta_db.get_enrichment(filename) or {}
+    has_pack = appstate.song_pack_art_exists(filename)
+    art_url = f"/api/song/{quote(filename)}/art"
+
+    # What the plain art route would serve right now — the serve chain's
+    # order (override > pack > CAA cache) restated as provenance.
+    if appstate.art_override_paths(filename):
+        provenance = "yours"
+    elif has_pack:
+        provenance = "pack"
+    elif row.get("art_state") == "caa" and row.get("art_cache_path"):
+        provenance = "matched"
+    else:
+        provenance = "none"
+
+    candidates: list[dict] = [{
+        "id": "current", "kind": "current", "label": "Current",
+        "thumb_url": art_url, "provenance": provenance,
+    }]
+    if has_pack:
+        candidates.append({
+            "id": "pack", "kind": "pack", "label": "Pack original",
+            "thumb_url": art_url + "?source=pack", "provenance": "pack",
+        })
+
+    # Releases worth asking the archive about: the matched/manual release
+    # first (it seeds the best candidates), then any distinct release among
+    # the stored review candidates (a review row has no mb_release_id of its
+    # own — its releases live in the candidates JSON).
+    # Only spend the shared CAA rate budget on rows whose match warrants it:
+    # a matched/manual release seeds the best candidates, and a review row's
+    # stored candidates are still live proposals. A failed/rejected (or
+    # unscanned) row has no accepted match — asking would burn the budget and
+    # surface releases already rejected as non-matches. The Current + Pack
+    # tiles above serve regardless, so those songs still get a picker.
+    rids: list[str] = []
+    if row.get("match_state") in ("matched", "manual", "review"):
+        if row.get("match_state") in ("matched", "manual") and row.get("mb_release_id"):
+            rids.append(str(row["mb_release_id"]))
+        for cand in (row.get("candidates") or []):
+            rid = str(cand.get("release_id") or "") if isinstance(cand, dict) else ""
+            if rid and rid not in rids:
+                rids.append(rid)
+
+    caa_entries: list[dict] = []
+    for rid in rids:
+        if len(caa_entries) >= _ART_PICKER_MAX_CAA:
+            break
+        try:
+            imgs = enrichment._caa_index_cached(rid)
+        except enrichment.EnrichTransportError:
+            # Offline / archive down — stop asking (each further miss would
+            # only burn a timeout). The instant tiles still serve; a later
+            # picker-open retries naturally (failures are never cached).
+            break
+        # Front covers first, approved before pending, otherwise index order
+        # (the picker grammar is a RANKED list — §7/§9).
+        def _rank(img):
+            types = img.get("types") or []
+            is_front = bool(img.get("front")) or "Front" in types
+            return (not is_front, not bool(img.get("approved")))
+        for img in sorted((i for i in imgs if isinstance(i, dict)), key=_rank):
+            if len(caa_entries) >= _ART_PICKER_MAX_CAA:
+                break
+            thumbs = img.get("thumbnails") or {}
+            if not isinstance(thumbs, dict):
+                continue
+            thumb = (thumbs.get("500") or thumbs.get("large")
+                     or thumbs.get("250") or thumbs.get("small"))
+            if not thumb:
+                continue
+            types = [str(t) for t in (img.get("types") or []) if isinstance(t, str)]
+            caa_entries.append({
+                "id": f"caa-{rid}-{img.get('id', '')}",
+                "kind": "caa",
+                "label": ", ".join(types) or "Cover",
+                "thumb_url": str(thumb),
+                "provenance": "matched",
+                "types": types,
+                "approved": bool(img.get("approved")),
+                "release_id": rid,
+            })
+
+    return {"candidates": candidates + caa_entries, "pending": False}
+
+
+def _save_art_override(filename: str, img_data: bytes) -> dict:
+    """Persist a user art override into the art cache (R3). One override per
+    song: GIF input is validated and kept VERBATIM as .gif (animation intact —
+    the local-only bonus; it is never written into the pack file), everything
+    else is normalized to RGB PNG via PIL. Saving either kind removes the
+    other so the serve chain has exactly one user file to find."""
+    appstate.art_cache_dir.mkdir(parents=True, exist_ok=True)
+    stem = appstate.art_safe_name(filename)
+    png_path = appstate.art_cache_dir / f"{stem}.png"
+    gif_path = appstate.art_cache_dir / f"{stem}.gif"
+    from PIL import Image
+    import io as _io
+    if img_data[:6] in (b"GIF87a", b"GIF89a"):
+        try:
+            probe = Image.open(_io.BytesIO(img_data))
+            probe.verify()   # decodes headers/frames without keeping the image
+            if probe.format != "GIF":
+                raise ValueError("not a GIF")
+        except Exception as e:
+            return {"error": f"Invalid image: {e}"}
+        gif_path.write_bytes(img_data)
+        png_path.unlink(missing_ok=True)
+        return {"ok": True, "kind": "gif"}
+    try:
+        img = Image.open(_io.BytesIO(img_data)).convert("RGB")
+        img.save(str(png_path), "PNG")
+    except Exception as e:
+        return {"error": f"Invalid image: {e}"}
+    gif_path.unlink(missing_ok=True)
+    return {"ok": True, "kind": "png"}
+
+
+@router.post("/api/song/{filename:path}/art/upload")
+async def upload_song_art_b64(filename: str, data: dict):
+    """Upload a custom cover as base64 (PNG/JPG/WebP → normalized PNG;
+    GIF → kept animated, local-only). The override outranks pack art in the
+    serve chain; remove it via DELETE …/art/override."""
+    import base64
+    # Reject art for a filename that doesn't resolve to a real song (mirrors the
+    # url route's guard) — no writing stray override files for unknown keys.
+    dlc = _get_dlc_dir()
+    song_path = _resolve_dlc_path(dlc, filename) if dlc else None
+    if song_path is None or not song_path.exists():
+        raise HTTPException(status_code=404, detail="unknown song")
+    b64 = data.get("image", "")
+    if not b64:
+        return {"error": "No image data"}
+    # Strip data URL prefix if present
+    if "," in b64:
+        b64 = b64.split(",", 1)[1]
+    try:
+        img_data = base64.b64decode(b64)
+    except Exception:
+        return {"error": "Invalid base64"}
+    if len(img_data) > _ART_URL_MAX_BYTES:
+        raise HTTPException(status_code=400, detail="image larger than 10 MB")
+    return _save_art_override(filename, img_data)
+
+
+# Art-by-URL fetch cap — a cover, not a wallpaper pack.
+_ART_URL_MAX_BYTES = 10 * 1024 * 1024
+
+
+def _url_host_is_internal(url: str) -> bool:
+    """True when a user-supplied URL's host resolves to a loopback, private,
+    link-local, reserved, multicast or unspecified address — an SSRF target we
+    refuse to fetch on the user's behalf (e.g. 169.254.169.254 metadata, LAN
+    services). Fails CLOSED: an unresolvable or unparseable host is treated as
+    internal. Every resolved address must be public for the URL to pass."""
+    from urllib.parse import urlparse
+    import socket
+    host = urlparse(url).hostname
+    if not host:
+        return True
+    try:
+        infos = socket.getaddrinfo(host, None)
+    except OSError:
+        return True
+    if not infos:
+        return True
+    for info in infos:
+        raw = info[4][0].split("%", 1)[0]  # strip any zone id
+        try:
+            ip = ipaddress.ip_address(raw)
+        except ValueError:
+            return True
+        if (ip.is_private or ip.is_loopback or ip.is_link_local
+                or ip.is_reserved or ip.is_multicast or ip.is_unspecified):
+            return True
+    return False
+
+
+# Art-by-URL redirect budget. Cover hosts commonly answer with a redirect —
+# the Cover Art Archive (whose thumbs the cover picker applies through this
+# very route) 307s every image to archive.org — so redirects must work; 5
+# hops is generous for any real CDN chain while still bounding the walk.
+_ART_URL_MAX_REDIRECTS = 5
+
+
+def _fetch_art_url(url: str) -> bytes:
+    """The one place art-by-URL touches the network (tests fake this seam).
+    User-initiated, so not throttled like the background workers — but the
+    same offline guard applies (pytest can never fetch), the host is checked
+    against internal/reserved ranges (SSRF), redirects are followed MANUALLY
+    with the scheme + internal-host guard re-applied to every hop (so a
+    redirect can't smuggle the request to an internal target — a blanket
+    no-redirect rule would break every Cover Art Archive pick, which always
+    redirects to archive.org), and the size cap is enforced while streaming
+    so a huge response never fully downloads.
+
+    Residual, accepted: each hop's host is resolved here and again by
+    requests, so a rebinding DNS name is a theoretical TOCTOU. Not closed
+    with an IP-pinned connection because (a) this is a single-user, no-auth
+    app (constitution §I) and the route is demo-blocked, so there is no
+    untrusted submission path, and (b) no other in-tree client (MusicBrainz,
+    CAA) pins either — a bespoke pinned+SNI adapter here would be
+    inconsistent and disproportionate. The cheap guards above still stop the
+    realistic vectors (direct internal URL, redirect-to-internal)."""
+    if not enrichment._enrich_network_enabled():
+        raise enrichment.EnrichTransportError("art fetch disabled (offline)")
+    import requests
+    from urllib.parse import urljoin, urlparse
+    for _hop in range(_ART_URL_MAX_REDIRECTS + 1):
+        # Re-validate EVERY hop, not just the user's original URL: the whole
+        # point of handling redirects ourselves is that each target gets the
+        # same scheme + SSRF gate before any request is made.
+        if urlparse(url).scheme not in ("http", "https"):
+            raise ValueError("url must be http(s)")
+        if _url_host_is_internal(url):
+            raise ValueError("url host is not allowed")
+        try:
+            with requests.get(url, timeout=15, stream=True, allow_redirects=False,
+                              headers={"User-Agent": enrichment._enrich_user_agent()}) as resp:
+                if resp.status_code in (301, 302, 303, 307, 308):
+                    loc = resp.headers.get("Location") or ""
+                    if not loc:
+                        raise enrichment.EnrichTransportError(
+                            f"HTTP {resp.status_code} without a Location")
+                    url = urljoin(url, loc)
+                    continue
+                if resp.status_code != 200:
+                    raise enrichment.EnrichTransportError(f"HTTP {resp.status_code}")
+                data = b""
+                for chunk in resp.iter_content(65536):
+                    data += chunk
+                    if len(data) > _ART_URL_MAX_BYTES:
+                        raise ValueError("image larger than 10 MB")
+                return data
+        except requests.RequestException as e:
+            raise enrichment.EnrichTransportError(str(e)) from e
+    raise enrichment.EnrichTransportError("too many redirects")
+
+
+@router.post("/api/song/{filename:path}/art/url")
+def set_song_art_from_url(filename: str, data: dict):
+    """Paste-a-link cover art (the media-server idiom): the server fetches the
+    image and stores it as this song's local override — identical result to an
+    upload, including the GIF-stays-local rule. http(s) only."""
+    url = str((data or {}).get("url") or "").strip()
+    from urllib.parse import urlparse
+    parsed = urlparse(url)
+    if parsed.scheme not in ("http", "https") or not parsed.hostname:
+        raise HTTPException(status_code=400, detail="url must be http(s)")
+    dlc = _get_dlc_dir()
+    song_path = _resolve_dlc_path(dlc, filename) if dlc else None
+    if song_path is None or not song_path.exists():
+        raise HTTPException(status_code=404, detail="unknown song")
+    try:
+        img_data = _fetch_art_url(url)
+    except enrichment.EnrichTransportError as e:
+        return JSONResponse({"error": "could not fetch image", "detail": str(e)},
+                            status_code=502)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    return _save_art_override(filename, img_data)
+
+
+@router.delete("/api/art/{filename:path}/override")
+def remove_song_art_override(filename: str):
+    """Drop the user art override — the serve chain falls back to pack art,
+    then the Cover Art Archive cache. Lives under /api/art (NOT /api/song) so
+    the greedy DELETE /api/song/{path} catch-all can't shadow it — the same
+    dodge the chart split/unsplit routes use."""
+    removed = False
+    for p in appstate.art_override_paths(filename):
+        try:
+            p.unlink()
+            removed = True
+        except OSError:
+            pass
+    if removed:
+        # The art worker may have settled this row as 'user' (override present,
+        # no pack art). Reset it so the next enrichment pass re-evaluates and the
+        # CAA fallback resumes — otherwise a removed override strands the row
+        # (enrichment_art_pending only re-queues art_state IS NULL) and the song
+        # is left with no art at all.
+        try:
+            appstate.meta_db.set_enrichment_art(filename, None, None)
+        except Exception:
+            log.exception("art override delete: failed to reset enrichment state")
+    return {"ok": True, "removed": removed}

lib/routers/artist.py

@@ -0,0 +1,126 @@
+"""Artist routes: the artist page + external-links payload
+(/api/artist/{name}/page, /links, /links/refresh).
+
+Extracted verbatim from server.py (R3) except @app->@router and the seam reads
+(meta_db->appstate.meta_db, CONFIG_DIR->appstate.config_dir, _default_settings->
+appstate.default_settings). MusicBrainz link enrichment is reached as
+enrichment.X; the shared URL-safety validator lives in lib/library_registry.py.
+"""
+
+from fastapi import APIRouter
+
+import appstate
+import enrichment
+from appconfig import _load_config
+from library_registry import _safe_art_redirect_url
+
+import logging
+log = logging.getLogger("feedBack.server")
+router = APIRouter()
+
+# MB artist url-relation types → the page's link slots (locked position 4:
+# whitelist only, links-only forever). Everything not listed is dropped.
+_ARTIST_URL_REL_SLOTS = {
+    "official homepage": "official",
+    "setlistfm": "tour",
+    "concerts": "tour",
+    "youtube": "video",
+    "video channel": "video",
+    "social network": "social",
+    "bandcamp": "social",
+    "soundcloud": "social",
+    "wikipedia": "wikipedia",
+    "wikidata": "wikipedia",
+}
+
+
+def _artist_links_from_mb(body: dict) -> tuple[dict, list]:
+    """Whitelist an MB artist doc's url-relations into the page's link slots:
+    {official, tour, video, social: [...], wikipedia}. Every URL passes the
+    same http(s)-scheme gate as art redirects (_safe_art_redirect_url) so a
+    hostile javascript:/data:/file: resource can never reach an href. First
+    URL wins per single slot; social collects up to 5; wikipedia is preferred
+    over wikidata when both exist. Also returns MB's genre names (capped)."""
+    links: dict = {}
+    social: list = []
+    wikidata_url = None
+    for rel in (body or {}).get("relations") or []:
+        if not isinstance(rel, dict):
+            continue
+        rtype = str(rel.get("type") or "").strip().lower()
+        slot = _ARTIST_URL_REL_SLOTS.get(rtype)
+        if not slot:
+            continue
+        url = rel.get("url")
+        url = url.get("resource") if isinstance(url, dict) else url
+        if _safe_art_redirect_url(url) is None:
+            continue
+        if slot == "social":
+            if url not in social and len(social) < 5:
+                social.append(url)
+        elif rtype == "wikidata":
+            wikidata_url = wikidata_url or url
+        elif slot not in links:
+            links[slot] = url
+    if social:
+        links["social"] = social
+    if "wikipedia" not in links and wikidata_url:
+        links["wikipedia"] = wikidata_url
+    genres = [str(g.get("name")) for g in (body or {}).get("genres") or []
+              if isinstance(g, dict) and g.get("name")]
+    return links, genres[:8]
+
+
+def _artist_links_payload(name: str, force: bool = False) -> dict:
+    """Shared by GET links + POST refresh. Order of gates: the user's opt-in
+    setting (external links are OFF by default — the dev-chat thread's call),
+    then a known mb_artist_id (no id → nothing to look up), then the cache
+    (unless force), then the offline guard, then ONE throttled fetch."""
+    cfg = _load_config(appstate.config_dir / "config.json") or appstate.default_settings()
+    if cfg.get("artist_external_links") is not True:
+        return {"links": {}, "matched": False, "disabled": True}
+    canonical = appstate.meta_db._terminal_canonical((name or "").strip())
+    mbid = appstate.meta_db.artist_known_mb_id(appstate.meta_db._raw_variants_for(canonical))
+    mbid = (mbid or "").strip().lower()
+    # The id is interpolated into the MB request path — same strict-shape rule
+    # as the manifest identity keys (_MBID_RE), so a junk/hostile value stored
+    # via a hand-rolled /pick body can never reach the request line.
+    if not mbid or not enrichment._MBID_RE.match(mbid):
+        return {"links": {}, "matched": False}
+    if not force:
+        cached = appstate.meta_db.get_artist_enrichment(mbid)
+        if cached:
+            return {"links": cached["url_rels"], "genres": cached["genres"],
+                    "matched": True, "cached": True, "mb_artist_id": mbid}
+    if not enrichment._enrich_network_enabled():
+        return {"links": {}, "matched": True, "offline": True, "mb_artist_id": mbid}
+    try:
+        body = enrichment._mb_http_get(f"artist/{mbid}", {"inc": "url-rels+genres+tags"})
+    except enrichment.EnrichTransportError:
+        return {"links": {}, "matched": True, "offline": True, "mb_artist_id": mbid}
+    links, genres = _artist_links_from_mb(body or {})
+    appstate.meta_db.put_artist_enrichment(mbid, links, genres)
+    return {"links": links, "genres": genres, "matched": True, "cached": False,
+            "mb_artist_id": mbid}
+
+
+@router.get("/api/artist/{name:path}/page")
+def api_artist_page(name: str):
+    """The artist page's all-LOCAL payload — counts, albums, aliases, similar-
+    in-library, mosaic art, play-all seed. Never touches the network; an
+    unmatched or even unknown artist still returns a functional page."""
+    return appstate.meta_db.artist_page(name)
+
+
+@router.get("/api/artist/{name:path}/links")
+def api_artist_links(name: str):
+    """External links for a matched artist — cached after the first call.
+    Sync route on purpose (like /api/enrichment/search): FastAPI runs it in
+    the threadpool so the MB throttle's sleep never blocks the event loop."""
+    return _artist_links_payload(name)
+
+
+@router.post("/api/artist/{name:path}/links/refresh")
+def api_artist_links_refresh(name: str):
+    """Explicit re-fetch of the cached links (the page's manual Refresh)."""
+    return _artist_links_payload(name, force=True)

lib/routers/artist_aliases.py

@@ -0,0 +1,68 @@
+"""Artist aliases / Tidy-up (P4) — canonicalize messy artist tags at DISPLAY
+("ACDC" -> "AC/DC") without touching feedpak files or the scanner-derived
+songs.artist. All DB-only.
+
+Extracted verbatim from ``server.py`` (R3); only the decorator receiver
+(``@app`` -> ``@router``) and the singleton read (``meta_db`` ->
+``appstate.meta_db``) changed. The read stays a module attribute so a re-imported
+``server`` re-publishes a fresh DB into the seam — see ``appstate.py``.
+"""
+
+from fastapi import APIRouter
+from fastapi.responses import JSONResponse
+
+import appstate
+
+router = APIRouter()
+
+
+@router.get("/api/artist-aliases")
+def list_artist_aliases():
+    """Existing raw→canonical overrides (the Tidy-up 'current merges' list)."""
+    return {"aliases": appstate.meta_db.list_artist_aliases()}
+
+
+@router.get("/api/artists/raw")
+def list_raw_artists(limit: int = 2000):
+    """Distinct RAW artist names + song counts + current canonical — the Tidy-up
+    picker (you merge raw variants into one canonical)."""
+    return {"artists": appstate.meta_db.raw_artists(limit)}
+
+
+@router.post("/api/artist-aliases")
+def set_artist_alias(data: dict):
+    """Upsert one override: {raw_name, canonical_name, mb_artist_id?}. A self-alias
+    (raw == canonical) clears the row instead (un-merge)."""
+    raw = (data.get("raw_name") or "").strip()
+    canon = (data.get("canonical_name") or "").strip()
+    if not raw or not canon:
+        return JSONResponse({"error": "raw_name and canonical_name are required"}, 400)
+    result = appstate.meta_db.set_artist_alias(raw, canon, (data.get("mb_artist_id") or None))
+    if not result.get("ok"):
+        # Would form a cycle (raw → … → raw) — refuse rather than corrupt the chain.
+        return JSONResponse(
+            {"error": "alias would create a cycle", "raw_name": raw, "canonical_name": canon},
+            409)
+    return {"ok": True, "raw_name": raw, "canonical_name": result.get("canonical_name", canon)}
+
+
+@router.post("/api/artist-aliases/merge")
+def merge_artist_aliases(data: dict):
+    """Merge several raw artist variants into one canonical:
+    {raw_names: [...], canonical_name}. The canonical's own self-alias is skipped.
+    Returns {merged: N}."""
+    canon = (data.get("canonical_name") or "").strip()
+    raws = data.get("raw_names")
+    if not canon:
+        return JSONResponse({"error": "canonical_name is required"}, 400)
+    if not isinstance(raws, list) or not raws:
+        return JSONResponse({"error": "raw_names must be a non-empty array"}, 400)
+    n = appstate.meta_db.merge_artists(raws, canon)
+    return {"merged": n, "canonical_name": canon}
+
+
+@router.delete("/api/artist-aliases/{raw_name:path}")
+def delete_artist_alias(raw_name: str):
+    """Remove one override so that raw artist stands on its own again."""
+    appstate.meta_db.remove_artist_alias(raw_name)
+    return {"ok": True}

lib/routers/audio_effects.py

@@ -0,0 +1,80 @@
+"""Audio-effects mapping API — the core-owned song/tone -> provider routing index.
+
+Extracted verbatim from ``server.py`` (R3); only the decorator receiver
+(``@app`` -> ``@router``) and the singleton read (``audio_effect_mappings`` ->
+``appstate.audio_effect_mappings``) changed. The read must stay a module
+attribute so a re-imported ``server`` re-publishes a fresh DB into the seam and
+`monkeypatch.setattr` reaches this module — see ``appstate.py``.
+"""
+
+from fastapi import APIRouter, Body, Query
+from fastapi.responses import JSONResponse
+
+import appstate
+
+router = APIRouter()
+
+
+def _audio_effects_error(exc: Exception):
+    return JSONResponse({"error": str(exc)}, status_code=400)
+
+
+@router.get("/api/audio-effects/mappings")
+def list_audio_effect_mappings(
+    song_key: str = Query(""),
+    filename: str = Query(""),
+    tone_key: str = Query(""),
+    provider_id: str = Query(""),
+):
+    try:
+        return {
+            "mappings": appstate.audio_effect_mappings.list(
+                song_key=song_key,
+                filename=filename,
+                tone_key=tone_key,
+                provider_id=provider_id,
+            )
+        }
+    except ValueError as exc:
+        return _audio_effects_error(exc)
+
+
+@router.post("/api/audio-effects/mappings")
+def upsert_audio_effect_mapping(data: dict = Body(...)):
+    try:
+        mapping = appstate.audio_effect_mappings.upsert(data)
+    except ValueError as exc:
+        return _audio_effects_error(exc)
+    return {"ok": True, "mapping": mapping}
+
+
+@router.delete("/api/audio-effects/mappings/{mapping_id}")
+def delete_audio_effect_mapping(mapping_id: int, provider_id: str = Query("")):
+    try:
+        deleted = appstate.audio_effect_mappings.delete(mapping_id, provider_id=provider_id)
+    except ValueError as exc:
+        return _audio_effects_error(exc)
+    if not deleted:
+        return JSONResponse({"error": "mapping not found"}, status_code=404)
+    return {"ok": True}
+
+
+@router.post("/api/audio-effects/mappings/{mapping_id}/activate")
+def activate_audio_effect_mapping(mapping_id: int, data: dict = Body(default_factory=dict)):
+    try:
+        provider_id = data.get("provider_id") if "provider_id" in data else data.get("providerId")
+        mapping = appstate.audio_effect_mappings.activate(mapping_id, provider_id="" if provider_id is None else provider_id)
+    except ValueError as exc:
+        return _audio_effects_error(exc)
+    if not mapping:
+        return JSONResponse({"error": "mapping not found"}, status_code=404)
+    return {"ok": True, "mapping": mapping}
+
+
+@router.delete("/api/audio-effects/active-mapping")
+def clear_audio_effect_active_mapping(song_key: str = Query(...), tone_key: str = Query("")):
+    try:
+        cleared = appstate.audio_effect_mappings.clear_active(song_key=song_key, tone_key=tone_key)
+    except ValueError as exc:
+        return _audio_effects_error(exc)
+    return {"ok": True, "cleared": cleared}

lib/routers/chart.py

@@ -0,0 +1,115 @@
+"""Chart-level endpoints — split/unsplit a chart from its work, resolve work
+membership, and the context-menu "Get info" file inspector.
+
+Extracted verbatim from ``server.py`` (R3); edits: ``@app`` -> ``@router``,
+``meta_db`` -> ``appstate.meta_db``. DLC path resolution comes from
+``dlc_paths``; sloppak/loose detection from the shared lib modules.
+"""
+
+from fastapi import APIRouter, HTTPException
+
+import appstate
+from dlc_paths import _get_dlc_dir, _resolve_dlc_path
+import sloppak as sloppak_mod
+import loosefolder as loosefolder_mod
+
+router = APIRouter()
+
+
+@router.post("/api/chart/{filename:path}/split")
+def api_split_chart(filename: str):
+    """'These aren't the same song' — split this chart out as its own singleton
+    work. Under /api/chart (NOT /api/song) so the DELETE /api/song/{path}
+    catch-all can't shadow it."""
+    key = appstate.meta_db._canonical_song_filename(filename)
+    appstate.meta_db.split_chart(key)
+    return {"ok": True, "filename": key}
+
+
+@router.post("/api/chart/{filename:path}/unsplit")
+def api_unsplit_chart(filename: str):
+    """Undo a split — rejoin the chart to its work."""
+    key = appstate.meta_db._canonical_song_filename(filename)
+    appstate.meta_db.unsplit_chart(key)
+    return {"ok": True, "filename": key}
+
+
+@router.get("/api/chart/{filename:path}/work")
+def api_get_chart_work(filename: str):
+    """Resolve a chart's work membership: {work_key, chart_count}. For openers
+    on rows that came from an ungrouped query (the tree view) — grouped grid
+    rows already carry both fields inline."""
+    return appstate.meta_db.chart_work(filename)
+
+
+@router.get("/api/chart/{filename:path}/fileinfo")
+def api_chart_fileinfo(filename: str):
+    """The context menu's "Get info": where the file lives + what the pack
+    contains. Under /api/chart — the GET /api/song/{path} catch-all would
+    swallow a /api/song/…/fileinfo suffix. Read-only; demo-mode blocks it
+    because it exposes filesystem paths."""
+    dlc = _get_dlc_dir()
+    if not dlc:
+        raise HTTPException(status_code=404, detail="not configured")
+    p = _resolve_dlc_path(dlc, filename)
+    if p is None:
+        raise HTTPException(status_code=403, detail="forbidden")
+    if not p.exists():
+        raise HTTPException(status_code=404, detail="not found")
+    # Restrict to actual charts — sloppak or loose song. Without this the route
+    # would stat ANY file the user happens to keep under DLC_DIR (e.g. notes),
+    # leaking its path/size; the app only recognises these two song formats.
+    is_pak = sloppak_mod.is_sloppak(p)
+    is_loose = loosefolder_mod.is_loose_song(p)
+    if not (is_pak or is_loose):
+        raise HTTPException(status_code=404, detail="not a chart")
+    st = p.stat()
+    info = {
+        "filename": filename,
+        "path": str(p),
+        "folder": str(p.parent),
+        "format": "sloppak" if is_pak else "loose",
+        # Directory-form songs report the tree's total (covers loose folders
+        # and dir-form paks); zip-form paks report the archive size. Symlinked
+        # entries are skipped so a link inside the folder can't pull in — or
+        # leak the size of — a file outside it.
+        "size": (st.st_size if p.is_file()
+                 else sum(f.stat().st_size for f in p.rglob("*")
+                          if f.is_file() and not f.is_symlink())),
+        "mtime": st.st_mtime,
+    }
+    if is_pak:
+        try:
+            m = sloppak_mod.load_manifest(p) or {}
+        except Exception:
+            m = {}
+        arrs = [str(a.get("name", a.get("id", ""))) for a in (m.get("arrangements") or [])
+                if isinstance(a, dict)]
+        stems = [str(s.get("id", "")) for s in (m.get("stems") or []) if isinstance(s, dict)]
+        try:
+            has_cover = sloppak_mod.read_cover_bytes(p, m) is not None
+        except Exception:
+            has_cover = False
+        # The optional identity/catalog keys, listed only when present — the
+        # Get-info panel's "what this pack carries vs what's missing" readout.
+        identity = {k: m.get(k) for k in
+                    ("mbid", "isrc", "genres", "track", "disc", "album_artist",
+                     "feedpak_version", "language")
+                    if m.get(k) not in (None, "", [])}
+        info["manifest"] = {
+            "title": str(m.get("title", "")), "artist": str(m.get("artist", "")),
+            "album": str(m.get("album", "")), "year": str(m.get("year", "") or ""),
+            "arrangements": arrs, "stems": stems,
+            "has_cover": has_cover, "has_lyrics": bool(m.get("lyrics")),
+            "authors": [a.get("name", "") if isinstance(a, dict) else str(a)
+                        for a in (m.get("authors") or [])],
+            "identity": identity,
+        }
+    # The enrichment verdict, so Get info can say "Matched (auto, 96%)" /
+    # "Pinned by you" / "Not matched" alongside the file facts.
+    row = appstate.meta_db.get_enrichment(filename)
+    if row:
+        info["match"] = {k: row.get(k) for k in
+                         ("match_state", "match_source", "match_score",
+                          "canon_artist", "canon_title", "canon_album", "canon_year")}
+    return info

lib/routers/diagnostics.py

@@ -0,0 +1,295 @@
+"""Diagnostic bundle export + hardware probe (/api/diagnostics/*).
+
+One-click "Export Diagnostics" in Settings produces a redacted zip combining
+server logs, system info, hardware (CPU/GPU/RAM), plugin inventory, and the
+browser-side console transcript + hardware probe. Bundle format is specified in
+docs/diagnostics-bundle-spec.md.
+
+Extracted verbatim from server.py (R3) except:
+  - the decorators (@app -> @router),
+  - CONFIG_DIR -> appstate.config_dir and _running_version() ->
+    appstate.running_version() (both read through the appstate seam),
+  - the builtin-plugins lookup in _diag_plugins_roots: Path(__file__).parent
+    (the app root when this lived at the top level) ->
+    Path(__file__).resolve().parents[2] (routers -> lib -> app root). The
+    plugins/ dir ships at the app root in every packaging path.
+
+The pure helpers + caps here are re-exported from server.py so the existing
+`server._diag_*` / `server._DIAG_*` tests keep resolving (none monkeypatch them).
+"""
+
+import json
+import logging
+import os
+from pathlib import Path
+
+from fastapi import APIRouter, Body, Response
+
+import appstate
+from dlc_paths import _get_dlc_dir
+from diagnostics_bundle import build_bundle as _diag_build, preview_bundle as _diag_preview
+from diagnostics_hardware import collect as _diag_hardware
+from env_compat import getenv_compat
+
+log = logging.getLogger("feedBack.server")
+router = APIRouter()
+
+
+def _diag_log_file() -> Path | None:
+    raw = os.environ.get("LOG_FILE", "").strip()
+    if not raw:
+        return None
+    return Path(raw)
+
+
+def _diag_plugins_roots() -> list[Path]:
+    """Return all plugin root directories for orphan scanning.
+
+    Includes both the built-in ``plugins/`` directory and
+    ``FEEDBACK_PLUGINS_DIR`` when set, so user-installed plugins and
+    orphans in the external dir are reflected in the bundle.
+    """
+    roots: list[Path] = []
+    user_dir = getenv_compat("FEEDBACK_PLUGINS_DIR", "").strip()
+    if user_dir:
+        p = Path(user_dir)
+        if p.is_dir():
+            roots.append(p)
+    builtin = Path(__file__).resolve().parents[2] / "plugins"  # R3: app root from lib/routers/
+    if builtin not in roots:
+        roots.append(builtin)
+    return roots
+
+
+def _diag_coerce_bool(v, *, default: bool = True) -> bool:
+    """Coerce a request-side value to bool, accepting both JSON booleans and
+    string representations.
+
+    - Falsy strings: ``"false"``, ``"0"``, ``"no"``, ``""`` → ``False``
+    - ``None`` → *default*
+    - Everything else (including ``"true"``, ``"1"``) → ``True``
+    """
+    if v is None:
+        return default
+    if isinstance(v, bool):
+        return v
+    if isinstance(v, str):
+        return v.strip().lower() not in ("false", "0", "no", "")
+    return bool(v)
+
+
+def _diag_normalize_include(include: dict | None) -> dict:
+    """Coerce request-side flags to the booleans build_bundle expects.
+    Missing keys default to True so a bare {} request still produces
+    the full bundle.
+
+    Accepts both JSON booleans (``true``/``false``) and string
+    representations so callers that serialize flags as strings behave
+    consistently with the preview endpoint:
+    - Falsy strings: ``"false"``, ``"0"``, ``"no"``, ``""`` → ``False``
+    - Everything else (including ``"true"``, ``"1"``, ``"yes"``) → ``True``
+    """
+    keys = ("system", "hardware", "logs", "console", "plugins")
+    if not isinstance(include, dict):
+        return {k: True for k in keys}
+
+    return {k: _diag_coerce_bool(include.get(k), default=True) for k in keys}
+
+
+# Server-side caps on client-supplied payload sections.  diagnostics.js
+# enforces a 500-entry / ~250 KB ring buffer on the browser side; these
+# bounds give generous headroom while still preventing a crafted POST from
+# forcing the server to allocate arbitrarily large in-memory bundles.
+_DIAG_MAX_CONSOLE_ENTRIES = 1000          # hard cap: truncate silently
+_DIAG_MAX_CONSOLE_BYTES = 2 * 1024 * 1024  # 2 MB hard cap on total console list
+_DIAG_MAX_CLIENT_PAYLOAD_BYTES = 2 * 1024 * 1024   # 2 MB per dict section
+_DIAG_MAX_CONTRIBUTIONS_BYTES = 4 * 1024 * 1024    # 4 MB aggregate cap for contributions
+
+
+def _diag_cap_console(v) -> list | None:
+    """Return *v* if it is a list, truncated to _DIAG_MAX_CONSOLE_ENTRIES entries
+    and _DIAG_MAX_CONSOLE_BYTES total.  Entries are accumulated until either cap
+    is reached; no partial-entry splitting occurs."""
+    if not isinstance(v, list):
+        return None
+    result = v[:_DIAG_MAX_CONSOLE_ENTRIES]
+    # Also enforce a byte cap — the count cap alone does not bound memory when
+    # entries contain arbitrarily large strings.
+    try:
+        out = []
+        total = 0
+        for entry in result:
+            encoded = json.dumps(entry, separators=(",", ":")).encode("utf-8", errors="replace")
+            if total + len(encoded) > _DIAG_MAX_CONSOLE_BYTES:
+                break
+            out.append(entry)
+            total += len(encoded)
+        return out
+    except (TypeError, ValueError):
+        return None
+
+
+def _diag_cap_dict(v) -> dict | None:
+    """Return *v* if it is a dict whose JSON serialisation fits within
+    _DIAG_MAX_CLIENT_PAYLOAD_BYTES, otherwise return None."""
+    if not isinstance(v, dict):
+        return None
+    try:
+        encoded = json.dumps(v, separators=(",", ":")).encode("utf-8", errors="replace")
+    except (TypeError, ValueError) as e:
+        log.warning("diagnostics client payload is not JSON-serialisable, dropping: %s", e)
+        return None
+    if len(encoded) > _DIAG_MAX_CLIENT_PAYLOAD_BYTES:
+        return None
+    return v
+
+
+def _diag_cap_contributions(v, known_ids=None) -> dict | None:
+    """Apply per-plugin and aggregate size caps on client_contributions.
+
+    Unlike _diag_cap_dict(), which drops the whole dict when any plugin
+    exceeds the limit, this function caps each plugin independently so
+    one noisy plugin does not silence every other plugin's contribution.
+
+    Parameters
+    ----------
+    v:
+        The raw contributions dict from the POST payload.
+    known_ids:
+        When provided, contributions from plugins not in this set are
+        skipped *before* serialisation, preventing a malicious caller
+        from forcing the server to JSON-encode hundreds of near-limit
+        payloads that ``build_bundle()`` would later discard anyway.
+        ``None`` means "accept all plugin ids" (used in tests / preview).
+    """
+    if not isinstance(v, dict):
+        return None
+    result = {}
+    total_bytes = 0
+    for pid, contribution in v.items():
+        if not isinstance(pid, str):
+            continue
+        # Filter unknown plugin ids early — before serialising — so a
+        # crafted request cannot force large allocations for plugins that
+        # build_bundle() would drop.
+        if known_ids is not None and pid not in known_ids:
+            continue
+        try:
+            encoded = json.dumps(contribution, separators=(",", ":")).encode("utf-8", errors="replace")
+        except (TypeError, ValueError) as e:
+            log.warning(
+                "client_contributions[%r] is not JSON-serialisable, dropping: %s", pid, e
+            )
+            continue
+        if len(encoded) > _DIAG_MAX_CLIENT_PAYLOAD_BYTES:
+            log.warning(
+                "client_contributions[%r] exceeds %d bytes, dropping",
+                pid, _DIAG_MAX_CLIENT_PAYLOAD_BYTES,
+            )
+            continue
+        if total_bytes + len(encoded) > _DIAG_MAX_CONTRIBUTIONS_BYTES:
+            log.warning(
+                "client_contributions aggregate size limit (%d bytes) reached, "
+                "dropping remaining entries",
+                _DIAG_MAX_CONTRIBUTIONS_BYTES,
+            )
+            break
+        result[pid] = contribution
+        total_bytes += len(encoded)
+    return result or None
+
+
+@router.post("/api/diagnostics/export")
+def export_diagnostics(payload: dict = Body(default_factory=dict)):
+    """Build a diagnostic bundle and stream it back as a zip download.
+
+    The browser layers in `client_console`, `client_hardware`,
+    `client_ua`, and `local_storage` before posting; the server adds
+    server logs, hardware, plugin inventory, and packages everything
+    into a single zip.
+
+    Errors during plugin diagnostics callables are caught and logged
+    to the bundle's manifest `notes` rather than failing the export.
+    """
+    from plugins import LOADED_PLUGINS, PLUGINS_LOCK
+
+    redact = _diag_coerce_bool(payload.get("redact", True), default=True)
+    include = _diag_normalize_include(payload.get("include"))
+    client_console = _diag_cap_console(payload.get("client_console"))
+    client_hardware = _diag_cap_dict(payload.get("client_hardware"))
+    client_ua = _diag_cap_dict(payload.get("client_ua"))
+    local_storage = _diag_cap_dict(payload.get("local_storage"))
+    # Fetch the plugin list first so we can filter contributions to known
+    # plugin ids before serialising — prevents a crafted request from
+    # forcing large allocations for plugins build_bundle() would drop.
+    with PLUGINS_LOCK:
+        plugins_snapshot = list(LOADED_PLUGINS)
+    known_ids = {p.get("id") for p in plugins_snapshot if isinstance(p.get("id"), str)}
+    client_contributions = _diag_cap_contributions(
+        payload.get("client_contributions"), known_ids=known_ids
+    )
+
+    zip_bytes, filename, _manifest = _diag_build(
+        feedBack_version=appstate.running_version(),
+        config_dir=appstate.config_dir,
+        dlc_dir=_get_dlc_dir(),
+        log_file=_diag_log_file(),
+        loaded_plugins=plugins_snapshot,
+        include=include,
+        redact=redact,
+        client_console=client_console,
+        client_hardware=client_hardware,
+        client_ua=client_ua,
+        local_storage=local_storage,
+        client_contributions=client_contributions,
+        log=log,
+        plugins_root=_diag_plugins_roots(),
+    )
+    return Response(
+        content=zip_bytes,
+        media_type="application/zip",
+        headers={"Content-Disposition": f'attachment; filename="{filename}"'},
+    )
+
+
+@router.get("/api/diagnostics/preview")
+def preview_diagnostics(
+    redact: bool = True,
+    system: bool = True,
+    hardware: bool = True,
+    logs: bool = True,
+    console: bool = True,
+    plugins: bool = True,
+):
+    """Return what `/api/diagnostics/export` would produce, minus the
+    actual file contents — file tree, sizes, schemas, redaction counts.
+    Lets the Settings UI show the user what's about to be sent."""
+    from plugins import LOADED_PLUGINS, PLUGINS_LOCK
+
+    include = {
+        "system": system,
+        "hardware": hardware,
+        "logs": logs,
+        "console": console,
+        "plugins": plugins,
+    }
+    with PLUGINS_LOCK:
+        plugins_snapshot = list(LOADED_PLUGINS)
+    return _diag_preview(
+        feedBack_version=appstate.running_version(),
+        config_dir=appstate.config_dir,
+        dlc_dir=_get_dlc_dir(),
+        log_file=_diag_log_file(),
+        loaded_plugins=plugins_snapshot,
+        include=include,
+        redact=redact,
+        log=log,
+        plugins_root=_diag_plugins_roots(),
+    )
+
+
+@router.get("/api/diagnostics/hardware")
+def diagnostics_hardware():
+    """Backend hardware probe (cross-platform). Reusable independently
+    of the bundle export — handy for "what's my GPU" plugin queries."""
+    return _diag_hardware()

lib/routers/enrichment.py

@@ -0,0 +1,346 @@
+"""Metadata-enrichment route handlers (/api/enrichment/*): status, kick/cancel,
+per-song state, the Match-Review queue (accept/reject/pick/search), and AcoustID
+fingerprint identify.
+
+Extracted verbatim from server.py (R3) except @app->@router and the seam reads
+(meta_db->appstate.meta_db, CONFIG_DIR->appstate.config_dir). The enrichment
+engine itself — transport, matcher, the background worker, and the upload caps —
+lives in lib/enrichment.py and is reached here as enrichment.X.
+"""
+
+import asyncio
+import os
+import shutil
+from pathlib import Path
+
+from fastapi import APIRouter, Body, HTTPException, Request, UploadFile
+from fastapi.responses import JSONResponse
+
+import appstate
+import enrichment
+import mb_match
+from appconfig import _load_config
+
+import logging
+log = logging.getLogger("feedBack.server")
+router = APIRouter()
+
+@router.get("/api/enrichment/status")
+def enrichment_status():
+    """Enrichment pipeline state: worker flags + row counts by match_state.
+    Ambient tool-state for the match-review UI (never a home-screen score —
+    design §11); also what tests poke."""
+    return {
+        "running": enrichment._enrich_status["running"],
+        "processed": enrichment._enrich_status["processed"],
+        "last_pass_at": enrichment._enrich_status["last_pass_at"],
+        "states": appstate.meta_db.enrichment_state_counts(),
+        "total_songs": appstate.meta_db.count(),
+        # Per-pass matching progress for the "Refresh Metadata" batch bar +
+        # per-tile badges (total = songs queued to match this pass, matched =
+        # done so far, current = the one being matched now).
+        "total": enrichment._enrich_status.get("total", 0),
+        "matched": enrichment._enrich_status.get("matched", 0),
+        "current": enrichment._enrich_status.get("current"),
+        "cancelling": enrichment._enrich_cancel.is_set(),
+    }
+
+
+@router.get("/api/enrichment/song/{filename:path}")
+def api_enrichment_song(filename: str):
+    """Read-only per-song match provenance for the Details drawer (launch
+    polish): which canonical identity this chart matched and how. A tiny
+    projection of the cache row — no candidates, no cache paths."""
+    row = appstate.meta_db.get_enrichment(filename)
+    if not row:
+        raise HTTPException(status_code=404, detail="no enrichment row")
+    return {k: row.get(k) for k in
+            ("match_state", "canon_artist", "canon_title",
+             "match_source", "match_score")}
+
+
+@router.post("/api/enrichment/kick")
+def api_enrichment_kick():
+    """The Settings "Match now" button AND the library's "Refresh Metadata"
+    button: request an enrichment pass without waiting for a scan to complete.
+    Processes the songs that still need it (unscanned/changed + retriable
+    failures) — already-matched songs are left alone, so on a fully-matched
+    library this is a fast no-op. Single-flight + coalescing like every other
+    kick — spamming it queues at most one follow-up pass."""
+    return {"started": enrichment._kick_enrich()}
+
+
+@router.post("/api/enrichment/cancel")
+def api_enrichment_cancel():
+    """Stop button on the "Refresh Metadata" batch: signal the running pass to
+    halt after the current song (an in-flight ≤1/s lookup can't be interrupted,
+    but no new one is started) and drop any coalesced follow-up. A no-op when
+    nothing is running."""
+    was_running = enrichment._enrich_status["running"]
+    if was_running:
+        enrichment._enrich_cancel.set()
+    return {"ok": True, "was_running": was_running}
+
+
+@router.post("/api/enrichment/rematch")
+def api_enrichment_rematch(data: dict = Body(...)):
+    """The library "Refresh Metadata" button: force a fresh re-match of the
+    songs the grid is SHOWING (its visible/filtered window). Resets each to
+    `unscanned` so the next pass re-fetches it from scratch — EXCEPT user-pinned
+    `manual` rows, which are never auto-overwritten (apply_enrichment_match
+    guards that) — then kicks one pass. Scoped to the visible set on purpose:
+    fast (dozens of songs), visible (tiles animate), and it can't blow the whole
+    ≤1/s rate budget on a 1000-song library the way a full re-sweep would.
+    Returns the filenames actually queued so the UI badges exactly those."""
+    raw = (data or {}).get("filenames") or []
+    fns = [str(f) for f in raw if isinstance(f, str)][:500]
+    queued: list[str] = []
+    for fn in fns:
+        song = appstate.meta_db.enrichment_song_row(fn)
+        if not song:
+            continue
+        h = appstate.meta_db.enrichment_content_hash(
+            song["artist"], song["title"], song["album"], song["duration"])
+        # allow_manual_overwrite=False → a manual pin is left as-is (returns
+        # False), everything else resets to unscanned (returns True).
+        if appstate.meta_db.apply_enrichment_match(fn, h, "unscanned",
+                                          allow_manual_overwrite=False):
+            queued.append(fn)
+    started = enrichment._kick_enrich() if queued else False
+    return {"queued": queued, "count": len(queued), "started": started}
+
+
+@router.post("/api/enrichment/states")
+def api_enrichment_states(data: dict = Body(...)):
+    """Per-tile match states for the grid's VISIBLE window during a metadata
+    refresh: the client posts the filenames it is showing and gets back each
+    one's match_state (+ the song being matched right now, + whether a pass is
+    running), so a card can animate queued→working→result without a per-song
+    round-trip. Read-only — safe for demo visitors (no network, no mutation)."""
+    raw = (data or {}).get("filenames") or []
+    # Bound the batch: a visible grid window is dozens of cards; cap defensively.
+    fns = [str(f) for f in raw if isinstance(f, str)][:500]
+    return {
+        "states": appstate.meta_db.enrichment_states_for(fns),
+        "current": enrichment._enrich_status.get("current"),
+        "running": enrichment._enrich_status["running"],
+    }
+
+
+@router.post("/api/enrichment/refresh/{filename:path}")
+def api_enrichment_refresh(filename: str):
+    """The context menu's "Refresh metadata": reset THIS song's match to
+    unscanned (canonical values + candidates cleared, backoff zeroed) and
+    kick a pass so it re-matches immediately. An EXPLICIT user action, so it
+    may discard a manual pin — the automation never does, but the user
+    asking for a re-match is the one party who owns that pin."""
+    song = appstate.meta_db.enrichment_song_row(filename)
+    if not song:
+        raise HTTPException(status_code=404, detail="unknown song")
+    h = appstate.meta_db.enrichment_content_hash(
+        song["artist"], song["title"], song["album"], song["duration"])
+    appstate.meta_db.apply_enrichment_match(filename, h, "unscanned",
+                                   allow_manual_overwrite=True)
+    return {"ok": True, "started": enrichment._kick_enrich()}
+
+
+@router.get("/api/enrichment/review")
+def api_enrichment_review(limit: int = 200):
+    """The Match-Review queue: songs whose text match landed in the medium-
+    confidence review tier, each with its stored candidate list — the drawer
+    renders straight from this, no MusicBrainz round-trip. Ordered by the
+    user's enrich_review_order setting."""
+    limit = max(1, min(int(limit), 500))
+    cfg = _load_config(appstate.config_dir / "config.json") or {}
+    order = cfg.get("enrich_review_order", "missing_first")
+    return {
+        "songs": appstate.meta_db.enrichment_review_queue(limit=limit, order=order),
+        "total_review": appstate.meta_db.enrichment_state_counts().get("review", 0),
+    }
+
+
+@router.post("/api/enrichment/review/{filename:path}/accept")
+def api_enrichment_accept(filename: str, data: dict = Body(...)):
+    """Accept one of the stored review candidates: the row becomes a
+    user-pinned `manual` match (never auto-reset). Display-only, like every
+    enrichment write — nothing touches the pack file."""
+    recording_id = str((data or {}).get("recording_id") or "")
+    row = appstate.meta_db.get_enrichment(filename)
+    if not row or row["match_state"] != "review":
+        raise HTTPException(status_code=404, detail="no review row for this song")
+    cand = next((c for c in (row.get("candidates") or [])
+                 if c.get("recording_id") == recording_id), None)
+    if not cand:
+        raise HTTPException(status_code=404, detail="candidate not in the stored list")
+    if not appstate.meta_db.set_enrichment_manual(filename, cand, source="review"):
+        raise HTTPException(status_code=404, detail="unknown song")
+    return {"ok": True, "enrichment": appstate.meta_db.get_enrichment(filename)}
+
+
+@router.post("/api/enrichment/review/{filename:path}/reject")
+def api_enrichment_reject(filename: str):
+    """"None of these" — clears any canonical values and parks the row as
+    failed/rejected (never auto-retried; editing the song's metadata
+    re-queues it). Valid from `review` or `matched`, never from `manual`."""
+    if not appstate.meta_db.set_enrichment_rejected(filename):
+        raise HTTPException(status_code=404, detail="no rejectable match for this song")
+    return {"ok": True, "enrichment": appstate.meta_db.get_enrichment(filename)}
+
+
+# The candidate fields a manual pick is allowed to carry — the payload comes
+# from our own /api/enrichment/search proxy, but the route re-sanitizes so a
+# hand-rolled client can't stuff arbitrary keys/types into the cache row.
+_CAND_STR_FIELDS = ("recording_id", "title", "artist", "artist_id",
+                    "artist_sort", "release_id", "album", "year", "isrc")
+
+
+def _sanitize_candidate(raw: dict) -> dict | None:
+    if not isinstance(raw, dict):
+        return None
+    out = {k: str(raw.get(k) or "") for k in _CAND_STR_FIELDS}
+    if not out["recording_id"] or not out["title"]:
+        return None
+    genres = raw.get("genres") or []
+    out["genres"] = [str(g) for g in genres if isinstance(g, str)][:5] \
+        if isinstance(genres, list) else []
+    return out
+
+
+@router.post("/api/enrichment/review/{filename:path}/pick")
+def api_enrichment_pick(filename: str, data: dict = Body(...)):
+    """Fix-match / manual search-and-pick: pin a candidate the user found via
+    /api/enrichment/search (not limited to the stored review list — this is
+    the escape hatch for a wrong auto-match too). Sets `manual`, the
+    highest-authority state."""
+    cand = _sanitize_candidate((data or {}).get("candidate"))
+    if not cand:
+        raise HTTPException(status_code=400, detail="candidate needs recording_id + title")
+    if not appstate.meta_db.set_enrichment_manual(filename, cand, source="search"):
+        raise HTTPException(status_code=404, detail="unknown song")
+    return {"ok": True, "enrichment": appstate.meta_db.get_enrichment(filename)}
+
+
+@router.get("/api/enrichment/search")
+def api_enrichment_search(artist: str = "", title: str = "", limit: int = 8,
+                          filename: str = "", duration: float = 0.0):
+    """Manual-search proxy to MusicBrainz (throttled + identified like the
+    background matcher — a user typing in the drawer must not sidestep the
+    rate limit). `filename` optionally scores results against that song's
+    stored identity (year/duration corroboration) instead of just the typed
+    text. `duration` (seconds) lets a caller that HAS the audio but no library
+    row — e.g. the editor's create modal, which holds the master track — pass
+    its length so the studio take ranks above live/extended cuts. Sync route on
+    purpose: FastAPI runs it in the threadpool, so the throttle's sleep never
+    blocks the event loop."""
+    if not (artist.strip() or title.strip()):
+        raise HTTPException(status_code=400, detail="artist or title required")
+    limit = max(1, min(int(limit), 25))
+    try:
+        cands = enrichment._mb_search_recordings(artist, title, limit=limit)
+    except enrichment.EnrichTransportError as e:
+        return JSONResponse({"error": "musicbrainz unavailable", "detail": str(e)},
+                            status_code=503)
+    ref = None
+    if filename:
+        ref = appstate.meta_db.enrichment_song_row(filename)
+    if ref is None:
+        ref = {"artist": artist, "title": title}
+    # A caller-supplied duration corroborates the take even without a library row.
+    if duration and duration > 0 and not ref.get("duration"):
+        ref = dict(ref)
+        ref["duration"] = duration
+    # Alias-enrich so a non-Latin-primary artist (大橋純子) ranks by its
+    # romanized alias against the typed query ("Junko Ohashi") instead of
+    # sinking to the bottom with a 0 artist score.
+    try:
+        enrichment._alias_enrich(ref, cands)
+    except enrichment.EnrichTransportError:
+        pass   # aliases are a ranking nicety here; fall back to primary-name scoring
+    return {"candidates": mb_match.rank_candidates(ref, cands)}
+
+
+@router.post("/api/enrichment/identify")
+async def api_enrichment_identify(request: Request):
+    """Identify a song by AUDIO FINGERPRINT (AcoustID) rather than text — the
+    reliable way to get the EXACT recording/version (the studio take, not a live
+    bootleg or an extended cut). Upload the master audio; returns candidates in
+    the same shape as /search, so the review UI and the editor's Match popup can
+    render fingerprint hits identically. 412 `needs_setup` when the user hasn't
+    opted in / has no key (the UI nudges them to Settings); 503 when it's set up
+    but the fpcalc Chromaprint binary is missing or the network is off. Async so
+    the multipart is size-capped BEFORE spooling; the blocking fpcalc subprocess
+    + AcoustID HTTP run in the threadpool via run_in_executor."""
+    gate = enrichment._acoustid_gate()
+    if gate is not None:
+        return gate
+    # Pre-parse Content-Length guard — reject an oversized body before Starlette
+    # spools the multipart to temp disk (mirrors the song-upload endpoint). The
+    # per-part cap below is the authoritative limit; this is the fast up-front no.
+    cl = request.headers.get("content-length")
+    if cl is not None:
+        try:
+            cl_int = int(cl)
+        except ValueError:
+            return JSONResponse({"error": "Invalid Content-Length header"}, status_code=400)
+        if cl_int > enrichment._ACOUSTID_MAX_UPLOAD_BYTES + enrichment._MULTIPART_OVERHEAD_SLACK:
+            return JSONResponse({"error": "audio upload too large (256 MB max)"}, status_code=413)
+    try:
+        form = await request.form(max_part_size=enrichment._ACOUSTID_MAX_UPLOAD_BYTES)
+    except Exception:
+        return JSONResponse({"error": "audio upload too large (256 MB max)"}, status_code=413)
+    file = form.get("file")
+    if not isinstance(file, UploadFile):
+        raise HTTPException(status_code=400, detail="missing file upload")
+    import tempfile
+    ext = (Path(file.filename or "").suffix or ".bin").lower()
+    tmpdir = tempfile.mkdtemp(prefix="feedback_acoustid_")
+    tmp = os.path.join(tmpdir, "audio" + ext)
+    try:
+        total = 0
+        with open(tmp, "wb") as fh:
+            while True:
+                chunk = await file.read(1024 * 1024)
+                if not chunk:
+                    break
+                total += len(chunk)
+                if total > enrichment._ACOUSTID_MAX_UPLOAD_BYTES:
+                    return JSONResponse(
+                        {"error": "audio upload too large (256 MB max)"}, status_code=413)
+                fh.write(chunk)
+        if total == 0:
+            raise HTTPException(status_code=400, detail="empty upload")
+        # fpcalc subprocess + AcoustID HTTP are blocking — off the event loop.
+        cands = await asyncio.get_event_loop().run_in_executor(
+            None, enrichment._identify_by_fingerprint, tmp)
+    except enrichment.EnrichTransportError as e:
+        return JSONResponse({"error": "acoustid unavailable", "detail": str(e)},
+                            status_code=503)
+    finally:
+        shutil.rmtree(tmpdir, ignore_errors=True)
+    return {"candidates": cands}
+
+
+@router.post("/api/enrichment/identify/{filename:path}")
+def api_enrichment_identify_song(filename: str):
+    """Identify an EXISTING library song by AUDIO FINGERPRINT — the library-side
+    counterpart to /api/enrichment/identify (which takes an upload). Fingerprints
+    the song's own master audio on disk (the manual "Identify by audio" action in
+    the Fix-metadata / match-review flow). Same candidate shape as /search, so the
+    review UI renders fingerprint hits like text hits. Same 412/503 gating; 404
+    when the song has no full-mix audio to fingerprint."""
+    gate = enrichment._acoustid_gate()
+    if gate is not None:
+        return gate
+    audio = enrichment._song_audio_file(filename)
+    if not audio:
+        return JSONResponse(
+            {"error": "no audio",
+             "detail": "couldn't find this song's master audio to fingerprint "
+                       "(a stems-only pack has no full mix to identify)."},
+            status_code=404)
+    try:
+        cands = enrichment._identify_by_fingerprint(audio)
+    except enrichment.EnrichTransportError as e:
+        return JSONResponse({"error": "acoustid unavailable", "detail": str(e)},
+                            status_code=503)
+    return {"candidates": cands}

lib/routers/library.py

@@ -0,0 +1,485 @@
+"""Library + smart-collection routes: the provider list/art/sync endpoints, the
+library query surface (songs, albums, artists, stats, genres, tuning-names,
+practice-suggestions), and collection CRUD.
+
+Extracted verbatim from server.py (R3) except @app->@router and the seam reads:
+meta_db->appstate.meta_db, and the registry singletons ->
+appstate.library_providers / appstate.local_library_provider (constructed +
+owned by server.py; plugins register providers through plugin_context). The
+provider classes + shared query/collection helpers live in lib/library_registry.py.
+"""
+
+import inspect
+from pathlib import Path
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import FileResponse, JSONResponse, RedirectResponse, Response
+from starlette.concurrency import run_in_threadpool
+
+import appstate
+from library_registry import (
+    _library_filter_args, _sanitize_collection_rules,
+    _safe_art_redirect_url, _split_csv, _sync_collection_provider,
+    _unregister_collection_provider,
+)
+from metadata_db import _effective_keyset_sort, next_library_cursor
+from reqfields import _clean_str
+
+import logging
+log = logging.getLogger("feedBack.server")
+router = APIRouter()
+
+
+
+
+
+def _get_library_provider(provider: str = "local") -> object:
+    library_provider = appstate.library_providers.get(provider or "local")
+    if library_provider is None:
+        raise HTTPException(status_code=404, detail=f"Unknown library provider: {provider}")
+    return library_provider
+
+
+def _require_library_provider_capability(provider: object, capability: str) -> None:
+    if capability in appstate.library_providers.provider_capabilities(provider):
+        return
+    provider_id = appstate.library_providers.provider_id(provider)
+    raise HTTPException(
+        status_code=501,
+        detail=f"Library provider {provider_id!r} does not declare capability {capability!r}",
+    )
+
+
+_OPTIONAL_NEW_PROVIDER_KWARGS = ("naming_mode", "sort", "want_sort_letters", "after",
+                                 "mastery", "match_states")
+
+
+def _filter_provider_kwargs(method: object, kwargs: dict) -> dict:
+    """Drop kwargs that the method's signature does not declare.
+
+    Provides backward-compat for third-party library providers whose
+    query_page/query_artists/query_stats methods were written before
+    naming_mode was added — calling them with the extra kwarg would
+    raise TypeError and return a 500 to the client.
+
+    When ``inspect.signature`` cannot introspect the method (rare: C
+    extensions / built-ins / exotic callables), fall back to stripping
+    only the kwargs we know were added later — older providers won't
+    accept them, anything else stays so the call still works.
+    """
+    try:
+        sig = inspect.signature(method)  # type: ignore[arg-type]
+        for p in sig.parameters.values():
+            if p.kind == inspect.Parameter.VAR_KEYWORD:
+                return kwargs  # method accepts **kwargs, pass everything
+        return {k: v for k, v in kwargs.items() if k in sig.parameters}
+    except (ValueError, TypeError):
+        return {k: v for k, v in kwargs.items() if k not in _OPTIONAL_NEW_PROVIDER_KWARGS}
+
+
+def _call_library_provider(provider: object, method_name: str, **kwargs) -> Any:
+    method = appstate.library_providers.provider_method(provider, method_name)
+    if not callable(method):
+        provider_id = appstate.library_providers.provider_id(provider)
+        raise HTTPException(
+            status_code=501,
+            detail=f"Library provider {provider_id!r} does not support {method_name}",
+        )
+    try:
+        return method(**_filter_provider_kwargs(method, kwargs))
+    except HTTPException:
+        raise
+    except Exception as exc:
+        provider_id = appstate.library_providers.provider_id(provider)
+        # A provider with an explicit kind="local" is treated as local even if
+        # its id is not "local" (e.g. a kind="local" plugin variant). Otherwise
+        # fall back to provider_id comparison so providers that omit `kind` are
+        # still wrapped correctly — the safe default for unknown providers is to
+        # surface an offline message rather than leaking raw exceptions.
+        provider_kind = str(appstate.library_providers.provider_field(provider, "kind", "") or "")
+        if provider_kind:
+            is_remote = provider_kind not in ("", "local")
+        else:
+            is_remote = provider_id != "local"
+        if is_remote:
+            detail = f"This source appears to be offline ({provider_id})."
+            message = str(exc).strip()
+            if message:
+                detail = f"{detail} {message}"
+            raise HTTPException(status_code=503, detail=detail) from exc
+        raise
+
+
+def _is_async_callable(obj: object) -> bool:
+    """Return True if obj is an async function or a callable object with an async __call__.
+
+    ``inspect.iscoroutinefunction`` only recognises bare coroutine functions; it returns
+    False for class instances whose ``__call__`` method is defined as ``async def``.
+    Checking both handles the common plugin pattern of wrapping an async method in a
+    callable object.
+    """
+    if inspect.iscoroutinefunction(obj):
+        return True
+    _call = getattr(obj, "__call__", None)
+    return _call is not None and inspect.iscoroutinefunction(_call)
+
+
+async def _call_library_provider_async(provider: object, method_name: str, **kwargs) -> Any:
+    method = appstate.library_providers.provider_method(provider, method_name)
+    if _is_async_callable(method):
+        # Async provider method — call directly on the event loop.
+        try:
+            return await method(**_filter_provider_kwargs(method, kwargs))
+        except HTTPException:
+            raise
+        except Exception as exc:
+            provider_id = appstate.library_providers.provider_id(provider)
+            provider_kind = str(appstate.library_providers.provider_field(provider, "kind", "") or "")
+            if provider_kind:
+                is_remote = provider_kind not in ("", "local")
+            else:
+                is_remote = provider_id != "local"
+            if is_remote:
+                detail = f"This source appears to be offline ({provider_id})."
+                message = str(exc).strip()
+                if message:
+                    detail = f"{detail} {message}"
+                raise HTTPException(status_code=503, detail=detail) from exc
+            raise
+    # Synchronous provider method — run in a threadpool so the event loop stays free.
+    return await run_in_threadpool(_call_library_provider, provider, method_name, **kwargs)
+
+
+def _library_art_response(result: Any) -> Response:
+    if result is None:
+        raise HTTPException(status_code=404, detail="Library provider returned no art")
+    if isinstance(result, Response):
+        return result
+    if isinstance(result, (bytes, bytearray, memoryview)):
+        return Response(content=bytes(result), media_type="image/png")
+    if isinstance(result, str):
+        safe_url = _safe_art_redirect_url(result)
+        if safe_url is not None:
+            return RedirectResponse(safe_url)
+        # If the string looks like a URL (contains a scheme separator) but
+        # didn't pass the http/https check, refuse it rather than treating
+        # it as a filesystem path — a provider returning ftp:// or file://
+        # should get a 400, not a 500 from FileResponse failing on a URL.
+        if "://" in result:
+            raise HTTPException(
+                status_code=400,
+                detail="Library provider returned an unsupported URL scheme for art",
+            )
+        if not Path(result).is_file():
+            raise HTTPException(status_code=404, detail="Library provider returned an unreadable art path")
+        return FileResponse(result)
+    if isinstance(result, Path):
+        if not result.is_file():
+            raise HTTPException(status_code=404, detail="Library provider returned an unreadable art path")
+        return FileResponse(str(result))
+    if isinstance(result, dict):
+        url = result.get("url") or result.get("art_url") or result.get("artUrl")
+        if isinstance(url, str) and url:
+            safe_url = _safe_art_redirect_url(url)
+            if safe_url is None:
+                raise HTTPException(status_code=400, detail="Library provider returned an unsafe art URL")
+            return RedirectResponse(safe_url)
+        path = result.get("path") or result.get("file")
+        if isinstance(path, (str, Path)):
+            media_type = result.get("media_type") or result.get("content_type")
+            if not Path(path).is_file():
+                raise HTTPException(status_code=404, detail="Library provider returned an unreadable art path")
+            return FileResponse(str(path), media_type=media_type)
+        content = result.get("content") or result.get("bytes")
+        if isinstance(content, (bytes, bytearray, memoryview)):
+            media_type = result.get("media_type") or result.get("content_type") or "image/png"
+            return Response(content=bytes(content), media_type=media_type)
+    raise HTTPException(status_code=500, detail="Library provider returned unsupported art data")
+
+
+@router.get("/api/library/providers")
+def list_library_providers():
+    """List registered library providers."""
+    return {"providers": appstate.library_providers.list()}
+
+
+@router.get("/api/library/providers/{provider_id}/songs/{song_id:path}/art")
+async def get_library_provider_song_art(provider_id: str, song_id: str):
+    """Return album art for a song owned by a library provider."""
+    library_provider = _get_library_provider(provider_id)
+    _require_library_provider_capability(library_provider, "art.read")
+    result = await _call_library_provider_async(library_provider, "get_art", song_id=song_id)
+    return _library_art_response(result)
+
+
+@router.post("/api/library/providers/{provider_id}/songs/{song_id:path}/sync")
+async def sync_library_provider_song(provider_id: str, song_id: str):
+    """Ask a provider to sync a remote song into the local library/cache."""
+    library_provider = _get_library_provider(provider_id)
+    _require_library_provider_capability(library_provider, "song.sync")
+    result = await _call_library_provider_async(library_provider, "sync_song", song_id=song_id)
+    if result is None:
+        return {"ok": True}
+    if isinstance(result, dict):
+        return result
+    return {"ok": True, "result": result}
+
+
+@router.get("/api/library")
+async def list_library(q: str = "", page: int = 0, size: int = 24, sort: str = "artist",
+                       dir: str = "asc", favorites: int = 0, format: str = "",
+                       artist: str = "", album: str = "",
+                       arrangements_has: str = "", arrangements_lacks: str = "",
+                       stems_has: str = "", stems_lacks: str = "",
+                       has_lyrics: str = "", tunings: str = "", provider: str = "local",
+                       mastery: str = "", tags: str = "", user_difficulty: str = "",
+                       match: str = "", genre: str = "", after: str = "", group: int = 0,
+                       naming_mode: str = "legacy"):
+    """Paginated library search through the selected library provider.
+
+    `after` is an opaque keyset cursor (feedBack#636 item 3): pass back the
+    `next_cursor` from the previous response to fetch the next page with a
+    WHERE-seek instead of OFFSET. Providers that don't support it ignore it and
+    page by OFFSET, so the client can always fall back."""
+    size = min(size, 100)
+    library_provider = _get_library_provider(provider)
+    _require_library_provider_capability(library_provider, "library.read")
+    # Only the true local provider keysets: it's the one whose effective sort is
+    # exactly the request `sort`. A smart collection may pin its own sort and
+    # remote providers don't keyset — both must page by OFFSET, so never hand
+    # them a cursor (a mismatched one would mis-seek).
+    is_local = getattr(library_provider, "id", "") == "local"
+    songs, total = await _call_library_provider_async(
+        library_provider,
+        "query_page",
+        page=page,
+        size=size,
+        sort=sort,
+        direction=dir,
+        after=((after or None) if is_local else None),
+        group=bool(group),
+        naming_mode=naming_mode,
+        mastery=_split_csv(mastery),
+        tags_has=_split_csv(tags),
+        user_difficulty_in=_split_csv(user_difficulty),
+        match_states=_split_csv(match),
+        genre=_split_csv(genre),
+        **_library_filter_args(
+            q=q, favorites=favorites, format=format,
+            artist=artist, album=album,
+            arrangements_has=arrangements_has, arrangements_lacks=arrangements_lacks,
+            stems_has=stems_has, stems_lacks=stems_lacks,
+            has_lyrics=has_lyrics, tunings=tunings,
+        ),
+    )
+    # The cursor to resume after this page (effective sort folds in dir=desc).
+    next_cursor = (next_library_cursor(_effective_keyset_sort(sort, dir), songs[-1])
+                   if (is_local and songs) else None)
+    # Drop the private raw-title stash query_page attached for the cursor — it's
+    # an internal keyset detail, not part of the card payload.
+    for s in songs:
+        s.pop("_sort_title", None)
+    return {"songs": songs, "total": total, "page": page, "size": size,
+            "next_cursor": next_cursor}
+
+
+@router.get("/api/library/albums")
+async def list_library_albums(q: str = "", page: int = 0, size: int = 120,
+                              favorites: int = 0, format: str = "",
+                              artist: str = "", album: str = "",
+                              arrangements_has: str = "", arrangements_lacks: str = "",
+                              stems_has: str = "", stems_lacks: str = "",
+                              has_lyrics: str = "", tunings: str = "", mastery: str = "",
+                              match: str = "", genre: str = "",
+                              provider: str = "local"):
+    """Album-condensed browse: distinct (artist, album) groups with a track count
+    and a representative cover song. Paged by album. Same filters as /api/library."""
+    size = min(size, 500)
+    library_provider = _get_library_provider(provider)
+    _require_library_provider_capability(library_provider, "library.read")
+    albums, total = await _call_library_provider_async(
+        library_provider, "query_albums",
+        page=page, size=size, mastery=_split_csv(mastery),
+        match_states=_split_csv(match), genre=_split_csv(genre),
+        **_library_filter_args(
+            q=q, favorites=favorites, format=format, artist=artist, album=album,
+            arrangements_has=arrangements_has, arrangements_lacks=arrangements_lacks,
+            stems_has=stems_has, stems_lacks=stems_lacks,
+            has_lyrics=has_lyrics, tunings=tunings,
+        ),
+    )
+    return {"albums": albums, "total": total, "page": page, "size": size}
+
+
+@router.get("/api/library/artists")
+async def list_artists(letter: str = "", q: str = "", favorites: int = 0, page: int = 0,
+                       size: int = 50, format: str = "",
+                       artist: str = "", album: str = "",
+                       arrangements_has: str = "", arrangements_lacks: str = "",
+                       stems_has: str = "", stems_lacks: str = "",
+                       has_lyrics: str = "", tunings: str = "", provider: str = "local",
+                       naming_mode: str = "legacy"):
+    """Get artists grouped by letter with albums and songs (for tree view)."""
+    size = min(size, 100)
+    library_provider = _get_library_provider(provider)
+    _require_library_provider_capability(library_provider, "library.read")
+    artists, total = await _call_library_provider_async(
+        library_provider,
+        "query_artists",
+        letter=letter,
+        page=page,
+        size=size,
+        naming_mode=naming_mode,
+        **_library_filter_args(
+            q=q, favorites=favorites, format=format,
+            artist=artist, album=album,
+            arrangements_has=arrangements_has, arrangements_lacks=arrangements_lacks,
+            stems_has=stems_has, stems_lacks=stems_lacks,
+            has_lyrics=has_lyrics, tunings=tunings,
+        ),
+    )
+    return {"artists": artists, "total_artists": total, "page": page, "size": size}
+
+
+@router.get("/api/library/stats")
+async def library_stats(favorites: int = 0, q: str = "", format: str = "",
+                        artist: str = "", album: str = "",
+                        arrangements_has: str = "", arrangements_lacks: str = "",
+                        stems_has: str = "", stems_lacks: str = "",
+                        has_lyrics: str = "", tunings: str = "", provider: str = "local",
+                        match: str = "",
+                        sort: str = "artist", sort_letters: int = 0,
+                        group: int = 0, naming_mode: str = "legacy"):
+    """Aggregate stats for the UI. Accepts the same filter params as
+    /api/library so the letter bar mirrors the active grid filter set.
+    `sort` selects the column the jump rail's `sort_letters` keys on;
+    `sort_letters=1` opts into that breakdown (the rail), so non-rail
+    callers skip the extra per-letter aggregate. `group=1` counts works not
+    charts (mirrors the grouped grid)."""
+    library_provider = _get_library_provider(provider)
+    _require_library_provider_capability(library_provider, "library.read")
+    return await _call_library_provider_async(
+        library_provider,
+        "query_stats",
+        naming_mode=naming_mode,
+        sort=sort,
+        want_sort_letters=bool(sort_letters),
+        group=bool(group),
+        # The match facet rides the stats call too — the A–Z rail's letter
+        # counts must agree with the grid under the facet or its cumulative
+        # seek + sizer geometry break.
+        match_states=_split_csv(match),
+        **_library_filter_args(
+            q=q, favorites=favorites, format=format,
+            artist=artist, album=album,
+            arrangements_has=arrangements_has, arrangements_lacks=arrangements_lacks,
+            stems_has=stems_has, stems_lacks=stems_lacks,
+            has_lyrics=has_lyrics, tunings=tunings,
+        ),
+    )
+
+
+@router.get("/api/library/genres")
+def library_genres(provider: str = "local"):
+    """Distinct non-empty genres for the filter facet.
+
+    Genres are a local-library facet: they're populated from the feedpak
+    `genres` field at scan time and live in the local meta DB. Local-backed
+    providers (the local library and its smart collections, kind="local")
+    share that DB, so they surface the same set. Remote providers don't
+    expose genres here, so return an empty facet for them — the client then
+    hides the filter rather than offering local genres that don't apply to
+    the remote grid. Mirrors the local/remote gating used elsewhere for
+    provider calls (see `_call_library_provider`)."""
+    library_provider = _get_library_provider(provider)
+    kind = str(appstate.library_providers.provider_field(library_provider, "kind", "") or "")
+    is_remote = kind not in ("", "local") if kind else provider != "local"
+    if is_remote:
+        return {"genres": []}
+    with appstate.meta_db._lock:
+        g = appstate.meta_db._effective_genre_expr()
+        rows = appstate.meta_db.conn.execute(
+            f"SELECT g FROM (SELECT DISTINCT ({g}) AS g FROM songs) "
+            "WHERE g IS NOT NULL AND g != '' ORDER BY g COLLATE NOCASE"
+        ).fetchall()
+    return {"genres": [r[0] for r in rows]}
+
+
+@router.get("/api/library/tuning-names")
+async def list_tuning_names(provider: str = "local"):
+    """Distinct tuning names present in the library, with per-tuning
+    counts. Powers the tuning multi-select. Sorted by `tuning_sort_key`
+    so names appear in the same musical order the sort uses
+    (feedBack#22) — E Standard first, then nearest neighbors."""
+    library_provider = _get_library_provider(provider)
+    _require_library_provider_capability(library_provider, "library.read")
+    return await _call_library_provider_async(library_provider, "tuning_names")
+
+
+@router.get("/api/library/practice-suggestions")
+def api_practice_suggestions(limit: int = 8):
+    """Growth-edge 'practice next' shelf (P3): attempted-but-not-mastered songs
+    ranked by difficulty-appropriateness × mastery-proximity, joined to song
+    metadata. Replaces the recency-only 'Keep practicing' shelf ordering. Local
+    library only — reads local practice stats."""
+    from urllib.parse import quote
+    out = []
+    for r in appstate.meta_db.growth_edge_suggestions(limit):
+        meta = appstate.meta_db.conn.execute(
+            "SELECT title, artist, tuning_name FROM songs WHERE filename = ?",
+            (r["filename"],),
+        ).fetchone()
+        title, artist, tuning_name = meta if meta else (None, None, None)
+        out.append({
+            **r,
+            "title": title or r["filename"],
+            "artist": artist or "",
+            "tuning_name": tuning_name or "",
+            "art_url": f"/api/song/{quote(r['filename'])}/art",
+        })
+    return out
+
+
+@router.get("/api/collections")
+def api_list_collections():
+    """Smart/dynamic collections (saved live library filters)."""
+    return {"collections": appstate.meta_db.list_collections()}
+
+
+@router.post("/api/collections")
+def api_create_collection(data: dict):
+    """Create a collection from a name + a set of library filter rules. It
+    immediately appears as a source in the library provider picker."""
+    if not isinstance(data, dict):
+        return JSONResponse({"error": "body must be an object"}, status_code=400)
+    name = _clean_str(data.get("name"))
+    if not name:
+        return JSONResponse({"error": "name required"}, status_code=400)
+    col = appstate.meta_db.create_collection(name, _sanitize_collection_rules(data.get("rules")))
+    _sync_collection_provider(col)
+    return {"ok": True, "collection": col}
+
+
+@router.put("/api/collections/{pid}")
+def api_update_collection(pid: int, data: dict):
+    """Rename a collection and/or replace its rules."""
+    if not isinstance(data, dict):
+        return JSONResponse({"error": "body must be an object"}, status_code=400)
+    name = _clean_str(data.get("name")) or None
+    rules = _sanitize_collection_rules(data["rules"]) if "rules" in data else None
+    col = appstate.meta_db.update_collection(pid, name=name, rules=rules)
+    if col is None:
+        return JSONResponse({"error": "collection not found"}, status_code=404)
+    _sync_collection_provider(col)
+    return {"ok": True, "collection": col}
+
+
+@router.delete("/api/collections/{pid}")
+def api_delete_collection(pid: int):
+    """Delete a collection and unregister its provider."""
+    if not appstate.meta_db.is_collection(pid):
+        return JSONResponse({"error": "collection not found"}, status_code=404)
+    appstate.meta_db.delete_playlist(pid)
+    _unregister_collection_provider(pid)
+    return {"ok": True}

lib/routers/library_extras.py

@@ -0,0 +1,75 @@
+"""Small meta_db-backed library / user-state endpoints — work keeper-chart
+prefs, favorites, personal tags, saved-for-later, and continue-playing.
+
+Extracted verbatim from ``server.py`` (R3); edits: ``@app`` -> ``@router``,
+``meta_db`` -> ``appstate.meta_db``, ``_clean_str`` from ``reqfields``. All paths
+are distinct and non-overlapping, so mounting them together (rather than at each
+original scattered site) does not change routing.
+"""
+
+from fastapi import APIRouter
+from fastapi.responses import JSONResponse
+
+import appstate
+from reqfields import _clean_str
+
+router = APIRouter()
+
+
+@router.get("/api/work/{work_key:path}/charts")
+def api_get_work_charts(work_key: str):
+    """All charts in a work + which is the keeper (your pick vs auto-pick)."""
+    return appstate.meta_db.work_charts(work_key)
+
+
+@router.put("/api/work/{work_key:path}/preferred")
+def api_set_work_preferred(work_key: str, data: dict):
+    """Set the keeper chart of a work: body {filename}. The filename must be a
+    current member of the work. Returns the refreshed chart list."""
+    fn = (data.get("filename") or "").strip()
+    if not fn:
+        return JSONResponse({"error": "filename is required"}, 400)
+    members = {c["filename"] for c in appstate.meta_db.work_charts(work_key)["charts"]}
+    if fn not in members:
+        return JSONResponse({"error": "filename is not a chart of this work"}, 400)
+    appstate.meta_db.set_chart_preferred(work_key, fn)
+    return appstate.meta_db.work_charts(work_key)
+
+
+@router.delete("/api/work/{work_key:path}/preferred")
+def api_reset_work_preferred(work_key: str):
+    """Reset a work to auto-pick (drop the explicit preferred)."""
+    appstate.meta_db.clear_chart_preferred(work_key)
+    return appstate.meta_db.work_charts(work_key)
+
+
+@router.post("/api/favorites/toggle")
+def toggle_favorite(data: dict):
+    """Toggle a song's favorite status."""
+    filename = data.get("filename", "")
+    if not filename:
+        return {"error": "No filename"}
+    new_state = appstate.meta_db.toggle_favorite(filename)
+    return {"favorite": new_state}
+
+
+@router.get("/api/tags")
+def list_tags():
+    """All personal tags in use (over still-present songs), most-used first —
+    powers the tag filter UI."""
+    return {"tags": appstate.meta_db.all_tags()}
+
+
+@router.post("/api/saved/toggle")
+def api_toggle_saved(data: dict):
+    """Add/remove a song on the reserved Saved-for-Later playlist."""
+    filename = _clean_str(data.get("filename"))
+    if not filename:
+        return JSONResponse({"error": "filename required"}, status_code=400)
+    return {"saved": appstate.meta_db.toggle_saved(filename)}
+
+
+@router.get("/api/session/continue")
+def api_session_continue():
+    """The Continue-Playing card's song (most recent play) or null."""
+    return appstate.meta_db.continue_session()

lib/routers/loops.py

@@ -0,0 +1,60 @@
+"""Practice loops — saved A/B regions per song.
+
+Extracted verbatim from ``server.py`` (R3); only the decorator receiver
+(``@app`` -> ``@router``) and the singleton reads (``meta_db`` ->
+``appstate.meta_db``) changed. See ``appstate.py`` for why the reads stay
+module attributes.
+"""
+
+from fastapi import APIRouter
+
+import appstate
+
+router = APIRouter()
+
+
+@router.get("/api/loops")
+def list_loops(filename: str):
+    # Hold the DB lock for the read: the shared single connection
+    # (check_same_thread=False) is serialized through meta_db._lock by every
+    # writer, so an unlocked SELECT here can overlap a POST/DELETE commit.
+    db = appstate.meta_db
+    with db._lock:
+        rows = db.conn.execute(
+            "SELECT id, name, start_time, end_time FROM loops WHERE filename = ? ORDER BY start_time",
+            (filename,)
+        ).fetchall()
+    return [{"id": r[0], "name": r[1], "start": r[2], "end": r[3]} for r in rows]
+
+
+@router.post("/api/loops")
+def save_loop(data: dict):
+    filename = data.get("filename", "")
+    name = data.get("name", "").strip()
+    start = data.get("start")
+    end = data.get("end")
+    if not filename or start is None or end is None:
+        return {"error": "Missing fields"}
+    db = appstate.meta_db
+    with db._lock:
+        # COUNT + INSERT under one lock so two unnamed POSTs can't read the same
+        # count and both mint "Loop N" (the count is only used to name the row).
+        if not name:
+            count = db.conn.execute(
+                "SELECT COUNT(*) FROM loops WHERE filename = ?", (filename,)
+            ).fetchone()[0]
+            name = f"Loop {count + 1}"
+        db.conn.execute(
+            "INSERT INTO loops (filename, name, start_time, end_time) VALUES (?, ?, ?, ?)",
+            (filename, name, float(start), float(end))
+        )
+        db.conn.commit()
+    return {"ok": True, "name": name}
+
+
+@router.delete("/api/loops/{loop_id}")
+def delete_loop(loop_id: int):
+    with appstate.meta_db._lock:
+        appstate.meta_db.conn.execute("DELETE FROM loops WHERE id = ?", (loop_id,))
+        appstate.meta_db.conn.commit()
+    return {"ok": True}

lib/routers/media.py

@@ -0,0 +1,162 @@
+"""Media/file-serving routes: song audio (/audio/{f}), the local-audio-path
+resolver (/api/audio-local-path), and raw sloppak member serving
+(/api/sloppak/{f}/file/{rel}).
+
+Extracted verbatim from server.py (R3) except @app->@router and the cache/static
+path seams (AUDIO_CACHE_DIR->appstate.audio_cache_dir, STATIC_DIR->
+appstate.static_dir, SLOPPAK_CACHE_DIR->appstate.sloppak_cache_dir).
+"""
+
+import ipaddress
+import re
+
+from fastapi import APIRouter, Request
+from fastapi.responses import FileResponse, JSONResponse
+
+import appstate
+import sloppak as sloppak_mod
+from dlc_paths import _get_dlc_dir, _resolve_dlc_path
+
+import logging
+log = logging.getLogger("feedBack.server")
+router = APIRouter()
+
+def _resolve_sloppak_local_file(filename: str, rel_path: str):
+    """Resolve a file inside a sloppak to its on-disk path.
+
+    Applies the same containment guards as ``serve_sloppak_file``. Returns the
+    resolved ``Path`` on success, or an ``(error, status)`` tuple on failure so
+    callers can produce their endpoint-appropriate response.
+    """
+    dlc = _get_dlc_dir()
+    if not dlc:
+        return ("not configured", 404)
+    # `filename` is caller-controlled. Contain it under DLC_DIR before it
+    # reaches the resolver (see serve_sloppak_file for the traversal rationale).
+    resolved = _resolve_dlc_path(dlc, filename)
+    if resolved is None:
+        return ("forbidden", 403)
+    # Confine to actual sloppak bundles — otherwise any plain subdirectory
+    # would become a read-any-file-under-DLC_DIR source.
+    if not sloppak_mod.is_sloppak(resolved):
+        return ("not found", 404)
+    # Canonicalise the cache key against the resolved path so equivalent URL
+    # forms of the same sloppak converge on one _source_cache entry.
+    try:
+        filename = resolved.relative_to(dlc.resolve()).as_posix()
+    except ValueError:
+        # safe_join already proved containment; fail closed regardless.
+        return ("forbidden", 403)
+    src = sloppak_mod.get_cached_source_dir(filename)
+    if src is None:
+        try:
+            src = sloppak_mod.resolve_source_dir(filename, dlc, appstate.sloppak_cache_dir)
+        except Exception:
+            return ("not found", 404)
+    # Prevent path traversal within the sloppak.
+    target = (src / rel_path).resolve()
+    try:
+        target.relative_to(src.resolve())
+    except ValueError:
+        return ("forbidden", 403)
+    if not target.exists() or not target.is_file():
+        return ("not found", 404)
+    return target
+
+
+@router.get("/api/sloppak/{filename:path}/file/{rel_path:path}")
+def serve_sloppak_file(filename: str, rel_path: str):
+    """Serve a file from inside a sloppak (stems, cover, etc.)."""
+    result = _resolve_sloppak_local_file(filename, rel_path)
+    if isinstance(result, tuple):
+        error, status = result
+        return JSONResponse({"error": error}, status)
+    target = result
+    ext = target.suffix.lower()
+    mt = {
+        ".ogg": "audio/ogg", ".opus": "audio/ogg", ".oga": "audio/ogg",
+        ".mp3": "audio/mpeg", ".wav": "audio/wav", ".flac": "audio/flac",
+        ".m4a": "audio/mp4",
+        ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
+        ".png": "image/png", ".webp": "image/webp",
+        ".json": "application/json",
+    }.get(ext)
+    return FileResponse(str(target), media_type=mt) if mt else FileResponse(str(target))
+
+
+@router.get("/api/audio-local-path")
+def audio_local_path(url: str, request: Request):
+    """Return absolute local filesystem path for a song URL (Electron desktop only).
+
+    Accepts ``/audio/<path>`` where ``<path>`` may include subdirectory segments —
+    no scheme, no host, no query string, no fragment.  The resolved path must stay
+    inside appstate.audio_cache_dir or appstate.static_dir; ``..`` traversal, backslashes, and
+    absolute ``filename`` values are rejected.
+
+    Also accepts ``/api/sloppak/<filename>/file/<rel>`` (percent-encoded, as
+    emitted by the highway song payload) and resolves it to the unpacked
+    sloppak cache file via the same containment guards as
+    ``serve_sloppak_file`` — this lets the desktop engine play a feedpak
+    full-mix natively under WASAPI-exclusive output.
+
+    This endpoint returns a raw filesystem path and is intended exclusively for
+    the Electron desktop process (which runs on loopback). Requests from non-
+    loopback clients are rejected with 403.
+    """
+    # Loopback-only — only the local Electron process should call this
+    client_host = request.client.host if request.client else None
+    try:
+        is_loopback = bool(client_host and ipaddress.ip_address(client_host).is_loopback)
+    except ValueError:
+        is_loopback = client_host == "localhost"
+    if not is_loopback:
+        return JSONResponse({"error": "forbidden"}, status_code=403)
+    # Sloppak in-pack file (feedpak full-mix): /api/sloppak/<fn>/file/<rel>.
+    # Both segments arrive percent-encoded (built with urllib quote() in the
+    # highway payload); decode before handing to the shared resolver, which
+    # re-applies all containment guards on the decoded values.
+    slop_match = re.fullmatch(r"/api/sloppak/([^?#]+)/file/([^?#]+)", url)
+    if slop_match:
+        from urllib.parse import unquote
+
+        result = _resolve_sloppak_local_file(
+            unquote(slop_match.group(1)), unquote(slop_match.group(2))
+        )
+        if isinstance(result, tuple):
+            error, status = result
+            return JSONResponse({"error": error}, status_code=status)
+        return JSONResponse({"path": str(result)})
+    # Accept only simple /audio/<filename> — no scheme, no host, no query/fragment
+    if not re.fullmatch(r"/audio/[^?#]+", url):
+        return JSONResponse({"error": "invalid url"}, status_code=400)
+    filename = url[len("/audio/"):]
+    # Reject traversal, absolute paths, and backslash separators
+    if ".." in filename.split("/") or filename.startswith("/") or "\\" in filename:
+        return JSONResponse({"error": "invalid url"}, status_code=400)
+    for d in [appstate.audio_cache_dir, appstate.static_dir]:
+        candidate = (d / filename).resolve()
+        # Ensure resolved path is inside the allowed directory
+        try:
+            candidate.relative_to(d.resolve())
+        except ValueError:
+            continue
+        if candidate.is_file():
+            return JSONResponse({"path": str(candidate)})
+    return JSONResponse({"error": "not found"}, status_code=404)
+
+
+@router.get("/audio/{filename:path}")
+def serve_audio(filename: str):
+    """Serve audio files from the writable audio cache directory."""
+    # Reject traversal attempts and absolute-path components
+    if ".." in filename.split("/") or filename.startswith("/") or "\\" in filename:
+        return JSONResponse({"error": "not found"}, status_code=404)
+    for d in [appstate.audio_cache_dir, appstate.static_dir]:
+        candidate = (d / filename).resolve()
+        try:
+            candidate.relative_to(d.resolve())
+        except ValueError:
+            continue
+        if candidate.is_file():
+            return FileResponse(str(candidate))
+    return JSONResponse({"error": "not found"}, status_code=404)

lib/routers/playlists.py

@@ -0,0 +1,267 @@
+"""Playlists + custom playlist covers (fee[dB]ack v0.3.0).
+
+Extracted verbatim from ``server.py`` (R3). Edits: ``@app`` -> ``@router``,
+``meta_db`` -> ``appstate.meta_db``, ``CONFIG_DIR`` -> ``appstate.config_dir``
+(both read at call time through the seam), and ``_clean_str`` now imports from
+``reqfields``. See ``appstate.py``.
+"""
+
+import logging
+import os
+import tempfile
+from pathlib import Path
+
+from fastapi import APIRouter
+from fastapi.responses import FileResponse, JSONResponse
+
+import appstate
+from reqfields import _clean_str
+
+log = logging.getLogger("feedBack.server")
+
+router = APIRouter()
+
+# Cache policy for the custom-cover file response: revalidate every time so a
+# replaced cover is never served stale (pairs with the mtime-ns URL token).
+_ART_CACHE_HEADERS = {"Cache-Control": "no-cache"}
+
+
+def _playlist_cover_path(pid) -> Path | None:
+    """Filesystem path of a playlist's optional custom cover image (PNG),
+    stored under CONFIG_DIR. Returns None for a non-integer id."""
+    try:
+        pid = int(pid)
+    except (TypeError, ValueError):
+        return None
+    return appstate.config_dir / "playlist_covers" / f"{pid}.png"
+
+
+def _playlist_cover_url(pid) -> str | None:
+    cover = _playlist_cover_path(pid)
+    if not cover or not cover.exists():
+        return None
+    try:
+        # Nanosecond mtime so a same-second replace/remove/re-upload still
+        # changes the cache-bust token (int seconds could collide → stale image).
+        mt = cover.stat().st_mtime_ns
+    except OSError:
+        mt = 0
+    return f"/api/playlists/{pid}/cover?v={mt}"
+
+
+@router.get("/api/playlists")
+def api_list_playlists():
+    lists = appstate.meta_db.list_playlists()
+    for pl in lists:
+        pl["cover_url"] = _playlist_cover_url(pl["id"])
+    return lists
+
+
+@router.post("/api/playlists")
+def api_create_playlist(data: dict):
+    name = _clean_str(data.get("name"))
+    if not (1 <= len(name) <= 100):
+        return JSONResponse({"error": "Playlist name must be 1–100 characters."}, status_code=400)
+    # kind='album' = a curated album (§7.2): hand-picked works, a chosen chart
+    # per slot, played front-to-back on the queue. Absent/None = a regular mix.
+    kind = _clean_str(data.get("kind")) or None
+    if kind not in (None, "album"):
+        return JSONResponse({"error": "kind must be 'album' or omitted"}, status_code=400)
+    return appstate.meta_db.create_playlist(name, kind=kind)
+
+
+@router.get("/api/playlists/{pid}")
+def api_get_playlist(pid: int):
+    pl = appstate.meta_db.get_playlist(pid)
+    if pl is None:
+        return JSONResponse({"error": "not found"}, status_code=404)
+    pl["cover_url"] = _playlist_cover_url(pid)
+    return pl
+
+
+@router.patch("/api/playlists/{pid}")
+def api_rename_playlist(pid: int, data: dict):
+    pl = appstate.meta_db.get_playlist(pid)
+    if pl is None:
+        return JSONResponse({"error": "not found"}, status_code=404)
+    if pl["system_key"]:
+        return JSONResponse({"error": "System playlists cannot be renamed."}, status_code=400)
+    name = _clean_str(data.get("name"))
+    if not (1 <= len(name) <= 100):
+        return JSONResponse({"error": "Playlist name must be 1–100 characters."}, status_code=400)
+    appstate.meta_db.rename_playlist(pid, name)
+    return appstate.meta_db.get_playlist(pid)
+
+
+@router.delete("/api/playlists/{pid}")
+def api_delete_playlist(pid: int):
+    pl = appstate.meta_db.get_playlist(pid)
+    if pl is None:
+        return JSONResponse({"error": "not found"}, status_code=404)
+    if pl["system_key"]:
+        return JSONResponse({"error": "System playlists cannot be deleted."}, status_code=400)
+    if not appstate.meta_db.delete_playlist(pid):   # vanished under us (concurrent delete)
+        return JSONResponse({"error": "not found"}, status_code=404)
+    cover = _playlist_cover_path(pid)       # drop any custom cover with the playlist
+    if cover and cover.exists():
+        try:
+            cover.unlink()
+        except OSError:
+            pass
+    return {"ok": True}
+
+
+@router.post("/api/playlists/{pid}/songs")
+def api_add_playlist_song(pid: int, data: dict):
+    if appstate.meta_db.get_playlist(pid) is None:
+        return JSONResponse({"error": "not found"}, status_code=404)
+    filename = _clean_str(data.get("filename"))
+    if not filename:
+        return JSONResponse({"error": "filename required"}, status_code=400)
+    if appstate.meta_db.add_playlist_song(pid, filename) is None:   # playlist vanished under us
+        return JSONResponse({"error": "not found"}, status_code=404)
+    pl = appstate.meta_db.get_playlist(pid)
+    return pl if pl is not None else JSONResponse({"error": "not found"}, status_code=404)
+
+
+@router.patch("/api/playlists/{pid}/songs/{filename:path}")
+def api_update_playlist_slot(pid: int, filename: str, data: dict):
+    """Edit one curated-album slot: {"arrangement": name|null} pins/clears the
+    slot's arrangement; {"chart_filename": fn} swaps the slot to another chart
+    of the same work (position + pin kept). Albums only — a mix has no slots."""
+    pl = appstate.meta_db.get_playlist(pid)
+    if pl is None:
+        return JSONResponse({"error": "not found"}, status_code=404)
+    if pl.get("kind") != "album":
+        return JSONResponse({"error": "Slot editing is for albums."}, status_code=400)
+    kwargs = {}
+    if "chart_filename" in data:
+        new_fn = _clean_str(data.get("chart_filename"))
+        if not new_fn:
+            return JSONResponse({"error": "chart_filename must be a filename"}, status_code=400)
+        kwargs["new_filename"] = new_fn
+    if "arrangement" in data:
+        arr = data.get("arrangement")
+        if arr is not None and not (isinstance(arr, str) and 1 <= len(arr.strip()) <= 100):
+            return JSONResponse({"error": "arrangement must be a name or null"}, status_code=400)
+        kwargs["arrangement"] = arr.strip() if isinstance(arr, str) else None
+    if not kwargs:
+        return JSONResponse({"error": "nothing to update"}, status_code=400)
+    if appstate.meta_db.update_playlist_slot(pid, filename, **kwargs) is None:
+        return JSONResponse(
+            {"error": "no such slot, or the chart isn't a version of this song"},
+            status_code=400)
+    return appstate.meta_db.get_playlist(pid)
+
+
+@router.delete("/api/playlists/{pid}/songs/{filename:path}")
+def api_remove_playlist_song(pid: int, filename: str):
+    if appstate.meta_db.get_playlist(pid) is None:
+        return JSONResponse({"error": "not found"}, status_code=404)
+    appstate.meta_db.remove_playlist_song(pid, filename)
+    pl = appstate.meta_db.get_playlist(pid)
+    return pl if pl is not None else JSONResponse({"error": "not found"}, status_code=404)
+
+
+@router.post("/api/playlists/{pid}/reorder")
+def api_reorder_playlist(pid: int, data: dict):
+    pl = appstate.meta_db.get_playlist(pid)
+    if pl is None:
+        return JSONResponse({"error": "not found"}, status_code=404)
+    order = data.get("order")
+    if not isinstance(order, list) or not all(isinstance(f, str) for f in order):
+        return JSONResponse({"error": "order must be a list of filenames"}, status_code=400)
+    # Require an exact permutation of the playlist's current songs: a list with
+    # duplicates, omissions, or extras would otherwise produce duplicate
+    # positions / a partial reorder while still returning 200.
+    current = [s["filename"] for s in pl["songs"]]
+    if len(order) != len(current) or sorted(order) != sorted(current):
+        return JSONResponse(
+            {"error": "order must be a permutation of the playlist's current songs"},
+            status_code=400,
+        )
+    appstate.meta_db.reorder_playlist(pid, order)
+    return appstate.meta_db.get_playlist(pid)
+
+
+@router.post("/api/playlists/{pid}/cover")
+async def api_set_playlist_cover(pid: int, data: dict):
+    """Set a playlist's custom cover from a base64 / data-URL image (PNG/JPG).
+    Overrides the content-dependent (song-art) cover. Stored as a small PNG
+    thumbnail under CONFIG_DIR/playlist_covers/."""
+    if appstate.meta_db.get_playlist(pid) is None:
+        return JSONResponse({"error": "not found"}, status_code=404)
+    import base64
+    import io
+    b64 = data.get("image", "")
+    # Guard the type before the `","` membership test — a non-string image
+    # (e.g. {"image": 123} / null) would otherwise raise TypeError → 500.
+    # Mirrors the avatar/song-art upload guard.
+    if not isinstance(b64, str) or not b64:
+        return JSONResponse({"error": "No image data"}, status_code=400)
+    if "," in b64:
+        b64 = b64.split(",", 1)[1]
+    if not b64:
+        return JSONResponse({"error": "No image data"}, status_code=400)
+    try:
+        img_data = base64.b64decode(b64)
+    except Exception:
+        return JSONResponse({"error": "Invalid base64"}, status_code=400)
+    cover = _playlist_cover_path(pid)
+    cover.parent.mkdir(parents=True, exist_ok=True)
+    # Decode/validate the image — a bad payload is a CLIENT error (400), and the
+    # message stays generic so it can't echo internals.
+    try:
+        from PIL import Image
+        img = Image.open(io.BytesIO(img_data)).convert("RGB")
+        img.thumbnail((640, 640))                  # covers stay small
+    except Exception:
+        return JSONResponse({"error": "Invalid image"}, status_code=400)
+    # Persist. A save/replace failure is a SERVER error (500, logged, no
+    # filesystem detail leaked) — the pre-split handler mislabeled these as 400
+    # and echoed the exception. A unique temp name in the cover dir (not a shared
+    # `{pid}.png.tmp`) means two concurrent uploads can't clobber each other's
+    # temp file; the atomic replace publishes. Re-check the playlist still exists
+    # just before publishing so a delete that raced the decode above can't leave
+    # an orphan cover — cheap belt-and-braces; FeedBack is single-user
+    # (Principle I), so a full per-playlist lock would be for a race the
+    # deployment model precludes.
+    tmp = None
+    try:
+        # mkstemp is inside the try too: an unwritable dir / full disk raises
+        # here, and that's the same class of persistence failure as save/replace.
+        fd, tmp_name = tempfile.mkstemp(prefix=f".{pid}.", suffix=".png.tmp", dir=str(cover.parent))
+        tmp = Path(tmp_name)
+        with os.fdopen(fd, "wb") as f:
+            img.save(f, "PNG")
+        if appstate.meta_db.get_playlist(pid) is None:
+            tmp.unlink(missing_ok=True)
+            return JSONResponse({"error": "not found"}, status_code=404)
+        tmp.replace(cover)
+    except Exception:
+        if tmp is not None:
+            tmp.unlink(missing_ok=True)
+        log.exception("playlist cover save failed (pid=%s)", pid)
+        return JSONResponse({"error": "could not save cover"}, status_code=500)
+    return {"ok": True, "cover_url": _playlist_cover_url(pid)}
+
+
+@router.get("/api/playlists/{pid}/cover")
+def api_get_playlist_cover(pid: int):
+    cover = _playlist_cover_path(pid)
+    if not cover or not cover.exists():
+        return JSONResponse({"error": "not found"}, status_code=404)
+    # no-cache (revalidate) like song art, so a replaced cover is never served
+    # stale — pairs with the mtime-ns cache-bust token on the URL.
+    return FileResponse(str(cover), media_type="image/png", headers=_ART_CACHE_HEADERS)
+
+
+@router.delete("/api/playlists/{pid}/cover")
+def api_delete_playlist_cover(pid: int):
+    cover = _playlist_cover_path(pid)
+    if cover and cover.exists():
+        try:
+            cover.unlink()
+        except OSError:
+            pass
+    return {"ok": True}

lib/routers/profile.py

@@ -0,0 +1,138 @@
+"""Player profile — identity, avatars (bundled + custom uploads), and progress.
+
+Extracted verbatim from ``server.py`` (R3); edits: ``@app`` -> ``@router``,
+``meta_db`` -> ``appstate.meta_db``, ``CONFIG_DIR``/``STATIC_DIR`` ->
+``appstate.config_dir``/``appstate.static_dir`` (seam), ``_clean_str`` from
+``reqfields``, ``_get_progression_content()`` ->
+``appstate.get_progression_content()``. The bundled-avatar lister moves with it.
+"""
+
+import logging
+import secrets
+
+from fastapi import APIRouter
+from fastapi.responses import FileResponse, JSONResponse
+
+import appstate
+from reqfields import _clean_str
+
+log = logging.getLogger("feedBack.server")
+
+router = APIRouter()
+
+
+def _list_bundled_avatars() -> list[str]:
+    """Bundled default avatar filenames under static/v3/avatars/."""
+    d = appstate.static_dir / "v3" / "avatars"
+    if not d.is_dir():
+        return []
+    exts = {".svg", ".png", ".webp"}
+    return sorted(
+        p.name for p in d.iterdir()
+        if p.is_file() and p.suffix.lower() in exts and not p.name.startswith(".")
+    )
+
+
+@router.get("/api/profile")
+def api_get_profile():
+    profile = appstate.meta_db.get_profile()
+    # Equipped cosmetics ride along (resolved to their payloads) so the theme
+    # and avatar frame apply at boot without an extra request. Never let a
+    # cosmetics/content problem break the profile read.
+    cosmetics = {}
+    try:
+        shop = appstate.get_progression_content()["shop"]
+        for slot, item_id in appstate.meta_db.get_equipped().items():
+            item = shop.get(item_id)
+            if item:
+                cosmetics[slot] = {"item_id": item_id, "payload": item["payload"]}
+    except Exception:
+        log.warning("profile cosmetics enrich failed", exc_info=True)
+    profile["cosmetics"] = cosmetics
+    return profile
+
+
+
+@router.post("/api/profile")
+def api_set_profile(data: dict):
+    """Set/update the player profile. Body: {display_name, avatar:{type,value}}.
+    avatar.type is 'default' (value = bundled filename) or 'upload' (value =
+    the /api/profile/avatar/<name> URL returned by the upload endpoint); omit
+    avatar to keep the existing one (name-only edit)."""
+    name = _clean_str(data.get("display_name"))
+    if not (1 <= len(name) <= 32):
+        return JSONResponse({"error": "Display name must be 1–32 characters."}, status_code=400)
+    avatar = data.get("avatar")
+    if avatar is None:
+        avatar = {}            # omitted → keep the current avatar (name-only edit)
+    elif not isinstance(avatar, dict):
+        return JSONResponse({"error": "avatar must be an object."}, status_code=400)
+    atype = avatar.get("type")
+    aval = _clean_str(avatar.get("value"))
+    avatar_url = None
+    if atype == "default":
+        if aval not in _list_bundled_avatars():
+            return JSONResponse({"error": "Unknown default avatar."}, status_code=400)
+        avatar_url = f"/static/v3/avatars/{aval}"
+    elif atype == "upload":
+        from safepath import safe_join
+        fname = aval.rsplit("/", 1)[-1] if aval.startswith("/api/profile/avatar/") else ""
+        target = safe_join(appstate.config_dir / "avatars", fname) if fname else None
+        if target is None or not target.is_file():
+            return JSONResponse({"error": "Uploaded avatar not found."}, status_code=400)
+        avatar_url = f"/api/profile/avatar/{fname}"
+    elif atype:
+        return JSONResponse({"error": "Unknown avatar type."}, status_code=400)
+    # atype None/missing → keep the current avatar (name-only edit).
+    return appstate.meta_db.set_profile(name, avatar_url)
+
+
+@router.get("/api/profile/avatars")
+def api_list_avatars():
+    return [{"name": n, "url": f"/static/v3/avatars/{n}"} for n in _list_bundled_avatars()]
+
+
+@router.post("/api/profile/avatar")
+def api_upload_avatar(data: dict):
+    """Upload a custom avatar as base64 (mirrors the album-art upload pattern).
+    Re-encodes to a ≤512px PNG under appstate.config_dir/avatars/."""
+    import base64
+    import io
+    b64 = data.get("image", "")
+    if not isinstance(b64, str) or not b64:
+        return JSONResponse({"error": "No image data"}, status_code=400)
+    if "," in b64:
+        b64 = b64.split(",", 1)[1]
+    try:
+        raw = base64.b64decode(b64)
+    except Exception:
+        return JSONResponse({"error": "Invalid base64"}, status_code=400)
+    if len(raw) > 6 * 1024 * 1024:
+        return JSONResponse({"error": "Image too large (max 6 MB)."}, status_code=400)
+    avatars_dir = appstate.config_dir / "avatars"
+    avatars_dir.mkdir(parents=True, exist_ok=True)
+    try:
+        from PIL import Image
+        img = Image.open(io.BytesIO(raw)).convert("RGB")
+        img.thumbnail((512, 512))
+        fname = f"upload-{secrets.token_hex(4)}.png"  # token busts caches on change
+        img.save(str(avatars_dir / fname), "PNG")
+    except Exception as e:
+        return JSONResponse({"error": f"Invalid image: {e}"}, status_code=400)
+    return {"url": f"/api/profile/avatar/{fname}"}
+
+
+@router.get("/api/profile/avatar/{name}")
+def api_get_avatar(name: str):
+    from safepath import safe_join
+    target = safe_join(appstate.config_dir / "avatars", name)
+    if target is None or not target.is_file():
+        return JSONResponse({"error": "not found"}, status_code=404)
+    return FileResponse(str(target), media_type="image/png")
+
+
+@router.get("/api/profile/progress")
+def api_profile_progress():
+    """One call for the whole profile badge: {level, xp, xp_in_level,
+    xp_to_next, current_streak, best_streak, last_active_date}."""
+    return appstate.meta_db.get_progress()

lib/routers/progression.py

@@ -0,0 +1,230 @@
+"""Progression (spec 010) — mastery rank, challenges, quests, onboarding paths.
+
+Extracted verbatim from ``server.py`` (R3); edits: ``@app`` -> ``@router``,
+``meta_db`` -> ``appstate.meta_db``, ``_clean_str`` from ``reqfields``, and the
+two shared server accessors read through the seam:
+``_get_progression_content()`` -> ``appstate.get_progression_content()`` and
+``_builtin_diagnostic_filename()`` -> ``appstate.builtin_diagnostic_filename()``.
+The exclusive helpers (_goal_ui_progress, _progression_overview) + the
+_PROGRESSION_EVENT_TYPES whitelist move with it.
+"""
+
+import math
+
+from fastapi import APIRouter
+from fastapi.responses import JSONResponse
+
+import appstate
+from reqfields import _clean_str
+
+router = APIRouter()
+
+
+def _goal_ui_progress(goal: dict, state: dict, streak: int, xp_total: int) -> tuple:
+    """(count, target) for a challenge/quest progress bar. Count goals show
+    n/target; threshold goals show how far the live stat is along the line."""
+    import progression as progression_mod
+    gtype = goal.get("type")
+    if gtype in progression_mod.COUNT_GOAL_TYPES:
+        target = int(goal.get("target") or 1)
+        count = target if state.get("completed") else min(int(state.get("count") or 0), target)
+        return count, target
+    if gtype == "streak_reached":
+        target = int(goal.get("days") or 1)
+        return (target if state.get("completed") else min(streak, target)), target
+    if gtype == "db_earned":
+        target = int(goal.get("amount") or 1)
+        return (target if state.get("completed") else min(xp_total, target)), target
+    return 0, 1
+
+
+def _progression_overview() -> dict:
+    """The full GET /api/progression payload (also the capability `inspect`
+    result): rank, onboarding, per-path challenge checklists, quests, wallet."""
+    import progression as progression_mod
+    from datetime import datetime as _dt
+    content = appstate.get_progression_content()
+    now = _dt.now()
+    appstate.meta_db.ensure_quest_period(content, now)
+
+    state = appstate.meta_db.get_progression_state()
+    player_paths = appstate.meta_db.get_player_paths()
+    challenge_state = appstate.meta_db.get_challenge_state()
+    wallet = appstate.meta_db.get_wallet()
+    streak_progress = appstate.meta_db.get_progress()
+    streak = int(streak_progress.get("current_streak") or 0)
+    xp_total = wallet["lifetime_db"]
+    keys = progression_mod.period_keys(now)
+
+    def _path_order(pid):
+        pdef = content["paths"].get(pid) or {}
+        return (pdef.get("order") or 0, pid)
+
+    paths_payload = []
+    for pid in sorted(player_paths, key=_path_order):
+        pdef = content["paths"].get(pid)
+        level = player_paths[pid]
+        if not pdef:
+            # Path selected under older content that no longer ships: keep its
+            # rank contribution visible rather than silently dropping it.
+            paths_payload.append({"id": pid, "name": pid, "icon": "", "level": level,
+                                  "max_level": level, "next": None})
+            continue
+        next_block = None
+        active = progression_mod.active_challenges(content, pid, level)
+        if active:
+            level_def = next(e for e in pdef["levels"] if e["level"] == level + 1)
+            challenges = []
+            completed_count = 0
+            for ch in active:
+                st = challenge_state.get(ch["id"]) or {}
+                count, target = _goal_ui_progress(ch["goal"], st, streak, xp_total)
+                if st.get("completed"):
+                    completed_count += 1
+                challenges.append({
+                    "id": ch["id"],
+                    "title": ch["title"],
+                    "description": ch["description"],
+                    "count": count,
+                    "target": target,
+                    "completed": bool(st.get("completed")),
+                    "completed_at": st.get("completed_at"),
+                })
+            next_block = {
+                "level": level + 1,
+                "required": level_def["required"],
+                "completed": completed_count,
+                "challenges": challenges,
+            }
+        paths_payload.append({
+            "id": pid,
+            "name": pdef["name"],
+            "icon": pdef["icon"],
+            "level": level,
+            "max_level": progression_mod.path_max_level(content, pid),
+            "next": next_block,
+        })
+
+    available = [
+        {"id": pid, "name": pdef["name"], "icon": pdef["icon"]}
+        for pid, pdef in sorted(content["paths"].items(), key=lambda kv: (kv[1].get("order") or 0, kv[0]))
+        if pid not in player_paths
+    ]
+
+    quest_rows = appstate.meta_db.get_quest_rows(keys)
+    quests_payload = {}
+    for period_type in ("daily", "weekly"):
+        pool = content["quests"][period_type]["pool"]
+        quests = []
+        for row in quest_rows:
+            if row["period_type"] != period_type:
+                continue
+            qdef = pool.get(row["quest_id"])
+            if not qdef:
+                continue  # removed from the pool mid-period: hide, keep the row
+            count, target = _goal_ui_progress(qdef["goal"], row, streak, xp_total)
+            quests.append({
+                "id": row["quest_id"],
+                "title": qdef["title"],
+                "description": qdef["description"],
+                "reward_db": row["reward_db"],
+                "count": count,
+                "target": target,
+                "completed": row["completed"],
+                "completed_at": row["completed_at"],
+            })
+        quests_payload[period_type] = {
+            "period_key": keys[period_type],
+            "resets_at": progression_mod.period_resets_at(period_type, now).isoformat(),
+            "quests": quests,
+        }
+
+    return {
+        "mastery_rank": progression_mod.mastery_rank(state["calibration_status"], player_paths),
+        "onboarding": {
+            "calibration_status": state["calibration_status"],
+            "calibration_completed_at": state["calibration_completed_at"],
+            "diagnostic_filename": appstate.builtin_diagnostic_filename(),
+        },
+        "paths": paths_payload,
+        "available_paths": available,
+        "quests": quests_payload,
+        "wallet": wallet,
+    }
+
+
+@router.get("/api/progression")
+def api_progression():
+    return _progression_overview()
+
+
+@router.post("/api/progression/paths")
+def api_progression_add_paths(data: dict):
+    """Select instrument paths. Body: {add: [path_id, ...]}. Idempotent;
+    removal is unsupported (Mastery Rank never decreases)."""
+    add = data.get("add")
+    if not isinstance(add, list) or not add:
+        return JSONResponse({"error": "add must be a non-empty list of path ids"}, status_code=400)
+    content = appstate.get_progression_content()
+    for pid in add:
+        if not isinstance(pid, str) or pid not in content["paths"]:
+            return JSONResponse({"error": f"unknown path: {pid!r}"}, status_code=400)
+    appstate.meta_db.add_player_paths(add)
+    return _progression_overview()
+
+
+@router.post("/api/progression/onboarding")
+def api_progression_onboarding(data: dict):
+    """Onboarding calibration choice. Body: {action: "skip"} — completing the
+    calibration needs no endpoint, it flows through the normal /api/stats path."""
+    if _clean_str(data.get("action")) != "skip":
+        return JSONResponse({"error": "action must be 'skip'"}, status_code=400)
+    # Spec invariant: onboarding requires picking at least one instrument path
+    # before finishing, so skipping straight to rank 1 with no paths would
+    # leave a rank that can never grow. Only enforced when the content bundle
+    # actually defines paths — broken/empty content must never brick onboarding.
+    if appstate.get_progression_content()["paths"] and not appstate.meta_db.get_player_paths():
+        return JSONResponse(
+            {"error": "select at least one instrument path before skipping calibration"},
+            status_code=400,
+        )
+    appstate.meta_db.skip_calibration()
+    return _progression_overview()
+
+
+# Externally postable progression events. song_completed is deliberately NOT
+# here: it is server-derived inside /api/stats so the scored-session authority
+# stays in one place.
+_PROGRESSION_EVENT_TYPES = {"minigame_run"}
+
+
+@router.post("/api/progression/events")
+def api_progression_events(data: dict):
+    """Generic progression-event intake for plugins (capability `record-event`).
+    Body: {type, payload}. Whitelisted types, scalar payload values only."""
+    etype = _clean_str(data.get("type"))
+    if etype not in _PROGRESSION_EVENT_TYPES:
+        return JSONResponse(
+            {"error": f"event type must be one of {sorted(_PROGRESSION_EVENT_TYPES)}"},
+            status_code=400,
+        )
+    payload = data.get("payload")
+    if payload is None:
+        payload = {}
+    if not isinstance(payload, dict) or len(payload) > 16:
+        return JSONResponse({"error": "payload must be a small object"}, status_code=400)
+    clean = {}
+    for key, value in payload.items():
+        if not isinstance(key, str) or len(key) > 64:
+            return JSONResponse({"error": "payload keys must be short strings"}, status_code=400)
+        if value is None:
+            continue
+        if isinstance(value, bool) or (
+            not isinstance(value, (int, float, str))
+        ) or (isinstance(value, float) and not math.isfinite(value)) or (
+            isinstance(value, str) and len(value) > 256
+        ):
+            return JSONResponse({"error": "payload values must be short strings or finite numbers"}, status_code=400)
+        clean[key] = value
+    summary = appstate.meta_db.record_progression_event(etype, clean, appstate.get_progression_content())
+    return {"ok": True, "progression": summary}

lib/routers/shop.py

@@ -0,0 +1,62 @@
+"""Cosmetics shop (spec 010) — buy/equip avatars & themes with earned currency.
+
+Extracted verbatim from ``server.py`` (R3); edits: ``@app`` -> ``@router``,
+``meta_db`` -> ``appstate.meta_db``, ``_get_progression_content()`` ->
+``appstate.get_progression_content()`` (the accessor is injected into the seam;
+its lazy content cache stays in server.py).
+"""
+
+from fastapi import APIRouter
+from fastapi.responses import JSONResponse
+
+import appstate
+from reqfields import _clean_str
+
+router = APIRouter()
+
+
+@router.get("/api/shop")
+def api_shop():
+    content = appstate.get_progression_content()
+    owned = appstate.meta_db.get_owned_items()
+    equipped = appstate.meta_db.get_equipped()
+    items = [
+        {**item, "owned": iid in owned, "equipped": equipped.get(item["slot"]) == iid}
+        for iid, item in sorted(content["shop"].items())
+    ]
+    return {"items": items, "wallet": appstate.meta_db.get_wallet()}
+
+
+@router.post("/api/shop/buy")
+def api_shop_buy(data: dict):
+    """Spend Decibels on a cosmetic. Atomic: balance check + spend + ownership
+    in one transaction. Decibels are earned by playing only — never purchasable."""
+    item_id = _clean_str(data.get("item_id"))
+    item = appstate.get_progression_content()["shop"].get(item_id)
+    if not item:
+        return JSONResponse({"error": f"unknown item: {item_id!r}"}, status_code=400)
+    status, wallet = appstate.meta_db.buy_shop_item(item)
+    if status == "owned":
+        return JSONResponse({"error": "already owned", "wallet": wallet}, status_code=409)
+    if status == "insufficient":
+        return JSONResponse({"error": "insufficient balance", "wallet": wallet}, status_code=402)
+    return {"ok": True, "item_id": item_id, "wallet": wallet}
+
+
+@router.post("/api/shop/equip")
+def api_shop_equip(data: dict):
+    """Equip an owned cosmetic into its slot. Body: {slot, item_id|null}
+    (null unequips, restoring the default look)."""
+    import progression as progression_mod
+    slot = _clean_str(data.get("slot"))
+    if slot not in progression_mod.SHOP_SLOTS:
+        return JSONResponse({"error": f"slot must be one of {sorted(progression_mod.SHOP_SLOTS)}"}, status_code=400)
+    item_id = data.get("item_id")
+    if item_id is not None:
+        item_id = _clean_str(item_id)
+        item = appstate.get_progression_content()["shop"].get(item_id)
+        if not item or item["slot"] != slot:
+            return JSONResponse({"error": f"unknown item for slot {slot}: {item_id!r}"}, status_code=400)
+        if item_id not in appstate.meta_db.get_owned_items():
+            return JSONResponse({"error": "item not owned"}, status_code=403)
+    return {"ok": True, "equipped": appstate.meta_db.equip_item(slot, item_id)}

lib/routers/song.py

@@ -0,0 +1,867 @@
+"""Song routes: upload / delete / metadata (user-meta, overrides, catalog meta
+write-back), gap-fill proposals, and the per-song info payload.
+
+Extracted verbatim from server.py (R3) except @app->@router and the seam reads:
+meta_db->appstate.meta_db, and the scan/ingest helpers that stay in server.py
+(the scan lifecycle owns them) -> appstate.<callable>: kick_scan,
+invalidate_song_caches, stat_for_cache, scan_status() (a getter — the underlying
+dict is reassigned), plus art_override_paths. The gap-fill MBID/ISRC regexes live
+in lib/enrichment.py and are reached as enrichment.X.
+"""
+
+import os
+import shutil
+import tempfile
+import threading
+from pathlib import Path
+
+from fastapi import APIRouter, Request, UploadFile
+from fastapi.responses import JSONResponse
+from starlette.concurrency import run_in_threadpool
+
+import appstate
+import enrichment
+import loosefolder as loosefolder_mod
+import sloppak as sloppak_mod
+from dlc_paths import _get_dlc_dir, _resolve_dlc_path
+from scan_worker import _extract_meta_for_file
+
+import logging
+log = logging.getLogger("feedBack.server")
+router = APIRouter()
+
+_ALLOWED_SONG_EXTS = set(sloppak_mod.SONG_EXTS)
+
+_MAX_UPLOAD_BYTES = 1024 * 1024 * 1024  # 1 GB — covers sloppaks bundled with stems
+
+
+# Per-request batch cap. Lets a user drop a whole album of sloppaks at once
+# without giving a hostile client a 1000-file DoS surface via Starlette's
+# default max_files=1000. The pre-parse Content-Length guard is sized as
+# _MAX_UPLOAD_FILES * _MAX_UPLOAD_BYTES + slack.
+_MAX_UPLOAD_FILES = 50
+
+
+# Serializes the mutating step of upload (os.replace into DLC_DIR) with
+# delete_song so the two endpoints can't interleave on the same path —
+# e.g. an upload finishing right after a concurrent delete shouldn't
+# resurrect a song the user just removed, and a delete arriving mid-
+# overwrite shouldn't strand a half-written file. threading.Lock (not
+# asyncio.Lock) because delete_song is sync (runs in the threadpool);
+# upload acquires it inside ``run_in_threadpool`` for the same reason.
+_song_io_lock = threading.Lock()
+
+
+def _commit_uploaded_song(tmp_path: Path, dest: Path, overwrite: bool, base: str):
+    """Atomically move a validated temp upload into ``dest`` under ``_song_io_lock``.
+
+    Returns ``None`` on success or an error result dict matching the upload
+    endpoint's contract. Holds the lock across the directory re-check and
+    the final ``os.replace`` so a concurrent delete or upload can't slip
+    between them. Always cleans up the temp file on the error paths.
+    """
+    with _song_io_lock:
+        if dest.exists():
+            if not overwrite:
+                # Lost the race against a concurrent upload of the same name.
+                try:
+                    tmp_path.unlink()
+                except OSError:
+                    pass
+                return {"status": "exists", "filename": base,
+                        "error": "A file with this name already exists"}
+            # Re-check directory state under the lock — the pre-check
+            # may have raced an unrelated mkdir, and a sloppak directory
+            # has to be removed before os.replace() can write over it.
+            if dest.is_dir():
+                if not sloppak_mod.is_sloppak(dest):
+                    try:
+                        tmp_path.unlink()
+                    except OSError:
+                        pass
+                    return {"status": "exists", "filename": base,
+                            "error": "A directory with this name exists and is not "
+                                     "a sloppak — refusing to overwrite"}
+                shutil.rmtree(str(dest))
+        os.replace(str(tmp_path), str(dest))
+    return None
+
+
+@router.post("/api/songs/upload")
+async def upload_song(request: Request):
+    """Upload one or more .sloppak files into the configured DLC folder.
+
+    Multipart body with one or more ``file`` fields (up to ``_MAX_UPLOAD_FILES``
+    per request). Query string:
+      ``overwrite=1`` — replace existing files with the same name.
+
+    Response shape (always HTTP 200 once we've gotten past request-level guards
+    like DLC-not-configured / payload-too-large):
+      ``{"results": [{"filename": "...", "status": "ok" | "exists" | "error",
+                       "error"?: "...", "size"?: N, "format"?: "sloppak"}, ...]}``
+    Per-file conflicts surface as ``status: "exists"`` so a batch upload can
+    surface ALL conflicts at once instead of bailing on the first one. The
+    client re-POSTs just the conflicting files with ``overwrite=1`` if the
+    user opts in.
+
+    The DLC directory is resolved via ``_get_dlc_dir()`` which honours the
+    ``DLC_DIR`` env var first and falls back to ``dlc_dir`` in
+    ``config.json`` — so uploads land in whichever folder the rest of the
+    app already considers the library root, regardless of which mechanism
+    configured it.
+    """
+    dlc = _get_dlc_dir()
+    if dlc is None:
+        return JSONResponse(
+            {"error": "DLC folder is not configured. Set DLC_DIR or configure it in Settings."},
+            status_code=503,
+        )
+    if not os.access(str(dlc), os.W_OK):
+        return JSONResponse(
+            {"error": f"DLC folder {dlc} is not writable by the server process."},
+            status_code=500,
+        )
+
+    # Pre-parse Content-Length guard — fail fast before reading any body.
+    # Multipart Content-Length is file bytes + boundary + per-part headers, so
+    # we can't use _MAX_UPLOAD_BYTES as an exact cap here (a file right at the
+    # advertised max would be rejected before _save_uploaded_song() can apply
+    # the real per-file byte cap). For batch uploads we allow up to
+    # _MAX_UPLOAD_FILES files at _MAX_UPLOAD_BYTES each; the parser still
+    # enforces per-part size via max_part_size and per-batch count via
+    # max_files. The streaming check inside _save_uploaded_song() is the
+    # authoritative per-file size cap.
+    max_total = _MAX_UPLOAD_FILES * _MAX_UPLOAD_BYTES + enrichment._MULTIPART_OVERHEAD_SLACK
+    cl = request.headers.get("content-length")
+    if cl is not None:
+        try:
+            cl_int = int(cl)
+        except ValueError:
+            return JSONResponse({"error": "Invalid Content-Length header"}, status_code=400)
+        if cl_int < 0:
+            return JSONResponse({"error": "Invalid Content-Length header"}, status_code=400)
+        if cl_int > max_total:
+            return JSONResponse(
+                {"error": f"Batch upload exceeds {_MAX_UPLOAD_FILES} files × "
+                          f"{_MAX_UPLOAD_BYTES // (1024 * 1024)} MB limit"},
+                status_code=413,
+            )
+
+    overwrite = request.query_params.get("overwrite") == "1"
+    # Tighten the parser to the handler's contract: up to _MAX_UPLOAD_FILES
+    # file parts, no text parts (overwrite comes from query params).
+    # Starlette's defaults of max_files=1000 / max_fields=1000 would
+    # otherwise let a client force the parser to spool far more parts than
+    # the endpoint is willing to process.
+    form = await request.form(
+        max_files=_MAX_UPLOAD_FILES,
+        max_fields=0,
+        max_part_size=_MAX_UPLOAD_BYTES,
+    )
+    try:
+        from starlette.datastructures import UploadFile as _StarletteUploadFile
+        # form.getlist("file") returns all parts named "file" in submission
+        # order. Filter to file parts only — Starlette would yield strings
+        # for text parts, but we've capped max_fields=0 so any non-file part
+        # is already a parser error before reaching here.
+        uploads = [u for u in form.getlist("file") if isinstance(u, _StarletteUploadFile)]
+        if not uploads:
+            return JSONResponse(
+                {"error": "Expected one or more files in multipart field 'file'"},
+                status_code=400,
+            )
+
+        results = []
+        any_saved = False
+        for upload in uploads:
+            try:
+                result = await _save_uploaded_song(upload, dlc, overwrite)
+                results.append(result)
+                if result.get("status") == "ok":
+                    any_saved = True
+            except Exception as e:
+                # Per-file failure must not abort the batch — record and
+                # continue so the client gets a complete report.
+                log.exception("upload failed for %r", getattr(upload, "filename", "?"))
+                results.append({
+                    "filename": Path(getattr(upload, "filename", "") or "").name or "?",
+                    "status": "error",
+                    "error": f"Upload failed: {e}",
+                })
+            finally:
+                try:
+                    await upload.close()
+                except Exception:
+                    log.debug("failed to close upload file handle", exc_info=True)
+
+        if any_saved:
+            appstate.kick_scan()
+        return {"results": results}
+    finally:
+        try:
+            await form.close()
+        except Exception:
+            log.debug("failed to close form", exc_info=True)
+
+
+async def _save_uploaded_song(upload: UploadFile, dlc: Path, overwrite: bool) -> dict:
+    """Save one upload into ``dlc``. Returns a per-file result dict (never
+    a JSONResponse) so batch uploads can aggregate.
+
+    Shape:
+      ok:     ``{"status": "ok", "filename": base, "size": N, "format": "sloppak"}``
+      exists: ``{"status": "exists", "filename": base, "error": "..."}``
+      error:  ``{"status": "error", "filename": base, "error": "..."}``
+    """
+    # Strip any path components a client may have included in the filename —
+    # only the basename lands in the DLC root. Path traversal would otherwise
+    # let a crafted upload escape the library directory.
+    raw_name = upload.filename or ""
+    base = Path(raw_name).name
+    if not base or base in (".", "..") or "/" in base or "\\" in base:
+        return {"status": "error", "filename": raw_name or "?", "error": "Invalid filename"}
+    suffix = Path(base).suffix.lower()
+    if suffix not in _ALLOWED_SONG_EXTS:
+        return {"status": "error", "filename": base,
+                "error": "Only .feedpak files are accepted"}
+
+    dest = dlc / base
+    if dest.exists():
+        if not overwrite:
+            return {"status": "exists", "filename": base,
+                    "error": "A file with this name already exists"}
+        # overwrite=1 must handle directory-form sloppaks (the scanner and
+        # delete path both treat them as song entries). os.replace() can't
+        # clobber a non-empty directory, so without the rmtree below the
+        # whole upload would write to a temp file and then surface a late
+        # 500 at the os.replace() call. Refuse other directories so an
+        # unrelated folder isn't blown away by a same-named upload.
+        if dest.is_dir() and not sloppak_mod.is_sloppak(dest):
+            return {"status": "exists", "filename": base,
+                    "error": "A directory with this name exists and is not a sloppak — "
+                             "refusing to overwrite"}
+
+    # Temp file in the DLC dir itself so os.replace is atomic (same filesystem).
+    # Dot-prefix keeps it out of the rglob("*.sloppak") scan glob.
+    fd, tmp_name = await run_in_threadpool(
+        tempfile.mkstemp, dir=str(dlc), prefix=".upload-", suffix=".part"
+    )
+    tmp_path = Path(tmp_name)
+    bytes_read = 0
+    head = b""
+    error_result: dict | None = None
+    try:
+        try:
+            tmpf = await run_in_threadpool(os.fdopen, fd, "wb")
+        except BaseException:
+            try:
+                await run_in_threadpool(os.close, fd)
+            except OSError:
+                pass
+            raise
+        try:
+            while True:
+                chunk = await upload.read(1024 * 1024)
+                if not chunk:
+                    break
+                bytes_read += len(chunk)
+                if bytes_read > _MAX_UPLOAD_BYTES:
+                    error_result = {
+                        "status": "error", "filename": base,
+                        "error": f"Upload exceeds {_MAX_UPLOAD_BYTES // (1024 * 1024)} MB cap",
+                    }
+                    break
+                if len(head) < 4:
+                    head += chunk[: 4 - len(head)]
+                await run_in_threadpool(tmpf.write, chunk)
+        finally:
+            await run_in_threadpool(tmpf.close)
+
+        if error_result is None:
+            if bytes_read == 0:
+                error_result = {"status": "error", "filename": base,
+                                "error": "Empty upload — file is 0 bytes"}
+            elif suffix in _ALLOWED_SONG_EXTS:
+                if head[:2] != b"PK":
+                    error_result = {"status": "error", "filename": base,
+                                    "error": "Not a valid feedpak file (expected zip archive)"}
+                else:
+                    # ZIP magic alone admits any renamed zip — verify the sloppak
+                    # loader can actually parse a manifest.yaml inside. Without
+                    # this, /api/songs/upload returns "ok" for files the rest of
+                    # the backend would refuse to scan or load.
+                    try:
+                        await run_in_threadpool(sloppak_mod.load_manifest, tmp_path)
+                    except Exception as e:
+                        error_result = {"status": "error", "filename": base,
+                                        "error": f"Not a valid sloppak file: {e}"}
+
+        if error_result is not None:
+            try:
+                await run_in_threadpool(tmp_path.unlink)
+            except OSError:
+                pass
+            return error_result
+
+        # Single sync helper so the lock is held for the whole commit —
+        # ``async with _upload_lock`` would have released between every
+        # ``run_in_threadpool`` and let a concurrent delete or upload slip
+        # in between the dir check and the final ``os.replace``.
+        commit_result = await run_in_threadpool(
+            _commit_uploaded_song, tmp_path, dest, overwrite, base
+        )
+        if commit_result is not None:
+            return commit_result
+    except BaseException:
+        try:
+            await run_in_threadpool(tmp_path.unlink)
+        except OSError:
+            pass
+        raise
+
+    # Even on a fresh (non-overwrite) upload, evict any stale entries left
+    # over from a previous delete+re-upload of the same name.
+    await run_in_threadpool(appstate.invalidate_song_caches, base)
+
+    log.info("Uploaded %s (%d bytes) to %s", base, bytes_read, dlc)
+    return {"status": "ok", "filename": base, "size": bytes_read,
+            "format": suffix.lstrip(".")}
+
+
+@router.delete("/api/song/{filename:path}")
+def delete_song(filename: str):
+    """Remove a song from the DLC folder and clear its cache entries.
+
+    Works for both formats: ``.sloppak`` files OR directories, and
+    loose-folder songs (the directory containing the chart). The path is
+    resolved through ``_resolve_dlc_path`` so URL-encoded ``..`` segments
+    cannot escape the library root.
+    """
+    dlc = _get_dlc_dir()
+    if dlc is None:
+        return JSONResponse({"error": "DLC folder not configured"}, status_code=503)
+    resolved = _resolve_dlc_path(dlc, filename)
+    if resolved is None:
+        return JSONResponse({"error": "forbidden"}, status_code=403)
+    if not resolved.exists():
+        return JSONResponse({"error": "File not found"}, status_code=404)
+    if resolved == dlc.resolve():
+        return JSONResponse({"error": "Refusing to delete the DLC root"}, status_code=400)
+
+    # Only delete actual song entries. Without this, DELETE /api/song/ArtistName
+    # would recursively wipe a whole artist subfolder — far broader than the
+    # UI's per-song contract. Sloppak detection wins over loose because a
+    # sloppak dir can also contain WEM/XML (matches the scanner's precedence).
+    is_sloppak = sloppak_mod.is_sloppak(resolved)
+    is_loose = (
+        resolved.is_dir()
+        and not is_sloppak
+        and loosefolder_mod.is_loose_song(resolved)
+    )
+    if not (is_sloppak or is_loose):
+        return JSONResponse(
+            {"error": "Not a song entry — only sloppaks "
+                      "or loose-folder songs can be deleted"},
+            status_code=400,
+        )
+
+    # Hold ``_song_io_lock`` across the filesystem removal AND the DB/cache
+    # eviction. Without it, an upload of the same filename could ``os.replace``
+    # a new file into place between our removal and DB delete, leaving the
+    # new generation stranded with no library row; or the reverse, where
+    # delete runs between an upload's directory check and its replace and
+    # the upload then resurrects the song we just removed.
+    with _song_io_lock:
+        try:
+            if resolved.is_dir():
+                shutil.rmtree(resolved)
+            else:
+                resolved.unlink()
+        except OSError as e:
+            log.error("Failed to delete %s: %s", resolved, e)
+            return JSONResponse({"error": f"Delete failed: {e}"}, status_code=500)
+
+        # Canonicalise the cache key the same way update_song_meta does so we
+        # hit the row the scanner indexed under.
+        try:
+            cache_key = resolved.relative_to(dlc.resolve()).as_posix()
+        except ValueError:
+            cache_key = filename
+        with appstate.meta_db._lock:
+            appstate.meta_db.conn.execute("DELETE FROM songs WHERE filename = ?", (cache_key,))
+            appstate.meta_db.conn.execute("DELETE FROM favorites WHERE filename = ?", (cache_key,))
+            appstate.meta_db.conn.execute("DELETE FROM loops WHERE filename = ?", (cache_key,))
+            # Purge the v3 filename-keyed state too, so the deleted song stops
+            # surfacing in stats / recent / continue / playlists immediately.
+            appstate.meta_db.conn.execute("DELETE FROM song_stats WHERE filename = ?", (cache_key,))
+            appstate.meta_db.conn.execute("DELETE FROM playlist_songs WHERE filename = ?", (cache_key,))
+            # Personal difficulty / notes / tags for this song (we hold the
+            # lock, so purge is lock-free).
+            appstate.meta_db.purge_song_user_data(cache_key)
+            # Multi-chart grouping (P5a): drop this chart's split + read-model rows,
+            # and any preferred-chart pointer that named it (the work re-auto-picks).
+            # work_key-keyed prefs for OTHER charts survive. Mark the read-model
+            # dirty so the affected work regroups on the next grouped query.
+            appstate.meta_db.conn.execute("DELETE FROM chart_group_split WHERE filename = ?", (cache_key,))
+            appstate.meta_db.conn.execute("DELETE FROM work_display WHERE filename = ?", (cache_key,))
+            appstate.meta_db.conn.execute("DELETE FROM chart_group_pref WHERE preferred_filename = ?", (cache_key,))
+            appstate.meta_db._work_display_dirty = True
+            # Enrichment is never purged on rescan (delete_missing), only here
+            # on the explicit per-song delete — the never-clobber contract.
+            appstate.meta_db.conn.execute("DELETE FROM song_enrichment WHERE filename = ?", (cache_key,))
+            appstate.meta_db.conn.commit()
+
+        # User art overrides go with the song (CAA cache files are keyed by
+        # RELEASE and may be shared with other charts — the LRU owns those).
+        for _p in appstate.art_override_paths(cache_key):
+            try:
+                _p.unlink()
+            except OSError:
+                pass
+
+        appstate.invalidate_song_caches(cache_key)
+
+    log.info("Deleted song %s", cache_key)
+    # If a scan was mid-flight when we removed the row, it may already have
+    # listed (and not yet processed) the file and will call ``appstate.meta_db.put()``
+    # for it after our DB delete — reinserting a ghost row. Coalesce a
+    # follow-up pass via ``appstate.kick_scan`` so the next scan's ``delete_missing()``
+    # purges that entry. Cheap no-op when no scan is running.
+    if appstate.scan_status()["running"]:
+        appstate.kick_scan()
+    return {"ok": True, "filename": cache_key}
+
+
+@router.get("/api/song/{filename:path}/user-meta")
+def get_song_user_meta(filename: str):
+    """Read {user_difficulty, notes, tags} for one song."""
+    return appstate.meta_db.get_song_user_meta(appstate.meta_db._canonical_song_filename(filename))
+
+
+@router.put("/api/song/{filename:path}/user-meta")
+def put_song_user_meta(filename: str, data: dict):
+    """Partial update. Send any of: `user_difficulty` (int 1–5, or null/"" to
+    clear), `notes` (string, or null to clear), `tags` (a full-replace array of
+    strings). Omitted keys are preserved. Returns the merged meta.
+
+    Tag removal is a full-replace `tags` array (send the new set) rather than a
+    granular DELETE sub-route, because `DELETE /api/song/{filename:path}` already
+    owns every DELETE under /api/song and would shadow it."""
+    key = appstate.meta_db._canonical_song_filename(filename)
+    kwargs: dict = {}
+    if "user_difficulty" in data:
+        v = data["user_difficulty"]
+        if v is None or v == "":
+            kwargs["user_difficulty"] = None
+        else:
+            # Reject bools (int subclass) and non-integral floats so 2.5 / true
+            # can't silently truncate into a valid band.
+            if isinstance(v, bool) or (isinstance(v, float) and not v.is_integer()):
+                return JSONResponse({"error": "user_difficulty must be an integer 1–5 or null"}, 400)
+            try:
+                iv = int(v)
+            except (TypeError, ValueError):
+                return JSONResponse({"error": "user_difficulty must be an integer 1–5 or null"}, 400)
+            if not (1 <= iv <= 5):
+                return JSONResponse({"error": "user_difficulty must be 1–5 or null"}, 400)
+            kwargs["user_difficulty"] = iv
+    if "notes" in data:
+        n = data["notes"]
+        if n is None:
+            kwargs["notes"] = None
+        elif isinstance(n, str):
+            kwargs["notes"] = n.strip()[:4000]
+        else:
+            return JSONResponse({"error": "notes must be a string or null"}, 400)
+    tags = data.get("tags", "__absent__")
+    if tags != "__absent__" and not isinstance(tags, list):
+        return JSONResponse({"error": "tags must be an array of strings"}, 400)
+    if not kwargs and tags == "__absent__":
+        return JSONResponse({"error": "No fields to update"}, 400)
+    if kwargs:
+        appstate.meta_db.set_song_user_meta(key, **kwargs)
+    if tags != "__absent__":
+        appstate.meta_db.set_song_tags(key, tags)
+    return appstate.meta_db.get_song_user_meta(key)
+
+
+# Catalog fields the Fix-metadata popup may override/lock — the intersection of
+# "displayable identity" and "safe to correct locally". Guitar/practice facts
+# and personal fields are never overrides.
+_OVERRIDE_FIELDS = frozenset({"title", "artist", "album", "year", "genre"})
+
+
+@router.get("/api/song/{filename:path}/overrides")
+def get_song_overrides(filename: str):
+    """Per-field metadata overrides + locks for one song (Fix-metadata popup):
+    {"overrides": {field: {"value": str|null, "locked": bool}},
+     "pack": {field: str}}. `pack` is the stored value each override sits on top
+    of — the popup's Details tab renders it as the revert-to-pack reference and
+    the Yours/Pack provenance."""
+    key = appstate.meta_db._canonical_song_filename(filename)
+    return {"overrides": appstate.meta_db.get_song_overrides(key),
+            "pack": appstate.meta_db.pack_fields(key)}
+
+
+@router.put("/api/song/{filename:path}/overrides")
+def put_song_overrides(filename: str, data: dict):
+    """Set/clear per-field overrides + locks. Body:
+    `{"overrides": {field: {"value": str|null, "locked": bool}}}`. Only catalog
+    fields (title/artist/album/year/genre) are accepted. A field left with no
+    value and unlocked is removed. Returns the merged override map.
+
+    Clearing rides this PUT (send value:null, locked:false) rather than a DELETE
+    sub-route, because `DELETE /api/song/{filename:path}` already owns every
+    DELETE under /api/song and would shadow it (same reason as tags)."""
+    ov = (data or {}).get("overrides")
+    if not isinstance(ov, dict) or not ov:
+        return JSONResponse({"error": "overrides must be a non-empty object"}, 400)
+    bad = sorted(f for f in ov if f not in _OVERRIDE_FIELDS)
+    if bad:
+        return JSONResponse({"error": "unknown field(s): " + ", ".join(bad)}, 400)
+    key = appstate.meta_db._canonical_song_filename(filename)
+    for field, spec in ov.items():
+        if not isinstance(spec, dict):
+            return JSONResponse({"error": f"'{field}' must be an object with value/locked"}, 400)
+        kwargs: dict = {}
+        if "value" in spec:
+            v = spec["value"]
+            if v is None:
+                kwargs["value"] = None
+            elif isinstance(v, (str, int, float)) and not isinstance(v, bool):
+                kwargs["value"] = str(v).strip()[:500]
+            else:
+                return JSONResponse({"error": f"'{field}' value must be a string or null"}, 400)
+        if "locked" in spec:
+            kwargs["locked"] = bool(spec["locked"])
+        if kwargs:
+            appstate.meta_db.set_song_override(key, field, **kwargs)
+    return {"overrides": appstate.meta_db.get_song_overrides(key)}
+
+
+@router.post("/api/songs/user-meta/batch")
+def batch_song_user_meta(data: dict):
+    """Bulk personal-meta edit over a selection — one request instead of N×2
+    per-song round-trips (the batch bar's apply-to-all). DB-only; never touches
+    files. Body:
+      {"filenames": [...],            # required, non-empty
+       "set_difficulty": 1-5 | null,  # optional: set on all / clear on all
+       "add_tags": [...],             # optional: add to all (never full-replace)
+       "remove_tags": [...]}          # optional: remove from all
+    Omit `set_difficulty` entirely to leave each song's difficulty as-is
+    (mixed-state "leave unchanged"). Returns {"updated": N, "tags": [...]} so the
+    caller can refresh the tag-filter list without a second call."""
+    fns = data.get("filenames")
+    if not isinstance(fns, list) or not fns:
+        return JSONResponse({"error": "filenames must be a non-empty array"}, 400)
+    if not all(isinstance(f, str) and f for f in fns):
+        return JSONResponse({"error": "filenames must be non-empty strings"}, 400)
+
+    kwargs: dict = {}
+    if "set_difficulty" in data:
+        v = data["set_difficulty"]
+        if v is None or v == "":
+            kwargs["set_difficulty"] = None
+        else:
+            if isinstance(v, bool) or (isinstance(v, float) and not v.is_integer()):
+                return JSONResponse({"error": "set_difficulty must be an integer 1–5 or null"}, 400)
+            try:
+                iv = int(v)
+            except (TypeError, ValueError):
+                return JSONResponse({"error": "set_difficulty must be an integer 1–5 or null"}, 400)
+            if not (1 <= iv <= 5):
+                return JSONResponse({"error": "set_difficulty must be 1–5 or null"}, 400)
+            kwargs["set_difficulty"] = iv
+
+    add_tags = data.get("add_tags")
+    remove_tags = data.get("remove_tags")
+    for name, val in (("add_tags", add_tags), ("remove_tags", remove_tags)):
+        if val is not None and not isinstance(val, list):
+            return JSONResponse({"error": f"{name} must be an array of strings"}, 400)
+    if "set_difficulty" not in data and not add_tags and not remove_tags:
+        return JSONResponse({"error": "Nothing to apply"}, 400)
+
+    keys = [appstate.meta_db._canonical_song_filename(f) for f in fns]
+    n = appstate.meta_db.batch_user_meta(keys, add_tags=add_tags, remove_tags=remove_tags, **kwargs)
+    return {"updated": n, "tags": appstate.meta_db.all_tags()}
+
+
+@router.post("/api/song/{filename:path}/meta")
+def update_song_meta(filename: str, data: dict):
+    """Update song metadata, persisting it back into the underlying file.
+
+    The library scanner re-derives title/artist/album/year from the file
+    (archive manifest Attributes / sloppak manifest.yaml) on every full rescan,
+    so a DB-only edit reverts. We write the edit into the file first, then
+    refresh the cache row (including mtime/size) to match. Loose-folder and
+    unwritable songs fall back to a DB-only update (which still survives an
+    incremental rescan via the mtime/size cache hit).
+    """
+    # Canonicalise to the same key get_song_info uses so an update via
+    # one URL form (e.g. with `..` segments) lands on the row that
+    # later reads will see.
+    dlc = _get_dlc_dir()
+    cache_key = filename
+    resolved = None
+    if dlc:
+        resolved = _resolve_dlc_path(dlc, filename)
+        if resolved is None:
+            return JSONResponse({"error": "forbidden"}, 403)
+        try:
+            cache_key = resolved.relative_to(dlc.resolve()).as_posix()
+        except ValueError:
+            pass
+
+    fields = {k: data[k] for k in ("title", "artist", "album", "year") if k in data}
+    if not fields:
+        return {"error": "No fields to update"}
+    # Normalise the year value so the DB and file stay in sync.  The file
+    # writer (songmeta) coerces empty/non-numeric years to 0, which the
+    # scanner reads back as "".  Store "" in the DB instead of a raw
+    # non-numeric string so that if the mtime/size are updated (making the
+    # row cache-fresh) the DB still matches what the scanner would derive.
+    if "year" in fields:
+        try:
+            _yr_int = int(fields["year"])
+        except (TypeError, ValueError):
+            _yr_int = 0
+        fields = {**fields, "year": str(_yr_int) if _yr_int else ""}
+
+    # Persist into the file so the edit survives a full rescan.
+    # Hold _song_io_lock across the existence check and file write so a
+    # concurrent delete cannot remove the file between our check and the
+    # repack's atomic replace, and so a concurrent upload cannot be clobbered
+    # by our atomic rename. archive repack is slow — the lock is held longer
+    # than a simple upload/delete, but correctness requires serialisation.
+    persisted = False
+    with _song_io_lock:
+        if resolved is not None and resolved.exists():
+            try:
+                import songmeta
+                persisted = songmeta.write_song_metadata(resolved, fields)
+            except Exception:
+                log.warning("metadata file write failed for %s", cache_key, exc_info=True)
+
+        with appstate.meta_db._lock:
+            updates = [f"{field} = ?" for field in fields]
+            params = list(fields.values())
+            if persisted:
+                # The file changed — re-stat so an incremental rescan sees a
+                # consistent cache row instead of re-reading the (now matching)
+                # file.
+                try:
+                    mtime, size = appstate.stat_for_cache(resolved)
+                    updates += ["mtime = ?", "size = ?"]
+                    params += [mtime, size]
+                except OSError:
+                    pass
+            params.append(cache_key)
+            appstate.meta_db.conn.execute(
+                f"UPDATE songs SET {', '.join(updates)} WHERE filename = ?", params
+            )
+            appstate.meta_db.conn.commit()
+
+    if persisted:
+        appstate.invalidate_song_caches(cache_key)
+        # Coalesce a follow-up scan so a mid-flight scan's stale appstate.meta_db.put()
+        # for this file can't win: if a scan is running appstate.kick_scan() queues a
+        # pending pass; if not it starts a fresh one. Unconditional to avoid a
+        # race where the scan finishes between our DB commit and a guarded check.
+        appstate.kick_scan()
+    return {"ok": True, "persisted": persisted}
+
+
+# ── Gap-fill: write CONFIRMED missing metadata into the pack (R4a) ────────────
+# The agreed write-back contract (spec-alignment §7): opt-in + user-initiated
+# (nothing here runs in the background), adds ABSENT keys only (never replaces
+# an author-set value — the writer refuses, and existing manifest bytes are
+# preserved verbatim by appending), spec'd-keys allowlist, values only from a
+# CONFIRMED identity (an auto/exact match or a user pin — review-tier rows are
+# not eligible until a human confirms), atomic write + .bak. Single-song only;
+# batch write-back stays an open question with the spec chair.
+_GAP_FILL_KEYS = ("album", "year", "genres", "mbid", "isrc")
+
+
+def _gap_fill_manifest_absent(manifest: dict, key: str) -> bool:
+    """A key is a GAP only when it's genuinely MISSING from the manifest.
+
+    Gap-fill is append-only: the writer's never-clobber guard raises on ANY
+    key already present, and appending a second `album:` line to a manifest
+    that already carries `album: ''` would just create a duplicate YAML key.
+    So a present-but-empty value (None / '' / [] / year 0) is NOT a gap the
+    append-only writer can fill — offering it in the preview would only lead
+    to a POST the writer refuses. Present-but-empty keys are therefore left
+    to the metadata editor (which re-serializes and can replace in place)."""
+    return key not in manifest
+
+
+def _gap_fill_proposals(cache_key: str, resolved) -> tuple[dict, str]:
+    """What gap-fill could add for this song: (proposals, reason). Empty
+    proposals explain themselves via reason — 'not-sloppak', 'no-match'
+    (nothing confirmed yet), 'review' (a human hasn't confirmed the match),
+    or 'nothing-missing'."""
+    if resolved is None or not resolved.exists() or not sloppak_mod.is_sloppak(resolved):
+        return {}, "not-sloppak"
+    row = appstate.meta_db.get_enrichment(cache_key)
+    if not row or row.get("match_state") not in ("matched", "manual"):
+        state = (row or {}).get("match_state")
+        return {}, ("review" if state == "review" else "no-match")
+    try:
+        manifest = sloppak_mod.load_manifest(resolved) or {}
+    except Exception:
+        return {}, "not-sloppak"
+    # A LOCKED field (Fix-metadata popup) is never gap-filled — the user pinned
+    # it away from the matched value, so writing that value to the file would
+    # be exactly the clobber the lock exists to prevent. (The lock field name is
+    # `genre`; the manifest/gap-fill key is `genres`.)
+    locked = appstate.meta_db.locked_fields(cache_key)
+    out = {}
+    album = (row.get("canon_album") or "").strip()
+    if album and "album" not in locked and _gap_fill_manifest_absent(manifest, "album"):
+        out["album"] = album
+    year = (row.get("canon_year") or "").strip()
+    if (year.isdigit() and int(year) and "year" not in locked
+            and _gap_fill_manifest_absent(manifest, "year")):
+        out["year"] = int(year)
+    genres = [str(g) for g in (row.get("genres") or []) if isinstance(g, str) and g.strip()]
+    if genres and "genre" not in locked and _gap_fill_manifest_absent(manifest, "genres"):
+        out["genres"] = genres
+    # Identity keys (feedpak spec 1.14.0) — written in canonical form only.
+    mbid = (row.get("mb_recording_id") or "").strip().lower()
+    if enrichment._MBID_RE.match(mbid) and _gap_fill_manifest_absent(manifest, "mbid"):
+        out["mbid"] = mbid
+    isrc = (row.get("isrc") or "").strip().upper().replace("-", "").replace(" ", "")
+    if enrichment._ISRC_RE.match(isrc) and _gap_fill_manifest_absent(manifest, "isrc"):
+        out["isrc"] = isrc
+    return out, ("" if out else "nothing-missing")
+
+
+@router.get("/api/song/{filename:path}/gap-fill")
+def get_song_gap_fill(filename: str):
+    """Preview what "Write missing info to file" would add — the Details
+    drawer renders its confirm list straight from this. Read-only."""
+    dlc = _get_dlc_dir()
+    cache_key, resolved = filename, None
+    if dlc:
+        resolved = _resolve_dlc_path(dlc, filename)
+        if resolved is None:
+            return JSONResponse({"error": "forbidden"}, 403)
+        try:
+            cache_key = resolved.relative_to(dlc.resolve()).as_posix()
+        except ValueError:
+            pass
+    proposals, reason = _gap_fill_proposals(cache_key, resolved)
+    row = appstate.meta_db.get_enrichment(cache_key) or {}
+    return {
+        "eligible": bool(proposals),
+        "reason": reason,
+        "match_state": row.get("match_state"),
+        "missing": [{"key": k, "value": v} for k, v in proposals.items()],
+    }
+
+
+@router.post("/api/song/{filename:path}/gap-fill")
+def post_song_gap_fill(filename: str, data: dict):
+    """Write the user-confirmed subset of the preview into the pack file.
+    Proposals are recomputed under the io lock, so a key that gained an
+    author value between preview and confirm is skipped, never replaced."""
+    keys = (data or {}).get("keys")
+    if not isinstance(keys, list) or not keys:
+        return JSONResponse({"error": "keys must be a non-empty list"}, 400)
+    bad = [k for k in keys if k not in _GAP_FILL_KEYS]
+    if bad:
+        return JSONResponse(
+            {"error": "unknown key(s): " + ", ".join(sorted(set(map(str, bad))))}, 400)
+
+    dlc = _get_dlc_dir()
+    cache_key, resolved = filename, None
+    if dlc:
+        resolved = _resolve_dlc_path(dlc, filename)
+        if resolved is None:
+            return JSONResponse({"error": "forbidden"}, 403)
+        try:
+            cache_key = resolved.relative_to(dlc.resolve()).as_posix()
+        except ValueError:
+            pass
+
+    with _song_io_lock:
+        proposals, reason = _gap_fill_proposals(cache_key, resolved)
+        additions = {k: proposals[k] for k in _GAP_FILL_KEYS if k in keys and k in proposals}
+        skipped = sorted(set(keys) - set(additions))
+        if not additions:
+            return JSONResponse({"error": "nothing to write", "reason": reason,
+                                 "skipped": skipped}, 409)
+        try:
+            import songmeta
+            songmeta.gap_fill_sloppak(resolved, additions)
+        except Exception:
+            log.warning("gap-fill write failed for %s", cache_key, exc_info=True)
+            return JSONResponse({"error": "write failed"}, 500)
+
+        # Keep the cache row consistent with what the scanner would now derive
+        # (same contract as the metadata editor above): sync the columns the
+        # scan reads from the keys we appended, then re-stat so the row stays
+        # cache-fresh.
+        fields = {}
+        if "album" in additions:
+            fields["album"] = additions["album"]
+        if "year" in additions:
+            fields["year"] = str(additions["year"])
+        if "genres" in additions:
+            fields["genre"] = additions["genres"][0]
+        with appstate.meta_db._lock:
+            updates = [f"{field} = ?" for field in fields]
+            params = list(fields.values())
+            try:
+                mtime, size = appstate.stat_for_cache(resolved)
+                updates += ["mtime = ?", "size = ?"]
+                params += [mtime, size]
+            except OSError:
+                pass
+            if updates:
+                params.append(cache_key)
+                appstate.meta_db.conn.execute(
+                    f"UPDATE songs SET {', '.join(updates)} WHERE filename = ?", params)
+                appstate.meta_db.conn.commit()
+
+    appstate.invalidate_song_caches(cache_key)
+    appstate.kick_scan()
+    return {"ok": True, "written": additions, "skipped": skipped}
+
+
+@router.get("/api/song/{filename:path}")
+async def get_song_info(filename: str):
+    """Return song metadata, from cache or by extracting it from the song source."""
+    import asyncio
+    dlc = _get_dlc_dir()
+    if not dlc:
+        return JSONResponse({"error": "DLC folder not configured"}, 404)
+
+    song_path = _resolve_dlc_path(dlc, filename)
+    if song_path is None:
+        return JSONResponse({"error": "forbidden"}, 403)
+    if not song_path.exists():
+        return JSONResponse({"error": "File not found"}, 404)
+
+    # Canonicalise the cache key against the resolved path so two URL
+    # forms of the same physical file (e.g. `Artist/song.sloppak` vs
+    # `Artist/../Artist/song.sloppak`) converge on a single row instead
+    # of fragmenting / shadowing each other in appstate.meta_db.
+    try:
+        cache_key = song_path.relative_to(dlc.resolve()).as_posix()
+    except ValueError:
+        cache_key = filename
+
+    mtime, size = appstate.stat_for_cache(song_path)
+    cached = appstate.meta_db.get(cache_key, mtime, size)
+    if cached:
+        return cached
+
+    # Extract in thread pool
+    def _extract():
+        meta = _extract_meta_for_file(song_path, dlc)
+        appstate.meta_db.put(cache_key, mtime, size, meta)
+        return meta
+
+    meta = await asyncio.get_event_loop().run_in_executor(None, _extract)
+    return meta

lib/routers/stats.py

@@ -0,0 +1,233 @@
+"""Gameplay scoring — XP award + per-song practice stats (record / recent / best /
+top / per-song). The `/api/stats/{filename:path}` route is registered LAST so its
+catch-all doesn't shadow the fixed /recent /best /top paths.
+
+Extracted verbatim from ``server.py`` (R3); edits: ``@app`` -> ``@router``,
+``meta_db`` -> ``appstate.meta_db``, ``_get_progression_content()`` /
+``_builtin_diagnostic_filename()`` read through the seam.
+"""
+
+import logging
+import math
+
+from fastapi import APIRouter
+from fastapi.responses import JSONResponse
+
+import appstate
+from metadata_db import _as_int
+from reqfields import _clean_str
+
+log = logging.getLogger("feedBack.server")
+
+router = APIRouter()
+
+
+@router.post("/api/xp/award")
+def api_award_xp(data: dict):
+    """Award XP into the unified store. Body: {source, amount}. Returns the
+    new progress payload. The single XP authority — song-play, minigames, and
+    tutorials all feed this (no second curve)."""
+    try:
+        amount = _as_int(data.get("amount", 0))   # rejects bool / non-integral / inf
+    except (TypeError, ValueError, OverflowError):
+        return JSONResponse({"error": "amount must be an integer"}, status_code=400)
+    # Upper-bound it: an unbounded value overflows SQLite's 64-bit INTEGER on
+    # bind (→ 500) and no real run awards anywhere near this.
+    if not (0 <= amount <= 10_000_000):
+        return JSONResponse({"error": "amount must be between 0 and 10,000,000"}, status_code=400)
+    appstate.meta_db.award_xp(amount)
+    return appstate.meta_db.get_progress()
+
+
+@router.post("/api/stats")
+def api_record_stats(data: dict):
+    """Record a play. With `score`+`accuracy` → a scored session (plays += 1,
+    best_* = max, last_* = new) plus unified-XP + streak side-effects. With
+    only `lastPlayPosition`/`last_position` → a lightweight resume-position
+    touch (no plays change) so Continue-Playing works for non-scored plays."""
+    filename = _clean_str(data.get("filename"))
+    if not filename:
+        return JSONResponse({"error": "filename required"}, status_code=400)
+    # The recorder hands us URL-encoded filenames; canonicalize to the library
+    # key so stored rows line up with `songs` (and so the arrangement-count bound
+    # below resolves the real song). See MetadataDB._canonical_song_filename.
+    filename = appstate.meta_db._canonical_song_filename(filename)
+    arr_raw = data.get("arrangement", 0)
+    if arr_raw is None:
+        arrangement = 0
+    else:
+        try:
+            arrangement = _as_int(arr_raw)   # rejects bool / non-integral (1.9) / inf
+        except (TypeError, ValueError, OverflowError):
+            return JSONResponse({"error": "arrangement must be a non-negative integer"}, status_code=400)
+    # Reject (don't silently coerce to 0) so a malformed/out-of-range index
+    # can't corrupt arrangement 0's stats; also keeps it bindable to INTEGER.
+    if not (0 <= arrangement < 2**63):
+        return JSONResponse({"error": "arrangement must be a non-negative integer"}, status_code=400)
+    # Bound against the song's real arrangement count when it's a known library
+    # song, so a bad index can't create fake arrangement buckets that poison the
+    # per-song aggregate / Continue. Skipped when the song isn't in the library
+    # yet (count unknown — dead-song reads are filtered anyway).
+    _acount = appstate.meta_db.arrangement_count(filename)
+    if _acount and arrangement >= _acount:
+        return JSONResponse({"error": "arrangement out of range for this song"}, status_code=400)
+    score = data.get("score")
+    accuracy = data.get("accuracy")
+    last_pos = data.get("lastPlayPosition", data.get("last_position"))
+    if isinstance(last_pos, bool):   # float(False)=0.0 would otherwise store a bogus position
+        return JSONResponse({"error": "lastPlayPosition must be a finite number"}, status_code=400)
+
+    # A scored session needs BOTH score and accuracy. Exactly one provided is
+    # ambiguous — don't silently fall through to the position-only branch.
+    if (score is None) != (accuracy is None):
+        return JSONResponse({"error": "score and accuracy must be provided together"}, status_code=400)
+
+    if score is not None and accuracy is not None:
+        # Reject booleans explicitly — float(True) would otherwise record a play.
+        if isinstance(score, bool) or isinstance(accuracy, bool):
+            return JSONResponse({"error": "score/accuracy must be finite numbers"}, status_code=400)
+        # Reject NaN/Inf too: round(inf) raises OverflowError (→ 500), and a
+        # stored Inf/NaN later breaks JSON serialization of /api/stats reads.
+        try:
+            score = float(score)
+            accuracy = float(accuracy)
+            if not (math.isfinite(score) and math.isfinite(accuracy)):
+                raise ValueError("non-finite")
+            score = int(round(score))
+        except (TypeError, ValueError, OverflowError):
+            return JSONResponse({"error": "score/accuracy must be finite numbers"}, status_code=400)
+        # A huge-but-finite score passes isfinite() yet overflows SQLite's
+        # 64-bit INTEGER on bind (→ 500). Bound it to the int64 range.
+        if not (0 <= score < 2**63):
+            return JSONResponse({"error": "score out of range"}, status_code=400)
+        # accuracy is a 0..1 fraction (the recorder's contract); reject
+        # out-of-range values so they don't surface as >100% / negative in
+        # /api/stats/best and the badge UI.
+        if not (0 <= accuracy <= 1):
+            return JSONResponse({"error": "accuracy must be between 0 and 1"}, status_code=400)
+        # Validate the optional resume position in this branch too (the
+        # position-only branch below already rejects non-finite).
+        if last_pos is not None:
+            try:
+                last_pos = float(last_pos)
+                if not math.isfinite(last_pos):
+                    raise ValueError("non-finite")
+            except (TypeError, ValueError, OverflowError):
+                return JSONResponse({"error": "lastPlayPosition must be a finite number"}, status_code=400)
+        row = appstate.meta_db.record_session(filename, arrangement, score=score,
+                                     accuracy=accuracy, last_position=last_pos)
+        # Unified XP + streak side-effects — never let these drop the stat write.
+        progress = None
+        try:
+            from xp import xp_for_run
+            from datetime import date
+            appstate.meta_db.award_xp(xp_for_run(score))
+            appstate.meta_db.record_active_day(date.today().isoformat())
+            progress = appstate.meta_db.get_progress()
+        except Exception:
+            log.warning("stats side-effects (xp/streak) failed", exc_info=True)
+        # Progression engine (spec 010) — same never-drop-the-stat-write
+        # contract. Scored sessions are the server-derived `song_completed`
+        # authority (scored == note detection by construction); instrument is
+        # resolved from library arrangement metadata, after the XP award so
+        # db_earned goals see this run's Decibels.
+        progression_summary = None
+        try:
+            import progression as progression_mod
+            instrument = progression_mod.instrument_for_arrangement(
+                appstate.meta_db.arrangement_entry(filename, arrangement)
+            )
+            progression_summary = appstate.meta_db.record_progression_event(
+                "song_completed",
+                {
+                    "filename": filename,
+                    "instrument": instrument,
+                    "accuracy": accuracy,
+                    "score": score,
+                    "is_diagnostic": filename == appstate.builtin_diagnostic_filename(),
+                },
+                appstate.get_progression_content(),
+            )
+        except Exception:
+            log.warning("stats side-effects (progression) failed", exc_info=True)
+        return {"stats": row, "progress": progress, "progression": progression_summary}
+
+    # Position-only touch.
+    if last_pos is None:
+        return JSONResponse(
+            {"error": "provide score+accuracy (scored) or lastPlayPosition (resume)"},
+            status_code=400,
+        )
+    try:
+        pos = float(last_pos)
+        if not math.isfinite(pos):
+            raise ValueError("non-finite")
+        row = appstate.meta_db.touch_position(filename, arrangement, pos)
+    except (TypeError, ValueError, OverflowError):
+        return JSONResponse({"error": "lastPlayPosition must be a finite number"}, status_code=400)
+    # A resume session still counts as playing today: advance the streak (no XP —
+    # that's scoring-only) so a non-scored practice day keeps the streak alive,
+    # consistent with these sessions also surfacing in recent / continue.
+    progress = None
+    try:
+        from datetime import date
+        appstate.meta_db.record_active_day(date.today().isoformat())
+        progress = appstate.meta_db.get_progress()
+    except Exception:
+        log.warning("stats side-effects (streak) failed", exc_info=True)
+    return {"stats": row, "progress": progress}
+
+
+@router.get("/api/stats/recent")
+def api_recent_stats(limit: int = 12):
+    """Recently-played rows joined to song metadata for 'Jump back in'."""
+    from urllib.parse import quote
+    out = []
+    for r in appstate.meta_db.recent_stats(limit):
+        meta = appstate.meta_db.conn.execute(
+            "SELECT title, artist, tuning_name FROM songs WHERE filename = ?",
+            (r["filename"],),
+        ).fetchone()
+        title, artist, tuning_name = meta if meta else (None, None, None)
+        out.append({
+            **r,
+            "title": title or r["filename"],
+            "artist": artist or "",
+            "tuning_name": tuning_name or "",
+            "art_url": f"/api/song/{quote(r['filename'])}/art",
+        })
+    return out
+
+
+@router.get("/api/stats/best")
+def api_stats_best():
+    """{filename: best_accuracy} for all songs with a recorded best — one call
+    to badge the library grid (defined before the {filename} catch-all)."""
+    return appstate.meta_db.best_accuracy_map()
+
+
+@router.get("/api/stats/top")
+def api_top_stats(limit: int = 5):
+    """Top scored songs (best first), joined to song metadata, for the profile
+    'Your best scores' panel (defined before the {filename} catch-all)."""
+    from urllib.parse import quote
+    out = []
+    for r in appstate.meta_db.top_stats(limit):
+        meta = appstate.meta_db.conn.execute(
+            "SELECT title, artist, tuning_name FROM songs WHERE filename = ?",
+            (r["filename"],),
+        ).fetchone()
+        title, artist, tuning_name = meta if meta else (None, None, None)
+        out.append({
+            **r,
+            "title": title or r["filename"],
+            "artist": artist or "",
+            "tuning_name": tuning_name or "",
+            "art_url": f"/api/song/{quote(r['filename'])}/art",
+        })
+    return out
+
+
+@router.get("/api/stats/{filename:path}")
+def api_song_stats(filename: str):
+    return appstate.meta_db.get_song_stats(filename)

lib/routers/tunings.py

@@ -0,0 +1,46 @@
+"""The merged tuning catalog (/api/tunings).
+
+Extracted verbatim from server.py (R3) except @app->@router, CONFIG_DIR->
+appstate.config_dir, _load_config imported from lib/appconfig, and the tuning
+registry read through the appstate seam (appstate.tuning_providers — the same
+instance plugins register into via the plugin_context in server.py).
+"""
+
+from fastapi import APIRouter
+
+import appstate
+from appconfig import _load_config
+from tunings import DEFAULT_REFERENCE_PITCH, TUNING_PRESET_MIDIS, freqs_to_midis
+
+router = APIRouter()
+
+
+@router.get("/api/tunings")
+def get_tunings():
+    cfg = _load_config(appstate.config_dir / "config.json") or {}
+    ref = cfg.get("reference_pitch", DEFAULT_REFERENCE_PITCH)
+    try:
+        ref = float(ref)
+        if not (430.0 <= ref <= 450.0):
+            ref = DEFAULT_REFERENCE_PITCH
+    except (TypeError, ValueError):
+        ref = DEFAULT_REFERENCE_PITCH
+    merged = appstate.tuning_providers.get_merged(ref)
+    # tuningMidis: the same catalog as exact integer MIDI notes (low → high).
+    # Built-ins come straight from TUNING_PRESET_MIDIS (no float round-trip);
+    # provider-contributed entries are recovered from their frequencies at the
+    # served reference pitch. Every consumer today (the v3 badges, plugins)
+    # reconstructs midis client-side via log2 — a rounding footgun at non-440
+    # references — so serve the integers once, host-side. Additive: the
+    # existing referencePitch/tunings shape is unchanged.
+    tuning_midis: dict[str, dict[str, list[int]]] = {}
+    for key, names in merged.items():
+        builtin = TUNING_PRESET_MIDIS.get(key, {})
+        resolved: dict[str, list[int]] = {}
+        for name, freqs in names.items():
+            midis = builtin.get(name) or freqs_to_midis(freqs, ref)
+            if midis:
+                resolved[name] = list(midis)
+        if resolved:
+            tuning_midis[key] = resolved
+    return {"referencePitch": ref, "tunings": merged, "tuningMidis": tuning_midis}

lib/routers/version.py

@@ -0,0 +1,81 @@
+"""App version + source/license URLs (/api/version).
+
+Extracted verbatim from ``server.py`` (R3) except the decorator (``@app`` ->
+``@router``) and the VERSION-file lookup: ``Path(__file__).parent`` (app root
+when this lived at the top level) -> ``Path(__file__).resolve().parents[2]``
+(routers -> lib -> app root). VERSION ships at the app root in every packaging
+path (Dockerfile COPY, desktop bundle).
+"""
+
+import os
+from pathlib import Path
+
+from fastapi import APIRouter
+
+router = APIRouter()
+
+
+def _safe_http_url(raw):
+    """Return `raw` stripped + trailing-slash-stripped if it parses as an
+    http(s) URL with a non-empty host; else None.
+
+    Used to validate operator-supplied `APP_SOURCE_URL` / `APP_LICENSE_URL`
+    env vars before they reach `<a href>` in the UI. A bare prefix check
+    like `startswith(("http://","https://"))` accepts malformed inputs
+    such as `"https://"` (no host) or `"https:///foo"` (empty host) that
+    still produce broken hrefs — and, when used as a base for the default
+    `license_url`, garbage like `"https:///blob/main/LICENSE"`.
+    """
+    from urllib.parse import urlsplit
+    if not raw:
+        return None
+    s = raw.strip().rstrip("/")
+    if not s:
+        return None
+    try:
+        parsed = urlsplit(s)
+    except ValueError:
+        return None
+    if parsed.scheme.lower() not in ("http", "https"):
+        return None
+    # `netloc` includes any `user:pass@` and `:port` — strings like
+    # "http://:80/path" have non-empty netloc (":80") but no real
+    # hostname. Validate `hostname` so only URLs with an actual host
+    # are accepted.
+    if not parsed.hostname:
+        return None
+    return s
+
+
+@router.get("/api/version")
+def get_version():
+    env_version = os.environ.get("APP_VERSION", "").strip()
+    if env_version:
+        version = env_version
+    else:
+        version_file = Path(__file__).resolve().parents[2] / "VERSION"  # R3: app root from lib/routers/
+        version = "unknown"
+        if version_file.exists():
+            try:
+                version = version_file.read_text().strip()
+            except (OSError, UnicodeDecodeError):
+                pass
+    default_source_url = "https://github.com/got-feedback/feedBack"
+    # APP_SOURCE_URL / APP_LICENSE_URL flow straight into <a href> in the UI,
+    # so validate with urllib.parse rather than a bare prefix check — a prefix
+    # check accepts malformed values like "https://" (no host) which produce
+    # broken hrefs (and a constructed license_url like "https:///blob/main/LICENSE").
+    # _safe_http_url requires scheme in {http,https} AND a non-empty hostname
+    # (not just netloc — that would still accept port-only authorities like
+    # "http://:80/path"); fall back to the safe default otherwise.
+    source_url = _safe_http_url(os.environ.get("APP_SOURCE_URL")) or default_source_url
+    # APP_LICENSE_URL: explicit override for the LICENSE link. The default
+    # constructed value (source_url + "/blob/main/LICENSE") is GitHub-
+    # specific and assumes the repo's default branch is `main`; non-GitHub
+    # hosts (GitLab, Gitea, self-hosted) need an explicit value.
+    license_url = _safe_http_url(os.environ.get("APP_LICENSE_URL")) or (source_url + "/blob/main/LICENSE")
+    return {
+        "version": version,
+        "source_url": source_url,
+        "license_url": license_url,
+    }

lib/routers/wanted.py

@@ -0,0 +1,45 @@
+"""Wishlist / "wanted" API (feedBack#636) — songs the user wants but doesn't own.
+
+Extracted verbatim from ``server.py`` (R3); edits: ``@app`` -> ``@router``,
+``meta_db`` -> ``appstate.meta_db``, ``_clean_str`` from ``reqfields``.
+"""
+
+from fastapi import APIRouter
+from fastapi.responses import JSONResponse
+
+import appstate
+from reqfields import _clean_str
+
+router = APIRouter()
+
+
+@router.get("/api/wanted")
+def api_list_wanted():
+    """The wishlist — songs the user wants but doesn't own yet (newest first)."""
+    return {"wanted": appstate.meta_db.list_wanted()}
+
+
+@router.post("/api/wanted")
+def api_add_wanted(data: dict):
+    """Add a not-owned song to the wishlist. `artist`/`title` are required (at
+    least one non-empty); `source`/`source_ref`/`note` are optional. Idempotent
+    on identity so producers (find_more ownership-diff, manual add) can re-post."""
+    if not isinstance(data, dict):
+        return JSONResponse({"error": "body must be an object"}, status_code=400)
+    artist = _clean_str(data.get("artist"))
+    title = _clean_str(data.get("title"))
+    if not artist and not title:
+        return JSONResponse({"error": "artist or title required"}, status_code=400)
+    row = appstate.meta_db.add_wanted(
+        artist=artist, title=title,
+        source=_clean_str(data.get("source")) or "manual",
+        source_ref=_clean_str(data.get("source_ref")),
+        note=_clean_str(data.get("note")),
+    )
+    return {"ok": True, "wanted": row}
+
+
+@router.delete("/api/wanted/{wanted_id}")
+def api_remove_wanted(wanted_id: int):
+    """Remove a wishlist entry by id."""
+    return {"ok": appstate.meta_db.remove_wanted(wanted_id)}

lib/scan_worker.py

@@ -3,7 +3,7 @@
 This module is deliberately kept apart from ``server.py`` so that
 ``ProcessPoolExecutor`` workers can import and unpickle ``_scan_one``
 without dragging in ``server.py``'s import-time side effects
-(``configure_logging()``, ``meta_db = MetadataDB()`` opening/migrating
+(``configure_logging()``, ``meta_db = MetadataDB(CONFIG_DIR)`` opening/migrating
 SQLite, and ``register_plugin_api(app)`` registering routes).
 
 The background scan spawns its pool with the ``spawn`` start method (see

lib/tunings.py

@@ -98,6 +98,22 @@ def open_midis_to_freqs(midis: list[int], reference_pitch: float = DEFAULT_REFER
     return [round(midi_to_freq(m, reference_pitch), 2) for m in midis]
 
 
+def freqs_to_midis(freqs: list[float], reference_pitch: float = DEFAULT_REFERENCE_PITCH) -> list[int] | None:
+    """Return absolute open-string MIDI notes for frequencies at the supplied
+    A4 reference — the inverse of open_midis_to_freqs. None if any entry is
+    non-numeric or non-positive (a provider could hand us anything)."""
+    out: list[int] = []
+    for f in freqs:
+        try:
+            f = float(f)
+        except (TypeError, ValueError):
+            return None
+        if f <= 0:
+            return None
+        out.append(int(round(69 + 12 * math.log2(f / reference_pitch))))
+    return out
+
+
 def tuning_offsets_from_midis(instrument_key: str, midis: list[int]) -> list[int] | None:
     """Return semitone offsets from the instrument's standard open strings."""
     standard = STANDARD_OPEN_MIDIS.get(instrument_key)

plugins/drum_highway_3d/plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "drum_highway_3d",
   "name": "3D Drum Highway",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "type": "visualization",
   "bundled": true,
   "script": "screen.js",

plugins/drum_highway_3d/screen.js

@@ -1361,6 +1361,41 @@
         } catch (_) { /* dispatch unavailable — persisted value applies next init */ }
     };
 
+    /* ======================================================================
+     *  Camera Director bridge resolver (pure — exported via createFactory.__test)
+     * ====================================================================== */
+
+    /**
+     * The active splitscreen API, defensive on the global-name rename in flight
+     * (feedBackSplitscreen is canonical; slopsmithSplitscreen is the legacy alias).
+     * @returns {object|null} the splitscreen API, or null when not present
+     */
+    function _ssApi() { return window.feedBackSplitscreen || window.slopsmithSplitscreen || null; }
+
+    /**
+     * Resolve the Camera Director camera for a canvas: this panel's camera under
+     * splitscreen, else the global, else null (Camera Director absent → stock
+     * framing). Throw-safe on panelIndexFor so a misbehaving splitscreen build
+     * can't break framing.
+     * @param {HTMLCanvasElement} canvas this renderer's highway canvas
+     * @param {object|null} ss the splitscreen API (see _ssApi)
+     * @param {object|null} panelsMap window.__h3dCamCtlPanels (per-panel cameras by index)
+     * @param {object|null} globalCam window.__h3dCamCtl (single global camera)
+     * @returns {object|null} the resolved free-camera bridge, or null
+     */
+    function _resolveFreeCam(canvas, ss, panelsMap, globalCam) {
+        if (panelsMap && ss && typeof ss.panelIndexFor === 'function') {
+            try {
+                const i = ss.panelIndexFor(canvas);
+                // Only a non-negative integer indexes the panel map — a non-int /
+                // negative / string index (or a prototype key) must not resolve an
+                // unintended/inherited property; fall through to the global then.
+                if (Number.isInteger(i) && i >= 0 && panelsMap[i]) return panelsMap[i];
+            } catch (e) { /* ignore */ }
+        }
+        return globalCam || null;
+    }
+
     /* ======================================================================
      *  Renderer factory
      * ====================================================================== */
@@ -1414,7 +1449,7 @@
         let _sparkPts = null, _sparkPos = null, _sparkCol = null, _sparkVel = null, _sparkLife = null;
         let _fxLastWall = 0;          // wall clock for FX integration (sparks, pulse decay)
         let _kickPulse = 0;           // kick-hit camera-dip + floor-wash envelope
-        let _camBaseH = 0, _camBaseD = 0;  // positionCamera's unpulsed pose
+        let _camBaseH = null, _camBaseD = null;  // positionCamera's unpulsed pose (null until it first runs; applyCamera's guard depends on this)
         let _gaussTex = null;         // shared soft-falloff texture for flash quads
         let _laneFlashQuads = [];     // pooled additive quad per hand lane (z=0)
         let _kickFlashQuad = null;    // full-width flash quad for the kick bar
@@ -2651,6 +2686,48 @@
             cam.lookAt(0, 0, -AHEAD * TS * 0.45);
         }
 
+        /**
+         * Camera Director bridge for THIS panel — delegates to the pure, unit-
+         * tested _resolveFreeCam / _ssApi (resolver block above the factory).
+         * Reads the live globals: per-panel map __h3dCamCtlPanels → this panel's
+         * camera, else the global __h3dCamCtl, else null (stock framing).
+         * @param {HTMLCanvasElement} canvas this panel's highway canvas
+         * @returns {object|null} the resolved free-camera bridge, or null
+         */
+        function _freeCamFor(canvas) {
+            return _resolveFreeCam(canvas, _ssApi(), window.__h3dCamCtlPanels, window.__h3dCamCtl);
+        }
+
+        // Per-frame camera write: static base pose (positionCamera) + kick-pulse Y
+        // dip, then layer Camera Director free-cam offsets (dolly/height/orbit on
+        // the camera-from-target vector; pan/pitch on the look target). Runs every
+        // frame so a live free-cam drag is smooth; allocation-free; NaN-safe; a
+        // null/disabled bridge reproduces the stock static+pulse pose exactly.
+        function applyCamera() {
+            if (_camBaseH == null) return;               // before first positionCamera()
+            const _dip = (_kickPulse > 0.001) ? (0.8 * K * _kickPulse * fx.hitFx) : 0;
+            let _cx = 0, _cy = _camBaseH - _dip, _cz = _camBaseD;
+            let _lx = 0, _ly = 0, _lz = -AHEAD * TS * 0.45;
+            const _fc = _freeCamFor(highwayCanvas);
+            if (_fc && _fc.enabled) {
+                const _dm = Number.isFinite(_fc.distMul) ? _fc.distMul : 1;
+                const _hm = Number.isFinite(_fc.heightMul) ? _fc.heightMul : 1;
+                const _yaw = Number.isFinite(_fc.yaw) ? _fc.yaw : 0;
+                let _vx = _cx - _lx, _vy = _cy - _ly, _vz = _cz - _lz;
+                _vx *= _dm; _vy *= _dm; _vz *= _dm;   // dolly (zoom)
+                _vy *= _hm;                            // height
+                const _cyw = Math.cos(_yaw), _syw = Math.sin(_yaw);
+                const _rx = _vx * _cyw - _vz * _syw, _rz = _vx * _syw + _vz * _cyw; // orbit around Y
+                _cx = _lx + _rx; _cy = _ly + _vy; _cz = _lz + _rz;
+                const _px = Number.isFinite(_fc.panX) ? _fc.panX : 0;
+                const _py = Number.isFinite(_fc.panY) ? _fc.panY : 0;
+                const _pt = Number.isFinite(_fc.pitch) ? _fc.pitch : 0;
+                _lx += _px * K; _ly += (_pt + _py) * K;
+            }
+            cam.position.set(_cx, _cy, _cz);
+            cam.lookAt(_lx, _ly, _lz);
+        }
+
         function buildLanes(_floorW, floorD) {
             laneGroup = new T.Group();
             laneStripeMats = [];
@@ -3431,15 +3508,18 @@
                             BG_STYLES[_bgState._style].update(_bgState.s, bands, fdt, nowMs / 1000);
                         } catch (_) { /* visual-only */ }
                     }
+                    // Kick pulse decays each frame; it drives the floor flash and,
+                    // via applyCamera(), the camera Y dip.
                     if (_kickPulse > 0.001) {
                         _kickPulse *= Math.exp(-fdt * 7);
-                        cam.position.y = _camBaseH - 0.8 * K * _kickPulse * fx.hitFx;
                         if (_floorFlash) _floorFlash.material.opacity = 0.25 * _kickPulse * fx.hitFx;
                     } else if (_kickPulse !== 0) {
                         _kickPulse = 0;
-                        cam.position.y = _camBaseH;
                         if (_floorFlash) _floorFlash.material.opacity = 0;
                     }
+                    // Write the camera every frame: static base pose + kick dip +
+                    // Camera Director free-cam offsets (per-panel-aware).
+                    applyCamera();
                 }
                 // Approach highlight: raise each lane stripe toward its next
                 // note (accumulated by the rebuildNotes walk above).
@@ -3565,6 +3645,8 @@
     // vm-loaded with no DOM/WebGL; everything here must stay side-effect
     // free to call).
     window.slopsmithViz_drum_highway_3d.__test = {
+        _resolveFreeCam,
+        _ssApi,
         _variantForHit,
         _classifyTiming,
         readFxSettings,

plugins/drum_highway_3d/tests/camera_bridge.test.js

@@ -0,0 +1,78 @@
+// Camera Director bridge resolver tests: per-panel select, global fallback,
+// null-when-absent, throw-safety, and the splitscreen global-name alias. Loads
+// screen.js in a bare vm window and exercises the __test exports (no DOM/WebGL).
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+
+function load() {
+    const window = {
+        console,
+        location: { protocol: 'http:', host: 'localhost' },
+        slopsmith: {},
+    };
+    window.window = window;
+    window.globalThis = window;
+    const context = vm.createContext(window);
+    const src = fs.readFileSync(path.join(__dirname, '..', 'screen.js'), 'utf8');
+    vm.runInContext(src, context, { filename: 'screen.js' });
+    return { window, __test: window.slopsmithViz_drum_highway_3d.__test };
+}
+
+test('_resolveFreeCam: per-panel camera under splitscreen', () => {
+    const { __test } = load();
+    const c0 = {}, c1 = {};
+    const ss = { panelIndexFor: (c) => (c === c0 ? 0 : 1) };
+    const map = { 0: { id: 'p0' }, 1: { id: 'p1' } };
+    assert.equal(__test._resolveFreeCam(c0, ss, map, { id: 'g' }).id, 'p0');
+    assert.equal(__test._resolveFreeCam(c1, ss, map, { id: 'g' }).id, 'p1');
+});
+
+test('_resolveFreeCam: falls back to global when there is no panel map', () => {
+    const { __test } = load();
+    const g = { id: 'global' };
+    assert.equal(__test._resolveFreeCam({}, { panelIndexFor: () => 0 }, null, g), g);
+});
+
+test('_resolveFreeCam: falls back to global when the panel has no map entry', () => {
+    const { __test } = load();
+    const g = { id: 'global' };
+    const ss = { panelIndexFor: () => 3 };            // index 3 absent from map
+    assert.equal(__test._resolveFreeCam({}, ss, { 0: {} }, g), g);
+});
+
+test('_resolveFreeCam: null when Camera Director is absent (no global)', () => {
+    const { __test } = load();
+    assert.equal(__test._resolveFreeCam({}, null, null, null), null);
+    assert.equal(__test._resolveFreeCam({}, { panelIndexFor: () => 0 }, {}, undefined), null);
+});
+
+test('_resolveFreeCam: throw-safe on panelIndexFor → falls back to global', () => {
+    const { __test } = load();
+    const g = { id: 'global' };
+    const ss = { panelIndexFor: () => { throw new Error('boom'); } };
+    assert.equal(__test._resolveFreeCam({}, ss, { 0: {} }, g), g);
+});
+
+test('_resolveFreeCam: NaN/negative/float/string index → falls back to global', () => {
+    const { __test } = load();
+    const g = { id: 'global' };
+    assert.equal(__test._resolveFreeCam({}, { panelIndexFor: () => NaN }, { 0: {} }, g), g);
+    assert.equal(__test._resolveFreeCam({}, { panelIndexFor: () => -1 }, { 0: {} }, g), g);
+    assert.equal(__test._resolveFreeCam({}, { panelIndexFor: () => 0.5 }, { 0: {} }, g), g);
+    // A string/prototype key must not resolve an inherited property (e.g. toString).
+    assert.equal(__test._resolveFreeCam({}, { panelIndexFor: () => 'toString' }, {}, g), g);
+});
+
+test('_ssApi: null when neither global set; slopsmith alias; feedBack canonical wins', () => {
+    const { window, __test } = load();
+    assert.equal(__test._ssApi(), null);
+    const legacy = { panelIndexFor: () => 0 };
+    window.slopsmithSplitscreen = legacy;
+    assert.equal(__test._ssApi(), legacy);            // legacy alias picked up
+    const current = { panelIndexFor: () => 1 };
+    window.feedBackSplitscreen = current;
+    assert.equal(__test._ssApi(), current);           // canonical name takes precedence
+});

plugins/highway_3d/plugin.json

@@ -1,7 +1,7 @@
 {
     "id": "highway_3d",
     "name": "3D Highway",
-    "version": "3.31.3",
+    "version": "3.31.5",
     "type": "visualization",
     "bundled": true,
     "script": "screen.js",

plugins/highway_3d/screen.js

@@ -548,9 +548,20 @@
             ctrl.ownsActx = !(fogAudio && fogAudio.ctx);
             ctrl.actx = (fogAudio && fogAudio.ctx) || new Ctx();
             if (ctrl.actx.state === 'suspended' && ctrl.actx.resume) ctrl.actx.resume().catch(() => {});
+            // Seed the DRAWING BUFFER (canvas.width/height) to the device-pixel
+            // render size and report that SAME size to Butterchurn. Its on-screen
+            // pass viewports to the reported size but never sizes the output canvas
+            // itself — leaving the buffer at the 300x150 default blits the whole
+            // visualizer into a corner that CSS then stretches across the highway.
+            // pixelRatio:1 because DPR is now folded into the reported size, so
+            // buffer == viewport == internal texsize (no double-counting).
+            const _bcRatio0 = Math.min(window.devicePixelRatio || 1, 1.5);
+            const _bcW0 = Math.max(1, Math.round((sz.w || 1280) * _bcRatio0));
+            const _bcH0 = Math.max(1, Math.round((sz.h || 720) * _bcRatio0));
+            canvas.width = _bcW0; canvas.height = _bcH0;
             ctrl.viz = bc.createVisualizer(ctrl.actx, canvas, {
-                width: sz.w || 1280, height: sz.h || 720,
-                pixelRatio: Math.min(window.devicePixelRatio || 1, 1.5), textureRatio: 1,
+                width: _bcW0, height: _bcH0,
+                pixelRatio: 1, textureRatio: 1,
             });
             if (_bcIsDesktop()) {
                 try {
@@ -584,6 +595,27 @@
             ctrl.actx = null; ctrl.viz = null; ctrl.dead = true;
             _bcControllers.delete(ctrl);
         });
+        // Size the Butterchurn output: set the canvas DRAWING BUFFER to the
+        // device-pixel render size AND report that same size, so buffer ==
+        // on-screen viewport == full fill. Butterchurn never sizes the output
+        // canvas itself; the previous code set only CSS size, leaving the buffer
+        // at the 300x150 default -> the viz showed a stretched lower-left corner
+        // (worse the larger the panel). Ratio reuses the highway's DPR budget.
+        function _bcApplySize(cssW, cssH) {
+            if (!(cssW > 0 && cssH > 0)) return;
+            ctrl.lastW = cssW; ctrl.lastH = cssH;
+            const ratio = Math.min(window.devicePixelRatio || 1, 1.5);
+            const bw = Math.max(1, Math.round(cssW * ratio)), bh = Math.max(1, Math.round(cssH * ratio));
+            if (canvas.width !== bw) canvas.width = bw;
+            if (canvas.height !== bh) canvas.height = bh;
+            const wpx = cssW + 'px', hpx = cssH + 'px';
+            // Confine ALL layers to exactly the highway-canvas rect so the opaque
+            // backdrop can't bleed over the transport bar above the highway.
+            [ctrl.canvas, ctrl.backdrop, ctrl.scrim, ctrl.tint].forEach((el) => {
+                if (el) { el.style.width = wpx; el.style.height = hpx; el.style.right = 'auto'; el.style.bottom = 'auto'; }
+            });
+            if (ctrl.viz && ctrl.viz.setRendererSize) { try { ctrl.viz.setRendererSize(bw, bh); } catch (e) {} }
+        }
         return {
             applySettings() { ctrl.applySettings(); },
             dead() { return ctrl.dead; },
@@ -612,18 +644,11 @@
                 if (!ctrl.viz || !s.enabled) return; // skip GPU work when the bg is off
                 const sz = sizeProvider && sizeProvider();
                 if (sz && sz.w > 0 && sz.h > 0 && (sz.w !== ctrl.lastW || sz.h !== ctrl.lastH)) {
-                    ctrl.lastW = sz.w; ctrl.lastH = sz.h;
-                    const wpx = sz.w + 'px', hpx = sz.h + 'px';
-                    // Confine ALL layers to exactly the highway-canvas rect so the opaque
-                    // backdrop can't bleed over the transport bar above the highway.
-                    [ctrl.canvas, ctrl.backdrop, ctrl.scrim, ctrl.tint].forEach((el) => {
-                        if (el) { el.style.width = wpx; el.style.height = hpx; el.style.right = 'auto'; el.style.bottom = 'auto'; }
-                    });
-                    try { ctrl.viz.setRendererSize(sz.w, sz.h); } catch (e) {}
+                    _bcApplySize(sz.w, sz.h);
                 }
                 try { ctrl.viz.render(); } catch (e) {}
             },
-            resize(w, h) { if (ctrl.viz && ctrl.viz.setRendererSize) { try { ctrl.viz.setRendererSize(w, h); } catch (e) {} ctrl.lastW = w; ctrl.lastH = h; } },
+            resize(w, h) { _bcApplySize(w, h); },
             destroy() {
                 ctrl.dead = true;
                 _bcControllers.delete(ctrl);
@@ -2595,10 +2620,51 @@
     }
     const FRET_NUMBER_GHOST_SCOPE_IDS = ['chords', 'all'];
 
+    /**
+     * localStorage panel key for per-panel background settings ('main' or
+     * 'panel<index>'). Defensive on the splitscreen global-name rename in flight,
+     * and throw-safe on panelIndexFor — same as _freeCamFor — so a misbehaving
+     * splitscreen build can't take down background-settings resolution. Only a
+     * non-negative integer index yields a 'panel<N>' key; anything else (null,
+     * NaN, negative, non-integer) falls back to 'main' so a bad index can never
+     * mint a bogus "panelNaN"-style key.
+     * @param {HTMLCanvasElement} canvas this renderer's highway canvas
+     * @returns {string} 'main' or 'panel<index>'
+     */
     function _bgPanelKey(canvas) {
-        const ss = window.feedBackSplitscreen;
-        const idx = (ss && typeof ss.panelIndexFor === 'function') ? ss.panelIndexFor(canvas) : null;
-        return (idx == null) ? 'main' : 'panel' + idx;
+        const ss = window.feedBackSplitscreen || window.slopsmithSplitscreen;
+        let idx = null;
+        if (ss && typeof ss.panelIndexFor === 'function') {
+            try { idx = ss.panelIndexFor(canvas); } catch (e) { idx = null; }
+        }
+        return (Number.isInteger(idx) && idx >= 0) ? 'panel' + idx : 'main';
+    }
+
+    /**
+     * Camera Director bridge resolver. Prefers THIS panel's per-panel camera under
+     * splitscreen (window.__h3dCamCtlPanels[panelIndex]) and falls back to the
+     * single global (window.__h3dCamCtl); returns null when Camera Director is
+     * absent → 100% stock framing. Defensive on the splitscreen global-name rename
+     * in flight (feedBackSplitscreen vs slopsmithSplitscreen); throw-safe on
+     * panelIndexFor. Mirrors the panel resolution in _bgPanelKey.
+     * @param {HTMLCanvasElement} canvas this renderer's highway canvas
+     * @returns {object|null} the resolved free-camera bridge, or null
+     */
+    function _freeCamFor(canvas) {
+        const map = window.__h3dCamCtlPanels;
+        if (map) {
+            const ss = window.feedBackSplitscreen || window.slopsmithSplitscreen;
+            if (ss && typeof ss.panelIndexFor === 'function') {
+                try {
+                    const i = ss.panelIndexFor(canvas);
+                    // Only a non-negative integer indexes the map (same hardening
+                    // as _bgPanelKey) — a non-int / negative / string index must not
+                    // resolve an unintended/inherited property; fall through then.
+                    if (Number.isInteger(i) && i >= 0 && map[i]) return map[i];
+                } catch (e) { /* ignore */ }
+            }
+        }
+        return window.__h3dCamCtl || null;
     }
     // In-memory fallback for when localStorage is blocked (private mode,
     // sandboxed iframes, some test runners). _bgWriteGlobal stages the
@@ -14664,7 +14730,10 @@
             // suppressed while the Camera Director owns the view (it wins).
             const _startAspect = (_tune && Number.isFinite(_tune.startAspect) && _tune.startAspect > 0)
                 ? _tune.startAspect : HORPLUS_START_ASPECT;
-            const _dirActive = !!(window.__h3dCamCtl && window.__h3dCamCtl.enabled);
+            // Resolve the Camera Director bridge once (per-panel under splitscreen,
+            // else global). Used both for the wide-pane gate and the transforms below.
+            const _freeCam = _freeCamFor(highwayCanvas);
+            const _dirActive = !!(_freeCam && _freeCam.enabled);
             const _wide = !!(_tune && _paneAspect > _startAspect) && !_dirActive;
             const _poseHMul = (_wide && Number.isFinite(_tune.heightMul)) ? _tune.heightMul : 1;
             const _poseDMul = (_wide && Number.isFinite(_tune.distMul)) ? _tune.distMul : 1;
@@ -14691,13 +14760,16 @@
             if (_poseHMul !== 1) _camY *= _poseHMul;
             if (_poseDMul !== 1) _camZ *= _poseDMul;
             // ── Free-camera user tweaks (orbit / height / zoom / pan) ──
-            // Driven by the Camera Director plugin via window.__h3dCamCtl.
+            // Driven by the Camera Director plugin via the camera bridge:
+            // window.__h3dCamCtlPanels[panelIndexFor(canvas)] when split (this
+            // panel's own camera), falling back to the global window.__h3dCamCtl.
             // Layered ON TOP of the auto-framing so note tracking still works.
             // The bridge is read once into _freeCam and reused for both the
             // position and the look-at transforms; every field is coerced to a
             // finite number before use so a malformed object can never feed NaN
             // into cam.position / cam.lookAt.
-            const _freeCam = window.__h3dCamCtl;
+            // _freeCam resolved above via _freeCamFor(highwayCanvas): the
+            // per-panel __h3dCamCtlPanels entry, else global __h3dCamCtl, else null.
             const _lookAtZ = -FOCUS_D * 0.35 * _poseLookZMul;
             if (_freeCam && _freeCam.enabled) {
                 const _distMul = Number.isFinite(_freeCam.distMul) ? _freeCam.distMul : 1;

plugins/keys_highway_3d/plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "keys_highway_3d",
   "name": "Keys Highway 3D",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "RS+-style 3D falling-note piano highway fed by the Sloppak Notation Format, with Web MIDI input scoring.",
   "type": "visualization",
   "bundled": true,

plugins/keys_highway_3d/screen.js

@@ -813,20 +813,36 @@
         _writeStore(STORE_KEYS.midiPick, JSON.stringify({ id: id || '', name: name || '', key: key || '' }));
     }
 
-    function _midiAutoConnect(allowFallback) {
-        // Recovery (sources-changed after unplug) passes false: never switch to a
-        // fallback input, because _midiConnect persists the pick and that would
-        // overwrite the user's saved device on a transient multi-device unplug
-        // (the original returns on replug and reconnects then).
-        if (allowFallback === undefined) allowFallback = true;
-        const inputs = _midiSources();
-        if (!inputs.length) return;
-        const saved = _readSavedPick();
-        // Explicit "None" opt-out.
-        if (saved && saved.id === '' && saved.name === '') return;
-        // Prefer the globally-unique logicalSourceKey, then the legacy bare
-        // sourceId, then case-insensitive name (Chrome on Linux regenerates ids
-        // per page load), then first non-loopback.
+    // Pure decision logic (exported via __test): pick which device to
+    // auto-connect to from the current source list, the domain-wide selection
+    // (`globalKey`, from Settings → Input Setup), and this plugin's own legacy
+    // saved pick. Returns null for "connect to nothing" (explicit None opt-out,
+    // or the configured device currently absent during hotplug recovery).
+    //
+    // The domain-wide selection is the SOURCE OF TRUTH (checked first): a device
+    // configured globally must never be overridden by a stale plugin-local pick
+    // or an arbitrary first-device fallback — that override was the bug. The
+    // local pick is retained only as a fallback BELOW the global (and for
+    // name-recovery when the global's logicalSourceKey went stale, e.g. a
+    // browser that regenerates MIDI port ids across reloads). Auto-connect no
+    // longer writes the local pick, so it only ever holds a value an explicit
+    // selection put there (or a stale one from a pre-fix build — the global
+    // still wins over it).
+    function _pickMidiTarget(inputs, saved, globalKey, allowFallback) {
+        if (!inputs.length) return null;
+        const notBlocked = (i) => !!i && !_MIDI_BLOCKLIST_RE.test(i.name || '');
+        // Explicit "None" opt-out (set only via the device-select API).
+        if (saved && saved.id === '' && saved.name === '') return null;
+
+        // 1. Domain-wide selection (Settings → Input Setup) — source of truth.
+        if (globalKey) {
+            const g = inputs.find(i => i.key === globalKey);
+            if (notBlocked(g)) return g;
+        }
+
+        // 2. Legacy plugin-local pick, as a fallback below the global. Prefer the
+        // globally-unique logicalSourceKey, then the legacy bare sourceId, then
+        // case-insensitive name (Chrome on Linux regenerates ids per page load).
         let target = null;
         if (saved && saved.key) target = inputs.find(i => i.key === saved.key) || null;
         if (!target && saved && saved.id) target = inputs.find(i => i.id === saved.id) || null;
@@ -834,23 +850,50 @@
             const n = saved.name.toLowerCase();
             target = inputs.find(i => (i.name || '').toLowerCase() === n) || null;
         }
-        // Never honour a saved pick that's a loopback / "Midi Through" port — it
-        // carries no device input, so a stale pick silently eats every note. The
-        // saved-pick lookups above bypass the block-list; re-apply it here.
-        if (target && _MIDI_BLOCKLIST_RE.test(target.name || '')) target = null;
-        if (!target) {
-            // Skip the substitute ONLY when a saved pick exists but is currently
-            // absent (recovery: preserve it, don't clobber on a transient unplug).
-            // With no saved pick at all, a fallback is the intended first-hotplug
-            // auto-connect — allow it even in recovery.
-            const hasSavedPick = !!(saved && (saved.key || saved.id || saved.name));
-            if (!allowFallback && hasSavedPick) return;
-            target = inputs.find(i => !_MIDI_BLOCKLIST_RE.test(i.name || '')) || inputs[0];
-        }
+        // Never honour a saved pick that resolves to a loopback / "Midi Through"
+        // port — it carries no device input, so it silently eats every note.
+        if (target && !notBlocked(target)) target = null;
+        if (target) return target;
+
+        // 3. Nothing configured resolved to a present device. In recovery
+        // (allowFallback=false) with a configured preference — a global pick or a
+        // saved pick — that's currently absent, preserve it rather than switching
+        // to an arbitrary device on a transient multi-device unplug. With no
+        // preference at all, a first-device grab is the intended first-hotplug
+        // auto-connect, allowed even in recovery.
+        const hasPreference = !!(globalKey || (saved && (saved.key || saved.id || saved.name)));
+        if (!allowFallback && hasPreference) return null;
+        // Connect to nothing rather than a loopback: if every present device is
+        // blocklisted, a first-device grab would attach to a "Midi Through"/IAC
+        // port that carries no input and silently eats every note.
+        return inputs.find(notBlocked) || null;
+    }
+
+    function _midiAutoConnect(allowFallback) {
+        // Recovery (sources-changed after unplug) passes false: never switch to a
+        // fallback input on a transient multi-device unplug (the configured
+        // device returns on replug and reconnects then). Auto-connect is
+        // non-persisting (persist omitted → false): it opens the resolved device
+        // for this session WITHOUT writing the plugin-local pick or the shared
+        // domain selection, so opening this highway can't clobber the user's
+        // globally-configured device.
+        if (allowFallback === undefined) allowFallback = true;
+        const inputs = _midiSources();
+        const saved = _readSavedPick();
+        const mi = _mi();
+        const globalKey = mi && typeof mi.getSelected === 'function' ? mi.getSelected() : null;
+        const target = _pickMidiTarget(inputs, saved, globalKey, allowFallback);
+        if (!target) return;
         _midiConnect(target.id, target.name, target.key);
     }
 
-    async function _midiConnect(id, name, key) {
+    // `persist` gates the two preference writes. Only an EXPLICIT device
+    // selection (the device-select API) persists: it writes the plugin-local
+    // pick AND the shared domain selection (`mi.select`, so the user's choice
+    // becomes the global default). Auto-connect and programmatic opens pass
+    // falsy — they open the resolved device for this session only, never
+    // touching either store, so they can't clobber a globally-configured device.
+    async function _midiConnect(id, name, key, persist) {
         // Capture our generation AFTER _midiDetach()'s own bump, so a later
         // detach (device removal / new connect / opt-out) reliably supersedes us.
         _midiDetach();
@@ -861,7 +904,7 @@
         for (const inst of _instances) {
             if (inst && typeof inst._releaseAllHeld === 'function') inst._releaseAllHeld();
         }
-        _writeSavedPick(id || '', name || '', key || '');
+        if (persist) _writeSavedPick(id || '', name || '', key || '');
         const mi = _mi();
         if ((id || key) && mi) {
             // Prefer the globally-unique logicalSourceKey so two providers that
@@ -874,13 +917,19 @@
                 const lkey = src.key || ('web-midi::' + src.id);
                 _midiInput = { id: src.id, name: src.name, key: lkey };
                 _midiJustConnected = true;
+                // Only an explicit selection writes the shared global default;
+                // open takes the logicalSourceKey directly, so select() is not
+                // needed to open — it exists purely to set the global. Persist it
+                // BEFORE the no-instance early return so a settings-panel pick with
+                // no live renderer still updates the shared default (best-effort:
+                // a select hiccup must not abort the connect).
+                if (persist) { try { await mi.select(lkey); } catch (_) { /* best-effort */ } }
                 // No live renderer to consume OR release a session — don't hold one
                 // open (settings-only ensure-init, or the last instance was torn
-                // down during async discovery). The pick is saved; a later renderer
-                // mount re-runs auto-connect and opens for real, releasing on destroy.
+                // down during async discovery). A later renderer mount re-runs
+                // auto-connect and opens for real, releasing on destroy.
                 if (_instances.size === 0) { _midiNotifyDeviceListChanged(); return; }
                 try {
-                    await mi.select(lkey);
                     const res = await mi.open({ requester: PLUGIN_ID, logicalSourceKey: lkey });
                     // A newer _midiConnect (device switch / None / replug) ran while
                     // we awaited open — discard this stale session so we don't wire a
@@ -1039,10 +1088,11 @@
     window.keysH3dGetMidiInputId = function () { return _midiInput ? _midiInput.id : ''; };
     window.keysH3dSetMidiInput = function (id) {
         // `id` may be a logicalSourceKey (new host calls) or a legacy sourceId.
+        // Explicit user selection → persist (local pick + shared global default).
         const src = id
             ? (_midiSources().find(s => s.key === id) || _midiSources().find(s => s.id === id))
             : null;
-        _midiConnect(src ? src.id : (id || ''), src ? src.name : '', src ? src.key : '');
+        _midiConnect(src ? src.id : (id || ''), src ? src.name : '', src ? src.key : '', true);
         return true;
     };
     window.keysH3dGetMidiChannel = function () { return _cfg.midiChannel; };
@@ -1547,6 +1597,8 @@
 
     function _aiOpen(req) {
         // Opening a MIDI source connects the corresponding Web MIDI input.
+        // Programmatic open (audio-input source.open) — non-persisting: it must
+        // not rewrite the user's saved pick or the shared global default.
         const idx = _aiIndexFor(req && (req.sourceId || req.logicalSourceKey));
         const inputs = _midiSources();   // carries .key (logicalSourceKey), unlike _midiListInputs()
         if (idx == null || idx >= inputs.length) {
@@ -1600,6 +1652,41 @@
         _aiRegisteredCount = 0;
     }
 
+    /* ======================================================================
+     *  Camera Director bridge resolver (pure — exported via createFactory.__test)
+     * ====================================================================== */
+
+    /**
+     * The active splitscreen API, defensive on the global-name rename in flight
+     * (feedBackSplitscreen is canonical; slopsmithSplitscreen is the legacy alias).
+     * @returns {object|null} the splitscreen API, or null when not present
+     */
+    function _ssApi() { return window.feedBackSplitscreen || window.slopsmithSplitscreen || null; }
+
+    /**
+     * Resolve the Camera Director camera for a canvas: this panel's camera under
+     * splitscreen, else the global, else null (Camera Director absent → 100% stock
+     * framing). Throw-safe on panelIndexFor so a misbehaving splitscreen build
+     * can't break framing.
+     * @param {HTMLCanvasElement} canvas this renderer's highway canvas
+     * @param {object|null} ss the splitscreen API (see _ssApi)
+     * @param {object|null} panelsMap window.__h3dCamCtlPanels (per-panel cameras by index)
+     * @param {object|null} globalCam window.__h3dCamCtl (single global camera)
+     * @returns {object|null} the resolved free-camera bridge, or null
+     */
+    function _resolveFreeCam(canvas, ss, panelsMap, globalCam) {
+        if (panelsMap && ss && typeof ss.panelIndexFor === 'function') {
+            try {
+                const i = ss.panelIndexFor(canvas);
+                // Only a non-negative integer indexes the panel map — a non-int /
+                // negative / string index (or a prototype key) must not resolve an
+                // unintended/inherited property; fall through to the global then.
+                if (Number.isInteger(i) && i >= 0 && panelsMap[i]) return panelsMap[i];
+            } catch (e) { /* ignore */ }
+        }
+        return globalCam || null;
+    }
+
     /* ======================================================================
      *  Renderer factory
      * ====================================================================== */
@@ -1849,6 +1936,18 @@
             _rigOut.lookZ = _camPreset.lookZ;
             return _rigOut;
         }
+
+        /**
+         * Camera Director bridge for THIS panel — delegates to the pure, unit-
+         * tested _resolveFreeCam / _ssApi (resolver block above the factory).
+         * Reads the live globals: per-panel map __h3dCamCtlPanels → this panel's
+         * camera, else the global __h3dCamCtl, else null (stock framing).
+         * @param {HTMLCanvasElement} canvas this panel's highway canvas
+         * @returns {object|null} the resolved free-camera bridge, or null
+         */
+        function _freeCamFor(canvas) {
+            return _resolveFreeCam(canvas, _ssApi(), window.__h3dCamCtlPanels, window.__h3dCamCtl);
+        }
         // Per-key approach glow: a key lights in its pitch-class color ONLY while a
         // note is heading for it, ramping up the closer that note gets to the hit-line.
         const KEY_GLOW_AHEAD = 2.0;      // seconds before the hit-line a key starts to light
@@ -3259,7 +3358,33 @@
             }
             _camX += (_camTargetX - _camX) * CAM_PAN_LERP;
             _camZoom += (_camTargetZoom - _camZoom) * CAM_ZOOM_LERP;
-            { const r = _rig(); cam.position.set(_camX, r.y * K * _camZoom, r.z * K * _camZoom); cam.lookAt(_camX, r.lookY * K * _camZoom, r.lookZ * K * _camZoom); }
+            {
+                const r = _rig();
+                let _cx = _camX, _cy = r.y * K * _camZoom, _cz = r.z * K * _camZoom;
+                let _lx = _camX, _ly = r.lookY * K * _camZoom, _lz = r.lookZ * K * _camZoom;
+                // Camera Director free-cam offsets (per-panel-aware), layered on top
+                // of the auto-framing so pan/zoom-follow still works. Dolly/height/
+                // orbit act on the camera-from-target vector; pan/pitch shift the
+                // look target. NaN-safe; null/disabled bridge → stock.
+                const _fc = _freeCamFor(highwayCanvas);
+                if (_fc && _fc.enabled) {
+                    const _dm = Number.isFinite(_fc.distMul) ? _fc.distMul : 1;
+                    const _hm = Number.isFinite(_fc.heightMul) ? _fc.heightMul : 1;
+                    const _yaw = Number.isFinite(_fc.yaw) ? _fc.yaw : 0;
+                    let _vx = _cx - _lx, _vy = _cy - _ly, _vz = _cz - _lz;
+                    _vx *= _dm; _vy *= _dm; _vz *= _dm;   // dolly (zoom)
+                    _vy *= _hm;                            // height
+                    const _cyw = Math.cos(_yaw), _syw = Math.sin(_yaw);
+                    const _rx = _vx * _cyw - _vz * _syw, _rz = _vx * _syw + _vz * _cyw; // orbit around Y
+                    _cx = _lx + _rx; _cy = _ly + _vy; _cz = _lz + _rz;
+                    const _px = Number.isFinite(_fc.panX) ? _fc.panX : 0;
+                    const _py = Number.isFinite(_fc.panY) ? _fc.panY : 0;
+                    const _pt = Number.isFinite(_fc.pitch) ? _fc.pitch : 0;
+                    _lx += _px * K; _ly += (_pt + _py) * K;
+                }
+                cam.position.set(_cx, _cy, _cz);
+                cam.lookAt(_lx, _ly, _lz);
+            }
 
             for (const km of keyMeshes.values()) km.userData.glow = 0;
             for (const { mesh, note, len, label } of noteMeshes) {
@@ -3960,6 +4085,8 @@
     };
     // Pure data-layer + scoring hooks for headless tests.
     window.slopsmithViz_keys_highway_3d.__test = {
+        _resolveFreeCam,
+        _ssApi,
         beatDurSec,
         flattenNotation,
         keyRange,
@@ -3993,6 +4120,7 @@
         FX_DEFAULTS,
         FX_RANGES,
         _classifyTiming,
+        _pickMidiTarget,
     };
 
     // Headless verification hook: lets Playwright drive synthetic note-ons

plugins/keys_highway_3d/tests/camera_bridge.test.js

@@ -0,0 +1,78 @@
+// Camera Director bridge resolver tests: per-panel select, global fallback,
+// null-when-absent, throw-safety, and the splitscreen global-name alias. Loads
+// screen.js in a bare vm window and exercises the __test exports (no DOM/WebGL).
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+
+function load() {
+    const window = {
+        console,
+        location: { protocol: 'http:', host: 'localhost' },
+        slopsmith: {},
+    };
+    window.window = window;
+    window.globalThis = window;
+    const context = vm.createContext(window);
+    const src = fs.readFileSync(path.join(__dirname, '..', 'screen.js'), 'utf8');
+    vm.runInContext(src, context, { filename: 'screen.js' });
+    return { window, __test: window.slopsmithViz_keys_highway_3d.__test };
+}
+
+test('_resolveFreeCam: per-panel camera under splitscreen', () => {
+    const { __test } = load();
+    const c0 = {}, c1 = {};
+    const ss = { panelIndexFor: (c) => (c === c0 ? 0 : 1) };
+    const map = { 0: { id: 'p0' }, 1: { id: 'p1' } };
+    assert.equal(__test._resolveFreeCam(c0, ss, map, { id: 'g' }).id, 'p0');
+    assert.equal(__test._resolveFreeCam(c1, ss, map, { id: 'g' }).id, 'p1');
+});
+
+test('_resolveFreeCam: falls back to global when there is no panel map', () => {
+    const { __test } = load();
+    const g = { id: 'global' };
+    assert.equal(__test._resolveFreeCam({}, { panelIndexFor: () => 0 }, null, g), g);
+});
+
+test('_resolveFreeCam: falls back to global when the panel has no map entry', () => {
+    const { __test } = load();
+    const g = { id: 'global' };
+    const ss = { panelIndexFor: () => 3 };            // index 3 absent from map
+    assert.equal(__test._resolveFreeCam({}, ss, { 0: {} }, g), g);
+});
+
+test('_resolveFreeCam: null when Camera Director is absent (no global)', () => {
+    const { __test } = load();
+    assert.equal(__test._resolveFreeCam({}, null, null, null), null);
+    assert.equal(__test._resolveFreeCam({}, { panelIndexFor: () => 0 }, {}, undefined), null);
+});
+
+test('_resolveFreeCam: throw-safe on panelIndexFor → falls back to global', () => {
+    const { __test } = load();
+    const g = { id: 'global' };
+    const ss = { panelIndexFor: () => { throw new Error('boom'); } };
+    assert.equal(__test._resolveFreeCam({}, ss, { 0: {} }, g), g);
+});
+
+test('_resolveFreeCam: NaN/negative/float/string index → falls back to global', () => {
+    const { __test } = load();
+    const g = { id: 'global' };
+    assert.equal(__test._resolveFreeCam({}, { panelIndexFor: () => NaN }, { 0: {} }, g), g);
+    assert.equal(__test._resolveFreeCam({}, { panelIndexFor: () => -1 }, { 0: {} }, g), g);
+    assert.equal(__test._resolveFreeCam({}, { panelIndexFor: () => 0.5 }, { 0: {} }, g), g);
+    // A string/prototype key must not resolve an inherited property (e.g. toString).
+    assert.equal(__test._resolveFreeCam({}, { panelIndexFor: () => 'toString' }, {}, g), g);
+});
+
+test('_ssApi: null when neither global set; slopsmith alias; feedBack canonical wins', () => {
+    const { window, __test } = load();
+    assert.equal(__test._ssApi(), null);
+    const legacy = { panelIndexFor: () => 0 };
+    window.slopsmithSplitscreen = legacy;
+    assert.equal(__test._ssApi(), legacy);            // legacy alias picked up
+    const current = { panelIndexFor: () => 1 };
+    window.feedBackSplitscreen = current;
+    assert.equal(__test._ssApi(), current);           // canonical name takes precedence
+});

plugins/keys_highway_3d/tests/data_layer.test.js

@@ -188,3 +188,99 @@ test('measureMarkers extracts idx/t pairs', () => {
         [{ idx: 1, t: 0 }, { idx: 2, t: 2.5 }],
     );
 });
+
+test('_pickMidiTarget: no plugin-local pick defers to the domain-wide selection, not "first device"', () => {
+    const { _pickMidiTarget } = load();
+    const inputs = [
+        { id: 'a', name: 'Device A', key: 'web-midi::a' },
+        { id: 'b', name: 'Device B', key: 'web-midi::b' },
+    ];
+    // Fresh install / never picked here — must use the Input Setup global,
+    // NOT fall through to inputs[0].
+    const target = _pickMidiTarget(inputs, null, 'web-midi::b', true);
+    assert.equal(target.id, 'b');
+});
+
+test('_pickMidiTarget: the domain-wide selection is the source of truth — it wins over a stale plugin-local pick', () => {
+    const { _pickMidiTarget } = load();
+    const inputs = [
+        { id: 'a', name: 'Device A', key: 'web-midi::a' },
+        { id: 'b', name: 'Device B', key: 'web-midi::b' },
+    ];
+    // A stale local pick (e.g. left by a pre-fix build's auto-connect) must
+    // NOT override the device the user configured in Settings → Input Setup.
+    const target = _pickMidiTarget(inputs, { id: 'a', name: 'Device A', key: 'web-midi::a' }, 'web-midi::b', true);
+    assert.equal(target.id, 'b');
+});
+
+test('_pickMidiTarget: local pick is used as a fallback when no global is configured', () => {
+    const { _pickMidiTarget } = load();
+    const inputs = [
+        { id: 'a', name: 'Device A', key: 'web-midi::a' },
+        { id: 'b', name: 'Device B', key: 'web-midi::b' },
+    ];
+    const target = _pickMidiTarget(inputs, { id: 'a', name: 'Device A', key: 'web-midi::a' }, null, true);
+    assert.equal(target.id, 'a');
+});
+
+test('_pickMidiTarget: local pick name-recovers when its logicalSourceKey went stale (id regeneration)', () => {
+    const { _pickMidiTarget } = load();
+    // Same physical device, new id/key across a reload; the saved key/id miss
+    // but the name still matches.
+    const inputs = [{ id: 'a2', name: 'Device A', key: 'web-midi::a2' }];
+    const target = _pickMidiTarget(inputs, { id: 'a1', name: 'Device A', key: 'web-midi::a1' }, null, true);
+    assert.equal(target.id, 'a2');
+});
+
+test('_pickMidiTarget: domain-wide selection is ignored if it names a blocklisted loopback port', () => {
+    const { _pickMidiTarget } = load();
+    const inputs = [
+        { id: 'thru', name: 'IAC Driver Bus 1', key: 'web-midi::thru' },
+        { id: 'b', name: 'Device B', key: 'web-midi::b' },
+    ];
+    const target = _pickMidiTarget(inputs, null, 'web-midi::thru', true);
+    assert.equal(target.id, 'b'); // falls through to the first non-loopback device
+});
+
+test('_pickMidiTarget: when every present device is a loopback, connect to nothing (never a dead port)', () => {
+    const { _pickMidiTarget } = load();
+    const inputs = [
+        { id: 'thru', name: 'MIDI Through Port-0', key: 'web-midi::thru' },
+        { id: 'iac', name: 'IAC Driver Bus 1', key: 'web-midi::iac' },
+    ];
+    // No non-loopback device exists — must NOT fall back to inputs[0] (a port
+    // that carries no input and would silently eat every note).
+    const target = _pickMidiTarget(inputs, null, null, true);
+    assert.equal(target, null);
+});
+
+test('_pickMidiTarget: explicit "None" opt-out still wins over any global default', () => {
+    const { _pickMidiTarget } = load();
+    const inputs = [{ id: 'a', name: 'Device A', key: 'web-midi::a' }];
+    const target = _pickMidiTarget(inputs, { id: '', name: '' }, 'web-midi::a', true);
+    assert.equal(target, null);
+});
+
+test('_pickMidiTarget: a present global wins even during hotplug recovery', () => {
+    const { _pickMidiTarget } = load();
+    const inputs = [{ id: 'b', name: 'Device B', key: 'web-midi::b' }];
+    // The configured global device is present — reconnect to it, don't bail.
+    const target = _pickMidiTarget(inputs, null, 'web-midi::b', false);
+    assert.equal(target.id, 'b');
+});
+
+test('_pickMidiTarget: recovery (allowFallback=false) preserves an absent configured device instead of grabbing a random one', () => {
+    const { _pickMidiTarget } = load();
+    const inputs = [{ id: 'b', name: 'Device B', key: 'web-midi::b' }];
+    // The configured device ('x', global) is currently unplugged; a transient
+    // recovery must NOT switch to the unrelated device that is present.
+    const target = _pickMidiTarget(inputs, null, 'web-midi::x', false);
+    assert.equal(target, null);
+});
+
+test('_pickMidiTarget: recovery with no preference at all still allows a first-hotplug grab', () => {
+    const { _pickMidiTarget } = load();
+    const inputs = [{ id: 'b', name: 'Device B', key: 'web-midi::b' }];
+    const target = _pickMidiTarget(inputs, null, null, false);
+    assert.equal(target.id, 'b');
+});

scripts/perf-baseline.mjs

@@ -6,6 +6,16 @@
 //
 // Usage:
 //   node scripts/perf-baseline.mjs --base http://127.0.0.1:8000 [--n 60] [--soak 30]
+//   node scripts/perf-baseline.mjs --base http://127.0.0.1:8300 --song "Arcturus ….feedpak"
+//
+// With --song, it additionally measures the 2D highway's PER-FRAME DRAW cost:
+// it wraps requestAnimationFrame before any page script runs, tags the frames
+// in which the highway actually painted (via highway.addDrawHook), starts
+// playback, and reports draw-frame p50/p95/p99 over --frames seconds. Tagging
+// matters — roughly half the rAF callbacks belong to other cheap loops, and
+// averaging them in hides a renderer regression behind ~0.1 ms no-op frames.
+// This is the metric that gates the highway.js split (R3c); run it before AND
+// after each highway change on the same machine.
 //
 // Maintainer/CI-only dev tooling (uses the committed @playwright/test browser);
 // never part of the serve or Docker path. Metrics that need a seeded library
@@ -21,6 +31,9 @@ for (let i = 2; i < process.argv.length; i += 2) args.set(process.argv[i].replac
 const BASE = args.get('base') || 'http://127.0.0.1:8000';
 const N = parseInt(args.get('n') || '60', 10);
 const SOAK_S = parseInt(args.get('soak') || '30', 10);
+const SONG = args.get('song') || null;
+const FRAME_S = parseInt(args.get('frames') || '10', 10);
+const RUNS = parseInt(args.get('runs') || '3', 10);   // repeat frame sampling to show spread
 
 const pct = (xs, p) => {
     if (!xs.length) return null;
@@ -69,6 +82,64 @@ async function clientMetrics() {
     return { bootMs, memStartMB: mem0 && mem0 / 1048576, memSoakMB: mem1 && mem1 / 1048576, scripts };
 }
 
+// ── 2D highway per-frame draw cost (needs --song + a seeded library) ──────────
+async function frameTimeOnce(browser) {
+    const page = await browser.newPage();
+    let f, t2, notes;
+    try {
+        // Wrap rAF before any page script; mark frames the highway actually drew.
+        await page.addInitScript(() => {
+            window.__f = [];
+            window.__drew = false;
+            const raf = window.requestAnimationFrame.bind(window);
+            window.requestAnimationFrame = (cb) => raf((t) => {
+                window.__drew = false;
+                const t0 = performance.now();
+                try { cb(t); } finally { window.__f.push({ ms: performance.now() - t0, drew: window.__drew }); }
+            });
+        });
+        await page.goto(BASE, { waitUntil: 'networkidle', timeout: 60000 });
+        await page.evaluate(() => document.getElementById('v3-onboarding')?.remove());
+        await page.evaluate((s) => window.playSong(s), SONG);
+        await page.waitForFunction(() => (window.highway?.getNotes?.() || []).length >= 0 && window.highway?.getSongInfo?.(),
+            null, { timeout: 45000 }).catch(() => {});
+        await page.waitForFunction(() => (window.highway?.getNotes?.() || []).length > 0, null, { timeout: 45000 });
+        await page.evaluate(() => window.highway.addDrawHook(() => { window.__drew = true; }));
+        // Start playback so draw() leaves its paused-throttle path; confirm the clock advances.
+        await page.evaluate(async () => { const a = window.highway.getAudioElement?.(); if (a) a.muted = true; await a?.play?.(); });
+        await page.waitForTimeout(1500);
+        const t1 = await page.evaluate(() => window.highway.getTime());
+        await page.evaluate(() => { window.__f.length = 0; });
+        await page.waitForTimeout(FRAME_S * 1000);
+        ({ f, t2, notes } = await page.evaluate(() => ({
+            f: window.__f.slice(), t2: window.highway.getTime(), notes: window.highway.getNotes().length,
+        })));
+        if (!(t2 > t1 + 1)) throw new Error(`clock did not advance (${t1}→${t2}) — measured the paused path`);
+    } finally {
+        // Always close, even when an await above throws — otherwise a failing
+        // run leaks its page until the final browser.close().
+        await page.close();
+    }
+    const drew = f.filter((x) => x.drew).map((x) => x.ms);
+    return { drew, total: f.length, notes };
+}
+
+async function frameTime() {
+    const browser = await chromium.launch({ args: ['--autoplay-policy=no-user-gesture-required'] });
+    const rows = [];
+    for (let i = 0; i < RUNS; i++) {
+        try {
+            const r = await frameTimeOnce(browser);
+            rows.push({
+                p50: pct(r.drew, 50), p95: pct(r.drew, 95), p99: pct(r.drew, 99),
+                max: Math.max(...r.drew), n: r.drew.length, total: r.total, notes: r.notes,
+            });
+        } catch (e) { rows.push({ error: String(e.message || e) }); }
+    }
+    await browser.close();
+    return rows;
+}
+
 const server = await serverLatency([
     '/api/version',
     '/api/plugins',
@@ -86,9 +157,21 @@ out += `| Cold boot → networkidle | ${client.bootMs} ms |\n`;
 out += `| JS heap after load | ${client.memStartMB ? client.memStartMB.toFixed(1) + ' MB' : '—'} |\n`;
 out += `| JS heap after ${SOAK_S}s idle soak | ${client.memSoakMB ? client.memSoakMB.toFixed(1) + ' MB' : '—'} |\n`;
 out += `| Plugin scripts injected | ${client.scripts} |\n`;
-out += `\n> **Requires a seeded library** (not captured by this run): playback frame-time p95\n`;
-out += `> on the 2D + 3D highway, and screen-entry (plugin inject → interactive) for\n`;
-out += `> editor / notedetect / highway_3d with a real chart loaded. Run this harness\n`;
-out += `> against an environment with charts in \`DLC_DIR\` to fill those in.\n`;
+if (SONG) {
+    const frames = await frameTime();
+    out += `\n### 2D highway per-frame draw cost — \`${SONG}\` (${RUNS} runs × ${FRAME_S}s)\n\n`;
+    out += `| run | draw frames | p50 | p95 | p99 | max |\n|---|---|---|---|---|---|\n`;
+    for (let i = 0; i < frames.length; i++) {
+        const r = frames[i];
+        if (r.error) { out += `| ${i + 1} | — | \`${r.error}\` | | | |\n`; continue; }
+        out += `| ${i + 1} | ${r.n}/${r.total} | ${ms(r.p50)} | ${ms(r.p95)} | ${ms(r.p99)} | ${ms(r.max)} |\n`;
+    }
+    const p95s = frames.filter((r) => !r.error).map((r) => r.p95);
+    if (p95s.length) out += `\n**p95 spread across runs: ${ms(Math.min(...p95s))}–${ms(Math.max(...p95s))} ms**\n`;
+} else {
+    out += `\n> **Requires a seeded library** (not captured by this run): playback frame-time p95\n`;
+    out += `> on the 2D highway — pass \`--song "<filename in DLC_DIR>"\` to capture it.\n`;
+    out += `> (3D highway_3d + screen-entry timings are a separate R4 concern.)\n`;
+}
 
 console.log(out);

static/app.js

@@ -4864,6 +4864,65 @@ window.jucePlayer = jucePlayer;
     // (a network blip on /api/audio-local-path, an isAudioRunning() race
     // during a device restart) are deliberately NOT memoised so they retry.
     let _rerouteRejectedUrl = null;
+    // Exclusive-style output backends silence every other client on the
+    // endpoint — including our own <audio> element. The share mode IS the
+    // JUCE output device type: "Windows Audio (Exclusive Mode)" is a
+    // hardcoded, unlocalised JUCE type name; ASIO drivers typically hold
+    // the endpoint exclusively too. "Windows Audio (Low Latency Mode)" is
+    // shared and must NOT match.
+    function _isExclusiveOutputType(t) {
+        return t === 'Windows Audio (Exclusive Mode)' || t === 'ASIO';
+    }
+    // [feedpak-route] diagnostics: log the raw outputType string once per
+    // value change (this runs on a 350ms poll — logging every tick would
+    // flood the diagnostics buffer).
+    let _loggedOutputType;
+    // [asio-diag] verbose diagnostics, gated on --debug (preload exposes
+    // audio.debugEnabled). Resolved once at install; until it resolves the
+    // flag stays false and verbose lines are skipped. Shared with the
+    // renderer-bus feeder below via window._asioDiagEnabled.
+    let _asioDiag = false;
+    if (typeof juceApi.debugEnabled === 'function') {
+        juceApi.debugEnabled().then((v) => { _asioDiag = !!v; }).catch(() => {});
+    }
+    window._asioDiagEnabled = () => _asioDiag;
+    async function _outputIsExclusive() {
+        if (typeof juceApi.getCurrentDevice !== 'function') {
+            if (_loggedOutputType !== '<no-getCurrentDevice>') {
+                _loggedOutputType = '<no-getCurrentDevice>';
+                console.warn('[feedpak-route] juceApi.getCurrentDevice missing — cannot detect exclusive output');
+            }
+            return false;
+        }
+        try {
+            const dev = await juceApi.getCurrentDevice();
+            const t = dev?.outputType || dev?.type || '';
+            const excl = _isExclusiveOutputType(t);
+            if (t !== _loggedOutputType) {
+                _loggedOutputType = t;
+                console.log('[feedpak-route] outputType=', JSON.stringify(t), '→ exclusive=', excl);
+                // [asio-diag] full device object on every type change — shows
+                // the exact strings the predicate saw (inputType vs outputType,
+                // device names, duplex), so a driver reporting a non-'ASIO'
+                // type name is visible in tester logs.
+                if (_asioDiag) {
+                    try {
+                        console.log('[asio-diag] getCurrentDevice=', JSON.stringify(dev));
+                    } catch (_) { /* circular/hostile object — skip */ }
+                }
+            }
+            return excl;
+        } catch (e) {
+            if (_loggedOutputType !== '<getCurrentDevice-failed>') {
+                _loggedOutputType = '<getCurrentDevice-failed>';
+                console.warn('[feedpak-route] getCurrentDevice failed:', e);
+            }
+            return false;
+        }
+    }
+    // highway.js's initial song-load routing consults this for the same
+    // feedpak-under-exclusive decision the watcher makes below.
+    window._juceOutputIsExclusive = _outputIsExclusive;
     // Returns true when window._currentSongAudio no longer references the exact
     // snapshot object captured at reroute entry — i.e. the song was swapped (or
     // cleared) mid-flight. Staleness is detected by object-reference identity,
@@ -4904,8 +4963,12 @@ window.jucePlayer = jucePlayer;
         audio.pause();
         try {
             const res = await fetch(`/api/audio-local-path?url=${encodeURIComponent(url)}`);
-            if (!res.ok) throw new Error('HTTP ' + res.status);
+            if (!res.ok) {
+                console.warn('[feedpak-route] audio-local-path HTTP', res.status, 'for', url);
+                throw new Error('HTTP ' + res.status);
+            }
             const { path } = await res.json();
+            console.log('[feedpak-route] audio-local-path resolved:', (typeof path === 'string' && path.split(/[\\/]/).pop()) || '<missing>');
             if (_isStale(songAudio)) return 'stale';   // song changed mid-fetch
             const ok = await juceApi.loadBackingTrack(path);
             if (ok === false) {
@@ -5123,8 +5186,12 @@ window.jucePlayer = jucePlayer;
     async function _reevaluateJuceRouting() {
         if (_rerouteInFlight) return;
         const songAudio = window._currentSongAudio;
-        // Only /audio/ songs are JUCE-routable; sloppak stems stay on HTML5.
-        if (!songAudio || !songAudio.juceEligible) return;
+        // /audio/ songs are always JUCE-routable. A feedpak full-mix
+        // (single-mix pack, no stems) is routable ONLY under an
+        // exclusive-style output — in shared mode it must stay on HTML5 so
+        // the stem mixer / WebAudio path keeps working. Sloppak stem URLs
+        // are never routable (per-stem mix can't ride a single transport).
+        if (!songAudio || (!songAudio.juceEligible && !songAudio.feedpakFullMix)) return;
         // Don't race highway.js's own initial song-load routing: it owns
         // _juceMode until _juceRoutingPromise settles. Re-running our switch
         // concurrently would double-call loadBackingTrack for the same URL.
@@ -5142,13 +5209,30 @@ window.jucePlayer = jucePlayer;
             try { running = await juceApi.isAudioRunning(); }
             catch (_) { return; }
             if (_isStale(songAudio)) return;               // song changed during IPC
-            if (!!running === !!window._juceMode) return;  // routing already consistent
-
-            const wantJuce = running && !window._juceMode;
+            // Eligibility is evaluated per tick, not snapshotted at song load:
+            // the output share mode can change mid-song (device switch in the
+            // Audio Engine panel), and a feedpak full-mix must follow it —
+            // exclusive → ride the engine; back to shared → return to HTML5.
+            let eligible = !!songAudio.juceEligible;
+            if (!eligible && songAudio.feedpakFullMix && running) {
+                eligible = await _outputIsExclusive();
+                if (_isStale(songAudio)) return;           // song changed during IPC
+            }
+            const wantJuce = !!(running && eligible);
+            // [feedpak-route] diagnostics: one line per decision change (the
+            // watcher polls at 350ms; steady state must not spam the buffer).
+            const _decision = 'running=' + running + ' eligible=' + eligible
+                + ' feedpakFullMix=' + !!songAudio.feedpakFullMix
+                + ' juceMode=' + !!window._juceMode + ' url=' + songAudio.url;
+            if (_decision !== window._lastFeedpakRouteDecision) {
+                window._lastFeedpakRouteDecision = _decision;
+                console.log('[feedpak-route] watcher:', _decision);
+            }
+            if (wantJuce === !!window._juceMode) return;   // routing already consistent
             // Don't keep retrying a track JUCE explicitly rejected.
             if (wantJuce && songAudio.url === _rerouteRejectedUrl) return;
 
-            if (running) {
+            if (wantJuce) {
                 const outcome = await _switchHtml5ToJuce(songAudio);
                 // Memoise ONLY an explicit hard JUCE reject. A successful
                 // switch clears the memo; a 'stale' abort (song changed
@@ -5163,9 +5247,10 @@ window.jucePlayer = jucePlayer;
                 // outcome === 'stale': leave _rerouteRejectedUrl as-is.
             } else {
                 await _switchJuceToHtml5(songAudio);
-                // The engine just stopped. Clear any hard-reject memo so a
-                // later engine restart re-evaluates the track at least once —
-                // the rejection may have been a transient device/decoder state.
+                // The engine stopped (or a feedpak's output left exclusive
+                // mode). Clear any hard-reject memo so a later engine restart
+                // or mode change re-evaluates the track at least once — the
+                // rejection may have been a transient device/decoder state.
                 _rerouteRejectedUrl = null;
             }
         } catch (e) {
@@ -5197,6 +5282,234 @@ window.jucePlayer = jucePlayer;
     }, 350);
 })();
 
+// Renderer-audio bus feeder (desktop Phase 2): when the engine holds the
+// output endpoint in an exclusive-style mode, Chromium cannot reach the
+// device, so any song audio still played by the renderer goes silent. The
+// Phase 1 watcher above already migrates what a single-file transport can
+// carry (loose /audio/ songs, feedpak full-mixes) onto the native backing
+// transport. This feeder covers the rest — the stems plugin's multi-stem
+// WebAudio graph, plus <audio>-element songs the native transport could not
+// take (e.g. a codec loadBackingTrack rejected).
+//
+// Mechanism: capture the renderer-side master with an AudioWorklet tap,
+// re-point the owning AudioContext at a null sink so it keeps rendering
+// without a device, and push ~10 ms chunks over IPC into the engine's
+// renderer bus, where they are mixed into the exclusive output like a
+// backing track (~10-20 ms added latency on song audio only; the guitar
+// monitoring path is untouched). Validated by the fix12 tester spike:
+// null-sink rendering works, clocks hold (drift → 0), no overflow.
+//
+// Docker sphere: window.feedBackDesktop is undefined → this whole block is
+// inert. Shared-mode desktop: the bus stays disabled (no double audio) and
+// captured contexts keep/regain their default sink.
+(function _installRendererBusFeeder() {
+    const api = window.feedBackDesktop?.audio;
+    if (!api || typeof api.setRendererBus !== 'function'
+             || typeof api.pushRendererAudio !== 'function') return;
+
+    const TAP_WORKLET = `
+        class FeedbackBusTap extends AudioWorkletProcessor {
+            process(inputs) {
+                const inp = inputs[0];
+                if (inp && inp[0]) {
+                    const L = inp[0], R = inp[1] || inp[0];
+                    const out = new Float32Array(L.length * 2);
+                    for (let i = 0; i < L.length; i++) { out[i*2] = L[i]; out[i*2+1] = R[i]; }
+                    this.port.postMessage(out, [out.buffer]);
+                }
+                return true;
+            }
+        }
+        registerProcessor('feedback-bus-tap', FeedbackBusTap);
+    `;
+    const _tapModuleUrl = URL.createObjectURL(new Blob([TAP_WORKLET], { type: 'application/javascript' }));
+    const _tapModuleLoaded = new WeakSet();   // AudioContexts with the module added
+
+    // One tap per captured graph. `active` gates the push (the worklet keeps
+    // running when inactive — it's silent bookkeeping, not audio).
+    function _makeTap(ctx) {
+        const state = { node: null, active: false, batch: [], batchFrames: 0 };
+        state.attach = async (sourceNode) => {
+            if (!_tapModuleLoaded.has(ctx)) {
+                await ctx.audioWorklet.addModule(_tapModuleUrl);
+                _tapModuleLoaded.add(ctx);
+            }
+            if (!state.node) {
+                state.node = new AudioWorkletNode(ctx, 'feedback-bus-tap', { numberOfInputs: 1, channelCount: 2 });
+                const BATCH = Math.round(ctx.sampleRate / 100);   // ~10 ms
+                state.node.port.onmessage = (e) => {
+                    if (!state.active) { state.batch = []; state.batchFrames = 0; return; }
+                    state.batch.push(e.data);
+                    state.batchFrames += e.data.length / 2;
+                    if (state.batchFrames >= BATCH) {
+                        const merged = new Float32Array(state.batchFrames * 2);
+                        let o = 0;
+                        for (const c of state.batch) { merged.set(c, o); o += c.length; }
+                        api.pushRendererAudio(merged, ctx.sampleRate);
+                        state.batch = []; state.batchFrames = 0;
+                    }
+                };
+            }
+            sourceNode.connect(state.node);
+            // No onward connection: the tap is a sink-side observer; audibility
+            // in shared mode comes from the graph's own destination path.
+        };
+        state.detach = (sourceNode) => {
+            state.active = false;
+            state.batch = []; state.batchFrames = 0;
+            if (state.node && sourceNode) {
+                try { sourceNode.disconnect(state.node); } catch (_) { /* already gone */ }
+            }
+        };
+        return state;
+    }
+
+    // ── Core <audio> element capture ─────────────────────────────────────────
+    // createMediaElementSource permanently reroutes the element into its
+    // context, so it is created lazily — only the first time an exclusive
+    // device actually needs it — and never torn down. From then on the element
+    // always plays through _elCtx; sink toggling routes it to the speakers
+    // (shared mode) or the null sink + bus (exclusive mode).
+    let _elCtx = null, _elSource = null, _elTap = null;
+    async function _ensureElementCapture() {
+        if (_elCtx) return;
+        const el = document.getElementById('audio');
+        if (!el) throw new Error('no core audio element');
+        _elCtx = new AudioContext();
+        _elSource = _elCtx.createMediaElementSource(el);
+        _elSource.connect(_elCtx.destination);
+        _elTap = _makeTap(_elCtx);
+        await _elTap.attach(_elSource);
+    }
+
+    // ── Engagement state machine ─────────────────────────────────────────────
+    // 'off' | 'element' | 'stems'
+    let _mode = 'off';
+    let _stemsGraph = null;   // { context, masterNode } snapshot while engaged
+    let _stemsTap = null;
+    const _stemsTaps = new WeakMap();  // context → tap (stems ctx is reused across songs)
+    let _busy = false;
+
+    async function _setSink(ctx, exclusive) {
+        if (typeof ctx.setSinkId !== 'function') throw new Error('setSinkId unsupported');
+        await ctx.setSinkId(exclusive ? { type: 'none' } : '');
+        if (ctx.state !== 'running') await ctx.resume().catch(() => {});
+        // [asio-diag] a context left on the default sink while the bus is
+        // engaged is exactly the "song on the wrong device" symptom — record
+        // every successful sink flip (failures throw and are logged upstream).
+        if (window._asioDiagEnabled?.()) {
+            console.log('[asio-diag] setSink:', exclusive ? 'null-sink' : 'default',
+                'state=', ctx.state, 'rate=', ctx.sampleRate);
+        }
+    }
+
+    async function _disengage() {
+        if (_mode === 'off') return;
+        const prev = _mode;
+        _mode = 'off';
+        try { await api.setRendererBus(false, 0); } catch (_) { /* engine gone */ }
+        if (prev === 'element' && _elCtx) {
+            _elTap.active = false;
+            await _setSink(_elCtx, false).catch(() => {});
+        } else if (prev === 'stems' && _stemsGraph) {
+            if (_stemsTap) _stemsTap.detach(_stemsGraph.masterNode);
+            await _setSink(_stemsGraph.context, false).catch(() => {});
+            _stemsGraph = null; _stemsTap = null;
+        }
+        console.log('[renderer-bus] disengaged (' + prev + ')');
+    }
+
+    async function _engageStems(graph) {
+        await _setSink(graph.context, true);
+        let tap = _stemsTaps.get(graph.context);
+        if (!tap) { tap = _makeTap(graph.context); _stemsTaps.set(graph.context, tap); }
+        await tap.attach(graph.masterNode);
+        await api.setRendererBus(true, 1.0);
+        tap.active = true;
+        _stemsGraph = graph; _stemsTap = tap;
+        _mode = 'stems';
+        console.log('[renderer-bus] engaged: stems graph → engine bus');
+    }
+
+    async function _engageElement() {
+        await _ensureElementCapture();
+        await _setSink(_elCtx, true);
+        await api.setRendererBus(true, 1.0);
+        _elTap.active = true;
+        _mode = 'element';
+        console.log('[renderer-bus] engaged: <audio> element → engine bus');
+    }
+
+    async function _reevaluate() {
+        if (_busy) return;
+        _busy = true;
+        try {
+            let running = false, exclusive = false;
+            try {
+                running = await api.isAudioRunning();
+            } catch (_) { /* engine unreachable → treat as not running */ }
+            if (running) {
+                // Reuse the Phase 1 predicate installed by the routing watcher
+                // (getCurrentDevice + exclusive-type check with change-logged
+                // diagnostics). Fail closed if it is somehow absent.
+                exclusive = !!(await window._juceOutputIsExclusive?.());
+            }
+
+            // The stems plugin publishes its live graph while a multi-stem
+            // song is loaded (and removes it on teardown).
+            const stems = (window.feedBack || window.slopsmith)?.stems?.audioGraph || null;
+            // Element songs: a song is loaded, it is NOT riding the native
+            // transport (Phase 1 owns those), and the stems graph is not the
+            // player. Covers native-transport rejects (codec) in exclusive
+            // mode — without this they would be silent.
+            const songAudio = window._currentSongAudio;
+            const elementSong = !!songAudio && !window._juceMode && !stems;
+
+            let want = 'off';
+            if (running && exclusive) {
+                if (stems) want = 'stems';
+                else if (elementSong) want = 'element';
+            }
+
+            // [asio-diag] full decision vector, change-gated (500ms poll —
+            // steady state must not flood the buffer). This is the feeder-side
+            // counterpart of the watcher's [feedpak-route] decision line: it
+            // shows WHY the bus did or didn't engage (exclusive predicate,
+            // stems graph presence, native transport ownership, element song).
+            if (window._asioDiagEnabled?.()) {
+                const d = 'running=' + running + ' exclusive=' + exclusive
+                    + ' stems=' + !!stems + ' songAudio=' + !!songAudio
+                    + ' juceMode=' + !!window._juceMode
+                    + ' elementSong=' + elementSong
+                    + ' want=' + want + ' mode=' + _mode;
+                if (d !== window._lastRendererBusDecision) {
+                    window._lastRendererBusDecision = d;
+                    console.log('[asio-diag] renderer-bus:', d);
+                }
+            }
+
+
+            const stemsGraphChanged = _mode === 'stems' && stems !== _stemsGraph;
+            if (want !== _mode || stemsGraphChanged) {
+                await _disengage();
+                if (want === 'stems') await _engageStems(stems);
+                else if (want === 'element') await _engageElement();
+            }
+        } catch (e) {
+            console.warn('[renderer-bus] reevaluate failed (will retry):', e);
+            _mode = 'off';
+        } finally {
+            _busy = false;
+        }
+    }
+
+    // Same cadence/rationale as the routing watcher above. Also re-check on
+    // visibility return so a device switch made while hidden is reconciled.
+    setInterval(() => { if (!document.hidden) void _reevaluate(); }, 500);
+    document.addEventListener('visibilitychange', () => { if (!document.hidden) void _reevaluate(); });
+    window._reevaluateRendererBus = _reevaluate;
+})();
+
 // Desktop JUCE backing uses an empty <audio> element; plugins such as Section Map
 // still seek via audio.currentTime / pause / play. Mirror those onto jucePlayer
 // while _juceMode is active. Same-tick pause+seek coalesce into a single seek
@@ -6325,7 +6638,9 @@ window.feedBack.on('screen:changed', (ev) => {
     if (id === 'player') _hideResumePill();
     else _maybeShowResumePill();
 });
-if (document.readyState === 'loading') {
+// `defer` runs this at readyState 'interactive' — later scripts have not
+// evaluated yet, so wait for DOMContentLoaded (see static/v3/index.html).
+if (document.readyState !== 'complete') {
     document.addEventListener('DOMContentLoaded',
         () => { try { _maybeShowResumePill(); } catch (_) {} }, { once: true });
 } else {
@@ -8868,7 +9183,7 @@ function _ensureSectionPracticeDom() {
     ctrl.appendChild(bar);
     // Mount OUTSIDE #player-controls (in #player-footer, or as its sibling) so
     // the popover's chip <button>s can't be matched by a plugin injector that
-    // anchors on `#player-controls > button:last-of-type` (see static/index.html).
+    // anchors on `#player-controls > button:last-of-type` (see static/v3/index.html).
     _mountSectionPracticeControlSafe(ctrl);
     _placeSectionPracticeControlForChrome();
     return bar;
@@ -11850,3 +12165,52 @@ async function bootstrapPluginsAndUi() {
         })
         .catch(() => {});
 })();
+
+
+// ─── The window contract ────────────────────────────────────────────────────
+// app.js is a classic script today, so every top-level `function foo()` here is
+// implicitly a property of `window`. The R3a migration turns this file into an
+// ES module, where that stops being true — module scope is not global scope, and
+// each of these names would silently vanish from `window`.
+//
+// Everything below is reached by NAME from outside this file, so each one is
+// made explicit BEFORE the flip. While app.js is still classic this whole block
+// is a no-op (it just re-assigns what is already there), which is exactly what
+// makes it safe to land on its own.
+//
+// The consumers are: inline on*= handlers in static/v3/index.html; on*= handlers
+// this file builds inside template literals; static/v3/*.js; the capabilities;
+// bundled plugins; and — easy to forget, since they live in other repos —
+// feedback-desktop and the external plugins. Constitution II names
+// `window.playSong` / `window.showScreen` / `window.feedBack` as the public
+// extension contract.
+//
+// Guarded by tests/js/window_contract.test.js. Add a name here the moment
+// anything outside app.js calls it.
+Object.assign(window, {
+    _confirmDialog, _getArrangementNamingMode, _libraryLocalFilename, _librarySongArtUrl,
+    _librarySongId, _onHeaderClick, _onNamingModeChange, _trapFocusInModal,
+    changeArrangement, checkPluginUpdates, clearLibFilters, clearLoop,
+    deleteSelectedLoop, exportDiagnostics, exportSettings, filterFavorites,
+    filterLibrary, fullRescanLibrary, goFavPage, handleSliderInput,
+    hideScanBanner, importSettings, loadPlugins, loadSavedLoop,
+    loadSettings, onSectionPracticeModeChange, openEditModal, persistSetting,
+    pickDlcFolder, pinCurrentArrangementDefault, playSong, previewDiagnostics,
+    previewEditArt, renderGridCards, renderTreeInto, rescanLibrary,
+    retuneSong, saveCurrentLoop, saveSettings, seekBy,
+    setAvOffsetMs, setFavView, setInstrumentPathway, setLibView,
+    setLibraryProvider, setLoopEnd, setLoopStart, setMastery,
+    setSpeed, setViz, showScreen, sortFavorites,
+    sortLibrary, syncLibrarySong, toggleAllArtists, toggleAllFavoriteArtists,
+    toggleLibFilters, togglePlay, toggleSectionPracticePopover, uiPrompt,
+    updatePlugin, uploadSongs,
+
+    // These four are invisible to every static scan. app.js:2156-2157 picks the
+    // handler NAME at runtime —
+    //     const letterFn = favoritesOnly ? 'filterFavTreeLetter' : 'filterTreeLetter';
+    // — and interpolates it: `onclick="${letterFn}('A')"`. So the names never
+    // appear as identifiers anywhere, and ESLint / no-undef / a grep for
+    // `onclick="fn` all miss them. They are the library A-Z rail and its
+    // pagination; drop one and those buttons throw at click time, nowhere else.
+    filterFavTreeLetter, filterTreeLetter, goFavTreePage, goTreePage,
+});

static/audio-mixer.js

@@ -519,7 +519,9 @@ window.feedBack.audio = Object.assign(window.feedBack.audio || {}, {
     readSongVolume: _readSongVolume,
 });
 
-if (document.readyState === 'loading') {
+// `defer` runs this at readyState 'interactive' — later scripts have not
+// evaluated yet, so wait for DOMContentLoaded (see static/v3/index.html).
+if (document.readyState !== 'complete') {
     document.addEventListener('DOMContentLoaded', _init);
 } else {
     _init();

static/capabilities/audio-effects.js

@@ -9,6 +9,8 @@
 
     const SCHEMA = 'feedBack.audio_effects.diagnostics.v1';
     const PLAN_SCHEMA = 'feedBack.audio_effects.chain_plan.v1';
+// Pre-rebrand plugins (rig_builder <= 2.9.x) still send the old schema id — accept it as an alias.
+const LEGACY_PLAN_SCHEMA = 'slopsmith.audio_effects.chain_plan.v1';
     const OWNER_ID = 'core.audio.effects';
     const DEFAULT_ROUTE_KEY = 'desktop-main';
     const DEFAULT_TIMEOUT_MS = 2000;
@@ -734,7 +736,7 @@
         const errors = [];
         const source = _plainObject(rawPlan);
         const schema = _string(source.schema || source.version, PLAN_SCHEMA);
-        if (schema !== PLAN_SCHEMA && schema !== '1') errors.push('Unsupported chain plan schema');
+        if (schema !== PLAN_SCHEMA && schema !== LEGACY_PLAN_SCHEMA && schema !== '1') errors.push('Unsupported chain plan schema');
         const planRoute = _safeRoute(source.routeKey || source.route || routeKey);
         if (planRoute !== routeKey) errors.push('Chain plan route does not match selected route');
         const providerId = _safeId(source.providerId || provider.providerId, provider.providerId);

static/capabilities/interface-scale.js

@@ -111,7 +111,9 @@
 
     // Announce once after the document parses, so any listener wired during page
     // load can sync without special-casing (consumers may also just call get()).
-    if (document.readyState === 'loading') {
+    // `defer` runs this at readyState 'interactive' — later scripts have not
+    // evaluated yet, so wait for DOMContentLoaded (see static/v3/index.html).
+    if (document.readyState !== 'complete') {
         document.addEventListener('DOMContentLoaded', announce, { once: true });
     } else {
         announce();

static/index.html

@@ -1,621 +0,0 @@
-<!DOCTYPE html>
-<html lang="en" class="scroll-smooth">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>FeedBack</title>
-    <!-- Placeholder favicon — emoji SVG data URI. Swap for a real logo later. See #55. -->
-    <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Ctext y='14' font-size='14'%3E%F0%9F%8E%B8%3C/text%3E%3C/svg%3E">
-    <!-- Tailwind utility classes are served from a prebuilt static
-         stylesheet (regenerated by scripts/build-tailwind.sh). The old
-         Play CDN (cdn.tailwindcss.com) JIT scanned the DOM ~1.8x/sec
-         on the main thread, dropping ~26% of frames with the 3D
-         highway running — see feedBack-desktop#110. Theme extensions
-         (dark/accent/gold colors, Inter font) live in tailwind.config.js. -->
-    <link rel="stylesheet" href="/static/tailwind.min.css">
-    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800&display=swap" rel="stylesheet">
-    <link rel="stylesheet" href="/static/style.css">
-    <link rel="stylesheet" href="/static/vendor/shepherd.css">
-    <link rel="stylesheet" href="/static/tour-engine.css">
-    <!-- Diagnostics console capture must wrap console.* before any other
-         script logs anything; load it as early as possible. See
-         docs/diagnostics-bundle-spec.md (feedBack#166). -->
-    <script src="/static/diagnostics.js"></script>
-    <script src="/static/capabilities.js"></script>
-    <script src="/static/capabilities/library.js"></script>
-    <script src="/static/capabilities/tuning.js"></script>
-    <script src="/static/capabilities/working-tuning.js"></script>
-    <script src="/static/capabilities/audio-session.js"></script>
-    <script src="/static/capabilities/audio-effects.js"></script>
-    <script src="/static/capabilities/playback.js"></script>
-    <!-- fee[dB]ack v0.3.0: ui.library-card-injection capability (plugin card actions). -->
-    <script src="/static/capabilities/library-card-actions.js"></script>
-    <script src="/static/capabilities/visualization.js"></script>
-    <script src="/static/capabilities/note-detection.js"></script>
-    <script src="/static/capabilities/midi-input.js"></script>
-</head>
-<body class="bg-dark-900 text-gray-200 font-display">
-
-    <!-- Navigation -->
-    <nav id="navbar" class="fixed top-0 w-full z-50 transition-all duration-300">
-        <div class="max-w-7xl mx-auto px-6 h-16 flex items-center justify-between">
-            <div class="flex items-end gap-1.5">
-                <a href="#" onclick="showScreen('home');return false" class="text-xl font-bold bg-gradient-to-r from-accent-light to-purple-400 bg-clip-text text-transparent">
-                    FeedBack
-                </a>
-                <span id="app-version" class="text-xs text-gray-600 mb-0.5"></span>
-            </div>
-            <div class="hidden md:flex items-center gap-8">
-                <a href="#" onclick="showScreen('home');return false" class="text-sm text-gray-400 hover:text-white transition">Library</a>
-                <a href="#" onclick="showScreen('favorites');return false" class="text-sm text-gray-400 hover:text-white transition">Favorites</a>
-                <a href="#" onclick="document.getElementById('upload-songs-file').click();return false" class="text-sm text-gray-400 hover:text-white transition">Upload</a>
-                <span id="nav-plugins" class="contents"></span>
-                <a href="#" onclick="showScreen('settings');return false" class="text-sm text-gray-400 hover:text-white transition">Settings</a>
-            </div>
-            <!-- Mobile menu -->
-            <button onclick="document.getElementById('mobile-menu').classList.toggle('hidden')" class="md:hidden text-gray-400">
-                <svg class="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 12h16M4 18h16"/></svg>
-            </button>
-        </div>
-        <div id="mobile-menu" class="hidden md:hidden bg-dark-800/95 backdrop-blur border-t border-gray-800">
-            <div class="px-6 py-4 flex flex-col gap-3">
-                <a href="#" onclick="showScreen('home');this.parentElement.parentElement.classList.add('hidden');return false" class="text-gray-400 hover:text-white">Library</a>
-                <a href="#" onclick="showScreen('favorites');this.parentElement.parentElement.classList.add('hidden');return false" class="text-gray-400 hover:text-white">Favorites</a>
-                <a href="#" onclick="document.getElementById('upload-songs-file').click();this.parentElement.parentElement.classList.add('hidden');return false" class="text-gray-400 hover:text-white">Upload</a>
-                <span id="mobile-nav-plugins" class="flex flex-col gap-2 border-t border-b border-gray-800 py-2 my-1">
-                    <span class="text-xs text-gray-600 uppercase tracking-wider">Plugins</span>
-                </span>
-                <a href="#" onclick="showScreen('settings');this.parentElement.parentElement.classList.add('hidden');return false" class="text-gray-400 hover:text-white">Settings</a>
-            </div>
-        </div>
-    </nav>
-
-    <!-- Hidden file input shared by the navbar "Upload" link. Kept at body
-         level so it stays reachable regardless of which screen is active. -->
-    <input type="file" id="upload-songs-file" accept=".feedpak,.sloppak" multiple class="hidden" onchange="uploadSongs(this.files); this.value=''">
-
-    <!-- ══ HOME (Hero + Library) ══════════════════════════════════════════ -->
-    <div id="home" class="screen active">
-        <!-- Library -->
-        <section id="library-section" class="max-w-7xl mx-auto px-6 pt-24 pb-16">
-            <div id="alpha-warning-banner" class="hidden mb-6 px-4 py-3 bg-amber-900/30 border border-amber-500/30 rounded-xl flex items-start gap-3" role="status">
-                <span class="text-amber-400 text-lg leading-none mt-0.5" aria-hidden="true">⚠</span>
-                <div class="text-sm text-amber-100">
-                    <strong class="text-amber-300">Heads up — this is an alpha build.</strong>
-                    Some things may be broken or change without warning. If you hit a bug, please file an issue. Thanks for trying it out!
-                </div>
-            </div>
-            <div class="flex flex-col md:flex-row md:items-center justify-between gap-4 mb-10">
-                <div>
-                    <h2 id="lib-title" class="text-3xl font-bold text-white">Your Library</h2>
-                    <p class="text-gray-500 mt-1" id="lib-count"></p>
-                </div>
-                <div class="flex gap-3 w-full md:w-auto flex-wrap">
-                    <select id="lib-provider" onchange="setLibraryProvider(this.value)"
-                        aria-label="Library source"
-                        class="bg-dark-700 border border-gray-800 rounded-xl px-3 py-2.5 text-sm text-gray-300 outline-none" title="Library source">
-                        <option value="local">My Library</option>
-                    </select>
-                    <!-- View toggle -->
-                    <div class="flex bg-dark-700 border border-gray-800 rounded-xl overflow-hidden">
-                        <button id="view-grid-btn" onclick="setLibView('grid')" class="px-3 py-2.5 text-sm transition" title="Grid view">
-                            <svg class="w-4 h-4" fill="currentColor" viewBox="0 0 16 16"><rect x="1" y="1" width="6" height="6" rx="1"/><rect x="9" y="1" width="6" height="6" rx="1"/><rect x="1" y="9" width="6" height="6" rx="1"/><rect x="9" y="9" width="6" height="6" rx="1"/></svg>
-                        </button>
-                        <button id="view-tree-btn" onclick="setLibView('tree')" class="px-3 py-2.5 text-sm transition" title="Artist/Album view">
-                            <svg class="w-4 h-4" fill="currentColor" viewBox="0 0 16 16"><rect x="1" y="1" width="14" height="3" rx="1"/><rect x="3" y="6" width="12" height="3" rx="1"/><rect x="3" y="11" width="12" height="3" rx="1"/></svg>
-                        </button>
-                            <button id="view-folder-btn" onclick="setLibView('folder')" class="px-3 py-2.5 text-sm transition" title="Folder view">
-                                <svg class="w-4 h-4" fill="currentColor" viewBox="0 0 16 16"><path d="M1 3.5A1.5 1.5 0 012.5 2h3.086a1.5 1.5 0 011.06.44l.915.914H13.5A1.5 1.5 0 0115 4.914V12.5a1.5 1.5 0 01-1.5 1.5h-11A1.5 1.5 0 011 12.5v-9z"/></svg>
-                            </button>
-                    </div>
-                    <!-- Grid controls -->
-                    <select id="lib-sort" onchange="sortLibrary()"
-                        class="lib-nontree-ctrl bg-dark-700 border border-gray-800 rounded-xl px-3 py-2.5 text-sm text-gray-300 outline-none">
-                        <option value="artist">Artist A-Z</option>
-                        <option value="artist-desc">Artist Z-A</option>
-                        <option value="title">Title A-Z</option>
-                        <option value="title-desc">Title Z-A</option>
-                        <option value="recent">Recently Added</option>
-                        <option value="year-desc">Year (newest)</option>
-                        <option value="year">Year (oldest)</option>
-                        <option value="tuning">Tuning</option>
-                        <option value="difficulty">Difficulty (easiest first)</option>
-                        <option value="difficulty-desc">Difficulty (hardest first)</option>
-                    </select>
-                    <!-- Format filter (shared) -->
-                    <select id="lib-format" onchange="sortLibrary()"
-                        class="bg-dark-700 border border-gray-800 rounded-xl px-3 py-2.5 text-sm text-gray-300 outline-none" title="Filter by format">
-                        <option value="">All formats</option>
-                        <option value="sloppak">Feedpak</option>
-                        <option value="loose">Folder</option>
-                    </select>
-                    <!-- Tree controls -->
-                    <button onclick="toggleAllArtists(true)" class="lib-tree-ctrl bg-dark-700 border border-gray-800 rounded-xl px-3 py-2.5 text-sm text-gray-400 hover:text-white transition">Expand All</button>
-                    <button onclick="toggleAllArtists(false)" class="lib-tree-ctrl bg-dark-700 border border-gray-800 rounded-xl px-3 py-2.5 text-sm text-gray-400 hover:text-white transition">Collapse All</button>
-                    <!-- Filters drawer toggle (feedBack#129) -->
-                    <button onclick="toggleLibFilters()" id="btn-lib-filters"
-                        class="bg-dark-700 border border-gray-800 hover:border-accent/40 rounded-xl px-4 py-2.5 text-sm text-gray-300 transition flex items-center gap-2"
-                        title="Filter by parts, tuning, lyrics">
-                        <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M3 4h18M6 12h12M10 20h4"/></svg>
-                        <span>Filters</span>
-                        <span id="lib-filters-count" class="hidden bg-accent/30 text-accent-light text-xs font-semibold rounded-full px-1.5 py-0.5 min-w-[1.25rem] text-center">0</span>
-                    </button>
-                    <!-- Shared -->
-                    <input type="text" id="lib-filter" placeholder="Search songs..." oninput="filterLibrary()"
-                        class="bg-dark-700 border border-gray-800 rounded-xl px-4 py-2.5 text-sm text-gray-300 placeholder-gray-600 focus:border-accent/50 focus:ring-1 focus:ring-accent/30 outline-none flex-1 md:w-60 transition">
-                </div>
-            </div>
-            <!-- Active-filter chip row (only visible when filters are set, feedBack#129) -->
-            <div id="lib-filter-chips" class="hidden flex flex-wrap gap-2 mb-5"></div>
-            <div id="lib-grid" class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-5">
-                <!-- Cards populated by JS -->
-            </div>
-            <div id="lib-tree" class="space-y-2 hidden">
-                <!-- Tree populated by JS -->
-            </div>
-            <div id="lib-folder-tree" class="space-y-1 hidden">
-                <!-- Folder tree populated by JS when Folders source is active -->
-            </div>
-        </section>
-
-        <!-- ══ Filters drawer (feedBack#129/#69/#22) ═════════════════════ -->
-        <div id="lib-filter-overlay" class="fixed inset-0 bg-black/40 z-40 hidden"
-             onclick="toggleLibFilters(false)"></div>
-        <aside id="lib-filter-drawer"
-               class="fixed top-0 right-0 h-full w-full sm:w-96 bg-dark-800 border-l border-gray-800 z-50 transform translate-x-full transition-transform duration-200 overflow-y-auto">
-            <div class="p-6 space-y-6">
-                <div class="flex items-center justify-between">
-                    <h3 class="text-lg font-semibold text-white">Filters</h3>
-                    <button onclick="toggleLibFilters(false)" class="text-gray-500 hover:text-white" title="Close">
-                        <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12"/></svg>
-                    </button>
-                </div>
-
-                <section>
-                    <div class="text-xs font-semibold uppercase tracking-wider text-gray-500 mb-2">Arrangements</div>
-                    <p class="text-xs text-gray-600 mb-3">Click cycles: any → require → exclude</p>
-                    <div id="filter-arrangements" class="flex flex-wrap gap-2"></div>
-                </section>
-
-                <section id="filter-stems-section">
-                    <div class="text-xs font-semibold uppercase tracking-wider text-gray-500 mb-2">Stems <span class="text-gray-600 normal-case font-normal">(sloppak)</span></div>
-                    <p class="text-xs text-gray-600 mb-3">Click cycles: any → require → exclude</p>
-                    <div id="filter-stems" class="flex flex-wrap gap-2"></div>
-                </section>
-
-                <section>
-                    <div class="text-xs font-semibold uppercase tracking-wider text-gray-500 mb-2">Lyrics</div>
-                    <div id="filter-lyrics" class="flex flex-wrap gap-2"></div>
-                </section>
-
-                <section>
-                    <details>
-                        <summary class="cursor-pointer flex items-center justify-between text-xs font-semibold uppercase tracking-wider text-gray-500 mb-2">
-                            <span>Tuning</span>
-                            <span id="filter-tunings-summary" class="text-gray-600 normal-case font-normal text-xs">All tunings</span>
-                        </summary>
-                        <div id="filter-tunings" class="mt-3 space-y-1 max-h-64 overflow-y-auto pr-1"></div>
-                    </details>
-                </section>
-
-                <div class="flex items-center justify-between pt-4 border-t border-gray-800">
-                    <button onclick="clearLibFilters()" class="text-sm text-gray-400 hover:text-white transition">Clear all</button>
-                    <button onclick="toggleLibFilters(false)" class="bg-accent hover:bg-accent-light px-4 py-2 rounded-lg text-sm font-medium text-white transition">Done</button>
-                </div>
-            </div>
-        </aside>
-    </div>
-
-    <!-- ══ FAVORITES ════════════════════════════════════════════════════ -->
-    <div id="favorites" class="screen">
-        <section class="max-w-7xl mx-auto px-6 pt-24 pb-16">
-            <div class="flex flex-col md:flex-row md:items-center justify-between gap-4 mb-10">
-                <div>
-                    <h2 class="text-3xl font-bold text-white">Favorites</h2>
-                    <p class="text-gray-500 mt-1" id="fav-count"></p>
-                </div>
-                <div class="flex gap-3 w-full md:w-auto flex-wrap">
-                    <div class="flex bg-dark-700 border border-gray-800 rounded-xl overflow-hidden">
-                        <button id="fav-view-grid-btn" onclick="setFavView('grid')" class="px-3 py-2.5 text-sm transition" title="Grid view">
-                            <svg class="w-4 h-4" fill="currentColor" viewBox="0 0 16 16"><rect x="1" y="1" width="6" height="6" rx="1"/><rect x="9" y="1" width="6" height="6" rx="1"/><rect x="1" y="9" width="6" height="6" rx="1"/><rect x="9" y="9" width="6" height="6" rx="1"/></svg>
-                        </button>
-                        <button id="fav-view-tree-btn" onclick="setFavView('tree')" class="px-3 py-2.5 text-sm transition" title="Artist/Album view">
-                            <svg class="w-4 h-4" fill="currentColor" viewBox="0 0 16 16"><rect x="1" y="1" width="14" height="3" rx="1"/><rect x="3" y="6" width="12" height="3" rx="1"/><rect x="3" y="11" width="12" height="3" rx="1"/></svg>
-                        </button>
-                    </div>
-                    <select id="fav-sort" onchange="sortFavorites()"
-                        class="fav-grid-ctrl bg-dark-700 border border-gray-800 rounded-xl px-3 py-2.5 text-sm text-gray-300 outline-none">
-                        <option value="artist">Artist A-Z</option>
-                        <option value="artist-desc">Artist Z-A</option>
-                        <option value="title">Title A-Z</option>
-                        <option value="title-desc">Title Z-A</option>
-                        <option value="recent">Recently Added</option>
-                        <option value="tuning">Tuning</option>
-                    </select>
-                    <button onclick="toggleAllFavoriteArtists(true)" class="fav-tree-ctrl bg-dark-700 border border-gray-800 rounded-xl px-3 py-2.5 text-sm text-gray-400 hover:text-white transition">Expand All</button>
-                    <button onclick="toggleAllFavoriteArtists(false)" class="fav-tree-ctrl bg-dark-700 border border-gray-800 rounded-xl px-3 py-2.5 text-sm text-gray-400 hover:text-white transition">Collapse All</button>
-                    <input type="text" id="fav-filter" placeholder="Search favorites..." oninput="filterFavorites()"
-                        class="bg-dark-700 border border-gray-800 rounded-xl px-4 py-2.5 text-sm text-gray-300 placeholder-gray-600 focus:border-accent/50 focus:ring-1 focus:ring-accent/30 outline-none flex-1 md:w-60 transition">
-                </div>
-            </div>
-            <div id="fav-grid" class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-5">
-            </div>
-            <div id="fav-tree" class="space-y-2 hidden">
-            </div>
-        </section>
-    </div>
-
-    <!-- ══ Plugin screens injected dynamically by loadPlugins() ══════════ -->
-
-    <!-- ══ SETTINGS ═══════════════════════════════════════════════════════ -->
-    <div id="settings" class="screen">
-        <div class="max-w-2xl mx-auto px-6 pt-24 pb-16">
-            <button onclick="showScreen('home')" class="text-gray-500 hover:text-white text-sm mb-6 flex items-center gap-1">
-                <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 19l-7-7 7-7"/></svg> Back
-            </button>
-            <h2 class="text-3xl font-bold text-white mb-8">Settings</h2>
-
-            <div class="space-y-10">
-                <!-- App Updates — Velopack auto-update, desktop only. Stays
-                     hidden in the plain web app; setupAppUpdates() unhides
-                     this block when window.feedBackDesktop.update exists,
-                     and shows a disabled "not available on Linux" fallback
-                     when running on Linux. -->
-                <div id="app-updates-block" class="hidden border border-gray-800 rounded-xl bg-dark-800/40 p-5">
-                    <h3 class="text-xs font-semibold uppercase tracking-wider text-gray-500 mb-4">App Updates</h3>
-                    <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
-                        <div>
-                            <label class="text-sm font-medium text-gray-400 mb-2 block" for="app-update-channel">Update channel</label>
-                            <select id="app-update-channel"
-                                class="w-full bg-dark-700 border border-gray-800 rounded-xl px-3 py-2.5 text-sm text-gray-300 outline-none">
-                                <option value="stable">Stable</option>
-                                <option value="rc">Release candidate</option>
-                                <option value="beta">Beta</option>
-                                <option value="alpha">Alpha</option>
-                            </select>
-                        </div>
-                        <div class="flex items-end">
-                            <button id="app-update-check-now"
-                                class="bg-accent hover:bg-accent-light px-4 py-2.5 rounded-xl text-sm font-medium text-white transition disabled:opacity-50">
-                                Check for updates
-                            </button>
-                        </div>
-                    </div>
-                    <p id="app-update-status" class="text-xs text-gray-500 mt-3">Loading updater status…</p>
-                    <p id="app-update-linux-note" class="hidden text-xs text-yellow-300 mt-2">
-                        Auto-update is not available on Linux —
-                        <a href="https://github.com/got-feedback/feedBack-desktop/releases" target="_blank" rel="noopener" class="text-accent hover:text-accent-light underline">download new versions from GitHub Releases</a>.
-                    </p>
-                </div>
-
-                <!-- ── Core FeedBack settings ─────────────────────────────── -->
-                <section>
-                    <h3 class="text-xs font-semibold uppercase tracking-wider text-gray-500 mb-4">FeedBack</h3>
-                    <div class="space-y-6">
-                        <div>
-                            <label class="text-sm font-medium text-gray-400 mb-2 block">Library Folder Path</label>
-                            <div class="flex gap-3">
-                                <input type="text" id="dlc-path" placeholder="/path/to/your/library"
-                                    class="flex-1 bg-dark-700 border border-gray-800 rounded-xl px-4 py-2.5 text-sm text-gray-300 placeholder-gray-600 focus:border-accent/50 outline-none">
-                                <button onclick="pickDlcFolder()" id="btn-pick-dlc" class="hidden bg-dark-600 hover:bg-dark-500 px-4 py-2.5 rounded-xl text-sm text-gray-300 transition whitespace-nowrap">📂 Browse</button>
-                                <button onclick="saveSettings()" class="bg-accent hover:bg-accent-light px-6 py-2.5 rounded-xl text-sm font-semibold text-white transition">Save</button>
-                            </div>
-                        </div>
-                        <div>
-                            <label class="flex items-center gap-3 cursor-pointer select-none">
-                                <input type="checkbox" id="setting-lefty" onchange="highway.setLefty(this.checked)"
-                                    class="rounded border-gray-600 bg-dark-700 text-accent focus:ring-accent/40">
-                                <span class="text-sm text-gray-300">Left-handed <span class="text-gray-500">(invert frets on the note highway)</span></span>
-                            </label>
-                        </div>
-                        <div>
-                            <label class="flex items-center gap-3 cursor-pointer select-none">
-                                <input type="checkbox" id="setting-autoplay-exit" checked onchange="setAutoplayExit(this.checked)"
-                                    class="rounded border-gray-600 bg-dark-700 text-accent focus:ring-accent/40">
-                                <span class="text-sm text-gray-300">Autoplay &amp; auto-exit <span class="text-gray-500">(start songs/lessons automatically and return to the menu when the score screen closes)</span></span>
-                            </label>
-                        </div>
-                        <div>
-                            <label class="text-sm font-medium text-gray-400 mb-2 block">Default Arrangement</label>
-                            <select id="default-arrangement"
-                                onchange="persistSetting('default_arrangement', this.value)"
-                                class="bg-dark-700 border border-gray-800 rounded-xl px-3 py-2.5 text-sm text-gray-300 outline-none">
-                                <option value="">Most notes (auto)</option>
-                                <option value="Lead">Lead</option>
-                                <option value="Rhythm">Rhythm</option>
-                                <option value="Bass">Bass</option>
-                            </select>
-                        </div>
-                        <div>
-                            <label class="text-sm font-medium text-gray-400 mb-2 block">Arrangement Names</label>
-                            <select id="arrangement-naming-mode"
-                                onchange="_onNamingModeChange(this.value)"
-                                class="bg-dark-700 border border-gray-800 rounded-xl px-3 py-2.5 text-sm text-gray-300 outline-none">
-                                <option value="smart">Smart (Lead, Alt. Lead, Rhythm, Bass…)</option>
-                                <option value="legacy">Legacy (Combo, Bass)</option>
-                            </select>
-                        </div>
-                        <div>
-                            <label for="setting-av-offset" class="text-sm font-medium text-gray-400 mb-2 block">
-                                A/V Sync Offset: <span id="setting-av-offset-val">0</span> ms
-                            </label>
-                            <input type="range" id="setting-av-offset" min="-1000" max="1000" step="1" value="0"
-                                oninput="setAvOffsetMs(this.value)"
-                                class="w-full slider-input">
-                            <p class="text-xs text-gray-600 mt-1">Positive = audio plays ahead of visual notes; raise this value to catch the highway up. Adjust live with the [ and ] keys (Shift for ±50 ms). Auto-saves on every change.</p>
-                        </div>
-                        <div>
-                            <label for="demucs-server-url" class="text-sm font-medium text-gray-400 mb-2 block">Demucs Server (for stem separation)</label>
-                            <div class="flex gap-3">
-                                <input type="text" id="demucs-server-url" placeholder="http://192.168.1.100:7865"
-                                    class="flex-1 bg-dark-700 border border-gray-800 rounded-xl px-4 py-2.5 text-sm text-gray-300 placeholder-gray-600 focus:border-accent/50 outline-none">
-                                <button onclick="saveSettings()" class="bg-accent hover:bg-accent-light px-6 py-2.5 rounded-xl text-sm font-semibold text-white transition">Save</button>
-                            </div>
-                            <p class="text-xs text-gray-600 mt-1">Optional. Run <a href="https://github.com/got-feedBack/feedBack-demucs-server" target="_blank" rel="noopener" class="text-accent hover:text-accent-light underline">feedBack-demucs-server</a> on a machine with a GPU to offload stem splitting and avoid resource exhaustion on the host running FeedBack.</p>
-                        </div>
-                        <div>
-                            <label class="text-sm font-medium text-gray-400 mb-2 block">Library</label>
-                            <div class="flex items-center gap-3">
-                                <button onclick="rescanLibrary()" id="btn-rescan" class="bg-dark-600 hover:bg-dark-500 px-5 py-2.5 rounded-xl text-sm text-gray-300 transition">Rescan Library</button>
-                                <button onclick="fullRescanLibrary()" id="btn-full-rescan" class="bg-dark-600 hover:bg-red-900/30 px-5 py-2.5 rounded-xl text-sm text-gray-400 transition">Full Rescan</button>
-                                <span id="rescan-status" class="text-xs text-gray-500"></span>
-                            </div>
-                            <p class="text-xs text-gray-600 mt-1">Rescan checks for new songs. Full Rescan clears the cache and re-imports everything.</p>
-                        </div>
-                        <div>
-                            <label class="text-sm font-medium text-gray-400 mb-2 block">Backup</label>
-                            <div class="flex items-center gap-3">
-                                <button onclick="exportSettings()" id="btn-export-settings" class="bg-dark-600 hover:bg-dark-500 px-5 py-2.5 rounded-xl text-sm text-gray-300 transition">Export Settings</button>
-                                <button onclick="document.getElementById('import-settings-file').click()" id="btn-import-settings" class="bg-dark-600 hover:bg-dark-500 px-5 py-2.5 rounded-xl text-sm text-gray-300 transition">Import Settings</button>
-                                <input type="file" id="import-settings-file" accept="application/json,.json" class="hidden" onchange="importSettings(this.files[0]); this.value=''">
-                                <span id="backup-status" class="text-xs text-gray-500"></span>
-                            </div>
-                            <p class="text-xs text-gray-600 mt-1">Export bundles server config, browser preferences, and opted-in plugin data into one JSON file. Import overwrites current settings and reloads.</p>
-                        </div>
-                        <!-- ── Diagnostics (feedBack#166) ────────────────────── -->
-                        <div>
-                            <label class="text-sm font-medium text-gray-400 mb-2 block">Diagnostics</label>
-                            <div class="grid grid-cols-2 gap-2 mb-3 text-xs text-gray-400">
-                                <label class="flex items-center gap-2"><input type="checkbox" id="diag-incl-system" checked class="rounded border-gray-600 bg-dark-700 text-accent"> System info</label>
-                                <label class="flex items-center gap-2"><input type="checkbox" id="diag-incl-hardware" checked class="rounded border-gray-600 bg-dark-700 text-accent"> Hardware (CPU/GPU/RAM)</label>
-                                <label class="flex items-center gap-2"><input type="checkbox" id="diag-incl-logs" checked class="rounded border-gray-600 bg-dark-700 text-accent"> Server logs (last 5 MB)</label>
-                                <label class="flex items-center gap-2"><input type="checkbox" id="diag-incl-console" checked class="rounded border-gray-600 bg-dark-700 text-accent"> Browser console + errors</label>
-                                <label class="flex items-center gap-2"><input type="checkbox" id="diag-incl-plugins" checked class="rounded border-gray-600 bg-dark-700 text-accent"> Plugin diagnostics</label>
-                                <label class="flex items-center gap-2"><input type="checkbox" id="diag-redact" checked class="rounded border-gray-600 bg-dark-700 text-accent"> Redact paths &amp; song names</label>
-                            </div>
-                            <div class="flex items-center gap-3">
-                                <button onclick="previewDiagnostics()" id="btn-diag-preview" class="bg-dark-600 hover:bg-dark-500 px-5 py-2.5 rounded-xl text-sm text-gray-300 transition">Preview Bundle</button>
-                                <button onclick="exportDiagnostics()" id="btn-diag-export" class="bg-dark-600 hover:bg-dark-500 px-5 py-2.5 rounded-xl text-sm text-gray-300 transition">Export Diagnostics</button>
-                                <span id="diag-status" class="text-xs text-gray-500"></span>
-                            </div>
-                            <p class="text-xs text-gray-600 mt-1">Bundles server logs, hardware info, plugin inventory, and the browser console transcript into one zip for bug reports. Redaction strips DLC paths, song filenames, and IP addresses by default. Attach to GitHub issues; AI agents can parse the included <code>manifest.json</code>.</p>
-                            <div id="diag-preview" class="hidden mt-3 bg-dark-700 border border-gray-800 rounded-xl p-3 text-xs text-gray-400 max-h-96 overflow-auto"></div>
-                        </div>
-                        <div id="settings-status" class="text-sm text-gray-500"></div>
-                    </div>
-                </section>
-
-                <!-- ── Plugin settings ─────────────────────────────────────── -->
-                <section id="plugin-settings-area" class="hidden">
-                    <h3 class="text-xs font-semibold uppercase tracking-wider text-gray-500 mb-4">Plugins</h3>
-                    <div class="space-y-6">
-                        <div>
-                            <label class="text-sm font-medium text-gray-400 mb-2 block">Plugin Updates</label>
-                            <div class="flex items-center gap-3 mb-2">
-                                <button onclick="checkPluginUpdates()" id="btn-check-updates" class="bg-dark-600 hover:bg-dark-500 px-5 py-2.5 rounded-xl text-sm text-gray-300 transition">Check for Updates</button>
-                                <span id="updates-status" class="text-xs text-gray-500"></span>
-                            </div>
-                            <div id="plugin-updates-list" class="space-y-2"></div>
-                        </div>
-                        <!-- Per-plugin collapsible sections injected here -->
-                        <div id="plugin-settings" class="space-y-3"></div>
-                    </div>
-                </section>
-
-                <!-- ── About / Source / License (AGPL §13 disclosure) ──────── -->
-                <section>
-                    <h3 class="text-xs font-semibold uppercase tracking-wider text-gray-500 mb-4">About</h3>
-                    <div class="space-y-2 text-sm text-gray-400">
-                        <div>FeedBack <span id="app-version-about" class="text-gray-500"></span></div>
-                        <div>Licensed under <a id="about-license-link" href="https://github.com/got-feedback/feedBack/blob/main/LICENSE" target="_blank" rel="noopener" class="text-accent hover:text-accent-light underline">GNU AGPL v3.0</a>.</div>
-                        <div><a id="about-source-link" href="https://github.com/got-feedback/feedBack" target="_blank" rel="noopener" class="text-accent hover:text-accent-light underline">Source code repository</a></div>
-                        <p class="text-xs text-gray-600 mt-2">FeedBack is free software. You can redistribute it and modify it under the terms of the AGPL. If you run a modified version that interacts with users over a network, you must make the modified source available to those users.</p>
-                    </div>
-                </section>
-            </div>
-        </div>
-    </div>
-
-    <!-- Global audio element (outside player so it's always accessible) -->
-    <audio id="audio" preload="auto"></audio>
-    <script>
-    // Web Audio API fallback for iOS WKWebView which can't play WAV via <audio>
-    (function() {
-        var _waCtx = null, _waSource = null, _waStartTime = 0, _waBuffer = null, _waPlaying = false, _waLoading = false;
-        var audioEl = document.getElementById('audio');
-
-        window._webAudioFallback = {
-            load: function(url, cb) {
-                if (!url || _waLoading) return;
-                _waLoading = true;
-                if (!_waCtx) _waCtx = new (window.AudioContext || window.webkitAudioContext)();
-                console.log('[WebAudio] Loading: ' + url);
-                var xhr = new XMLHttpRequest();
-                xhr.open('GET', url, true);
-                xhr.responseType = 'arraybuffer';
-                xhr.onload = function() {
-                    _waCtx.decodeAudioData(xhr.response, function(decoded) {
-                        _waBuffer = decoded;
-                        _waLoading = false;
-                        console.log('[WebAudio] Decoded: ' + decoded.duration.toFixed(1) + 's');
-                        if (cb) cb();
-                    }, function(e) {
-                        _waLoading = false;
-                        console.error('[WebAudio] Decode error:', e);
-                    });
-                };
-                xhr.onerror = function() { _waLoading = false; };
-                xhr.send();
-            },
-            play: function() {
-                if (!_waBuffer || !_waCtx) return false;
-                this.stop();
-                if (_waCtx.state === 'suspended') _waCtx.resume();
-                _waSource = _waCtx.createBufferSource();
-                _waSource.buffer = _waBuffer;
-                // AudioBufferSourceNode has no preservesPitch equivalent so changing playbackRate here also changes pitch
-                _waSource.playbackRate.value = audioEl.playbackRate || 1;
-                _waSource.connect(_waCtx.destination);
-                _waStartTime = _waCtx.currentTime;
-                _waSource.start(0);
-                _waPlaying = true;
-                console.log('[WebAudio] Playing');
-                return true;
-            },
-            stop: function() {
-                if (_waSource) { try { _waSource.stop(); } catch(e){} _waSource = null; }
-                _waPlaying = false;
-            },
-            getTime: function() {
-                if (!_waPlaying || !_waCtx) return 0;
-                return _waCtx.currentTime - _waStartTime;
-            },
-            isActive: function() { return _waPlaying; },
-            isReady: function() { return !!_waBuffer; },
-            getDuration: function() { return _waBuffer ? _waBuffer.duration : 0; }
-        };
-    })();
-    </script>
-
-    <!-- ══ PLAYER ═════════════════════════════════════════════════════════ -->
-    <div id="player" class="screen">
-        <canvas id="highway"></canvas>
-        <div id="player-hud" class="absolute top-0 left-0 right-0 flex justify-between px-4 py-3 pointer-events-none z-10">
-            <div class="text-sm">
-                <span id="hud-artist" class="text-gray-300"></span> — <span id="hud-title" class="text-white font-semibold"></span>
-                <br><span id="hud-arrangement" class="text-gray-500 text-xs"></span>
-                <br><span id="hud-tuning" class="text-gray-500 text-xs"></span>
-                <br><span id="hud-tuning-targets" class="text-gray-500 text-xs"></span>
-            </div>
-            <div class="text-right">
-                <div id="hud-time" class="text-sm text-gray-400"></div>
-                <div id="hud-avoffset" class="text-xs text-gray-500 tabular-nums hidden" title="A/V offset — [ and ] to adjust, Shift for ±50 ms">A/V 0 ms</div>
-            </div>
-        </div>
-        <!-- #section-practice-bar lives OUTSIDE #player-controls on purpose: its
-             nested chip <button>s would otherwise be matched by plugins' legacy
-             `#player-controls`-scoped `button:last-child` injector anchor, making
-             insertBefore throw (the node isn't a direct child) and aborting the
-             shared playSong wrapper chain. The #player-footer wrapper keeps it
-             visually directly above the transport row; margin-top:auto moves here
-             from #player-controls so the whole footer still pins to the bottom. -->
-        <div id="player-footer">
-        <!-- Section Practice is collapsed behind a single pill; the multi-row bar
-             is a popover opened from the pill (toggleSectionPracticePopover). The
-             pill + popover live in #player-footer (NOT #player-controls) so the
-             popover's nested chip <button>s can't be matched by a plugin's
-             `#player-controls > button:last-child` injector anchor. -->
-        <div id="section-practice-control" class="section-practice-control section-practice-control--hidden">
-            <button type="button" id="section-practice-pill" class="section-practice-pill"
-                    aria-haspopup="dialog" aria-expanded="false" aria-controls="section-practice-bar"
-                    aria-label="Section practice"
-                    onclick="toggleSectionPracticePopover()" title="Section practice">
-                <span class="section-practice-pill-icon" aria-hidden="true">🎯</span>
-                <span class="section-practice-pill-text">Practice</span>
-                <span class="section-practice-pill-caret" aria-hidden="true">▾</span>
-            </button>
-            <div id="section-practice-bar" class="section-practice-bar" role="dialog" aria-label="Section practice">
-                <div class="section-practice-row">
-                    <label class="section-practice-mode-wrap" title="Loop the selected section until turned off">
-                        <input type="checkbox" id="section-practice-mode" onchange="onSectionPracticeModeChange()">
-                        <span class="section-practice-mode-text">Practice Section</span>
-                    </label>
-                    <span class="section-practice-label">Sections:</span>
-                    <div id="section-practice-scroll" class="section-practice-scroll" role="toolbar" aria-label="Section selection"></div>
-                </div>
-            </div>
-        </div>
-        <div id="player-controls" class="flex items-center gap-2 px-4 py-2.5 bg-dark-800 border-t border-gray-800/50 flex-wrap">
-            <button onclick="seekBy(-5)" class="px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs text-gray-300 transition" title="Seek Back 5s" aria-label="Seek Back 5s"><img src="/static/svg/rw.svg" class="button-icon-svg" alt="" aria-hidden="true" /> 5s</button>
-            <button type="button" onclick="restartCurrentSong()" class="px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs text-gray-300 transition" title="Restart song" aria-label="Restart song">↺</button>
-            <button onclick="togglePlay()" id="btn-play" class="px-4 py-1.5 bg-accent hover:bg-accent-light rounded-lg text-xs font-semibold text-white transition" aria-label="Play" title="Play" aria-pressed="false"><img src="/static/svg/play.svg" class="button-icon-svg" alt="" aria-hidden="true" /></button>
-            <button onclick="seekBy(5)" class="px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs text-gray-300 transition" title="Seek Forward 5s" aria-label="Seek Forward 5s">5s <img src="/static/svg/ff.svg" class="button-icon-svg" alt="" aria-hidden="true" /></button>
-            <select id="arr-select" onchange="changeArrangement(this.value)" class="bg-dark-600 border border-gray-700 rounded-lg px-2 py-1.5 text-xs text-gray-300 outline-none max-w-[130px]"></select>
-            <button id="arr-default-pin" type="button" onclick="pinCurrentArrangementDefault()" aria-pressed="false" aria-label="Select an arrangement to make it the default" class="w-8 h-8 inline-flex items-center justify-center bg-dark-600 border border-gray-700 hover:bg-dark-500 rounded-lg text-xs text-gray-400 transition" title="Select an arrangement to make it the default">☆</button>
-            <input type="range" id="speed-slider" min="15" max="150" value="100" step="5" oninput="setSpeed(this.value/100)" class="w-20 accent-accent slider-input">
-            <span id="speed-label" class="text-xs text-gray-500 w-10">1.0x</span>
-            <span id="mastery-slider-label" class="text-xs text-gray-500 ml-1">Difficulty</span>
-            <input type="range" id="mastery-slider" min="0" max="100" value="100" step="5" oninput="setMastery(this.value)" class="w-20 accent-accent slider-input" title="Master difficulty — low = simpler chart, high = full" aria-labelledby="mastery-slider-label">
-            <span id="mastery-label" class="text-xs text-gray-500 w-10">100%</span>
-            <span id="player-av-offset-slider-label" class="text-xs text-gray-500 ml-1">A/V sync offset (ms)</span>
-            <input type="range" id="player-av-offset-slider" min="-1000" max="1000" value="0" step="1" oninput="setAvOffsetMs(this.value)" class="w-20 accent-accent slider-input" title="A/V sync offset (ms) — positive = audio plays ahead of visuals. [ and ] adjust ±10 ms (Shift = ±50). Double-click to reset." ondblclick="setAvOffsetMs(0)" aria-labelledby="player-av-offset-slider-label">
-            <span id="player-av-offset-label" class="text-xs text-gray-500 w-12 tabular-nums">+0ms</span>
-            <div id="mixer-control">
-                <div id="mixer-anchor" class="relative">
-                    <button id="btn-mixer" type="button" onclick="window.feedBack.audio.toggleMixer()" class="px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs text-gray-300 transition" aria-haspopup="true" aria-expanded="false" aria-controls="mixer-popover" title="Audio mixer">Mixer ▾</button>
-                    <div id="mixer-popover" class="hidden absolute right-0 bottom-full mb-2 z-50 bg-dark-700 border border-gray-800 rounded-xl shadow-xl" role="group" aria-label="Audio mixer"></div>
-                </div>
-            </div>
-            <button onclick="highway.toggleLyrics()" id="btn-lyrics" class="px-3 py-1.5 bg-purple-900/40 hover:bg-purple-900/60 rounded-lg text-xs text-purple-300 transition">Lyrics ✓</button>
-            <select id="quality-select" onchange="highway.setRenderScale(parseFloat(this.value))" class="bg-dark-600 border border-gray-700 rounded-lg px-2 py-1.5 text-xs text-gray-300 outline-none">
-                <option value="1">HD</option>
-                <option value="0.75">Medium</option>
-                <option value="0.5">Low</option>
-            </select>
-            <select id="min-scale-select" aria-label="Minimum auto resolution" onchange="highway.setMinRenderScale && highway.setMinRenderScale(parseFloat(this.value))" class="bg-dark-600 border border-gray-700 rounded-lg px-2 py-1.5 text-xs text-gray-300 outline-none" title="Minimum auto resolution — how far the highway may lower its resolution to hold the frame rate on heavy scenes. 'Full' disables auto-downscaling, but the Quality selector still caps the maximum (so it's only full resolution at Quality = HD).">
-                <option value="0.25">Min res: 25%</option>
-                <option value="0.5">Min res: 50%</option>
-                <option value="0.75">Min res: 75%</option>
-                <option value="1">Min res: Full</option>
-            </select>
-            <span id="viz-picker-label" class="text-xs text-gray-500 ml-1 sr-only">Visualization</span>
-            <select id="viz-picker" onchange="setViz(this.value)" class="bg-dark-600 border border-gray-700 rounded-lg px-2 py-1.5 text-xs text-gray-300 outline-none" aria-labelledby="viz-picker-label" title="Visualization">
-                <option value="auto">Auto (match arrangement)</option>
-                <option value="default">Classic 2D Highway</option>
-                <!-- Additional entries populated on load from /api/plugins (feedBack#36).
-                     The bundled 3D Highway plugin (plugins/highway_3d/) registers as
-                     `highway_3d` and is the default selection on fresh installs — see
-                     _populateVizPicker() in app.js. -->
-            </select>
-            <span class="text-gray-700 mx-1">|</span>
-            <button onclick="setLoopStart()" id="btn-loop-a" class="px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs text-gray-300 transition" title="Set loop start at current time">A</button>
-            <button onclick="setLoopEnd()" id="btn-loop-b" class="px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs text-gray-300 transition" title="Set loop end at current time">B</button>
-            <button onclick="saveCurrentLoop()" id="btn-loop-save" class="px-3 py-1.5 bg-dark-600 hover:bg-green-900/50 rounded-lg text-xs text-gray-300 transition hidden" title="Save this loop">Save</button>
-            <button onclick="clearLoop()" id="btn-loop-clear" class="px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs text-gray-500 transition hidden" title="Clear loop">✕</button>
-            <span id="loop-label" class="text-xs text-gray-600"></span>
-            <select id="saved-loops" onchange="loadSavedLoop(this.value)" class="bg-dark-600 border border-gray-700 rounded-lg px-2 py-1.5 text-xs text-gray-300 outline-none max-w-[160px] hidden">
-                <option value="">Saved Loops</option>
-            </select>
-            <button onclick="deleteSelectedLoop()" id="btn-loop-delete" class="px-2 py-1.5 bg-dark-600 hover:bg-red-900/50 rounded-lg text-xs text-gray-500 hover:text-red-400 transition hidden" title="Delete selected loop">✕</button>
-            <!-- Editor ⇄ 3D Highway round-trip. "Edit region" opens the Song Editor
-                 scrolled to the active loop (or the section at the playhead).
-                 "↩ Editor" returns to the editing position you came from; it only
-                 appears after a Loop-in-3D handoff. Both are hidden when the editor
-                 plugin isn't loaded (state managed by _updateEditRegionBtn). -->
-            <button onclick="editRegionInEditor()" id="btn-edit-region" class="px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs text-gray-300 transition hidden" title="Edit this region in the Song Editor">✎ Edit region</button>
-            <button onclick="returnToEditorFromHighway()" id="btn-return-editor" class="px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs text-gray-300 transition hidden" title="Return to the editor where you left off">↩ Editor</button>
-            <button onclick="showScreen('home')" class="ml-auto px-3 py-1.5 bg-dark-600 hover:bg-red-900/50 rounded-lg text-xs text-gray-400 hover:text-red-400 transition">✕ Close</button>
-        </div>
-        </div>
-    </div>
-
-    <script src="/static/highway.js"></script>
-    <script src="/static/vendor/lottie.min.js"></script>
-    <script src="/static/lottie-api.js"></script>
-    <script src="/static/app.js"></script>
-    <script src="/static/audio-mixer.js"></script>
-    <script src="/static/vendor/shepherd.min.js"></script>
-    <script src="/static/tour-engine.js"></script>
-    <script>
-        // Navbar scroll effect
-        window.addEventListener('scroll', () => {
-            const nav = document.getElementById('navbar');
-            if (window.scrollY > 50) {
-                nav.classList.add('bg-dark-900/80', 'backdrop-blur-lg', 'border-b', 'border-gray-800/50');
-            } else {
-                nav.classList.remove('bg-dark-900/80', 'backdrop-blur-lg', 'border-b', 'border-gray-800/50');
-            }
-        });
-    </script>
-</body>
-</html>

static/v3/badges.js

@@ -592,6 +592,8 @@
             sm.on('working-tuning-changed', () => renderInstrument());
         }
     }
-    if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', boot, { once: true });
+    // `defer` runs this at readyState 'interactive' — later scripts have not
+    // evaluated yet, so wait for DOMContentLoaded (see static/v3/index.html).
+    if (document.readyState !== 'complete') document.addEventListener('DOMContentLoaded', boot, { once: true });
     else boot();
 })();

static/v3/dashboard.js

@@ -271,6 +271,8 @@
         sm.on('v3:profile-updated', () => render());
     }
     function boot() { render(); }
-    if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', boot, { once: true });
+    // `defer` runs this at readyState 'interactive' — later scripts have not
+    // evaluated yet, so wait for DOMContentLoaded (see static/v3/index.html).
+    if (document.readyState !== 'complete') document.addEventListener('DOMContentLoaded', boot, { once: true });
     else boot();
 })();

static/v3/feedbarcade.js

@@ -273,7 +273,9 @@
         // the stage observer attaches.
         window.addEventListener('feedBack-minigames-ready', () => { ensureStageObserver(); refresh(); });
     }
-    if (document.readyState === 'loading') {
+    // `defer` runs this at readyState 'interactive' — later scripts have not
+    // evaluated yet, so wait for DOMContentLoaded (see static/v3/index.html).
+    if (document.readyState !== 'complete') {
         document.addEventListener('DOMContentLoaded', boot, { once: true });
     } else {
         boot();

static/v3/index.html

@@ -1,14 +1,15 @@
 <!DOCTYPE html>
 <!--
-  fee[dB]ack v0.3.0 shell (FEEDBACK_UI=v3 / GET /v3).
+  fee[dB]ack v0.3.0 shell — the app's only UI, served at `/` (and `/v3`, a
+  back-compat alias). The classic v2 shell it was forked from is deleted.
 
-  This is a re-chromed copy of the legacy static/index.html: the v0.3.0
-  sidebar + topbar replace the (hidden) legacy navbar, new #v3-* screens are
-  added, and all the legacy screens (#home library, #favorites, #settings,
-  #player, #audio, plugin nav containers) are kept verbatim so static/app.js
-  boots UNMODIFIED and the whole engine — player/highway, plugin loader,
-  capabilities, audio, library, settings — is reused as-is. Navigation is the
-  shared window.showScreen across both #v3-* and legacy/#plugin-* screens.
+  Originally a re-chromed copy of that shell: the v0.3.0 sidebar + topbar
+  replace the (hidden) legacy navbar, new #v3-* screens are added, and all the
+  legacy screens (#home library, #favorites, #settings, #player, #audio, plugin
+  nav containers) are kept verbatim so static/app.js boots UNMODIFIED and the
+  whole engine — player/highway, plugin loader, capabilities, audio, library,
+  settings — is reused as-is. Navigation is the shared window.showScreen across
+  both #v3-* and legacy/#plugin-* screens.
   See ~/Repositories/feedBack-feedback-v030/prompts/12-app-shell.md.
 -->
 <html lang="en" class="dark scroll-smooth">
@@ -98,23 +99,39 @@
     <link rel="stylesheet" href="/static/tour-engine.css">
     <!-- v0.3.0 shell styles (radial-gradient bg, custom scrollbars). -->
     <link rel="stylesheet" href="/static/v3/v3.css">
+    <!-- EVERY external script below is `defer`. Do not add a plain one.
+         `defer` and `type="module"` scripts share a single "execute after
+         parsing" list and run in DOCUMENT ORDER; a plain classic script runs
+         DURING parse, ahead of all of them. So one plain tag would jump the
+         queue — and once the capabilities become modules (they defer), a
+         still-plain app.js would run BEFORE the bus exists and die on its
+         top-level `window.feedBack.on(...)` calls. Keeping every tag deferred
+         is what preserves this file's order through the ES-module migration.
+         Enforced by test_every_external_script_defers_so_document_order_is_execution_order.
+
+         The scripts themselves boot on DOMContentLoaded, which fires only after
+         all of the above have evaluated — that is what lets a script's boot()
+         use a global another script defines further down this list (there are
+         ~43 such forward references). Their readyState guards therefore treat
+         'interactive' as not-ready; see the note at each one. -->
+
     <!-- Diagnostics console capture must wrap console.* before any other
          script logs anything; load it as early as possible. See
          docs/diagnostics-bundle-spec.md (feedBack#166). -->
-    <script src="/static/diagnostics.js"></script>
-    <script src="/static/capabilities.js"></script>
-    <script src="/static/capabilities/library.js"></script>
-    <script src="/static/capabilities/tuning.js"></script>
-    <script src="/static/capabilities/working-tuning.js"></script>
-    <script src="/static/capabilities/audio-session.js"></script>
-    <script src="/static/capabilities/audio-effects.js"></script>
-    <script src="/static/capabilities/playback.js"></script>
+    <script defer src="/static/diagnostics.js"></script>
+    <script type="module" src="/static/capabilities.js"></script>
+    <script type="module" src="/static/capabilities/library.js"></script>
+    <script type="module" src="/static/capabilities/tuning.js"></script>
+    <script type="module" src="/static/capabilities/working-tuning.js"></script>
+    <script type="module" src="/static/capabilities/audio-session.js"></script>
+    <script type="module" src="/static/capabilities/audio-effects.js"></script>
+    <script type="module" src="/static/capabilities/playback.js"></script>
     <!-- fee[dB]ack v0.3.0: ui.library-card-injection capability (plugin card actions). -->
-    <script src="/static/capabilities/library-card-actions.js"></script>
-    <script src="/static/capabilities/visualization.js"></script>
-    <script src="/static/capabilities/note-detection.js"></script>
-    <script src="/static/capabilities/midi-input.js"></script>
-    <script src="/static/capabilities/interface-scale.js"></script>
+    <script type="module" src="/static/capabilities/library-card-actions.js"></script>
+    <script type="module" src="/static/capabilities/visualization.js"></script>
+    <script type="module" src="/static/capabilities/note-detection.js"></script>
+    <script type="module" src="/static/capabilities/midi-input.js"></script>
+    <script type="module" src="/static/capabilities/interface-scale.js"></script>
 </head>
 <body class="h-screen flex overflow-hidden bg-fb-sidebar text-fb-text font-display">
 
@@ -1224,64 +1241,64 @@
     </main>
     <!-- /#v3-main -->
 
-    <script src="/static/highway.js"></script>
-    <script src="/static/vendor/lottie.min.js"></script>
-    <script src="/static/lottie-api.js"></script>
-    <script src="/static/app.js"></script>
-    <script src="/static/audio-mixer.js"></script>
-    <script src="/static/vendor/shepherd.min.js"></script>
-    <script src="/static/tour-engine.js"></script>
+    <script defer src="/static/highway.js"></script>
+    <script defer src="/static/vendor/lottie.min.js"></script>
+    <script defer src="/static/lottie-api.js"></script>
+    <script defer src="/static/app.js"></script>
+    <script defer src="/static/audio-mixer.js"></script>
+    <script defer src="/static/vendor/shepherd.min.js"></script>
+    <script defer src="/static/tour-engine.js"></script>
     <!-- fee[dB]ack v0.3.0 shell: brand helper, then the shell (sidebar/topbar/
          routing). Loaded after app.js/audio-mixer so window.showScreen and
          window.feedBack(.audio) exist; dashboard.js is filled in prompt 13. -->
-    <script src="/static/v3/brand.js"></script>
-    <script src="/static/v3/shell.js"></script>
+    <script defer src="/static/v3/brand.js"></script>
+    <script defer src="/static/v3/shell.js"></script>
     <!-- Progression (spec 010): theme-core before profile.js so the equipped
          theme/avatar frame apply with the first badge render; progression-core
          registers the `progression` capability owner + window.v3Progression. -->
-    <script src="/static/v3/theme-core.js"></script>
-    <script src="/static/v3/progression-core.js"></script>
-    <script src="/static/v3/notifications.js"></script>
-    <script src="/static/v3/profile.js"></script>
-    <script src="/static/v3/progress.js"></script>
-    <script src="/static/v3/shop.js"></script>
-    <script src="/static/v3/tuner-core.js"></script>
-    <script src="/static/v3/badges.js"></script>
-    <script src="/static/v3/stats-recorder.js"></script>
-    <script src="/static/v3/live-performance-hud.js"></script>
-    <script src="/static/v3/scoreboard-pref.js"></script>
-    <script src="/static/v3/venue-viz.js"></script>
-    <script src="/static/v3/venue-instrument-pov.js"></script>
+    <script defer src="/static/v3/theme-core.js"></script>
+    <script defer src="/static/v3/progression-core.js"></script>
+    <script defer src="/static/v3/notifications.js"></script>
+    <script defer src="/static/v3/profile.js"></script>
+    <script defer src="/static/v3/progress.js"></script>
+    <script defer src="/static/v3/shop.js"></script>
+    <script defer src="/static/v3/tuner-core.js"></script>
+    <script defer src="/static/v3/badges.js"></script>
+    <script defer src="/static/v3/stats-recorder.js"></script>
+    <script defer src="/static/v3/live-performance-hud.js"></script>
+    <script defer src="/static/v3/scoreboard-pref.js"></script>
+    <script defer src="/static/v3/venue-viz.js"></script>
+    <script defer src="/static/v3/venue-instrument-pov.js"></script>
     <!-- venue-mood-fx must load before venue-scene-3d: the scene bridge reads
          window.v3VenueMoodFx.getMotion() synchronously at boot when the saved
          viz is 'venue'; loading it after falls back to 'subtle' and ignores a
          saved 'off'/'full' motion preference on first paint. -->
-    <script src="/static/v3/venue-mood-fx.js"></script>
-    <script src="/static/v3/venue-scene-3d.js"></script>
-    <script src="/static/v3/playlists.js"></script>
-    <script src="/static/v3/audio-routing.js"></script>
-    <script src="/static/v3/live-guitar-tone-source.js"></script>
-    <script src="/static/v3/pedal-cables.js"></script>
-    <script src="/static/v3/plugins-page.js"></script>
-    <script src="/static/v3/card-actions-core.js"></script>
+    <script defer src="/static/v3/venue-mood-fx.js"></script>
+    <script defer src="/static/v3/venue-scene-3d.js"></script>
+    <script defer src="/static/v3/playlists.js"></script>
+    <script defer src="/static/v3/audio-routing.js"></script>
+    <script defer src="/static/v3/live-guitar-tone-source.js"></script>
+    <script defer src="/static/v3/pedal-cables.js"></script>
+    <script defer src="/static/v3/plugins-page.js"></script>
+    <script defer src="/static/v3/card-actions-core.js"></script>
     <!-- Before songs.js: the songs toolbar calls the match-review chip hook
          on build, so the module must already be registered. -->
-    <script src="/static/v3/match-review.js"></script>
+    <script defer src="/static/v3/match-review.js"></script>
     <!-- Before songs.js: the drawer art click + card ⋮ "Change cover…" open
          the cover picker (window.__fbOpenImagePicker). -->
-    <script src="/static/v3/image-picker.js"></script>
-    <script src="/static/v3/songs.js"></script>
-    <script src="/static/v3/lessons.js"></script>
-    <script src="/static/v3/dashboard.js"></script>
-    <script src="/static/v3/settings.js"></script>
-    <script src="/static/v3/interface-size-ui.js"></script>
+    <script defer src="/static/v3/image-picker.js"></script>
+    <script defer src="/static/v3/songs.js"></script>
+    <script defer src="/static/v3/lessons.js"></script>
+    <script defer src="/static/v3/dashboard.js"></script>
+    <script defer src="/static/v3/settings.js"></script>
+    <script defer src="/static/v3/interface-size-ui.js"></script>
     <!-- First-run home tour: spotlights the home cards via the shared tour
          engine (tour-engine.js, loaded above). Auto-runs once after onboarding
          (triggered from profile.js finish()); replayable from the "?" menu. -->
-    <script src="/static/v3/onboarding-tour.js"></script>
-    <script src="/static/v3/interface-size-nudge.js"></script>
-    <script src="/static/v3/feedbarcade.js"></script>
-    <script src="/static/v3/player-chrome.js"></script>
+    <script defer src="/static/v3/onboarding-tour.js"></script>
+    <script defer src="/static/v3/interface-size-nudge.js"></script>
+    <script defer src="/static/v3/feedbarcade.js"></script>
+    <script defer src="/static/v3/player-chrome.js"></script>
     <script>
         // Navbar scroll effect
         window.addEventListener('scroll', () => {

static/v3/interface-size-nudge.js

@@ -71,7 +71,9 @@
         setTimeout(maybeNudge, 4000);
     }
 
-    if (document.readyState === 'loading') {
+    // `defer` runs this at readyState 'interactive' — later scripts have not
+    // evaluated yet, so wait for DOMContentLoaded (see static/v3/index.html).
+    if (document.readyState !== 'complete') {
         document.addEventListener('DOMContentLoaded', start, { once: true });
     } else {
         start();

static/v3/interface-size-ui.js

@@ -45,7 +45,9 @@
     // Settings markup is static, but re-sync when settings.js signals it wired.
     document.addEventListener('v3:settings-rendered', function () { sync(); });
 
-    if (document.readyState === 'loading') {
+    // `defer` runs this at readyState 'interactive' — later scripts have not
+    // evaluated yet, so wait for DOMContentLoaded (see static/v3/index.html).
+    if (document.readyState !== 'complete') {
         document.addEventListener('DOMContentLoaded', function () { sync(); }, { once: true });
     } else {
         sync();

static/v3/live-guitar-tone-source.js

@@ -94,7 +94,9 @@
     }
 
     if (typeof document !== 'undefined') {
-        if (document.readyState === 'loading') {
+        // `defer` runs this at readyState 'interactive' — later scripts have not
+        // evaluated yet, so wait for DOMContentLoaded (see static/v3/index.html).
+        if (document.readyState !== 'complete') {
             document.addEventListener('DOMContentLoaded', init);
         } else {
             init();

static/v3/live-performance-hud.js

@@ -303,7 +303,9 @@
             const sm = root && root.feedBack;
             if (sm) bindRuntime(sm);
         };
-        if (document.readyState === 'loading') {
+        // `defer` runs this at readyState 'interactive' — later scripts have not
+        // evaluated yet, so wait for DOMContentLoaded (see static/v3/index.html).
+        if (document.readyState !== 'complete') {
             document.addEventListener('DOMContentLoaded', boot);
         } else {
             boot();

static/v3/match-review.js

@@ -913,7 +913,9 @@
         });
     }
 
-    if (document.readyState === 'loading') {
+    // `defer` runs this at readyState 'interactive' — later scripts have not
+    // evaluated yet, so wait for DOMContentLoaded (see static/v3/index.html).
+    if (document.readyState !== 'complete') {
         document.addEventListener('DOMContentLoaded', () => {
             wireSettingsCard();
             wireScreenTeardown();

static/v3/player-chrome.js

@@ -362,6 +362,8 @@
         syncActivation();
     }
 
-    if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', init);
+    // `defer` runs this at readyState 'interactive' — later scripts have not
+    // evaluated yet, so wait for DOMContentLoaded (see static/v3/index.html).
+    if (document.readyState !== 'complete') document.addEventListener('DOMContentLoaded', init);
     else init();
 })();

static/v3/playlists.js

@@ -440,6 +440,8 @@
         });
     }
     function boot() { renderPlaylists(); renderSaved(); }
-    if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', boot, { once: true });
+    // `defer` runs this at readyState 'interactive' — later scripts have not
+    // evaluated yet, so wait for DOMContentLoaded (see static/v3/index.html).
+    if (document.readyState !== 'complete') document.addEventListener('DOMContentLoaded', boot, { once: true });
     else boot();
 })();

static/v3/plugins-page.js

@@ -579,6 +579,8 @@
     }, { passive: true });
 
     function boot() { render(); }
-    if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', boot, { once: true });
+    // `defer` runs this at readyState 'interactive' — later scripts have not
+    // evaluated yet, so wait for DOMContentLoaded (see static/v3/index.html).
+    if (document.readyState !== 'complete') document.addEventListener('DOMContentLoaded', boot, { once: true });
     else boot();
 })();

static/v3/profile.js

@@ -792,7 +792,9 @@
             });
         }
     }
-    if (document.readyState === 'loading') {
+    // `defer` runs this at readyState 'interactive' — later scripts have not
+    // evaluated yet, so wait for DOMContentLoaded (see static/v3/index.html).
+    if (document.readyState !== 'complete') {
         document.addEventListener('DOMContentLoaded', boot, { once: true });
     } else {
         boot();

static/v3/progress.js

@@ -320,7 +320,9 @@
             });
         }
     }
-    if (document.readyState === 'loading') {
+    // `defer` runs this at readyState 'interactive' — later scripts have not
+    // evaluated yet, so wait for DOMContentLoaded (see static/v3/index.html).
+    if (document.readyState !== 'complete') {
         document.addEventListener('DOMContentLoaded', boot, { once: true });
     } else {
         boot();

static/v3/progression-core.js

@@ -241,7 +241,9 @@
     };
 
     _registerOwner();
-    if (document.readyState === 'loading') {
+    // `defer` runs this at readyState 'interactive' — later scripts have not
+    // evaluated yet, so wait for DOMContentLoaded (see static/v3/index.html).
+    if (document.readyState !== 'complete') {
         document.addEventListener('DOMContentLoaded', () => { refresh(); }, { once: true });
     } else {
         refresh();

static/v3/settings.js

@@ -200,7 +200,9 @@
         });
     }
 
-    if (document.readyState === 'loading') {
+    // `defer` runs this at readyState 'interactive' — later scripts have not
+    // evaluated yet, so wait for DOMContentLoaded (see static/v3/index.html).
+    if (document.readyState !== 'complete') {
         document.addEventListener('DOMContentLoaded', init, { once: true });
     } else {
         init();

static/v3/shell.js

@@ -399,7 +399,9 @@
         setTimeout(refreshHomeTitle, 700);
     }
 
-    if (document.readyState === 'loading') {
+    // `defer` runs this at readyState 'interactive' — later scripts have not
+    // evaluated yet, so wait for DOMContentLoaded (see static/v3/index.html).
+    if (document.readyState !== 'complete') {
         document.addEventListener('DOMContentLoaded', boot, { once: true });
     } else {
         boot();

static/v3/shop.js

@@ -203,7 +203,9 @@
             });
         }
     }
-    if (document.readyState === 'loading') {
+    // `defer` runs this at readyState 'interactive' — later scripts have not
+    // evaluated yet, so wait for DOMContentLoaded (see static/v3/index.html).
+    if (document.readyState !== 'complete') {
         document.addEventListener('DOMContentLoaded', boot, { once: true });
     } else {
         boot();

static/v3/venue-mood-fx.js

@@ -511,7 +511,9 @@
             const sm = root && root.feedBack;
             if (sm) bindRuntime(sm);
         };
-        if (document.readyState === 'loading') {
+        // `defer` runs this at readyState 'interactive' — later scripts have not
+        // evaluated yet, so wait for DOMContentLoaded (see static/v3/index.html).
+        if (document.readyState !== 'complete') {
             document.addEventListener('DOMContentLoaded', boot);
         } else {
             boot();

static/v3/venue-scene-3d.js

@@ -242,7 +242,9 @@
 
     if (typeof document !== 'undefined') {
         const boot = () => bindRuntime();
-        if (document.readyState === 'loading') {
+        // `defer` runs this at readyState 'interactive' — later scripts have not
+        // evaluated yet, so wait for DOMContentLoaded (see static/v3/index.html).
+        if (document.readyState !== 'complete') {
             document.addEventListener('DOMContentLoaded', boot);
         } else {
             boot();

tailwind.config.js

@@ -13,9 +13,9 @@
 module.exports = {
     content: [
         './static/**/*.{html,js}',
-        // fee[dB]ack v0.3.0 shell + screens (additive, behind FEEDBACK_UI=v3).
-        // Subsumed by the recursive ./static/** glob above, but listed
-        // explicitly so the v3 tree's Tailwind coverage is obvious.
+        // fee[dB]ack v0.3.0 shell + screens — the only UI since the classic v2
+        // shell was removed. Subsumed by the recursive ./static/** glob above,
+        // but listed explicitly so the v3 tree's Tailwind coverage is obvious.
         './static/v3/**/*.{html,js}',
         // One recursive plugin glob subsumes the previous four narrow ones
         // (static/**, screen.js, settings.html, *.html) and additionally

tests/conftest.py

@@ -9,6 +9,36 @@ import structlog
 _LOGGING_NAMES = ("feedBack", "uvicorn", "uvicorn.error", "uvicorn.access")
 
 
+@pytest.fixture(autouse=True)
+def _reset_enrichment_state():
+    """Reset the enrichment worker's process-global state between tests.
+
+    The `server` fixtures pop-and-reimport `server`, but `lib/enrichment.py`
+    (which now owns the worker) stays imported for the whole session, so its
+    module globals — the cancel Event, the status dict, the caches — would
+    otherwise leak across tests. A test that set `_enrich_cancel` (or a stale
+    `running` status) could silently short-circuit a later direct
+    `_background_enrich()` call. Clear it up front so each test starts clean.
+    """
+    try:
+        import enrichment
+    except ImportError:
+        yield
+        return
+    enrichment._enrich_cancel.clear()
+    enrichment._enrich_pending_pass = False
+    enrichment._enrich_status.update(
+        {"running": False, "processed": 0, "last_pass_at": None,
+         "total": 0, "matched": 0, "current": None})
+    enrichment._enrich_last_fetch = 0.0
+    enrichment._artist_alias_cache.clear()
+    # _caa_index_locks is deliberately left alone: it's guarded by
+    # _caa_index_locks_guard, so clearing it here (unlocked) would race a
+    # still-alive worker thread, and its entries are stateless per-release
+    # mutexes that don't leak test state anyway.
+    yield
+
+
 @pytest.fixture()
 def isolate_logging():
     """Restore feedBack / uvicorn logger state after each test.

tests/js/alpha_warning_banner.test.js

@@ -1,5 +1,5 @@
 // Verify the alpha-build heads-up banner: markup is present in
-// static/index.html and `_updateAlphaWarningBanner(version)` in
+// static/v3/index.html and `_updateAlphaWarningBanner(version)` in
 // static/app.js toggles its visibility correctly per the version string.
 
 const { test } = require('node:test');
@@ -8,7 +8,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const vm = require('node:vm');
 
-const INDEX_HTML = path.join(__dirname, '..', '..', 'static', 'index.html');
+const INDEX_HTML = path.join(__dirname, '..', '..', 'static', 'v3', 'index.html');
 const APP_JS = path.join(__dirname, '..', '..', 'static', 'app.js');
 
 test('index.html ships the alpha-warning banner inside the library section', () => {

tests/js/beats_loaded.test.js

@@ -42,7 +42,7 @@ test('beats:loaded emit is wired into the WS beats case', () => {
     );
     assert.match(
         block,
-        /count:\s*beats\.length/,
+        /count:\s*hwState\.beats\.length/,
         'beats:loaded payload must include count = beats.length',
     );
 });

tests/js/handshapes_pipeline.test.js

@@ -33,7 +33,7 @@ test('handshapes WS case accumulates incoming chunks into handShapes', () => {
     const block = getCaseBlock(src, 'handshapes');
     assert.match(
         block,
-        /handShapes\s*=\s*handShapes\.concat\(\s*msg\.data\s*\)/,
+        /hwState\.handShapes\s*=\s*hwState\.handShapes\.concat\(\s*msg\.data\s*\)/,
         'handshapes case must concat msg.data into the handShapes accumulator',
     );
 });
@@ -62,7 +62,7 @@ test('bundle exposes handShapes to renderers with flat-list fallback', () => {
     const src = fs.readFileSync(HIGHWAY_JS, 'utf8');
     assert.match(
         src,
-        /\bhandShapes\s*[:=]\s*\([^)]*_filteredHandShapes[^)]*\)\s*\?\s*_filteredHandShapes\s*:\s*handShapes\b/,
+        /\bhandShapes\s*[:=]\s*\([^)]*hwState\._filteredHandShapes[^)]*\)\s*\?\s*hwState\._filteredHandShapes\s*:\s*hwState\.handShapes\b/,
         'bundle must expose handShapes with the _filteredHandShapes-vs-handShapes ternary fallback',
     );
 });

tests/js/highway_3d_lefty.test.js

@@ -20,7 +20,7 @@ function src(file) {
 test('highway renderer bundles surface the core lefty flag', () => {
     assert.match(
         src(HIGHWAY_JS),
-        /lefty\s*[:=]\s*_lefty/,
+        /lefty\s*[:=]\s*hwState\._lefty/,
         'custom renderer bundles must include lefty: _lefty',
     );
 });

tests/js/highway_3d_smooth_clock_pause.test.js

@@ -49,12 +49,12 @@ test('core _makeBundle exposes isPlaying derived from the chart-clock anchor', (
     // within the interp cap.
     assert.match(
         fn,
-        /isPlaying\s*[:=]\s*!Number\.isNaN\(\s*_chartAnchorPerfNow\s*\)/,
+        /isPlaying\s*[:=]\s*!Number\.isNaN\(\s*hwState\._chartAnchorPerfNow\s*\)/,
         'isPlaying must gate on a live anchor (_chartAnchorPerfNow not NaN)',
     );
     assert.match(
         fn,
-        /_chartLastAdvanceAt\s*\)\s*<=\s*_CHART_MAX_INTERP_MS/,
+        /hwState\._chartLastAdvanceAt\s*\)\s*<=\s*_CHART_MAX_INTERP_MS/,
         'isPlaying must require the clock advanced within _CHART_MAX_INTERP_MS',
     );
 });

tests/js/highway_adaptive_scale.test.js

@@ -29,7 +29,7 @@ function extractBlock(src, signature) {
 
 test('highway declares adaptive-scale state with a floor', () => {
     const src = fs.readFileSync(highwayJs, 'utf8');
-    assert.match(src, /let\s+_autoScale\s*=\s*1/, 'missing _autoScale multiplier');
+    assert.match(src, /hwState\._autoScale\s*=\s*1/, 'missing _autoScale multiplier');
     assert.match(src, /const\s+_AUTO_SCALE_MIN\s*=\s*0?\.25/, 'missing _AUTO_SCALE_MIN floor (0.25)');
     assert.match(src, /const\s+_DRAW_BUDGET_HI_MS\s*=\s*\d+/, 'missing high draw budget');
     assert.match(src, /const\s+_DRAW_BUDGET_LO_MS\s*=\s*\d+/, 'missing low draw budget');
@@ -49,18 +49,18 @@ test('_effectiveRenderScale clamps user ceiling * auto factor to [MIN, 1]', () =
 test('min render scale floor is user-configurable + exposed on the api (#654)', () => {
     const src = fs.readFileSync(highwayJs, 'utf8');
     // Hard floor constant kept; configurable floor read from localStorage.
-    assert.match(src, /let\s+_autoScaleMin\s*=/, 'missing configurable _autoScaleMin');
+    assert.match(src, /hwState\._autoScaleMin\s*=/, 'missing configurable _autoScaleMin');
     assert.match(src, /localStorage\.getItem\('highwayMinRenderScale'\)/,
         'configurable floor must load from localStorage.highwayMinRenderScale');
     assert.match(src, /setMinRenderScale\(/, 'api.setMinRenderScale missing');
-    assert.match(src, /getMinRenderScale\(\)\s*\{\s*return\s+_autoScaleMin/, 'api.getMinRenderScale missing');
+    assert.match(src, /getMinRenderScale\(\)\s*\{\s*return\s+hwState\._autoScaleMin/, 'api.getMinRenderScale missing');
     // Floor is clamped to the user ceiling so it can never exceed the manual cap.
     const eff = extractBlock(src, 'function _effectiveRenderScale()');
-    assert.match(eff, /Math\.min\(\s*_autoScaleMin\s*,\s*user\s*\)/,
+    assert.match(eff, /Math\.min\(\s*hwState\._autoScaleMin\s*,\s*user\s*\)/,
         'effective scale must clamp the floor to the user ceiling');
     // _adaptRenderScale must cap the lo bound at 1 so _autoScale stays in [_,1].
     const adapt = extractBlock(src, 'function _adaptRenderScale(');
-    assert.match(adapt, /Math\.min\(\s*1\s*,\s*_autoScaleMin\s*\/\s*_renderScale\s*\)/,
+    assert.match(adapt, /Math\.min\(\s*1\s*,\s*hwState\._autoScaleMin\s*\/\s*hwState\._renderScale\s*\)/,
         'lo bound must be capped at 1 to keep _autoScale a [0,1] multiplier');
 });
 

tests/js/highway_chord_render_cache.test.js

@@ -34,9 +34,9 @@ test('_ensureChordRenderCache keys off src, _inverted, AND chordTemplates', () =
     const neqEither = (a, b) => new RegExp(
         `\\b${a}\\b\\s*!==\\s*\\b${b}\\b|\\b${b}\\b\\s*!==\\s*\\b${a}\\b`
     );
-    assert.match(src, eqEither('_chordRenderCacheSrc', 'src'), 'cache must key on src');
-    assert.match(src, eqEither('_chordRenderCacheInverted', '_inverted'), 'cache must key on _inverted');
-    assert.match(src, neqEither('_chordRenderCacheTemplates', 'chordTemplates'),
+    assert.match(src, eqEither('hwState\\._chordRenderCacheSrc', 'src'), 'cache must key on src');
+    assert.match(src, eqEither('hwState\\._chordRenderCacheInverted', 'hwState\\._inverted'), 'cache must key on _inverted');
+    assert.match(src, neqEither('hwState\\._chordRenderCacheTemplates', 'hwState\\.chordTemplates'),
         'cache must key on chordTemplates (detected via !== for change-flag)');
 });
 
@@ -50,9 +50,9 @@ test('chordTemplates change resets fretline preview and frame-mismatch warner',
     // block inside the `if (templatesChanged) { … }` branch (e.g. an
     // inner conditional reset) doesn't break the match by introducing
     // a `}` before the symbol we're checking for.
-    assert.match(src, /if\s*\(\s*templatesChanged\s*\)\s*\{[\s\S]*?_chordFretLineNotes\s*=\s*\[\][\s\S]*?\}/,
+    assert.match(src, /if\s*\(\s*templatesChanged\s*\)\s*\{[\s\S]*?hwState\._chordFretLineNotes\s*=\s*\[\][\s\S]*?\}/,
         'templatesChanged branch must reset _chordFretLineNotes');
-    assert.match(src, /if\s*\(\s*templatesChanged\s*\)\s*\{[\s\S]*?_lastChordOnFretLine\s*=\s*null[\s\S]*?\}/,
+    assert.match(src, /if\s*\(\s*templatesChanged\s*\)\s*\{[\s\S]*?hwState\._lastChordOnFretLine\s*=\s*null[\s\S]*?\}/,
         'templatesChanged branch must null _lastChordOnFretLine');
     assert.match(src, /if\s*\(\s*templatesChanged\s*\)\s*\{[\s\S]*?_frameMismatchWarned\.clear\(\)[\s\S]*?\}/,
         'templatesChanged branch must clear _frameMismatchWarned');

tests/js/highway_filtered_notes.test.js

@@ -23,7 +23,7 @@ test('getFilteredNotes falls through to notes when _filteredNotes is null', () =
     const src = fs.readFileSync(highwayJs, 'utf8');
     assert.match(
         src,
-        /getFilteredNotes\s*\(\s*\)\s*\{[^}]*_filteredNotes[^}]*:\s*notes/,
+        /getFilteredNotes\s*\(\s*\)\s*\{[^}]*_filteredNotes[^}]*:\s*hwState\.notes/,
         'getFilteredNotes must return notes as fallback',
     );
 });
@@ -41,7 +41,7 @@ test('getFilteredChords falls through to chords when _filteredChords is null', (
     const src = fs.readFileSync(highwayJs, 'utf8');
     assert.match(
         src,
-        /getFilteredChords\s*\(\s*\)\s*\{[^}]*_filteredChords[^}]*:\s*chords/,
+        /getFilteredChords\s*\(\s*\)\s*\{[^}]*_filteredChords[^}]*:\s*hwState\.chords/,
         'getFilteredChords must return chords as fallback',
     );
 });

tests/js/highway_monotonic_clock.test.js

@@ -35,7 +35,10 @@ function extractBlock(src, signature) {
 // + getTime methods so behavioral tests can exercise the real
 // implementation in isolation.
 function buildClockSandbox(perfNowImpl) {
-    const sandbox = {
+    // The lifted per-instance state now lives on `hwState` (the R3c H lift);
+    // the extracted setTime/getTime bodies reference hwState.<slot>. The const
+    // _CHART_MAX_INTERP_MS was NOT lifted, so it stays a top-level global here.
+    const hwState = {
         chartTime: 0,
         currentTime: 0,
         avOffsetSec: 0,
@@ -50,6 +53,9 @@ function buildClockSandbox(perfNowImpl) {
         _chartAnchorPerfNow: NaN,
         _chartLastAdvanceAt: 0,
         _chartObservedRate: 1,
+    };
+    const sandbox = {
+        hwState,
         _CHART_MAX_INTERP_MS: 100,
         performance: { now: perfNowImpl },
     };
@@ -72,10 +78,10 @@ test('highway declares chart anchor + stall-detect + rate state', () => {
     // particular MUST start as NaN, not 0, otherwise setTime(0) on the
     // very first 60 Hz tick fails the `t !== _chartAnchorAudioT` check
     // and never re-anchors, leaving the clock uninitialized.
-    assert.match(src, /let\s+_chartAnchorAudioT\s*=\s*NaN/, 'missing _chartAnchorAudioT (NaN sentinel)');
-    assert.match(src, /let\s+_chartAnchorPerfNow\s*=\s*NaN/, 'missing _chartAnchorPerfNow (NaN sentinel)');
-    assert.match(src, /let\s+_chartLastAdvanceAt\s*=\s*0/, 'missing _chartLastAdvanceAt (pause detection)');
-    assert.match(src, /let\s+_chartObservedRate\s*=\s*1/, 'missing _chartObservedRate (playback rate awareness)');
+    assert.match(src, /hwState\._chartAnchorAudioT\s*=\s*NaN/, 'missing _chartAnchorAudioT (NaN sentinel)');
+    assert.match(src, /hwState\._chartAnchorPerfNow\s*=\s*NaN/, 'missing _chartAnchorPerfNow (NaN sentinel)');
+    assert.match(src, /hwState\._chartLastAdvanceAt\s*=\s*0/, 'missing _chartLastAdvanceAt (pause detection)');
+    assert.match(src, /hwState\._chartObservedRate\s*=\s*1/, 'missing _chartObservedRate (playback rate awareness)');
     assert.match(src, /const\s+_CHART_MAX_INTERP_MS\s*=\s*100/, 'missing _CHART_MAX_INTERP_MS cap');
 });
 
@@ -86,7 +92,7 @@ test('getTime scales interpolation by _chartObservedRate (speed-slider safe)', (
     const slice = m[0];
     assert.match(
         slice,
-        /_chartObservedRate\s*\*\s*elapsedMs/,
+        /hwState\._chartObservedRate\s*\*\s*elapsedMs/,
         'getTime must scale interpolation by observed rate so audio.playbackRate != 1 stays accurate',
     );
 });
@@ -100,12 +106,12 @@ test('setTime re-anchors and updates _chartLastAdvanceAt only when t actually ch
     // The implementation may capture performance.now() into a local
     // (e.g. newPerfNow) and assign that to both fields; accept either
     // direct or via-local writes.
-    const m = src.match(/if\s*\(\s*t\s*!==\s*_chartAnchorAudioT\s*\)\s*\{[\s\S]+?\}\s*\},/);
+    const m = src.match(/if\s*\(\s*t\s*!==\s*hwState\._chartAnchorAudioT\s*\)\s*\{[\s\S]+?\}\s*\},/);
     assert.ok(m, 'if (t !== _chartAnchorAudioT) block not found inside setTime');
     const block = m[0];
-    assert.match(block, /_chartAnchorAudioT\s*=\s*t/, 'must assign _chartAnchorAudioT = t');
-    assert.match(block, /_chartAnchorPerfNow\s*=/, 'must assign _chartAnchorPerfNow');
-    assert.match(block, /_chartLastAdvanceAt\s*=/, 'must assign _chartLastAdvanceAt');
+    assert.match(block, /hwState\._chartAnchorAudioT\s*=\s*t/, 'must assign _chartAnchorAudioT = t');
+    assert.match(block, /hwState\._chartAnchorPerfNow\s*=/, 'must assign _chartAnchorPerfNow');
+    assert.match(block, /hwState\._chartLastAdvanceAt\s*=/, 'must assign _chartLastAdvanceAt');
 });
 
 test('getTime falls back to chartTime when audio has stalled (paused)', () => {
@@ -119,7 +125,7 @@ test('getTime falls back to chartTime when audio has stalled (paused)', () => {
     // Must check stall-since-last-advance against the cap.
     assert.match(
         slice,
-        /nowP\s*-\s*_chartLastAdvanceAt\s*>\s*_CHART_MAX_INTERP_MS/,
+        /nowP\s*-\s*hwState\._chartLastAdvanceAt\s*>\s*_CHART_MAX_INTERP_MS/,
         'getTime must short-circuit when audio has stalled past the cap',
     );
     // Must interpolate when active.
@@ -127,7 +133,7 @@ test('getTime falls back to chartTime when audio has stalled (paused)', () => {
     // Rate-scaled formula: _chartAnchorAudioT + (_chartObservedRate * elapsedMs) / 1000
     assert.match(
         slice,
-        /_chartAnchorAudioT\s*\+\s*\(\s*_chartObservedRate\s*\*\s*elapsedMs\s*\)\s*\/\s*1000/,
+        /_chartAnchorAudioT\s*\+\s*\(\s*hwState\._chartObservedRate\s*\*\s*elapsedMs\s*\)\s*\/\s*1000/,
         'getTime must compute anchor + rate-scaled elapsed during play',
     );
 });
@@ -138,10 +144,10 @@ test('api.stop() clears the chart anchor state so re-init starts fresh', () => {
     // the actual stop() body — a fixed-size slice would falsely match
     // resets that landed in an adjacent method.
     const stopBlock = extractBlock(src, 'stop() {');
-    assert.match(stopBlock, /_chartAnchorAudioT\s*=\s*NaN/, 'stop() must reset _chartAnchorAudioT to the NaN sentinel');
-    assert.match(stopBlock, /_chartAnchorPerfNow\s*=\s*NaN/, 'stop() must reset _chartAnchorPerfNow to the NaN sentinel');
-    assert.match(stopBlock, /_chartLastAdvanceAt\s*=\s*0/, 'stop() must reset _chartLastAdvanceAt');
-    assert.match(stopBlock, /_chartObservedRate\s*=\s*1/, 'stop() must reset _chartObservedRate to 1x');
+    assert.match(stopBlock, /hwState\._chartAnchorAudioT\s*=\s*NaN/, 'stop() must reset _chartAnchorAudioT to the NaN sentinel');
+    assert.match(stopBlock, /hwState\._chartAnchorPerfNow\s*=\s*NaN/, 'stop() must reset _chartAnchorPerfNow to the NaN sentinel');
+    assert.match(stopBlock, /hwState\._chartLastAdvanceAt\s*=\s*0/, 'stop() must reset _chartLastAdvanceAt');
+    assert.match(stopBlock, /hwState\._chartObservedRate\s*=\s*1/, 'stop() must reset _chartObservedRate to 1x');
 });
 
 // ── Behavioral tests (run extracted setTime/getTime in vm sandbox) ──────
@@ -195,12 +201,12 @@ test('behavior: seek discontinuity resets observed rate to 1x', () => {
     sb.setTime(10);
     now = 50;
     sb.setTime(10.025); // observed rate ≈ 0.5
-    assert.ok(Math.abs(sb._chartObservedRate - 0.5) < 0.001, `prior segment must measure ≈0.5, got ${sb._chartObservedRate}`);
+    assert.ok(Math.abs(sb.hwState._chartObservedRate - 0.5) < 0.001, `prior segment must measure ≈0.5, got ${sb.hwState._chartObservedRate}`);
     // Seek: large t jump in same perf delta — observed-rate clamp
     // rejects this segment, resets to 1.
     now = 70;
     sb.setTime(120); // dPerf=20ms, dT=110s → observed=5500 (out of clamp)
-    assert.equal(sb._chartObservedRate, 1, 'seek must reset rate to 1x');
+    assert.equal(sb.hwState._chartObservedRate, 1, 'seek must reset rate to 1x');
 });
 
 test('behavior: getTime caps interpolation at _CHART_MAX_INTERP_MS', () => {
@@ -225,8 +231,8 @@ test('behavior: setTime(0) on first tick anchors correctly (boot edge case)', ()
     const sb = buildClockSandbox(() => now);
     sb.setTime(0);
     // Anchor must now be initialized.
-    assert.equal(sb._chartAnchorAudioT, 0, 'setTime(0) on first tick must set anchor.audioT');
-    assert.equal(sb._chartAnchorPerfNow, 16, 'setTime(0) on first tick must set anchor.perfNow');
+    assert.equal(sb.hwState._chartAnchorAudioT, 0, 'setTime(0) on first tick must set anchor.audioT');
+    assert.equal(sb.hwState._chartAnchorPerfNow, 16, 'setTime(0) on first tick must set anchor.perfNow');
     // getTime should return a finite value, not NaN.
     const t = sb.getTime();
     assert.ok(!Number.isNaN(t), `getTime must not return NaN after setTime(0); got ${t}`);
@@ -252,10 +258,10 @@ test('behavior: long anchor gap resets observed rate to 1x', () => {
     sb.setTime(10);
     now = 50;
     sb.setTime(10.025); // observed rate ≈ 0.5
-    assert.ok(Math.abs(sb._chartObservedRate - 0.5) < 0.001, 'first segment measured 0.5x');
+    assert.ok(Math.abs(sb.hwState._chartObservedRate - 0.5) < 0.001, 'first segment measured 0.5x');
     // Long gap (1 second) before next setTime — out of the dPerf < 0.5
     // window, so the rate must reset to 1.
     now = 1100;
     sb.setTime(10.5);
-    assert.equal(sb._chartObservedRate, 1, 'long anchor gap must reset rate to 1x');
+    assert.equal(sb.hwState._chartObservedRate, 1, 'long anchor gap must reset rate to 1x');
 });

tests/js/highway_note_state.test.js

@@ -34,16 +34,16 @@ function extractBlock(src, signature) {
 
 test('highway declares the note-state provider slot', () => {
     const src = fs.readFileSync(highwayJs, 'utf8');
-    assert.match(src, /let\s+_noteStateProvider\s*=\s*null/, 'missing _noteStateProvider (provider slot, null = none)');
+    assert.match(src, /hwState\._noteStateProvider\s*=\s*null/, 'missing _noteStateProvider (provider slot, null = none)');
 });
 
 test('public API exposes setNoteStateProvider / getNoteStateProvider / getNoteState / isDefaultRenderer', () => {
     const src = fs.readFileSync(highwayJs, 'utf8');
-    assert.match(src, /setNoteStateProvider\s*\(\s*fn\s*\)\s*\{[^}]*_noteStateProvider\s*=/, 'setNoteStateProvider must assign _noteStateProvider');
+    assert.match(src, /setNoteStateProvider\s*\(\s*fn\s*\)\s*\{[^}]*hwState\._noteStateProvider\s*=/, 'setNoteStateProvider must assign _noteStateProvider');
     assert.match(src, /setNoteStateProvider\s*\(\s*fn\s*\)\s*\{[^}]*typeof\s+fn\s*===\s*['"]function['"][^}]*:\s*null/, 'setNoteStateProvider must coerce non-functions (incl. null) to null');
-    assert.match(src, /getNoteStateProvider\s*\(\s*\)\s*\{\s*return\s+_noteStateProvider/, 'getNoteStateProvider must return the slot');
+    assert.match(src, /getNoteStateProvider\s*\(\s*\)\s*\{\s*return\s+hwState\._noteStateProvider/, 'getNoteStateProvider must return the slot');
     assert.match(src, /getNoteState\s*\(\s*note\s*,\s*chartTime\s*\)\s*\{\s*return\s+_noteState\s*\(/, 'getNoteState must delegate to _noteState');
-    assert.match(src, /isDefaultRenderer\s*\(\s*\)\s*\{\s*return\s+_renderer\s*===\s*_defaultRenderer\s*\|\|\s*_renderer\s*==\s*null/, 'isDefaultRenderer must be (_renderer === _defaultRenderer || _renderer == null)');
+    assert.match(src, /isDefaultRenderer\s*\(\s*\)\s*\{\s*return\s+hwState\._renderer\s*===\s*_defaultRenderer\s*\|\|\s*hwState\._renderer\s*==\s*null/, 'isDefaultRenderer must be (_renderer === _defaultRenderer || _renderer == null)');
 });
 
 test('_makeBundle exposes getNoteState (stable reference, no per-frame alloc)', () => {
@@ -72,7 +72,7 @@ test('_makeBundle exposes getNoteStateProvider as a stable reference (feedBack#2
     // slot, so renderers see a live "is a provider registered?" view.
     assert.match(
         src,
-        /function\s+_getNoteStateProvider\s*\(\s*\)\s*\{\s*return\s+_noteStateProvider\s*;?\s*\}/,
+        /function\s+_getNoteStateProvider\s*\(\s*\)\s*\{\s*return\s+hwState\._noteStateProvider\s*;?\s*\}/,
         '_getNoteStateProvider must be defined as a stable named function returning _noteStateProvider'
     );
 });
@@ -80,7 +80,7 @@ test('_makeBundle exposes getNoteStateProvider as a stable reference (feedBack#2
 test('_noteState normalizes provider output as documented', () => {
     const src = fs.readFileSync(highwayJs, 'utf8');
     const fn = extractBlock(src, 'function _noteState(note, chartTime)');
-    assert.match(fn, /if\s*\(\s*!_noteStateProvider\s*\)\s*return\s+null/, 'must short-circuit when no provider is registered');
+    assert.match(fn, /if\s*\(\s*!hwState\._noteStateProvider\s*\)\s*return\s+null/, 'must short-circuit when no provider is registered');
     assert.match(fn, /try\s*\{[\s\S]*_noteStateProvider\s*\([\s\S]*catch[\s\S]*return\s+null/, 'must call the provider inside try/catch and return null on throw');
     assert.match(fn, /state\s*!==\s*['"]hit['"]\s*&&\s*state\s*!==\s*['"]active['"]\s*&&\s*state\s*!==\s*['"]miss['"]/, 'must reject states other than hit/active/miss');
     assert.match(fn, /Math\.max\(\s*0\s*,\s*Math\.min\(\s*1\s*,\s*raw\.alpha\s*\)\s*\)/, 'must clamp alpha to [0,1]');

tests/js/highway_pause_throttle.test.js

@@ -32,7 +32,7 @@ function extractBlock(src, signature) {
 test('highway declares the paused-render throttle state', () => {
     const src = fs.readFileSync(highwayJs, 'utf8');
     assert.match(src, /const\s+_PAUSED_FRAME_INTERVAL_MS\s*=\s*\d+/, 'missing _PAUSED_FRAME_INTERVAL_MS cap');
-    assert.match(src, /let\s+_lastPausedDrawAt\s*=\s*0/, 'missing _lastPausedDrawAt accumulator');
+    assert.match(src, /hwState\._lastPausedDrawAt\s*=\s*0/, 'missing _lastPausedDrawAt accumulator');
 });
 
 test('draw() throttles full renders while the audio clock is stalled', () => {
@@ -42,7 +42,7 @@ test('draw() throttles full renders while the audio clock is stalled', () => {
     assert.match(fn, /_chartLastAdvanceAt/, 'throttle must key off _chartLastAdvanceAt (the advance timestamp)');
     assert.match(fn, /_CHART_MAX_INTERP_MS/, 'throttle must reuse the _CHART_MAX_INTERP_MS pause threshold');
     assert.match(fn, /_PAUSED_FRAME_INTERVAL_MS/, 'throttle must cap paused draws to _PAUSED_FRAME_INTERVAL_MS');
-    assert.match(fn, /_lastPausedDrawAt\s*=\s*_nowP/, 'throttle must record the last paused draw time');
+    assert.match(fn, /hwState\._lastPausedDrawAt\s*=\s*_nowP/, 'throttle must record the last paused draw time');
 });
 
 test('throttle runs after the ready gate, before bundle/draw', () => {
@@ -51,7 +51,7 @@ test('throttle runs after the ready gate, before bundle/draw', () => {
     // Regex landmarks (not exact-string indexOf) so harmless spacing /
     // semicolon changes don't break the ordering guard — matches the
     // search-based style of the other highway source-guard tests.
-    const readyIdx = fn.search(/if\s*\(\s*!ready\s*\)\s*return;/);
+    const readyIdx = fn.search(/if\s*\(\s*!hwState\.ready\s*\)\s*return;/);
     const throttleIdx = fn.search(/_PAUSED_FRAME_INTERVAL_MS/);
     const drawIdx = fn.search(/_renderer\.draw\s*\(/);
     assert.ok(readyIdx !== -1, 'ready gate not found');

tests/js/highway_phrases.test.js

@@ -22,7 +22,7 @@ test('getPhrases returns null when _phrases is falsy or empty', () => {
     const src = fs.readFileSync(highwayJs, 'utf8');
     assert.match(
         src,
-        /getPhrases\s*\(\s*\)\s*\{[^}]*!\s*_phrases[^}]*return null/,
+        /getPhrases\s*\(\s*\)\s*\{[^}]*!\s*hwState\._phrases[^}]*return null/,
         'getPhrases must return null when no phrase data is available',
     );
 });

tests/js/highway_renderer_swap_canvas_reset.test.js

@@ -44,9 +44,9 @@ test('_setRenderer captures the outgoing renderer before overwriting it', () =>
     // prev must be captured BEFORE _destroyCurrentIfInited and the
     // `_renderer = next` assignment, otherwise the swap detection below
     // would always compare next against itself.
-    const prevIdx = fn.search(/const\s+prev\s*=\s*_renderer/);
+    const prevIdx = fn.search(/const\s+prev\s*=\s*hwState\._renderer/);
     const destroyIdx = fn.search(/_destroyCurrentIfInited\(\)/);
-    const assignIdx = fn.search(/^\s*_renderer\s*=\s*next\s*;/m);
+    const assignIdx = fn.search(/^\s*hwState\._renderer\s*=\s*next\s*;/m);
     assert.ok(prevIdx !== -1, 'must capture `const prev = _renderer`');
     assert.ok(destroyIdx !== -1, 'must call _destroyCurrentIfInited');
     assert.ok(assignIdx !== -1, 'must assign `_renderer = next`');
@@ -67,7 +67,7 @@ test('_setRenderer replaces the canvas on a context-type change OR a viz change'
     );
     assert.match(
         fn,
-        /if\s*\(\s*nextType\s*!==\s*_currentCanvasContextType\s*\|\|\s*_vizChanged\s*\)\s*\{\s*_replaceCanvas\(nextType\)/,
+        /if\s*\(\s*nextType\s*!==\s*hwState\._currentCanvasContextType\s*\|\|\s*_vizChanged\s*\)\s*\{\s*_replaceCanvas\(nextType\)/,
         'replace guard must be `nextType !== _currentCanvasContextType || _vizChanged`',
     );
 });

tests/js/highway_string_colors.test.js

@@ -40,20 +40,20 @@ test('2D palette arrays are mutable (let) with frozen DEFAULT_* originals', () =
     assert.match(src, /const\s+DEFAULT_STRING_COLORS\s*=/, 'DEFAULT_STRING_COLORS must exist for reset');
     assert.match(src, /const\s+DEFAULT_STRING_DIM\s*=/, 'DEFAULT_STRING_DIM must exist for reset');
     assert.match(src, /const\s+DEFAULT_STRING_BRIGHT\s*=/, 'DEFAULT_STRING_BRIGHT must exist for reset');
-    assert.match(src, /let\s+STRING_COLORS\s*=\s*DEFAULT_STRING_COLORS\.slice\(\)/, 'STRING_COLORS must be a mutable copy of the defaults');
-    assert.match(src, /let\s+STRING_DIM\s*=\s*DEFAULT_STRING_DIM\.slice\(\)/, 'STRING_DIM must be a mutable copy of the defaults');
-    assert.match(src, /let\s+STRING_BRIGHT\s*=\s*DEFAULT_STRING_BRIGHT\.slice\(\)/, 'STRING_BRIGHT must be a mutable copy of the defaults');
+    assert.match(src, /hwState\.STRING_COLORS\s*=\s*DEFAULT_STRING_COLORS\.slice\(\)/, 'STRING_COLORS must be a mutable copy of the defaults');
+    assert.match(src, /hwState\.STRING_DIM\s*=\s*DEFAULT_STRING_DIM\.slice\(\)/, 'STRING_DIM must be a mutable copy of the defaults');
+    assert.match(src, /hwState\.STRING_BRIGHT\s*=\s*DEFAULT_STRING_BRIGHT\.slice\(\)/, 'STRING_BRIGHT must be a mutable copy of the defaults');
 });
 
 test('2D public API exposes getStringColors / setStringColors', () => {
     const src = fs.readFileSync(highwayJs, 'utf8');
-    assert.match(src, /getStringColors\s*\(\s*\)\s*\{\s*return\s+STRING_COLORS\.slice\(\)/, 'getStringColors must return a copy');
+    assert.match(src, /getStringColors\s*\(\s*\)\s*\{\s*return\s+hwState\.STRING_COLORS\.slice\(\)/, 'getStringColors must return a copy');
     const fn = extractBlock(src, 'setStringColors(arr)');
     // Each provided index sets base + derived dim/bright; missing → default.
-    assert.match(fn, /STRING_COLORS\[i\]\s*=\s*base/, 'setStringColors must set the base color');
-    assert.match(fn, /STRING_DIM\[i\]\s*=\s*_darken\(/, 'setStringColors must derive the dim variant');
-    assert.match(fn, /STRING_BRIGHT\[i\]\s*=\s*_lighten\(/, 'setStringColors must derive the bright variant');
-    assert.match(fn, /STRING_COLORS\[i\]\s*=\s*DEFAULT_STRING_COLORS\[i\]/, 'setStringColors must restore defaults for missing/invalid indices');
+    assert.match(fn, /hwState\.STRING_COLORS\[i\]\s*=\s*base/, 'setStringColors must set the base color');
+    assert.match(fn, /hwState\.STRING_DIM\[i\]\s*=\s*_darken\(/, 'setStringColors must derive the dim variant');
+    assert.match(fn, /hwState\.STRING_BRIGHT\[i\]\s*=\s*_lighten\(/, 'setStringColors must derive the bright variant');
+    assert.match(fn, /hwState\.STRING_COLORS\[i\]\s*=\s*DEFAULT_STRING_COLORS\[i\]/, 'setStringColors must restore defaults for missing/invalid indices');
 });
 
 // ── 3D highway (plugins/highway_3d/screen.js) ─────────────────────────────

tests/js/highway_visibility.test.js

@@ -32,14 +32,14 @@ function extractBlock(src, signature) {
 
 test('highway declares visibility state (_visibleOverride + _lastVisible)', () => {
     const src = fs.readFileSync(highwayJs, 'utf8');
-    assert.match(src, /let\s+_visibleOverride\s*=\s*null/, 'missing _visibleOverride (override sentinel)');
-    assert.match(src, /let\s+_lastVisible\s*=\s*null/, 'missing _lastVisible (last-emitted state)');
+    assert.match(src, /hwState\._visibleOverride\s*=\s*null/, 'missing _visibleOverride (override sentinel)');
+    assert.match(src, /hwState\._lastVisible\s*=\s*null/, 'missing _lastVisible (last-emitted state)');
 });
 
 test('_isHighwayVisible respects _visibleOverride and falls back to offsetParent', () => {
     const src = fs.readFileSync(highwayJs, 'utf8');
     const fn = extractBlock(src, 'function _isHighwayVisible()');
-    assert.match(fn, /_visibleOverride\s*!==\s*null/, 'must check the override before the DOM');
+    assert.match(fn, /hwState\._visibleOverride\s*!==\s*null/, 'must check the override before the DOM');
     assert.match(fn, /canvas\.offsetParent\s*!==\s*null/, 'DOM fallback must use offsetParent !== null');
 });
 
@@ -47,9 +47,9 @@ test('_emitVisibilityIfChanged is transition-only (no per-frame spam)', () => {
     const src = fs.readFileSync(highwayJs, 'utf8');
     const fn = extractBlock(src, 'function _emitVisibilityIfChanged()');
     // Must short-circuit when the current state equals the cached one.
-    assert.match(fn, /v\s*===\s*_lastVisible/, 'must compare current vs _lastVisible and bail when equal');
+    assert.match(fn, /v\s*===\s*hwState\._lastVisible/, 'must compare current vs _lastVisible and bail when equal');
     // Must update the cache and emit the event with the documented payload shape.
-    assert.match(fn, /_lastVisible\s*=\s*v/, 'must update _lastVisible after a transition');
+    assert.match(fn, /hwState\._lastVisible\s*=\s*v/, 'must update _lastVisible after a transition');
     assert.match(
         fn,
         /window\.feedBack\.emit\(\s*['"]highway:visibility['"][\s\S]*?visible:\s*v[\s\S]*?canvas/,
@@ -66,7 +66,7 @@ test('rAF draw() loop calls _emitVisibilityIfChanged and skips when hidden', ()
     // transitions during loading/reconnect windows still propagate.
     const emitIdx = fn.search(/_emitVisibilityIfChanged\(\)/);
     const skipIdx = fn.search(/if\s*\(\s*!_rendering\s*\)\s*return/);
-    const readyIdx = fn.search(/if\s*\(\s*!ready\s*\)\s*return/);
+    const readyIdx = fn.search(/if\s*\(\s*!hwState\.ready\s*\)\s*return/);
     const drawIdx = fn.search(/_renderer\.draw\(/);
     assert.ok(emitIdx !== -1 && skipIdx !== -1 && readyIdx !== -1 && drawIdx !== -1, 'all four landmarks must be present');
     assert.ok(emitIdx < readyIdx, 'emit must run BEFORE the !ready gate (transitions during loading must still fire)');
@@ -84,19 +84,19 @@ test('draw() keeps an active custom renderer painting through an override-hide (
     const src = fs.readFileSync(highwayJs, 'utf8');
     const fn = extractBlock(src, 'function draw()');
     // Single render decision drives both the perf-HUD reset and the gate.
-    assert.match(fn, /let\s+_rendering\s*=\s*_lastVisible/, 'must derive a single _rendering decision from _lastVisible');
+    assert.match(fn, /let\s+_rendering\s*=\s*hwState\._lastVisible/, 'must derive a single _rendering decision from _lastVisible');
     // Assert the exact boolean RELATIONSHIP, not just the tokens (CodeRabbit):
     // the exemption must AND together override-hide, an active custom renderer,
     // and the canvas still in layout. A weakened guard (e.g. `||`, or a dropped
     // offsetParent clause) must fail this — that's the regression being fixed.
     assert.match(
         fn,
-        /!_rendering\s*&&\s*_visibleOverride\s*===\s*false\s*&&\s*_renderer\s*!==\s*_defaultRenderer\s*&&\s*canvas\s*&&\s*canvas\.offsetParent\s*!==\s*null/,
+        /!_rendering\s*&&\s*hwState\._visibleOverride\s*===\s*false\s*&&\s*hwState\._renderer\s*!==\s*_defaultRenderer\s*&&\s*hwState\.canvas\s*&&\s*hwState\.canvas\.offsetParent\s*!==\s*null/,
         'exemption must AND override-hide + active custom renderer + canvas-in-layout (genuine off-screen still pauses, #246)',
     );
     // Both the HUD reset and the gate key off _rendering, not _lastVisible,
     // so the HUD doesn\'t churn while the custom renderer is actually drawing.
-    assert.match(fn, /_perfHud\s*&&\s*\(\s*!_rendering/, 'perf-HUD reset must key off _rendering, not _lastVisible');
+    assert.match(fn, /hwState\._perfHud\s*&&\s*\(\s*!_rendering/, 'perf-HUD reset must key off _rendering, not _lastVisible');
     assert.match(fn, /if\s*\(\s*!_rendering\s*\)\s*return/, 'the draw gate must bail on !_rendering');
 });
 

tests/js/juce_engine_reroute.test.js

@@ -40,7 +40,7 @@ function extractWatcherIIFE(src) {
 
 // Build a sandbox with fakes and run the watcher IIFE inside it. Returns the
 // sandbox so tests can drive window._reevaluateJuceRouting and inspect state.
-function makeSandbox({ isAudioRunning, loadBackingTrack }) {
+function makeSandbox({ isAudioRunning, loadBackingTrack, outputType = 'Windows Audio' }) {
     const calls = { loadBackingTrack: [], jucePlay: 0, jucePause: 0, audioPlay: 0 };
 
     const audio = {
@@ -65,6 +65,7 @@ function makeSandbox({ isAudioRunning, loadBackingTrack }) {
     const juceApi = {
         isAudioRunning: () => Promise.resolve(isAudioRunning()),
         loadBackingTrack: (p) => { calls.loadBackingTrack.push(p); return Promise.resolve(loadBackingTrack()); },
+        getCurrentDevice: () => Promise.resolve({ outputType: typeof outputType === 'function' ? outputType() : outputType }),
         getBackingDuration: () => Promise.resolve(180),
         seekBacking: () => Promise.resolve(),
         startBacking: () => Promise.resolve(),
@@ -152,6 +153,87 @@ test('non-JUCE-eligible song (sloppak stems) is never rerouted', async () => {
     assert.equal(sb.__calls.loadBackingTrack.length, 0);
 });
 
+test('feedpak full-mix + exclusive output → migrates to JUCE', async () => {
+    const sb = makeSandbox({
+        isAudioRunning: () => true,
+        loadBackingTrack: () => true,
+        outputType: 'Windows Audio (Exclusive Mode)',
+    });
+    sb.window._juceMode = false;
+    sb.window._currentSongAudio = {
+        url: '/api/sloppak/song.sloppak/file/stems/full.ogg',
+        juceEligible: false,
+        feedpakFullMix: true,
+    };
+
+    await sb.window._reevaluateJuceRouting();
+
+    assert.equal(sb.window._juceMode, true, 'feedpak full-mix rides the engine under exclusive output');
+    assert.equal(sb.__calls.loadBackingTrack.length, 1);
+});
+
+test('feedpak full-mix + ASIO output → migrates to JUCE', async () => {
+    const sb = makeSandbox({
+        isAudioRunning: () => true,
+        loadBackingTrack: () => true,
+        outputType: 'ASIO',
+    });
+    sb.window._juceMode = false;
+    sb.window._currentSongAudio = {
+        url: '/api/sloppak/song.sloppak/file/stems/full.ogg',
+        juceEligible: false,
+        feedpakFullMix: true,
+    };
+
+    await sb.window._reevaluateJuceRouting();
+
+    assert.equal(sb.window._juceMode, true, 'ASIO is exclusive-style; feedpak rides the engine');
+});
+
+test('feedpak full-mix + shared output → stays on HTML5 (stem mixer untouched)', async () => {
+    for (const shared of ['Windows Audio', 'Windows Audio (Low Latency Mode)', 'DirectSound']) {
+        const sb = makeSandbox({
+            isAudioRunning: () => true,
+            loadBackingTrack: () => true,
+            outputType: shared,
+        });
+        sb.window._juceMode = false;
+        sb.window._currentSongAudio = {
+            url: '/api/sloppak/song.sloppak/file/stems/full.ogg',
+            juceEligible: false,
+            feedpakFullMix: true,
+        };
+
+        await sb.window._reevaluateJuceRouting();
+
+        assert.equal(sb.window._juceMode, false, `stays on HTML5 for shared type "${shared}"`);
+        assert.equal(sb.__calls.loadBackingTrack.length, 0);
+    }
+});
+
+test('feedpak on JUCE + output leaves exclusive mode → migrates back to HTML5', async () => {
+    let type = 'Windows Audio (Exclusive Mode)';
+    const sb = makeSandbox({
+        isAudioRunning: () => true,
+        loadBackingTrack: () => true,
+        outputType: () => type,
+    });
+    const url = '/api/sloppak/song.sloppak/file/stems/full.ogg';
+    sb.window._juceMode = true;
+    sb.window._juceAudioUrl = url;
+    sb.window._currentSongAudio = { url, juceEligible: false, feedpakFullMix: true };
+
+    // Still exclusive: routing is consistent, no switch.
+    await sb.window._reevaluateJuceRouting();
+    assert.equal(sb.window._juceMode, true, 'consistent while exclusive');
+
+    // Device switched to shared mid-song: must return to HTML5.
+    type = 'Windows Audio';
+    await sb.window._reevaluateJuceRouting();
+    assert.equal(sb.window._juceMode, false, 'returned to HTML5 after leaving exclusive mode');
+    assert.equal(sb.audio.src, url, 'HTML5 element re-pointed at the song');
+});
+
 test('JUCE hard-reject is memoised → not retried on the next poll', async () => {
     const sb = makeSandbox({ isAudioRunning: () => true, loadBackingTrack: () => false });
     sb.window._juceMode = false;

tests/js/renderer_bus_feeder.test.js

@@ -0,0 +1,195 @@
+// Behavioral tests for the renderer-audio bus feeder in static/app.js.
+//
+// The feeder (an IIFE, `_installRendererBusFeeder`) captures renderer-side
+// song audio (stems-plugin WebAudio master, or the core <audio> element) and
+// pushes it into the desktop engine's renderer bus while the output device is
+// exclusive-style — the Phase 2 path for audio the native backing transport
+// cannot carry. These tests extract that IIFE from source and exercise
+// `window._reevaluateRendererBus` against fakes, covering: stems engagement
+// under exclusive output, disengagement on return to shared mode, inertness
+// in shared mode / while the native transport owns the song, and the
+// element-capture fallback.
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+
+const APP_JS = path.join(__dirname, '..', '..', 'static', 'app.js');
+
+function extractFeederIIFE(src) {
+    const marker = '(function _installRendererBusFeeder() {';
+    const start = src.indexOf(marker);
+    assert.ok(start !== -1, 'feeder IIFE not found in app.js');
+    const openBrace = src.indexOf('{', start);
+    let depth = 1;
+    let i = openBrace + 1;
+    while (i < src.length && depth > 0) {
+        const ch = src[i];
+        if (ch === '{') depth++;
+        else if (ch === '}') depth--;
+        i++;
+    }
+    assert.ok(depth === 0, 'unbalanced braces in feeder IIFE');
+    const tail = src.slice(i, i + 5);
+    assert.match(tail, /^\)\(\)/, 'feeder IIFE not immediately invoked');
+    return src.slice(start, i) + ')();';
+}
+
+function makeFakeContext(sampleRate = 48000) {
+    const ctx = {
+        sampleRate,
+        state: 'running',
+        sinkIdCalls: [],
+        destination: { isDestination: true },
+        setSinkId(v) { this.sinkIdCalls.push(v); return Promise.resolve(); },
+        resume() { this.state = 'running'; return Promise.resolve(); },
+        audioWorklet: { addModule: () => Promise.resolve() },
+        createMediaElementSource(el) {
+            this.mediaSourceEl = el;
+            return { connect() {}, disconnect() {} };
+        },
+    };
+    return ctx;
+}
+
+function makeSandbox({ isAudioRunning = () => true, exclusive = () => true } = {}) {
+    const calls = { setRendererBus: [], pushRendererAudio: [] };
+
+    const api = {
+        isAudioRunning: () => Promise.resolve(isAudioRunning()),
+        setRendererBus: (en, g) => { calls.setRendererBus.push([en, g]); return Promise.resolve(); },
+        pushRendererAudio: (buf, rate) => { calls.pushRendererAudio.push([buf.length, rate]); },
+    };
+
+    class FakeWorkletNode {
+        constructor() { this.port = { onmessage: null }; }
+        connect() {}
+        disconnect() {}
+    }
+
+    const sandbox = {
+        console: { log() {}, warn() {}, error() {} },
+        URL: { createObjectURL: () => 'blob:tap', revokeObjectURL() {} },
+        Blob: class { constructor() {} },
+        AudioWorkletNode: FakeWorkletNode,
+        AudioContext: function () { const c = makeFakeContext(); sandbox.__createdContexts.push(c); return c; },
+        WeakSet, WeakMap, Promise, Float32Array, Math,
+        setInterval: () => 0,
+        document: {
+            hidden: false,
+            addEventListener() {},
+            getElementById: () => sandbox.__audioEl,
+        },
+        __createdContexts: [],
+        __audioEl: { id: 'audio' },
+        __calls: calls,
+        window: null,
+    };
+    sandbox.window = {
+        feedBackDesktop: { audio: api },
+        _juceOutputIsExclusive: () => Promise.resolve(exclusive()),
+        _juceMode: false,
+        _currentSongAudio: null,
+        feedBack: { stems: {} },
+    };
+    sandbox.globalThis = sandbox;
+
+    const src = fs.readFileSync(APP_JS, 'utf8');
+    vm.createContext(sandbox);
+    vm.runInContext(extractFeederIIFE(src), sandbox);
+    assert.equal(typeof sandbox.window._reevaluateRendererBus, 'function',
+        'feeder must expose window._reevaluateRendererBus');
+    return sandbox;
+}
+
+function makeStemsGraph() {
+    return {
+        context: makeFakeContext(),
+        masterNode: { connect() {}, disconnect() {} },
+    };
+}
+
+test('stems graph + exclusive output → bus enabled, stems ctx null-sinked', async () => {
+    const sb = makeSandbox({ exclusive: () => true });
+    const graph = makeStemsGraph();
+    sb.window.feedBack.stems.audioGraph = graph;
+
+    await sb.window._reevaluateRendererBus();
+
+    assert.deepEqual(sb.__calls.setRendererBus.at(-1), [true, 1.0], 'bus enabled');
+    assert.equal(graph.context.sinkIdCalls.at(-1)?.type, 'none', 'stems ctx re-pointed at null sink');
+});
+
+test('output returns to shared → bus disabled, sink restored', async () => {
+    let excl = true;
+    const sb = makeSandbox({ exclusive: () => excl });
+    const graph = makeStemsGraph();
+    sb.window.feedBack.stems.audioGraph = graph;
+
+    await sb.window._reevaluateRendererBus();
+    excl = false;
+    await sb.window._reevaluateRendererBus();
+
+    assert.deepEqual(sb.__calls.setRendererBus.at(-1), [false, 0], 'bus disabled');
+    assert.equal(graph.context.sinkIdCalls.at(-1), '', 'default sink restored');
+});
+
+test('stems graph + shared output → feeder stays off (no double audio)', async () => {
+    const sb = makeSandbox({ exclusive: () => false });
+    sb.window.feedBack.stems.audioGraph = makeStemsGraph();
+
+    await sb.window._reevaluateRendererBus();
+
+    assert.equal(sb.__calls.setRendererBus.length, 0, 'bus never touched in shared mode');
+});
+
+test('element song + exclusive → element captured into bus', async () => {
+    const sb = makeSandbox({ exclusive: () => true });
+    sb.window._currentSongAudio = { url: '/api/sloppak/x.sloppak/file/stems/full.ogg' };
+    sb.window._juceMode = false;
+
+    await sb.window._reevaluateRendererBus();
+
+    assert.equal(sb.__createdContexts.length, 1, 'capture context created');
+    assert.equal(sb.__createdContexts[0].mediaSourceEl, sb.__audioEl, 'element source captured');
+    assert.deepEqual(sb.__calls.setRendererBus.at(-1), [true, 1.0], 'bus enabled');
+});
+
+test('song riding the native transport (_juceMode) → feeder stays off', async () => {
+    const sb = makeSandbox({ exclusive: () => true });
+    sb.window._currentSongAudio = { url: '/audio/song.ogg' };
+    sb.window._juceMode = true;
+
+    await sb.window._reevaluateRendererBus();
+
+    assert.equal(sb.__calls.setRendererBus.length, 0, 'native transport owns the song');
+    assert.equal(sb.__createdContexts.length, 0, 'no capture context created');
+});
+
+test('stems graph replaced mid-engagement → re-engages on the new graph', async () => {
+    const sb = makeSandbox({ exclusive: () => true });
+    const g1 = makeStemsGraph();
+    sb.window.feedBack.stems.audioGraph = g1;
+    await sb.window._reevaluateRendererBus();
+
+    const g2 = makeStemsGraph();
+    sb.window.feedBack.stems.audioGraph = g2;
+    await sb.window._reevaluateRendererBus();
+
+    assert.equal(g2.context.sinkIdCalls.at(-1)?.type, 'none', 'new graph null-sinked');
+    assert.deepEqual(sb.__calls.setRendererBus.at(-1), [true, 1.0], 're-enabled for new graph');
+});
+
+test('engine stops → bus disabled', async () => {
+    let running = true;
+    const sb = makeSandbox({ isAudioRunning: () => running, exclusive: () => true });
+    sb.window.feedBack.stems.audioGraph = makeStemsGraph();
+    await sb.window._reevaluateRendererBus();
+
+    running = false;
+    await sb.window._reevaluateRendererBus();
+
+    assert.deepEqual(sb.__calls.setRendererBus.at(-1), [false, 0], 'bus disabled after engine stop');
+});

tests/js/song_restart.test.js

@@ -14,7 +14,6 @@ const { extractFunction } = require('./test_utils');
 
 const APP_JS = path.join(__dirname, '..', '..', 'static', 'app.js');
 const V3_HTML = path.join(__dirname, '..', '..', 'static', 'v3', 'index.html');
-const V2_HTML = path.join(__dirname, '..', '..', 'static', 'index.html');
 
 function buildSandbox({ loopA = null, loopB = null, isPlaying = false } = {}) {
     const sandbox = {
@@ -138,10 +137,3 @@ test('V3 transport restart button exists with correct attributes', () => {
     assert.match(html, /title="Restart song"/);
     assert.match(html, /aria-label="Restart song"/);
 });
-
-test('V2 transport restart button exists with correct attributes', () => {
-    const html = fs.readFileSync(V2_HTML, 'utf8');
-    assert.match(html, /#player-controls|player-controls[\s\S]*onclick="restartCurrentSong\(\)"/);
-    assert.match(html, /title="Restart song"/);
-    assert.match(html, /aria-label="Restart song"/);
-});

tests/js/tuning_display.test.js

@@ -9,7 +9,6 @@ const vm = require('node:vm');
 const APP_JS = path.join(__dirname, '..', '..', 'static', 'app.js');
 const HIGHWAY_JS = path.join(__dirname, '..', '..', 'static', 'highway.js');
 const V3_HTML = path.join(__dirname, '..', '..', 'static', 'v3', 'index.html');
-const V2_HTML = path.join(__dirname, '..', '..', 'static', 'index.html');
 
 function extractBlock(src, startMarker) {
     const start = src.indexOf(startMarker);
@@ -97,11 +96,6 @@ test('V3 index.html defines hud-tuning', () => {
     assert.match(html, /id="hud-tuning"/);
 });
 
-test('V2 index.html defines hud-tuning', () => {
-    const html = fs.readFileSync(V2_HTML, 'utf8');
-    assert.match(html, /id="hud-tuning"/);
-});
-
 test('highway.js updates hud-tuning from song_info tuning offsets', () => {
     const src = fs.readFileSync(HIGHWAY_JS, 'utf8');
     assert.match(src, /getElementById\('hud-tuning'\)/);