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>

.github/workflows/ci.yml

@@ -52,7 +52,7 @@ jobs:
         run: pytest
 
       - name: Run JS plugin-API tests
-        run: node --test tests/js/*.test.js 'tests/plugins/*/js/*.test.js'
+        run: node --test tests/js/*.test.js 'tests/plugins/*/js/*.test.js' 'plugins/*/tests/*.test.js'
 
   tailwind-fresh:
     # Guard that the committed static/tailwind.min.css is in sync with source.
@@ -123,3 +123,28 @@ jobs:
               sys.exit(1)
           print(f"Validated {len(manifests)} manifest(s) — OK")
           EOF
+
+  lint:
+    # Maintainer/CI-only size + module-hygiene gate (constitution Principle I:
+    # dev tooling, never on the serve/Docker path — same category as
+    # scripts/build-tailwind.sh). max-lines WARNS (the 1,500-line size ratchet;
+    # non-blocking), while import-x/no-unresolved + no-cycle HARD-ERROR on the
+    # ES-module graphs the refactor produces. Exemptions: docs/size-exemptions.md.
+    name: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        # npm ci runs third-party postinstall scripts; don't leave the token in
+        # git config for them (this job never pushes).
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: ESLint (size norm + module hygiene)
+        run: npm run lint

.github/workflows/nightly.yml

@@ -1,41 +1,19 @@
 name: Nightly
 
+# Trunk-based: nightly always builds main — the release-branch discovery
+# from the old release-centric flow is gone (it pinned nightlies to the
+# highest release/v* branch forever, even after it shipped). Stabilization
+# builds from release/** come from rc.yml instead.
 on:
   schedule:
-    - cron: '0 2 * * *'
+    - cron: '0 23 * * *'
   workflow_dispatch:
 
 permissions:
   contents: read
 
 jobs:
-  setup:
-    runs-on: ubuntu-latest
-    outputs:
-      branch: ${{ steps.branch.outputs.branch }}
-      date: ${{ steps.date.outputs.date }}
-
-    steps:
-      - name: Find active release branch
-        id: branch
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          branch=$(gh api "repos/${{ github.repository }}/git/matching-refs/heads/release/v" \
-            --jq '[.[].ref | ltrimstr("refs/heads/")] | map(ltrimstr("refs/heads/")) | .[]' \
-            | sort -V | tail -1 || true)
-          if [[ -z "$branch" ]]; then
-            branch="main"
-          fi
-          echo "branch=$branch" >> "$GITHUB_OUTPUT"
-          echo "Active branch: $branch"
-
-      - name: Get date
-        id: date
-        run: echo "date=$(date -u +%Y%m%d)" >> "$GITHUB_OUTPUT"
-
   build-docker:
-    needs: setup
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -44,9 +22,12 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
-          ref: ${{ needs.setup.outputs.branch }}
           persist-credentials: false
 
+      - name: Get date
+        id: date
+        run: echo "date=$(date -u +%Y%m%d)" >> "$GITHUB_OUTPUT"
+
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
@@ -65,6 +46,6 @@ jobs:
           push: true
           tags: |
             ghcr.io/got-feedback/feedback:nightly
-            ghcr.io/got-feedback/feedback:nightly-${{ needs.setup.outputs.date }}
+            ghcr.io/got-feedback/feedback:nightly-${{ steps.date.outputs.date }}
           cache-from: type=gha
           cache-to: type=gha,mode=max

.github/workflows/rc.yml

@@ -0,0 +1,63 @@
+name: rc
+
+# Release-candidate images for stabilization: every push to a release/**
+# branch builds and pushes ghcr.io tags :rc (moving) and
+# :rc-<version>-<date> (pinned). Final versioned images still come from
+# release.yml on tag push.
+on:
+  push:
+    branches: ['release/**']
+
+permissions:
+  contents: read
+
+# One build per branch at a time; a newer push supersedes an in-flight one.
+concurrency:
+  group: rc-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-docker:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Derive RC tags
+        id: meta
+        run: |
+          # release/v0.3.0 -> 0.3.0 (tolerate a missing v prefix too)
+          version="${GITHUB_REF_NAME#release/}"
+          version="${version#v}"
+          date="$(date -u +%Y%m%d)"
+          {
+            echo "tags<<TAGS_EOF"
+            echo "ghcr.io/got-feedback/feedback:rc"
+            echo "ghcr.io/got-feedback/feedback:rc-${version}-${date}"
+            echo "TAGS_EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/release.yml

@@ -35,9 +35,9 @@ jobs:
           # stable releases (no pre-release suffix).
           {
             echo "tags<<TAGS_EOF"
-            echo "ghcr.io/${GITHUB_REPOSITORY}:${version}"
+            echo "ghcr.io/${GITHUB_REPOSITORY,,}:${version}"
             if [[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-              echo "ghcr.io/${GITHUB_REPOSITORY}:latest"
+              echo "ghcr.io/${GITHUB_REPOSITORY,,}:latest"
             fi
             echo "TAGS_EOF"
           } >> "$GITHUB_OUTPUT"

.github/workflows/ship-ci.yml

@@ -8,6 +8,11 @@ name: ship-ci
 on:
   pull_request:
     branches: [main, 'release/**']
+  # Trunk-based: post-merge CI on main catches semantic conflicts between
+  # independently-green PRs; push on release/** covers stabilization
+  # cherry-picks that land without a PR.
+  push:
+    branches: [main, 'release/**']
 
 permissions:
   contents: read

.gitignore

@@ -44,6 +44,12 @@ plugins/minigames/__pycache__/
 plugins/tuner/__pycache__/
 !plugins/input_setup/
 !plugins/input_setup/**
+!plugins/drum_highway_3d/
+!plugins/drum_highway_3d/**
+plugins/drum_highway_3d/__pycache__/
+!plugins/keys_highway_3d/
+!plugins/keys_highway_3d/**
+plugins/keys_highway_3d/__pycache__/
 node_modules/
 test-results/
 playwright-report/

.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
@@ -48,11 +48,30 @@ output is committed, so Docker / desktop / end users never build. New
 features extend `app.js` and the existing globals (`window.playSong`,
 `window.showScreen`, `window.createHighway`, `window.feedBack`).
 
+Native ES modules are a first-class, build-free extension mechanism.
+Because `<script type="module">` and `import` are browser features — not
+a bundler — a large source file MAY be split into an `import`-ed module
+graph of plain source files, with **no build step and no framework**. A
+plugin opts in with `"scriptType": "module"` in `plugin.json`: its
+`screen.js` becomes a one-line `import './src/main.js'`, and the host
+serves the `src/` subtree from the sandboxed `/api/plugins/<id>/src/…`
+route and injects the entry as `<script type="module">`. The classic
+global-scope `screen.js` path remains fully supported; both coexist, and
+module scripts are still source-served — the no-bundler, no-transpiler,
+build-free-at-serve rule is unchanged. Core's own `static/` tree may
+migrate to the same module-graph shape (`static/js/…`) over time under
+this rule.
+
 **Non-negotiable rules**
 
 - Do not introduce a frontend framework, JSX, or a JS build pipeline in
   core. Plugins MAY ship their own bundled assets but core MUST remain
   source-served.
+- ES-module plugins remain source-served: no bundler or transpiler, and
+  their own asset URLs (worklets, WASM, images) resolve via
+  `import.meta.url` — never `document.currentScript`, which is `null`
+  inside a module. `scriptType:"module"` and the optional `minHost`
+  version floor are the only new `plugin.json` keys the module path adds.
 - Because the core Tailwind stylesheet is prebuilt, it contains only the
   classes present in core source at build time. Core's committed
   `static/tailwind.min.css` MUST stay in sync with source — CI enforces
@@ -214,6 +233,15 @@ no `..`, no absolute paths).
   runs first). Plugins MUST tolerate dependent globals being absent
   at load time and check at runtime
   (`typeof window.X === 'function'`).
+- **Module load contract**: a `scriptType:"module"` plugin is injected
+  as `<script type="module">`, whose load event fires only after its
+  whole static-import graph fetches and evaluates — so the loader's
+  completion-by-`onload` guarantee (and the `playSong` wrapper-chain
+  order above) is preserved exactly. The host loads `screen.js` once per
+  version and `showScreen` re-injects nothing, so a plugin's per-visit
+  re-initialization comes from its `screen:changed` handler, not from
+  screen.js re-running; ES-module plugins inherit this unchanged (module
+  top-level code does not re-execute on same-version re-mount).
 
 ## Development Workflow
 
@@ -256,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.1.0 | **Ratified**: 2026-05-09 | **Last Amended**: 2026-06-01
+**Version**: 1.3.0 | **Ratified**: 2026-05-09 | **Last Amended**: 2026-07-11

CHANGELOG.md

@@ -7,10 +7,159 @@ 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.
+- **Perf-baseline harness (R0).** `scripts/perf-baseline.mjs` (maintainer-only, Playwright-driven) captures server p50/p95/p99 latency, cold boot-to-interactive, JS-heap after an idle soak, and the injected plugin-script shape (how many are `type=module`), so every refactor phase can be checked for "screen-entry and frame-time no worse." Methodology + the R0 baseline live in `docs/perf-baseline.md`; playback frame-time and chart-loaded screen-entry rows need a seeded library and are re-taken per environment.
+- **Sort and filter the library by your personal difficulty rating — now visible at a glance, not just in the edit drawer.** `song_user_meta.user_difficulty` (the 1–5 planning rating, settable manually or seeded by a plugin like the community `difficulty_tagger`) already existed but was only readable by opening a song's per-song details drawer. The library API gains `sort=difficulty` / `sort=difficulty-desc` — a correlated subquery over `song_user_meta`, following the same unrated-rows-sort-to-the-bottom-in-both-directions pattern as the existing `mastery` sort — and library cards now show the rating as a `◆N` badge (v2 grid/tree views and the v3 grid alike), next to the tuning and lyrics badges. The classic tree view's `query_artists` batch-attaches `user_difficulty` the same way `query_page` already did for the grid, so the badge actually renders there too instead of staying dark. Tests: `tests/test_library_filters.py::test_difficulty_sort_pushes_unrated_to_bottom`, `tests/test_library_filters.py::test_tree_view_songs_carry_user_difficulty`.
+- **`lib/midi_import.py`: `convert_midi_tempo_map` — MIDI imports can finally carry
+  their bars.** The keys/drums note converters always computed a tempo-aware
+  tick→seconds map internally (to bake note times to absolute seconds) and then threw
+  it away — and never read `time_signature` meta at all — so every MIDI import landed
+  with no measures and an implied 4/4 regardless of what the file said. The new helper
+  extracts the whole grid: `tempos` (`{time, bpm}`), `time_signatures` (`{time,
+  ts:[num,den]}`, the song-timeline sidecar shape), and a full `beats` grid on the
+  editor's row shape (numbered downbeats with a `den` hint, `-1` interior beats,
+  eighth-note rows in 6/8 etc.). Event scope mirrors the existing tick map — SMF
+  type 0/1 merge meta across tracks, type 2 reads only the chosen track (independent
+  timelines must never share a grid); mid-bar signature events apply at the next bar
+  boundary; times are computed from absolute ticks through the cumulative tempo table
+  and rounded once at emit, so rounding error never accumulates with song length.
+  Consumed by the editor's upcoming multitrack MIDI import (tempo-seed dialog). Tests:
+  `tests/test_midi_tempo_map.py`.
+
+### Fixed
+- **Tuner: opening the player screen no longer throws `NotFoundError` and aborts the player render (feedBack#800).** `injectPlayerButton()` anchored the injected Tuner button with `controls.querySelector('button:last-child')`, which — unlike a `:scope`-scoped query — can match a **nested** button that is not a direct child of `#player-controls`. `controls.insertBefore(btn, nestedButton)` then throws `NotFoundError` (the reference node must be a direct child), and because the injection runs from the tuner's `screen:changed` → player handler, the throw propagated out of the player-screen transition and stalled its render (surfaced by a headless render of a notation arrangement; the v3 path was already safe via the plugin-control slot, only the classic path had the bad anchor). The anchor is now `:scope > button:last-of-type` (a direct child only) with a `parentNode === controls` guard before `insertBefore`, falling back to `appendChild`. `plugins/tuner` → 1.3.4. Tests: `tests/plugins/tuner/js/inject_player_button.test.js` (nested-last-button repro, direct-child insert, no-button append, idempotency, v3 slot path).
+- **Auto-sync: DTW step constraint — riff-based songs no longer produce garbage sync points.** `librosa.sequence.dtw`'s default step pattern allows unbounded horizontal/vertical path runs, and on music with long self-similar chroma stretches (riff-driven stoner/doom, drone sections) the flat cost surface let the warping path collapse — minutes of score mapped onto a single audio frame, so the per-bar warp imported charts wildly out of sync while reporting success (observed on a real 138 BPM tab: effective displayed tempo 159 BPM, three sync points sharing one audio timestamp). `_dtw_align` now uses the standard music-sync slope-constrained step pattern (`[[1,1],[1,2],[2,1]]`, local tempo ratio bounded to 0.5x–2x), which makes the degenerate path impossible, with a fallback to unconstrained steps when the global length ratio makes the constrained pattern infeasible (e.g. a tab aligned against a full-concert video). Validated on the failing song: coarse points track the recording 1:1, refined downbeats land on onset peaks at 3.3x background energy.
+
+### Added
+- **3D Keys Highway: key layout modes, lane-color opacity & octave lines.** A new **Highway layout** settings section rebuilds how sharps/flats and lanes draw on the 3D piano highway. **Sharps & flats layout** (`keys3d_bg_sharpMode`) picks between **floating** (the original raised-sharp look), **flat** (one plane, zero-overlap piano-shaped tiled lanes with the naturals evened out), and **realistic** (one plane, bars sized like the physical keys) — default **realistic**; the geometry lives in pure, unit-tested `laneSpanFlat()`/`laneSpanReal()` helpers. **Lane color opacity** (`keys3d_bg_laneOpacity`, 0–1, default 0) fades the pitch-class lane tint from full vivid color down to a dark floor with guide lines only at the key-block boundaries (E→F and each octave); the lane strips, per-lane separators and block lines crossfade with the value. **Octave separators** (`keys3d_bg_octaveGaps`, default on) and **Octave line contrast** (`keys3d_bg_octaveContrast`, 0–1) control the B→C octave divider, which auto-shifts from a dark to a bright layer as lane opacity fades. Settings re-read on init and apply on the next chart build. `plugins/keys_highway_3d` → 0.2.0. Tests: `plugins/keys_highway_3d/tests/fx_settings.test.js` (new defaults, sharp-mode setting, lane-geometry tiling/evening for flat, uniform/overlap for realistic, and an active-range boundary case where a white key's edge stays untrimmed when its neighboring sharp falls outside the active range).
+- **Unmapped-percussion capture now records velocities alongside times.** Both drum converters' opt-in `out_unmapped` reporting (`lib/midi_import.py` `convert_drum_track_from_midi`, `lib/gp2rs.py` `convert_drum_track_to_drumtab`) gain an index-aligned `velocities` list next to `times`, carrying each dropped note's real dynamics (MIDI velocity verbatim; GP velocity with the same 1–127 gate as mapped hits, falling back to the 100 import default). This lets a hand-mapping UI (the editor's unmapped-notes dialog) restore mapped notes at their source dynamics instead of flattening everything to `v:100`. The GP path's chronological sort now reorders times and velocities in lockstep so multi-voice measures can't silently reassign dynamics. Additive — callers that ignore the new key are unaffected. Tests: `tests/test_midi_import_drums.py`, `tests/test_gp2rs_drums.py`.
+- **Handedness (left-handed) is now a first-class choice in the instrument selector — and surfaced during onboarding.** Left-handed players could already mirror the highway, but only via a buried Settings toggle they had to find *after* setup — so a lefty hit the tour, the tuner and calibration all right-handed first. The v3 instrument badge popover now has a **Handedness: Right / Left** row alongside Instrument / Strings / Tuning (all player-orientation choices), writing the same `lefty` preference (`highway.setLefty` when a live highway exists, else the `lefty` localStorage key it reads on init; the Settings checkbox stays in sync). The first-run tour's "Choose your instrument" step — which runs **before** the tuner/audio-calibration steps — now calls it out so lefties flip it up front. Frontend-only, additive: `static/v3/badges.js`, `static/v3/onboarding-tour.js`. Tests: `tests/js/badges_handedness.test.js`.
+- **"Colorblind (deuteranope)" highway string-color preset.** Adds a one-click preset to the shared "Highway String Colors" picker, sitting next to the existing Okabe–Ito "Colorblind-friendly" preset — contributed by a deuteranopic player who found the Okabe–Ito set still hard to separate. It retunes the six main strings (red / yellow-green / blue / orange / teal / deep-purple) and keeps that set's 7/8-string colors, and applies to **both** the 2D and 3D highways via the shared picker. Frontend-only, additive: `static/app.js` (`HWC_PRESETS`).
+- **`lib/gp_autosync.py`: piecewise time-warp helpers + a working `refine_sync()`.** `auto_sync()` has always computed per-bar sync points (DTW), but consumers could only apply the scalar bar-1 `audio_offset`, so any tempo difference between the recording and the tab's authored tempo accumulated audibly over the song. New librosa-free helpers expose the full mapping: `bar_start_times(gp_path)` (per-bar score times on the same axis as the sync points — GPIF bar-resolution map for `.gp`/`.gpx`, per-tick integration for GP3/4/5), `build_warp_anchors(points, bar_starts)` (strictly-monotonic `(score, audio)` anchor pairs), `warp_time(t, anchors)` (piecewise-linear map with edge-slope extrapolation for count-ins/tails), `warp_song_times(song, warp)` (retimes a `lib.song.Song` in place: notes + sustains, chords, beats, sections, anchors, handshapes, per-phrase difficulty levels, tone changes, tempo overrides), and `gp_has_expandable_repeats(gp_path)` (detects GP3/4/5 repeat/volta/direction markup whose playback expansion the as-written sync points cannot map — callers fall back to offset-only sync). Also implements `refine_sync()`, which the editor plugin's refine-sync endpoint has imported since the snapshot but which never existed in core (the Refine button 500'd): it densifies the coarse DTW points to every Nth bar and re-times each with a local onset phase sweep (sweep radius clamped under half a beat so periodic material can't lock a full beat off; short scoring grid + median residual snap). Synthetic click-track validation: ~13ms mean / ~40ms max error from ±180ms coarse input across 117–123 BPM recordings of a 120 BPM tab. Tests: `tests/test_gp_autosync_warp.py`.
+- **Playlist shuffle.** The v3 playlist detail page gains a crossing-arrows shuffle toggle next to Play all / Play album. When on, `playQueue.start` Fisher-Yates-shuffles the queue once at start (on a copy — the stored playlist order is untouched), swapping any per-slot album arrangements in lockstep so each slot keeps its pinned arrangement. The preference is global and persists in `localStorage` (`v3PlaylistShuffle`). Tests: `tests/js/play_queue_shuffle.test.js`.
+
 ### Changed
 - **Player frame-time hotspots removed (trace-backed) + weak-hardware hardening.** A Chrome performance trace of a 3D-highway session surfaced two core per-frame layout-thrash sources, now fixed: the highway's visibility check read `canvas.offsetParent` every rAF frame (forces style/layout recalc — now sampled every 10th frame with a cached value, force-refreshed on init/canvas-replace/resize/override-clear), and the v3 player chrome loop called `matches(':hover')` per frame and unconditionally rewrote the Up-Next pill's `textContent`/bar width at 6 Hz (now hover-tracked via mouseenter/mouseleave, DOM writes only on value change, progress bar moved from `width` to compositor-only `scaleX`). The 3D highway pre-warms shader programs (`ren.compile`) and deterministic label textures at init — and chart-dependent chord/section label textures on first draw — so first-appearance shader-compile/texture-upload frame spikes move into the load spinner. For weaker hardware: the per-frame renderer bundle is now a single reused object instead of a fresh ~35-field allocation per frame (object identity is stable and meaningless; array fields still swap reference on chart changes), custom viz get `bundle.lowerBoundT`/`bundle.lowerBoundTime` binary-search helpers for visible-window culling, the default 2D highway's beat lines no longer scan every beat in the song per frame, and the 3D highway stops reading `localStorage` per frame (1 Hz poll) and caches its lyrics text-measurement layout per displayed line instead of re-measuring every syllable every frame. A second, throttled-CPU trace pass additionally removed: shader-program re-resolution churn from label texture swaps (`material.needsUpdate` is now only set on a null↔texture transition — swapping between two cached label textures never changes the compiled program), the 3D highway's per-frame `getBoundingClientRect` layout read in its canvas-size self-check (now every 10th frame, still immediate on backing-store change), and the core 60 Hz HUD clock rewriting `textContent` on every tick (now write-on-change, ~1/s). The dominant residual — steady `getParameters` shader-program re-resolution (~4% of throttled main thread) — turned out to be Three r158+'s transparent-DoubleSide two-pass rendering, which sets `material.needsUpdate` twice per object per frame; all 18 of the 3D highway's transparent DoubleSide materials are flat unlit quads (labels, rails, chord frames, lanes), so they now declare `forceSinglePass: true`, eliminating the recompile churn and halving those objects' draw calls.
 
+### Fixed
+- **`playback.loop-api` bridge no longer fires dozens of times per second.** Every `window.feedBack.getLoop()` call recorded a full bridge hit — compat-shim bookkeeping, a `playback:bridge-hit` event, and a diagnostics snapshot rebuild + stringify — so a plugin polling loop state from a HUD tick (note_detect at ~30 Hz) flooded the capability inspector and burned main-thread time even with no song playing. `_recordPlaybackBridge` now throttles per bridge/surface (5 s window): bridge hits are a "surface still in use" signal, not a call counter. The manual A/B loop buttons (`setLoopEnd`) also now emit the same `loop-set` transport event as `setLoop()`, so plugins can react to loop changes via `playback:loop-set` / `playback:loop-cleared` events instead of polling `getLoop()`.
+- **3D Highway: recover from a WebGL context loss instead of crashing on alt-tab.** Switching the active window / alt-tabbing away from the app (most often on Windows) can trigger a GPU context reset; the 3D highway's WebGL renderer had **no `webglcontextlost` handler**, so a lost context was left to escalate into a render-process crash — matching the intermittent "randomly crashes when I change windows" desktop reports. The renderer now binds `webglcontextlost`/`webglcontextrestored` on its own WebGL canvas (`ren.domElement`): the loss is `preventDefault()`'d so the browser keeps the context restorable, `draw()` bails while the context is down so no GL work runs on a dead context, and on restore the viewport is re-applied and rendering resumes (Three re-uploads scene resources on the next frame). Listeners are torn down with the renderer. `plugins/highway_3d` → 3.31.3. Tests: `tests/js/highway_3d_context_loss.test.js`. (The sibling `keys_highway_3d` / `drum_highway_3d` renderers share the same gap — tracked as a follow-up in their repos.)
+- **Guitar Pro 6 (`.gpx`) import no longer fails on every real file.** The GPX BCFS container reader (`lib/gp2rs_gpx.py`) rejected any file whose final sector wasn't a full `0x1000` block — but a real `.gpx`'s BCFZ-declared decompressed size isn't sector-aligned, so the last (small) container file always lands in a partial trailing sector. The bounds check *raised* `GPX BCFS sector pointer out of range (malformed file)` instead of clamping the tail read, so `_load_gpif` threw before `score.gpif` could be extracted and **no GP6 file could be imported into the song editor** (both real test files failed identically — this wasn't file-specific). GP7/GP8 `.gp` files were unaffected — they take the ZIP path, not BCFS, which is why prior GP-import work didn't surface it. The reader now **clamps the final sector read to the buffer end** (the per-file size field trims the padding anyway), matching canonical GPX readers (alphaTab / PyGuitarPro); a sector whose *start* is past the end still raises, preserving the malformed-file guard. Verified against two real GP6 files — both now unpack to valid GPIF with all tracks. Tests: `tests/test_gp2rs_gpx.py` (partial-final-sector round-trip, multi-file container, sector-aligned baseline, and the preserved out-of-range guard).
+- **v3 Songs grid: fixed the scroll stutter that "skips every so many scrolls," up or down.** The virtualized grid rebuilt its **entire** visible window (`grid.innerHTML = …` + a full `wireCards` pass) every time it slid by one row, so each row-boundary crossing was a heavy synchronous frame that stalled the main thread and buffered held-arrow key-repeats into a visible lurch (a tester's "super fast for a second then slowed down") at fixed scroll offsets — in **both directions and regardless of whether the page was already loaded** (the cost was DOM teardown, not fetching, which is why scrolling back up over cached songs hitched too). `renderWindow()` now **reconciles the window in place**: it reuses the card nodes that stay on-screen and builds only the row that enters/leaves (~6 nodes per slide instead of ~60), keyed by absolute index with a real-vs-skeleton + select-mode signature so hole-fills (after a page fetch) and select-mode toggles still rebuild exactly the nodes that changed. `wireCards`'s `data-wired` guard then wires only the freshly-built nodes, so per-slide listener churn drops with it. Follow-up to the stage-2 virtualized grid (got-feedback/feedBack#636 item 3). Frontend-only: `static/v3/songs.js`. Tests: `tests/js/v3_songs_window_recycle.test.js` (window stays `[start,end)` contiguous + in-window node identity reused across a down-then-up scroll; select-mode toggle and rail-seek jump rebuild correctly).
+- **Starter content seeds again (and now ships The Adicts' "Ode to Joy").** `_BUILTIN_STARTER_SOURCES` still listed `beethoven-ode_to_joy.feedpak` after that pack was deleted, and never wired up its replacement `the_adicts-ode-to-joy_vst_cover.feedpak` that landed on disk. The listed-but-missing file made the all-present gate never fire, so **no** starter songs seeded on first run. Synced the manifest to what's on disk (Für Elise, Star Spangled Banner, The Adicts' Ode to Joy). Tests: `tests/test_builtin_starter_seed.py` (the present/unlisted guards were red on `main`).
+- **Edit Metadata now writes into `.feedpak` files, not just legacy `.sloppak` ones.** `lib/songmeta.py`'s suffix gate predated the format rename — core reads both suffixes everywhere else (`sloppak.SONG_EXTS`), but the metadata writer only dispatched on `.sloppak`, so editing a zip-form `.feedpak`'s title/artist/album/year silently fell back to a DB-only update. That looked fine until the next **full library rescan** re-derived metadata from the file and reverted the edit (directory-form packages were unaffected — they dispatch on manifest presence, not suffix). The gate now accepts both package suffixes. Tests: `tests/test_songmeta.py` `TestWriteSongMetadata` (both zip suffixes, mixed-case suffix, directory form, unknown-suffix fallback).
+- **3D Drum & Keys highways now re-frame on fullscreen/layout drift under splitscreen.** The guitar/bass `highway_3d` self-detects when its panel canvas changes size and re-runs `applySize()` every frame, because the splitscreen host overrides `hw.resize` and never calls `renderer.resize()`. The drum and keys highways lacked that fallback — they only re-framed when the host explicitly called `resize(w, h)` — so their panels stayed framed for the pre-fullscreen size while the guitar/bass panels adapted (visible as a too-small, off-center highway after maximizing a split-screen session). Both draw loops now port `highway_3d`'s per-frame drift check: they re-apply on backing-store change (`canvas.width/height`) AND on CSS-box drift (`clientWidth/clientHeight` vs the last applied logical size, throttled to every 10th frame), and reset the tracking in `destroy()` so a reused instance re-frames on the next song. `plugins/drum_highway_3d` → 0.3.1, `plugins/keys_highway_3d` → 0.1.1. Tests: `tests/js/drum_keys_highway_3d_resize_reframe.test.js`.
+- **Tuner: finished the "remove unused settings" cleanup and fixed the sidebar panel position.** The Floating Button and Tuning Visibility settings sections were removed, but their config was still live: `disabledTunings` still filtered the tuner menu (with no UI left to re-enable a hidden tuning — a one-way trap) and `showFloatingButton` still gated the floating launcher. Both are now fully retired — the enforcement paths in `plugins/tuner/screen.js`/`utils/ui.js` and the persistence in `plugins/tuner/routes.py` are gone (and `routes.py` strips the retired keys on write, so stale values are purged). The tuner panel opened from the v3 sidebar Plugins rail popover now anchors beside it via the host's stable plugin-control slot API (falling back to the popover id), is **clamped to the viewport** so it can't open off the right/bottom edge on narrow/short windows, and re-anchors on window resize. `plugins/tuner` → 1.3.3.
+
 ### Added
+- **Host theme read surface — `window.feedBack.theme` + always-present `--fbv-*` tokens — so a plugin feature can render correctly under any theme instead of binding to whichever one the developer happened to see.** The cosmetics applier (`static/v3/theme-core.js`) previously only *applied* themes and emitted `--fbv-*` vars **only while a theme was equipped** (nothing for a plugin to read in the default, un-themed state) with no read/capability API — so plugins reinvented their own theming and a new visual *device* (a glow, a gradient) silently bound to one look. It now: (1) emits the default `fb` palette as **always-present `--fbv-*` on `:root`** (additive — the un-themed look is unchanged; the `fb-*` utilities still use their compiled defaults; this only hands plugins a stable host token to read + derive surfaces from), plus two keystone ROLES the palette lacked — **`on-accent`** (a foreground legible *on* the accent fill — the missing piece behind white-on-accent contrast bugs) and **`focus-ring`**; (2) adds **`window.feedBack.theme`** — `get()` → `{id, isThemed, tokens}`, **`capabilities()`** → `{glow, gradients, motion}` (the device-affordance signal a feature reads to choose a glow vs. a solid device; recolor-only themes report defaults, a theme may opt out via a `capabilities` block in its payload, and `motion` is additionally reduced-motion-gated), and **`prefersReducedMotion()`** (one central matchMedia wrapper); and (3) emits a normalized **`theme:changed`** event (`{id, isThemed, tokens, capabilities}`) from the single `apply()` chokepoint. All additive + feature-detected (the apply side stays on `window.v3Theme`; the read surface is attached defensively so it survives the `feedBack` bus being (re)built by `capabilities.js` regardless of load order). First slice of the host theme contract (got-feedback/feedBack#644) — the framework fix so a plugin UI feature can't accidentally carve itself into a single theme; see `docs/host-theme-contract.md`. Verified by a headless render (apply/unequip intact, defaults present + restored, capability opt-out honored, event payload correct). Tests: `tests/js/v3_theme_read_api.test.js`.
+- **3D Keys Highway: audio-reactive background ambience + score effects (parity slice 4 — completes the keys side of the visual-parity epic).** The gradient sky behind the highway gains the guitar's **background ambience styles** — drifting **Particles**, pitch-class-colored pulsing **Stage lights**, wireframe **Geometric** shapes, or Off — driven by the shared audio-analyser bridge (stems-first on sloppaks, one-shot `#audio` fallback; bass/mid/treble bands, 5 ms cache) with an **Ambience intensity** slider and an **Audio-reactive** toggle. And the score talks back: a **score-FX overlay** canvas draws rising **“+1” pops** off each scored key, an **expanding ring every 10-combo tier**, **milestone bursts** at 25/50/100 streak, and a brief **red flicker** when a 3+ streak breaks (wrong notes and swept misses both count). All settings-gated and on by default (`keys3d_bg_*`), pooled, cleared when idle, torn down with the scene. Butterchurn/image/video remain out of scope. The `#audio` analyser tap is also **shared across visualizers** now (`window.__feedBackAudioTap` — whoever taps first publishes, everyone else adopts, `highway_3d` included), so switching between or splitting the guitar/drum/keys highways can't strand a permanently non-reactive backdrop, and the tap is never created before the page has user activation (a suspended AudioContext would silence live playback). Tests: bg-style id validation + FX defaults (30 total).
+- **3D Keys Highway: the anti-plastic pass — lacquered note gems, glossy piano-black keys, a studio environment, scene themes and a gradient sky (parity slice 3).** The note gems move to `MeshPhysicalMaterial` with a full **clearcoat** (roughness 0.32, clearcoat 1.0/0.18, envMapIntensity 0.9): a sharp lacquer highlight over the colored body instead of the old dead matte surface — glass, not plastic. What sells it is **image-based lighting**: the same procedural PMREM "studio" environment as the drum highway (dark room + cool overhead / warm+cool side light strips, no addon dependency) feeds `scene.environment`, so the **black keys finally read as glossy piano black** (roughness 0.55 → 0.22, envMapIntensity 1.3) with visible strip reflections, whites keep an ivory sheen (0.42/0.55), and the highway floor gets a stage sheen (roughness 0.9 → 0.55, metalness 0.15). The flat background becomes a **vertical gradient** (lighter above the horizon → theme color → darker toward the keyboard), and the guitar highway's **11 scene themes** arrive (same names/values — your look carries across instruments; `default` preserves the original keys palette; pitch-class note/key colors are never themed — themes own the scene, Synthesia colors own the notes). Plus **Cinematic lighting** (ambient 0.55/key 1.3, on by default) and a **Glow strength** slider multiplying the note glow, key approach-glow and the sustain consume-flash (0.5 = stock). All live-applying from the Graphics settings (`keys3d_bg_theme` + `keys3d_bg_*`); the PMREM target and gradient texture are disposed with the scene. Tests: theme-table id parity + default-look preservation + fallbacks (28 total).
+- **3D Drum Highway: audio-reactive background ambience + score effects (parity slice 4 — completes the drum side of the visual-parity epic).** The empty fog band behind the kit gains the guitar highway's **background ambience styles**: drifting **Particles**, palette-colored pulsing **Stage lights**, and slowly-tumbling wireframe **Geometric** shapes (plus Off) — driven by the same audio-analyser bridge the guitar uses (prefers the stems plugin's per-song analyser on sloppaks, falls back to a one-shot `#audio` tap; bass/mid/treble bands with a 5 ms cache), with an **Ambience intensity** slider and an **Audio-reactive** toggle (off = the styles animate on time only; a permanently-tapped `#audio` in a mixed split degrades the same way). The guitar's butterchurn/image/video styles are deliberately out of scope (vendored megabytes / upload plumbing; the style enum is extensible). And your combo finally talks back: a **score-FX overlay** (2D canvas over the WebGL scene, guitar `drawScoreFx` adapted to this plugin's internal scoring) draws rising **“+1” pops** off each scored lane, an **expanding ring pulse every 10-combo tier**, **milestone particle bursts** at 25/50/100 streak, and a brief **red flicker** when a 3+ streak breaks. Everything is settings-gated (Background ambience dropdown + intensity + reactive, Score effects toggle — all on by default, live-applying, `drum_h3d_bg_*` keys), pooled (zero per-frame allocation), and torn down with the scene across kit changes. Tests: bg-style id validation + FX defaults (15 total).
+- **3D Drum Highway: real materials + scene themes (parity slice 3).** The scene gets **image-based lighting**: a procedural PMREM "studio" environment (dark room + three emissive light strips — cool overhead key, warm/cool side fills; no vendored-addon dependency) feeds `scene.environment`, so the cymbals' metalness **finally reads as metal** (retuned to roughness 0.2 / metalness 0.85 / envMapIntensity 1.2 — the old 0.7-metalness look was matte because there was nothing to reflect), drumheads get a satin sheen, and the floor (roughness 0.95 → 0.7) catches the strips without turning into a mirror. **Scene themes arrive** — the same 11 theme names as the guitar highway (Midnight, Charcoal, Deep Purple, Forest, Warm Slate, Deep Focus, Deep Sea, Cathode, Cathode Green, Hearth) retint the background/fog, floor and lane stripes so your look carries across instruments; `default` preserves the original drum palette byte-for-byte, and piece colours stay with the existing Palette picker (themes own the scene, palettes own the kit). Plus **Cinematic lighting** (dimmer ambient / stronger key, on by default), a **Glow strength** slider (0–1, 0.5 = stock) multiplying every emissive base — notes, hit line, snare wires — and a **Lane vibrancy** slider driving stripe/halo/ghost-ring strength (the hit-FX approach highlight stacks on top). Everything applies live from the plugin settings (`drum_h3d_bg_theme` + `drum_h3d_bg_*` keys); the PMREM render target is rebuilt across kit-change renderer recreation and disposed in both teardown paths — and the floor/hit-bar geometry+materials that previously leaked on every kit change are now tracked and disposed too. Tests: theme-table parity with the guitar ids + default-look preservation + fallbacks (13 total).
+- **3D Drum Highway: hit FX — sparks, timing-colored lane flashes, kick camera pulse, approach glow, and open hi-hat notation (parity slice 2).** Striking a pad now *feels* struck: a pooled additive **spark burst** fires at the lane (ported from the guitar highway's Points-cloud system, pool 160), colored by **timing** — on-time green, early cyan, late amber (same `_timingHex` vocabulary as `highway_3d`, classified against the ±50 ms hit window with the inner 40% reading as on-time); with **Streak feedback** on, bursts grow with your combo. The **lane flash** feedback that was removed when note-recoloring landed is resurrected properly: pooled additive quads with a soft gaussian falloff light up the struck lane at the hit line (timing-colored; red for wrong-pad hits), and a **kick** hit fires triple amber bursts across the bar plus a subtle **camera dip + amber floor wash** that decays exponentially. Lanes also glow ahead of time: each stripe brightens as its next note approaches the hit line, so the eye is led to where the next hit lands. **Open hi-hat finally renders distinctly** — `hh_open` chart hits get a thin warm ring around the cymbal gem (standard notation's "o"), closing the long-standing TODO; the flag is orthogonal to accents/ghosts/flams so combined cues stack. All of it is settings-gated (Graphics → Hit sparks / Timing colours / Streak feedback / a 0–1 **Hit feedback intensity** slider driving flashes, approach glow and the kick pulse; everything on by default, `drum_h3d_bg_*` keys, live-applying) and GPU-frugal: every new visual is pooled or shares geometry/materials — zero per-note allocation on top of the per-frame notes rebuild, all registered in both dispose paths (kit-change renderer recreation included). Tests: timing-classifier boundaries + FX defaults added to `plugins/drum_highway_3d/tests/data_layer.test.js` (10 total).
+- **3D Keys Highway: hit FX — vibrant note gems, timing-colored sparks, and a hit-line that reacts to your playing (parity slice 2).** The washed-out note look is gone: gem opacity is now driven by a **Note vibrancy** slider (default 0.85 → opacity 0.92, up from a fixed 0.8; lane guides scale with it too, live-applying without a chart rebuild) and the resting emissive glow rises 0.08 → 0.22, so the falling notes finally read saturated against the dark floor. Scored key presses fire a pooled additive **spark burst** at the struck key (guitar-highway port, pool 96) **colored by timing** — on-time green, early cyan, late amber, classified against the ±100 ms window with the inner 40% reading as on-time (the timing delta is recovered from the matched note's key, so `judgeHit`'s tested contract is untouched); the per-pitch-class flame sprite keeps its identity color so pitch and timing stay separate signals. With **Streak feedback** on, bursts grow with the combo. The **hit line kicks brighter** for a beat on every scored press (exponential decay, scaled by a 0–1 **Hit feedback intensity** slider). All new controls live in the plugin's Graphics settings (on by default, `keys3d_bg_*` keys, live-applying), and the spark pool is disposed with the scene like every other GPU resource. Tests: timing-classifier boundaries, the noteKey time round-trip that the delta recovery relies on, and the new FX defaults (26 total).
+- **3D Drum Highway: bloom glow + adaptive-resolution support — the first slice of visual parity with the guitar highway.** The drum highway now renders through the same post-processing path as `highway_3d`: an `UnrealBloomPass` (strength 0.65, radius 0.5, threshold 0.82 — high, so only emissive/bright surfaces bleed) on a multisampled HalfFloat target with ACES filmic tone mapping, so the white hit-line bar and proximity-lit notes get a real glow instead of a flat emissive tint. **On by default**, with a new **Graphics → "Glow (bloom)"** toggle in the plugin settings (`drum_h3d_bg_bloom`, applies live, no reload); if the vendored postprocessing addons can't load (older self-hosted core), the plugin silently falls back to the direct render path. The plugin also now honors the host's **adaptive render scale** (`bundle.renderScale` — the Quality/"Min res" controls that the guitar highway already respected), multiplying it into the device pixel ratio, and caps DPR at 1.25 when more than one viz instance is live (splitscreen) so two panels don't double the GPU fill cost. Groundwork for the rest of the parity series: an FX-settings scaffold (`FX_DEFAULTS`/`readFxSettings`/`window.drumH3dSetFx`, `drum_h3d_bg_*` localStorage keys) that the sparks/themes/backgrounds PRs extend, plus a first node test suite for the plugin (`plugins/drum_highway_3d/tests/data_layer.test.js` — vm-loaded like the keys plugin's, covering the hit-variant precedence, the Auto-mode steal-guard predicate, and FX defaults; 8 tests, runs in CI via the `plugins/*/tests/*.test.js` glob).
+- **3D Keys Highway: sharp HiDPI rendering, bloom glow, a live combo HUD, and a graphics settings panel — the first slice of visual parity with the guitar highway.** The biggest single fix is resolution: the plugin never called `setPixelRatio`, so on HiDPI/retina displays (and Windows display scaling) it rendered at CSS resolution and was upscaled — soft and aliased. It now multiplies the device pixel ratio (capped at 2, or 1.25 when two viz panels are live in splitscreen) with the host's **adaptive render scale** (`bundle.renderScale`, the Quality/"Min res" controls), exactly like `highway_3d`. On top of that: the same **bloom** post-processing path as the guitar highway (UnrealBloomPass 0.65/0.5/0.82 on a multisampled HalfFloat target + ACES tone mapping — the cyan hit-line, hit flames and the sustain "consume" glow finally bleed light instead of reading flat), **on by default** with a graceful direct-render fallback when the vendored addons can't load. The plugin gains its first **settings panel** (`settings.html`, Settings → graphics category, `"settings"` block in plugin.json) with a live-applying "Glow (bloom)" toggle (`keys3d_bg_bloom`), plus the FX scaffold (`FX_DEFAULTS`/`readFxSettings`/`window.keys3dSetFx`, `keys3d_bg_*` keys) the later parity PRs extend. And the score state the plugin was already tracking is finally visible: a **combo / accuracy / best-streak HUD** overlay (drum-highway pattern), shown only while a MIDI keyboard session is wired so it never renders a frozen 0× combo. Tests: `plugins/keys_highway_3d/tests/fx_settings.test.js` (defaults, localStorage overrides + type coercion, setter persist/dispatch/unknown-key guard; 3 tests alongside the existing 20).
+- **The 3D Drum Highway and 3D Keys Highway are now bundled core plugins** (`plugins/drum_highway_3d/`, `plugins/keys_highway_3d/`), imported from their former standalone repos (`feedBack-plugin-drum-highway-3d`, `feedBack-plugin-keys-highway-3d`, now archived) via `git subtree` so their history is preserved. They join the other in-tree plugins-as-plugins: the loader treats them identically to user-installed ones, both are marked `"bundled": true` in their manifests, and `.gitignore` gains the matching `!plugins/<id>/` exceptions. This puts all three 3D highways (guitar, drums, keys) in one repo ahead of a visual-parity pass that ports the guitar highway's polish (bloom, sparks, themes, reactive backgrounds) to the other two — shared helper code and theme tables can now be reviewed and kept in sync in a single place. The keys plugin's existing node test suite is wired into CI (the JS test step gains a `plugins/*/tests/*.test.js` glob, +20 tests), and `static/tailwind.min.css` is regenerated since the core Tailwind build scans `plugins/**`. One deliberate behavior change ships with the bundling: the drum highway's Auto-mode predicate is **narrowed** (it used to claim any pack with `has_drum_tab` — a pack-level flag — which, now that the plugin ships to everyone and sorts before `highway_3d` in first-match-wins Auto order, would have stolen full-band packs from the guitar highway even on Lead/Bass arrangements; it now claims only drum arrangements, or packs nothing more specific can render). Picking the drum highway manually from the viz picker is unchanged.
 - **The tuner now tracks what tuning your instrument is *actually* in, so it prompts you to retune in BOTH directions — down to a song's tuning, and back up when the next song needs it.** The coverage check used to compare each song against your fixed instrument-profile tuning, so it only ever prompted you *away* from "home" (e.g. E → Drop C#) and stayed silent coming back (Drop C# → E), even though you'd physically retuned. It now reads the host's live **per-instrument working tuning** (`window.feedBack.workingTuning`) — what your selected instrument is currently in — so coverage is measured against your *actual* tuning and fires both ways. When you clear an auto-opened tuner, the tuner publishes that song's tuning as your instrument's live working tuning (`assumed` — an explicit "I tuned / Skip" refines it in a later PR), so the next song is judged against where you now are. **Per-instrument** — your guitar's and bass's tunings are tracked separately (keyed like the selector), so switching instruments uses the right one. Feature-detected: on a host without the working-tuning capability it falls back to the static `/api/settings` tuning (today's behavior). `plugins/tuner/screen.js` (`_playerTuning` reads `workingTuning` keyed by the selected instrument; `_publishWorkingTuning` writes on clear). Builds on the host `workingTuning` foundation (PR 1 of the series) + the instrument→chart routing (PR 2). Tests: `tests/js/tuner_auto_open.test.js` (both-directions coverage via a live Drop-D working tuning; publish-on-clear targets the right instrument slot) — 29 pass.
 - **`.jsonc` support for feedpak data files** (feedpak-spec §8, FEP #3 / PR #13). Hand-edited packs may now use the `.jsonc` extension (JSON with C-style `//` line and `/* */` block comments) for any data file the manifest points at — arrangements, notation sidecars, `drum_tab`, `song_timeline`, `lyrics`, and `keys`. New shared `lib/jsonc.py` provides `parse_jsonc(text)` + `load_json(path)` (auto-detects `.jsonc` by suffix, string-aware so comment-like text inside JSON string values is preserved) and is now used by every reader in `lib/sloppak.py` (six side-file sites) and `scripts/lift_keys_notation.py` (three arrangement / song_timeline read sites). The strip regex mirrors the reference validator in `feedpak-spec/tools/validate.py`. This is an additive (MINOR) change: `.jsonc` is opt-in, so any pack that keeps its data files as `.json` is unaffected and needs no regeneration. Note that a `.jsonc` file containing real comments only loads on a reader that implements §8 — a pre-this-change reader calls bare `json.loads` and fails on the comments rather than ignoring them, so don't hand out `.jsonc` packs to older hosts. Tests: `tests/test_sloppak_jsonc_load.py` (covers all six side-file types, the lift helper, and the string-boundary preservation rule end-to-end).
 - **The highway now loads the part that matches your selected instrument — a bass player gets the Bass arrangement, not the default Lead/guitar chart.** When you open a song without an explicit arrangement, the WebSocket handler (`server.py` `highway_ws`) reads your selected `instrument` from `config.json` (the same file it already reads for your default-arrangement preference) and routes to the matching part: **bass → the Bass arrangement**; guitar — and any unknown/future instrument (drums, keys) — falls through to the existing preference/most-notes default, which already lands on a guitar part. Previously the instrument selector only fed the tuner, so a bass player was handed a guitar chart (and a tune/coverage check then compared a 4-string bass against a 6-string part). An **explicit arrangement request always wins** (a manual arrangement switch is untouched), and a bass player's saved default-arrangement preference is still honored **within** the bass parts (so a preferred `Bass 2` / `Alt. Bass` wins over the canonical Bass), so this only changes the *default* part chosen on load. Server-only — every launch path already flows through the WS, so there's no client change. This is the instrument↔chart-routing piece the working-tuning series leans on (otherwise coverage compares across instruments). Tests: `tests/test_highway_ws_instrument_routing.py` (bass→Bass, bass-honors-pref, bass-no-bass-part→guitar, guitar→default, explicit-wins).
@@ -54,10 +203,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **v3 library: exact artist/album filters + scroll/page-depth restore** (feedBack#857). The v3 Songs toolbar gains Artist and Album dropdowns (Album populates from the selected artist and stays disabled until one is chosen), backed by new exact, case-insensitive (`COLLATE NOCASE`) `artist` / `album` query params threaded through `MetadataDB._build_where` → `query_page` / `query_artists` / `query_stats` and the `/api/library`, `/api/library/artists`, `/api/library/stats` endpoints (the free-text `q` search stays fuzzy and composes with the exact filters). The artist/album catalog is fetched independently of the active artist/album selection so the dropdowns always list the full set for the current provider/search. The toolbar is now sticky so filter controls stay reachable when browsing deep libraries, and returning from the player restores the previous scroll position **and** the loaded infinite-scroll page depth via a `sessionStorage` snapshot keyed by a filter/sort/view state hash (invalidated whenever those change, so a filter change still resets to the top). Tests: `tests/test_library_filters.py` (backend artist/album filters), `tests/js/v3_songs_scroll.test.js` (state-hash + snapshot helpers).
 
 ### Fixed
+- **GP8 multi-staff (piano/keys) tracks now import both hands — the bass stave was being silently dropped, and hand-splits landed on the wrong hand.** A GP8 grand-staff keyboard part is one `<Track>` with two `<Staff>` entries, and `MasterBar/Bars` lists one bar id per **stave**, not per track (`lib/gp2rs_gpx.py`). Two bugs fell out of assuming one stave per track: (1) the bar-column lookup used a raw `enumerate(Tracks)` index, so every track *after* a multi-stave track read the wrong column; (2) the string-tuning parse scanned all `.//Property` descendants and let the last stave's `<Tuning>` overwrite the first, so a treble note indexed against the 5-entry bass tuning fell out of range in `_note_midi` and was **dropped without a trace**. The importer now advances a bar-column counter by each track's stave count, reads tuning **per stave** (with a per-staff fall-back to the track-level property so an untuned staff never yields empty pitches), and folds **every** extra stave's notes into the arrangement (not just stave 1), keeping the `note_count` import-preview honest. A grand-staff track is now classified as keys end-to-end so the stave-0 and folded stave-1+ notes share one encoding. Separately, `notation_lift.split_hands` no longer forces a hard middle-C split when doing so produces a physically unplayable hand (e.g. a bass note under an Em7-shape voicing dipping below C4 would put a 19-semitone span in one hand) — it uses the middle-C boundary only when both resulting hands are within `HAND_SPLIT_SPAN_SEMITONES`, else falls back to the largest-gap heuristic. The GPX LH/RH pair merge and the GP8 stave fold now share one `_collect_column_notes` / `_merge_lh_notes` pair so the two formats can't drift in tie/timing/dedup handling. Companion editor change: got-feedback/feedBack-plugin-editor#38. Tests: `tests/test_gp2notation.py` (grand-staff fold + bar-column offset), `tests/test_notation_lift.py` (both middle-C split cases). Follow-up: `lib/gp_autosync.py` still carries the pre-fix bar-column + tuning logic (CLI/tests only, no production caller).
 - **Tuner auto-open is now opt-in and persists instead of flashing open-then-shut.** When you entered a song (or switched arrangement) whose tuning differed from the last, the tuner auto-opened and — for some testers — vanished ~1s later (reported macOS+Windows, 0.3.0). Root cause: the tuner closes itself on `song:play` (`plugins/tuner/utils/ui.js` — you don't tune while playing), so a **song switch** fired autoplay → `song:play` → the just-auto-opened tuner closed; an **arrangement switch** (which never arms autoplay) had no `song:play`, so it stayed open — exactly why two testers saw opposite behaviour (it wasn't the mic). Now: (1) the feature is a **new opt-in setting** ("Auto-open on tuning change", in the tuner's Settings panel, persisted as `autoOpenOnTuningChange`, **default OFF**); (2) an **auto**-opened tuner *persists* — it ignores the autoplay `song:play`, stray outside-clicks, and same-screen re-emits, closing only via the new in-panel **`×`** / **"Skip"** buttons or when you leave the song. A *manually* opened tuner keeps its classic click-away / play-to-close behaviour. The panel previously had no in-box close at all; this adds one (`×` + contextual Skip). All in the tuner plugin (`routes.py` config, `screen.js` gate + persist, `utils/ui.js` buttons + `song:play` guard, `settings.html` toggle) — **no core `app.js` changes**. Tests: `tests/js/tuner_auto_open.test.js` (opt-in gate, `{ auto: true }` persist mode, play/click-proofing). **Default (opt-in vs opt-out) is teed up for Byron to decide — flip one boolean.**
 - **Tuner auto-open is now tuning-coverage-aware — extended-range players aren't nagged for songs their instrument already covers.** With the opt-in auto-open on, it now prompts only when your **current physical tuning** (from your instrument selection in Settings) doesn't already cover the song. FeedBack is tune-to-song — the highway draws tab in the song's tuning — so the check aligns the song's open-string tuning string-for-string against your instrument: an **8-string F♯-standard** player gets **no** prompt for a 6- or 7-string standard song (its top strings already match those tunings), while a song needing an open string you don't have (e.g. a **Drop-A 7-string**, whose low A isn't an open string on an F♯ 8-string) **still** prompts. A whole-instrument reference difference also prompts — A440 vs A432, or an octave-down `centOffset` (which the auto-open now accounts for; it was previously ignored). The player's instrument is read from core **`/api/settings`** (the v3 instrument selector — a stable physical reference, not the tuner's song-tracking selection); when nothing's declared or the lookup is unavailable it falls back to a conservative prompt, so a real retune is never silently skipped. **v3-only** (the instrument selector is v3). All in the tuner plugin (`plugins/tuner/screen.js`) — **no core changes**. Tests: `tests/js/tuner_auto_open.test.js` (covered vs uncovered, the Drop-A case, reference-pitch mismatch, contiguous alignment). _Follow-up (E1.6): a passive "different tuning" badge cue that names the string(s) to retune, plus the splitscreen / no-usable-input guards._
 - **The tuner badge now passively flags when a song needs a different tuning — and names the retune.** Building on the coverage check: when you enter a song your current instrument doesn't cover, the topbar tuner badge gets an amber ring and a tooltip that **names the change** — e.g. *"retune B→A"* for a Drop-A song on an F♯ 8-string, or *"the reference pitch"* for an A440-vs-A432 mismatch. It's purely **advisory** (it never auto-opens the panel — tap the badge to tune), recomputed on `song:ready` and cleared when a new song loads or you leave the player. The retune diff comes from the tuner plugin's coverage report (`window._tunerAutoOpen.coverageReport` → `{ covered, retune: [{ from, to }], reference, cantCover }`); the cue is CSS-free (an inline ring + native tooltip — no Tailwind rebuild) and no-ops when the tuner plugin isn't installed. **v3-only.** Touches `static/v3/badges.js` (the cue) + `plugins/tuner/screen.js` (the report). Tests: `tests/js/tuner_auto_open.test.js` (the report names the strings; reference mismatch; the badge wiring). _(The splitscreen-suppress and no-usable-input guards move to the playback-gate stage, where they matter for its no-trap rule.)_
 - **Tuner auto-open can now gate playback until you've tuned — the "tune before you play" model — via a new core `holdAutoplay()` hook.** With the opt-in auto-open on, when a song needs a retune the tuner opens and **playback waits** for your choice — **Skip** (you've tuned → play, and record the song's tuning as your instrument's current working tuning), **Back to library** / **Esc** (leave the song; a gated retune is never a one-way trap), or press **Play** (always wins). For an auto-open the in-panel **×** is dropped — Skip / Back to library / Esc are its dismiss surface. Previously the song played with the tuner overlaid; now it holds — which also definitively kills the original flash, since autoplay's `song:play` can't fire while playback is held. Implemented as a small **core hook** `window.feedBack.holdAutoplay()` (mirrors the existing `holdAutoExit()`): a plugin claims it **synchronously on `song:loading`** (so it beats the `song:ready` autostart), and `release()` — or a **12-second fail-open backstop** — runs the deferred start. **Generation-guarded** (a new song invalidates a stale hold) and **fail-open** (a wedged or crashed plugin can never permanently strand a song); **manual Play always wins** (it doesn't flow through the autostart path). The tuner claims the gate only when the feature is on, and **releases it the instant** it decides not to open (song already covered / tuning unchanged) or when you Skip. Touches core `static/app.js` (the hook + an autostart refactor) and the tuner plugin (`plugins/tuner/screen.js` — the claim/release; `plugins/tuner/utils/ui.js` — the Skip / Back-to-library buttons, × dropped on auto-open); the hook is generic and shell-agnostic (a test asserts `app.js` still doesn't reference the tuner's internals). Tests: `tests/js/tuner_auto_open.test.js` (claim on `song:loading`, release on dismiss, feature-off no-claim, the core hook + fail-open backstop, the Skip / Back-to-library / Esc escape-hatch) + a `speed_reset.test.js` stub. ⚠️ **Needs a manual smoke-test before shipping** — this is a core playback change; verify on desktop that the tuner mic doesn't contend with note_detect's scoring input (ASIO/exclusive mode), per the design charrette.
+- **v3 Songs List View: favoriting a song now turns the heart red immediately (no re-search needed).** In the tree / "List View" (Songs → List → expand an artist), clicking the heart flipped the glyph ♡→♥ but it stayed dim grey until you re-searched the library — reported on macOS + Windows, open since 0.3.0 / 2026-06-25. One shared `wireCards()` `[data-fav]` handler (`static/v3/songs.js`) serves both the grid card and the List-View row, but the two render with different idle colours — grid `text-white`, List View `text-fb-textDim` — and the handler only ever removed the grid's `text-white`. So in List View the row kept `text-fb-textDim` alongside the freshly-added `text-fb-accent`, and the dim class won by CSS source order (glyph changed, colour didn't). Each heart now declares its idle colour via a `data-fav-idle` attribute and the handler swaps exactly that class, so only one colour class is ever present; the handler also writes the new state back onto the in-memory song model so a re-render / virtualized-grid recycle agrees instead of reverting. Tests: `tests/js/v3_favorites_toggle.test.js`.
+- **v3 Songs A–Z rail: taps now land reliably, a drag releases exactly on the let-go letter, and the rail is large enough to hit on hi-res displays.** Follow-up to the rail's debut (#634); three bugs reported on macOS + Windows (0.3.0, 2026-06-29): a tap often did nothing ("clicked O, nothing happened"), a drag "got you kind of there but where you release isn't where you get sent," and the rail was "way too small" at 1440p and didn't scale with resolution. Root causes & fixes, all in `static/v3/songs.js` + `static/v3/v3.css` (`bindRailOnce`/`jumpToLetter`/`.v3-azrail`): (1) **taps** — `pointerdown` calls `setPointerCapture`, after which the browser **retargets the follow-up `click` to the rail container**, so the click handler's `closest('.v3-azrail-letter')` resolved `null` and a plain tap (no `pointermove`) had no other path → no-op. The jump is now driven from `pointerdown` itself (seek on press); the `click` handler is reduced to **keyboard activation only** (`e.detail === 0`, Enter/Space). (2) **drag precision** — every letter crossed fired `jumpToLetter` with `behavior:'smooth'`; stacked smooth-scroll animations over the virtualized grid lagged and settled short of the release. `jumpToLetter(letter, smooth)` now scrolls **instantly while scrubbing** (`'auto'`) and only animates discrete taps/keyboard jumps, so the grid tracks the finger and the release lands on the let-go letter. (3) **size** — the letters were a fixed `.62rem` glued at `right:2px` (~13px-tall target on the screen edge); they now scale with the viewport (`clamp(.72rem, 1.4vh, 1.05rem)`), sit off the edge with taller/wider equal-width hit targets and a hover/active highlight so the scrub target is visible. Keyboard arrow-nav + the present-letter gating are unchanged. Reported by =Scr4tch= and MajorMokoto. Tests: `tests/js/v3_az_rail.test.js` (pointerdown-seek, keyboard-only click guard, instant-vs-smooth scroll).
 - **v3 player: opening another rail popover now closes the Section Practice popover (no more two stacked popovers).** Opening the **Practice** pill's popover and then clicking a different player-rail icon (e.g. **Plugins**) left the Practice popover open underneath the new one — looked broken (reported on macOS, 0.3.0 / 2026-06-28). The rail icons call `e.stopPropagation()` in their click handler (`static/v3/player-chrome.js`), which killed bubbling before it reached the Practice popover's outside-click dismiss bound on `document`. The dismiss (`_installSectionPracticeDismiss` in `static/app.js`) now binds in the **capture phase**, which runs before the target's handler so a descendant's `stopPropagation()` can't swallow it — mirroring how the audio-mixer popover already dismisses. Esc handling stays bubble-phase (the player's Escape-to-exit ordering is unchanged). v2 shares `app.js` and is only hardened (no rail `stopPropagation` there). Tests: `tests/js/section_practice_dismiss.test.js`.
 - **v3 UI no longer lets you accidentally text-select the chrome.** Dragging or double-clicking across the interface used to marquee-highlight buttons, labels, the sidebar, the transport, and the note-highway HUD — which looks broken (reported on Mac + Windows). The v3 shell now defaults to `user-select: none` on `html` (`static/v3/v3.css`), then opts *content* back in — so chrome is non-selectable but the text you actually copy still works. Decided by a 4-lens panel (UX / accessibility / dev-ops / plugin-ecosystem); the guardrails are deliberate: **form fields are always re-enabled** (never break the caret / IME — no `* { user-select:none }`, which trips a WebKit input bug); **plugin screens (`.screen[id^="plugin-"]`) stay selectable by default** so a plugin's copyable text (lyrics, chord names, results) — including community plugins that don't know about this — isn't silently locked; and **core read-only content opts back in by container** via a new hand-authored **`.fb-selectable`** class — applied to the whole **Settings** panel (paths, device names, version, diagnostics, About — answering "is settings still copyable?": yes), the **now-playing song metadata** (with `pointer-events` re-enabled so the HUD text is actually reachable), and the focused **modals / dialogs / toasts / scan banner** that carry copyable errors, IDs, paths, and file names. It's cosmetic only (it protects nothing) and never used to lock copy-worthy text — errors, IDs, paths, versions, and metadata stay selectable per WCAG 2.2 (copy-paste as a permitted mechanism). Dense card lists (library grid, dashboard, profile) stay non-selectable by design — making them selectable would reintroduce the marquee-mess across cards. **v3-only** (v2 unchanged); plain CSS, no Tailwind rebuild; no desktop changes (standard OS-framed window). Plugin authors: `.fb-selectable` is documented in `CLAUDE.md` for re-enabling copyable content rendered outside a plugin screen. Tests: `tests/js/v3_user_select_policy.test.js`.
 - **Input-setup wizard no longer collapses an audio device's driver-type variants into one entry.** On Windows the desktop engine enumerates the same interface once per host API (ASIO / Windows Audio / DirectSound), and the wizard's audio picker (`plugins/input_setup/screen.js`) de-duped the source list by display **label** — so the variants (which share a name) collapsed to a single choice, silently keeping whichever sorted first (often *not* the low-latency ASIO one the player wants). The audio-input capability already collapses true duplicates by `logicalSourceKey` (`_visibleInputSources` in `static/capabilities/audio-session.js`), and the variants each have a **distinct** key, so the wizard's extra label-collapse was redundant for real dupes and destructive for these — it also could drop the variant that was actually `selected`. Removed it; the picker now lists every selectable input. Pairs with feedBack-desktop's change to label each source with its driver type (e.g. "Focusrite (ASIO)") so the now-distinct entries are legible.

CLAUDE.md

@@ -117,19 +117,21 @@ Notes:
 
 **Frontend scripts** — `screen.js` runs in the global scope via a `<script>` tag. It can access `window.playSong`, `window.showScreen`, `window.createHighway`, the `<audio>` element, and the `window.feedBack` event emitter.
 
+**ES-module plugins (`scriptType:"module"`)** — a plugin may instead ship a native ES-module graph with **no build step**: set `"scriptType": "module"` in `plugin.json`, make `screen.js` a one-line `import './src/main.js'`, and put the module tree under `src/` (served by the sandboxed `/api/plugins/<id>/src/{path}` route). The host injects it as `<script type="module">`, whose `onload` fires only after the whole static-import graph evaluates — so the loader's completion-by-`onload` + `_loadingPluginId` + `playSong` wrapper-chain ordering all hold. Resolve your own asset URLs (worklets, WASM) with `import.meta.url` — `document.currentScript` is `null` in a module. Module top-level code does **not** re-run when the user re-enters the screen at the same version (the host loads screen.js once and `showScreen` re-injects nothing), so keep per-visit re-init in a `screen:changed` handler, exactly as classic plugins do. Classic global-scope `screen.js` remains fully supported. See `docs/plugin-modules.md`.
+
 **The playSong wrapper chain** — Plugins commonly wrap `window.playSong` to hook into song playback. Plugins load alphabetically, so the last-loaded (alphabetically later) wrapper runs first, while the alphabetically first plugin runs closest to the original. Be aware that `await` calls in inner wrappers yield to the event loop — WebSocket messages can arrive before outer wrappers finish setup.
 
 ## Plugin Best Practices
 
 ### 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:
@@ -155,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
 
@@ -564,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

Dockerfile

@@ -47,11 +47,11 @@ RUN cmake -S /tmp/vgmstream -B /tmp/vgmstream/build \
 # and update FFMPEG_RELEASE + both SHA256 ARGs below.
 FROM alpine:3.20 AS ffmpeg-fetcher
 ARG TARGETARCH
-ARG FFMPEG_RELEASE=autobuild-2026-06-19-23-17
-ARG FFMPEG_BUILD_AMD64=ffmpeg-n7.1.4-145-g4cbf7a4b3d-linux64-gpl-7.1.tar.xz
-ARG FFMPEG_BUILD_ARM64=ffmpeg-n7.1.4-145-g4cbf7a4b3d-linuxarm64-gpl-7.1.tar.xz
-ARG FFMPEG_SHA256_AMD64=03c0431e0d1aa75cc343d83bda9d2d4cd8eaa37f35b7b93465e9ff6864f5d7f8
-ARG FFMPEG_SHA256_ARM64=74629b88342fd94eea12b7481c8b8560ca6d497744123c0a27b98f39d767fd93
+ARG FFMPEG_RELEASE=autobuild-2026-07-03-13-21
+ARG FFMPEG_BUILD_AMD64=ffmpeg-n7.1.5-1-g7d0e842004-linux64-gpl-7.1.tar.xz
+ARG FFMPEG_BUILD_ARM64=ffmpeg-n7.1.5-1-g7d0e842004-linuxarm64-gpl-7.1.tar.xz
+ARG FFMPEG_SHA256_AMD64=1390e1c320a1e38dae106d6d0b05a6f08eb8b30f732bc1aa0d45a4aa17f13795
+ARG FFMPEG_SHA256_ARM64=53b2e30df04d56932b7782234c9bc97abfe0bb242192ca50346474a41b100ab0
 RUN apk add --no-cache curl xz \
     && arch="${TARGETARCH:-$(apk --print-arch)}" \
     && case "$arch" in \
@@ -94,9 +94,9 @@ FROM python:3.12-slim
 # Re-declare the ffmpeg ARGs so their values are available to LABEL below.
 # ARG values don't cross stage boundaries in multi-stage builds; defaults
 # must be repeated here to take effect when no --build-arg is supplied.
-ARG FFMPEG_RELEASE=autobuild-2026-06-19-23-17
-ARG FFMPEG_BUILD_AMD64=ffmpeg-n7.1.4-145-g4cbf7a4b3d-linux64-gpl-7.1.tar.xz
-ARG FFMPEG_BUILD_ARM64=ffmpeg-n7.1.4-145-g4cbf7a4b3d-linuxarm64-gpl-7.1.tar.xz
+ARG FFMPEG_RELEASE=autobuild-2026-07-03-13-21
+ARG FFMPEG_BUILD_AMD64=ffmpeg-n7.1.5-1-g7d0e842004-linux64-gpl-7.1.tar.xz
+ARG FFMPEG_BUILD_ARM64=ffmpeg-n7.1.5-1-g7d0e842004-linuxarm64-gpl-7.1.tar.xz
 
 # Apply latest security updates to base packages (clears glibc deb13u3 and
 # similar). Done first so any subsequent installs resolve against the

README.md

@@ -1,46 +0,0 @@
-# fee[dB]ack
-
-## Plugins
-
-| Plugin                                                                             | Description                                                                                                                                                                                                                      | Install                                                                 |
-|------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|
-| [Create from Tab](https://github.com/got-feedback/feedBack-plugin-ug)             | Search Ultimate Guitar for GP tabs and convert to playable songs                                                                                                                                                                 | `git clone ...feedBack-plugin-ug.git ultimate_guitar`                  |
-| [Import Tab](https://github.com/got-feedback/feedBack-plugin-tabimport)           | Drag and drop Guitar Pro files to create songs                                                                                                                                                                                   | `git clone ...feedBack-plugin-tabimport.git tab_import`                |
-| [Practice Journal](https://github.com/got-feedback/feedBack-plugin-practice)      | Auto-track practice time, speed, loops. Dashboard with charts                                                                                                                                                                    | `git clone ...feedBack-plugin-practice.git practice_journal`           |
-| [Setlist Builder](https://github.com/got-feedback/feedBack-plugin-setlist)        | Create ordered playlists with sequential playback                                                                                                                                                                                | `git clone ...feedBack-plugin-setlist.git setlist`                     |
-| [Metronome](https://github.com/got-feedback/feedBack-plugin-metronome)            | Audible click and visual beat flash synced to song tempo                                                                                                                                                                         | `git clone ...feedBack-plugin-metronome.git metronome`                 |
-| [Tone Player](https://github.com/got-feedback/feedBack-plugin-tones)              | View amp/pedal/cab signal chains with gear artwork                                                                                                                                                                               | `git clone ...feedBack-plugin-tones.git tones`                         |
-| [Fretboard View](https://github.com/got-feedback/feedBack-plugin-fretboard)       | Live fretboard overlay showing active notes in real-time                                                                                                                                                                         | `git clone ...feedBack-plugin-fretboard.git fretboard`                 |
-| [Tab View](https://github.com/got-feedback/feedBack-plugin-tabview)               | Scrolling guitar tablature notation via alphaTab                                                                                                                                                                                 | `git clone ...feedBack-plugin-tabview.git tab_view`                    |
-| [MIDI Amp Control](https://github.com/got-feedback/feedBack-plugin-midi)          | Auto-switch amp/modeler presets via MIDI on tone changes                                                                                                                                                                         | `git clone ...feedBack-plugin-midi.git midi_amp`                       |
-| [Section Map](https://github.com/got-feedback/feedBack-plugin-sectionmap)         | Color-coded song structure minimap with clickable navigation                                                                                                                                                                     | `git clone ...feedBack-plugin-sectionmap.git section_map`              |
-| [Arrangement Editor](https://github.com/got-feedback/feedBack-plugin-editor)      | DAW-like visual editor for creating and editing song note charts                                                                                                                                                                 | `git clone ...feedBack-plugin-editor.git editor`                       |
-| [MIDI Capo](https://github.com/masc0t/slopsmith-plugin-midi-capo)                  | MIDI capo control for real-time transposition                                                                                                                                                                                    | `git clone ...slopsmith-plugin-midi-capo.git midi_capo`                 |
-| [Note Detection](https://github.com/got-feedback/feedBack-plugin-notedetect)      | Real-time pitch detection and scoring against highway notes                                                                                                                                                                      | `git clone ...feedBack-plugin-notedetect.git note_detect`              |
-| [Find More](https://github.com/masc0t/slopsmith-plugin-find-more)                  | Search for more songs by the same artist                                                                                                                                                                                         | `git clone ...slopsmith-plugin-find-more.git find_more`                 |
-| [Piano Highway](https://github.com/got-feedback/feedBack-plugin-piano)            | Scrolling piano/keyboard view for Keys arrangements with MIDI input                                                                                                                                                              | `git clone ...feedBack-plugin-piano.git piano`                         |
-| [Studio](https://github.com/got-feedback/feedBack-plugin-studio)                  | Collaborative band recording and multi-track mixing                                                                                                                                                                              | `git clone ...feedBack-plugin-studio.git studio`                       |
-| [Drum Highway](https://github.com/got-feedback/feedBack-plugin-drums)             | Lane-based drum highway with MIDI drum pad input and built-in sounds                                                                                                                                                             | `git clone ...feedBack-plugin-drums.git drums`                         |
-| [Invert Highway](https://github.com/masc0t/slopsmith-plugin-invert-highway)        | Flip the highway note direction                                                                                                                                                                                                  | `git clone ...slopsmith-plugin-invert-highway.git invert_highway`       |
-| [Jumping Tab](https://github.com/renanboni/slopsmith-plugin-jumpingtab)            | Yousician-style 2D horizontal tab with trajectory arcs and hopping ball                                                                                                                                                          | `git clone ...slopsmith-plugin-jumpingtab.git jumpingtab`               |
-| [Step Mode](https://github.com/got-feedback/feedBack-plugin-stepmode)             | Step-by-step practice mode — highway freezes at each note until played (via Note Detection) or Space                                                                                                                             | `git clone ...feedBack-plugin-stepmode.git step_mode`                  |
-| [Lyrics Sync](https://github.com/got-feedback/feedBack-plugin-lyrics-sync)        | Generate synced LRC lyrics from text + vocals stem via Whisper alignment                                                                                                                                                         | `git clone ...feedBack-plugin-lyrics-sync.git lyrics_sync`             |
-| [Lyrics Karaoke](https://github.com/got-feedback/feedBack-plugin-lyrics-karaoke)  | Per-syllable karaoke pitch ribbon for sloppak songs (Whisper alignment + librosa pYIN)                                                                                                                                           | `git clone ...feedBack-plugin-lyrics-karaoke.git lyrics_karaoke`       |
-| [NAM Tone Engine](https://github.com/got-feedback/feedBack-plugin-nam-tone)       | In-browser amp modeling with NAM WASM, cabinet IRs, tone auto-switching                                                                                                                                                          | `git clone ...feedBack-plugin-nam-tone.git nam_tone`                   |
-| [Guitar Theory Lab](https://github.com/topkoa/slopsmith-plugin-guitar-theory)      | Explore scales, chords, intervals, tunings, and voicings on a fully interactive fretboard                                                                                                                                        | `git clone ...slopsmith-plugin-guitar-theory.git guitar-theory-lab`          |
-| [Themes](https://github.com/masc0t/slopsmith-plugin-themes)                        | Offers several basic recolorings of the interface                                                                                                                                                                                | `git clone ...slopsmith-plugin-themes.git themes`                       |
-| [Update Manager](https://github.com/masc0t/slopsmith-update-manager)               | Installs, updates, and uninstalls other plugins and the feedBack core itself                                                                                                                                                    | `git clone ...slopsmith-update-manager.git update_manager`              |
-| [Simplify Chords](https://github.com/bkranendonk/slopsmith-plugin-simplify-chords) | Changes complex chords on the note highway to simpler ones. Inspired by Ultimate Guitar's Simplify button.                                                                                                                       | `git clone ...slopsmith-plugin-simplify-chords.git simplify-chords`     |
-| [Key Bindings](https://github.com/jackipicco/slopsmith-plugin-key-bindings)        | Highway key bindings for keyboard and TV remote                                                                                                                                                                                  | `git clone ...slopsmith-plugin-key-bindings.git key_bindings`           |
-| [Virtuoso](https://github.com/got-feedback/feedBack-plugin-virtuoso)               | Practice studio for guitar & bass — scale, technique, and rhythm drills, timed workouts, and jam backing that teach skills you take off the screen.                                                                              | `git clone ...feedBack-plugin-virtuoso.git virtuoso`                    |
-| [Audio Preview](https://github.com/saleemk/slopsmith-plugin-audio-preview)         | Quick audio previews from library cards with configurable start time, volume, and duration                                                                                                                                       | `git clone ...slopsmith-plugin-audio-preview.git audio_preview`         |
-| [Song Mastery](https://github.com/jamesgaiser/slopsmith-plugin-song-mastery)       | Auto-adjusts difficulty based on your rolling note accuracy and saves the slider position per song                                                                                                                               | `git clone ...slopsmith-plugin-song-mastery.git song_mastery`           |
-| [Mobile Note Highway](https://github.com/saleemk/slopsmith-plugin-mobile-note-highway) | Touch-optimized player with collapsible controls, highway gestures, and device-adaptive layouts for phones and tablets | `git clone ...slopsmith-plugin-mobile-note-highway.git mobile_note_highway` |
-
-Install any plugin by cloning it into your `plugins/` directory and restarting:
-
-```bash
-cd plugins
-git clone https://github.com/got-feedback/feedBack-plugin-ug.git ultimate_guitar
-docker compose restart
-```

VERSION

@@ -1 +1 @@
-0.3.0
+0.3.0-alpha.1

docs/perf-baseline.md

@@ -0,0 +1,92 @@
+# Perf baseline — module-migration refactor
+
+The refactor promises "measured runtime wins, no hand-waved perf claims" and
+"screen-entry and frame-time no worse." This is the baseline to hold it to.
+Rerun the harness after every phase (R0 → R3c) and compare.
+
+## Running it
+
+```
+# 1. start core against a library with real charts (see caveat below)
+CONFIG_DIR=… DLC_DIR=/path/to/songs PYTHONPATH=lib \
+  python3 -m uvicorn server:app --host 127.0.0.1 --port 8000
+
+# 2. capture (maintainer/CI-only; uses the committed Playwright chromium)
+node scripts/perf-baseline.mjs --base http://127.0.0.1:8000 --n 60 --soak 30
+```
+
+The script prints a markdown block; paste it under "Results" below with the date
+and the commit it was taken at.
+
+## What it measures
+
+- **Server latency** — p50/p95/p99 over N requests for `/api/version`,
+  `/api/plugins`, `/api/library`, `/api/library/artists`.
+- **Cold boot → interactive** — full page load to `networkidle`.
+- **JS heap** — `performance.memory.usedJSHeapSize` after load and after an idle
+  soak (a leak signal across a session).
+- **Plugin-script shape** — how many plugin `<script>`s the loader injected (a
+  "the app booted with its plugins" sanity signal).
+
+**Not yet captured — needs a seeded library with charts** (fill in when run
+against a real environment): playback **frame-time p95** on the 2D and 3D
+highway, and **screen-entry** (plugin inject → interactive) for
+editor / notedetect / highway_3d with a chart loaded. These are the
+perf-sensitive numbers that gate the `highway.js` split (R3c); the harness has
+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
+> in `DLC_DIR`), so the `/api/library*` and boot numbers are floor values —
+> re-take on a seeded environment with the recommended `--n 60 --soak 30` for the
+> real R0 baseline before comparing R1+ against it. Recorded here to prove the
+> harness and lock the methodology.
+
+Server latency (ms), n=50:
+
+| Endpoint | status | p50 | p95 | p99 |
+|---|---|---|---|---|
+| `/api/version` | 200 | 0.9 | 1.8 | 22.3 |
+| `/api/plugins` | 200 | 1.6 | 2.1 | 3.4 |
+| `/api/library?limit=60` | 200 | 1.4 | 1.7 | 2.9 |
+| `/api/library/artists` | 200 | 1.3 | 1.8 | 2.7 |
+
+Client:
+
+| Metric | Value |
+|---|---|
+| Cold boot → networkidle | 1268 ms |
+| JS heap after load | 10.1 MB |
+| JS heap after idle soak | 10.1 MB (no idle growth) |
+| Plugin scripts injected | 12 |
+
+No plugin has migrated yet, so all 12 are classic. When the R1 pilot (stems)
+lands, cold-boot / heap should not regress.

docs/plugin-modules.md

@@ -0,0 +1,103 @@
+# Plugin ES-module migration playbook
+
+How to move a plugin off a single global-scope `screen.js` IIFE onto a native
+ES-module graph — **no build step, no framework, no bundler**. This is the
+mechanism the monolith-killing refactor uses; the host rails for it shipped in
+R0 (see `.specify/memory/constitution.md` Principle II + the "Module load
+contract" in Operating Constraints).
+
+## The shape
+
+```
+my-plugin/
+  plugin.json      +  "scriptType": "module"        ← opt in
+  screen.js           import './src/main.js';        ← the entire file
+  src/
+    state.js          (0) module state + accessors
+    util/…            (1) pure helpers — real-import testable
+    …/…               (2..4) model → render/audio/io → input
+    globals.js        (5) THE ONLY file that writes window.*
+    main.js           (5) boot: wire modules, register screen:changed
+  assets/…            worklets / WASM / images (unchanged, served as today)
+```
+
+`screen.js` becomes a one-line static `import`. The host injects it as
+`<script type="module">`, whose load event fires **only after the whole
+static-import graph fetches and evaluates** — so the loader's
+completion-by-`onload` + `_loadingPluginId` window + `playSong` wrapper-chain
+order are all preserved. (A classic IIFE that fired a fire-and-forget
+`import()` would break that contract — don't do that; use `scriptType:"module"`.)
+
+## Non-negotiable rules
+
+1. **Source-served, no build.** Modules are plain source files fetched from
+   `/api/plugins/<id>/src/<path>`. No bundler, transpiler, or TypeScript.
+2. **Layering points downward** — `state → util → commands/model →
+   render/audio/io → input → globals/main`. A lint check (`import-x/no-cycle`)
+   enforces acyclicity; extract bottom-up so each move only imports
+   already-extracted layers.
+3. **`globals.js` is the only writer of `window.*`.** The deliberate global
+   surface shrinks to one auditable file; everything else is module-scoped.
+4. **Import-time purity.** `node --test` runs a module's top-level code on
+   import, so a module you want to unit-test must be side-effect-free at import:
+   no `document` / `window` / `localStorage` at module top level — lift init
+   into an exported `init()` called by `main.js`. (Constitution Principle V's
+   "no implicit IO at import time", applied to the frontend.) Tests are `.mjs`
+   and use real `import`, retiring the regex/`extractFunction` harness.
+5. **Assets resolve via `import.meta.url`.** `document.currentScript` is `null`
+   inside a module. `assets/` lives at the plugin root, so a `src/` module must
+   climb out of `src/`: from `src/main.js`, `new URL('../assets/x.js',
+   import.meta.url)` (deeper modules need more `../`). Simpler and
+   depth-independent: the absolute route `/api/plugins/<id>/assets/x.js`.
+   Worklets run in a *separate* module graph (`AudioWorkletGlobalScope`) and
+   cannot share modules with `src/`.
+6. **Re-init comes from `screen:changed`, not re-execution.** The host loads
+   `screen.js` once per version and `showScreen` re-injects nothing, so module
+   top-level code does **not** re-run when the user re-enters the screen at the
+   same version. Keep per-visit setup/teardown in a `window.feedBack.on(
+   'screen:changed', …)` handler — exactly as classic plugins (tuner,
+   minigames) already do. Do not rely on the IIFE re-running.
+7. **Inline `onclick=` keeps working** during migration via `globals.js` (which
+   keeps every referenced symbol on `window`); retire inline handlers to
+   module-side `addEventListener` opportunistically, never as a blocking step.
+
+## The live-edit loop
+
+The host serves `screen.js`, `src/**`, and `assets/**` with
+`Cache-Control: no-cache` + a weak `ETag` and honors `If-None-Match` → `304`.
+So: edit a `src/` file → **refresh the browser** → the edited module returns
+`200` and reloads while every unchanged module `304`s. There is no hot-reload;
+the loop is edit → refresh → see change, exactly as before. The `?v=<version>`
+query on `screen.js` is the legacy version buster; it does **not** propagate
+into the `src/` graph and does not need to — ETag/mtime is the correctness
+authority for the whole graph.
+
+## Host-version floor (`minHost`)
+
+A migrated plugin *requires* a host new enough to serve `src/` and inject
+`type=module`. Declare the floor with `"minHost": "X.Y.Z"` in `plugin.json`.
+(R0 plumbs the field through `/api/plugins`; enforcement — refuse-with-message
+on an older host — is deferred, so bundled plugins are unaffected. Community
+plugins should state the floor and not migrate below it.)
+
+## Migration mechanics
+
+- **Move-only PRs.** One slice extracts one module: cut code, add
+  imports/exports, update `globals.js` — zero behavior change. Behavior fixes
+  are separate PRs. (Init-lifts for import purity are the one non-pure move —
+  budget them.)
+- **Bottom-up, layer by layer.** Within a layer, independent modules are
+  independent PRs (a DAG, not a chain); use a git worktree per branch.
+- Tests move with their subject and convert to real `.mjs` imports in the same
+  PR (assertions unchanged).
+- Size norm: no source file over **1,500 lines**; legitimate exceptions
+  (hot renderers, etc.) go in the signed register at `docs/size-exemptions.md`.
+
+## Verifying a migration
+
+`node --test <plugin>/tests/*.mjs`; load the plugin on the `:8000` testbed and
+confirm it boots (`<script type=module>` in DevTools, the `src/` graph in
+Network); edit a `src/` file → refresh → change visible (`200` on the edited
+file, `304` on the rest); leave and re-enter the screen at the same version →
+it re-inits via `screen:changed`. The R1 pilots (stems, then studio) certify
+this end-to-end before the flagship repos migrate.

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

@@ -0,0 +1,66 @@
+# Size-exemption register
+
+The working norm (constitution Principle II; enforced by the `max-lines` lint
+gate) is **no source file over 1,500 lines**. A few files are allowed to exceed
+it because splitting them would do more harm than good — hot per-frame
+renderers, C++, offline generators, cohesive registries. This register is the
+list of those exceptions: each row is a **deliberate, signed** decision with a
+ceiling, a rationale, and a review trigger. Without it, "no file over 1,500
+without a *signed* exemption" is unenforceable.
+
+**Rules**
+- One row per file: a ceiling, a rationale, a signer, a review trigger.
+- The `max-lines` per-file ceilings in `eslint.config.js` mirror this table —
+  keep them in sync (this register is canonical).
+- Files with a scheduled split **plan** are *not* exempt — they live in
+  "Planned, not exempt" at the bottom so nothing falls between the two states.
+- **Signers** (decided 2026-07-08): **Byron** signs core + bundled rows;
+  **Christian** signs the authored-plugin row (virtuoso, its own repo/track).
+
+## Permanent exemptions (structural rationale)
+
+| Repo / file | Lines (7-07) | Ceiling | Rationale | Signer | Review |
+|---|---|---|---|---|---|
+| core `static/highway.js` → residual `renderer-2d.js` (post-split) | ~2,400–2,900 est. | **3,000** | 60 fps hot path; no module boundary inside the per-frame loop | Byron | after the highway.js split |
+| core `plugins/highway_3d/` → residual renderer | sized at split; likely **>3,000** | set at split, flagged now | same hot-path rule; the draw core can't be cut without behavior risk | Byron | after the highway_3d split |
+| core `static/capabilities.js` | 1,538 | 1,600 | cohesive registry + `window.feedBack` bus, 38 lines over; a split spends credibility for nothing | Byron | R4 |
+| tutorials `builtin/reading-the-highway/generate.py` | 1,818 | 2,000 | offline content generator, never imported at runtime, deps not in runtime requirements | Byron | if a 3rd builtin pack appears |
+| desktop `src/audio/NodeAddon.cpp` | 3,542 | as-is | C++, outside the ESM/routes playbooks; under active use-after-free crash work — do not churn | Byron | after crash-class work settles |
+| desktop `src/audio/AudioEngine.cpp` | 2,977 | as-is | same | Byron | same |
+| desktop `src/vst-host/main.cpp` | 1,928 | as-is | same | Byron | same |
+| virtuoso `screen.js` (authored, own track) | 25,741 | as-is until its own split | authored plugin on a separate roadmap; migrates on its own schedule | Christian | virtuoso split kickoff |
+
+## Split-when-touched (no scheduled train; row retires when split)
+
+| Repo / file | Lines | Ceiling | Rationale | Signer | Review |
+|---|---|---|---|---|---|
+| core `lib/gp2rs_gpx.py` | 2,540 | as-is | import converter, off the serve-path hot loop | Byron | when next touched |
+| core `lib/gp2rs.py` | 2,055 | as-is | same | Byron | when next touched |
+| core `lib/song.py` | 1,689 | as-is | data models + wire format; cohesive | Byron | when next touched |
+| core `lib/gp_autosync.py` | 1,572 | as-is | under active dev (#787/#791) — don't collide | Byron | after in-flight work lands |
+| core `plugins/capability_inspector/screen.js` | 1,752 | as-is | bundled diagnostics plugin, low churn | Byron | when next touched |
+| core `plugins/folder_library/screen.js` | 1,672 | as-is | bundled plugin, low churn | Byron | when next touched |
+
+## Temporary rows (cleared by a scheduled PR)
+
+| Repo / file | Lines | Cleared by |
+|---|---|---|
+| core `plugins/__init__.py` | ~2,470 (grew under R0) | the `plugins/_routes.py` + `plugins/_registry.py` split (rides the server.py router work) |
+
+## Watch list (under the norm — no row needed, re-census each phase)
+
+`musicxml-import/mxml2notation.py` (1,456) · core `static/capabilities/audio-effects.js`
+(1,436) · `studio routes.py` (1,399) · `update-manager screen.js` (1,492 — zero headroom).
+
+## Planned, NOT exempt (owned by split plans — listed so nothing falls between states)
+
+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
+by policy — the norm governs source files.

eslint.config.js

@@ -0,0 +1,66 @@
+// Flat ESLint config — MAINTAINER / CI ONLY. Never runs on the serve or Docker
+// path (constitution Principle I: dev-only tooling is exempt, same category as
+// scripts/build-tailwind.sh). It enforces the module-migration guardrails:
+//
+//   * max-lines — the 1,500-line size norm, as a WARNING ratchet. Legacy
+//     monoliths warn (the "this is over the norm, split it" signal) and shrink
+//     as the refactor lands; warnings do not fail CI. Genuinely-large files are
+//     exempted below, mirroring the signed register in docs/size-exemptions.md.
+//   * import-x/no-unresolved + no-cycle — module hygiene, scoped to the real
+//     ES-module graphs the refactor produces (a plugin's src/ tree, .mjs
+//     tests). no-unresolved (a HARD error) catches broken import paths;
+//     no-cycle enforces the downward-only layering rule. Core's classic scripts
+//     have no import graph, so both are dormant today and become live gates the
+//     moment module code appears — validated against the first real module
+//     plugin (R1 pilot).
+
+const importX = require('eslint-plugin-import-x');
+
+// Per-file size ceilings — a mirror of docs/size-exemptions.md (canonical).
+// Keep in sync; each entry corresponds to a signed row in the register.
+const SIZE_EXEMPTIONS = [
+    { files: ['**/static/capabilities.js'], max: 1600 },
+    { files: ['**/plugins/capability_inspector/screen.js'], max: 100000 },
+    { files: ['**/plugins/folder_library/screen.js'], max: 100000 },
+];
+
+const sizeRule = (max) => ['warn', { max, skipBlankLines: false, skipComments: false }];
+
+module.exports = [
+    {
+        ignores: [
+            'node_modules/**',
+            'static/vendor/**',
+            'plugins/**/assets/vendor/**',
+            '**/*.min.js',
+            'static/tailwind.min.css',
+        ],
+    },
+    // Size norm across all first-party JS. Classic scripts are parsed as
+    // scripts (no import/export); module files get their own block below.
+    {
+        files: ['**/*.js', '**/*.cjs'],
+        languageOptions: { ecmaVersion: 'latest', sourceType: 'script' },
+        rules: { 'max-lines': sizeRule(1500) },
+    },
+    // ES-module graphs (a plugin's src/ tree, .mjs tests): module parsing + the
+    // acyclic-imports hard gate + the size norm. A migrated bundled plugin's
+    // entry `import './src/main.js'` screen.js must parse as a module — add its
+    // glob here in that plugin's migration PR (classic screen.js stays a script).
+    {
+        files: ['**/src/**/*.js', '**/*.mjs'],
+        languageOptions: { ecmaVersion: 'latest', sourceType: 'module' },
+        plugins: { 'import-x': importX },
+        // v4 flat-config resolver (resolver-next + createNodeResolver). Without
+        // it the import rules silently skip imports they can't resolve.
+        settings: { 'import-x/resolver-next': [importX.createNodeResolver()] },
+        rules: {
+            'max-lines': sizeRule(1500),
+            'import-x/no-unresolved': 'error',
+            'import-x/no-cycle': 'error',
+        },
+    },
+    // Signed size exemptions (docs/size-exemptions.md) — raise the ceiling so
+    // registered files don't warn below it.
+    ...SIZE_EXEMPTIONS.map(({ files, max }) => ({ files, rules: { 'max-lines': sizeRule(max) } })),
+];

lib/acoustid_match.py

@@ -0,0 +1,152 @@
+"""AcoustID audio-fingerprint identification for MusicBrainz enrichment.
+
+A flat MusicBrainz *text* search ties every take of a song at the same score —
+studio, a dozen live bootlegs, and every compilation — so "AC/DC — Highway to
+Hell" returns junk (see lib/mb_match.py's canonical re-ranking, which mitigates
+it). The definitive fix is content-based: fingerprint the actual audio with
+Chromaprint (`fpcalc`) and look it up on AcoustID, which maps the fingerprint
+straight to the *exact* MusicBrainz recording — the same approach Lidarr uses.
+
+This module is the PURE half (no network, no subprocess): response parsing +
+config gating, so it is unit-testable in isolation. server.py owns the `fpcalc`
+subprocess and the throttled HTTP GET to api.acoustid.org.
+
+Operational requirements (both optional — absent ⇒ this path is a graceful
+no-op and the text matcher still runs):
+  * `fpcalc` (Chromaprint) on PATH or at $FPCALC — generates the fingerprint.
+  * an AcoustID application API key in $ACOUSTID_API_KEY — free from
+    https://acoustid.org/new-application ; AcoustID etiquette limits to ~3 req/s.
+"""
+
+import os
+
+ACOUSTID_API_ROOT = "https://api.acoustid.org/v2"
+
+# The `meta` fields we ask AcoustID to return so a hit resolves to displayable
+# metadata without a second MusicBrainz round-trip. SPACE-separated, not
+# `+`-joined: a literal `+` in the value gets percent-encoded to %2B, which
+# AcoustID does NOT split into flags — it then attaches no recording metadata
+# and every hit comes back empty (verified: `+` → 0 recordings, space → 28).
+# `releases` is what carries the per-release DATE (nested under each
+# releasegroup), which we need to pick the earliest original album + fill year.
+LOOKUP_META = "recordings releasegroups releases compress"
+
+# Mirror mb_match._SECONDARY_SKIP: release-group secondary types that mark a
+# non-canonical (live/comp/remix) release, so we can flag the studio take.
+_SECONDARY_SKIP = {
+    "live", "compilation", "remix", "dj-mix", "mixtape/street",
+    "demo", "interview", "audiobook", "spokenword",
+}
+
+
+def api_key(explicit: str | None = None) -> str:
+    """The AcoustID application API key: an explicit value (e.g. a host setting)
+    wins, else $ACOUSTID_API_KEY, else "" (⇒ fingerprinting disabled)."""
+    return (explicit or os.environ.get("ACOUSTID_API_KEY") or "").strip()
+
+
+def is_configured(explicit_key: str | None = None) -> bool:
+    """True when an API key is available. `fpcalc` presence is checked by
+    server.py (it owns the binary lookup); both are required to actually run."""
+    return bool(api_key(explicit_key))
+
+
+def _rg_is_studio(rg: dict) -> bool:
+    if str(rg.get("type", "")).lower() != "album":
+        return False
+    secs = {str(s).lower() for s in (rg.get("secondarytypes") or [])}
+    return not (secs & _SECONDARY_SKIP)
+
+
+def _rg_earliest_year(rg: dict) -> "int | None":
+    """Earliest release YEAR in a release-group (min over its nested releases'
+    dates). None when no release carries a date. This is what separates the
+    original pressing from later reissues/comps sharing the same group."""
+    years = []
+    for rel in (rg.get("releases") or []):
+        d = (rel or {}).get("date")
+        if isinstance(d, dict) and d.get("year"):
+            try:
+                years.append(int(d["year"]))
+            except (TypeError, ValueError):
+                pass
+    return min(years) if years else None
+
+
+def _best_group(recording: dict) -> dict:
+    """Pick the display album: a clean studio Album first, and among those the
+    EARLIEST-released one — the original, not a later reissue or a compilation
+    that happens to be typed 'Album' (e.g. a soundtrack). This is what pulls
+    "Machine Head" ahead of a later comp for "Smoke on the Water". Falls back to
+    the first group when nothing is a studio album or nothing carries a date."""
+    groups = [g for g in (recording.get("releasegroups") or []) if isinstance(g, dict)]
+    if not groups:
+        return {}
+
+    def sort_key(g):
+        yr = _rg_earliest_year(g)
+        # studio (0) before non-studio (1); then earliest year (undated last).
+        return (0 if _rg_is_studio(g) else 1, yr if yr is not None else 9999)
+
+    return sorted(groups, key=sort_key)[0]
+
+
+def _first_artist(recording: dict) -> str:
+    for a in (recording.get("artists") or []):
+        if isinstance(a, dict) and a.get("name"):
+            return str(a["name"])
+    return ""
+
+
+def parse_lookup_response(body: dict) -> list[dict]:
+    """Normalize an AcoustID /v2/lookup response into the same flat candidate
+    shape as mb_match (recording_id / title / artist / album / year / duration /
+    studio / mb_score / score), so the review UI and the editor's Match popup
+    render fingerprint hits and text hits identically. `mb_score` carries the
+    AcoustID confidence (0-100) — a fingerprint hit is high-signal by nature."""
+    if not isinstance(body, dict) or body.get("status") != "ok":
+        return []
+    out: list[dict] = []
+    seen: set[str] = set()
+    for result in (body.get("results") or []):
+        if not isinstance(result, dict):
+            continue
+        try:
+            score = float(result.get("score") or 0.0)
+        except (TypeError, ValueError):
+            score = 0.0
+        for rec in (result.get("recordings") or []):
+            if not isinstance(rec, dict) or not rec.get("id"):
+                continue
+            rid = str(rec["id"])
+            if rid in seen:
+                continue
+            seen.add(rid)
+            rg = _best_group(rec)
+            _yr = _rg_earliest_year(rg)
+            year = str(_yr) if _yr else ""
+            dur = rec.get("duration")
+            try:
+                duration = int(round(float(dur))) if dur else None
+            except (TypeError, ValueError):
+                duration = None
+            out.append({
+                "recording_id": rid,
+                "title": str(rec.get("title", "") or ""),
+                "artist": _first_artist(rec),
+                "album": str(rg.get("title", "") or ""),
+                "year": year,
+                "duration": duration,
+                "isrc": "",
+                "genres": [],
+                "studio": _rg_is_studio(rg),
+                "acoustid_score": round(score, 4),
+                # Fingerprint hits are content-verified, not text-guessed — carry
+                # the AcoustID confidence as the display score band.
+                "mb_score": int(round(score * 100)),
+                "score": round(score, 4),
+                "source": "acoustid",
+            })
+    # Best AcoustID confidence first; studio take breaks ties.
+    out.sort(key=lambda c: (c["acoustid_score"], 1 if c["studio"] else 0), reverse=True)
+    return out

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

@@ -34,7 +34,7 @@ _QSTRING_SECRET_RE = re.compile(
     r"(?i)\b(api[_-]?key|key|token|secret|password|pwd|auth)=([^\s&\"']+)"
 )
 _SONG_FILENAME_RE = re.compile(
-    r"\b[\w()'\-+&,.!?\[\]]+\.(?:psarc|sloppak|wem|ogg|mp3|wav)\b",
+    r"\b[\w()'\-+&,.!?\[\]]+\.(?:psarc|sloppak|feedpak|wem|ogg|mp3|wav)\b",
     re.IGNORECASE,
 )
 

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)))
@@ -1836,9 +1843,10 @@ def convert_drum_track_to_drumtab(
     drum strings. Unknown percussion sounds (cowbell, tambourine etc.) are
     skipped — round-tripping them would require teaching `lib/drums.py` first.
     Callers can pass an empty dict as ``out_unmapped`` to receive a per-MIDI
-    record of every skipped note (``{midi: {"count": int, "times": [...]}}``,
-    times capped at 100 samples per note) so they can surface a warning or
-    offer a manual mapping UI.
+    record of every skipped note (``{midi: {"count": int, "times": [...],
+    "velocities": [...]}}``, times/velocities index-aligned and capped at
+    100 samples per note — velocities carry the source notes' real dynamics)
+    so they can surface a warning or offer a manual mapping UI.
 
     Honours GP repeat brackets and D.S./D.C./Coda/Fine jumps when
     ``expand_repeats`` is true — same `_build_playback_schedule` machinery
@@ -1894,18 +1902,29 @@ def convert_drum_track_to_drumtab(
                             # NB: do NOT shadow the outer `entry` loop
                             # variable from `for entry in schedule:`.
                             unmapped_rec = out_unmapped.setdefault(
-                                int(midi_note), {"count": 0, "times": []})
+                                int(midi_note),
+                                {"count": 0, "times": [], "velocities": []})
                             unmapped_rec["count"] += 1
                             if len(unmapped_rec["times"]) < 100:
                                 unmapped_rec["times"].append(round(t, 3))
+                                # Index-aligned with times: the note's real
+                                # dynamics (same 1-127 gate as mapped hits,
+                                # falling back to the 100 import default) so
+                                # a hand-mapping UI doesn't flatten them.
+                                _uv = int(getattr(note, "velocity", 0) or 0)
+                                unmapped_rec["velocities"].append(
+                                    _uv if 1 <= _uv <= 127 else 100)
                         continue
 
                     hit: dict = {"t": round(t, 3), "p": piece}
 
-                    # Velocity: GP stores 1-127 MIDI velocity directly; default
-                    # is 95 (Velocities.default). Pass through verbatim,
-                    # clamping defensively so a corrupt file can't poison the
-                    # wire format.
+                    # Velocity: GP stores 1-127 MIDI velocity directly. Note
+                    # this is GP's *authoring* default (95, Velocities.default)
+                    # — unrelated to the drumtab render default of 100
+                    # (DEFAULT_VELOCITY, lib/drums.py:179), which only applies
+                    # when `v` is omitted from a hit. Pass the GP value through
+                    # verbatim, clamping defensively so a corrupt file can't
+                    # poison the wire format.
                     vel = int(getattr(note, "velocity", 0) or 0)
                     if 1 <= vel <= 127:
                         hit["v"] = vel
@@ -1946,9 +1965,21 @@ def convert_drum_track_to_drumtab(
     # Times for unmapped notes were collected in beat-iteration order;
     # multi-voice measures can produce out-of-order beats, so sort each
     # entry's `times` list chronologically before returning to the caller.
+    # Velocities are index-aligned with times, so they must sort in
+    # LOCKSTEP — sorting times alone would silently reassign dynamics.
     if out_unmapped is not None:
         for _rec in out_unmapped.values():
-            _rec["times"].sort()
+            _vels = _rec.get("velocities")
+            if _vels and len(_vels) == len(_rec["times"]):
+                _pairs = sorted(zip(_rec["times"], _vels))
+                _rec["times"] = [p[0] for p in _pairs]
+                _rec["velocities"] = [p[1] for p in _pairs]
+            else:
+                # Belt-and-suspenders: times & velocities are always appended
+                # together under the same `len(times) < 100` guard above, so
+                # in practice the lengths can't diverge. Kept as a defensive
+                # fallback, not a real divergence case.
+                _rec["times"].sort()
 
     return {
         "version": drums_mod.SCHEMA_VERSION,

lib/gp2rs_gpx.py

@@ -121,10 +121,18 @@ def _parse_bcfs(bcfs: bytes) -> dict:
             while sc <= max_sectors:
                 s = _gi(po + 4 * sc); sc += 1
                 if s == 0: break
-                so = s * SECTOR
-                if HDR + so + SECTOR > len(data):
+                start = HDR + s * SECTOR
+                # Real .gpx files' final sector is a few bytes short of a full
+                # 0x1000 block: the BCFZ-declared decompressed size isn't
+                # sector-aligned, so the last (small) container file lands in a
+                # partial trailing sector. Clamp the read to the buffer end —
+                # the per-file size field (`fs`, applied below) trims any
+                # padding — matching canonical GPX readers (alphaTab /
+                # PyGuitarPro slice-and-clamp). Only a sector whose *start* is
+                # past the end is genuinely malformed.
+                if start < 0 or start >= len(data):
                     raise ValueError("GPX BCFS sector pointer out of range (malformed file)")
-                fb.extend(data[HDR + so: HDR + so + SECTOR])
+                fb.extend(data[start: min(start + SECTOR, len(data))])
             else:
                 raise ValueError("GPX BCFS sector chain too long (malformed file)")
             files[fn] = bytes(fb[:fs])
@@ -229,12 +237,29 @@ def _build_tempo_map(root: ET.Element) -> list[tuple[int, float]]:
     return events
 
 
+def _parse_tuning(el: ET.Element) -> list[int]:
+    """Return the string-tuning MIDI pitches from the first ``Tuning`` Property
+    at or below ``el`` (a Track or a single Staff), high string first. ``[]`` if
+    there is no Tuning property or its Pitches text is unparseable."""
+    for prop in el.findall('.//Property'):
+        if prop.get('name') == 'Tuning':
+            pe = prop.find('Pitches')
+            if pe is not None and pe.text:
+                try:
+                    return [int(p) for p in pe.text.split()]
+                except ValueError:
+                    return []
+            break
+    return []
+
+
 def _gpif_tracks(root: ET.Element) -> list[dict]:
     """Return a list of raw track dicts from the GPIF Tracks element."""
     # Lookups for per-track note counting. MasterBar/Bars lists one bar id per
-    # track in raw Tracks order, so the enumerate index below (which counts
-    # skipped pseudo-tracks) is the correct bar-lookup index — same mapping
-    # convert_file uses via filtered_to_raw.
+    # *stave* (not per Track element) in document order. A multi-stave track
+    # (e.g. GP8 piano with treble + bass) occupies N consecutive columns; the
+    # bar_column counter below advances by num_staves per track so every track
+    # gets the correct column regardless of neighbour stave counts.
     _masterbars = list(root.find('MasterBars') or [])
     _bars_by_id = {b.get('id'): b for b in (root.find('Bars') or [])}
     _voices_by_id = {v.get('id'): v for v in (root.find('Voices') or [])}
@@ -279,10 +304,17 @@ def _gpif_tracks(root: ET.Element) -> list[dict]:
         return n
 
     result = []
-    for raw_idx, t in enumerate(root.find('Tracks') or []):
+    bar_column = 0
+    for t in (root.find('Tracks') or []):
+        # Count staves: each Staff occupies one column in MasterBar/Bars.
+        # Default to 1 for tracks with no explicit <Staves> (GP3/4/5, old GPX).
+        num_staves = max(1, len(list(t.findall('Staves/Staff'))))
+        stave_columns = list(range(bar_column, bar_column + num_staves))
+
         name = (t.findtext('Name') or '').strip()
         if name.startswith('@$') and name.endswith('$@'):
-            continue  # GP internal pseudo-tracks (raw_idx still advances)
+            bar_column += num_staves
+            continue  # GP internal pseudo-tracks (bar_column still advances)
 
         gm = t.find('GeneralMidi')
         midi_program = 0
@@ -319,27 +351,37 @@ def _gpif_tracks(root: ET.Element) -> list[dict]:
                 except (ValueError, TypeError):
                     pass
 
-        # String tuning
-        string_pitches: list[int] = []
-        for prop in t.findall('.//Property'):
-            if prop.get('name') == 'Tuning':
-                pe = prop.find('Pitches')
-                if pe is not None and pe.text:
-                    try:
-                        string_pitches = [int(p) for p in pe.text.split()]
-                    except ValueError:
-                        pass
+        # String tuning — one list per stave, in stave order.  Reading all
+        # `.//Property` descendants across every stave meant the last stave's
+        # tuning overwrote the first; for a GP8 piano (treble 6-string +
+        # bass 5-string) that caused stave-0 notes with String=5 to be
+        # out-of-range against the 5-entry bass tuning and silently dropped.
+        # A staff with no Tuning of its own falls back to the track-level
+        # property (never to []) — an empty list silently drops every fretted
+        # note on that stave in `_note_midi`.  The list stays parallel to
+        # `stave_columns` so a per-stave column always has a matching tuning.
+        _track_tuning = _parse_tuning(t)
+        _staff_els = list(t.findall('Staves/Staff'))
+        if _staff_els:
+            stave_pitches = [(_parse_tuning(s) or _track_tuning) for s in _staff_els]
+        else:
+            # No <Staves> (GP3/4/5 or old GPX): single track-level tuning.
+            stave_pitches = [_track_tuning]
 
         result.append({
             '_el': t,
             'id': t.get('id', ''),
             'name': name,
-            'string_pitches': string_pitches,
+            'string_pitches': stave_pitches[0],   # primary stave (existing key)
+            'num_staves': num_staves,
+            'stave_columns': stave_columns,
+            'stave_pitches': stave_pitches,
             'is_drums': is_drums,
             'midi_program': midi_program,
             'midi_channel': midi_channel,
-            'note_count': _note_count_for_raw(raw_idx),
+            'note_count': sum(_note_count_for_raw(c) for c in stave_columns),
         })
+        bar_column += num_staves
     return result
 
 
@@ -367,6 +409,121 @@ def _beat_dur_secs(beat_el: ET.Element, rhythms_dict: dict, tempo_bpm: float) ->
     return dur_qn * (60.0 / tempo_bpm)
 
 
+def _collect_column_notes(
+    col: int,
+    string_pitches: list[int],
+    *,
+    masterbars: list,
+    bars_by_id: dict,
+    voices_dict: dict,
+    beats_dict: dict,
+    notes_dict: dict,
+    rhythms_dict: dict,
+    tempo_map: list,
+    tempo_bpm: float,
+    audio_offset: float,
+) -> list['RsNote']:
+    """Walk one ``MasterBar/Bars`` column (a single stave / hand) and return its
+    notes as keys-encoded ``RsNote`` (``string = midi // 24``, ``fret = midi %
+    24``). Tie destinations extend the matching prior note's sustain (keyed by
+    pitch, so polyphonic parts are handled) rather than emitting a new note —
+    mirroring the main ``convert_file`` builder, including its full-precision
+    timing and the 0.2s sustain threshold.
+
+    Shared by the GPX LH/RH pair merge and the GP8 multi-stave (grand-staff)
+    fold so the two code paths can never drift in tie / timing / dedup handling.
+    """
+    from gp2rs import RsNote  # lazy: gp2rs<->gpx circular import (see convert_file)
+
+    notes: list[RsNote] = []
+    last_per_key: dict[int, RsNote] = {}
+    tempo_iter = iter(tempo_map)
+    next_bar, next_bpm = next(tempo_iter, (999999, tempo_bpm))
+    cur_tempo = tempo_bpm
+    t_cursor = 0.0
+
+    for mb_idx, mb in enumerate(masterbars):
+        while mb_idx >= next_bar:
+            cur_tempo = next_bpm
+            next_bar, next_bpm = next(tempo_iter, (999999, cur_tempo))
+        ts = mb.findtext('Time', '4/4')
+        try:
+            nb, db = [int(x) for x in ts.split('/')]
+        except ValueError:
+            nb, db = 4, 4
+        bar_dur = nb * (4.0 / db) * (60.0 / cur_tempo)
+        bar_ids = mb.findtext('Bars', '').split()
+        bid = bar_ids[col] if col < len(bar_ids) else '-1'
+        if bid != '-1' and bid:
+            bar = bars_by_id.get(bid)
+            if bar is not None:
+                for vid in bar.findtext('Voices', '').split():
+                    if vid == '-1':
+                        continue
+                    voice = voices_dict.get(vid)
+                    if voice is None:
+                        continue
+                    vt = t_cursor
+                    for beat_id in voice.findtext('Beats', '').split():
+                        beat = beats_dict.get(beat_id)
+                        if beat is None:
+                            continue
+                        dur = _beat_dur_secs(beat, rhythms_dict, cur_tempo)
+                        for nid in beat.findtext('Notes', '').strip().split():
+                            note_el = notes_dict.get(nid)
+                            if note_el is None:
+                                continue
+                            if _note_is_tie(note_el):
+                                tie_midi = _note_midi(note_el, string_pitches)
+                                if tie_midi is not None:
+                                    prev = last_per_key.get(tie_midi)
+                                    tie_t = vt + audio_offset
+                                    if prev is not None and prev.time < tie_t:
+                                        prev.sustain = max(
+                                            prev.sustain, (tie_t + dur) - prev.time)
+                                continue
+                            midi = _note_midi(note_el, string_pitches)
+                            if midi is None:
+                                continue
+                            rn = RsNote(
+                                time=vt + audio_offset,
+                                string=midi // 24,
+                                fret=midi % 24,
+                                sustain=dur if dur > 0.2 else 0.0,
+                            )
+                            notes.append(rn)
+                            last_per_key[midi] = rn
+                        vt += dur
+        t_cursor += bar_dur
+    return notes
+
+
+def _merge_lh_notes(rs_notes: list, rs_chords: list, lh_notes: list) -> None:
+    """Fold ``lh_notes`` (a second stave / left hand) into ``rs_notes`` in
+    place, de-duplicating simultaneous same-pitch notes and keeping the LONGER
+    sustain when both hands strike the same key at the same instant. Seeds the
+    dedup set from chord notes too (polyphonic RH beats live in
+    ``rs_chords[*].notes``). No-op for an empty ``lh_notes``."""
+    if not lh_notes:
+        return
+    seen: dict[tuple, RsNote] = {}
+    for n in rs_notes:
+        seen.setdefault((round(n.time, 3), n.string, n.fret), n)
+    for c in rs_chords:
+        for cn in c.notes:
+            seen.setdefault((round(cn.time, 3), cn.string, cn.fret), cn)
+    for rn in lh_notes:
+        k = (round(rn.time, 3), rn.string, rn.fret)
+        existing = seen.get(k)
+        if existing is None:
+            rs_notes.append(rn)
+            seen[k] = rn
+        elif rn.sustain > existing.sustain:
+            # Mutating the RsNote also updates it in place inside any RH chord.
+            existing.sustain = rn.sustain
+    rs_notes.sort(key=lambda n: (n.time, n.string))
+
+
 # ---------------------------------------------------------------------------
 # Drum encoding tables — ported from alphaTab PercussionMapper (MIT licensed)
 # ---------------------------------------------------------------------------
@@ -1349,6 +1506,10 @@ def convert_file(
     # Surface that to the caller rather than only the docstring: if the score
     # actually uses repeats, the produced bar count/timing will differ from the
     # equivalent .gp5. Warn once so plugin code/logs don't silently drift.
+    # NB: lib/gp_autosync.gp_has_expandable_repeats() encodes this single-pass
+    # behaviour (.gp/.gpx never expand). Implementing GPIF expansion here MUST
+    # update that helper in the same change, or the editor's per-bar sync warp
+    # would silently retime repeated sections onto the wrong bars.
     if expand_repeats and any(
         mb.find('Repeat') is not None or mb.find('AlternateEndings') is not None
         for mb in masterbars
@@ -1366,17 +1527,16 @@ def convert_file(
     rhythms_dict = {r.get('id'): r for r in (root.find('Rhythms') or [])}
     _bend_divisor = _gpx_bend_scale(root)   # GPIF bend value -> semitones
 
-    # Map filtered track index -> raw track index (needed for bar lookup)
-    raw_tracks = list(root.find('Tracks') or [])
-    filtered_to_raw: dict[int, int] = {}
-    filtered_pos = 0
-    for raw_idx, t_el in enumerate(raw_tracks):
-        name = (t_el.findtext('Name') or '').strip()
-        if name.startswith('@$') and name.endswith('$@'):
-            continue
-        filtered_to_raw[filtered_pos] = raw_idx
-        filtered_pos += 1
-
+    # Map filtered track index -> bar column (MasterBar/Bars position for
+    # stave 0 of that track). `_gpif_tracks` already computed the per-stave
+    # column layout (advancing by num_staves per track, pseudo-tracks skipped),
+    # so reuse its `stave_columns[0]` rather than re-deriving the counting rule
+    # here — divergence in stave counting *is* the bug class this fix closes.
+    # NB: despite the historical name, the value is a bar *column*, not a raw
+    # Track index — do not index `root.find('Tracks')` with it.
+    filtered_to_raw: dict[int, int] = {
+        i: t['stave_columns'][0] for i, t in enumerate(tracks)
+    }
 
     # Detect and merge Piano LH+RH pairs into single full-keyboard arrangements
     track_indices, _piano_merge_map = _find_piano_pairs(track_indices, tracks, names)
@@ -1468,7 +1628,16 @@ def convert_file(
         is_keys = (
             not is_drum and not is_vocal
             and (
-                any(kw in track['name'].lower() for kw in ('piano', 'keys', 'keyboard', 'organ'))
+                # A multi-stave track is a grand staff (treble + bass) — i.e. a
+                # keyboard-family part. Treating it as keys end-to-end keeps the
+                # stave-0 encoding and the folded stave-1+ encoding consistent
+                # (both midi//24, midi%24) and makes the `note_count` preview
+                # (which sums every stave column) match what actually imports,
+                # even for instruments the name/program heuristics miss (harp,
+                # celesta, marimba). GPIF writes guitars as a single Staff, so
+                # this does not sweep in ordinary fretted tracks.
+                track.get('num_staves', 1) > 1
+                or any(kw in track['name'].lower() for kw in ('piano', 'keys', 'keyboard', 'organ'))
                 or arr_name.lower().startswith('keys')
                 or (
                     not track['string_pitches']
@@ -1534,7 +1703,6 @@ def convert_file(
         pending_slides: list = []         # (RsNote, rs_string, gp_slide_flags) — resolved post-loop
 
         current_time = 0.0
-        num_raw_tracks = len(raw_tracks)
 
         # Resolve current tempo per bar from the tempo map
         _tempo_iter = iter(tempo_map)
@@ -1866,112 +2034,20 @@ def convert_file(
             tuning = _gpx_tuning(track)
 
         # Merge Piano LH notes into this (RH) arrangement if a pair was detected
+        _walk_kwargs = dict(
+            masterbars=masterbars, bars_by_id=bars_by_id,
+            voices_dict=voices_dict, beats_dict=beats_dict,
+            notes_dict=notes_dict, rhythms_dict=rhythms_dict,
+            tempo_map=tempo_map, tempo_bpm=tempo_bpm, audio_offset=audio_offset,
+        )
         if is_keys and track_idx in _piano_merge_map:
+            # GPX LH/RH pair: the left hand is a *separate* Track element. Walk
+            # its column and fold it into this (right-hand) arrangement.
             lh_idx = _piano_merge_map[track_idx]
             lh_track = tracks[lh_idx]
             lh_raw_idx = filtered_to_raw.get(lh_idx, lh_idx)
-
-            _lh_notes: list[RsNote] = []
-            _lh_last_per_key: dict[int, RsNote] = {}
-            _lh_tempo_iter = iter(tempo_map)
-            _lh_next_bar, _lh_next_bpm = next(_lh_tempo_iter, (999999, tempo_bpm))
-            _lh_cur_tempo = tempo_bpm
-            _lh_time = 0.0
-
-            for _lh_mb_idx, _lh_mb in enumerate(masterbars):
-                while _lh_mb_idx >= _lh_next_bar:
-                    _lh_cur_tempo = _lh_next_bpm
-                    _lh_next_bar, _lh_next_bpm = next(_lh_tempo_iter, (999999, _lh_cur_tempo))
-                _lh_ts = _lh_mb.findtext('Time', '4/4')
-                try:
-                    _lh_nb, _lh_db = [int(x) for x in _lh_ts.split('/')]
-                except ValueError:
-                    _lh_nb, _lh_db = 4, 4
-                _lh_bar_dur = _lh_nb * (4.0 / _lh_db) * (60.0 / _lh_cur_tempo)
-                _lh_bar_ids = _lh_mb.findtext('Bars', '').split()
-                _lh_bid = _lh_bar_ids[lh_raw_idx] if lh_raw_idx < len(_lh_bar_ids) else '-1'
-                if _lh_bid != '-1' and _lh_bid:
-                    _lh_bar = bars_by_id.get(_lh_bid)
-                    if _lh_bar is not None:
-                        for _lh_vid in _lh_bar.findtext('Voices', '').split():
-                            if _lh_vid == '-1':
-                                continue
-                            _lh_voice = voices_dict.get(_lh_vid)
-                            if _lh_voice is None:
-                                continue
-                            _lh_vt = _lh_time
-                            for _lh_beat_id in _lh_voice.findtext('Beats', '').split():
-                                _lh_beat = beats_dict.get(_lh_beat_id)
-                                if _lh_beat is None:
-                                    continue
-                                _lh_dur = _beat_dur_secs(_lh_beat, rhythms_dict, _lh_cur_tempo)
-                                for _lh_nid in _lh_beat.findtext('Notes', '').strip().split():
-                                    _lh_note_el = notes_dict.get(_lh_nid)
-                                    if _lh_note_el is None:
-                                        continue
-                                    if _note_is_tie(_lh_note_el):
-                                        # Extend the matching prior note (same
-                                        # pitch), mirroring the main builder's
-                                        # last_note_per_key handling — blindly
-                                        # extending the last-emitted note
-                                        # mishandles polyphonic (chord) LH parts.
-                                        _tie_midi = _note_midi(_lh_note_el, lh_track['string_pitches'])
-                                        if _tie_midi is not None:
-                                            _prev = _lh_last_per_key.get(_tie_midi)
-                                            # Full-precision comparison (matching
-                                            # the main builder); rounding only
-                                            # happens at XML serialization. Rounding
-                                            # here could make a short note appear to
-                                            # start at the tie time and skip the
-                                            # sustain extension.
-                                            _tie_t = _lh_vt + audio_offset
-                                            if _prev is not None and _prev.time < _tie_t:
-                                                _prev.sustain = max(
-                                                    _prev.sustain,
-                                                    (_tie_t + _lh_dur) - _prev.time,
-                                                )
-                                        continue
-                                    _lh_midi = _note_midi(_lh_note_el, lh_track['string_pitches'])
-                                    if _lh_midi is None:
-                                        continue
-                                    # Keep full-precision time (like the main
-                                    # convert_file() builder — rounding happens at
-                                    # serialization); same 0.2s sustain threshold.
-                                    _lh_rn = RsNote(
-                                        time=_lh_vt + audio_offset,
-                                        string=_lh_midi // 24,
-                                        fret=_lh_midi % 24,
-                                        sustain=_lh_dur if _lh_dur > 0.2 else 0.0,
-                                    )
-                                    _lh_notes.append(_lh_rn)
-                                    _lh_last_per_key[_lh_midi] = _lh_rn
-                                _lh_vt += _lh_dur
-                _lh_time += _lh_bar_dur
-
-            # Merge: combine and deduplicate simultaneous same-pitch notes, then
-            # sort by time. Map each (time, string, fret) to its existing RsNote
-            # so that when both hands hit the same key at the same instant we
-            # keep the LONGER sustain instead of arbitrarily discarding the LH
-            # one. Seed from both single notes and chord notes — polyphonic RH
-            # beats live in rs_chords[*].notes, so seeding from rs_notes alone
-            # would let an identical LH note slip in as a duplicate.
-            _seen: dict[tuple, RsNote] = {}
-            for _n in rs_notes:
-                _seen.setdefault((round(_n.time, 3), _n.string, _n.fret), _n)
-            for _c in rs_chords:
-                for _cn in _c.notes:
-                    _seen.setdefault((round(_cn.time, 3), _cn.string, _cn.fret), _cn)
-            for _lh_rn in _lh_notes:
-                _k = (round(_lh_rn.time, 3), _lh_rn.string, _lh_rn.fret)
-                _existing = _seen.get(_k)
-                if _existing is None:
-                    rs_notes.append(_lh_rn)
-                    _seen[_k] = _lh_rn
-                elif _lh_rn.sustain > _existing.sustain:
-                    # Same key both hands — preserve the longer sustain (mutating
-                    # the RsNote also updates it in place inside any RH chord).
-                    _existing.sustain = _lh_rn.sustain
-            rs_notes.sort(key=lambda n: (n.time, n.string))
+            _merge_lh_notes(rs_notes, rs_chords, _collect_column_notes(
+                lh_raw_idx, lh_track['string_pitches'], **_walk_kwargs))
 
             # Collapse "Keys 2" -> "Keys": the merged LH+RH is a single
             # keyboard arrangement. Keep the standard "Keys" name (not "Piano")
@@ -1979,6 +2055,18 @@ def convert_file(
             # auto-select (which keys on arr_name.startswith("keys")) still work.
             arr_name = re.sub(r'\s*\d+$', '', arr_name).strip() or 'Keys'
 
+        elif track.get('num_staves', 1) > 1:
+            # GP8 grand-staff keyboard: staves 1+ (bass clef, and any further
+            # staves) are extra MasterBar/Bars columns for the SAME Track
+            # element. Fold each one in, exactly like the GPX LH merge above.
+            # (num_staves > 1 implies is_keys, set above.) Iterating every
+            # extra column — not just stave_columns[1] — keeps the arrangement
+            # consistent with note_count, which sums all columns.
+            for _col, _sp in zip(track['stave_columns'][1:],
+                                 track['stave_pitches'][1:]):
+                _merge_lh_notes(rs_notes, rs_chords, _collect_column_notes(
+                    _col, _sp, **_walk_kwargs))
+
         # Resolve pending slides now that every note on each string is known.
         # GPIF slide flags: 1=shift, 2=legato (both slide to the NEXT note on the
         # string); 4=slide out downwards, 8=slide out upwards (unpitched).
@@ -2032,19 +2120,24 @@ def convert_file(
             try:
                 import gp2notation as _gp2notation
                 _lh_idx = _piano_merge_map.get(track_idx)
+                if _lh_idx is not None:
+                    # GPX LH/RH pair (two separate Track elements)
+                    _nt_lh_raw = filtered_to_raw.get(_lh_idx, _lh_idx)
+                    _nt_lh_sp  = tracks[_lh_idx]['string_pitches']
+                elif track.get('num_staves', 1) > 1:
+                    # GP8 two-stave piano (one Track with multiple <Staves>)
+                    _nt_lh_raw = track['stave_columns'][1]
+                    _nt_lh_sp  = (track['stave_pitches'][1]
+                                  if len(track.get('stave_pitches', [])) > 1 else [])
+                else:
+                    _nt_lh_raw, _nt_lh_sp = None, []
                 _payload = _gp2notation.convert_track_to_notation(
                     root, raw_idx, track['string_pitches'],
                     instrument='piano',
                     audio_offset=audio_offset,
                     track_name=track['name'],
-                    lh_raw_idx=(
-                        filtered_to_raw.get(_lh_idx, _lh_idx)
-                        if _lh_idx is not None else None
-                    ),
-                    lh_string_pitches=(
-                        tracks[_lh_idx]['string_pitches']
-                        if _lh_idx is not None else None
-                    ),
+                    lh_raw_idx=_nt_lh_raw,
+                    lh_string_pitches=_nt_lh_sp or None,
                 )
                 _gp2notation.write_notation_sidecar(filepath, _payload)
             except Exception:

lib/gp_autosync.py

@@ -18,8 +18,22 @@ plugin is installed; graceful ImportError otherwise with clear message).
 Public API:
     is_available()                          -> bool
     auto_sync(gp_path, audio_path, ...)    -> GpSyncData
+    refine_sync(sync, audio_path, ...)     -> GpSyncData
     estimate_audio_offset(gp_path,
                           audio_path)      -> float
+    bar_start_times(gp_path)               -> list[float]
+    gp_has_expandable_repeats(gp_path)     -> bool
+    build_warp_anchors(sync_points,
+                       bar_starts)         -> list[tuple[float, float]]
+    warp_time(t, anchors)                  -> float
+    warp_song_times(song, warp)            -> None
+
+The warp helpers (bar_start_times / build_warp_anchors / warp_time /
+warp_song_times) are librosa-free: they turn a GpSyncData produced by
+auto_sync (or extracted from a GP8 file) into a piecewise-linear
+score-time -> audio-time mapping and apply it to a lib.song.Song, so
+converted charts follow the recording's actual tempo drift instead of a
+single scalar offset.
 """
 
 from __future__ import annotations
@@ -353,15 +367,22 @@ def _synthesise_score_chroma(
     return chroma
 
 _GP345_TICKS_PER_QUARTER = 960
+# PyGuitarPro absolute ticks start at quarterTime (measure 1 begins at tick
+# 960, not 0). All tick math in this module runs on a 0-based axis (cumulative
+# measure starts), so raw beat.start values must be shifted by this origin —
+# mixing the two axes applied every mid-song tempo change a quarter note late
+# and skewed the synthesised chroma against the bar timeline.
+_GP345_TICK_ORIGIN = 960
 
 
 def _gp345_tempo_events(song) -> list[tuple[int, float]]:
     """Sorted, tick-deduplicated ``[(tick, bpm)]`` tempo events for a GP3/4/5 song.
 
     Seeds with the song's initial tempo at tick 0, then appends every
-    ``mixTableChange`` tempo. Shared by chroma synthesis and bar-time
-    computation so both use one identical tempo model (mirrors
-    ``gp2rs._build_tempo_map``).
+    ``mixTableChange`` tempo. Ticks are normalised to the 0-based axis
+    (raw ``beat.start`` minus ``_GP345_TICK_ORIGIN``). Shared by chroma
+    synthesis and bar-time computation so both use one identical tempo
+    model (mirrors ``gp2rs._build_tempo_map``).
     """
     events: list[tuple[int, float]] = [(0, float(song.tempo))]
     for track in song.tracks:
@@ -371,7 +392,10 @@ def _gp345_tempo_events(song) -> list[tuple[int, float]]:
                     if beat.effect and beat.effect.mixTableChange:
                         mtc = beat.effect.mixTableChange
                         if mtc.tempo and mtc.tempo.value > 0:
-                            events.append((beat.start, float(mtc.tempo.value)))
+                            events.append((
+                                max(0, beat.start - _GP345_TICK_ORIGIN),
+                                float(mtc.tempo.value),
+                            ))
     events.sort(key=lambda e: e[0])
     seen_ticks: set[int] = set()
     unique: list[tuple[int, float]] = []
@@ -459,8 +483,9 @@ def _synthesise_score_chroma_gp345(
                 for beat in voice.beats:
                     if not beat.notes:
                         continue
-                    beat_secs = tick_to_secs(beat.start)
-                    cur_tempo = tempo_at_tick(beat.start)
+                    beat_tick = max(0, beat.start - _GP345_TICK_ORIGIN)
+                    beat_secs = tick_to_secs(beat_tick)
+                    cur_tempo = tempo_at_tick(beat_tick)
                     dur_secs = duration_to_secs(beat.duration, cur_tempo)
 
                     for note in beat.notes:
@@ -513,13 +538,75 @@ def _dtw_align(
     Returns wp where wp[i] = [score_frame_index, audio_frame_index].
     """
     import librosa
+    import numpy as np
     cs = _safe_normalise(chroma_score)
     ca = _safe_normalise(chroma_audio)
-    _D, wp = librosa.sequence.dtw(cs, ca, metric='cosine')
+    # Slope-constrained step pattern ([[1,1],[1,2],[2,1]], Müller's standard
+    # music-sync config): every step advances BOTH axes, bounding the local
+    # tempo ratio to 0.5x-2x. librosa's default steps allow pure
+    # horizontal/vertical runs, and on riff-based music (long self-similar
+    # chroma stretches, e.g. stoner/doom) the flat cost surface let the path
+    # collapse — whole minutes of score mapped onto a single audio frame,
+    # producing garbage sync points. The constrained pattern makes that
+    # degenerate path impossible.
+    steps = np.array([[1, 1], [1, 2], [2, 1]])
+    weights = np.array([1.0, 1.0, 1.0])
+    try:
+        _D, wp = librosa.sequence.dtw(
+            cs, ca, metric='cosine',
+            step_sizes_sigma=steps, weights_mul=weights,
+        )
+    except Exception as exc:
+        # The constrained pattern needs the global length ratio within its
+        # 0.5x-2x slope bounds; a pathological pairing (e.g. a 3-minute tab
+        # against a 20-minute video) is infeasible and librosa raises. Fall
+        # back to the unconstrained path rather than failing the whole sync.
+        _log.warning("gp_autosync: constrained DTW infeasible (%s) — "
+                     "falling back to unconstrained steps", exc)
+        _D, wp = librosa.sequence.dtw(cs, ca, metric='cosine')
     return wp[::-1]  # reverse to forward order
 
 # ── Sync point extraction from DTW path ──────────────────────────────────────
 
+def _gpif_bar_starts(root: ET.Element) -> list[float]:
+    """Score-time (seconds) at the start of each masterbar in a GPIF score.
+
+    Integrates bar durations from the bar-resolution tempo map and each
+    masterbar's time signature — the same time model _synthesise_score_chroma
+    uses, so bar times land where the bars sit in the synthesised chroma.
+    """
+    tempo_map = _get_tempo_map(root)
+    masterbars = _children(root, 'MasterBars')
+    tempo_iter = iter(tempo_map)
+    next_tb, next_bpm = next(tempo_iter, (999999, tempo_map[0][1]))
+    ct = tempo_map[0][1]
+    t_cur = 0.0
+    bar_starts: list[float] = []
+    for mb_idx, mb in enumerate(masterbars):
+        while mb_idx >= next_tb:
+            ct = next_bpm
+            next_tb, next_bpm = next(tempo_iter, (999999, ct))
+        bar_starts.append(t_cur)
+        ts = mb.findtext('Time', '4/4')
+        try:
+            n_b, d_b = [int(x) for x in ts.split('/')]
+        except ValueError:
+            n_b, d_b = 4, 4
+        t_cur += n_b * (4.0 / d_b) * (60.0 / ct)
+    return bar_starts
+
+
+def _gp345_measure_start_ticks(song) -> list[int]:
+    """Cumulative start tick of each measure in a PyGuitarPro song."""
+    starts: list[int] = []
+    cum = 0
+    for mh in song.measureHeaders:
+        starts.append(cum)
+        ts = mh.timeSignature
+        cum += int(ts.numerator * (4.0 / ts.denominator.value) * _GP345_TICKS_PER_QUARTER)
+    return starts
+
+
 def _extract_sync_points(
     wp: 'np.ndarray',
     root: ET.Element,
@@ -565,22 +652,7 @@ def _extract_sync_points(
     if bar_starts_override is not None:
         bar_starts_score = list(bar_starts_override)
     else:
-        tempo_iter = iter(tempo_map)
-        next_tb, next_bpm = next(tempo_iter, (999999, tempo_map[0][1]))
-        ct = tempo_map[0][1]
-        t_cur = 0.0
-        bar_starts_score = []
-        for mb_idx, mb in enumerate(masterbars):
-            while mb_idx >= next_tb:
-                ct = next_bpm
-                next_tb, next_bpm = next(tempo_iter, (999999, ct))
-            bar_starts_score.append(t_cur)
-            ts = mb.findtext('Time', '4/4')
-            try:
-                n_b, d_b = [int(x) for x in ts.split('/')]
-            except ValueError:
-                n_b, d_b = 4, 4
-            t_cur += n_b * (4.0 / d_b) * (60.0 / ct)
+        bar_starts_score = _gpif_bar_starts(root)
 
     # Map each sampled bar to its audio time via the DTW path
     sync_points: list[SyncPoint] = []
@@ -663,6 +735,224 @@ def _tempo_at_bar(tempo_map: list[tuple[int, float]], bar: int) -> float:
 
 # ── Audio offset estimation ───────────────────────────────────────────────────
 
+# ── Piecewise time warp (librosa-free) ───────────────────────────────────────
+#
+# auto_sync's per-bar sync points describe where each sampled bar of the tab
+# falls in the real recording. Applying only the scalar audio_offset (bar 1)
+# assumes the recording holds the authored tempo for the whole song — any
+# drift accumulates. These helpers build the full piecewise-linear
+# score-time -> audio-time mapping and apply it to a converted Song, so the
+# chart follows the recording bar by bar (Songsterr-style sync).
+
+def bar_start_times(gp_path: str) -> list[float]:
+    """Score-time (seconds) at the start of every bar of a GP file.
+
+    Uses the same tempo models as auto_sync's chroma synthesis (GPIF
+    bar-resolution map for .gp/.gpx, per-tick integration for .gp3/4/5), so
+    the returned times share an axis with auto_sync's sync points.
+
+    Raises ValueError if the file cannot be parsed, ImportError if the file
+    is GP3/4/5 and PyGuitarPro is not installed.
+    """
+    try:
+        root = _load_gpif(gp_path)
+    except _Gp345FileError:
+        import guitarpro
+        try:
+            song = guitarpro.parse(gp_path)
+        except Exception as exc:
+            raise ValueError(f"Cannot parse GP3/4/5 file {gp_path!r}: {exc}") from exc
+        tempo_events = _gp345_tempo_events(song)
+        return [
+            _gp345_tick_to_secs(tempo_events, tick)
+            for tick in _gp345_measure_start_ticks(song)
+        ]
+    return _gpif_bar_starts(root)
+
+
+def gp_has_expandable_repeats(gp_path: str) -> bool:
+    """True when converting `gp_path` expands repeats into a longer timeline
+    than the as-written score auto_sync aligned against.
+
+    gp2rs.convert_file walks the GP3/4/5 playback graph (repeat brackets,
+    voltas, D.S./D.C. directions), so a file using any of those produces an
+    as-performed timeline that auto_sync's as-written sync points cannot be
+    mapped onto. GPIF (.gp/.gpx) conversion is single-pass as-written today,
+    so those files always return False — both sides share one bar order.
+
+    Returns False when the file cannot be parsed (callers fall back to
+    offset-only sync on parse failure anyway).
+    """
+    if Path(gp_path).suffix.lower() in ('.gp', '.gpx'):
+        return False
+    try:
+        import guitarpro
+        song = guitarpro.parse(gp_path)
+    except Exception:
+        return False
+    for mh in song.measureHeaders:
+        if mh.isRepeatOpen or mh.repeatClose >= 0 or mh.repeatAlternative:
+            return True
+        # Both jump SOURCES (fromDirection: D.C., D.S., Da Coda) and jump
+        # TARGETS (direction: Segno, Coda, Fine) count — a plain Da Capo
+        # needs no target marker, so checking `direction` alone would miss
+        # it while gp2rs's playback walker still expands the jump.
+        if (getattr(mh, 'direction', None) is not None
+                or getattr(mh, 'fromDirection', None) is not None):
+            return True
+    return False
+
+
+def build_warp_anchors(
+    sync_points: list[SyncPoint],
+    bar_starts: list[float],
+) -> list[tuple[float, float]]:
+    """Turn sync points into (score_secs, audio_secs) anchor pairs.
+
+    Drops points whose bar index is out of range, points that would break
+    strict monotonicity on either axis (DTW can locally fold on noisy audio;
+    a non-monotonic anchor would make the warp non-invertible and reorder
+    notes), and points whose segment slope implies a physically implausible
+    tempo ratio (outside 0.2x-5x authored). Returns [] when fewer than 2
+    usable anchors remain — callers should fall back to scalar-offset sync
+    in that case.
+    """
+    anchors: list[tuple[float, float]] = []
+    for sp in sorted(sync_points, key=lambda p: p.bar):
+        if not 0 <= sp.bar < len(bar_starts):
+            continue
+        score_t = bar_starts[sp.bar]
+        audio_t = float(sp.time_secs)
+        if anchors and (score_t <= anchors[-1][0] + 1e-6
+                        or audio_t <= anchors[-1][1] + 1e-3):
+            continue
+        if anchors:
+            # Slope sanity gate: a segment whose audio/score tempo ratio is
+            # outside [0.2, 5] is not a performance — it's a DTW fold onto a
+            # repeated section, an abridged recording, or a run of
+            # monotonicity-clamped refine points. Keeping it would crush (or
+            # absurdly stretch) every bar in the span, which is far worse
+            # than interpolating through from the neighbouring anchors.
+            slope = (audio_t - anchors[-1][1]) / (score_t - anchors[-1][0])
+            if not 0.2 <= slope <= 5.0:
+                continue
+        anchors.append((score_t, audio_t))
+    return anchors if len(anchors) >= 2 else []
+
+
+def warp_time(t: float, anchors: list[tuple[float, float]]) -> float:
+    """Map a score-time (seconds) to audio-time via piecewise-linear anchors.
+
+    Between anchors: linear interpolation. Outside the anchor range: the
+    nearest segment's slope is extended, so a count-in before bar 1 and the
+    tail after the last sampled bar keep the local tempo ratio.
+
+    `anchors` must be the >=2-point strictly-monotonic list produced by
+    build_warp_anchors.
+    """
+    lo = 0
+    hi = len(anchors) - 1
+    if t <= anchors[0][0]:
+        seg = (anchors[0], anchors[1])
+    elif t >= anchors[hi][0]:
+        seg = (anchors[hi - 1], anchors[hi])
+    else:
+        # Binary search for the segment containing t
+        while hi - lo > 1:
+            mid = (lo + hi) // 2
+            if anchors[mid][0] <= t:
+                lo = mid
+            else:
+                hi = mid
+        seg = (anchors[lo], anchors[hi])
+    (s0, a0), (s1, a1) = seg
+    slope = (a1 - a0) / (s1 - s0)
+    return a0 + (t - s0) * slope
+
+
+def warp_song_times(song, warp) -> None:
+    """Apply a monotonic time-mapping callable to every absolute time in a
+    lib.song.Song, in place.
+
+    Covers beats, sections, song_length, and per-arrangement notes (onset +
+    sustain), chords (incl. chord notes), anchors, hand shapes, per-phrase
+    difficulty levels, tone changes, and tempo overrides. Durations (note
+    sustain, handshape span) are warped as end-start so they stretch with the
+    local tempo ratio; sub-second intra-note envelopes (bend curves, which are
+    relative to the note onset) are left untouched.
+
+    Duck-typed: accepts any object with the lib.song.Song surface.
+
+    Identity-safe: parse_arrangement shares the SAME Note/Chord/Anchor/
+    HandShape objects between the flat arrangement lists and the
+    max-difficulty phrase level, so each object is warped at most once no
+    matter how many containers reference it.
+    """
+    seen: set[int] = set()
+
+    def _once(obj) -> bool:
+        key = id(obj)
+        if key in seen:
+            return False
+        seen.add(key)
+        return True
+
+    def _warp_notes(notes):
+        for n in notes or []:
+            if not _once(n):
+                continue
+            end = warp(n.time + n.sustain)
+            n.time = warp(n.time)
+            n.sustain = max(0.0, end - n.time)
+
+    def _warp_chords(chords):
+        for c in chords or []:
+            if not _once(c):
+                continue
+            c.time = warp(c.time)
+            _warp_notes(c.notes)
+
+    def _warp_anchors(anchors):
+        for a in anchors or []:
+            if _once(a):
+                a.time = warp(a.time)
+
+    def _warp_handshapes(shapes):
+        for h in shapes or []:
+            if not _once(h):
+                continue
+            start = warp(h.start_time)
+            end = warp(h.end_time)
+            h.start_time = start
+            h.end_time = max(start, end)
+
+    song.song_length = max(0.0, warp(song.song_length))
+    for b in song.beats:
+        b.time = warp(b.time)
+    for s in song.sections:
+        s.start_time = warp(s.start_time)
+    for arr in song.arrangements:
+        _warp_notes(arr.notes)
+        _warp_chords(arr.chords)
+        _warp_anchors(arr.anchors)
+        _warp_handshapes(arr.hand_shapes)
+        for ph in arr.phrases or []:
+            ph.start_time = warp(ph.start_time)
+            ph.end_time = warp(ph.end_time)
+            for lvl in ph.levels or []:
+                _warp_notes(lvl.notes)
+                _warp_chords(lvl.chords)
+                _warp_anchors(lvl.anchors)
+                _warp_handshapes(lvl.hand_shapes)
+        if arr.tones and isinstance(arr.tones, dict):
+            for change in arr.tones.get('changes') or []:
+                if isinstance(change, dict) and isinstance(change.get('t'), (int, float)):
+                    change['t'] = warp(float(change['t']))
+        for tempo_ev in arr.tempos or []:
+            if isinstance(tempo_ev, dict) and isinstance(tempo_ev.get('time'), (int, float)):
+                tempo_ev['time'] = warp(float(tempo_ev['time']))
+
+
 def _estimate_audio_offset(
     root: ET.Element,
     audio_path: str,
@@ -932,12 +1222,7 @@ def auto_sync(
         # below line up with the chroma timeline.
         _tempo_events_gp345 = _gp345_tempo_events(_gp345x_song)
         # Convert tick events to bar events using actual measure start ticks
-        _measure_starts = []  # cumulative tick at start of each bar
-        _cum = 0
-        for _mh2 in _gp345x_song.measureHeaders:
-            _measure_starts.append(_cum)
-            _ts = _mh2.timeSignature
-            _cum += int(_ts.numerator * (4.0 / _ts.denominator.value) * _GP345_TICKS_PER_QUARTER)
+        _measure_starts = _gp345_measure_start_ticks(_gp345x_song)
 
         def _tick_to_bar(tick):
             """Return 0-based bar index for a given tick position."""
@@ -1024,6 +1309,216 @@ def auto_sync(
         sync_points=sync_points,
     )
 
+def refine_sync(
+    sync: GpSyncData,
+    audio_path: str,
+    bars_per_point: int = 8,
+    gp_path: str | None = None,
+    sr: int = _SR,
+    search_radius: float = 0.35,
+    phase_step: float = 0.005,
+    onset_tolerance: float = 0.05,
+) -> GpSyncData:
+    """Refine coarse DTW sync points with a per-bar onset phase sweep.
+
+    auto_sync's mid-song points inherit the DTW frame granularity (~186ms at
+    the default hop). This pass re-times a denser grid of bars — every
+    `bars_per_point`-th bar plus the first and last — by sweeping a local
+    beat grid (±`search_radius`s in `phase_step` steps) against detected
+    onsets and keeping the phase that aligns best, narrowing each kept point
+    to roughly the phase-step resolution on percussive material.
+
+    Args:
+        sync:            Coarse sync data from auto_sync (or a prior refine).
+        audio_path:      The same audio file auto_sync aligned against.
+        bars_per_point:  Refined-point density; every Nth bar gets a point.
+        gp_path:         Optional path to the GP file. When given, exact
+                         per-bar score times (bar_start_times) drive the
+                         densified grid; without it the grid is limited to
+                         a 4/4 approximation built from the points' authored
+                         tempos, and accuracy degrades on odd meters.
+        sr:              Analysis sample rate.
+        search_radius:   ±seconds around each coarse estimate to sweep.
+        phase_step:      Sweep resolution in seconds.
+        onset_tolerance: Max onset-to-click distance that counts as aligned.
+
+    Returns:
+        A new GpSyncData with the refined (and usually denser) points and a
+        recomputed audio_offset. Returns `sync` unchanged when it has no
+        usable points. Quiet bars (fewer than 4 onsets nearby) keep their
+        coarse interpolated time rather than locking onto noise.
+    """
+    if not sync.sync_points:
+        return sync
+
+    pts = sorted(sync.sync_points, key=lambda p: p.bar)
+
+    bar_starts: list[float] | None = None
+    if gp_path:
+        try:
+            bar_starts = bar_start_times(gp_path)
+        except Exception as exc:
+            _log.warning("refine_sync: bar_start_times(%s) failed (%s) — "
+                         "falling back to 4/4 tempo model", gp_path, exc)
+    if bar_starts is None:
+        # Approximate score bar starts from the points' authored tempos,
+        # assuming 4 beats per bar (all GpSyncData carries without the file).
+        max_bar = pts[-1].bar
+        bar_starts = [0.0]
+        ti = 0
+        cur_bpm = pts[0].original_tempo or 120.0
+        for b in range(1, max_bar + 1):
+            while ti + 1 < len(pts) and pts[ti + 1].bar <= b - 1:
+                ti += 1
+                cur_bpm = pts[ti].original_tempo or cur_bpm
+            bar_starts.append(bar_starts[-1] + 4 * 60.0 / max(cur_bpm, 1e-3))
+
+    anchors = build_warp_anchors(pts, bar_starts)
+    if len(anchors) < 2:
+        _log.warning("refine_sync: fewer than 2 usable anchors — returning "
+                     "input unchanged")
+        return sync
+
+    # Authored-tempo lookup via the shared bar-map scan (_tempo_at_bar) so
+    # boundary semantics can't drift from the rest of the module.
+    _orig_map = [(p.bar, p.original_tempo or 120.0) for p in pts]
+
+    def _orig_bpm_at(bar: int) -> float:
+        return max(_tempo_at_bar(_orig_map, bar), 1e-3)
+
+    n_bars = len(bar_starts)
+    step = max(1, int(bars_per_point))
+    targets = sorted(set(range(0, n_bars, step)) | {n_bars - 1})
+
+    # Deferred past the pure early-return paths above so degenerate inputs
+    # (no points, <2 anchors) resolve without librosa installed.
+    import librosa
+    import numpy as np
+
+    y, _ = librosa.load(audio_path, sr=sr, mono=True)
+    audio_dur = len(y) / sr
+    hop = 512  # ~23ms at 22050Hz — fine enough for onset timing
+    onset_frames = librosa.onset.onset_detect(
+        y=y, sr=sr, hop_length=hop, backtrack=True
+    )
+    onset_times = np.asarray(
+        librosa.frames_to_time(onset_frames, sr=sr, hop_length=hop)
+    )
+
+    refined: list[tuple[int, float]] = []
+    for b in targets:
+        score_t = bar_starts[b]
+        coarse = warp_time(score_t, anchors)
+        if coarse > audio_dur + 1.0:
+            break  # bar falls past the end of the recording
+        # Local beat period in AUDIO time: authored beat period scaled by the
+        # local warp slope (recording tempo / authored tempo around this bar).
+        slope = warp_time(score_t + 1.0, anchors) - coarse
+        slope = min(max(slope, 0.25), 4.0)
+        beat_period = (60.0 / _orig_bpm_at(b)) * slope
+
+        # Keep the scoring grid short: beat_period is estimated from the
+        # coarse anchors (a few % off), and grid drift grows linearly with
+        # distance — 16 beats at 2% error is already ~150ms of skew at the
+        # far end, which drags the sweep. 8 beats bounds that to ~beat noise.
+        grid_span = 8 * beat_period
+        # Clamp the sweep window below half a beat so the neighbouring beat
+        # is never a candidate — on periodic material (steady drums) a grid
+        # shifted by one whole beat scores identically and the sweep could
+        # lock a full beat off. DTW coarse error is ~1 analysis frame, which
+        # this window still covers at all but extreme tempos.
+        radius = min(search_radius, 0.45 * beat_period)
+        w_lo = coarse - radius - onset_tolerance
+        w_hi = coarse + radius + grid_span + onset_tolerance
+        local = onset_times[(onset_times >= w_lo) & (onset_times <= w_hi)]
+        if len(local) < 4:
+            refined.append((b, coarse))
+            continue
+
+        best_t, best_score, best_dist = coarse, -1, 0.0
+        for phase in np.arange(coarse - radius, coarse + radius + 1e-9,
+                               phase_step):
+            clicks = np.arange(phase, phase + grid_span, beat_period)
+            score = int(sum(
+                1 for t in local
+                if float(np.min(np.abs(clicks - t))) < onset_tolerance
+            ))
+            dist = abs(float(phase) - coarse)
+            # Ties break toward the coarse estimate so a flat score surface
+            # (sustained pads, sparse onsets) can't drag the point sideways.
+            if score > best_score or (score == best_score and dist < best_dist):
+                best_score, best_t, best_dist = score, float(phase), dist
+
+        # A sweep that matched almost nothing found a spurious edge
+        # alignment, not the beat grid — this happens when the true phase
+        # lies outside the (ambiguity-clamped) window, e.g. fast tempos
+        # where the DTW coarse error exceeds half a beat. Keeping the
+        # coarse estimate degrades gracefully instead of locking a
+        # fraction of a beat off.
+        if best_score < 3:
+            refined.append((b, coarse))
+            continue
+
+        # The onset-count score is flat within ±onset_tolerance of the true
+        # phase, so the sweep alone can be off by up to the tolerance. Snap
+        # inside that plateau: shift by the median residual between matched
+        # onsets and their nearest grid click. Only the first few beats
+        # count here — they are nearly insensitive to beat_period error,
+        # while far clicks would leak that error into the residuals.
+        if best_score > 0:
+            clicks = np.arange(best_t, best_t + 4 * beat_period + 1e-9,
+                               beat_period)
+            residuals = []
+            for t in local:
+                d = clicks - float(t)
+                j = int(np.argmin(np.abs(d)))
+                if abs(d[j]) < onset_tolerance:
+                    residuals.append(-float(d[j]))  # onset minus click
+            if residuals:
+                best_t += float(np.median(residuals))
+        refined.append((b, best_t))
+
+    if not refined:
+        return sync
+
+    # Enforce monotonicity: a point refined earlier than its predecessor
+    # would fold the warp. Clamp to a small positive gap.
+    mono: list[tuple[int, float]] = []
+    prev_t: float | None = None
+    for b, t in refined:
+        t = max(t, 0.0)
+        if prev_t is not None and t <= prev_t + 0.02:
+            t = prev_t + 0.02
+        mono.append((b, t))
+        prev_t = t
+
+    # Recompute per-segment modified tempos from the refined times (same
+    # formula _extract_sync_points uses; the last point carries the previous
+    # segment's tempo forward).
+    new_points: list[SyncPoint] = []
+    for i, (b, t) in enumerate(mono):
+        obpm = _orig_bpm_at(b)
+        if i + 1 < len(mono):
+            b2, t2 = mono[i + 1]
+            score_seg = bar_starts[b2] - bar_starts[b]
+            audio_seg = t2 - t
+            mod = obpm * (score_seg / audio_seg) if audio_seg > 1e-3 else obpm
+            mod = max(20.0, min(300.0, mod))
+        else:
+            mod = new_points[-1].modified_tempo if new_points else obpm
+        new_points.append(SyncPoint(
+            bar=b, time_secs=t, modified_tempo=mod, original_tempo=obpm,
+        ))
+
+    _log.info("refine_sync: %d points (was %d), audio_offset=%.3fs",
+              len(new_points), len(pts), -new_points[0].time_secs)
+    return GpSyncData(
+        audio_offset=-new_points[0].time_secs,
+        audio_asset_id=sync.audio_asset_id,
+        sync_points=new_points,
+    )
+
+
 def estimate_audio_offset(gp_path: str, audio_path: str) -> float:
     """
     Estimate the audio_offset for a GP file aligned to an audio file.

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

@@ -0,0 +1,406 @@
+"""Text-matching engine for MusicBrainz metadata enrichment (P8).
+
+Pure functions only — no network, no database, no server imports — so the
+whole matching pipeline is unit-testable in isolation. server.py owns the
+throttled HTTP transport and the song_enrichment writes; this module owns:
+
+* denoise/tokenize: fold community chart-title noise (author suffixes,
+  ``(440Hz)``/``(Live)``/``(No Lead)``/``(v2)`` parentheticals, punctuation,
+  diacritics, ``AC DC``/``ACDC``/``AC/DC`` spelling drift) into a comparable
+  token form,
+* similarity + scoring: token-set similarity on artist+title with year and
+  duration proximity as corroborating bonuses,
+* tier classification: auto (high) / review (medium) / none (low) — the
+  design rule is that a WRONG match is worse than no match, so the auto
+  tier is deliberately strict and medium confidence goes to a human,
+* MusicBrainz JSON parsing: normalize ``/ws/2`` recording documents into
+  the flat candidate dicts the review UI and song_enrichment store.
+"""
+
+import re
+import unicodedata
+
+# ── Tier thresholds ───────────────────────────────────────────────────────────
+# Combined score = 0.5*artist_sim + 0.5*title_sim + corroboration bonuses
+# (capped at 1.0). Wrong-match is worse than slow (design §5), so `auto`
+# additionally requires BOTH fields to individually agree — a perfect title
+# with a mismatched artist (a cover) must never auto-canonicalize, whatever
+# the combined threshold is set to. AUTO_MIN is only the DEFAULT: the host
+# surfaces it as the user-configurable "auto-apply confidence" setting and
+# passes the chosen value into classify(auto_min=…).
+AUTO_MIN = 0.90
+AUTO_ARTIST_MIN = 0.8
+AUTO_TITLE_MIN = 0.6
+REVIEW_MIN = 0.65
+
+YEAR_BONUS = 0.05        # candidate year within ±1 of the chart's year
+DURATION_BONUS = 0.05    # candidate length within 5s of the chart's audio
+DURATION_BONUS_LOOSE = 0.025   # …within 15s
+_DURATION_TIGHT = 5
+_DURATION_LOOSE = 15
+
+# Release-group secondary types that mark a NON-canonical release (a live album,
+# a greatest-hits comp, a remix/DJ set, …). Used both to pick the canonical
+# studio album for display and to reward studio recordings in ranking.
+_SECONDARY_SKIP = {
+    "live", "compilation", "remix", "dj-mix", "mixtape/street",
+    "demo", "interview", "audiobook", "spokenword",
+}
+
+# ── Denoise ───────────────────────────────────────────────────────────────────
+# A parenthetical/bracketed group is dropped when it contains any of these
+# noise terms as a whole word (chart-variant markers, tuning/pitch notes,
+# performance qualifiers) or when it reads as an author credit ("by X",
+# "charted by X"). Both sides of a comparison are denoised symmetrically, so
+# over-stripping a meaningful group costs a little precision but never
+# produces an asymmetric mismatch.
+_NOISE_TERMS = (
+    r"440\s*hz", r"a440", r"432\s*hz",
+    r"live", r"acoustic", r"instrumental",
+    r"no\s+(?:lead|rhythm|bass|vocals?|drums)",
+    r"(?:lead|rhythm|bass)\s+only",
+    r"v\d+", r"ver(?:sion)?\s*\d+",
+    r"remaster(?:ed)?(?:\s*\d{4})?", r"re-?recorded?",
+    r"fix(?:ed)?", r"updated?",
+    r"bonus", r"custom",
+)
+_NOISE_GROUP_RE = re.compile(
+    r"[(\[][^)\]]*\b(?:" + "|".join(_NOISE_TERMS) + r")\b[^)\]]*[)\]]",
+    re.IGNORECASE,
+)
+# Author credits: "(by SomeCharter)", "[charted by X]", "(chart by X)".
+_AUTHOR_GROUP_RE = re.compile(
+    r"[(\[]\s*(?:chart(?:ed)?\s+)?by\s+[^)\]]*[)\]]", re.IGNORECASE)
+# Trailing "- by SomeCharter" outside parens.
+_AUTHOR_TAIL_RE = re.compile(r"\s+-\s+(?:chart(?:ed)?\s+)?by\s+.+$", re.IGNORECASE)
+
+_PUNCT_RE = re.compile(r"[^\w\s]|_")
+_WS_RE = re.compile(r"\s+")
+
+
+def _strip_diacritics(s: str) -> str:
+    return "".join(
+        ch for ch in unicodedata.normalize("NFKD", s)
+        if not unicodedata.combining(ch)
+    )
+
+
+def denoise(s, *, strip_leading_the: bool = False) -> str:
+    """Fold a community metadata string into its comparable form:
+    lowercase, diacritics stripped, noise parentheticals and author credits
+    removed, punctuation collapsed to spaces. ``strip_leading_the`` drops a
+    leading "The " — used for ARTIST comparison only ("The Beatles" ==
+    "Beatles"), never titles ("The Trooper" must keep its "the")."""
+    s = str(s or "")
+    s = _NOISE_GROUP_RE.sub(" ", s)
+    s = _AUTHOR_GROUP_RE.sub(" ", s)
+    s = _AUTHOR_TAIL_RE.sub(" ", s)
+    s = _strip_diacritics(s).casefold()
+    s = s.replace("&", " and ")
+    s = _PUNCT_RE.sub(" ", s)
+    s = _WS_RE.sub(" ", s).strip()
+    if strip_leading_the and s.startswith("the "):
+        s = s[4:]
+    return s
+
+
+def tokens(s, **kw) -> list[str]:
+    d = denoise(s, **kw)
+    return d.split() if d else []
+
+
+def _compact(toks: list[str]) -> str:
+    return "".join(toks)
+
+
+def similarity(a, b, *, artist: bool = False) -> float:
+    """Token-set similarity in [0, 1]. Dice coefficient over the denoised
+    token sets, with a compacted-string equality fold so spelling drift that
+    only moves token boundaries ("ACDC" / "AC DC" / "AC/DC", "Greenday" /
+    "Green Day") counts as identical."""
+    kw = {"strip_leading_the": artist}
+    ta, tb = tokens(a, **kw), tokens(b, **kw)
+    if not ta or not tb:
+        return 0.0
+    if _compact(ta) == _compact(tb):
+        return 1.0
+    sa, sb = set(ta), set(tb)
+    return 2.0 * len(sa & sb) / (len(sa) + len(sb))
+
+
+def _year_int(v):
+    try:
+        y = int(str(v)[:4])
+        return y if y > 0 else None
+    except (TypeError, ValueError):
+        return None
+
+
+def _duration_int(v):
+    try:
+        d = int(round(float(v)))
+        return d if d > 0 else None
+    except (TypeError, ValueError):
+        return None
+
+
+def cand_artist_sim(song: dict, cand: dict) -> float:
+    """Best artist similarity between the song's reference artist and the
+    candidate's PRIMARY name OR any of its `artist_aliases` (romanized/alternate
+    names). MusicBrainz stores many artists under a non-Latin primary name
+    (大橋純子) with the romanized form ("Junko Ohashi") only as an alias, so a
+    reference typed/derived in romaji scores 0 against the primary but 1.0
+    against the alias. The caller (server) attaches `artist_aliases` only for
+    promising near-misses, so this is a plain max when they're present and the
+    original single comparison when they're not."""
+    best = similarity(song.get("artist"), cand.get("artist"), artist=True)
+    for alias in cand.get("artist_aliases") or []:
+        if best >= 1.0:
+            break
+        s = similarity(song.get("artist"), alias, artist=True)
+        if s > best:
+            best = s
+    return best
+
+
+def score_candidate(song: dict, cand: dict) -> float:
+    """Combined confidence that MusicBrainz candidate `cand` is the song the
+    chart transcribes. 0.5*artist + 0.5*title, plus small year/duration
+    corroboration bonuses, capped at 1.0. Missing fields score 0 on their
+    half — classify() separately refuses to auto-match without both."""
+    artist_sim = cand_artist_sim(song, cand)
+    title_sim = similarity(song.get("title"), cand.get("title"))
+    score = 0.5 * artist_sim + 0.5 * title_sim
+    sy, cy = _year_int(song.get("year")), _year_int(cand.get("year"))
+    if sy and cy and abs(sy - cy) <= 1:
+        score += YEAR_BONUS
+    sd, cd = _duration_int(song.get("duration")), _duration_int(cand.get("duration"))
+    if sd and cd:
+        diff = abs(sd - cd)
+        if diff <= _DURATION_TIGHT:
+            score += DURATION_BONUS
+        elif diff <= _DURATION_LOOSE:
+            score += DURATION_BONUS_LOOSE
+    # NB: the studio-vs-live distinction is deliberately NOT scored here — a live
+    # take is still the RIGHT SONG (same title/artist), so it must not change the
+    # auto/review confidence. Canonical-version preference lives in the RANK sort
+    # (rank_candidates) instead, where it only reorders same-song candidates.
+    return min(score, 1.0)
+
+
+def classify(song: dict, cand: dict, score: float, auto_min: float | None = None) -> str:
+    """Tier for a scored candidate: 'auto' | 'review' | 'none'.
+
+    `auto` (tier-2) needs the combined score AND per-field agreement AND
+    both fields present — a perfect-title/wrong-artist cover, or a chart
+    with no artist at all, is at best a review item, never an auto match.
+    `auto_min` overrides the default combined-score threshold (the user's
+    "auto-apply confidence" setting); the per-field floors always apply.
+    """
+    if auto_min is None:
+        auto_min = AUTO_MIN
+    artist_sim = cand_artist_sim(song, cand)
+    title_sim = similarity(song.get("title"), cand.get("title"))
+    if (score >= auto_min and artist_sim >= AUTO_ARTIST_MIN
+            and title_sim >= AUTO_TITLE_MIN):
+        return "auto"
+    if score >= REVIEW_MIN:
+        return "review"
+    return "none"
+
+
+def rank_candidates(song: dict, candidates: list[dict]) -> list[dict]:
+    """Score every candidate against the song and return them sorted best-first.
+    The combined `score` caps at 1.0, so a perfect-text-match query (every "AC/DC
+    Highway to Hell" recording) ties at the top — there the studio flag and, when
+    the caller knows the audio length, the duration match break the tie so the
+    canonical studio take wins over live/promo/extended cuts. Each returned dict
+    is a copy carrying `score` (rounded — it's displayed and stored)."""
+    sd = _duration_int(song.get("duration"))
+    # For a chart that IS a live take (build_recording_query keeps live
+    # recordings for these) the studio take is the WRONG recording, so drop the
+    # studio tiebreak — duration proximity + text/mb score then pick the right
+    # live version instead of auto-matching the studio one.
+    prefer_studio = not _LIVE_GROUP_RE.search(str(song.get("title") or ""))
+
+    def _dur_diff(c):
+        cd = _duration_int(c.get("duration"))
+        return abs(sd - cd) if (sd and cd) else 10 ** 6
+
+    ranked = []
+    for cand in candidates or []:
+        c = dict(cand)
+        c["score"] = round(score_candidate(song, cand), 4)
+        ranked.append(c)
+    ranked.sort(
+        key=lambda c: (c["score"],
+                       (1 if c.get("studio") else 0) if prefer_studio else 0,
+                       -_dur_diff(c),                 # closest to the audio length
+                       c.get("mb_score") or 0),
+        reverse=True)
+    return ranked
+
+
+# ── MusicBrainz query + response parsing ──────────────────────────────────────
+
+def _lucene_escape_phrase(s: str) -> str:
+    """Escape a string for use inside a quoted Lucene phrase."""
+    return s.replace("\\", "\\\\").replace('"', '\\"')
+
+
+# A parenthetical/bracketed "(Live …)" marker — the live signal denoise() strips
+# from the title. Mirrors _NOISE_GROUP_RE but for the `live` term only.
+_LIVE_GROUP_RE = re.compile(r"[(\[][^)\]]*\blive\b[^)\]]*[)\]]", re.IGNORECASE)
+
+
+def build_recording_query(artist, title, *, loose: bool = False) -> str:
+    """Lucene query for /ws/2/recording. Built from the DENOISED fields —
+    the noise we strip (author credits, "(Live)", "(v2)") would otherwise
+    poison the search server's own scoring.
+
+    ``loose=True`` drops the field-scoped quoted PHRASES for plain AND-ed
+    term groups (``(telephone number) AND (junko ohashi)``). The point:
+    a field phrase like ``artist:"Junko Ohashi"`` only matches MusicBrainz's
+    *primary* artist name — it never searches ALIASES — so a recording stored
+    under a non-Latin primary (大橋純子) whose romanized name is only an alias
+    is invisible to the strict query. A loose term query searches the whole
+    document, aliases included, and surfaces it. Lower precision by design: it
+    is a FALLBACK for when the strict query returns nothing, and its results
+    are re-scored by ``rank_candidates`` (and, for auto-match, gated by the
+    per-field floors), so noise never auto-applies."""
+    t = denoise(title)
+    a = denoise(artist)
+    if loose:
+        # denoise() already reduced each field to lowercase [a-z0-9 and] tokens
+        # (punctuation → spaces, diacritics stripped, & → "and"), so no
+        # Lucene-special character survives to need escaping. Group each field's
+        # terms and require both groups.
+        q = " AND ".join("(%s)" % g for g in (t, a) if g)
+        # Keep the SAME live exclusion as the strict path: the loose query is
+        # lower-precision, and score_candidate doesn't penalize a live take, so
+        # without this a studio chart whose strict query missed could fall back
+        # to — and auto-confirm — a live-only recording. Skipped only when the
+        # source title is itself a live take (mirrors the strict path).
+        if q and not _LIVE_GROUP_RE.search(str(title or "")):
+            q += " AND -secondarytype:Live"
+        return q
+    parts = []
+    if t:
+        parts.append('recording:"%s"' % _lucene_escape_phrase(t))
+    if a:
+        parts.append('artist:"%s"' % _lucene_escape_phrase(a))
+    q = " AND ".join(parts)
+    # Drop live-ONLY recordings (bootlegs, live albums) — the canonical studio
+    # take is never tagged Live, and this is the single biggest source of junk in
+    # a flat recording search. Compilations are deliberately NOT excluded: they
+    # REUSE the studio recording, so filtering them would drop the very recording
+    # we want (verified against MusicBrainz — `-secondarytype:Compilation` cut the
+    # AC/DC studio "Highway to Hell" recording entirely).
+    #
+    # EXCEPT when the source chart is itself a live take: denoise() strips the
+    # "(Live at …)" qualifier from the query, so filtering Live would leave the
+    # genuinely-live chart with NO correct recording. Only a parenthetical marker
+    # counts — a bare title word ("Live and Let Die") is a real word, not a live
+    # tag — mirroring what denoise removes.
+    if q and not _LIVE_GROUP_RE.search(str(title or "")):
+        q += " AND -secondarytype:Live"
+    return q
+
+
+def _artist_credit(doc: dict) -> tuple[str, str, str]:
+    """(display name, artist mbid, sort name) from an artist-credit array."""
+    credits = doc.get("artist-credit") or []
+    name = ""
+    for part in credits:
+        if isinstance(part, dict):
+            name += str(part.get("name", "")) + str(part.get("joinphrase", "") or "")
+        else:  # ws/2 can emit bare join strings in older serializations
+            name += str(part)
+    first = next((p for p in credits if isinstance(p, dict)), None) or {}
+    artist = first.get("artist") or {}
+    return name, str(artist.get("id", "") or ""), str(artist.get("sort-name", "") or "")
+
+
+def _is_clean_studio_album(rg: dict) -> bool:
+    """A release-group that is a primary-type Album with NO non-canonical
+    secondary type (Live / Compilation / Remix / …) — i.e. a studio album."""
+    if str(rg.get("primary-type", "")).lower() != "album":
+        return False
+    secs = {str(s).lower() for s in (rg.get("secondary-types") or [])}
+    return not (secs & _SECONDARY_SKIP)
+
+
+def _best_release(doc: dict) -> dict:
+    """Pick the release used for canon album/year: prefer an OFFICIAL studio
+    Album (primary Album with no Live/Compilation/… secondary type), then the
+    earliest date. Falls back to any release when none is clean. {} if none."""
+    releases = [r for r in (doc.get("releases") or []) if isinstance(r, dict)]
+    if not releases:
+        return {}
+
+    def sort_key(r):
+        rg = r.get("release-group") or {}
+        clean = 0 if _is_clean_studio_album(rg) else 1
+        status_ok = 0 if str(r.get("status", "")).lower() == "official" else 1
+        date = str(r.get("date", "") or "9999")
+        # Official FIRST, then prefer a clean studio album: this still surfaces
+        # the studio album over an (official) live/comp album for the display
+        # album/year, but never lets an UNofficial bootleg album outrank an
+        # official single/EP/comp — which `(clean, status_ok, …)` would.
+        return (status_ok, clean, date)
+
+    return sorted(releases, key=sort_key)[0]
+
+
+def _genres(doc: dict, limit: int = 5) -> list[str]:
+    """Genre names from a recording doc. Search results carry folksonomy
+    `tags`; lookups with inc=genres carry curated `genres`. Both are
+    [{name, count}] — take the most-voted few."""
+    raw = doc.get("genres") or doc.get("tags") or []
+    entries = [e for e in raw if isinstance(e, dict) and e.get("name")]
+    entries.sort(key=lambda e: e.get("count") or 0, reverse=True)
+    return [str(e["name"]) for e in entries[:limit]]
+
+
+def parse_recording_doc(doc: dict) -> dict | None:
+    """Normalize one /ws/2 recording document (search hit or direct lookup)
+    into the flat candidate dict stored in song_enrichment.candidates and
+    rendered by the review drawer. Returns None for malformed docs."""
+    if not isinstance(doc, dict) or not doc.get("id") or not doc.get("title"):
+        return None
+    artist_name, artist_id, artist_sort = _artist_credit(doc)
+    release = _best_release(doc)
+    studio = _is_clean_studio_album(release.get("release-group") or {})
+    length = doc.get("length")
+    try:
+        duration = int(round(float(length) / 1000.0)) if length else None
+    except (TypeError, ValueError):
+        duration = None
+    isrcs = doc.get("isrcs") or []
+    isrcs = [str(i) for i in isrcs if isinstance(i, (str,))]
+    return {
+        "recording_id": str(doc["id"]),
+        "title": str(doc.get("title", "")),
+        "artist": artist_name,
+        "artist_id": artist_id,
+        "artist_sort": artist_sort,
+        "release_id": str(release.get("id", "") or ""),
+        "album": str(release.get("title", "") or ""),
+        "year": str(release.get("date", "") or "")[:4],
+        "duration": duration,
+        "isrc": isrcs[0] if isrcs else "",
+        "genres": _genres(doc),
+        "mb_score": int(doc.get("score") or 0),
+        "studio": studio,
+    }
+
+
+def parse_search_response(body: dict) -> list[dict]:
+    """Candidates from a /ws/2/recording search response."""
+    docs = (body or {}).get("recordings") or []
+    out = []
+    for doc in docs:
+        cand = parse_recording_doc(doc)
+        if cand:
+            out.append(cand)
+    return out

lib/midi_import.py

@@ -203,7 +203,13 @@ def convert_midi_track_to_keys_wire(
     #     a foreign track's tempo events do NOT apply to the chosen
     #     track. Merging would mis-time the notes — restrict the tempo
     #     scan to the selected track only.
-    ticks_per_beat = midi.ticks_per_beat
+    # ``ticks_per_beat`` is 0 for a malformed header and NEGATIVE for SMPTE
+    # division (mido returns the signed short as-is). Both feed the two
+    # divisions below (tempo-table build + tick_to_seconds), so guard here:
+    # 0 would raise ZeroDivisionError and a negative value would yield
+    # negative/garbage times. Use ``> 0`` (not ``or``) so the negative SMPTE
+    # case also falls back to the SMF default.
+    ticks_per_beat = midi.ticks_per_beat if midi.ticks_per_beat > 0 else 480
     raw_events: list[tuple[int, int]] = [(0, 500000)]  # default 120 BPM
     midi_type = getattr(midi, "type", 1)
     tempo_source = (
@@ -352,7 +358,14 @@ def _build_tick_to_seconds(midi: mido.MidiFile, track_index: int) -> Callable[[i
       - type 1: parallel tracks share the timeline; merge tempo events.
       - type 2: independent timelines; tempo only from the chosen track.
     """
-    ticks_per_beat = midi.ticks_per_beat
+    # A metrical header carries positive ticks-per-beat. mido reads the SMF
+    # division as a signed short, so an SMPTE-division file surfaces as a
+    # negative value and a malformed header as 0 — both make the two division
+    # sites below divide by a non-positive number (ZeroDivisionError, or
+    # negative seconds that send the bar walk off the rails). Fall back to the
+    # SMF default here, the single place every caller routes ticks through, so
+    # each caller's own fallback is real rather than cosmetic.
+    ticks_per_beat = midi.ticks_per_beat if midi.ticks_per_beat > 0 else 480
     raw_events: list[tuple[int, int]] = [(0, 500000)]  # default 120 BPM
     midi_type = getattr(midi, "type", 1)
     tempo_source = (
@@ -393,6 +406,141 @@ def _build_tick_to_seconds(midi: mido.MidiFile, track_index: int) -> Callable[[i
     return tick_to_seconds
 
 
+# Safety valve for the bar walk below: a malformed SMF (absurd tempo + long
+# trailing meta) could otherwise imply millions of bars. Real charts sit
+# orders of magnitude below this.
+_TEMPO_MAP_MAX_BARS = 20000
+
+
+def convert_midi_tempo_map(midi_path: str, track_index: int = 0) -> dict:
+    """Extract the song-timeline grid a `.mid` file carries: tempos, time
+    signatures, and a full beat grid — the data the note converters here
+    always computed internally (to bake note times) and then threw away,
+    which left every MIDI import with no bars, no measures, and an implied
+    4/4 no matter what the file said.
+
+    Returns ``{"tempos": [...], "time_signatures": [...], "beats": [...]}``:
+
+    - ``tempos``: ``{time, bpm}`` per tempo event (deduped per tick).
+    - ``time_signatures``: ``{time, ts: [num, den]}`` per signature event —
+      the song-timeline sidecar shape (feedpak-spec §7.4).
+    - ``beats``: one row per beat on the editor grid shape — downbeats carry
+      a running ``measure`` (1, 2, 3, …) plus a ``den`` hint (the signature
+      denominator), interior beats carry ``measure: -1``. The beat unit
+      follows the active signature (6/8 ⇒ six eighth-note rows per bar).
+
+    Event scope mirrors ``_build_tick_to_seconds``: SMF type 0/1 merge meta
+    from all tracks (shared timeline); type 2 reads ONLY ``track_index``
+    (independent timelines — callers must never share one grid across
+    type-2 tracks). Signature changes apply at the NEXT bar boundary when a
+    file places one mid-bar (ill-formed but seen in the wild). All times
+    are computed from absolute ticks through the cumulative tempo table and
+    rounded once at emit — rounding error never accumulates with song
+    length. An SMF with no note events yields empty ``beats``.
+    """
+    midi = mido.MidiFile(midi_path)
+    # Positive for metrical files; 0 (malformed) or negative (SMPTE division,
+    # read as a signed short) otherwise — fall back so beat_ticks below stays
+    # sane, mirroring the guard inside _build_tick_to_seconds.
+    ticks_per_beat = midi.ticks_per_beat if midi.ticks_per_beat > 0 else 480
+    midi_type = getattr(midi, "type", 1)
+    # Same scope both converters use: type 2 reads only the chosen track
+    # (independent timelines); type 0/1 merge all tracks (shared timeline).
+    source_tracks = (
+        [midi.tracks[track_index]] if midi_type == 2 else midi.tracks
+    )
+    tick_to_seconds = _build_tick_to_seconds(midi, track_index)
+
+    # ── collect meta + the end of musical content in one pass ────────────
+    sig_events: list[tuple[int, int, int]] = []
+    tempo_events: list[tuple[int, int]] = []
+    end_tick = 0
+    for tr in source_tracks:
+        abs_tick = 0
+        for msg in tr:
+            abs_tick += msg.time
+            if msg.type == "time_signature":
+                num = int(getattr(msg, "numerator", 4) or 4)
+                den = int(getattr(msg, "denominator", 4) or 4)
+                if num > 0 and den > 0:
+                    sig_events.append((abs_tick, num, den))
+            elif msg.type == "set_tempo":
+                tempo_events.append((abs_tick, int(msg.tempo)))
+            elif msg.type in ("note_on", "note_off"):
+                end_tick = max(end_tick, abs_tick)
+
+    # Dedupe at equal ticks (last wins), matching the tempo-table rule.
+    sig_events.sort(key=lambda e: e[0])
+    sigs: list[tuple[int, int, int]] = []
+    for ev in sig_events:
+        if sigs and sigs[-1][0] == ev[0]:
+            sigs[-1] = ev
+        else:
+            sigs.append(ev)
+    if not sigs or sigs[0][0] > 0:
+        sigs.insert(0, (0, 4, 4))
+
+    tempo_events.sort(key=lambda e: e[0])
+    seen_tempo_ticks: dict[int, int] = {}
+    for ev_tick, ev_tempo in tempo_events:
+        seen_tempo_ticks[ev_tick] = ev_tempo
+    sorted_tempo_ticks = sorted(seen_tempo_ticks)
+    tempos_out: list[dict] = []
+    # Seed the MIDI default (120 BPM) at time 0 when the first tempo event
+    # lands after the start (or there are none). The beat grid already runs
+    # at 120 for the head of the song, so the sidecar must say so too —
+    # symmetric with the (0, 4, 4) default seeded into the signatures above.
+    if not sorted_tempo_ticks or sorted_tempo_ticks[0] > 0:
+        tempos_out.append({"time": 0.0, "bpm": 120.0})
+    for ev_tick in sorted_tempo_ticks:
+        tempos_out.append({
+            "time": round(tick_to_seconds(ev_tick), 3),
+            "bpm": round(60_000_000.0 / seen_tempo_ticks[ev_tick], 3),
+        })
+
+    time_signatures_out = [
+        {"time": round(tick_to_seconds(t), 3), "ts": [num, den]}
+        for t, num, den in sigs
+    ]
+
+    # ── walk bars from tick 0 to the end of the notes ────────────────────
+    beats: list[dict] = []
+    if end_tick > 0:
+        cur_tick = 0.0
+        measure = 1
+        sig_idx = 0
+        while cur_tick < end_tick and measure <= _TEMPO_MAP_MAX_BARS:
+            # Active signature: the latest event at or before this bar's
+            # start. Mid-bar events wait for the next boundary by
+            # construction (we only re-read between bars).
+            while (sig_idx + 1 < len(sigs)
+                    and sigs[sig_idx + 1][0] <= cur_tick + 1e-6):
+                sig_idx += 1
+            _, num, den = sigs[sig_idx]
+            beat_ticks = ticks_per_beat * 4.0 / den
+            beats.append({
+                "time": round(tick_to_seconds(int(round(cur_tick))), 3),
+                "measure": measure,
+                "den": den,
+            })
+            for k in range(1, num):
+                sub_tick = cur_tick + k * beat_ticks
+                if sub_tick >= end_tick:
+                    break
+                beats.append({
+                    "time": round(tick_to_seconds(int(round(sub_tick))), 3),
+                    "measure": -1,
+                })
+            cur_tick += num * beat_ticks
+            measure += 1
+
+    return {
+        "tempos": tempos_out,
+        "time_signatures": time_signatures_out,
+        "beats": beats,
+    }
+
+
 # ── Drum track listing (channel-9 only) ──────────────────────────────────────
 
 # Velocity below this is treated as a ghost note. GM doesn't have an explicit
@@ -486,10 +634,12 @@ def convert_drum_track_from_midi(
 
     Callers can pass an empty dict as ``out_unmapped`` to receive a
     per-MIDI record of every channel-9 note_on that didn't resolve to a
-    piece-id (``{midi: {"count": int, "times": [float, ...]}}``, times
-    capped at 100 samples per note). The default path skips this
-    capture entirely so MIDIs heavy with cowbell/tambourine/etc. take
-    no extra work.
+    piece-id (``{midi: {"count": int, "times": [float, ...],
+    "velocities": [int, ...]}}``, times/velocities index-aligned and
+    capped at 100 samples per note — velocities carry the source notes'
+    real dynamics so a hand-mapping UI doesn't have to flatten them to a
+    default). The default path skips this capture entirely so MIDIs
+    heavy with cowbell/tambourine/etc. take no extra work.
     """
     offset = float(audio_offset)
     if not math.isfinite(offset):
@@ -527,10 +677,13 @@ def convert_drum_track_from_midi(
                     continue
                 t = tick_to_seconds(abs_tick) + offset
                 entry = out_unmapped.setdefault(
-                    midi_note, {"count": 0, "times": []})
+                    midi_note, {"count": 0, "times": [], "velocities": []})
                 entry["count"] += 1
                 if len(entry["times"]) < 100:
                     entry["times"].append(round(t, 3))
+                    # Index-aligned with times: the note's real dynamics,
+                    # so hand-mapping doesn't flatten everything to 100.
+                    entry["velocities"].append(int(msg.velocity))
                 continue
             # Mapped note: compute t once for the raw entry.
             t = tick_to_seconds(abs_tick) + offset

lib/notation_lift.py

@@ -114,11 +114,27 @@ def split_hands(notes: list[dict]) -> dict[str, list[dict]]:
         pitches = sorted(n["midi"] for n in group)
         span = pitches[-1] - pitches[0]
         if len(pitches) > 1 and span > HAND_SPLIT_SPAN_SEMITONES:
-            # Largest internal gap; ties resolve to the lowest such gap so the
-            # left hand keeps the tight low cluster.
-            gaps = [pitches[i + 1] - pitches[i] for i in range(len(pitches) - 1)]
-            split_after = gaps.index(max(gaps))
-            threshold = pitches[split_after]  # lh: midi <= threshold
+            # Prefer middle C as the split boundary when notes straddle it —
+            # this correctly handles bass+treble chords from piano imports where
+            # the largest-gap heuristic picks the wrong split point (e.g.
+            # [G2, E3, C4]: largest gap is G2→E3 but the real split is E3|C4).
+            # BUT only when both resulting hands are themselves playable: a bass
+            # note under a treble voicing that merely dips below C4 (e.g.
+            # [E2, B3, D4, G4]) would otherwise land E2+B3 in one hand — a
+            # 19-semitone span that re-violates HAND_SPLIT_SPAN_SEMITONES. When
+            # the middle-C split produces an unplayable hand, fall back to the
+            # largest internal gap (which correctly isolates E2 there).
+            threshold = None
+            if pitches[0] < MIDDLE_C <= pitches[-1]:
+                _lh = [p for p in pitches if p < MIDDLE_C]
+                _rh = [p for p in pitches if p >= MIDDLE_C]
+                if (_lh[-1] - _lh[0] <= HAND_SPLIT_SPAN_SEMITONES
+                        and _rh[-1] - _rh[0] <= HAND_SPLIT_SPAN_SEMITONES):
+                    threshold = MIDDLE_C - 1  # lh: midi < MIDDLE_C
+            if threshold is None:
+                gaps = [pitches[i + 1] - pitches[i] for i in range(len(pitches) - 1)]
+                split_after = gaps.index(max(gaps))
+                threshold = pitches[split_after]
             for n in group:
                 hands["lh" if n["midi"] <= threshold else "rh"].append(n)
         else:

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

@@ -26,6 +26,13 @@ def safe_join(root: Path, name: str) -> Path | None:
     """
     if not name:
         return None
+    # Reject embedded NULs explicitly. This used to ride on `.resolve()`
+    # raising ValueError, but on Python 3.13 (Windows) resolve() no longer
+    # raises for an embedded NUL, so the byte would otherwise leak through
+    # containment. An explicit guard is strictly-more-rejection (no effect on
+    # the zip-slip / traversal contract).
+    if "\x00" in name:
+        return None
     safe = name.replace("\\", "/")
     try:
         root_resolved = root.resolve()

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
@@ -109,13 +109,14 @@ def _extract_meta_for_file(path: Path, dlc_root=None) -> dict:
     the root it already resolved; in-process callers can pass the resolver
     itself (e.g. `_get_dlc_dir`) to keep the lookup lazy.
 
-    FeedBack reads only its own `.sloppak` format and loose-folder XML
-    songs. Encrypted/proprietary archive formats are not supported and are
-    silently ignored (empty metadata) rather than decrypted.
+    FeedBack reads only its own song-package format (`.feedpak` / legacy
+    `.sloppak`) and loose-folder XML songs. Encrypted/proprietary archive
+    formats are not supported and are silently ignored (empty metadata)
+    rather than decrypted.
     """
-    # Sloppak is detected by `.sloppak` suffix only (cheap), so check it
-    # first — that way a user's loose folder named `foo.sloppak` still wins
-    # the sloppak branch instead of being misclassified.
+    # Packages are detected by suffix only (`.feedpak`/`.sloppak`, cheap), so
+    # check that first — that way a user's loose folder named `foo.feedpak`
+    # still wins the package branch instead of being misclassified.
     if sloppak_mod.is_sloppak(path):
         return _extract_meta_sloppak(path)
     if loosefolder_mod.is_loose_song(path):

lib/sloppak.py

@@ -703,20 +703,32 @@ def load_song(
                     and isinstance(e.get("d"), (int, float))
                 ]
                 if song.lyrics:
-                    # Provenance — populated by the converter (xml/notechart),
-                    # the WhisperX fallback (whisperx), or hand-edits
-                    # (user). Validate against the closed enum so a
-                    # hand-edited (or otherwise malformed) manifest can't
-                    # propagate a YAML dict / list / arbitrary string
-                    # into the highway WS `lyrics.source` field and out
-                    # to plugin badges. Anything outside the enum (or
-                    # the wrong type) falls back to "xml" — the spec's
-                    # back-compat default — instead of being stringified
-                    # and trusted.
-                    _ALLOWED_LYRICS_SOURCES = {"xml", "notechart", "whisperx", "user"}
-                    # Legacy alias: older manifests labelled note-chart-derived
-                    # lyrics with the source format's name; normalise it.
-                    _LYRICS_SOURCE_ALIASES = {"sng": "notechart"}
+                    # Provenance. The feedpak spec (§7.1) vocabulary is
+                    # {authored, transcribed, user}; older manifests + the
+                    # in-tree readers also use the source-format names
+                    # (xml/notechart) and the WhisperX engine name
+                    # (whisperx). Accept the union so both spec-compliant
+                    # writers (e.g. the stem_splitter plugin emitting
+                    # `transcribed`) and legacy packs validate. Validate
+                    # against the closed enum so a hand-edited (or otherwise
+                    # malformed) manifest can't propagate a YAML dict / list /
+                    # arbitrary string into the highway WS `lyrics.source`
+                    # field and out to plugin badges. Anything outside the
+                    # enum (or the wrong type) falls back to "xml" — the
+                    # back-compat default — instead of being stringified and
+                    # trusted.
+                    # Post-alias values only: `whisperx` is normalised to
+                    # `transcribed` before the membership check below, so (like
+                    # `sng`) it is intentionally absent from this set.
+                    _ALLOWED_LYRICS_SOURCES = {
+                        "xml", "notechart", "user",
+                        "authored", "transcribed",
+                    }
+                    # Legacy aliases: older manifests labelled note-chart-derived
+                    # lyrics with the source format's name, and the WhisperX
+                    # fallback with the engine name — normalise both to the
+                    # spec vocabulary the badges now expect.
+                    _LYRICS_SOURCE_ALIASES = {"sng": "notechart", "whisperx": "transcribed"}
                     raw_source = manifest.get("lyrics_source")
                     if isinstance(raw_source, str):
                         raw_source = _LYRICS_SOURCE_ALIASES.get(raw_source, raw_source)
@@ -919,6 +931,12 @@ def extract_meta(path: Path) -> dict:
         "artist": str(manifest.get("artist", "")),
         "album": str(manifest.get("album", "")),
         "year": str(manifest.get("year", "") or ""),
+        # Primary genre from the feedpak `genres` list (spec 1.12.0); [0] = primary.
+        "genre": (lambda g: str(g[0]) if isinstance(g, list) and g else "")(manifest.get("genres")),
+        # Album track order from the feedpak `track`/`disc` fields (spec 1.12.0);
+        # None when unauthored (the album view then falls back to title order).
+        "track_number": (lambda v: int(v) if str(v if v is not None else "").strip().isdigit() else None)(manifest.get("track")),
+        "disc": (lambda v: int(v) if str(v if v is not None else "").strip().isdigit() else None)(manifest.get("disc")),
         "duration": float(manifest.get("duration", 0) or 0),
         "tuning_offsets": tuning_offsets,  # caller maps to a name via tunings.tuning_name
         "arrangements": arrangements,

lib/songmeta.py

@@ -10,9 +10,9 @@ source of truth, so the change survives both incremental and full rescans.
 only the keys present are overwritten, so an edit of just the title can't blank
 out the artist.
 
-Only feedBack's own ``.sloppak`` format (zip- or directory-form) is writable.
-Unknown / unsupported shapes return False and the caller keeps the DB-only
-update.
+Only feedBack's own song-package format (zip- or directory-form, ``.feedpak``
+or the legacy ``.sloppak`` suffix) is writable. Unknown / unsupported shapes
+return False and the caller keeps the DB-only update.
 """
 from __future__ import annotations
 
@@ -107,19 +107,75 @@ def write_sloppak_metadata(path: Path, fields: dict) -> bool:
     return _rewrite_zip_manifest(path, dumped)
 
 
+def gap_fill_sloppak(path: Path, additions: dict) -> bool:
+    """Append ABSENT top-level keys to a sloppak manifest (the gap-fill
+    contract: user-initiated, adds missing keys only, never replaces
+    anything the author set).
+
+    Unlike ``write_sloppak_metadata`` this does NOT re-serialize the
+    manifest — because every added key is absent by definition, the new
+    lines can simply be appended, so the author's existing bytes (key
+    order, comments, formatting) survive verbatim. Directory form gets a
+    one-time ``manifest.yaml.bak`` + temp + atomic replace; zip form goes
+    through the same backup/temp/replace rewriter the metadata editor
+    uses. Returns True if anything was written; raises ``ValueError`` if
+    a requested key already exists (callers are expected to have checked
+    — this is the last-line never-clobber guard)."""
+    import sloppak as sloppak_mod
+
+    path = Path(path)
+    if not additions:
+        return False
+    manifest = sloppak_mod.load_manifest(path) or {}
+    clash = sorted(k for k in additions if k in manifest)
+    if clash:
+        raise ValueError("gap-fill refused: key(s) already present: " + ", ".join(clash))
+
+    if path.is_dir():
+        mf = path / "manifest.yaml"
+        if not mf.exists() and (path / "manifest.yml").exists():
+            mf = path / "manifest.yml"
+        original = mf.read_text(encoding="utf-8")
+    else:
+        with zipfile.ZipFile(str(path), "r") as zin:
+            names = zin.namelist()
+            manifest_name = "manifest.yaml"
+            for cand in ("manifest.yaml", "manifest.yml"):
+                if cand in names:
+                    manifest_name = cand
+                    break
+            original = zin.read(manifest_name).decode("utf-8")
+
+    appended = original if original.endswith("\n") or not original else original + "\n"
+    appended += yaml.safe_dump(additions, sort_keys=False, allow_unicode=True)
+
+    if path.is_dir():
+        backup = mf.with_name(mf.name + ".bak")
+        if not backup.exists():
+            shutil.copy2(mf, backup)
+        tmp = mf.with_name(mf.name + ".tmp")
+        tmp.write_text(appended, encoding="utf-8")
+        tmp.replace(mf)
+        return True
+    return _rewrite_zip_manifest(path, appended)
+
+
 def write_song_metadata(path: Path, fields: dict) -> bool:
     """Persist edited title/artist/album/year into the song's file.
 
-    Dispatches by shape: ``.sloppak`` files and sloppak directories
+    Dispatches by shape: zip-form song packages (``.feedpak`` / legacy
+    ``.sloppak``, per ``sloppak.SONG_EXTS``) and package directories
     (manifest.yaml present). Loose-folder and unknown shapes return False
     (caller keeps the DB-only update). Returns True if the file was modified.
     """
+    from sloppak import SONG_EXTS
+
     path = Path(path)
     suffix = path.suffix.lower()
     if path.is_dir():
         if (path / "manifest.yaml").exists() or (path / "manifest.yml").exists():
             return write_sloppak_metadata(path, fields)
         return False
-    if suffix == ".sloppak":
+    if suffix in SONG_EXTS:
         return write_sloppak_metadata(path, fields)
     return False

lib/tunings.py

@@ -4,51 +4,148 @@ Kept separate from server.py so tests can import it without triggering
 FastAPI / SQLite module-level side effects.
 """
 
+from __future__ import annotations
+
+import math
+
 DEFAULT_REFERENCE_PITCH = 440.0
 
-# Canonical tuning frequencies at 440 Hz reference, keyed by instrument then
-# tuning name. This is the authoritative source; tuner/routes.py previously
-# held a copy — it was removed in favour of this one.
-DEFAULT_TUNINGS: dict[str, dict[str, list[float]]] = {
+# Canonical open strings, low to high, as MIDI notes. This is the host-level
+# source of truth for guitar/bass tuning profiles; UI surfaces derive names,
+# frequencies, and semitone offsets from these absolute pitches.
+STANDARD_OPEN_MIDIS: dict[str, list[int]] = {
+    "guitar-6": [40, 45, 50, 55, 59, 64],
+    "guitar-7": [35, 40, 45, 50, 55, 59, 64],
+    "guitar-8": [30, 35, 40, 45, 50, 55, 59, 64],
+    "bass-4": [28, 33, 38, 43],
+    "bass-5": [23, 28, 33, 38, 43],
+    "bass-6": [23, 28, 33, 38, 43, 48],
+}
+
+# Curated built-in profiles. This intentionally starts by absorbing the useful
+# Virtuoso guitar/bass coverage into host-owned data so the host selector,
+# tuner, practice tools, and plugins can converge on one profile model.
+TUNING_PRESET_MIDIS: dict[str, dict[str, list[int]]] = {
     "guitar-6": {
-        "Standard":    [82.41, 110.00, 146.83, 196.00, 246.94, 329.63],
-        "Eb Standard": [77.78, 103.83, 138.59, 185.00, 233.08, 311.13],
-        "Drop D":      [73.42, 110.00, 146.83, 196.00, 246.94, 329.63],
-        "D Standard":  [73.42,  98.00, 130.81, 174.61, 220.00, 293.66],
-        "Drop C":      [65.41,  98.00, 130.81, 174.61, 220.00, 293.66],
-        "Open G":      [73.42,  98.00, 146.83, 196.00, 246.94, 293.66],
-        "Open D":      [73.42, 110.00, 146.83, 185.00, 220.00, 293.66],
-        "DADGAD":      [73.42, 110.00, 146.83, 196.00, 220.00, 293.66],
-        "Open E":      [82.41, 123.47, 164.81, 207.65, 246.94, 329.63],
+        "Standard": [40, 45, 50, 55, 59, 64],
+        "Eb Standard": [39, 44, 49, 54, 58, 63],
+        "D Standard": [38, 43, 48, 53, 57, 62],
+        "C# Standard": [37, 42, 47, 52, 56, 61],
+        "C Standard": [36, 41, 46, 51, 55, 60],
+        "Drop D": [38, 45, 50, 55, 59, 64],
+        "Drop C": [36, 43, 48, 53, 57, 62],
+        "Drop B": [35, 42, 47, 52, 56, 61],
+        "Drop A": [33, 40, 45, 50, 54, 59],
+        "Drop Ab": [32, 39, 44, 49, 53, 58],
+        "Open G": [38, 43, 50, 55, 59, 62],
+        "Open D": [38, 45, 50, 54, 57, 62],
+        "DADGAD": [38, 45, 50, 55, 57, 62],
+        "Open E": [40, 47, 52, 56, 59, 64],
     },
     "guitar-7": {
-        "Standard":    [61.74, 82.41, 110.00, 146.83, 196.00, 246.94, 329.63],
-        "Drop A":      [55.00, 82.41, 110.00, 146.83, 196.00, 246.94, 329.63],
-        "A Standard":  [55.00, 73.42,  98.00, 130.81, 174.61, 220.00, 293.66],
-        "Drop G":      [49.00, 73.42, 110.00, 146.83, 196.00, 246.94, 329.63],
-        "Bb Standard": [58.27, 77.78, 103.83, 138.59, 185.00, 233.08, 311.13],
+        "Standard": [35, 40, 45, 50, 55, 59, 64],
+        "Bb Standard": [34, 39, 44, 49, 54, 58, 63],
+        "A Standard": [33, 38, 43, 48, 53, 57, 62],
+        "G Standard": [31, 36, 41, 46, 51, 55, 60],
+        "Drop A": [33, 40, 45, 50, 55, 59, 64],
+        "Drop G": [31, 38, 43, 48, 53, 57, 62],
+        "Drop F#": [30, 37, 42, 47, 52, 56, 61],
     },
     "guitar-8": {
-        "Standard":    [46.25, 61.74, 82.41, 110.00, 146.83, 196.00, 246.94, 329.63],
-        "Drop E":      [41.20, 61.74, 82.41, 110.00, 146.83, 196.00, 246.94, 329.63],
-        "E Standard":  [41.20, 55.00, 73.42,  98.00, 130.81, 174.61, 220.00, 293.66],
-        "Drop D":      [36.71, 55.00, 73.42,  98.00, 130.81, 174.61, 220.00, 293.66],
-        "Eb Standard": [38.89, 51.91, 69.30,  92.50, 123.47, 164.81, 207.65, 277.18],
+        "Standard": [30, 35, 40, 45, 50, 55, 59, 64],
+        "Drop E": [28, 35, 40, 45, 50, 55, 59, 64],
+        "Drop A + Drop E": [28, 33, 40, 45, 50, 55, 59, 64],
+        "E Standard": [28, 33, 38, 43, 48, 53, 57, 62],
+        "Eb Standard": [27, 32, 37, 42, 47, 52, 56, 61],
+        "Drop D": [26, 33, 38, 43, 48, 53, 57, 62],
     },
     "bass-4": {
-        "Standard":    [41.20, 55.00, 73.42,  98.00],
-        "Eb Standard": [38.89, 51.91, 69.30,  92.50],
-        "Drop D":      [36.71, 55.00, 73.42,  98.00],
-        "D Standard":  [36.71, 48.99, 65.41,  87.31],
-        "Drop C":      [32.70, 48.99, 65.41,  87.31],
+        "Standard": [28, 33, 38, 43],
+        "Eb Standard": [27, 32, 37, 42],
+        "D Standard": [26, 31, 36, 41],
+        "C# Standard": [25, 30, 35, 40],
+        "C Standard": [24, 29, 34, 39],
+        "Drop D": [26, 33, 38, 43],
+        "Drop C": [24, 31, 36, 41],
+        "BEAD": [23, 28, 33, 38],
     },
     "bass-5": {
-        "Standard":    [30.87, 41.20, 55.00, 73.42,  98.00],
-        "Eb Standard": [29.14, 38.89, 51.91, 69.30,  92.50],
-        "Drop D":      [30.87, 36.71, 55.00, 73.42,  98.00],
-        "D Standard":  [27.50, 36.71, 48.99, 65.41,  87.31],
-        "Drop C":      [27.50, 32.70, 48.99, 65.41,  87.31],
+        "Standard": [23, 28, 33, 38, 43],
+        "High C": [28, 33, 38, 43, 48],
+        "Eb Standard": [22, 27, 32, 37, 42],
+        "D Standard": [21, 26, 31, 36, 41],
+        "C# Standard": [20, 25, 30, 35, 40],
+        "C Standard": [19, 24, 29, 34, 39],
+        "Drop A": [21, 28, 33, 38, 43],
     },
+    "bass-6": {
+        "Standard": [23, 28, 33, 38, 43, 48],
+        "Eb Standard": [22, 27, 32, 37, 42, 47],
+        "D Standard": [21, 26, 31, 36, 41, 46],
+        "C# Standard": [20, 25, 30, 35, 40, 45],
+        "C Standard": [19, 24, 29, 34, 39, 44],
+    },
+}
+
+
+def midi_to_freq(midi: int, reference_pitch: float = DEFAULT_REFERENCE_PITCH) -> float:
+    """Return the frequency for a MIDI note at the supplied A4 reference."""
+    return reference_pitch * math.pow(2, (midi - 69) / 12)
+
+
+def open_midis_to_freqs(midis: list[int], reference_pitch: float = DEFAULT_REFERENCE_PITCH) -> list[float]:
+    """Return rounded frequencies for low-to-high MIDI open strings."""
+    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)
+    if not standard or len(standard) != len(midis):
+        return None
+    return [int(m - s) for m, s in zip(midis, standard)]
+
+
+def tuning_midis_from_offsets(instrument_key: str, offsets: list[int]) -> list[int] | None:
+    """Return absolute open-string MIDI notes for host semitone offsets."""
+    standard = STANDARD_OPEN_MIDIS.get(instrument_key)
+    if not standard or len(standard) != len(offsets):
+        return None
+    return [int(s + o) for s, o in zip(standard, offsets)]
+
+
+def tuning_preset_offsets(instrument_key: str, name: str) -> list[int] | None:
+    """Return host semitone offsets for a named preset."""
+    midis = TUNING_PRESET_MIDIS.get(instrument_key, {}).get(name)
+    if not midis:
+        return None
+    return tuning_offsets_from_midis(instrument_key, midis)
+
+
+# Canonical tuning frequencies at 440 Hz reference, keyed by instrument then
+# tuning name. Kept for the existing /api/tunings contract.
+DEFAULT_TUNINGS: dict[str, dict[str, list[float]]] = {
+    instrument: {
+        name: open_midis_to_freqs(midis)
+        for name, midis in presets.items()
+    }
+    for instrument, presets in TUNING_PRESET_MIDIS.items()
 }
 
 
@@ -67,6 +164,256 @@ def apply_reference_pitch(
     }
 
 
+PROFILE_IDS = ("guitar-lead", "guitar-rhythm", "bass")
+PROFILE_PATHWAYS = ("songs", "practice", "learn", "studio")
+DEFAULT_ACTIVE_INSTRUMENT_PROFILE = "guitar-lead"
+PROFILE_DEFAULTS: dict[str, dict] = {
+    "guitar-lead": {
+        "id": "guitar-lead",
+        "label": "Lead Guitar",
+        "instrument": "guitar",
+        "role": "lead",
+        "string_count": 6,
+        "tuning": "Standard",
+        "reference_pitch": DEFAULT_REFERENCE_PITCH,
+        "pathway": "songs",
+    },
+    "guitar-rhythm": {
+        "id": "guitar-rhythm",
+        "label": "Rhythm Guitar",
+        "instrument": "guitar",
+        "role": "rhythm",
+        "string_count": 6,
+        "tuning": "Standard",
+        "reference_pitch": DEFAULT_REFERENCE_PITCH,
+        "pathway": "songs",
+    },
+    "bass": {
+        "id": "bass",
+        "label": "Bass",
+        "instrument": "bass",
+        "role": "bass",
+        "string_count": 4,
+        "tuning": "Standard",
+        "reference_pitch": DEFAULT_REFERENCE_PITCH,
+        "pathway": "songs",
+    },
+}
+
+
+def instrument_key(instrument: str, string_count: int) -> str:
+    return f"{instrument}-{string_count}"
+
+
+def default_instrument_profiles() -> dict[str, dict]:
+    return {profile_id: dict(profile) for profile_id, profile in PROFILE_DEFAULTS.items()}
+
+
+def _valid_reference_pitch(value) -> float | None:
+    if isinstance(value, bool):
+        return None
+    try:
+        ref = float(value)
+    except (TypeError, ValueError, OverflowError):
+        return None
+    if not math.isfinite(ref) or ref < 430.0 or ref > 450.0:
+        return None
+    return ref
+
+
+def _valid_tuning_for_key(key: str, tuning):
+    if isinstance(tuning, str):
+        if len(tuning) > 64:
+            return None
+        if tuning in TUNING_PRESET_MIDIS.get(key, {}):
+            return tuning
+        # A name that IS a built-in preset for a different key is a misapplied
+        # built-in (e.g. "Drop D" on a 5-string bass, whose low string is B) —
+        # reject it. A name unknown to every built-in table is a provider/custom
+        # tuning (the tuner plugin's, exposed via /api/tunings) that this pure
+        # layer can't resolve — accept it so settings round-trip; the provider
+        # owns its validity.
+        if any(tuning in names for names in TUNING_PRESET_MIDIS.values()):
+            return None
+        return tuning
+    if isinstance(tuning, list):
+        expected = len(STANDARD_OPEN_MIDIS.get(key, []))
+        if len(tuning) != expected:
+            return None
+        if any(isinstance(o, bool) or not isinstance(o, int) or o < -12 or o > 12 for o in tuning):
+            return None
+        return list(tuning)
+    return None
+
+
+def normalize_instrument_profile(profile_id: str, raw) -> tuple[dict | None, str | None]:
+    """Validate one persisted host instrument profile."""
+    base = dict(PROFILE_DEFAULTS.get(profile_id, {}))
+    if not base:
+        return None, f"unknown instrument profile: {profile_id}"
+    if raw is None:
+        return base, None
+    if not isinstance(raw, dict):
+        return None, f"instrument_profiles.{profile_id} must be an object"
+
+    instrument = raw.get("instrument", base["instrument"])
+    if instrument not in ("guitar", "bass"):
+        return None, f"instrument_profiles.{profile_id}.instrument must be 'guitar' or 'bass'"
+
+    try:
+        string_count = int(raw.get("string_count", base["string_count"]))
+    except (TypeError, ValueError, OverflowError):
+        return None, f"instrument_profiles.{profile_id}.string_count must be valid for the instrument"
+    key = instrument_key(instrument, string_count)
+    if key not in STANDARD_OPEN_MIDIS:
+        return None, f"instrument_profiles.{profile_id}.string_count must be valid for the instrument"
+
+    tuning = _valid_tuning_for_key(key, raw.get("tuning", base["tuning"]))
+    if tuning is None:
+        return None, f"instrument_profiles.{profile_id}.tuning must match {key}"
+
+    ref = _valid_reference_pitch(raw.get("reference_pitch", base["reference_pitch"]))
+    if ref is None:
+        return None, f"instrument_profiles.{profile_id}.reference_pitch must be a number between 430 and 450"
+
+    label = raw.get("label", base["label"])
+    if not isinstance(label, str) or len(label) > 64:
+        return None, f"instrument_profiles.{profile_id}.label must be a short string"
+    role = raw.get("role", base["role"])
+    if not isinstance(role, str) or len(role) > 32:
+        return None, f"instrument_profiles.{profile_id}.role must be a short string"
+    pathway = raw.get("pathway", base["pathway"])
+    if not isinstance(pathway, str) or pathway not in PROFILE_PATHWAYS:
+        return None, f"instrument_profiles.{profile_id}.pathway must be one of songs, practice, learn, studio"
+
+    out = dict(base)
+    out.update({
+        "id": profile_id,
+        "label": label,
+        "instrument": instrument,
+        "role": role,
+        "string_count": string_count,
+        "tuning": tuning,
+        "reference_pitch": ref,
+        "pathway": pathway,
+    })
+    return out, None
+
+
+def normalize_instrument_profiles(raw_profiles=None) -> tuple[dict[str, dict] | None, str | None]:
+    """Validate persisted host profiles, filling omitted built-ins with defaults."""
+    if raw_profiles is None:
+        return default_instrument_profiles(), None
+    if not isinstance(raw_profiles, dict):
+        return None, "instrument_profiles must be an object"
+    profiles = {}
+    for profile_id in PROFILE_IDS:
+        profile, error = normalize_instrument_profile(profile_id, raw_profiles.get(profile_id))
+        if error:
+            return None, error
+        profiles[profile_id] = profile
+    return profiles, None
+
+
+def active_profile_id(raw) -> str:
+    return raw if raw in PROFILE_DEFAULTS else DEFAULT_ACTIVE_INSTRUMENT_PROFILE
+
+
+def profile_from_legacy_settings(cfg: dict) -> dict:
+    """Build an active profile from the old flat settings keys."""
+    instrument = cfg.get("instrument") if cfg.get("instrument") in ("guitar", "bass") else "guitar"
+    fallback_sc = 4 if instrument == "bass" else 6
+    try:
+        sc = int(cfg.get("string_count", fallback_sc))
+    except (TypeError, ValueError, OverflowError):
+        sc = fallback_sc
+    key = instrument_key(instrument, sc)
+    if key not in STANDARD_OPEN_MIDIS:
+        sc = fallback_sc
+        key = instrument_key(instrument, sc)
+    tuning = _valid_tuning_for_key(key, cfg.get("tuning", "Standard")) or "Standard"
+    ref = _valid_reference_pitch(cfg.get("reference_pitch", DEFAULT_REFERENCE_PITCH)) or DEFAULT_REFERENCE_PITCH
+    pathway = cfg.get("pathway") if cfg.get("pathway") in PROFILE_PATHWAYS else "songs"
+    profile_id = "bass" if instrument == "bass" else DEFAULT_ACTIVE_INSTRUMENT_PROFILE
+    profile = dict(PROFILE_DEFAULTS[profile_id])
+    profile.update({
+        "instrument": instrument,
+        "string_count": sc,
+        "tuning": tuning,
+        "reference_pitch": ref,
+        "pathway": pathway,
+    })
+    return profile
+
+
+def settings_with_instrument_profiles(cfg: dict) -> dict:
+    """Return settings with canonical host profiles and mirrored flat keys."""
+    out = dict(cfg)
+    profiles, _error = normalize_instrument_profiles(out.get("instrument_profiles"))
+    if profiles is None:
+        profiles = default_instrument_profiles()
+    if "instrument_profiles" not in out:
+        legacy = profile_from_legacy_settings(out)
+        profiles[legacy["id"]] = legacy
+        # Default the active profile to the one migrated from the legacy flat
+        # fields, but DON'T clobber an explicit request — a fresh-config
+        # `POST {"active_instrument_profile": "bass"}` must switch, not be
+        # overwritten by the guitar-lead inferred from defaults. active_profile_id
+        # below normalizes an invalid value.
+        out.setdefault("active_instrument_profile", legacy["id"])
+    active = active_profile_id(out.get("active_instrument_profile"))
+    selected = profiles[active]
+    out["instrument_profiles"] = profiles
+    out["active_instrument_profile"] = active
+    out["instrument"] = selected["instrument"]
+    out["string_count"] = selected["string_count"]
+    out["tuning"] = selected["tuning"]
+    out["reference_pitch"] = selected["reference_pitch"]
+    out["pathway"] = selected["pathway"]
+    return out
+
+
+def apply_flat_instrument_patch_to_profiles(cfg: dict, updates: dict) -> dict:
+    """Mirror legacy flat instrument updates into the active host profile."""
+    out = settings_with_instrument_profiles(cfg)
+    if not any(k in updates for k in ("instrument", "string_count", "tuning", "reference_pitch", "pathway")):
+        return out
+    active = active_profile_id(out.get("active_instrument_profile"))
+    if "instrument" in updates:
+        active = "bass" if updates["instrument"] == "bass" else "guitar-lead"
+        out["active_instrument_profile"] = active
+    current = dict(out["instrument_profiles"][active])
+
+    if "instrument" in updates:
+        current["instrument"] = updates["instrument"]
+        if "string_count" not in updates:
+            current["string_count"] = 4 if updates["instrument"] == "bass" else 6
+    if "string_count" in updates:
+        current["string_count"] = updates["string_count"]
+    if "reference_pitch" in updates:
+        current["reference_pitch"] = updates["reference_pitch"]
+    if "pathway" in updates:
+        current["pathway"] = updates["pathway"]
+    if "tuning" in updates:
+        current["tuning"] = updates["tuning"]
+    else:
+        key = instrument_key(current["instrument"], current["string_count"])
+        if _valid_tuning_for_key(key, current.get("tuning")) is None:
+            current["tuning"] = "Standard"
+
+    profile, error = normalize_instrument_profile(active, current)
+    if error:
+        raise ValueError(error)
+    out["instrument_profiles"][active] = profile
+    out.update({
+        "instrument": profile["instrument"],
+        "string_count": profile["string_count"],
+        "tuning": profile["tuning"],
+        "reference_pitch": profile["reference_pitch"],
+        "pathway": profile["pathway"],
+    })
+    return out
+
 def tuning_name(offsets: list[int]) -> str:
     # All three pattern checks below are gated on `len(offsets) == 6`. The
     # naming conventions here are 6-string-specific — e.g. a 7-string all-zeros

package.json

@@ -8,9 +8,12 @@
     "test:headed": "playwright test --headed",
     "test:debug": "playwright test --debug",
     "test:js": "node --test tests/js/*.test.js 'tests/plugins/*/js/*.test.js'",
-    "install:playwright": "playwright install chromium"
+    "install:playwright": "playwright install chromium",
+    "lint": "eslint ."
   },
   "devDependencies": {
-    "@playwright/test": "^1.59.1"
+    "@playwright/test": "^1.59.1",
+    "eslint": "^9.39.4",
+    "eslint-plugin-import-x": "^4.17.1"
   }
 }

plugins/__init__.py

@@ -18,6 +18,54 @@ from safepath import safe_join
 log = logging.getLogger("feedBack.plugins")
 
 
+def _plugin_media_type(path: Path) -> str:
+    """Best-effort Content-Type for a served plugin file. `.js`/`.css` must come
+    back as JavaScript/CSS so `<script type=module>` / `addModule()` / a `<link>`
+    accept them; `mimetypes.guess_type` can miss these on a stripped platform
+    registry, so fall back explicitly (mirrors the assets/ route)."""
+    media_type = mimetypes.guess_type(path.name)[0]
+    if media_type is None and path.suffix == ".js":
+        return "application/javascript"
+    if media_type is None and path.suffix == ".css":
+        return "text/css"
+    return media_type or "application/octet-stream"
+
+
+def _plugin_file_etag(path: Path) -> str | None:
+    """Weak ETag from mtime+size — cheap, stable across reads, changes on edit.
+    This is what makes the live-edit loop work for module graphs: a conditional
+    GET revalidates and 304s unchanged files on refresh instead of re-downloading
+    the whole `src/` tree. Returns None if the file can't be stat'd."""
+    try:
+        st = path.stat()
+    except OSError:
+        return None
+    return f'W/"{st.st_mtime_ns:x}-{st.st_size:x}"'
+
+
+def _if_none_match(request: Request, etag: str) -> bool:
+    """True when the client's If-None-Match already holds `etag`."""
+    # ponytail: we serve one weak ETag; the browser echoes it back verbatim, so
+    # a direct compare is enough (comma-split tolerates a proxy concatenation).
+    return etag in [t.strip() for t in request.headers.get("if-none-match", "").split(",")]
+
+
+def _plugin_file_response(request: Request, path: Path, media_type: str) -> Response:
+    """Serve a plugin source/asset file with the live-edit cache contract:
+    `Cache-Control: no-cache` (browser may store but MUST revalidate) + a weak
+    ETag, and a bodyless 304 when the client's If-None-Match already matches.
+    Starlette's `FileResponse` emits an ETag but never evaluates If-None-Match
+    itself, so the conditional handling has to live here."""
+    headers = {"Cache-Control": "no-cache"}
+    etag = _plugin_file_etag(path)
+    if etag:
+        headers["ETag"] = etag
+        if _if_none_match(request, etag):
+            return Response(status_code=304, headers=headers)
+    # FileResponse sets etag/last-modified via setdefault, so the ETag above wins.
+    return FileResponse(path, media_type=media_type, headers=headers)
+
+
 PLUGINS_DIR = Path(__file__).parent
 # Holds only *ready* (loaded) plugins — those whose dependencies installed
 # and whose routes registered. A plugin GRADUATES from PENDING_PLUGINS into
@@ -1373,6 +1421,12 @@ def load_plugins(app: FastAPI, context: dict, progress_cb=None, route_setup_fn=N
             "version": manifest.get("version"),
             "has_screen": bool(manifest.get("screen")),
             "has_script": bool(manifest.get("script")),
+            # Module-migration (R0): `scriptType:"module"` tells the loader to
+            # inject screen.js as <script type="module">; `minHost` is the
+            # min core version a migrated plugin needs (passthrough only in R0 —
+            # enforcement is deferred to R4, master §4b). None when unset.
+            "script_type": manifest.get("scriptType"),
+            "min_host": manifest.get("minHost"),
             "has_settings": bool(manifest.get("settings")),
             "settings_category": _settings_category,
             # Drives the v3 shell's immersive (full-screen) mode for this
@@ -2089,6 +2143,11 @@ def register_plugin_api(app: FastAPI):
                 "fallback": p.get("fallback", False),
                 "has_screen": p["has_screen"],
                 "has_script": p["has_script"],
+                # Module-migration passthrough (R0). Re-read from the manifest
+                # like `version` above so stubbed test entries (built without
+                # _nav_entry) don't need the key.
+                "script_type": (p.get("_manifest") or {}).get("scriptType"),
+                "min_host": (p.get("_manifest") or {}).get("minHost"),
                 "has_settings": p["has_settings"],
                 # v3 immersive screen opt-in (full-screen plugin UI).
                 "fullscreen": p.get("fullscreen", False),
@@ -2142,6 +2201,9 @@ def register_plugin_api(app: FastAPI):
                 "fallback": False,
                 "has_screen": e.get("has_screen", False),
                 "has_script": e.get("has_script", False),
+                # Pending entries come from _nav_entry, so they carry these.
+                "script_type": e.get("script_type"),
+                "min_host": e.get("min_host"),
                 "has_settings": e.get("has_settings", False),
                 "settings_category": e.get("settings_category"),
                 "fullscreen": e.get("fullscreen", False),
@@ -2307,7 +2369,7 @@ def register_plugin_api(app: FastAPI):
         return HTMLResponse("", status_code=404)
 
     @app.get("/api/plugins/{plugin_id}/screen.js")
-    def plugin_screen_js(plugin_id: str):
+    def plugin_screen_js(request: Request, plugin_id: str):
         with PLUGINS_LOCK:
             snapshot = list(LOADED_PLUGINS)
         for p in snapshot:
@@ -2315,8 +2377,11 @@ def register_plugin_api(app: FastAPI):
                 if p.get("status", "ready") != "ready":
                     break
                 script_file = p["_dir"] / p["_manifest"].get("script", "screen.js")
-                if script_file.exists():
-                    return Response(script_file.read_text(encoding="utf-8"), media_type="application/javascript")
+                if script_file.is_file():
+                    # no-cache + ETag/304 so an edited screen.js reloads on
+                    # refresh while an unchanged one revalidates cheaply — the
+                    # same live-edit contract the src/ module graph relies on.
+                    return _plugin_file_response(request, script_file, "application/javascript")
         return Response("", status_code=404)
 
     @app.get("/api/plugins/{plugin_id}/settings.html")
@@ -2377,7 +2442,7 @@ def register_plugin_api(app: FastAPI):
         return Response("{}", status_code=404, media_type="application/json")
 
     @app.get("/api/plugins/{plugin_id}/assets/{asset_path:path}")
-    def plugin_asset(plugin_id: str, asset_path: str):
+    def plugin_asset(request: Request, plugin_id: str, asset_path: str):
         """Serve a static file a plugin bundles under its own ``assets/``
         directory (e.g. an AudioWorklet module, WASM, or image). Unlike the
         fixed screen.js/settings.html handlers above, this is a generic
@@ -2399,16 +2464,35 @@ def register_plugin_api(app: FastAPI):
                     log.warning("Plugin %r: asset path rejected: %r", plugin_id, asset_path)
                     break
                 if target.is_file():
-                    media_type = mimetypes.guess_type(target.name)[0]
-                    # .js must come back as JavaScript so addModule() / <script>
-                    # accept it; guess_type can miss this on some platforms.
-                    if media_type is None and target.suffix == ".js":
-                        media_type = "application/javascript"
-                    # .css must come back as text/css so a <link rel=stylesheet>
-                    # (the styles capability) is honoured; guess_type can miss it
-                    # on a stripped platform mimetypes registry, same as .js.
-                    elif media_type is None and target.suffix == ".css":
-                        media_type = "text/css"
-                    return FileResponse(target, media_type=media_type or "application/octet-stream")
+                    # no-cache + ETag/304 so a live-edited worklet/asset reloads
+                    # on refresh (bare FileResponse emits an ETag but never 304s).
+                    return _plugin_file_response(request, target, _plugin_media_type(target))
+                break
+        return Response("", status_code=404)
+
+    @app.get("/api/plugins/{plugin_id}/src/{src_path:path}")
+    def plugin_src(request: Request, plugin_id: str, src_path: str):
+        """Serve a file from a plugin's ES-module source tree under ``src/``.
+
+        This is the R0 host capability that lets a migrated plugin's
+        ``screen.js`` (a one-line ``import './src/main.js'``) load its whole
+        module graph. Containment mirrors the assets/ route exactly —
+        ``safe_join`` against ``<plugin>/src`` rejects ``..``, absolute paths,
+        and NUL bytes — and the live-edit cache contract (no-cache + ETag/304)
+        makes an edited module reload on refresh while unchanged ones 304.
+        Read-only; the src/ tree is source files, never executed server-side.
+        """
+        with PLUGINS_LOCK:
+            snapshot = list(LOADED_PLUGINS)
+        for p in snapshot:
+            if p["id"] == plugin_id:
+                if p.get("status", "ready") != "ready":
+                    break
+                target = safe_join(p["_dir"] / "src", src_path)
+                if target is None:
+                    log.warning("Plugin %r: src path rejected: %r", plugin_id, src_path)
+                    break
+                if target.is_file():
+                    return _plugin_file_response(request, target, _plugin_media_type(target))
                 break
         return Response("", status_code=404)

plugins/drum_highway_3d/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.DS_Store
+Thumbs.db
+*.swp
+.vscode/
+.idea/

plugins/drum_highway_3d/LICENSE

@@ -0,0 +1,661 @@
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU Affero General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.

plugins/drum_highway_3d/README.md

@@ -0,0 +1,100 @@
+# 3D Drum Highway — Mockup
+
+![3D Drum Highway mockup screenshot](screenshots/drum-highway-3d.png)
+
+An exploratory **pure-visual** sibling of `highway_3d`. Renders an 8-lane
+drum highway (7 lanes for hand pieces + a full-width kick bar) populated
+from a hardcoded demo pattern that loops indefinitely. Not yet wired to
+song data, hit detection, audio, or note_detect — this is here to play
+with the look-and-feel.
+
+To see it, load any song in the player, then pick **3D Drum Highway**
+from the viz picker. The mockup animates regardless of what song is
+playing.
+
+## Layout
+
+```
+ [HH]  [SNR]  [TM1]  [TM2]  [FT]  [CR]  [RD]    <- 7 lanes, left to right
+   |    |      |      |     |    |     |
+   v    v      v      v     v    v     v
+ -----  hit line  -----------------------------
+ ▓▓▓▓▓▓▓▓▓▓▓▓▓ KICK BAR ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓     <- full-width kick lane
+```
+
+- **Drums** (snare, toms, floor tom): flat disc geometry (`CylinderGeometry`),
+  palette-tinted, with subtle emissive pulse on approach. Snare gets a
+  thin white "wires" stripe.
+- **Cymbals** (hi-hat, crash, ride): faceted gem geometry (truncated
+  `CylinderGeometry`), metallic material, slightly translucent.
+- **Kick**: full-width amber bar across the base, brighter on approach.
+
+## Variants visible in the demo
+
+| Variant | How it reads |
+|---|---|
+| `accent` | Bigger note + white halo ring |
+| `ghost`  | Hollow ring (~65% size) instead of a solid disc |
+| `flam`   | Main note + a small grace disc offset slightly before |
+| `bell`   | Ride only — adds a bright dot in the center of the gem |
+
+The **Fill showcase** demo pattern fires every variant at least once in
+a few bars, plus a tom roll down the kit. Best read of what's possible.
+
+## Settings (Settings → Plugins → 3D Drum Highway)
+
+- **Palette** — shared 3 palettes with `highway_3d` (default / neon / pastel).
+- **Demo pattern** — rock backbeat / jazz swing / fill showcase.
+- **Camera angle** — 0 (down the lanes) to 1 (top-down). Default 0.35.
+
+All settings persist in `localStorage` under the `drum_h3d_*` prefix.
+
+## What this plugin is *not* doing yet
+
+(Historical note: this started as a pure-visual mockup; it now reads
+`bundle.drumTab` + `bundle.currentTime` and scores MIDI hits against the
+chart, so the old "no song-data wiring" caveats are gone.)
+
+- Sustain trails (drums don't sustain meaningfully)
+- Sticking labels, double kick, rolls — see the TODOs in `screen.js`
+  for the variant backlog
+
+## Ported helpers (keep in sync with highway_3d)
+
+Visual-parity code copied from `plugins/highway_3d/screen.js` — same
+function names, signatures, and constants on purpose, marked with
+`PORTED FROM highway_3d` comments at each site. If the guitar highway
+tunes one of these, mirror the change here (and in `keys_highway_3d`):
+
+- `_bloomEnsure()` / `_bloomDispose()` — EffectComposer + UnrealBloomPass
+  (0.65/0.5/0.82) on a multisampled HalfFloat target, ACES↔None tone-
+  mapping switch in `draw()`; addons dynamic-imported from
+  `/static/vendor/three/addons/` (no CDN fallback — direct render is the
+  graceful degrade)
+- `_sparkBurst()` / `_sparkUpdate()` — pooled additive Points hit sparks
+  (pool 160 here vs the guitar's 256)
+- `_makeGaussTex()` — soft-falloff DataTexture for the additive lane-flash
+  quads
+- `_timingHex()` — early/late/on-time feedback colors (green/cyan/amber)
+- `_ssActive()` — host splitscreen probe (minus the guitar's focus-API
+  checks, which it needs for input routing and we don't)
+- `BG_THEMES` / `_bgThemeColors()` — the scene theme table (same ids/values
+  as the guitar's, except `default` which is this plugin's original
+  palette); one pick drives both of the guitar's background/highway axes
+- `_applyCinematic()` — ambient/key rebalance (values tuned per plugin)
+- `BG_STYLES` (off/particles/lights/geometric) + `_bgGetAnalyser()` /
+  `_bgReadBands()` — background ambience + the stems-first audio-analyser
+  bridge (guitar's diagnostics plumbing dropped; butterchurn/image/video
+  out of scope)
+- `_drawScoreFx()` — the guitar's drawScoreFx overlay adapted to this
+  plugin's internal scoring (pops / tier rings / milestone bursts /
+  streak-break wash)
+
+## Why a separate plugin (vs. drum mode inside highway_3d)?
+
+Cleaner iteration. The drum highway is its own geometry, its own
+gameplay assumptions (lanes ≠ strings, no frets, no chord shapes,
+no sustains), and likely its own chart format. Forking the visuals
+in a sibling plugin lets the mockup move fast without risking
+regressions in the guitar viz that ships today. If the drum highway
+eventually matures, we can decide whether to merge or keep separate.

plugins/drum_highway_3d/assets/thumb.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="256" viewBox="0 0 256 256" role="img" aria-label="3D Drum Highway placeholder thumbnail">
+  <rect width="256" height="256" rx="36" fill="#0f172a"/>
+  <rect x="18" y="18" width="220" height="220" rx="28" fill="#1e293b" stroke="#334155" stroke-width="3"/>
+  <text x="128" y="150" font-family="Rubik, Arial, sans-serif" font-size="104" font-weight="800" fill="#38bdf8" text-anchor="middle">3D</text>
+</svg>

plugins/drum_highway_3d/plugin.json

@@ -0,0 +1,39 @@
+{
+  "id": "drum_highway_3d",
+  "name": "3D Drum Highway",
+  "version": "0.3.2",
+  "type": "visualization",
+  "bundled": true,
+  "script": "screen.js",
+  "settings": {
+    "html": "settings.html",
+    "category": "graphics"
+  },
+  "standards": [
+    "capability-pipelines.v1",
+    "plugin-runtime-idempotent.v1"
+  ],
+  "capabilities": {
+    "midi-input": {
+      "roles": [
+        "requester"
+      ],
+      "requests": [
+        "discover",
+        "list-sources",
+        "select-source",
+        "open-source",
+        "close-source"
+      ],
+      "mode": "active",
+      "compatibility": "degrade-noop",
+      "ownership": "requester-only",
+      "safety": "sensitive",
+      "description": "Reads the e-kit/MIDI-pad input through the core midi-input domain (Web-MIDI provider ships built-in with the domain). Absent domain \u2192 no MIDI devices, fail-soft.",
+      "version": 1
+    }
+  },
+  "category": "practice",
+  "description": "3D note highway for drum charts.",
+  "icon": "assets/thumb.svg"
+}

plugins/drum_highway_3d/settings.html

@@ -0,0 +1,615 @@
+<div role="group" aria-labelledby="drumh3d-heading">
+    <h3 id="drumh3d-heading" class="text-sm font-medium text-gray-400 mb-2">3D Drum Highway</h3>
+    <p class="text-xs text-gray-500 mb-3">
+        Pick a song with a drum tab (sloppak-spec §5.3), choose <em>3D
+        Drum Highway</em> from the viz picker. The plugin auto-attaches
+        to your MIDI controller and routes chart pieces through the kit
+        you configure below.
+    </p>
+
+    <!-- Palette -->
+    <div class="mt-3">
+        <label for="drumh3d-palette" class="text-xs font-medium text-gray-400 mb-1 block">Palette</label>
+        <select id="drumh3d-palette"
+            onchange="window.drumH3dSetPalette && window.drumH3dSetPalette(this.value); (window._drumH3dRenderPaletteSwatches || function(){})(this.value)"
+            class="w-full bg-dark-700 border border-gray-800 rounded-lg px-3 py-2 text-xs text-gray-300 outline-none">
+            <option value="default">Default (Classic)</option>
+            <option value="neon">Neon (saturated, electric)</option>
+            <option value="pastel">Pastel (soft, low contrast)</option>
+        </select>
+        <div class="mt-2 flex items-center gap-1" aria-hidden="true">
+            <span id="drumh3d-swatch-0" class="inline-block h-6 w-5 rounded border border-gray-700/60"></span>
+            <span id="drumh3d-swatch-1" class="inline-block h-6 w-5 rounded border border-gray-700/60"></span>
+            <span id="drumh3d-swatch-2" class="inline-block h-6 w-5 rounded border border-gray-700/60"></span>
+            <span id="drumh3d-swatch-3" class="inline-block h-6 w-5 rounded border border-gray-700/60"></span>
+            <span id="drumh3d-swatch-4" class="inline-block h-6 w-5 rounded border border-gray-700/60"></span>
+            <span id="drumh3d-swatch-5" class="inline-block h-6 w-5 rounded border border-gray-700/60"></span>
+            <span id="drumh3d-swatch-6" class="inline-block h-6 w-5 rounded border border-gray-700/60"></span>
+            <span id="drumh3d-swatch-7" class="inline-block h-6 w-5 rounded border border-gray-700/60"
+                  style="background:#ffa030"></span>
+        </div>
+    </div>
+
+    <!-- Camera angle -->
+    <div class="mt-4">
+        <label for="drumh3d-camera" class="text-xs font-medium text-gray-400 mb-1 block">
+            Camera angle <span id="drumh3d-camera-val" class="text-gray-500 font-mono">0.35</span>
+        </label>
+        <input type="range" id="drumh3d-camera"
+            min="0" max="1" step="0.05" value="0.35"
+            oninput="window.drumH3dSetCameraAngle && window.drumH3dSetCameraAngle(this.value); document.getElementById('drumh3d-camera-val').textContent = parseFloat(this.value).toFixed(2)"
+            class="w-full">
+        <p class="text-xs text-gray-500 mt-1">0 = down the lanes · 1 = top-down</p>
+    </div>
+
+    <!-- Graphics -->
+    <div class="mt-6 border-t border-gray-800 pt-4">
+        <h4 class="text-xs font-medium text-gray-300 mb-2">Graphics</h4>
+
+        <label for="drumh3d-fx-theme" class="text-xs font-medium text-gray-400 mb-1 block">Scene theme</label>
+        <select id="drumh3d-fx-theme"
+            onchange="window.drumH3dSetTheme && window.drumH3dSetTheme(this.value)"
+            class="w-full bg-dark-700 border border-gray-800 rounded-lg px-3 py-2 text-xs text-gray-300 outline-none">
+            <option value="default">Default (original)</option>
+            <option value="midnight">Midnight</option>
+            <option value="charcoal">Charcoal</option>
+            <option value="deeppurple">Deep Purple</option>
+            <option value="forest">Forest</option>
+            <option value="warmslate">Warm Slate</option>
+            <option value="deepfocus">Deep Focus</option>
+            <option value="deepsea">Deep Sea</option>
+            <option value="cathode">Cathode</option>
+            <option value="cathodegreen">Cathode Green</option>
+            <option value="hearth">Hearth</option>
+        </select>
+        <p class="text-xs text-gray-500 mt-1 mb-3">
+            Background, floor and lane colours — the same theme names as the
+            guitar highway, so your look carries across instruments. Piece
+            colours stay with the Palette above.
+        </p>
+
+        <label for="drumh3d-fx-cinematic" class="flex items-center gap-2 text-xs text-gray-300 cursor-pointer">
+            <input type="checkbox" id="drumh3d-fx-cinematic" checked
+                onchange="window.drumH3dSetFx && window.drumH3dSetFx('cinematic', this.checked)">
+            Cinematic lighting
+        </label>
+        <p class="text-xs text-gray-500 mt-1">
+            Dimmer ambience, stronger key light — more depth on the cymbals
+            and drumheads.
+        </p>
+
+        <label for="drumh3d-fx-glow" class="text-xs font-medium text-gray-400 mb-1 mt-3 block">
+            Glow strength <span id="drumh3d-fx-glow-val" class="text-gray-500 font-mono">0.50</span>
+        </label>
+        <input type="range" id="drumh3d-fx-glow"
+            min="0" max="1" step="0.05" value="0.5"
+            oninput="window.drumH3dSetFx && window.drumH3dSetFx('glow', this.value); document.getElementById('drumh3d-fx-glow-val').textContent = parseFloat(this.value).toFixed(2)"
+            class="w-full">
+        <p class="text-xs text-gray-500 mt-1">
+            How hard the notes and hit line self-illuminate (0.5 = stock).
+            Pairs with bloom.
+        </p>
+
+        <label for="drumh3d-fx-vibrancy" class="text-xs font-medium text-gray-400 mb-1 mt-3 block">
+            Lane vibrancy <span id="drumh3d-fx-vibrancy-val" class="text-gray-500 font-mono">0.85</span>
+        </label>
+        <input type="range" id="drumh3d-fx-vibrancy"
+            min="0" max="1" step="0.05" value="0.85"
+            oninput="window.drumH3dSetFx && window.drumH3dSetFx('vibrancy', this.value); document.getElementById('drumh3d-fx-vibrancy-val').textContent = parseFloat(this.value).toFixed(2)"
+            class="w-full">
+        <p class="text-xs text-gray-500 mt-1">
+            Lane stripe and accent-ring strength — lower for a calmer deck.
+        </p>
+
+        <label for="drumh3d-fx-bgstyle" class="text-xs font-medium text-gray-400 mb-1 mt-3 block">Background ambience</label>
+        <select id="drumh3d-fx-bgstyle"
+            onchange="window.drumH3dSetBgStyle && window.drumH3dSetBgStyle(this.value)"
+            class="w-full bg-dark-700 border border-gray-800 rounded-lg px-3 py-2 text-xs text-gray-300 outline-none">
+            <option value="off">Off</option>
+            <option value="particles" selected>Particles</option>
+            <option value="lights">Stage lights</option>
+            <option value="geometric">Geometric</option>
+        </select>
+        <label for="drumh3d-fx-bgintensity" class="text-xs font-medium text-gray-400 mb-1 mt-2 block">
+            Ambience intensity <span id="drumh3d-fx-bgintensity-val" class="text-gray-500 font-mono">0.50</span>
+        </label>
+        <input type="range" id="drumh3d-fx-bgintensity"
+            min="0" max="1" step="0.05" value="0.5"
+            oninput="window.drumH3dSetFx && window.drumH3dSetFx('bgIntensity', this.value); document.getElementById('drumh3d-fx-bgintensity-val').textContent = parseFloat(this.value).toFixed(2)"
+            class="w-full">
+        <label for="drumh3d-fx-bgreactive" class="flex items-center gap-2 text-xs text-gray-300 cursor-pointer mt-2">
+            <input type="checkbox" id="drumh3d-fx-bgreactive" checked
+                onchange="window.drumH3dSetFx && window.drumH3dSetFx('bgReactive', this.checked)">
+            Audio-reactive ambience
+        </label>
+        <p class="text-xs text-gray-500 mt-1">
+            The backdrop pulses with the mix (stems analyser when a sloppak
+            is loaded). Off = it animates on time only.
+        </p>
+
+        <label for="drumh3d-fx-scorefx" class="flex items-center gap-2 text-xs text-gray-300 cursor-pointer mt-3">
+            <input type="checkbox" id="drumh3d-fx-scorefx" checked
+                onchange="window.drumH3dSetFx && window.drumH3dSetFx('scoreFx', this.checked)">
+            Score effects
+        </label>
+        <p class="text-xs text-gray-500 mt-1">
+            +1 pops on hits, a ring pulse every 10-combo, milestone bursts at
+            25/50/100, and a brief red flicker when a streak breaks.
+        </p>
+
+        <label for="drumh3d-fx-bloom" class="flex items-center gap-2 text-xs text-gray-300 cursor-pointer mt-3">
+            <input type="checkbox" id="drumh3d-fx-bloom" checked
+                onchange="window.drumH3dSetFx && window.drumH3dSetFx('bloom', this.checked)">
+            Glow (bloom)
+        </label>
+        <p class="text-xs text-gray-500 mt-1">
+            Soft light-bleed around the hit line and bright notes. Applies
+            live; turn off to reclaim GPU headroom on weak machines.
+        </p>
+
+        <label for="drumh3d-fx-sparks" class="flex items-center gap-2 text-xs text-gray-300 cursor-pointer mt-3">
+            <input type="checkbox" id="drumh3d-fx-sparks" checked
+                onchange="window.drumH3dSetFx && window.drumH3dSetFx('sparks', this.checked)">
+            Hit sparks
+        </label>
+        <p class="text-xs text-gray-500 mt-1">
+            A small particle burst on every scored pad hit.
+        </p>
+
+        <label for="drumh3d-fx-timing" class="flex items-center gap-2 text-xs text-gray-300 cursor-pointer mt-3">
+            <input type="checkbox" id="drumh3d-fx-timing" checked
+                onchange="window.drumH3dSetFx && window.drumH3dSetFx('timingFx', this.checked)">
+            Timing colours
+        </label>
+        <p class="text-xs text-gray-500 mt-1">
+            Tint hit feedback by timing — on-time green, early cyan, late
+            amber. Off = always green.
+        </p>
+
+        <label for="drumh3d-fx-streak" class="flex items-center gap-2 text-xs text-gray-300 cursor-pointer mt-3">
+            <input type="checkbox" id="drumh3d-fx-streak" checked
+                onchange="window.drumH3dSetFx && window.drumH3dSetFx('streakFx', this.checked)">
+            Streak feedback
+        </label>
+        <p class="text-xs text-gray-500 mt-1">
+            Spark bursts grow with your combo.
+        </p>
+
+        <label for="drumh3d-fx-hitfx" class="text-xs font-medium text-gray-400 mb-1 mt-3 block">
+            Hit feedback intensity <span id="drumh3d-fx-hitfx-val" class="text-gray-500 font-mono">0.70</span>
+        </label>
+        <input type="range" id="drumh3d-fx-hitfx"
+            min="0" max="1" step="0.05" value="0.7"
+            oninput="window.drumH3dSetFx && window.drumH3dSetFx('hitFx', this.value); document.getElementById('drumh3d-fx-hitfx-val').textContent = parseFloat(this.value).toFixed(2)"
+            class="w-full">
+        <p class="text-xs text-gray-500 mt-1">
+            Drives the lane flashes, approach glow and the kick camera pulse.
+            0 turns them off.
+        </p>
+    </div>
+
+    <!-- MIDI input -->
+    <div class="mt-6 border-t border-gray-800 pt-4">
+        <h4 class="text-xs font-medium text-gray-300 mb-2">MIDI input</h4>
+        <label for="drumh3d-midi-input" class="text-xs font-medium text-gray-400 mb-1 block">Device</label>
+        <select id="drumh3d-midi-input"
+            onchange="window.drumH3dSetMidiInput && window.drumH3dSetMidiInput(this.value)"
+            class="w-full bg-dark-700 border border-gray-800 rounded-lg px-3 py-1.5 text-xs text-gray-300 outline-none">
+            <option value="">— none —</option>
+        </select>
+        <p class="text-xs text-gray-500 mt-1">
+            Auto-picks the first non-passthrough input on load. Pick "none" to pause hit and miss tracking.
+        </p>
+
+        <label for="drumh3d-synth-vol" class="text-xs font-medium text-gray-400 mb-1 mt-3 block">
+            Kit volume <span id="drumh3d-synth-vol-val" class="text-gray-500 font-mono">0.70</span>
+        </label>
+        <input type="range" id="drumh3d-synth-vol"
+            min="0" max="1" step="0.01" value="0.7"
+            oninput="window.drumH3dSetSynthVolume && window.drumH3dSetSynthVolume(this.value); document.getElementById('drumh3d-synth-vol-val').textContent = parseFloat(this.value).toFixed(2)"
+            class="w-full">
+    </div>
+
+    <!-- Kit configuration -->
+    <div class="mt-6 border-t border-gray-800 pt-4">
+        <h4 class="text-xs font-medium text-gray-300 mb-2">My kit</h4>
+        <p class="text-xs text-gray-500 mb-3">
+            Add the pieces you actually have, in the order you want them
+            on the highway (left → right). The default fallback routing
+            covers most common kit setups; use the fallbacks panel below
+            to reroute any chart piece to a different lane on your kit,
+            or set it to "—" to silently drop it.
+        </p>
+
+        <label class="text-xs font-medium text-gray-400 mb-1 block">Kit name</label>
+        <input type="text" id="drumh3d-kit-name" maxlength="80"
+            class="w-full bg-dark-700 border border-gray-800 rounded-lg px-3 py-1.5 text-xs text-gray-300 outline-none mb-3"
+            oninput="window._drumH3dKit && window._drumH3dKit.onNameInput(this.value)">
+
+        <label class="text-xs font-medium text-gray-400 mb-1 block">Lanes (left → right on the highway; kick is always a full-width bar)</label>
+        <div id="drumh3d-kit-lanes" class="space-y-1 mb-2"></div>
+
+        <div class="mt-2 mb-3">
+            <label class="text-xs font-medium text-gray-400 mb-1 block">Add a piece</label>
+            <select id="drumh3d-kit-add"
+                onchange="window._drumH3dKit && window._drumH3dKit.onAddPiece(this.value); this.value=''"
+                class="w-full bg-dark-700 border border-gray-800 rounded-lg px-3 py-1.5 text-xs text-gray-300 outline-none">
+                <option value="">— pick a piece to add —</option>
+            </select>
+        </div>
+
+        <details class="mt-2 mb-3">
+            <summary class="text-xs text-gray-400 cursor-pointer">Chart fallbacks for pieces I don't have</summary>
+            <p class="text-xs text-gray-500 mt-2 mb-2">
+                When a song uses a piece that isn't on your kit, route it
+                to one of your lanes. Set "—" to silently drop that piece.
+            </p>
+            <div id="drumh3d-kit-fallbacks" class="space-y-1"></div>
+        </details>
+
+        <div class="flex flex-wrap items-center gap-2 mt-3">
+            <button type="button"
+                onclick="window._drumH3dKit && window._drumH3dKit.copyToClipboard()"
+                class="px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs">📋 Copy kit</button>
+            <button type="button"
+                onclick="document.getElementById('drumh3d-kit-import-row').classList.toggle('hidden')"
+                class="px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs">📥 Import kit…</button>
+            <button type="button"
+                onclick="window._drumH3dKit && window._drumH3dKit.resetDefault()"
+                class="px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs">Reset</button>
+            <span id="drumh3d-kit-status" class="text-xs text-gray-500 ml-auto"></span>
+        </div>
+
+        <div id="drumh3d-kit-import-row" class="hidden mt-3">
+            <label class="text-xs font-medium text-gray-400 mb-1 block">Paste a shared kit</label>
+            <textarea id="drumh3d-kit-import-text" rows="3"
+                placeholder="Paste a base64 kit string here…"
+                class="w-full bg-dark-700 border border-gray-800 rounded-lg px-3 py-2 text-[10px] font-mono text-gray-300 outline-none"></textarea>
+            <button type="button"
+                onclick="window._drumH3dKit && window._drumH3dKit.importFromTextarea()"
+                class="mt-2 px-3 py-1.5 bg-emerald-700 hover:bg-emerald-600 rounded-lg text-xs">Apply imported kit</button>
+        </div>
+    </div>
+
+    <script>
+    (function () {
+        // Mirror of PALETTES in screen.js — kept in sync for swatch previews.
+        const PALETTES = {
+            default: [0xff2828, 0xffd400, 0x2080ff, 0xff8020, 0x30d040, 0xa040ff, 0xff6bd5, 0x6bffe6],
+            neon:    [0xff0030, 0xffe800, 0x0080ff, 0xff8030, 0x40ff50, 0xb050ff, 0xff40d0, 0x40ffd0],
+            pastel:  [0xe89aa0, 0xefdf90, 0x9adfee, 0xefb898, 0xa6e0a8, 0xc4a6e0, 0xe0a6c8, 0xa6e0d8],
+        };
+
+        function toHex(n) { return '#' + n.toString(16).padStart(6, '0'); }
+
+        // Palette swatch preview: read the FIRST 8 pieces of the active
+        // kit's lanes (or pad to 8) for colour reference.
+        window._drumH3dRenderPaletteSwatches = function (id) {
+            const pal = PALETTES[id] || PALETTES.default;
+            const kit = (window.drumH3dGetKit && window.drumH3dGetKit()) || null;
+            const lanes = (kit && kit.lanes) || [];
+            // The kick always shows amber — same as the renderer. Other
+            // lanes follow the piece's palette index from screen.js,
+            // retrieved via drumH3dGetPiecePaletteIdx() so settings.html
+            // stays in sync when pieces are added without any copy-paste.
+            const PALETTE_IDX = (window.drumH3dGetPiecePaletteIdx && window.drumH3dGetPiecePaletteIdx()) || {
+                kick: -1,  // sentinel — render amber
+                snare: 0, snare_xstick: 0,
+                hh_closed: 7, hh_open: 7, hh_pedal: 7,
+                tom_hi: 4, tom_mid: 2, tom_low: 5, tom_floor: 5,
+                crash_l: 1, crash_r: 1, splash: 1, china: 1,
+                ride: 3, ride_bell: 3,
+            };
+            for (let i = 0; i < 8; i++) {
+                const el = document.getElementById('drumh3d-swatch-' + i);
+                if (!el) continue;
+                const ln = lanes[i];
+                if (!ln) { el.style.background = '#000'; el.style.opacity = '0.3'; continue; }
+                el.style.opacity = '1';
+                const idx = PALETTE_IDX[ln.piece];
+                if (idx === -1) { el.style.background = '#ffa030'; continue; }
+                el.style.background = toHex(pal[idx ?? 0]);
+            }
+        };
+
+        // Read fresh inside renderKit() — they're set by screen.js's IIFE,
+        // which may not have finished evaluating when this inline script
+        // first runs if the user opens Settings before the player ever loaded.
+
+        // Friendly piece labels — self-contained so renderKit's callbacks
+        // (which run after our local PIECE_LABELS scope has cleared)
+        // still work.
+        const FRIENDLY = {
+            kick: 'Kick',
+            snare: 'Snare', snare_xstick: 'Snare (cross-stick)',
+            hh_closed: 'Hi-hat (closed)', hh_open: 'Hi-hat (open)', hh_pedal: 'Hi-hat (pedal)',
+            tom_hi: 'Tom — high', tom_mid: 'Tom — mid', tom_low: 'Tom — low', tom_floor: 'Floor tom',
+            crash_l: 'Crash (left)', crash_r: 'Crash (right)', splash: 'Splash', china: 'China',
+            ride: 'Ride', ride_bell: 'Ride bell',
+        };
+        function friendly(p) { return FRIENDLY[p] || p; }
+
+        // Render the current kit's lane list with reorder + remove buttons.
+        function renderKit() {
+            const kit = window.drumH3dGetKit ? window.drumH3dGetKit() : null;
+            if (!kit) {
+                // screen.js hasn't published its API yet — defer one tick.
+                // Happens when the settings panel opens before the player
+                // has loaded a song.
+                setTimeout(renderKit, 100);
+                return;
+            }
+            const PIECE_CATEGORY = window.drumH3dGetPieceCategory ? window.drumH3dGetPieceCategory() : {};
+            const ALL_PIECES = window.drumH3dGetAllPieces ? window.drumH3dGetAllPieces() : [];
+            document.getElementById('drumh3d-kit-name').value = kit.name || '';
+
+            // Lanes panel — order matters: up/down buttons reorder, x
+            // removes (also clears any fallback that pointed at the
+            // removed piece on the way out).
+            const lanesEl = document.getElementById('drumh3d-kit-lanes');
+            lanesEl.innerHTML = '';
+            const taken = new Set(kit.lanes.map(l => l.piece));
+            kit.lanes.forEach((ln, i) => {
+                const row = document.createElement('div');
+                row.className = 'flex items-center gap-2 px-2 py-1 bg-dark-700/60 rounded';
+                // Screen readers should hear the user-facing label
+                // ("Hi-hat (closed)") not the internal piece id ("hh_closed").
+                const pieceName = friendly(ln.piece);
+                row.innerHTML =
+                    `<span class="font-mono text-[10px] text-gray-500 w-6 text-center">${i}</span>` +
+                    `<span class="flex-1 text-xs text-gray-300">${pieceName}</span>` +
+                    `<button type="button" data-act="up"   data-i="${i}" class="px-1.5 py-0.5 text-xs text-gray-400 hover:text-white" ${i === 0 ? 'disabled' : ''} title="Move up" aria-label="Move ${pieceName} up">▲</button>` +
+                    `<button type="button" data-act="down" data-i="${i}" class="px-1.5 py-0.5 text-xs text-gray-400 hover:text-white" ${i === kit.lanes.length - 1 ? 'disabled' : ''} title="Move down" aria-label="Move ${pieceName} down">▼</button>` +
+                    `<button type="button" data-act="rm"   data-i="${i}" class="px-1.5 py-0.5 text-xs text-red-400 hover:text-red-300" title="Remove from kit" aria-label="Remove ${pieceName} from kit">✗</button>`;
+                lanesEl.appendChild(row);
+            });
+            lanesEl.querySelectorAll('button').forEach(btn => {
+                btn.onclick = () => {
+                    const i = parseInt(btn.dataset.i, 10);
+                    const act = btn.dataset.act;
+                    const next = JSON.parse(JSON.stringify(kit));
+                    if (act === 'up' && i > 0) {
+                        [next.lanes[i - 1], next.lanes[i]] = [next.lanes[i], next.lanes[i - 1]];
+                    } else if (act === 'down' && i < next.lanes.length - 1) {
+                        [next.lanes[i + 1], next.lanes[i]] = [next.lanes[i], next.lanes[i + 1]];
+                    } else if (act === 'rm') {
+                        const removed = next.lanes[i].piece;
+                        next.lanes.splice(i, 1);
+                        // Drop any fallback that targeted the removed piece
+                        // — it's no longer a valid target.
+                        for (const k of Object.keys(next.fallbacks || {})) {
+                            if (next.fallbacks[k] === removed) delete next.fallbacks[k];
+                        }
+                    } else { return; }
+                    // Guard: drumH3dSetKit returns false when validation
+                    // rejects the kit (e.g. empty lanes[] after last removal).
+                    if (!window.drumH3dSetKit(next)) {
+                        setStatus('Kit must have at least one lane', 'err');
+                    }
+                };
+            });
+
+            // Add-a-piece dropdown — pieces NOT already in lanes, grouped
+            // by category (kick / drums / cymbals).
+            const addSel = document.getElementById('drumh3d-kit-add');
+            addSel.innerHTML = '<option value="">— pick a piece to add —</option>';
+            const groups = { kick: [], drum: [], cymbal: [] };
+            for (const p of ALL_PIECES) {
+                if (taken.has(p)) continue;
+                const cat = PIECE_CATEGORY[p] || 'drum';
+                if (groups[cat]) groups[cat].push(p);
+            }
+            for (const [cat, label] of [['kick', 'Kick'], ['drum', 'Drums'], ['cymbal', 'Cymbals']]) {
+                if (!groups[cat].length) continue;
+                const og = document.createElement('optgroup');
+                og.label = label;
+                for (const p of groups[cat]) {
+                    const opt = document.createElement('option');
+                    opt.value = p;
+                    opt.textContent = friendly(p);
+                    og.appendChild(opt);
+                }
+                addSel.appendChild(og);
+            }
+
+            // Fallback list — every piece NOT in lanes gets a dropdown
+            // mapping it to one of the user's pieces (or "—" to drop).
+            const fbEl = document.getElementById('drumh3d-kit-fallbacks');
+            fbEl.innerHTML = '';
+            for (const p of ALL_PIECES) {
+                if (taken.has(p)) continue;
+                const row = document.createElement('div');
+                row.className = 'flex items-center gap-2 px-2 py-1';
+                const labelTxt = friendly(p);
+                const current = (kit.fallbacks && kit.fallbacks[p]) || '';
+                let optsHtml = '<option value="">— drop —</option>';
+                for (const ln of kit.lanes) {
+                    const sel = ln.piece === current ? ' selected' : '';
+                    optsHtml += `<option value="${ln.piece}"${sel}>${friendly(ln.piece)}</option>`;
+                }
+                row.innerHTML =
+                    `<span class="flex-1 text-xs text-gray-400">${labelTxt}</span>` +
+                    `<span class="text-xs text-gray-600">→</span>` +
+                    `<select data-from="${p}" class="bg-dark-700 border border-gray-800 rounded px-2 py-1 text-xs text-gray-300 outline-none">${optsHtml}</select>`;
+                fbEl.appendChild(row);
+            }
+            fbEl.querySelectorAll('select').forEach(s => {
+                s.onchange = () => {
+                    const next = JSON.parse(JSON.stringify(kit));
+                    next.fallbacks = next.fallbacks || {};
+                    if (s.value) next.fallbacks[s.dataset.from] = s.value;
+                    else delete next.fallbacks[s.dataset.from];
+                    window.drumH3dSetKit(next);  // event-driven renderKit() via drum_h3d:kit
+                };
+            });
+
+            // Refresh palette swatches so they reflect the new lane order.
+            if (window._drumH3dRenderPaletteSwatches) {
+                const pSel = document.getElementById('drumh3d-palette');
+                window._drumH3dRenderPaletteSwatches(pSel ? pSel.value : 'default');
+            }
+        }
+
+        function setStatus(msg, kind) {
+            const el = document.getElementById('drumh3d-kit-status');
+            if (!el) return;
+            el.textContent = msg;
+            el.className = 'text-xs ml-auto ' + (kind === 'err' ? 'text-red-400' : kind === 'ok' ? 'text-emerald-400' : 'text-gray-500');
+            setTimeout(() => { if (el.textContent === msg) el.textContent = ''; }, 3000);
+        }
+
+        // Expose the kit interaction surface to the inline onclick / onchange
+        // attributes used by the markup above.
+        window._drumH3dKit = {
+            onNameInput(name) {
+                // Use the name-only setter to avoid triggering 'drum_h3d:kit'
+                // on every keystroke — that event causes a full WebGL scene
+                // teardown/reinit which produces visible stutter while typing.
+                window.drumH3dSetKitName && window.drumH3dSetKitName(name);
+            },
+            onAddPiece(piece) {
+                if (!piece) return;
+                const kit = window.drumH3dGetKit();
+                kit.lanes.push({ piece });
+                window.drumH3dSetKit(kit);  // event-driven renderKit() via drum_h3d:kit
+            },
+            copyToClipboard() {
+                const b64 = window.drumH3dExportKit && window.drumH3dExportKit();
+                if (!b64) return setStatus('export failed', 'err');
+                const _showImportFallback = (str) => {
+                    // Clipboard unavailable — reveal the import row so the user can
+                    // copy the string from the textarea manually.
+                    document.getElementById('drumh3d-kit-import-row').classList.remove('hidden');
+                    const ta = document.getElementById('drumh3d-kit-import-text');
+                    ta.value = str;
+                    ta.focus();
+                    ta.select();
+                    setStatus('clipboard blocked — copy from the textarea below', 'err');
+                };
+                if (!navigator.clipboard) {
+                    _showImportFallback(b64);
+                    return;
+                }
+                navigator.clipboard.writeText(b64).then(
+                    () => setStatus('✓ kit copied', 'ok'),
+                    () => _showImportFallback(b64),
+                );
+            },
+            importFromTextarea() {
+                const txt = document.getElementById('drumh3d-kit-import-text').value;
+                if (!txt.trim()) return setStatus('paste a kit string first', 'err');
+                const ok = window.drumH3dImportKit && window.drumH3dImportKit(txt);
+                // drumH3dImportKit calls drumH3dSetKit which dispatches drum_h3d:kit;
+                // the event listener re-renders the panel, so no explicit renderKit().
+                if (ok) { setStatus('✓ kit imported', 'ok'); }
+                else setStatus('invalid kit string', 'err');
+            },
+            resetDefault() {
+                window.drumH3dResetKit && window.drumH3dResetKit();
+                // drumH3dResetKit calls drumH3dSetKit → dispatches drum_h3d:kit
+                // → event listener re-renders. No explicit renderKit() needed.
+                setStatus('✓ reset to default', 'ok');
+            },
+        };
+
+        // Re-render the kit list whenever the kit changes (covers external
+        // changes from setKit() / importKit() not initiated by this panel).
+        window.addEventListener('drum_h3d:kit', () => renderKit());
+
+        // ─── MIDI device picker ───────────────────────────────
+        function renderMidiPicker() {
+            const sel = document.getElementById('drumh3d-midi-input');
+            if (!sel) return;
+            const inputs = window.drumH3dListMidiInputs ? window.drumH3dListMidiInputs() : [];
+            const current = window.drumH3dGetMidiInputId ? window.drumH3dGetMidiInputId() : '';
+            sel.innerHTML = '<option value="">— none —</option>';
+            for (const inp of inputs) {
+                const opt = document.createElement('option');
+                opt.value = inp.id;
+                opt.textContent = inp.name;
+                if (inp.id === current) opt.selected = true;
+                sel.appendChild(opt);
+            }
+            // Sync volume slider with the actual persisted value (default
+            // 0.7 if storage was empty or never written).
+            const vol = window.drumH3dGetSynthVolume ? window.drumH3dGetSynthVolume() : 0.7;
+            const volSlider = document.getElementById('drumh3d-synth-vol');
+            const volLabel = document.getElementById('drumh3d-synth-vol-val');
+            if (volSlider) volSlider.value = String(vol);
+            if (volLabel) volLabel.textContent = parseFloat(vol).toFixed(2);
+        }
+        window.addEventListener('drum_h3d:midi_devices', renderMidiPicker);
+        // Kick off MIDI initialisation if the player viz never ran (user
+        // opened Settings → 3D Drum Highway directly). _midiInit is
+        // idempotent so this is safe even when the viz is also active.
+        // Re-render the picker when the access promise settles.
+        (function pollMidi() {
+            if (window.drumH3dEnsureMidiInit) {
+                Promise.resolve(window.drumH3dEnsureMidiInit()).then(renderMidiPicker);
+                renderMidiPicker();  // first paint with whatever's cached
+            } else {
+                setTimeout(pollMidi, 100);
+            }
+        })();
+
+        // Hydrate controls from stored config on first paint.
+        // Narrow the try/catch to just localStorage reads — renderKit() and
+        // swatches must always run even when storage is blocked/disabled.
+        const pSel = document.getElementById('drumh3d-palette');
+        const cam = document.getElementById('drumh3d-camera');
+        const camVal = document.getElementById('drumh3d-camera-val');
+        try {
+            const storedPal = localStorage.getItem('drum_h3d_palette');
+            if (storedPal && PALETTES[storedPal]) pSel.value = storedPal;
+
+            const storedCam = parseFloat(localStorage.getItem('drum_h3d_camera_angle'));
+            if (Number.isFinite(storedCam)) {
+                const c = Math.min(1, Math.max(0, storedCam));
+                cam.value = String(c);
+                camVal.textContent = c.toFixed(2);
+            }
+
+            // FX toggles (drum_h3d_bg_* — guitar-parity graphics controls).
+            // Only explicit values override; absent/corrupt keys keep the
+            // default (ON), matching screen.js readFxSettings.
+            const hydrateFxBool = (key, elId) => {
+                const raw = localStorage.getItem('drum_h3d_bg_' + key);
+                if (raw === '1' || raw === 'true') document.getElementById(elId).checked = true;
+                else if (raw === '0' || raw === 'false') document.getElementById(elId).checked = false;
+            };
+            hydrateFxBool('bloom', 'drumh3d-fx-bloom');
+            hydrateFxBool('sparks', 'drumh3d-fx-sparks');
+            hydrateFxBool('timingFx', 'drumh3d-fx-timing');
+            hydrateFxBool('streakFx', 'drumh3d-fx-streak');
+            hydrateFxBool('cinematic', 'drumh3d-fx-cinematic');
+            hydrateFxBool('bgReactive', 'drumh3d-fx-bgreactive');
+            hydrateFxBool('scoreFx', 'drumh3d-fx-scorefx');
+            const hydrateFxRange = (key, elId, valId) => {
+                const n = parseFloat(localStorage.getItem('drum_h3d_bg_' + key));
+                if (!Number.isFinite(n)) return;
+                const v = Math.min(1, Math.max(0, n));
+                document.getElementById(elId).value = String(v);
+                document.getElementById(valId).textContent = v.toFixed(2);
+            };
+            hydrateFxRange('hitFx', 'drumh3d-fx-hitfx', 'drumh3d-fx-hitfx-val');
+            hydrateFxRange('glow', 'drumh3d-fx-glow', 'drumh3d-fx-glow-val');
+            hydrateFxRange('vibrancy', 'drumh3d-fx-vibrancy', 'drumh3d-fx-vibrancy-val');
+            hydrateFxRange('bgIntensity', 'drumh3d-fx-bgintensity', 'drumh3d-fx-bgintensity-val');
+            const storedStyle = localStorage.getItem('drum_h3d_bg_style');
+            const styleSel = document.getElementById('drumh3d-fx-bgstyle');
+            if (storedStyle && Array.from(styleSel.options).some(o => o.value === storedStyle)) {
+                styleSel.value = storedStyle;
+            }
+            const storedTheme = localStorage.getItem('drum_h3d_bg_theme');
+            const themeSel = document.getElementById('drumh3d-fx-theme');
+            if (storedTheme && Array.from(themeSel.options).some(o => o.value === storedTheme)) {
+                themeSel.value = storedTheme;
+            }
+        } catch (e) {
+            console.warn('[Drum-Hwy3D settings] hydration failed:', e);
+        }
+        renderKit();
+        window._drumH3dRenderPaletteSwatches(pSel.value);
+    })();
+    </script>
+</div>

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/drum_highway_3d/tests/data_layer.test.js

@@ -0,0 +1,164 @@
+// Pure data-layer tests: load screen.js in a bare vm window and exercise the
+// __test exports (no DOM, no WebGL, no network). Doubles as a lint that no
+// module-scope code touches document/localStorage outside a try/catch —
+// the vm window deliberately provides neither.
+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.slopsmithViz_drum_highway_3d;
+}
+
+test('module loads in a bare vm (no DOM / localStorage at module scope)', () => {
+    const factory = load();
+    assert.equal(typeof factory, 'function');
+    assert.equal(factory.contextType, 'webgl2');
+});
+
+test('_variantForHit: ghost > flam > bell > accent > normal precedence', () => {
+    const { _variantForHit } = load().__test;
+    assert.equal(_variantForHit({ g: true, f: true, v: 120 }), 'ghost');
+    assert.equal(_variantForHit({ f: true, v: 120 }), 'flam');
+    assert.equal(_variantForHit({ p: 'ride_bell' }), 'bell');
+    assert.equal(_variantForHit({ v: 100 }), 'accent');
+    assert.equal(_variantForHit({ v: 127 }), 'accent');
+    assert.equal(_variantForHit({ v: 99 }), 'normal');
+    // Missing velocity defaults to 100 → accent.
+    assert.equal(_variantForHit({}), 'accent');
+});
+
+test('matchesArrangement: claims drum arrangements', () => {
+    const matches = load().matchesArrangement;
+    assert.equal(matches({ has_drum_tab: true, arrangement: 'Drums' }), true);
+    assert.equal(matches({ has_drum_tab: true, arrangement: 'Drum Kit' }), true);
+    assert.equal(matches({ has_drum_tab: true, arrangement: 'Percussion' }), true);
+});
+
+test('matchesArrangement: never claims without a drum tab', () => {
+    const matches = load().matchesArrangement;
+    assert.equal(matches(null), false);
+    assert.equal(matches({}), false);
+    assert.equal(matches({ arrangement: 'Drums' }), false);
+});
+
+test('matchesArrangement: steal-guard — guitar arrangements stay with highway_3d', () => {
+    const matches = load().matchesArrangement;
+    // Full-band pack (drum_tab present) playing a guitar-family part:
+    // first-match-wins Auto order must not hand these to the drum highway.
+    for (const arr of ['Lead', 'Rhythm', 'Bass', 'Combo', 'Guitar 22', 'Alt. Lead']) {
+        assert.equal(matches({ has_drum_tab: true, arrangement: arr }), false, arr);
+    }
+    // Keys notation present → the keys/staff viz take it.
+    assert.equal(matches({ has_drum_tab: true, has_notation: true, arrangement: 'Piano' }), false);
+});
+
+test('matchesArrangement: claims packs nothing more specific can render', () => {
+    const matches = load().matchesArrangement;
+    // Drum tab + nondescript arrangement, no notation → drummable, claim it.
+    assert.equal(matches({ has_drum_tab: true, arrangement: '' }), true);
+    assert.equal(matches({ has_drum_tab: true }), true);
+    // Word-boundary check: "BasslineKeys"-style names don't contain a
+    // guitar-family word as a whole word.
+    assert.equal(matches({ has_drum_tab: true, arrangement: 'Bassline' }), true);
+});
+
+test('readFxSettings: defaults survive a localStorage-less environment', () => {
+    const { readFxSettings, FX_DEFAULTS } = load().__test;
+    // The vm window has no localStorage — the try/catch must eat the
+    // ReferenceError and hand back pure defaults (everything ON).
+    assert.deepEqual(readFxSettings(), FX_DEFAULTS);
+    assert.equal(FX_DEFAULTS.bloom, true);
+});
+
+test('MIDI map: open hi-hat is a first-class piece (46 → hh_open)', () => {
+    const { MIDI_TO_PIECE, HIT_TOLERANCE_S } = load().__test;
+    assert.equal(MIDI_TO_PIECE[46], 'hh_open');
+    assert.equal(MIDI_TO_PIECE[42], 'hh_closed');
+    assert.equal(MIDI_TO_PIECE[35], 'kick');
+    assert.equal(MIDI_TO_PIECE[36], 'kick');
+    // ±50 ms window matches the 2D drums plugin.
+    assert.equal(HIT_TOLERANCE_S, 0.05);
+});
+
+test('_classifyTiming: OK band is 40% of the window, sign maps early/late', () => {
+    const { _classifyTiming, HIT_TOLERANCE_S } = load().__test;
+    const tol = HIT_TOLERANCE_S;         // 0.05
+    assert.equal(_classifyTiming(0, tol), 'OK');
+    assert.equal(_classifyTiming(tol * 0.4, tol), 'OK');    // boundary inclusive
+    assert.equal(_classifyTiming(-tol * 0.4, tol), 'OK');
+    // delta = note.t - now: positive → struck before the note → EARLY.
+    assert.equal(_classifyTiming(tol * 0.41, tol), 'EARLY');
+    assert.equal(_classifyTiming(-tol * 0.41, tol), 'LATE');
+    assert.equal(_classifyTiming(tol, tol), 'EARLY');
+    assert.equal(_classifyTiming(-tol, tol), 'LATE');
+    // Degenerate inputs read as on-time rather than throwing.
+    assert.equal(_classifyTiming(NaN, tol), 'OK');
+});
+
+test('FX defaults: hit-FX controls ship enabled', () => {
+    const { FX_DEFAULTS } = load().__test;
+    assert.equal(FX_DEFAULTS.sparks, true);
+    assert.equal(FX_DEFAULTS.timingFx, true);
+    assert.equal(FX_DEFAULTS.streakFx, true);
+    assert.equal(FX_DEFAULTS.hitFx, 0.7);
+});
+
+test('themes: table ids match the guitar highway, default is the stock palette', () => {
+    const { BG_THEMES, _bgThemeColors } = load().__test;
+    // Same id set as highway_3d's BG_THEMES (cross-instrument consistency).
+    assert.deepEqual(Object.keys(BG_THEMES), [
+        'default', 'midnight', 'charcoal', 'deeppurple', 'forest', 'warmslate',
+        'deepfocus', 'deepsea', 'cathode', 'cathodegreen', 'hearth',
+    ]);
+    // 'default' preserves THIS plugin's original look byte-for-byte.
+    assert.equal(BG_THEMES.default.clear, 0x1a1a2e);
+    assert.equal(BG_THEMES.default.board, 0x0a0e1a);
+    assert.equal(BG_THEMES.default.lane, undefined); // stock stripes fallback
+    // Unknown ids fall back to default.
+    assert.equal(_bgThemeColors('nonsense'), BG_THEMES.default);
+    // Every non-default theme carries a lane pair (the axis differentiator).
+    for (const [id, t] of Object.entries(BG_THEMES)) {
+        if (id === 'default') continue;
+        assert.ok(t.lane != null && t.laneDim != null, id + ' lane pair');
+        assert.equal(t.clear, t.fog, id + ' clear==fog (horizon dissolve)');
+    }
+});
+
+test('readThemeSetting: defaults without localStorage; validates ids', () => {
+    const { readThemeSetting } = load().__test;
+    assert.equal(readThemeSetting(), 'default');
+});
+
+test('FX defaults: theme-PR controls ship enabled at stock-neutral values', () => {
+    const { FX_DEFAULTS } = load().__test;
+    assert.equal(FX_DEFAULTS.cinematic, true);
+    assert.equal(FX_DEFAULTS.glow, 0.5);      // 0.5 = 1.0x multiplier (stock)
+    assert.equal(FX_DEFAULTS.vibrancy, 0.85); // ≈ the stock 0.32 stripe base
+});
+
+test('bg styles: validated id set, particles default, no out-of-scope styles', () => {
+    const { BG_STYLE_IDS, readBgStyleSetting } = load().__test;
+    // Host-realm copy — the vm array's foreign prototype trips deepEqual.
+    assert.deepEqual([...BG_STYLE_IDS], ['off', 'particles', 'lights', 'geometric']);
+    assert.equal(readBgStyleSetting(), 'particles'); // no localStorage in the vm
+});
+
+test('FX defaults: ambience + score FX ship enabled', () => {
+    const { FX_DEFAULTS } = load().__test;
+    assert.equal(FX_DEFAULTS.scoreFx, true);
+    assert.equal(FX_DEFAULTS.bgIntensity, 0.5);
+    assert.equal(FX_DEFAULTS.bgReactive, true);
+});

plugins/highway_3d/plugin.json

@@ -1,7 +1,7 @@
 {
     "id": "highway_3d",
     "name": "3D Highway",
-    "version": "3.31.2",
+    "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);
@@ -2196,6 +2221,24 @@
         }
         const audio = document.getElementById('audio');
         if (!audio) return null;
+        // Shared tap: createMediaElementSource is one-shot per element, so
+        // the FIRST visualizer to tap #audio publishes it at
+        // window.__feedBackAudioTap and every later one (this plugin, the
+        // drum/keys 3D highways) adopts it instead of throwing
+        // InvalidStateError when visualizers are switched or mixed in
+        // splitscreen.
+        const sharedTap = window.__feedBackAudioTap;
+        if (sharedTap && sharedTap.analyser && sharedTap.mediaEl === audio) {
+            _bgAudio = {
+                ctx: sharedTap.ctx,
+                analyser: sharedTap.analyser,
+                freq: new Uint8Array(Math.max(BG_FREQ_BINS, sharedTap.analyser.frequencyBinCount)),
+                source: 'core',
+            };
+            _bgAudioCore = _bgAudio;
+            _bgRecordAudioBridge('audio-mix.analyser', 'shared #audio analyser tap', 'handled', '', 'core');
+            return _bgAudio;
+        }
         // Hoist ctx out of the try so we can close() it if a later step
         // throws (e.g. createMediaElementSource on an element that
         // already has a source node). Otherwise the AudioContext leaks.
@@ -2210,6 +2253,7 @@
             source.connect(analyser);
             analyser.connect(ctx.destination);
             _bgAudio = { ctx, analyser, freq: new Uint8Array(Math.max(BG_FREQ_BINS, analyser.frequencyBinCount)), source: 'core' };
+            try { window.__feedBackAudioTap = { ctx, analyser, mediaEl: audio }; } catch (_) {}
             _bgRecordAudioBridge('audio-mix.analyser', 'HTMLAudioElement analyser tap', 'handled', '', 'core');
             // Remember the core analyser so a later stems-then-back-to-core
             // transition can re-use it instead of re-tapping #audio (which
@@ -2576,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
@@ -3728,6 +3813,15 @@
         // ── Per-instance Three.js state ───────────────────────────────────
         let scene = null, cam = null, ren = null;
         let wrap = null;
+        // WebGL context-loss recovery. Switching the active window / alt-tabbing
+        // (especially on Windows) can trigger a GPU context reset; with no
+        // handler the lost context escalates into a render-process crash. The
+        // listeners (bound in initScene on ren.domElement, removed in teardown)
+        // preventDefault the loss so the browser keeps the context restorable,
+        // _ctxLost gates draw() off the dead context, and on restore we reset the
+        // viewport + resume (Three re-uploads scene resources on the next render).
+        let _ctxLost = false;
+        let _onCtxLost = null, _onCtxRestored = null;
         let bcCtrl = null; // Butterchurn audio-reactive background (the 'butterchurn' bg-style)
         let _chartEnv = 0, _chartPrevT = -1, _bcBeatIdx = 0, _bcNoteIdx = 0, _bcChordIdx = 0, _bcTintTarget = null;
         let _tintR = 20, _tintG = 24, _tintB = 40; // smoothed instrument-color tint for the bg
@@ -6507,6 +6601,26 @@
             ren.setClearColor(0x101820, _bcActive() ? 0 : 1);
             wrap.appendChild(ren.domElement);
 
+            // WebGL context-loss recovery (see the _ctxLost declaration). Bound
+            // on Three's own canvas — the context that actually resets on a GPU
+            // reset / alt-tab. preventDefault() keeps the context restorable
+            // instead of letting the loss escalate to a render-process crash;
+            // _ctxLost then makes draw() bail so no GL work runs on the dead
+            // context; on restore we reset the viewport and resume (Three
+            // re-uploads geometry/materials/textures lazily on the next render).
+            _onCtxLost = (e) => {
+                if (e && typeof e.preventDefault === 'function') e.preventDefault();
+                _ctxLost = true;
+                console.warn('[3D-Hwy] WebGL context lost — pausing render until it is restored.');
+            };
+            _onCtxRestored = () => {
+                _ctxLost = false;
+                console.warn('[3D-Hwy] WebGL context restored — resuming render.');
+                try { const s = canvasSize(highwayCanvas); if (s.w > 0 && s.h > 0) applySize(s.w, s.h); } catch (err) {}
+            };
+            ren.domElement.addEventListener('webglcontextlost', _onCtxLost, false);
+            ren.domElement.addEventListener('webglcontextrestored', _onCtxRestored, false);
+
             lyricsCanvas = document.createElement('canvas');
             lyricsCanvas.style.cssText = 'position:absolute;top:0;left:0;pointer-events:none;z-index:1;';
             lyricsCtx = lyricsCanvas.getContext('2d');
@@ -14616,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;
@@ -14643,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;
@@ -14810,6 +14930,15 @@
             // mid-teardown settings change doesn't try to rebuild a torn-
             // down scene; then dispose the active style's resources.
             if (_bgListener) { _bgUnsubscribe(_bgListener); _bgListener = null; }
+            // WebGL context-loss listeners (bound in initScene on ren.domElement).
+            // Remove before ren is disposed below so a torn-down instance can't
+            // keep firing them; reset the flag so a reused instance starts clean.
+            if (ren && ren.domElement) {
+                if (_onCtxLost) { try { ren.domElement.removeEventListener('webglcontextlost', _onCtxLost, false); } catch (e) {} }
+                if (_onCtxRestored) { try { ren.domElement.removeEventListener('webglcontextrestored', _onCtxRestored, false); } catch (e) {} }
+            }
+            _onCtxLost = _onCtxRestored = null;
+            _ctxLost = false;
             // Notedetect listeners (issue #9). Remove on destroy so a
             // panel that stops doesn't keep accumulating marks. Marks
             // arrays are cleared too — they hold stale chart positions
@@ -15135,6 +15264,7 @@
 
             draw(bundle) {
                 if (!_isReady) return;
+                if (_ctxLost) return;   // GPU context lost (alt-tab / reset) — skip until restored
                 if (!_chartPrewarmed) {
                     _chartPrewarmed = true;
                     _prewarmChart(bundle);

plugins/keys_highway_3d/LICENSE

@@ -0,0 +1,661 @@
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU Affero General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.

plugins/keys_highway_3d/README.md

@@ -0,0 +1,76 @@
+# Keys Highway 3D
+
+RS+-style falling-note 3D piano highway for [Slopsmith](https://github.com/got-feedback/feedback), fed by the **Sloppak Notation Format** (sloppak-spec §5.3) — part of the piano/keys first-class epic (slopsmith#828, plugin workstream slopsmith#824).
+
+- Consumes the `notation_info` / `notation_measures` highway-WS stream over a private per-instance socket and flattens measure → staff → voice → beat → note into `{midi, t, durSec, hand}` (durations derived from written `dur`/`dot`/`tu` at the running tempo; ties extend; overlap-clamped).
+- 3D perspective highway to a vanishing point with a real white/black-key keyboard; per-key **pitch-class colors** (Synthesia convention — C red, D yellow, E blue, …) with hand (rh/lh) as a secondary brightness cue. Selectable **note-color palettes** (settings → Note colors, `keys3d_bg_palette`, default the per-octave scheme): a per-octave rainbow (each octave its own hue, darker sharps), the original per-pitch "Rainbow" table, vivid/pastel per-pitch variants, and single-hue two-tone palettes (uniform naturals, darker sharps) for players who want "black key coming" to read at a glance; notes, key glow, lane guides and hit flames all follow the pick live.
+- Full RS+ visual treatment: key **letter glyphs** printed on the active-range key tops (cached CanvasTextures), **bevelled gem-style note blocks** (ExtrudeGeometry, geometry/material caches keyed by size and pitch-class×hand), **floating bar numbers** scrolling with the notes, **active-range lane dimming** so the playable span pops, and a **glowing pulsing hit-line** (layered additive gradient planes — no postprocessing).
+- Performance discipline: no per-frame allocations or DOM queries in `draw()`. Chart-scoped resources — note geometries/materials, bar-number and glow textures — are cached and disposed on chart teardown; the key-letter glyph `CanvasTexture`s live in a shared module-level cache that survives teardown and is reused across instances.
+- Auto-selected for arrangements with notation via `matchesArrangement(songInfo.has_notation)`; capability-native `visualization` provider declaration.
+- **Camera settings**: camera-rig presets (`keys3d_bg_camera` — classic low rig / elevated / overhead; default overhead, applied live, adaptive pan-zoom preserved) with base-rig fine-tune sliders for height, distance and tilt (`keys3d_bg_camHeight` / `camDist` / `camTilt`) that nudge the vantage point the follow-motion orbits. Numeric FX keys clamp to per-key declared ranges (`FX_RANGES`, default 0–1).
+- **Highway-layout options** (settings → Highway layout). **Sharps & flats**
+  (`keys3d_bg_sharpMode`, string; default `realistic`) picks the sharp layout:
+  `floating` (original raised-plane sharps, white-only lanes); `flat` (one plane,
+  zero-overlap piano-shaped tiled lanes — white lanes trimmed where a sharp adjoins
+  them, and each sharp leaned toward the edge natural beside it so the naturals come
+  out close to even: C/D/E/F/B equal, G/A a hair smaller since G# can't lean; pure
+  `laneSpanFlat()`); `realistic` (one plane, bars sized like the physical keys — full
+  naturals always rendered full, full black keys drawn on top and only occluding a
+  natural where a sharp note actually coincides in time; pure `laneSpanReal()`).
+  **Lane color opacity** (`keys3d_bg_laneOpacity`, 0–1, default 0) fades the
+  pitch-class lane tint; at 0 (default) the strips are a dark floor with guide lines
+  only at the key-block boundaries (E→F and each octave B→C), so each block is bounded
+  rather than every lane — the notes keep their colors; toward 1 it fills in full,
+  vivid colored lanes. The strips, per-lane separators and block lines crossfade with
+  this value. **Octave separators** (`keys3d_bg_octaveGaps`, default on) widens the
+  gap a touch at each B→C octave boundary. **Octave line contrast**
+  (`keys3d_bg_octaveContrast`, 0–1, default 0.5) scales how hard the B→C octave line
+  reads; it is drawn as a dark layer (scaled by lane opacity) plus a bright layer
+  (scaled by its inverse), so it auto-shifts dark→bright as the lanes fade — no mode
+  switch needed. All are geometry-time — applied on the next chart build via
+  `init()`'s re-read.
+- **Web MIDI input scoring**: module-level MIDI singleton (one access per tab, focused-instance routing) with device auto-connect by saved id+name, loopback blocklist, channel filter, transpose and CC64 sustain (`keys3d_` localStorage prefix; `window.keysH3d*` settings API). Hit detection matches played MIDI against the flattened chart notes within ±0.10 s with per-note dedupe and a missed-note sweep (only while a device is connected — never retroactive across a mid-song connect).
+- **Live hit feedback on the MIDI path** (not the chart): key depress (~4° back-edge pivot, ~120 ms spring; the key letter rides along), wrong-note red key flash, and a vertical flame flare on hits (pooled additive sprites, white-hot base fading into the pitch-class color, ~400 ms).
+- **End-of-run stats**: POSTs `/api/stats` `{filename, arrangement, score, accuracy}` exactly once per run with the same formula as the guitar notedetect path (`accuracy = hits / max(1, hits+misses)`, `score = round(hits·100·accuracy)`), then notifies the progression core when present.
+- **Capability wiring** (all guarded for servers without the hosts): registers as a note-detection `midi` provider (`keys-midi`, `verify.target`), opens a per-song binding scoped to the chart's keys range, reports hit/miss observability events, and exposes Web MIDI inputs to the audio-input domain with pseudonymized labels (`midi-input-1`, …) via `source.enumerate/describe/open/close`.
+- Headless test hook: `window.__keysHwTest = { injectNoteOn(midi, when), getScore() }`.
+
+## Tests
+
+```
+node --test tests/*.test.js
+```
+
+## Ported helpers (keep in sync with highway_3d)
+
+Visual-parity code copied from `plugins/highway_3d/screen.js` — same
+function names, signatures, and constants on purpose, marked with
+`PORTED FROM highway_3d` comments at each site. If the guitar highway
+tunes one of these, mirror the change here (and in `drum_highway_3d`):
+
+- `_bloomEnsure()` / `_bloomDispose()` — EffectComposer + UnrealBloomPass
+  (0.65/0.5/0.82) on a multisampled HalfFloat target, ACES↔None tone-
+  mapping switch in `draw()`; addons dynamic-imported from
+  `/static/vendor/three/addons/` (no CDN fallback — direct render is the
+  graceful degrade)
+- `_sparkBurst()` / `_sparkUpdate()` — pooled additive Points hit sparks
+  (pool 96 here — the flame sprites carry most of the hit feedback)
+- `_timingHex()` / `_classifyTiming()` — early/late/on-time feedback
+  colors (green/cyan/amber) + the 40%-window classifier
+- `_ssActive()` — host splitscreen probe (minus the guitar's focus-API
+  checks, which it needs for input routing and we don't)
+- `BG_THEMES` / `_bgThemeColors()` — the scene theme table (same ids/values
+  as the guitar's, except `default` which is this plugin's original
+  palette); one pick drives background gradient + floor + lane rails
+- `_makeStudioEnv()` — procedural PMREM studio environment (shared with
+  drum_highway_3d; RoomEnvironment isn't vendored)
+- `_applyCinematic()` — ambient/key rebalance (values tuned per plugin)
+- `BG_STYLES` (off/particles/lights/geometric) + `_bgGetAnalyser()` /
+  `_bgReadBands()` — background ambience + the stems-first audio-analyser
+  bridge (shared with drum_highway_3d)
+- `_drawScoreFx()` — score overlay (pops / tier rings / milestone bursts /
+  streak-break wash), drum_highway_3d pattern
+
+## License
+
+AGPL-3.0.

plugins/keys_highway_3d/assets/thumb.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="256" viewBox="0 0 256 256" role="img" aria-label="Keys Highway 3D placeholder thumbnail">
+  <rect width="256" height="256" rx="36" fill="#0f172a"/>
+  <rect x="18" y="18" width="220" height="220" rx="28" fill="#1e293b" stroke="#334155" stroke-width="3"/>
+  <text x="128" y="150" font-family="Rubik, Arial, sans-serif" font-size="104" font-weight="800" fill="#38bdf8" text-anchor="middle">KH</text>
+</svg>

plugins/keys_highway_3d/plugin.json

@@ -0,0 +1,68 @@
+{
+  "id": "keys_highway_3d",
+  "name": "Keys Highway 3D",
+  "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,
+  "script": "screen.js",
+  "settings": {
+    "html": "settings.html",
+    "category": "graphics"
+  },
+  "standards": [
+    "capability-pipelines.v1",
+    "plugin-runtime-idempotent.v1"
+  ],
+  "capabilities": {
+    "visualization": {
+      "roles": [
+        "provider"
+      ],
+      "operations": [
+        "renderer.create",
+        "renderer.destroy"
+      ],
+      "emits": [
+        "renderer-ready",
+        "renderer-failed"
+      ],
+      "mode": "active",
+      "safety": "safe"
+    },
+    "note-detection": {
+      "roles": [
+        "provider"
+      ],
+      "operations": [
+        "verify.target"
+      ],
+      "emits": [
+        "hit",
+        "miss"
+      ],
+      "mode": "active",
+      "safety": "sensitive"
+    },
+    "midi-input": {
+      "roles": [
+        "requester"
+      ],
+      "requests": [
+        "discover",
+        "list-sources",
+        "select-source",
+        "open-source",
+        "close-source"
+      ],
+      "mode": "active",
+      "compatibility": "degrade-noop",
+      "ownership": "requester-only",
+      "safety": "sensitive",
+      "description": "Reads the MIDI keyboard input through the core midi-input domain (Web-MIDI provider ships built-in with the domain). Absent domain \u2192 no MIDI devices, fail-soft.",
+      "version": 1
+    }
+  },
+  "category": "practice",
+  "icon": "assets/thumb.svg"
+}

plugins/keys_highway_3d/settings.html

@@ -0,0 +1,367 @@
+<div role="group" aria-labelledby="keysh3d-heading">
+    <h3 id="keysh3d-heading" class="text-sm font-medium text-gray-400 mb-2">3D Keys Highway</h3>
+    <p class="text-xs text-gray-500 mb-3">
+        Pick a song with keys notation (sloppak-spec §5.3) and choose
+        <em>Keys Highway 3D</em> from the viz picker (Auto selects it for
+        notation charts). The plugin auto-attaches to your MIDI keyboard;
+        device, channel and transpose are configured from the player for
+        now — this panel holds the graphics controls.
+    </p>
+
+    <!-- Graphics -->
+    <div class="mt-3">
+        <h4 class="text-xs font-medium text-gray-300 mb-2">Graphics</h4>
+
+        <label for="keysh3d-fx-palette" class="text-xs font-medium text-gray-400 mb-1 block">Note colors</label>
+        <select id="keysh3d-fx-palette"
+            onchange="window.keys3dSetPalette && window.keys3dSetPalette(this.value)"
+            class="w-full bg-dark-700 border border-gray-800 rounded-lg px-3 py-2 text-xs text-gray-300 outline-none">
+            <option value="octaves" selected>Octaves (color per octave, darker sharps)</option>
+            <option value="emerald">Emerald (green, darker sharps)</option>
+            <option value="ice">Ice (blue, darker sharps)</option>
+            <option value="classic">Rainbow (per-pitch)</option>
+            <option value="vivid">Vivid (per-pitch, punchier)</option>
+            <option value="pastel">Pastel (per-pitch, soft)</option>
+        </select>
+        <p class="text-xs text-gray-500 mt-1 mb-3">
+            Choose the color scheme for the falling notes, key glow, lane
+            guides and hit flames. Each option is described in its own label.
+        </p>
+
+        <label for="keysh3d-fx-theme" class="text-xs font-medium text-gray-400 mb-1 block">Scene theme</label>
+        <select id="keysh3d-fx-theme"
+            onchange="window.keys3dSetTheme && window.keys3dSetTheme(this.value)"
+            class="w-full bg-dark-700 border border-gray-800 rounded-lg px-3 py-2 text-xs text-gray-300 outline-none">
+            <option value="default">Default (original)</option>
+            <option value="midnight">Midnight</option>
+            <option value="charcoal">Charcoal</option>
+            <option value="deeppurple">Deep Purple</option>
+            <option value="forest">Forest</option>
+            <option value="warmslate">Warm Slate</option>
+            <option value="deepfocus">Deep Focus</option>
+            <option value="deepsea">Deep Sea</option>
+            <option value="cathode">Cathode</option>
+            <option value="cathodegreen">Cathode Green</option>
+            <option value="hearth">Hearth</option>
+        </select>
+        <p class="text-xs text-gray-500 mt-1 mb-3">
+            Background gradient, floor and lane rails — the same theme names
+            as the guitar highway. Note colors come from the
+            "Note colors" palette above.
+        </p>
+
+        <label for="keysh3d-fx-camera" class="text-xs font-medium text-gray-400 mb-1 block">Camera angle</label>
+        <select id="keysh3d-fx-camera"
+            onchange="window.keys3dSetCamera && window.keys3dSetCamera(this.value)"
+            class="w-full bg-dark-700 border border-gray-800 rounded-lg px-3 py-2 text-xs text-gray-300 outline-none">
+            <option value="classic">Classic (low, deep runway)</option>
+            <option value="elevated">Elevated (higher, more board)</option>
+            <option value="overhead" selected>Overhead (top-down reading view)</option>
+        </select>
+        <p class="text-xs text-gray-500 mt-1 mb-3">
+            Where the camera sits. Classic is the original low rig; Elevated
+            lifts it for a fuller view of the keybed; Overhead looks down the
+            lanes for a sheet-reading feel. Applies live, keeps the
+            auto-pan/zoom that follows your hands.
+        </p>
+
+        <label for="keysh3d-fx-camheight" class="text-xs font-medium text-gray-400 mb-1 block">
+            Camera height <span id="keysh3d-fx-camheight-val" class="text-gray-500 font-mono">1.00</span>
+        </label>
+        <input type="range" id="keysh3d-fx-camheight"
+            min="0.4" max="2.2" step="0.02" value="1"
+            oninput="window.keys3dSetFx && window.keys3dSetFx('camHeight', this.value); document.getElementById('keysh3d-fx-camheight-val').textContent = parseFloat(this.value).toFixed(2)"
+            class="w-full">
+        <p class="text-xs text-gray-500 mt-1">
+            Raise or lower the camera around the angle above (higher = more
+            top-down). Fine-tunes the base view; the follow-motion stays.
+        </p>
+
+        <label for="keysh3d-fx-camdist" class="text-xs font-medium text-gray-400 mb-1 mt-3 block">
+            Camera distance <span id="keysh3d-fx-camdist-val" class="text-gray-500 font-mono">1.00</span>
+        </label>
+        <input type="range" id="keysh3d-fx-camdist"
+            min="0.4" max="2.2" step="0.02" value="1"
+            oninput="window.keys3dSetFx && window.keys3dSetFx('camDist', this.value); document.getElementById('keysh3d-fx-camdist-val').textContent = parseFloat(this.value).toFixed(2)"
+            class="w-full">
+        <p class="text-xs text-gray-500 mt-1">
+            Pull the camera back or push it in (larger = further away, smaller
+            = closer).
+        </p>
+
+        <label for="keysh3d-fx-camtilt" class="text-xs font-medium text-gray-400 mb-1 mt-3 block">
+            Camera tilt <span id="keysh3d-fx-camtilt-val" class="text-gray-500 font-mono">0.00</span>
+        </label>
+        <input type="range" id="keysh3d-fx-camtilt"
+            min="-1" max="1" step="0.02" value="0"
+            oninput="window.keys3dSetFx && window.keys3dSetFx('camTilt', this.value); document.getElementById('keysh3d-fx-camtilt-val').textContent = parseFloat(this.value).toFixed(2)"
+            class="w-full">
+        <p class="text-xs text-gray-500 mt-1 mb-3">
+            Tilt the view up (+) or down (−) without moving the camera —
+            aims higher up the runway or down toward the keys. 0 = neutral.
+        </p>
+
+        <h4 class="text-xs font-medium text-gray-300 mb-2 mt-4">Highway layout</h4>
+
+        <label for="keysh3d-fx-sharpmode" class="text-xs font-medium text-gray-400 mb-1 block">Sharps &amp; flats</label>
+        <select id="keysh3d-fx-sharpmode"
+            onchange="window.keys3dSetSharpMode && window.keys3dSetSharpMode(this.value)"
+            class="w-full bg-dark-700 border border-gray-800 rounded-lg px-3 py-2 text-xs text-gray-300 outline-none">
+            <option value="floating">Floating</option>
+            <option value="flat">Non-floating</option>
+            <option value="realistic" selected>Realistic key sizes (default — best with no colored lanes)</option>
+        </select>
+        <p class="text-xs text-gray-500 mt-1 mb-3">
+            How sharps and flats are drawn. <em>Floating</em>: they ride a raised
+            plane above the naturals. <em>Non-floating</em>: everything on one
+            plane, each key its own even piano-shaped lane. <em>Realistic key
+            sizes</em>: one plane, bars sized like the real keys (full naturals,
+            full black keys on top). Applies next time you open a song.
+        </p>
+
+        <label for="keysh3d-fx-laneopacity" class="text-xs font-medium text-gray-400 mb-1 block">
+            Lane color opacity <span id="keysh3d-fx-laneopacity-val" class="text-gray-500 font-mono">0.00</span>
+        </label>
+        <input type="range" id="keysh3d-fx-laneopacity"
+            min="0" max="1" step="0.05" value="0"
+            oninput="window.keys3dSetFx && window.keys3dSetFx('laneOpacity', this.value); document.getElementById('keysh3d-fx-laneopacity-val').textContent = parseFloat(this.value).toFixed(2)"
+            class="w-full">
+        <p class="text-xs text-gray-500 mt-1 mb-3">
+            How strongly each lane is tinted its note color. 0.00 (default) is a
+            dark floor with plain guide lines only between the key blocks (at E–F
+            and each octave); the notes keep their colors and pop off the floor.
+            Raise toward 1.00 for full, vivid colored lanes. Applies next time you
+            open a song.
+        </p>
+
+        <label for="keysh3d-fx-octavegaps" class="flex items-center gap-2 text-xs text-gray-300 cursor-pointer mt-3">
+            <input type="checkbox" id="keysh3d-fx-octavegaps" checked
+                onchange="window.keys3dSetFx && window.keys3dSetFx('octaveGaps', this.checked)">
+            Octave separators
+        </label>
+        <p class="text-xs text-gray-500 mt-1 mb-3">
+            Widen the gap a little at each octave boundary (every B to the C
+            above it) so octaves are easier to read. Applies next time you open
+            a song.
+        </p>
+
+        <label for="keysh3d-fx-octavecontrast" class="text-xs font-medium text-gray-400 mb-1 mt-3 block">
+            Octave line contrast <span id="keysh3d-fx-octavecontrast-val" class="text-gray-500 font-mono">0.50</span>
+        </label>
+        <input type="range" id="keysh3d-fx-octavecontrast"
+            min="0" max="1" step="0.05" value="0.5"
+            oninput="window.keys3dSetFx && window.keys3dSetFx('octaveContrast', this.value); document.getElementById('keysh3d-fx-octavecontrast-val').textContent = parseFloat(this.value).toFixed(2)"
+            class="w-full">
+        <p class="text-xs text-gray-500 mt-1 mb-3">
+            How strongly the octave line (every B to C) stands out. It adapts to
+            the lane color opacity automatically — darkening the line against
+            bright lanes and brightening it as you fade them toward the dark
+            floor. Applies next time you open a song.
+        </p>
+
+        <label for="keysh3d-fx-cinematic" class="flex items-center gap-2 text-xs text-gray-300 cursor-pointer">
+            <input type="checkbox" id="keysh3d-fx-cinematic" checked
+                onchange="window.keys3dSetFx && window.keys3dSetFx('cinematic', this.checked)">
+            Cinematic lighting
+        </label>
+        <p class="text-xs text-gray-500 mt-1">
+            Dimmer ambience, stronger key light — deeper shading on the keys
+            and gems.
+        </p>
+
+        <label for="keysh3d-fx-glow" class="text-xs font-medium text-gray-400 mb-1 mt-3 block">
+            Glow strength <span id="keysh3d-fx-glow-val" class="text-gray-500 font-mono">0.50</span>
+        </label>
+        <input type="range" id="keysh3d-fx-glow"
+            min="0" max="1" step="0.05" value="0.5"
+            oninput="window.keys3dSetFx && window.keys3dSetFx('glow', this.value); document.getElementById('keysh3d-fx-glow-val').textContent = parseFloat(this.value).toFixed(2)"
+            class="w-full">
+        <p class="text-xs text-gray-500 mt-1">
+            How hard the notes, key glow and sustain consume-flash
+            self-illuminate (0.5 = stock). Pairs with bloom.
+        </p>
+
+        <label for="keysh3d-fx-bgstyle" class="text-xs font-medium text-gray-400 mb-1 mt-3 block">Background ambience</label>
+        <select id="keysh3d-fx-bgstyle"
+            onchange="window.keys3dSetBgStyle && window.keys3dSetBgStyle(this.value)"
+            class="w-full bg-dark-700 border border-gray-800 rounded-lg px-3 py-2 text-xs text-gray-300 outline-none">
+            <option value="off">Off</option>
+            <option value="particles" selected>Particles</option>
+            <option value="lights">Stage lights</option>
+            <option value="geometric">Geometric</option>
+        </select>
+        <label for="keysh3d-fx-bgintensity" class="text-xs font-medium text-gray-400 mb-1 mt-2 block">
+            Ambience intensity <span id="keysh3d-fx-bgintensity-val" class="text-gray-500 font-mono">0.50</span>
+        </label>
+        <input type="range" id="keysh3d-fx-bgintensity"
+            min="0" max="1" step="0.05" value="0.5"
+            oninput="window.keys3dSetFx && window.keys3dSetFx('bgIntensity', this.value); document.getElementById('keysh3d-fx-bgintensity-val').textContent = parseFloat(this.value).toFixed(2)"
+            class="w-full">
+        <label for="keysh3d-fx-bgreactive" class="flex items-center gap-2 text-xs text-gray-300 cursor-pointer mt-2">
+            <input type="checkbox" id="keysh3d-fx-bgreactive" checked
+                onchange="window.keys3dSetFx && window.keys3dSetFx('bgReactive', this.checked)">
+            Audio-reactive ambience
+        </label>
+        <p class="text-xs text-gray-500 mt-1">
+            The backdrop pulses with the mix (stems analyser when a sloppak
+            is loaded). Off = it animates on time only.
+        </p>
+
+        <label for="keysh3d-fx-scorefx" class="flex items-center gap-2 text-xs text-gray-300 cursor-pointer mt-3">
+            <input type="checkbox" id="keysh3d-fx-scorefx" checked
+                onchange="window.keys3dSetFx && window.keys3dSetFx('scoreFx', this.checked)">
+            Score effects
+        </label>
+        <p class="text-xs text-gray-500 mt-1">
+            +1 pops on scored presses, a ring pulse every 10-combo,
+            milestone bursts at 25/50/100, and a brief red flicker when a
+            streak breaks.
+        </p>
+
+        <label for="keysh3d-fx-bloom" class="flex items-center gap-2 text-xs text-gray-300 cursor-pointer mt-3">
+            <input type="checkbox" id="keysh3d-fx-bloom" checked
+                onchange="window.keys3dSetFx && window.keys3dSetFx('bloom', this.checked)">
+            Glow (bloom)
+        </label>
+        <p class="text-xs text-gray-500 mt-1">
+            Soft light-bleed around the hit line, hit flames and consumed
+            sustains. Applies live; turn off to reclaim GPU headroom on
+            weak machines.
+        </p>
+
+        <label for="keysh3d-fx-sparks" class="flex items-center gap-2 text-xs text-gray-300 cursor-pointer mt-3">
+            <input type="checkbox" id="keysh3d-fx-sparks" checked
+                onchange="window.keys3dSetFx && window.keys3dSetFx('sparks', this.checked)">
+            Hit sparks
+        </label>
+        <p class="text-xs text-gray-500 mt-1">
+            A small particle burst on every scored key press, beside the
+            pitch-colored flame.
+        </p>
+
+        <label for="keysh3d-fx-timing" class="flex items-center gap-2 text-xs text-gray-300 cursor-pointer mt-3">
+            <input type="checkbox" id="keysh3d-fx-timing" checked
+                onchange="window.keys3dSetFx && window.keys3dSetFx('timingFx', this.checked)">
+            Timing colors
+        </label>
+        <p class="text-xs text-gray-500 mt-1">
+            Tint the sparks by timing — on-time green, early cyan, late
+            amber. Off = always green.
+        </p>
+
+        <label for="keysh3d-fx-streak" class="flex items-center gap-2 text-xs text-gray-300 cursor-pointer mt-3">
+            <input type="checkbox" id="keysh3d-fx-streak" checked
+                onchange="window.keys3dSetFx && window.keys3dSetFx('streakFx', this.checked)">
+            Streak feedback
+        </label>
+        <p class="text-xs text-gray-500 mt-1">
+            Spark bursts grow with your combo.
+        </p>
+
+        <label for="keysh3d-fx-hitfx" class="text-xs font-medium text-gray-400 mb-1 mt-3 block">
+            Hit feedback intensity <span id="keysh3d-fx-hitfx-val" class="text-gray-500 font-mono">0.70</span>
+        </label>
+        <input type="range" id="keysh3d-fx-hitfx"
+            min="0" max="1" step="0.05" value="0.7"
+            oninput="window.keys3dSetFx && window.keys3dSetFx('hitFx', this.value); document.getElementById('keysh3d-fx-hitfx-val').textContent = parseFloat(this.value).toFixed(2)"
+            class="w-full">
+        <p class="text-xs text-gray-500 mt-1">
+            Drives the hit-line brightness kick on scored presses. 0 turns
+            it off.
+        </p>
+
+        <label for="keysh3d-fx-vibrancy" class="text-xs font-medium text-gray-400 mb-1 mt-3 block">
+            Note vibrancy <span id="keysh3d-fx-vibrancy-val" class="text-gray-500 font-mono">0.85</span>
+        </label>
+        <input type="range" id="keysh3d-fx-vibrancy"
+            min="0" max="1" step="0.05" value="0.85"
+            oninput="window.keys3dSetFx && window.keys3dSetFx('vibrancy', this.value); document.getElementById('keysh3d-fx-vibrancy-val').textContent = parseFloat(this.value).toFixed(2)"
+            class="w-full">
+        <p class="text-xs text-gray-500 mt-1">
+            Note-gem solidity and lane-guide strength — lower to see more of
+            the keyboard through the notes.
+        </p>
+    </div>
+
+    <script>
+    (function () {
+        'use strict';
+        // Hydrate controls from stored config on first paint. Narrow the
+        // try/catch to just the localStorage reads (drum_highway_3d
+        // settings-hydration convention).
+        try {
+            // FX toggles (keys3d_bg_* — guitar-parity graphics controls).
+            // Only explicit values override; absent/corrupt keys keep the
+            // default (ON), matching screen.js readFxSettings.
+            const hydrateFxBool = (key, elId) => {
+                const raw = localStorage.getItem('keys3d_bg_' + key);
+                if (raw === '1' || raw === 'true') document.getElementById(elId).checked = true;
+                else if (raw === '0' || raw === 'false') document.getElementById(elId).checked = false;
+            };
+            hydrateFxBool('bloom', 'keysh3d-fx-bloom');
+            hydrateFxBool('sparks', 'keysh3d-fx-sparks');
+            hydrateFxBool('timingFx', 'keysh3d-fx-timing');
+            hydrateFxBool('streakFx', 'keysh3d-fx-streak');
+            hydrateFxBool('cinematic', 'keysh3d-fx-cinematic');
+            hydrateFxBool('bgReactive', 'keysh3d-fx-bgreactive');
+            hydrateFxBool('scoreFx', 'keysh3d-fx-scorefx');
+            // Highway-layout: octaveGaps defaults ON (bool); laneOpacity /
+            // octaveContrast are 0-1 sliders hydrated with hydrateFxRange below.
+            hydrateFxBool('octaveGaps', 'keysh3d-fx-octavegaps');
+            const hydrateFxRange = (key, elId, valId) => {
+                const n = parseFloat(localStorage.getItem('keys3d_bg_' + key));
+                if (!Number.isFinite(n)) return;
+                const v = Math.min(1, Math.max(0, n));
+                document.getElementById(elId).value = String(v);
+                document.getElementById(valId).textContent = v.toFixed(2);
+            };
+            hydrateFxRange('hitFx', 'keysh3d-fx-hitfx', 'keysh3d-fx-hitfx-val');
+            hydrateFxRange('vibrancy', 'keysh3d-fx-vibrancy', 'keysh3d-fx-vibrancy-val');
+            hydrateFxRange('glow', 'keysh3d-fx-glow', 'keysh3d-fx-glow-val');
+            hydrateFxRange('bgIntensity', 'keysh3d-fx-bgintensity', 'keysh3d-fx-bgintensity-val');
+            hydrateFxRange('laneOpacity', 'keysh3d-fx-laneopacity', 'keysh3d-fx-laneopacity-val');
+            hydrateFxRange('octaveContrast', 'keysh3d-fx-octavecontrast', 'keysh3d-fx-octavecontrast-val');
+            // Camera fine-tune sliders live outside 0-1 — clamp to the
+            // control's own min/max (mirrors screen.js FX_RANGES).
+            const hydrateFxRangeIn = (key, elId, valId) => {
+                const n = parseFloat(localStorage.getItem('keys3d_bg_' + key));
+                if (!Number.isFinite(n)) return;
+                const el = document.getElementById(elId);
+                const v = Math.min(parseFloat(el.max), Math.max(parseFloat(el.min), n));
+                el.value = String(v);
+                document.getElementById(valId).textContent = v.toFixed(2);
+            };
+            hydrateFxRangeIn('camHeight', 'keysh3d-fx-camheight', 'keysh3d-fx-camheight-val');
+            hydrateFxRangeIn('camDist', 'keysh3d-fx-camdist', 'keysh3d-fx-camdist-val');
+            hydrateFxRangeIn('camTilt', 'keysh3d-fx-camtilt', 'keysh3d-fx-camtilt-val');
+            const storedCamera = localStorage.getItem('keys3d_bg_camera');
+            const cameraSel = document.getElementById('keysh3d-fx-camera');
+            if (storedCamera && Array.from(cameraSel.options).some(o => o.value === storedCamera)) {
+                cameraSel.value = storedCamera;
+            }
+            const storedStyle = localStorage.getItem('keys3d_bg_style');
+            const styleSel = document.getElementById('keysh3d-fx-bgstyle');
+            if (storedStyle && Array.from(styleSel.options).some(o => o.value === storedStyle)) {
+                styleSel.value = storedStyle;
+            }
+            const storedTheme = localStorage.getItem('keys3d_bg_theme');
+            const themeSel = document.getElementById('keysh3d-fx-theme');
+            if (storedTheme && Array.from(themeSel.options).some(o => o.value === storedTheme)) {
+                themeSel.value = storedTheme;
+            }
+            const storedPalette = localStorage.getItem('keys3d_bg_palette');
+            const paletteSel = document.getElementById('keysh3d-fx-palette');
+            if (storedPalette && Array.from(paletteSel.options).some(o => o.value === storedPalette)) {
+                paletteSel.value = storedPalette;
+            }
+            const storedSharp = localStorage.getItem('keys3d_bg_sharpMode');
+            const sharpSel = document.getElementById('keysh3d-fx-sharpmode');
+            if (storedSharp && Array.from(sharpSel.options).some(o => o.value === storedSharp)) {
+                sharpSel.value = storedSharp;
+            }
+        } catch (e) {
+            console.warn('[Keys-Hwy3D settings] hydration failed:', e);
+        }
+    })();
+    </script>
+</div>

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

@@ -0,0 +1,286 @@
+// Pure data-layer tests: load screen.js in a bare vm window and exercise the
+// __test exports (no DOM, no WebGL, no network).
+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.slopsmithViz_keys_highway_3d.__test;
+}
+
+test('beatDurSec: base, dotted, double-dotted, tuplet', () => {
+    const { beatDurSec } = load();
+    // 120 BPM → quarter = 0.5s
+    assert.equal(beatDurSec({ dur: 4 }, 120), 0.5);
+    assert.equal(beatDurSec({ dur: 2 }, 120), 1.0);
+    assert.equal(beatDurSec({ dur: 8 }, 120), 0.25);
+    // dotted quarter = 0.75s; double-dotted = 0.875s
+    assert.equal(beatDurSec({ dur: 4, dot: 1 }, 120), 0.75);
+    assert.equal(beatDurSec({ dur: 4, dot: 2 }, 120), 0.875);
+    // triplet eighth: 0.25 * 2/3
+    assert.ok(Math.abs(beatDurSec({ dur: 8, tu: [3, 2] }, 120) - 0.25 * 2 / 3) < 1e-9);
+    // invalid → null
+    assert.equal(beatDurSec({ dur: 0 }, 120), null);
+    assert.equal(beatDurSec({ dur: 4 }, null), null);
+});
+
+function measure(idx, t, opts = {}) {
+    return { idx, t, ...opts };
+}
+
+test('flattenNotation: basic two-hand flatten, sorted, durSec from tempo', () => {
+    const { flattenNotation } = load();
+    const notes = flattenNotation([
+        {
+            idx: 1, t: 0, tempo: 120,
+            staves: {
+                rh: { voices: [{ v: 1, beats: [
+                    { t: 0.5, dur: 4, notes: [{ midi: 64 }] },
+                    { t: 1.0, dur: 8, notes: [{ midi: 67 }] },
+                ] }] },
+                lh: { voices: [{ v: 1, beats: [
+                    { t: 0.0, dur: 2, notes: [{ midi: 48 }] },
+                ] }] },
+            },
+        },
+    ]);
+    assert.equal(notes.length, 3);
+    assert.deepEqual(JSON.parse(JSON.stringify(notes.map(n => n.midi))), [48, 64, 67]); // time-sorted
+    assert.equal(notes[0].hand, 'lh');
+    assert.equal(notes[0].durSec, 1.0);   // half at 120
+    assert.equal(notes[1].durSec, 0.5);   // quarter
+    assert.equal(notes[2].durSec, 0.25);  // eighth
+    assert.equal(notes[1].measureIdx, 1);
+});
+
+test('flattenNotation: tempo state carries across measures and changes apply', () => {
+    const { flattenNotation } = load();
+    const notes = flattenNotation([
+        measure(1, 0, { tempo: 120, staves: { rh: { voices: [{ v: 1, beats: [{ t: 0, dur: 4, notes: [{ midi: 60 }] }] }] } } }),
+        measure(2, 2, { staves: { rh: { voices: [{ v: 1, beats: [{ t: 2, dur: 4, notes: [{ midi: 62 }] }] }] } } }),
+        measure(3, 4, { tempo: 60, staves: { rh: { voices: [{ v: 1, beats: [{ t: 4, dur: 4, notes: [{ midi: 64 }] }] }] } } }),
+    ]);
+    assert.equal(notes[0].durSec, 0.5); // 120 BPM
+    assert.equal(notes[1].durSec, 0.5); // tempo carried
+    assert.equal(notes[2].durSec, 1.0); // 60 BPM
+});
+
+test('flattenNotation: tied notes extend instead of emitting a new block', () => {
+    const { flattenNotation } = load();
+    const notes = flattenNotation([
+        {
+            idx: 1, t: 0, tempo: 120,
+            staves: { rh: { voices: [{ v: 1, beats: [
+                { t: 0.0, dur: 2, notes: [{ midi: 60 }] },
+                { t: 1.0, dur: 2, notes: [{ midi: 60, tied: true }] },
+            ] }] } },
+        },
+    ]);
+    assert.equal(notes.length, 1);
+    assert.equal(notes[0].durSec, 2.0); // half + tied half
+});
+
+test('flattenNotation: no tempo anywhere falls back to next-onset gap', () => {
+    const { flattenNotation } = load();
+    const notes = flattenNotation([
+        {
+            idx: 1, t: 0,
+            staves: { rh: { voices: [{ v: 1, beats: [
+                { t: 0.0, dur: 4, notes: [{ midi: 60 }] },
+                { t: 0.8, dur: 4, notes: [{ midi: 62 }] },
+            ] }] } },
+        },
+    ]);
+    assert.ok(Math.abs(notes[0].durSec - 0.8) < 1e-9);
+    assert.equal(notes[1].durSec, 2.0); // final-beat fallback
+});
+
+test('flattenNotation: overlap clamp against next same-hand same-midi onset', () => {
+    const { flattenNotation } = load();
+    const notes = flattenNotation([
+        {
+            idx: 1, t: 0, tempo: 30, // whole note = 8s — way past the next onset
+            staves: { rh: { voices: [{ v: 1, beats: [
+                { t: 0.0, dur: 1, notes: [{ midi: 60 }] },
+                { t: 1.0, dur: 1, notes: [{ midi: 60 }] },
+            ] }] } },
+        },
+    ]);
+    assert.equal(notes[0].durSec, 1.0); // clamped to next onset
+});
+
+test('flattenNotation: rests, malformed beats, and out-of-range midi are skipped', () => {
+    const { flattenNotation } = load();
+    const notes = flattenNotation([
+        {
+            idx: 1, t: 0, tempo: 120,
+            staves: { rh: { voices: [{ v: 1, beats: [
+                { t: 0.0, dur: 4, rest: true },
+                { t: 0.5, dur: 4, notes: [{ midi: 200 }] },
+                null,
+                { t: 1.0, dur: 4, notes: [{ midi: 64 }] },
+            ] }] } },
+        },
+    ]);
+    assert.equal(notes.length, 1);
+    assert.equal(notes[0].midi, 64);
+});
+
+test('keyRange pads and clamps to the 88-key piano, keeps active span explicit', () => {
+    const { keyRange } = load();
+    assert.deepEqual(
+        JSON.parse(JSON.stringify(keyRange([{ midi: 60 }, { midi: 72 }]))),
+        { low: 58, high: 74, activeLow: 60, activeHigh: 72 },
+    );
+    // At the clamp edges the active span still reflects the chart extremes
+    // (not low+pad — that would mark A0/C8 inactive when actually played).
+    assert.deepEqual(
+        JSON.parse(JSON.stringify(keyRange([{ midi: 21 }, { midi: 108 }]))),
+        { low: 21, high: 108, activeLow: 21, activeHigh: 108 },
+    );
+    const empty = keyRange([]);
+    assert.ok(empty.low < 60 && empty.high > 60);
+    assert.ok(empty.activeLow > empty.activeHigh, 'empty chart has an empty active span');
+});
+
+test('noteLetter maps midi to pitch-class letters', () => {
+    const { noteLetter } = load();
+    assert.equal(noteLetter(60), 'C');
+    assert.equal(noteLetter(61), 'C#');
+    assert.equal(noteLetter(69), 'A');
+    assert.equal(noteLetter(71), 'B');
+    assert.equal(noteLetter(72), 'C');  // octave wraps
+    assert.equal(noteLetter(21), 'A');  // A0
+});
+
+test('scrollZ: events sit at hitZ exactly at their time and approach from -Z', () => {
+    const { scrollZ } = load();
+    const hitZ = -0.5, speed = 2.0;
+    // At now === eventT the event is exactly on the hit-line.
+    assert.equal(scrollZ(10, 10, hitZ, speed), hitZ);
+    // 1s before its time it is `speed` units further away (towards -Z).
+    assert.equal(scrollZ(10, 9, hitZ, speed), hitZ - speed);
+    // After its time it has moved past the hit-line (towards +Z).
+    assert.equal(scrollZ(10, 11, hitZ, speed), hitZ + speed);
+    // Marker and note-front-edge maths agree by construction: a note of
+    // length L positioned at scrollZ(t) - L/2 has its front edge at
+    // scrollZ(t).
+    const len = 0.8;
+    assert.equal(scrollZ(10, 10, hitZ, speed) - len / 2 + len / 2, hitZ);
+});
+
+test('measureMarkers extracts idx/t pairs', () => {
+    const { measureMarkers } = load();
+    assert.deepEqual(
+        JSON.parse(JSON.stringify(measureMarkers([{ idx: 1, t: 0 }, { idx: 2, t: 2.5 }, { bogus: true }]))),
+        [{ 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');
+});

plugins/keys_highway_3d/tests/fx_settings.test.js

@@ -0,0 +1,552 @@
+// FX-settings scaffold tests (guitar-highway parity controls). Same bare-vm
+// harness as data_layer.test.js — no DOM, no localStorage — which doubles as
+// a lint that the new module-scope FX code stays side-effect safe.
+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(extraWindow) {
+    const window = {
+        console,
+        location: { protocol: 'http:', host: 'localhost' },
+        slopsmith: {},
+        ...extraWindow,
+    };
+    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('readFxSettings: defaults survive a localStorage-less environment', () => {
+    const { readFxSettings, FX_DEFAULTS } = load().slopsmithViz_keys_highway_3d.__test;
+    assert.deepEqual(readFxSettings(), FX_DEFAULTS);
+    assert.equal(FX_DEFAULTS.bloom, true); // effects on by default
+});
+
+test('readFxSettings: reads keys3d_bg_* overrides and coerces types', () => {
+    const store = { keys3d_bg_bloom: '0' };
+    const win = load({
+        localStorage: {
+            getItem: (k) => (k in store ? store[k] : null),
+            setItem: (k, v) => { store[k] = v; },
+        },
+    });
+    const { readFxSettings } = win.slopsmithViz_keys_highway_3d.__test;
+    assert.equal(readFxSettings().bloom, false);
+    store.keys3d_bg_bloom = 'true';
+    assert.equal(readFxSettings().bloom, true);
+    store.keys3d_bg_bloom = 'false';
+    assert.equal(readFxSettings().bloom, false);
+    // Corrupt/foreign value → keep the default rather than silently
+    // disabling the effect.
+    store.keys3d_bg_bloom = 'banana';
+    assert.equal(readFxSettings().bloom, true);
+});
+
+test('keys3dSetFx: persists, coerces, and ignores unknown keys', () => {
+    const store = {};
+    const events = [];
+    const win = load({
+        localStorage: {
+            getItem: (k) => (k in store ? store[k] : null),
+            setItem: (k, v) => { store[k] = v; },
+        },
+        dispatchEvent: (ev) => { events.push(ev); return true; },
+        CustomEvent: class CustomEvent {
+            constructor(type, opts) { this.type = type; this.detail = opts && opts.detail; }
+        },
+    });
+    win.keys3dSetFx('bloom', false);
+    assert.equal(store.keys3d_bg_bloom, '0');
+    // String forms round-trip like the reader's accepted representations.
+    win.keys3dSetFx('bloom', 'false');
+    assert.equal(store.keys3d_bg_bloom, '0');
+    win.keys3dSetFx('bloom', 'true');
+    assert.equal(store.keys3d_bg_bloom, '1');
+    win.keys3dSetFx('bloom', false);
+    assert.equal(events.length, 4);
+    assert.equal(events[0].type, 'keys3d:settings');
+    // Field-wise (the detail object was built inside the vm realm, so a
+    // deep-strict compare would trip on its foreign Object.prototype).
+    assert.equal(events[0].detail.fx.bloom, false);
+    assert.deepEqual(Object.keys(events[0].detail.fx), ['bloom']);
+    // Unknown key: no write, no event.
+    win.keys3dSetFx('nonsense', 1);
+    assert.equal(events.length, 4);
+    assert.ok(!('keys3d_bg_nonsense' in store));
+});
+
+test('_classifyTiming: OK band is 40% of the window, sign maps early/late', () => {
+    const { _classifyTiming } = load().slopsmithViz_keys_highway_3d.__test;
+    const tol = 0.10;                    // keys HIT_TOLERANCE_S
+    assert.equal(_classifyTiming(0, tol), 'OK');
+    assert.equal(_classifyTiming(tol * 0.4, tol), 'OK');
+    assert.equal(_classifyTiming(-tol * 0.4, tol), 'OK');
+    // delta = note.t - now: positive → struck before the note → EARLY.
+    assert.equal(_classifyTiming(tol * 0.41, tol), 'EARLY');
+    assert.equal(_classifyTiming(-tol * 0.41, tol), 'LATE');
+    assert.equal(_classifyTiming(NaN, tol), 'OK');
+});
+
+test('noteKey prefix round-trips the matched note time (timing-delta source)', () => {
+    const { noteKey } = load().slopsmithViz_keys_highway_3d.__test;
+    // _checkHit derives the timing delta as parseFloat(judgeHit's key) - t;
+    // this pins the serialization that makes that recovery valid.
+    assert.equal(parseFloat(noteKey(12.3456, 60)), 12.346);
+    assert.equal(parseFloat(noteKey(0, 21)), 0);
+});
+
+test('FX defaults: hit-FX + vibrancy controls ship enabled', () => {
+    const { FX_DEFAULTS } = load().slopsmithViz_keys_highway_3d.__test;
+    assert.equal(FX_DEFAULTS.sparks, true);
+    assert.equal(FX_DEFAULTS.timingFx, true);
+    assert.equal(FX_DEFAULTS.streakFx, true);
+    assert.equal(FX_DEFAULTS.hitFx, 0.7);
+    assert.equal(FX_DEFAULTS.vibrancy, 0.85);
+});
+
+test('themes: table ids match the guitar highway, default is the stock palette', () => {
+    const { BG_THEMES, _bgThemeColors, readThemeSetting } = load().slopsmithViz_keys_highway_3d.__test;
+    assert.deepEqual(Object.keys(BG_THEMES), [
+        'default', 'midnight', 'charcoal', 'deeppurple', 'forest', 'warmslate',
+        'deepfocus', 'deepsea', 'cathode', 'cathodegreen', 'hearth',
+    ]);
+    // 'default' preserves THIS plugin's original look.
+    assert.equal(BG_THEMES.default.clear, 0x1a1a2e);
+    assert.equal(BG_THEMES.default.board, 0x141422);
+    assert.equal(BG_THEMES.default.laneDim, 0x2a2a3e);
+    assert.equal(_bgThemeColors('nonsense'), BG_THEMES.default);
+    assert.equal(readThemeSetting(), 'default'); // no localStorage in the vm
+    for (const [id, t] of Object.entries(BG_THEMES)) {
+        assert.equal(t.clear, t.fog, id + ' clear==fog (horizon dissolve)');
+        assert.ok(t.laneDim != null, id + ' rail color');
+    }
+});
+
+test('FX defaults: theme-PR controls ship enabled at stock-neutral values', () => {
+    const { FX_DEFAULTS } = load().slopsmithViz_keys_highway_3d.__test;
+    assert.equal(FX_DEFAULTS.cinematic, true);
+    assert.equal(FX_DEFAULTS.glow, 0.5);   // 0.5 = 1.0x multiplier (stock)
+});
+
+
+test('bg styles: validated id set, particles default', () => {
+    const { BG_STYLE_IDS, readBgStyleSetting } = load().slopsmithViz_keys_highway_3d.__test;
+    // Host-realm copy — the vm array's foreign prototype trips deepEqual.
+    assert.deepEqual([...BG_STYLE_IDS], ['off', 'particles', 'lights', 'geometric']);
+    assert.equal(readBgStyleSetting(), 'particles');
+});
+
+test('FX defaults: ambience + score FX ship enabled', () => {
+    const { FX_DEFAULTS } = load().slopsmithViz_keys_highway_3d.__test;
+    assert.equal(FX_DEFAULTS.scoreFx, true);
+    assert.equal(FX_DEFAULTS.bgIntensity, 0.5);
+    assert.equal(FX_DEFAULTS.bgReactive, true);
+});
+
+/* ── Note-colour palettes (feat/keys3d-note-palettes) ────────────────── */
+
+test('note palettes: 12 entries each, classic IS the stock table', () => {
+    const { NOTE_PALETTES, PITCH_CLASS_COLORS } =
+        load().slopsmithViz_keys_highway_3d.__test;
+    assert.deepEqual(Object.keys(NOTE_PALETTES),
+        ['classic', 'emerald', 'vivid', 'pastel', 'ice']);
+    for (const [id, colors] of Object.entries(NOTE_PALETTES)) {
+        assert.equal(colors.length, 12, id + ' has one colour per pitch class');
+        for (const c of colors) {
+            assert.ok(Number.isInteger(c) && c >= 0 && c <= 0xffffff,
+                id + ' colours are 24-bit ints');
+        }
+    }
+    // 'classic' preserves the shipped look byte-identically — it is the
+    // same array, not a copy that could drift.
+    assert.equal(NOTE_PALETTES.classic, PITCH_CLASS_COLORS);
+    assert.equal(PITCH_CLASS_COLORS[0], 0xff3030); // C stays red in classic
+});
+
+test('note palettes: two-tone tables use darker sharps than naturals', () => {
+    const { NOTE_PALETTES } = load().slopsmithViz_keys_highway_3d.__test;
+    const luma = (c) =>
+        0.2126 * ((c >> 16) & 0xff) + 0.7152 * ((c >> 8) & 0xff) + 0.0722 * (c & 0xff);
+    for (const id of ['emerald', 'ice']) {
+        const p = NOTE_PALETTES[id];
+        for (const sharp of [1, 3, 6, 8, 10]) {
+            assert.ok(luma(p[sharp]) < luma(p[0]),
+                id + ' sharp pc ' + sharp + ' darker than naturals');
+        }
+    }
+});
+
+test('readPaletteSetting: octaves default, validated overrides only', () => {
+    // No localStorage in the vm → the plug-and-play default.
+    const bare = load().slopsmithViz_keys_highway_3d.__test;
+    assert.equal(bare.readPaletteSetting(), 'octaves');
+    // An explicit non-default value (classic) overrides.
+    const store = { keys3d_bg_palette: 'classic' };
+    const win = load({
+        localStorage: {
+            getItem: (k) => (k in store ? store[k] : null),
+            setItem: (k, v) => { store[k] = v; },
+        },
+    });
+    const { readPaletteSetting } = win.slopsmithViz_keys_highway_3d.__test;
+    assert.equal(readPaletteSetting(), 'classic');
+    // Corrupt/foreign value → the default rather than an undefined scheme.
+    store.keys3d_bg_palette = 'banana';
+    assert.equal(readPaletteSetting(), 'octaves');
+});
+
+test('keys3dSetPalette: persists + dispatches valid ids, ignores unknown', () => {
+    const store = {};
+    const events = [];
+    const win = load({
+        localStorage: {
+            getItem: (k) => (k in store ? store[k] : null),
+            setItem: (k, v) => { store[k] = v; },
+        },
+        dispatchEvent: (ev) => { events.push(ev); return true; },
+        CustomEvent: class CustomEvent {
+            constructor(type, opts) { this.type = type; this.detail = opts && opts.detail; }
+        },
+    });
+    win.keys3dSetPalette('emerald');
+    assert.equal(store.keys3d_bg_palette, 'emerald');
+    assert.equal(events.length, 1);
+    assert.equal(events[0].type, 'keys3d:settings');
+    assert.equal(events[0].detail.palette, 'emerald');
+    // Unknown id: no write, no event.
+    win.keys3dSetPalette('banana');
+    assert.equal(store.keys3d_bg_palette, 'emerald');
+    assert.equal(events.length, 1);
+    // 'octaves' (procedural, not a 12-array) is a valid selectable id.
+    win.keys3dSetPalette('octaves');
+    assert.equal(store.keys3d_bg_palette, 'octaves');
+    assert.equal(events.length, 2);
+});
+
+test('PALETTE_IDS: the array palettes plus the procedural octaves scheme', () => {
+    const { PALETTE_IDS, NOTE_PALETTES } = load().slopsmithViz_keys_highway_3d.__test;
+    assert.deepEqual([...PALETTE_IDS],
+        [...Object.keys(NOTE_PALETTES), 'octaves']);
+    assert.ok(PALETTE_IDS.indexOf('octaves') !== -1);
+    assert.ok(!('octaves' in NOTE_PALETTES)); // it is NOT a 12-entry table
+});
+
+test('octaveNoteColor: hue steps per octave, loops, sharps darker, sub-C1 distinct', () => {
+    const { octaveNoteColor, OCTAVE_HUES } = load().slopsmithViz_keys_highway_3d.__test;
+    const luma = (c) =>
+        0.2126 * ((c >> 16) & 0xff) + 0.7152 * ((c >> 8) & 0xff) + 0.0722 * (c & 0xff);
+    // C1 (midi 24) = first hue; C2 (36) = second; C8 (108) = 8th (index 7).
+    assert.equal(octaveNoteColor(24), OCTAVE_HUES[0]);   // C1 red
+    assert.equal(octaveNoteColor(35), OCTAVE_HUES[0]);   // B1 still octave 1
+    assert.equal(octaveNoteColor(36), OCTAVE_HUES[1]);   // C2 orange
+    assert.equal(octaveNoteColor(60), OCTAVE_HUES[3]);   // C4 (middle C)
+    assert.equal(octaveNoteColor(108), OCTAVE_HUES[7]);  // C8 last hue
+    // Naturals across one octave (C1..B1 whites) all share the octave hue.
+    for (const nat of [24, 26, 28, 29, 31, 33, 35]) {
+        assert.equal(octaveNoteColor(nat), OCTAVE_HUES[0], 'natural ' + nat);
+    }
+    // Sharps in an octave are a DARKER shade of that same hue.
+    for (const sharp of [25, 27, 30, 32, 34]) { // C#1..A#1
+        assert.ok(luma(octaveNoteColor(sharp)) < luma(OCTAVE_HUES[0]),
+            'sharp ' + sharp + ' darker than the octave natural');
+    }
+    // The three keys below C1 (A0/A#0/B0) share a distinct sub-C1 colour,
+    // different from the red octave-1 start.
+    assert.equal(octaveNoteColor(21), octaveNoteColor(23)); // A0 == B0 hue
+    assert.notEqual(octaveNoteColor(21), OCTAVE_HUES[0]);
+    // Loop: an octave past the table wraps (safety for out-of-88 midi).
+    assert.equal(octaveNoteColor(24 + 12 * OCTAVE_HUES.length), OCTAVE_HUES[0]);
+});
+
+/* ── Camera presets + fine-tune (feat/keys3d-camera) ─────────────────── */
+
+test('FX defaults: camera height/distance/tilt all neutral (preset carries the tuned aim)', () => {
+    const { FX_DEFAULTS, FX_RANGES } = load().slopsmithViz_keys_highway_3d.__test;
+    assert.equal(FX_DEFAULTS.camHeight, 1.0);
+    assert.equal(FX_DEFAULTS.camDist, 1.0);
+    // Tilt ships NEUTRAL (0): the tuned plug-and-play aim now lives in
+    // CAM_PRESETS.overhead.lookY, so the fine-tune only nudges from a preset
+    // and 'classic' + this default reproduces the exact historical rig.
+    assert.equal(FX_DEFAULTS.camTilt, 0.0);
+    assert.ok(FX_DEFAULTS.camTilt >= FX_RANGES.camTilt[0] && FX_DEFAULTS.camTilt <= FX_RANGES.camTilt[1]);
+    // Height/distance bracket 1 (can go lower AND higher); tilt spans 0.
+    assert.ok(FX_RANGES.camHeight[0] < 1 && 1 < FX_RANGES.camHeight[1]);
+    assert.ok(FX_RANGES.camDist[0] < 1 && 1 < FX_RANGES.camDist[1]);
+    assert.ok(FX_RANGES.camTilt[0] < 0 && 0 < FX_RANGES.camTilt[1]);
+});
+
+test('camTilt: negative values survive the clamp (down-tilt must be reachable)', () => {
+    const store = {};
+    const win = load({
+        localStorage: {
+            getItem: (k) => (k in store ? store[k] : null),
+            setItem: (k, v) => { store[k] = v; },
+        },
+        dispatchEvent: () => true,
+        CustomEvent: class { constructor(t, o) { this.type = t; this.detail = o && o.detail; } },
+    });
+    const { FX_RANGES } = win.slopsmithViz_keys_highway_3d.__test;
+    win.keys3dSetFx('camTilt', -0.5);
+    assert.equal(store.keys3d_bg_camTilt, '-0.5');   // NOT crushed to 0 by a 0-1 clamp
+    win.keys3dSetFx('camTilt', -99);
+    assert.equal(parseFloat(store.keys3d_bg_camTilt), FX_RANGES.camTilt[0]);
+});
+
+test('FX ranges: reader + setter clamp to the declared range, not 0-1', () => {
+    const store = { keys3d_bg_camHeight: '5', keys3d_bg_camDist: '0.01' };
+    const events = [];
+    const win = load({
+        localStorage: {
+            getItem: (k) => (k in store ? store[k] : null),
+            setItem: (k, v) => { store[k] = v; },
+        },
+        dispatchEvent: (ev) => { events.push(ev); return true; },
+        CustomEvent: class CustomEvent {
+            constructor(type, opts) { this.type = type; this.detail = opts && opts.detail; }
+        },
+    });
+    const { readFxSettings, FX_RANGES } = win.slopsmithViz_keys_highway_3d.__test;
+    // Reader: corrupt/out-of-range writes clamp to the declared bounds.
+    assert.equal(readFxSettings().camHeight, FX_RANGES.camHeight[1]);
+    assert.equal(readFxSettings().camDist, FX_RANGES.camDist[0]);
+    // Setter: same clamp on the way in; a value above 1 must survive
+    // (the historical 0-1 clamp would have crushed 1.3 to 1).
+    win.keys3dSetFx('camHeight', 1.3);
+    assert.equal(store.keys3d_bg_camHeight, '1.3');
+    win.keys3dSetFx('camDist', 99);
+    assert.equal(parseFloat(store.keys3d_bg_camDist), FX_RANGES.camDist[1]);
+    // Un-ranged keys keep the historical 0-1 clamp.
+    win.keys3dSetFx('vibrancy', 2);
+    assert.equal(store.keys3d_bg_vibrancy, '1');
+});
+
+test('scrollZ: distance-to-hitline scales linearly with the speed argument', () => {
+    const { scrollZ } = load().slopsmithViz_keys_highway_3d.__test;
+    const hitZ = 0;
+    const d1 = scrollZ(2, 0, hitZ, 130) - hitZ;   // 2s ahead at stock speed
+    const d2 = scrollZ(2, 0, hitZ, 260) - hitZ;   // same note at 2x speed
+    assert.equal(d2, d1 * 2);
+    // At the hit moment the note is at the hit-line regardless of speed.
+    assert.equal(scrollZ(5, 5, hitZ, 130), hitZ);
+    assert.equal(scrollZ(5, 5, hitZ, 260), hitZ);
+});
+
+test('camera presets: classic preserves the stock rig, overhead is the default', () => {
+    const { CAM_PRESETS, readCameraSetting } = load().slopsmithViz_keys_highway_3d.__test;
+    assert.deepEqual(Object.keys(CAM_PRESETS), ['classic', 'elevated', 'overhead']);
+    // 'classic' preserves the historical constants (pre-K units) even though
+    // it is no longer the default — anyone who picks it gets the old rig back
+    // EXACTLY, because camTilt now defaults to 0 (neutral): effective aim =
+    // classic.lookY + 0*CAM_TILT_UNITS = 8, the historical LOOK_Y.
+    assert.deepEqual({ ...CAM_PRESETS.classic },
+        { fov: 40, y: 46, z: 112, lookY: 8, lookZ: -165 });
+    for (const [id, p] of Object.entries(CAM_PRESETS)) {
+        for (const f of ['fov', 'y', 'z', 'lookY', 'lookZ']) {
+            assert.ok(Number.isFinite(p[f]), id + '.' + f + ' is a number');
+        }
+        assert.ok(p.y > 0 && p.z > 0, id + ' sits above and behind the keys');
+    }
+    assert.equal(readCameraSetting(), 'overhead'); // no localStorage in the vm → tuned default
+});
+
+test('camera default look is unchanged: overhead bakes the old tuned tilt, camTilt is neutral', () => {
+    const { CAM_PRESETS, FX_DEFAULTS } = load().slopsmithViz_keys_highway_3d.__test;
+    const CAM_TILT_UNITS = 55; // full-swing of the camTilt offset at ±1 (screen.js)
+    // The shipped default look = overhead preset + the default camTilt. Before,
+    // that was lookY 0 + (−0.6 × 55) = −33; the tuned aim now lives in the
+    // preset (lookY −33) with a neutral camTilt (0), so the effective aim — and
+    // thus the out-of-the-box framing — is byte-identical.
+    const effOverhead = CAM_PRESETS.overhead.lookY + FX_DEFAULTS.camTilt * CAM_TILT_UNITS;
+    assert.equal(effOverhead, -33);
+    // 'classic' + the neutral default reproduces the historical LOOK_Y (8) —
+    // the "pick Classic for the original look" promise, now actually true.
+    const effClassic = CAM_PRESETS.classic.lookY + FX_DEFAULTS.camTilt * CAM_TILT_UNITS;
+    assert.equal(effClassic, 8);
+});
+
+test('keys3dSetCamera: persists + dispatches valid ids, ignores unknown', () => {
+    const store = {};
+    const events = [];
+    const win = load({
+        localStorage: {
+            getItem: (k) => (k in store ? store[k] : null),
+            setItem: (k, v) => { store[k] = v; },
+        },
+        dispatchEvent: (ev) => { events.push(ev); return true; },
+        CustomEvent: class CustomEvent {
+            constructor(type, opts) { this.type = type; this.detail = opts && opts.detail; }
+        },
+    });
+    win.keys3dSetCamera('overhead');
+    assert.equal(store.keys3d_bg_camera, 'overhead');
+    assert.equal(events.length, 1);
+    assert.equal(events[0].type, 'keys3d:settings');
+    assert.equal(events[0].detail.camera, 'overhead');
+    win.keys3dSetCamera('helicopter');
+    assert.equal(store.keys3d_bg_camera, 'overhead');
+    assert.equal(events.length, 1);
+    const { readCameraSetting } = win.slopsmithViz_keys_highway_3d.__test;
+    assert.equal(readCameraSetting(), 'overhead');
+    store.keys3d_bg_camera = 'garbage';
+    assert.equal(readCameraSetting(), 'overhead');
+});
+
+/* ── Flat-sharps / piano-shaped lanes (feat/keys3d-flat-lanes) ───────── */
+
+test('FX defaults: octave separators on, lanes off (minimal default look)', () => {
+    const { FX_DEFAULTS } = load().slopsmithViz_keys_highway_3d.__test;
+    assert.equal(FX_DEFAULTS.octaveGaps, true);   // octave separators ship on
+    assert.equal(FX_DEFAULTS.laneOpacity, 0.0);   // dark floor + guide lines by default
+    assert.equal(FX_DEFAULTS.octaveContrast, 0.5);
+    // Sharp LAYOUT is a string setting, not an FX bool.
+    assert.equal('flatSharps' in FX_DEFAULTS, false);
+    assert.equal('laneColors' in FX_DEFAULTS, false); // superseded by laneOpacity
+});
+
+test('keys3dSetFx: highway-layout controls persist (bool + sliders)', () => {
+    const store = {};
+    const win = load({
+        localStorage: {
+            getItem: (k) => (k in store ? store[k] : null),
+            setItem: (k, v) => { store[k] = v; },
+        },
+        dispatchEvent: () => true,
+        CustomEvent: class { constructor(t, o) { this.type = t; this.detail = o && o.detail; } },
+    });
+    win.keys3dSetFx('octaveGaps', true);
+    assert.equal(store.keys3d_bg_octaveGaps, '1');
+    // laneOpacity / octaveContrast are 0-1 numbers, persisted verbatim + clamped.
+    win.keys3dSetFx('laneOpacity', 0.35);
+    assert.equal(store.keys3d_bg_laneOpacity, '0.35');
+    win.keys3dSetFx('laneOpacity', 5); // clamps to the 0-1 range
+    assert.equal(store.keys3d_bg_laneOpacity, '1');
+    win.keys3dSetFx('octaveContrast', 0.8);
+    assert.equal(store.keys3d_bg_octaveContrast, '0.8');
+});
+
+test('sharpMode: realistic default, validated ids, persists + dispatches', () => {
+    const bare = load().slopsmithViz_keys_highway_3d.__test;
+    assert.deepEqual([...bare.SHARP_MODES], ['floating', 'flat', 'realistic']);
+    assert.equal(bare.readSharpModeSetting(), 'realistic'); // no localStorage → default
+    const store = {};
+    const events = [];
+    const win = load({
+        localStorage: {
+            getItem: (k) => (k in store ? store[k] : null),
+            setItem: (k, v) => { store[k] = v; },
+        },
+        dispatchEvent: (ev) => { events.push(ev); return true; },
+        CustomEvent: class { constructor(t, o) { this.type = t; this.detail = o && o.detail; } },
+    });
+    win.keys3dSetSharpMode('flat'); // a non-default id, to exercise persistence
+    assert.equal(store.keys3d_bg_sharpMode, 'flat');
+    assert.equal(events[0].detail.sharpMode, 'flat');
+    assert.equal(win.slopsmithViz_keys_highway_3d.__test.readSharpModeSetting(), 'flat');
+    // Unknown id ignored (no write, no event).
+    win.keys3dSetSharpMode('bogus');
+    assert.equal(store.keys3d_bg_sharpMode, 'flat');
+    assert.equal(events.length, 1);
+});
+
+test('laneSpanFlat (V5): lanes tile with zero overlap and even the naturals', () => {
+    const { laneSpanFlat, _isBlackPc } = load().slopsmithViz_keys_highway_3d.__test;
+    const sh = 2.2, shift = 2.2 / 3;
+    const dims = { whiteW: 12, sharpHalf: sh, shift, octGap: 0.9 }; // mirrors shipped LANE_DIMS_FLAT
+    // cx for one octave: whites on integer slots, blacks on half-slots — the
+    // same slot geometry keyLayout/keyX produce (cx = slot * whiteW=12).
+    const CX = {
+        60: 0, 61: 6, 62: 12, 63: 18, 64: 24, 65: 36, 66: 42,
+        67: 48, 68: 54, 69: 60, 70: 66, 71: 72, 72: 84,
+    };
+    const midis = [60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72];
+    const spans = midis.map((m) => laneSpanFlat(m, _isBlackPc(m), CX[m], dims, false));
+    const wOf = (s) => s.right - s.left;
+    const w = (m) => wOf(spans[midis.indexOf(m)]);
+    // Zero-overlap tiling: every lane abuts the previous one (no gap, no overlap).
+    for (let i = 1; i < spans.length; i++) {
+        assert.ok(Math.abs(spans[i].left - spans[i - 1].right) < 1e-9, 'lane ' + midis[i] + ' abuts');
+    }
+    // Sharps are all the same width.
+    for (const m of [61, 63, 66, 68, 70]) {
+        assert.ok(Math.abs(w(m) - 2 * sh) < 1e-9, 'sharp ' + m + ' width');
+    }
+    // The lean evens the naturals: C, D, E, F, B all come out equal.
+    for (const m of [62, 64, 65, 71]) {
+        assert.ok(Math.abs(w(m) - w(60)) < 1e-9, 'natural ' + m + ' == C (evened)');
+    }
+    // G and A are the only slightly-smaller naturals (G# can't lean) — still
+    // clearly wider than a sharp, and MUCH closer to the rest than plain V2
+    // (which would leave D at 12−2·sh, far below C's 12−sh).
+    assert.ok(Math.abs(w(67) - w(69)) < 1e-9, 'G == A');
+    assert.ok(w(67) < w(60) && w(67) > 2 * sh, 'G/A a touch smaller, still wider than a sharp');
+    assert.ok(w(60) - w(67) < sh, 'natural spread is under one sharp-width');
+});
+
+test('laneSpanReal (V4): naturals uniform, sharps full-width and overlapping', () => {
+    const { laneSpanReal } = load().slopsmithViz_keys_highway_3d.__test;
+    const dims = { natHalf: 5.64, sharpHalf: 3.2, octGap: 0.9 }; // mirrors LANE_DIMS_REAL
+    const wOf = (s) => s.right - s.left;
+    // Every natural is the same full width, whatever its neighbours.
+    for (const [midi, slot] of [[60, 0], [62, 1], [64, 2], [67, 4], [71, 6]]) {
+        assert.ok(Math.abs(wOf(laneSpanReal(midi, false, slot * 12, dims, false)) - 2 * 5.64) < 1e-9,
+            'natural ' + midi + ' uniform');
+    }
+    // Sharps are the full (wider) black-key width and overlap their naturals.
+    const C = laneSpanReal(60, false, 0, dims, false);
+    const Cs = laneSpanReal(61, true, 6, dims, false);
+    assert.ok(Math.abs(wOf(Cs) - 2 * 3.2) < 1e-9, 'sharp full width');
+    assert.ok(Cs.left < C.right, 'sharp overlaps (tucks over) the natural');
+});
+
+test('laneSpanFlat (V5): octaveGaps widens B→C by octGap, sharps unaffected', () => {
+    const { laneSpanFlat } = load().slopsmithViz_keys_highway_3d.__test;
+    const dims = { whiteW: 12, sharpHalf: 2.2, shift: 2.2 / 3, octGap: 0.9 };
+    const gapOff = laneSpanFlat(72, false, 84, dims, false).left - laneSpanFlat(71, false, 72, dims, false).right;
+    const gapOn = laneSpanFlat(72, false, 84, dims, true).left - laneSpanFlat(71, false, 72, dims, true).right;
+    assert.ok(Math.abs((gapOn - gapOff) - dims.octGap) < 1e-9, 'B→C divider grows by octGap');
+    // Sharps are unaffected by the octave-gap option.
+    const s = laneSpanFlat(61, true, 6, dims, true);
+    assert.ok(Math.abs((s.right - s.left) - 2 * dims.sharpHalf) < 1e-9, 'sharp width unchanged by gaps');
+});
+
+test('laneSpanFlat (V5): active-range boundary key is NOT trimmed by an out-of-range neighbor sharp', () => {
+    const { laneSpanFlat } = load().slopsmithViz_keys_highway_3d.__test;
+    const dims = { whiteW: 12, sharpHalf: 2.2, shift: 2.2 / 3, octGap: 0.9 }; // mirrors LANE_DIMS_FLAT
+    // F (midi 65, cx 36): its upper neighbor F# (66) is a sharp. When F sits
+    // at range.activeHigh and F# is excluded from the active range, F# never
+    // gets a lane drawn (see the activeLow/activeHigh skip around the
+    // lane-strip loop) — trimming F's right edge for it would leave a dark,
+    // unfilled sliver. The edge should stay full instead.
+    const highBoundary = { activeLow: 60, activeHigh: 65 };
+    const fAtBoundary = laneSpanFlat(65, false, 36, dims, false, highBoundary);
+    assert.ok(Math.abs(fAtBoundary.right - (36 + dims.whiteW / 2)) < 1e-9,
+        'F right edge stays full when F# is out of the active range');
+    // Same key, but now F# IS in the active range: normal zero-overlap
+    // tiling applies — the trim matches the ungated (no-range) call exactly,
+    // so in-range geometry is unaffected by this fix.
+    const highIncluded = { activeLow: 60, activeHigh: 66 };
+    const fWithSharpInRange = laneSpanFlat(65, false, 36, dims, false, highIncluded);
+    const fUngated = laneSpanFlat(65, false, 36, dims, false);
+    assert.ok(Math.abs(fWithSharpInRange.right - fUngated.right) < 1e-9,
+        'F trims normally once F# is back in range');
+    assert.ok(fWithSharpInRange.right < fAtBoundary.right, 'in-range trim is narrower than the boundary full edge');
+
+    // Symmetric case on the low edge: D (midi 62, cx 12), lower neighbor C#
+    // (61) excluded when D sits at range.activeLow.
+    const lowBoundary = { activeLow: 62, activeHigh: 72 };
+    const dAtBoundary = laneSpanFlat(62, false, 12, dims, false, lowBoundary);
+    assert.ok(Math.abs(dAtBoundary.left - (12 - dims.whiteW / 2)) < 1e-9,
+        'D left edge stays full when C# is out of the active range');
+    const lowIncluded = { activeLow: 61, activeHigh: 72 };
+    const dWithSharpInRange = laneSpanFlat(62, false, 12, dims, false, lowIncluded);
+    const dUngated = laneSpanFlat(62, false, 12, dims, false);
+    assert.ok(Math.abs(dWithSharpInRange.left - dUngated.left) < 1e-9,
+        'D trims normally once C# is back in range');
+});
+

plugins/keys_highway_3d/tests/scoring.test.js

@@ -0,0 +1,154 @@
+// Pure MIDI-scoring tests: load screen.js in a bare vm window and exercise
+// the __test exports (no DOM, no WebGL, no MIDI device, no network).
+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.slopsmithViz_keys_highway_3d.__test;
+}
+
+const TOL = 0.10;
+
+test('accuracyOf/scoreOf mirror the notedetect stats formula', () => {
+    const { accuracyOf, scoreOf } = load();
+    // accuracy = hits / max(1, hits + misses)
+    assert.equal(accuracyOf(0, 0), 0);
+    assert.equal(accuracyOf(10, 0), 1);
+    assert.equal(accuracyOf(3, 1), 0.75);
+    // score = round(hits * 100 * accuracy)
+    assert.equal(scoreOf(0, 0), 0);
+    assert.equal(scoreOf(10, 0), 1000);
+    assert.equal(scoreOf(3, 1), Math.round(3 * 100 * 0.75));
+    // Monotonic in accuracy at fixed hits.
+    assert.ok(scoreOf(5, 0) > scoreOf(5, 5));
+});
+
+test('judgeHit: exact note inside ±0.10 s window hits; outside misses', () => {
+    const { judgeHit } = load();
+    const notes = [
+        { midi: 60, t: 1.0 },
+        { midi: 64, t: 1.0 },
+        { midi: 62, t: 2.0 },
+    ];
+    const hitKeys = new Set();
+    // On time.
+    assert.equal(judgeHit(notes, 60, 1.0, hitKeys, TOL), '1.000|60');
+    // Near the edge of the window (the exact ±0.10 boundary is float-
+    // representation dependent, same as the piano plugin).
+    assert.equal(judgeHit(notes, 62, 2.099, hitKeys, TOL), '2.000|62');
+    assert.equal(judgeHit(notes, 64, 0.901, hitKeys, TOL), '1.000|64');
+    // Just outside the window.
+    assert.equal(judgeHit(notes, 60, 1.11, hitKeys, TOL), null);
+    // Wrong note — nothing at that midi anywhere near.
+    assert.equal(judgeHit(notes, 65, 1.0, hitKeys, TOL), null);
+});
+
+test('judgeHit: dedupes by t|midi — a chart note can only be hit once', () => {
+    const { judgeHit } = load();
+    const notes = [{ midi: 60, t: 1.0 }, { midi: 60, t: 1.15 }];
+    const hitKeys = new Set();
+    const first = judgeHit(notes, 60, 1.02, hitKeys, TOL);
+    assert.equal(first, '1.000|60');
+    hitKeys.add(first);
+    // Second strike near the same time falls through to the NEXT un-hit
+    // chart note at the same midi (double-stop repeats).
+    const second = judgeHit(notes, 60, 1.06, hitKeys, TOL);
+    assert.equal(second, '1.150|60');
+    hitKeys.add(second);
+    // Third strike: both consumed → wrong note.
+    assert.equal(judgeHit(notes, 60, 1.1, hitKeys, TOL), null);
+});
+
+test('judgeHit: empty/absent chart never judges', () => {
+    const { judgeHit } = load();
+    assert.equal(judgeHit([], 60, 1.0, new Set(), TOL), null);
+    assert.equal(judgeHit(null, 60, 1.0, new Set(), TOL), null);
+});
+
+test('sweepMissed: marks elapsed unhit notes once, respects hit + floor', () => {
+    const { sweepMissed, noteKey } = load();
+    const notes = [
+        { midi: 60, t: 1.0 },
+        { midi: 62, t: 1.5 },
+        { midi: 64, t: 5.0 },
+    ];
+    const hitKeys = new Set([noteKey(1.0, 60)]); // 60@1.0 was hit
+    const missedKeys = new Set();
+    const missed = [];
+    // At t=2.0 the windows for 1.0 and 1.5 have elapsed; 5.0 is pending.
+    const n1 = sweepMissed(notes, 2.0, hitKeys, missedKeys, TOL, null, n => missed.push(n.midi));
+    assert.equal(n1, 1);
+    assert.deepEqual(missed, [62]);
+    assert.ok(missedKeys.has(noteKey(1.5, 62)));
+    // Sweeping again counts nothing new (idempotent per note).
+    assert.equal(sweepMissed(notes, 2.1, hitKeys, missedKeys, TOL, null), 0);
+    // Floor: a device connected at t=6 must not retro-miss the 5.0 note.
+    const hk2 = new Set(), mk2 = new Set();
+    assert.equal(sweepMissed(notes, 6.0, hk2, mk2, TOL, 6.0), 0);
+});
+
+test('sweepMissed: a note exactly at the connect floor is not retro-missed', () => {
+    // Off-by-one guard: floor is the connect instant; a note whose onset
+    // equals it (device connected exactly as the onset passed) must be
+    // excluded, not swept. Floor comparison is `<=`, not `<`.
+    const { sweepMissed } = load();
+    const notes = [{ midi: 60, t: 5.0 }, { midi: 62, t: 6.0 }];
+    const missedKeys = new Set();
+    const missed = [];
+    const n = sweepMissed(notes, 7.0, new Set(), missedKeys, TOL, 5.0,
+        m => missed.push(m.midi));
+    assert.equal(n, 1);
+    assert.deepEqual(missed, [62]);
+});
+
+test('sweepMissed: a long frame stall cannot let elapsed notes slip past', () => {
+    const { sweepMissed } = load();
+    const notes = [{ midi: 60, t: 1.0 }, { midi: 62, t: 3.0 }];
+    const missedKeys = new Set();
+    // The previous sweep ran at t≈0; the next runs 10 s later (backgrounded
+    // tab / render hitch). Both elapsed notes must still be counted.
+    assert.equal(sweepMissed(notes, 10.0, new Set(), missedKeys, TOL, null), 2);
+});
+
+test('sweepMissed: cursor advances monotonically and never recounts', () => {
+    const { sweepMissed } = load();
+    const notes = [
+        { midi: 60, t: 1.0 },
+        { midi: 62, t: 2.0 },
+        { midi: 64, t: 9.0 },
+    ];
+    const hitKeys = new Set(), missedKeys = new Set();
+    const cursor = { idx: 0 };
+    assert.equal(sweepMissed(notes, 1.5, hitKeys, missedKeys, TOL, null, null, cursor), 1);
+    assert.equal(cursor.idx, 1);
+    // Stall to t=8: the 2.0 note is counted exactly once from the cursor.
+    assert.equal(sweepMissed(notes, 8.0, hitKeys, missedKeys, TOL, null, null, cursor), 1);
+    assert.equal(cursor.idx, 2);
+    // Seek BACKWARDS: the cursor does not rewind, nothing is recounted.
+    assert.equal(sweepMissed(notes, 1.5, hitKeys, missedKeys, TOL, null, null, cursor), 0);
+    // The cursor still advances past pre-floor notes without counting them.
+    const c2 = { idx: 0 };
+    const mk2 = new Set();
+    assert.equal(sweepMissed(notes, 8.0, new Set(), mk2, TOL, 5.0, null, c2), 0);
+    assert.equal(c2.idx, 2);
+});
+
+test('noteKey quantises time to ms so float drift cannot double-count', () => {
+    const { noteKey } = load();
+    assert.equal(noteKey(1.0004, 60), noteKey(1.0001, 60));
+    assert.notEqual(noteKey(1.002, 60), noteKey(1.0001, 60));
+    assert.notEqual(noteKey(1.0, 60), noteKey(1.0, 61));
+});

plugins/tuner/plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "tuner",
   "name": "Guitar/Bass Tuner",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "bundled": true,
   "private": false,
   "script": "screen.js",

plugins/tuner/routes.py

@@ -33,8 +33,6 @@ def setup(app: FastAPI, context: dict):
             "lastInstrument": DEFAULT_INSTRUMENT,
             "freeTune": False,
             "customTunings": {},
-            "disabledTunings": [],
-            "showFloatingButton": True,
             "visualizationMode": "default",
             "audioInputMode": "auto",
             "autoOpenOnTuningChange": False,
@@ -51,8 +49,6 @@ def setup(app: FastAPI, context: dict):
             res["lastInstrument"] = str(data.get("lastInstrument", DEFAULT_INSTRUMENT))
             res["freeTune"] = bool(data.get("freeTune", False))
             res["customTunings"] = data.get("customTunings", {})
-            res["disabledTunings"] = data.get("disabledTunings", [])
-            res["showFloatingButton"] = bool(data.get("showFloatingButton", True))
             res["visualizationMode"] = str(data.get("visualizationMode", "default"))
             raw_mode = str(data.get("audioInputMode", "auto"))
             res["audioInputMode"] = raw_mode if raw_mode in ("auto", "browser") else "auto"
@@ -64,8 +60,6 @@ def setup(app: FastAPI, context: dict):
 
             if not isinstance(res["customTunings"], dict):
                 res["customTunings"] = {}
-            if not isinstance(res["disabledTunings"], list):
-                res["disabledTunings"] = []
 
             # Migrate custom tunings from old flat-list format
             res["customTunings"] = {
@@ -73,12 +67,6 @@ def setup(app: FastAPI, context: dict):
                 for name, val in res["customTunings"].items()
             }
 
-            # Strip legacy disabledTunings entries that lack compound "instrument:name" format
-            res["disabledTunings"] = [
-                e for e in res["disabledTunings"]
-                if isinstance(e, str) and ":" in e
-            ]
-
             return res
         except Exception:
             return defaults
@@ -86,8 +74,10 @@ def setup(app: FastAPI, context: dict):
     def _write(data: dict) -> None:
         config_dir.mkdir(parents=True, exist_ok=True)
         current = _read()
-        # Strip keys that belong to core, not to this plugin's config.
-        for key in ("defaultTunings", "referencePitch"):
+        # Strip keys that belong to core, not to this plugin's config, plus
+        # retired keys (disabledTunings/showFloatingButton — their settings UI
+        # was removed) so a stale client can't re-persist them.
+        for key in ("defaultTunings", "referencePitch", "disabledTunings", "showFloatingButton"):
             data = {k: v for k, v in data.items() if k != key}
         current.update(data)
         config_file.write_text(json.dumps(current, indent=2), encoding="utf-8")

plugins/tuner/screen.js

@@ -42,7 +42,6 @@
         _allTunings: {},
         referencePitch: 440,
         visualizationMode: 'default',
-        showFloatingButton: true,
         currentSongOffsets: null,
         currentSongIsBass: false,
         currentSongStringCount: 0,
@@ -92,10 +91,6 @@
     }
 
     // ── Tuning helpers ────────────────────────────────────────────────
-    function _isTuningEnabled(instrument, name) {
-        return !((_state._serverConfig ? _state._serverConfig.disabledTunings : null) || []).includes(instrument + ':' + name);
-    }
-
     function _instrumentForTuning(name) {
         for (var key in _state._allTunings) {
             if (_state._allTunings[key] && _state._allTunings[key][name]) return key;
@@ -104,11 +99,7 @@
     }
 
     function _buildTuningsForInstrument(instrument) {
-        const all = _state._allTunings[instrument] || {};
-        const disabled = (_state._serverConfig ? _state._serverConfig.disabledTunings : null) || [];
-        return Object.fromEntries(
-            Object.entries(all).filter(([name]) => !disabled.includes(instrument + ':' + name))
-        );
+        return { ...(_state._allTunings[instrument] || {}) };
     }
 
     function _tuningIdentityKey(songInfo) {
@@ -554,7 +545,6 @@
             _state._serverConfig = config;
             _state._allTunings = tuningsData.tunings || {};
             _state.referencePitch = tuningsData.referencePitch || 440;
-            _state.showFloatingButton = config.showFloatingButton !== false;
             _state.visualizationMode = config.visualizationMode || 'default';
             _state.audioInputMode = config.audioInputMode || 'auto';
 

plugins/tuner/settings.html

@@ -1,15 +1,4 @@
 <div class="space-y-6 py-2">
-    <div class="flex items-center justify-between bg-dark-900/50 p-3 rounded-xl border border-gray-800/50">
-        <div>
-            <h3 class="text-sm font-medium text-gray-200">Floating Button</h3>
-            <p class="text-[11px] text-gray-500">Show the tuner button on the main interface.</p>
-        </div>
-        <label class="relative inline-flex items-center cursor-pointer">
-            <input type="checkbox" id="tuner-show-floating" class="sr-only peer" onchange="window._tunerToggleFloating(this.checked)">
-            <div class="w-9 h-5 bg-gray-700 peer-focus:outline-none rounded-full peer peer-checked:after:translate-x-full peer-checked:after:border-white after:content-[''] after:absolute after:top-[2px] after:left-[2px] after:bg-white after:border-gray-300 after:border after:rounded-full after:h-4 after:w-4 after:transition-all peer-checked:bg-accent"></div>
-        </label>
-    </div>
-
     <div class="flex items-center justify-between bg-dark-900/50 p-3 rounded-xl border border-gray-800/50">
         <div>
             <h3 class="text-sm font-medium text-gray-200">Auto-open on tuning change</h3>
@@ -38,14 +27,6 @@
     </script>
 
     <div>
-        <h3 class="text-sm font-medium text-gray-400 mb-3">Tuning Visibility</h3>
-        <p class="text-xs text-gray-500 mb-4">Toggle which built-in tunings appear in the tuner menu.</p>
-        <div id="tuner-visibility-list" class="space-y-2 pr-2">
-            <!-- Populated by JS -->
-        </div>
-    </div>
-
-    <div class="pt-4 border-t border-gray-800">
         <h3 class="text-sm font-medium text-gray-400 mb-3">Custom Tunings</h3>
         <div id="tuner-custom-list" class="space-y-2 mb-4">
             <!-- Populated by JS -->
@@ -88,16 +69,7 @@
 
     <script>
         (function() {
-            let config = { customTunings: {}, disabledTunings: [], defaultTunings: {}, showFloatingButton: true, audioInputMode: 'auto' };
-            let expandedGroups = [];
-
-            var _INSTRUMENT_CAPTIONS = {
-                "guitar-6": "Guitar",
-                "guitar-7": "Guitar 7-string",
-                "guitar-8": "Guitar 8-string",
-                "bass-4": "Bass 4-string",
-                "bass-5": "Bass 5-string"
-            };
+            let config = { customTunings: {}, audioInputMode: 'auto' };
 
             var _instrumentLabels = {
                 "guitar-6": "Guitar 6-string",
@@ -112,9 +84,6 @@
                     const resp = await fetch('/api/plugins/tuner/config');
                     config = await resp.json();
 
-                    const floatingToggle = document.getElementById('tuner-show-floating');
-                    if (floatingToggle) floatingToggle.checked = config.showFloatingButton !== false;
-
                     const browserAudioToggle = document.getElementById('tuner-force-browser-audio');
                     if (browserAudioToggle) browserAudioToggle.checked = config.audioInputMode === 'browser';
 
@@ -125,11 +94,6 @@
                 } catch (e) { console.error('Tuner settings: load failed', e); }
             }
 
-            window._tunerToggleFloating = (enabled) => {
-                config.showFloatingButton = enabled;
-                save();
-            };
-
             window._tunerToggleBrowserAudio = (forceBrowser) => {
                 config.audioInputMode = forceBrowser ? 'browser' : 'auto';
                 save();
@@ -153,115 +117,6 @@
             }
 
             function render() {
-                const visList = document.getElementById('tuner-visibility-list');
-                visList.innerHTML = '';
-
-                const defaultTunings = config.defaultTunings || {};
-
-                Object.keys(defaultTunings).forEach(groupName => {
-                    const group = defaultTunings[groupName];
-                    const groupTunings = Object.keys(group);
-                    const instrument = groupName;
-                    // Compound keys for all tunings in this group
-                    const compoundKeys = groupTunings.map(n => instrument + ':' + n);
-
-                    const groupWrapper = document.createElement('div');
-                    groupWrapper.className = 'mb-4';
-
-                    const header = document.createElement('div');
-                    header.className = 'flex items-center justify-between p-2 mt-2 bg-dark-900/80 rounded-t-lg border-x border-t border-gray-800/50 cursor-pointer hover:bg-dark-900 transition-colors';
-
-                    const left = document.createElement('div');
-                    left.className = 'flex items-center gap-2';
-
-                    const chevron = document.createElement('span');
-                    chevron.innerHTML = '<svg class="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5l7 7-7 7"/></svg>';
-                    chevron.className = 'text-gray-500 transition-transform duration-200 rotate-0';
-
-                    const groupLabel = document.createElement('span');
-                    groupLabel.className = 'text-[11px] font-bold text-gray-400 uppercase tracking-wider';
-                    groupLabel.textContent = _INSTRUMENT_CAPTIONS[groupName] || groupName;
-
-                    left.appendChild(chevron);
-                    left.appendChild(groupLabel);
-
-                    const groupToggle = document.createElement('input');
-                    groupToggle.type = 'checkbox';
-                    const allEnabled = compoundKeys.every(k => !config.disabledTunings.includes(k));
-                    const someEnabled = compoundKeys.some(k => !config.disabledTunings.includes(k));
-                    groupToggle.checked = allEnabled;
-                    groupToggle.indeterminate = someEnabled && !allEnabled;
-                    groupToggle.className = 'accent-accent';
-
-                    groupToggle.onclick = (e) => e.stopPropagation();
-                    groupToggle.onchange = () => {
-                        if (groupToggle.checked) {
-                            config.disabledTunings = config.disabledTunings.filter(k => !compoundKeys.includes(k));
-                        } else {
-                            compoundKeys.forEach(k => {
-                                if (!config.disabledTunings.includes(k)) config.disabledTunings.push(k);
-                            });
-                        }
-                        save();
-                        render();
-                    };
-
-                    header.appendChild(left);
-                    header.appendChild(groupToggle);
-                    groupWrapper.appendChild(header);
-
-                    const groupContainer = document.createElement('div');
-                    groupContainer.className = 'border-x border-b border-gray-800/50 rounded-b-lg overflow-hidden';
-
-                    const isExpanded = expandedGroups.includes(groupName);
-                    if (!isExpanded) {
-                        groupContainer.classList.add('hidden');
-                        chevron.classList.remove('rotate-90');
-                    } else {
-                        chevron.classList.add('rotate-90');
-                    }
-
-                    header.onclick = () => {
-                        const idx = expandedGroups.indexOf(groupName);
-                        if (idx === -1) {
-                            expandedGroups.push(groupName);
-                        } else {
-                            expandedGroups.splice(idx, 1);
-                        }
-                        render();
-                    };
-
-                    groupTunings.forEach((name, idx) => {
-                        const compoundKey = instrument + ':' + name;
-                        const div = document.createElement('div');
-                        div.className = `flex items-center justify-between p-2 bg-dark-800/30 hover:bg-dark-800/50 transition-colors ${idx === 0 ? 'border-t-0' : 'border-t border-gray-800/20'}`;
-
-                        const label = document.createElement('span');
-                        label.className = 'text-xs text-gray-300';
-                        label.textContent = name;
-
-                        const toggle = document.createElement('input');
-                        toggle.type = 'checkbox';
-                        toggle.checked = !config.disabledTunings.includes(compoundKey);
-                        toggle.className = 'accent-accent';
-                        toggle.onchange = () => {
-                            if (toggle.checked) {
-                                config.disabledTunings = config.disabledTunings.filter(k => k !== compoundKey);
-                            } else {
-                                if (!config.disabledTunings.includes(compoundKey)) config.disabledTunings.push(compoundKey);
-                            }
-                            save();
-                            render();
-                        };
-
-                        div.appendChild(label);
-                        div.appendChild(toggle);
-                        groupContainer.appendChild(div);
-                    });
-                    groupWrapper.appendChild(groupContainer);
-                    visList.appendChild(groupWrapper);
-                });
-
                 const customList = document.getElementById('tuner-custom-list');
                 customList.innerHTML = '';
                 const customNames = Object.keys(config.customTunings);

plugins/tuner/utils/ui.js

@@ -441,7 +441,7 @@ window._tunerUI = function(state, actions) {
         const btn = document.getElementById('tuner-toggle-btn');
         if (!btn) return;
         const isPlayer = document.querySelector('.screen.active')?.id === 'player';
-        if (!state.showFloatingButton || isPlayer || window.feedBack?.isPlaying) {
+        if (isPlayer || window.feedBack?.isPlaying) {
             btn.classList.add('hidden');
         } else {
             btn.classList.remove('hidden');
@@ -727,6 +727,33 @@ window._tunerUI = function(state, actions) {
 
         document.body.appendChild(state.uiContainer);
         state.uiContainer.addEventListener('click', (e) => e.stopPropagation());
+
+        // Re-anchor while the panel is open: the popover it hugs is
+        // vertically centered, so its rect shifts with viewport height.
+        // initUI() runs once (guarded above), so this binds a single listener.
+        window.addEventListener('resize', () => {
+            if (state.uiContainer && !state.uiContainer.classList.contains('hidden')) positionPanel();
+        });
+    }
+
+    // Resolve the sidebar Plugins popover to anchor the panel beside it.
+    // Prefer the host's stable plugin-control slot API and derive its popover
+    // container; fall back to the known popover id only if that's unavailable.
+    // Returns a visible rect, or null (→ caller uses the fixed fallback slot).
+    function _pluginsPopoverRect() {
+        let pop = null;
+        try {
+            if (window.feedBack?.ui && typeof window.feedBack.ui.playerControlSlot === 'function') {
+                const slot = window.feedBack.ui.playerControlSlot();
+                if (slot instanceof Element) pop = slot.closest('.v3-rail-pop') || slot;
+            }
+        } catch (_e) { /* host slot API failure → fall back to id lookup */ }
+        if (!pop) pop = document.getElementById('v3-rail-pop-plugins');
+        // offsetParent === null covers display:none on the element or any
+        // ancestor (more robust than testing a specific `hidden` class).
+        if (!pop || pop.offsetParent === null) return null;
+        const rect = pop.getBoundingClientRect();
+        return (rect.width || rect.height) ? rect : null;
     }
 
     function positionPanel() {
@@ -746,7 +773,20 @@ window._tunerUI = function(state, actions) {
                 .replace('right-0', '')
                 .replace('top-full', '')
                 .trim();
-            state.uiContainer.style.cssText = 'top:5rem;right:11rem';
+            const anchor = _pluginsPopoverRect();
+            if (anchor) {
+                // Anchor to the right of the Plugins popover, clamped to the
+                // viewport so the panel never opens off-screen (right/bottom)
+                // on a narrow or short window.
+                const GAP = 8, MARGIN = 8;
+                const pw = state.uiContainer.offsetWidth || 288;   // w-72
+                const ph = state.uiContainer.offsetHeight || 0;
+                const left = Math.max(MARGIN, Math.min(anchor.right + GAP, window.innerWidth - pw - MARGIN));
+                const top = Math.max(MARGIN, Math.min(anchor.top, window.innerHeight - ph - MARGIN));
+                state.uiContainer.style.cssText = `top:${top}px;left:${left}px`;
+            } else {
+                state.uiContainer.style.cssText = 'top:5rem;right:11rem';
+            }
             return;
         }
 
@@ -829,8 +869,15 @@ window._tunerUI = function(state, actions) {
         btn.textContent = 'Tuner';
         btn.title = 'Open Tuner';
         btn.onclick = window.tuner.toggle;
-        const closeBtn = isV3 ? null : controls.querySelector('button:last-child');
-        if (closeBtn) controls.insertBefore(btn, closeBtn);
+        // Anchor to the last DIRECT-child button of `controls` (the classic
+        // transport's close/exit button). A bare `button:last-child` can match
+        // a NESTED button that is not a direct child of `controls`, and
+        // `insertBefore()` then throws NotFoundError — which propagated out of
+        // the player-screen transition and aborted its render (feedBack#800).
+        // `:scope > button:last-of-type` restricts the anchor to a direct child;
+        // the parentNode check is a belt-and-suspenders guard before insertBefore.
+        const closeBtn = isV3 ? null : controls.querySelector(':scope > button:last-of-type');
+        if (closeBtn && closeBtn.parentNode === controls) controls.insertBefore(btn, closeBtn);
         else controls.appendChild(btn);
         updatePlayerButton();
     }

scripts/perf-baseline.mjs

@@ -0,0 +1,177 @@
+// Perf-baseline harness for the module-migration refactor (R0).
+//
+// Rerun this after every phase (R0 → R3c) to prove the split does not regress
+// screen-entry, frame-time, memory, or server latency. It writes a markdown
+// results block to stdout; paste it into docs/perf-baseline.md (or redirect).
+//
+// 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
+// with charts (playback frame-time, screen-entry into a live highway) are
+// clearly labelled — run those against an environment with real songs.
+
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const { chromium } = require('@playwright/test');
+
+const args = new Map();
+for (let i = 2; i < process.argv.length; i += 2) args.set(process.argv[i].replace(/^--/, ''), process.argv[i + 1]);
+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;
+    const s = [...xs].sort((a, b) => a - b);
+    return s[Math.min(s.length - 1, Math.floor((p / 100) * s.length))];
+};
+const ms = (x) => (x == null ? '—' : `${x.toFixed(1)}`);
+
+// ── Server latency: p50/p95/p99 over N requests per endpoint ──────────────────
+async function serverLatency(paths) {
+    const rows = [];
+    for (const path of paths) {
+        const t = [];
+        let status = 0;
+        for (let i = 0; i < N; i++) {
+            const t0 = performance.now();
+            try {
+                const r = await fetch(BASE + path);
+                status = r.status;
+                await r.arrayBuffer();
+            } catch { status = -1; }
+            t.push(performance.now() - t0);
+        }
+        rows.push({ path, status, p50: pct(t, 50), p95: pct(t, 95), p99: pct(t, 99) });
+    }
+    return rows;
+}
+
+// ── Client: cold boot-to-interactive + idle memory after a soak ───────────────
+async function clientMetrics() {
+    const browser = await chromium.launch();
+    const page = await browser.newPage();
+    const t0 = Date.now();
+    await page.goto(BASE, { waitUntil: 'networkidle', timeout: 60000 });
+    const bootMs = Date.now() - t0;
+
+    // performance.memory is Chromium-only; JS heap after settle.
+    const mem0 = await page.evaluate(() => (performance.memory ? performance.memory.usedJSHeapSize : null));
+    await page.waitForTimeout(SOAK_S * 1000);
+    const mem1 = await page.evaluate(() => (performance.memory ? performance.memory.usedJSHeapSize : null));
+
+    const scripts = await page.evaluate(() =>
+        document.querySelectorAll('script[data-plugin-id]').length);
+
+    await browser.close();
+    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',
+    '/api/library?limit=60',
+    '/api/library/artists',
+]);
+const client = await clientMetrics();
+
+const now = new Date().toISOString();
+let out = `\n<!-- generated by scripts/perf-baseline.mjs @ ${now} against ${BASE} (n=${N}, soak=${SOAK_S}s) -->\n\n`;
+out += `### Server latency (ms)\n\n| Endpoint | status | p50 | p95 | p99 |\n|---|---|---|---|---|\n`;
+for (const r of server) out += `| \`${r.path}\` | ${r.status} | ${ms(r.p50)} | ${ms(r.p95)} | ${ms(r.p99)} |\n`;
+out += `\n### Client\n\n| Metric | Value |\n|---|---|\n`;
+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`;
+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

@@ -1110,6 +1110,7 @@ const _LIB_VIEW_VALUES = new Set(['grid', 'tree', 'folder']);
 const _LIB_SORT_VALUES = new Set([
     'artist', 'artist-desc', 'title', 'title-desc',
     'recent', 'year-desc', 'year', 'tuning',
+    'difficulty', 'difficulty-desc',
 ]);
 const _LIB_FORMAT_VALUES = new Set(['', 'sloppak', 'loose']);
 // Tree-view expand/collapse persistence. Three states per tree:
@@ -2078,6 +2079,7 @@ function renderGridCards(songs, containerId = 'lib-grid', mode = 'replace') {
                     ${(() => { const _nm = _getArrangementNamingMode(); return (song.arrangements || []).map(a => _arrangementBadgeHtml(a, _nm)).join(''); })()}
                     ${tuning ? `<span class="px-1.5 py-0.5 rounded ${tuning === 'E Standard' ? 'bg-green-900/30 text-green-400' : 'bg-yellow-900/30 text-yellow-400'}">${esc(tuning)}</span>` : ''}
                     ${song.has_lyrics ? `<span class="px-1.5 py-0.5 bg-purple-900/30 rounded text-purple-300">Lyrics</span>` : ''}
+                    ${song.user_difficulty != null ? `<span class="px-1.5 py-0.5 bg-blue-900/30 rounded text-blue-300" title="Your difficulty rating">◆${esc(song.user_difficulty)}</span>` : ''}
                     ${duration ? `<span class="text-gray-600">${duration}</span>` : ''}
                 </div>
                 ${retuneBtn}
@@ -2277,6 +2279,8 @@ async function renderTreeInto(containerId, countId, stats, letter, q, favoritesO
                     html += `<span class="px-1.5 py-0.5 rounded ${tuning === 'E Standard' ? 'bg-green-900/30 text-green-400' : 'bg-yellow-900/30 text-yellow-400'}">${esc(tuning)}</span>`;
                 if (song.has_lyrics)
                     html += `<span class="px-1.5 py-0.5 bg-purple-900/30 rounded text-purple-300">Lyrics</span>`;
+                if (song.user_difficulty != null)
+                    html += `<span class="px-1.5 py-0.5 bg-blue-900/30 rounded text-blue-300" title="Your difficulty rating">◆${esc(song.user_difficulty)}</span>`;
                 if (duration)
                     html += `<span class="text-gray-600 w-10 text-right">${duration}</span>`;
                 if (stdRetune)
@@ -2758,6 +2762,12 @@ function goFavTreePage(p) {
 // ── Settings ─────────────────────────────────────────────────────────────
 let _defaultArrangement = '';
 
+const INSTRUMENT_PATHWAYS = ['songs', 'practice', 'learn', 'studio'];
+
+function _normalizeInstrumentPathway(value) {
+    return INSTRUMENT_PATHWAYS.includes(value) ? value : 'songs';
+}
+
 function _syncDefaultArrangementSelect(value) {
     const sel = document.getElementById('default-arrangement');
     if (!sel) return;
@@ -2864,6 +2874,10 @@ const HWC_DEFAULT_FALLBACK = { lowE: '#cc0000', A: '#cca800', D: '#0066cc', G: '
 //   - colorblind: the Okabe–Ito accessible qualitative palette (vermillion,
 //     orange, yellow, bluish-green, sky-blue, blue, reddish-purple), the most
 //     distinguishable option for deuteranopia/protanopia.
+//   - colorblind_deuteranope: a deuteranope-tuned variant of the Okabe–Ito set
+//     above, contributed by a deuteranopic player who still found that set hard
+//     to separate. Retunes the six main strings (red / yellow-green / blue /
+//     orange / teal / deep-purple) and keeps its 7/8-string colors unchanged.
 //   - neon: electric, max-saturation hues whose LIGHTNESS deliberately zig-zags
 //     between neighbours (bright→bright→brightest→dark blue→bright green→dark
 //     violet) so adjacent strings separate harder than vivid — a stage/stream
@@ -2900,6 +2914,10 @@ const HWC_PRESETS = [
         id: 'colorblind', label: 'Colorblind-friendly',
         colors: { lowE: '#d55e00', A: '#e69f00', D: '#f0e442', G: '#009e73', B: '#56b4e9', highE: '#cc79a7', low7: '#0072b2', low8: '#999999' },
     },
+    {
+        id: 'colorblind_deuteranope', label: 'Colorblind (deuteranope)',
+        colors: { lowE: '#aa1414', A: '#88de00', D: '#1889e3', G: '#c6601c', B: '#00f5b2', highE: '#4d2173', low7: '#0072b2', low8: '#999999' },
+    },
     {
         id: 'neon', label: 'Neon',
         colors: { lowE: '#ff1f4e', A: '#ff9d00', D: '#e9ff00', G: '#1844ff', B: '#00ff84', highE: '#d000ff', low7: '#ff00aa', low8: '#00f0ff' },
@@ -3410,6 +3428,8 @@ async function loadSettings() {
     if (dlcEl) dlcEl.value = data.dlc_dir || '';
     _defaultArrangement = data.default_arrangement || '';
     _syncDefaultArrangementSelect(_defaultArrangement);
+    const pathwayEl = document.getElementById('setting-instrument-pathway');
+    if (pathwayEl) pathwayEl.value = _normalizeInstrumentPathway(data.pathway);
     const demucsEl = document.getElementById('demucs-server-url');
     if (demucsEl) demucsEl.value = data.demucs_server_url || '';
     const leftyEl = document.getElementById('setting-lefty');
@@ -3901,6 +3921,18 @@ function persistSetting(key, value) {
     _settingSaveChain = next.catch(() => {});
     return next;
 }
+function setInstrumentPathway(value) {
+    const pathway = _normalizeInstrumentPathway(value);
+    const el = document.getElementById('setting-instrument-pathway');
+    if (el) el.value = pathway;
+    persistSetting('pathway', pathway).then(() => {
+        if (window.v3Badges && typeof window.v3Badges.reload === 'function') {
+            try { window.v3Badges.reload(); } catch (_) { /* noop */ }
+        }
+    });
+}
+
+
 async function _postSetting(key, value) {
     const status = document.getElementById('settings-status');
     try {
@@ -4351,7 +4383,7 @@ async function uploadSongs(fileList) {
         if (lower.endsWith('.feedpak') || lower.endsWith('.sloppak')) {
             files.push(f);
         } else {
-            failures.push(`${f.name}: only .feedpak accepted`);
+            failures.push(`${f.name}: only .feedpak or .sloppak accepted`);
         }
     }
     if (files.length === 0) {
@@ -4832,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,
@@ -4872,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) {
@@ -5091,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.
@@ -5110,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
@@ -5131,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) {
@@ -5165,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
@@ -5536,9 +5881,24 @@ function _playbackApi() {
         : null;
 }
 
+// Bridge hits are a "this legacy surface is still in use" signal, not a call
+// counter — but recordBridgeHit is not cheap (compat-shim bookkeeping, a
+// playback:bridge-hit event, and a diagnostics snapshot rebuild per call).
+// Plugins legitimately poll read surfaces like window.feedBack.getLoop() from
+// HUD ticks (note_detect polled at ~30 Hz), which turned every tick into a
+// snapshot serialization on the main thread and saturated the inspector's
+// hitCount. Throttle per surface: the first call records immediately, repeats
+// within the window are dropped.
+const _bridgeRecordLast = new Map();
+const _BRIDGE_RECORD_MIN_MS = 5000;
 function _recordPlaybackBridge(bridgeId, legacySurface, reason) {
     const playback = _playbackApi();
     if (!playback || typeof playback.recordBridgeHit !== 'function') return;
+    const key = `${bridgeId}|${legacySurface}`;
+    const now = Date.now();
+    const last = _bridgeRecordLast.get(key);
+    if (last != null && now - last < _BRIDGE_RECORD_MIN_MS) return;
+    _bridgeRecordLast.set(key, now);
     playback.recordBridgeHit({
         bridgeId,
         legacySurface,
@@ -6195,7 +6555,7 @@ window.feedBack.on('song:ready', () => {
             setSpeed(pend.speed);
         }
     } catch (_) { /* speed restore is best-effort */ }
-    Promise.resolve(_audioSeek(Math.max(0, Number(pend.position) || 0), 'resume'))
+    Promise.resolve(_audioSeek(Math.max(0, Number(pend.position) || 0), 'session-resume'))
         .then(() => { if (_autoplayExitEnabled() && !isPlaying) return togglePlay(); })
         .catch((err) => console.warn('[app] resume failed:', err));
 });
@@ -6278,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 {
@@ -6761,7 +7123,16 @@ window.feedBack.playQueue = (function () {
         if (!files.length) return false;
         list = files.slice(); idx = 0;
         source = (opts && opts.source) || '';
-        arrangements = (opts && opts.arrangements) || null;
+        arrangements = (opts && opts.arrangements) ? opts.arrangements.slice() : null;
+        if (opts && opts.shuffle && list.length > 1) {
+            // Fisher-Yates, once at start. Swap arrangements in lockstep so an
+            // album slot's pinned arrangement stays glued to its file (#685).
+            for (let i = list.length - 1; i > 0; i--) {
+                const j = Math.floor(Math.random() * (i + 1));
+                [list[i], list[j]] = [list[j], list[i]];
+                if (arrangements) [arrangements[i], arrangements[j]] = [arrangements[j], arrangements[i]];
+            }
+        }
         if (window.fbNotify) {
             try { window.fbNotify.show({ title: 'Playing ' + (source || 'queue'), message: files.length + ' songs', icon: '▶' }); } catch (e) { /* */ }
         }
@@ -6778,6 +7149,14 @@ window.feedBack.playQueue = (function () {
         start: start, advance: advance, hasNext: hasNext, active: active, clear: clear,
         source: function () { return source; },
         remaining: function () { return active() ? list.length - idx - 1 : 0; },
+        // What's coming, for consumers that RENDER the queue (a results
+        // screen's "Up next: … starting in 10s" strip) without reaching into
+        // queue internals. Null when nothing follows.
+        peekNext: function () {
+            return hasNext()
+                ? { filename: list[idx + 1], index: idx + 1, total: list.length }
+                : null;
+        },
     };
 })();
 
@@ -7895,6 +8274,10 @@ function setLoopEnd() {
     if (loopB <= loopA) { loopB = null; return; }
     document.getElementById('btn-loop-b').className = 'px-3 py-1.5 bg-green-900/50 rounded-lg text-xs text-green-300 transition';
     updateLoopUI();
+    // Manual A/B arming is a loop mutation like setLoop()'s — emit the same
+    // transport event so event-driven consumers (note_detect drill sync) see
+    // button-armed loops without having to poll getLoop().
+    window.feedBack?.playback?.transportEvent?.('loop-set', { requesterId: 'core.loop', loopA, loopB, loop: { startTime: loopA, endTime: loopB, enabled: true, state: 'active' } });
 }
 
 function clearLoop(options) {
@@ -8055,6 +8438,26 @@ function _resolveEditRegion() {
     return { a: Math.max(0, t - 4), b: t + 4 };
 }
 
+/* @pure:editor-pending-view:start */
+function _buildEditorPendingViewPure(filename, arrangement, region, opts) {
+    const options = opts || {};
+    const view = {
+        filename,
+        arrangement: Number.isFinite(arrangement) && arrangement >= 0 ? arrangement : 0,
+        barSel: region ? { startTime: region.a, endTime: region.b } : null,
+    };
+    if (options.returnToHighway) view.returnToHighway = true;
+    if (typeof options.cursorTime === 'number') {
+        view.cursorTime = options.cursorTime;
+    } else if (region && typeof region.a === 'number') {
+        view.cursorTime = region.a;
+    }
+    if (typeof options.scrollX === 'number') view.scrollX = Math.max(0, options.scrollX);
+    if (typeof options.zoom === 'number' && options.zoom > 0) view.zoom = options.zoom;
+    return view;
+}
+/* @pure:editor-pending-view:end */
+
 // Enable "Edit region" whenever the editor plugin is present and a song is
 // loaded; show "↩ Editor" only while a return context is pending.
 function _updateEditRegionBtn() {
@@ -8081,12 +8484,9 @@ function editRegionInEditor() {
             arrangement = si.arrangement_index;
         }
     } catch (_) { /* default to 0 */ }
-    window._editorPendingView = {
-        filename: currentFilename,
-        arrangement,
-        barSel: { startTime: region.a, endTime: region.b },
+    window._editorPendingView = _buildEditorPendingViewPure(currentFilename, arrangement, region, {
         returnToHighway: true,
-    };
+    });
     window.editSong(currentFilename);
 }
 window.editRegionInEditor = editRegionInEditor;
@@ -8098,14 +8498,14 @@ function returnToEditorFromHighway() {
     const ctx = window._highwayReturnCtx;
     if (!ctx || typeof window.editSong !== 'function') return;
     window._highwayReturnCtx = null;
-    window._editorPendingView = {
-        filename: ctx.filename,
-        arrangement: ctx.arrangement,
+    const region = ctx.barSel
+        ? { a: ctx.barSel.startTime, b: ctx.barSel.endTime }
+        : null;
+    window._editorPendingView = _buildEditorPendingViewPure(ctx.filename, ctx.arrangement, region, {
         scrollX: ctx.scrollX,
         zoom: ctx.zoom,
         cursorTime: ctx.cursorTime,
-        barSel: ctx.barSel,
-    };
+    });
     window.editSong(ctx.filename);
 }
 window.returnToEditorFromHighway = returnToEditorFromHighway;
@@ -8783,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;
@@ -10960,20 +11360,19 @@ async function loadPlugins() {
             const nameDelta = String(a.name || a.id || '').localeCompare(String(b.name || b.id || ''));
             return nameDelta || String(a.id || '').localeCompare(String(b.id || ''));
         });
-        const livePluginIds = new Set(plugins.map((plugin) => plugin.id));
-        for (const [pluginId, contributions] of _pluginUiContributions) {
-            if (livePluginIds.has(pluginId)) continue;
-            const stalePlugin = { id: pluginId };
-            for (const contribution of contributions) {
-                await _commandUiDomain(contribution.domain, 'unmount', stalePlugin, contribution);
-            }
-            try {
-                window.feedBack?.capabilities?.unregisterParticipant?.(pluginId);
-            } catch (e) {
-                console.warn(`capability participant unregister failed for ${pluginId}:`, e);
-            }
-            _pluginUiContributions.delete(pluginId);
-        }
+        // NOTE deliberately NO stale-contribution sweep for plugins absent
+        // from this response. Absent ≠ uninstalled: the backend clears its
+        // plugin registry at the start of load_plugins() and repopulates it
+        // incrementally while HTTP stays up, so every backend restart serves a
+        // window of partial (even empty) responses. The old sweep unmounted UI
+        // contributions and unregistered capability participants on mere
+        // absence, permanently breaking still-loaded plugins — their scripts
+        // don't re-run (loadedScripts guard below), so nothing ever
+        // re-registered. A genuine mid-session uninstall now leaves the
+        // (already-evaluated, un-unloadable) script's contributions in place
+        // until reload; its nav entry still disappears because nav is rebuilt
+        // from the response each round. Same invariant as the settings/screen
+        // DOM wipe and _reconcilePluginStyles below.
         console.log('[feedBack] loadPlugins: got', plugins.length, 'plugins');
 
         try {
@@ -11115,17 +11514,23 @@ async function loadPlugins() {
             loadedStyles.set(plugin.id, wantedVersion);
         };
         const _reconcilePluginStyles = (currentPlugins) => {
-            // Drop stylesheets for plugins that vanished from /api/plugins or are
-            // no longer ready+styled this round. _injectPluginStyles below only
-            // visits plugins still returned by the API, so an uninstalled or
-            // newly-not-ready plugin would otherwise keep its <link> applying.
+            // Drop stylesheets for plugins the response KNOWS about but that
+            // are no longer ready+styled this round. _injectPluginStyles below
+            // only visits plugins still returned by the API, so a newly-not-
+            // ready or unstyled plugin would otherwise keep its <link>
+            // applying. Plugins merely ABSENT from the response keep their
+            // stylesheet — a transient partial response during a backend
+            // restart is not an uninstall (same invariant as the screen/
+            // settings wipe below), and stripping the <link> would leave a
+            // still-loaded plugin visible but unstyled.
+            const responded = new Set(currentPlugins.map((p) => p.id));
             const styled = new Set(
                 currentPlugins
                     .filter((p) => (p.status || 'ready') === 'ready' && p.has_styles && p.styles)
                     .map((p) => p.id),
             );
             for (const id of Array.from(loadedStyles.keys())) {
-                if (!styled.has(id)) {
+                if (responded.has(id) && !styled.has(id)) {
                     _removePluginStyleTags(id);
                     loadedStyles.delete(id);
                 }
@@ -11138,6 +11543,18 @@ async function loadPlugins() {
                 if (pid) existingSettingsByPluginId.set(pid, child);
             }
         }
+        // Plugins named in THIS response. A plugin can be transiently absent
+        // from /api/plugins — the backend clears its registry at the start of
+        // load_plugins() and repopulates it incrementally while HTTP stays up,
+        // so every backend restart serves a window of partial (even empty)
+        // responses. The wipe loops below must never treat that absence as an
+        // uninstall: stripping a still-loaded plugin's DOM while keeping its
+        // loadedScripts entry made the NEXT refetch fail the DOM check and
+        // re-evaluate its screen.js mid-session — which duplicated the desktop
+        // audio_engine's native signal chain (its init re-ran against the
+        // surviving engine chain). Absent plugins keep their DOM and script;
+        // they're re-reconciled when they reappear in a later response.
+        const respondedIds = new Set(plugins.map((p) => p.id));
         const alreadyHydrated = new Set();
         for (const p of plugins) {
             if (!p.has_script) continue;
@@ -11165,7 +11582,10 @@ async function loadPlugins() {
         for (const container of _pluginSettingsContainers()) {
             [...container.children].forEach((el) => {
                 const pid = el.dataset ? el.dataset.pluginId : null;
-                if (!pid || !alreadyHydrated.has(pid)) el.remove();
+                // Remove junk (no plugin id) and plugins the response KNOWS
+                // about but that failed hydration; leave plugins absent from
+                // the response untouched (see respondedIds above).
+                if (!pid || (respondedIds.has(pid) && !alreadyHydrated.has(pid))) el.remove();
             });
         }
         document.querySelectorAll('.screen[id^="plugin-"]').forEach((el) => {
@@ -11174,7 +11594,7 @@ async function loadPlugins() {
             // change shipped — both forms strip a single leading "plugin-".
             const pid = (el.dataset && el.dataset.pluginId)
                 || el.id.replace(/^plugin-/, '');
-            if (!alreadyHydrated.has(pid)) el.remove();
+            if (!pid || (respondedIds.has(pid) && !alreadyHydrated.has(pid))) el.remove();
         });
 
         // Plugin settings area hosts both "Plugin Updates" and per-plugin
@@ -11462,6 +11882,14 @@ async function loadPlugins() {
                         // URL ?v=mtime convention elsewhere in this file).
                         const v = encodeURIComponent(wantedVersion);
                         script.src = `/api/plugins/${plugin.id}/screen.js${v ? `?v=${v}` : ''}`;
+                        // Module-migration (R0): a migrated plugin declares
+                        // scriptType:"module" and its screen.js is `import
+                        // './src/main.js'`. A <script type="module"> fires load
+                        // only after its whole static-import graph evaluates, so
+                        // the await-onload completion + _loadingPluginId contract
+                        // below is preserved (a classic-IIFE dynamic import()
+                        // would not). Classic plugins are unaffected.
+                        if (plugin.script_type === 'module') script.type = 'module';
                         script.dataset.pluginId = plugin.id;
                         script.dataset.pluginVersion = wantedVersion;
                         window.feedBack._loadingPluginId = plugin.id;
@@ -11737,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);