Added command timeouts for refresh-providers and sync-song

Host enablement for the plugin ES-module migration: sandboxed /api/plugins/{id}/src/ serving, no-cache+weak-ETag/304 live-edit caching on src/+screen.js+assets, scriptType:module loader injection + scriptType/minHost manifest passthrough; constitution v1.2.0 + module playbook + signed size-exemptions register + maintainer/CI-only ESLint gate; rerunnable perf-baseline harness. Reviewed by Codex (local), Copilot, and CodeRabbit.

.github/workflows/ci.yml

@@ -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

.specify/memory/constitution.md

@@ -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.2.0 | **Ratified**: 2026-05-09 | **Last Amended**: 2026-07-08

CHANGELOG.md

@@ -7,10 +7,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### 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.

CLAUDE.md

@@ -90,7 +90,7 @@ Best practices:
 - `extract_meta()` — metadata extraction callable
 - `meta_db` — shared MetadataDB instance
 - `library_providers` — shared library provider registry for source-aware browsing
-- `register_library_provider(provider)` — register a plugin-provided library source. Providers expose `id`, `label`, optional `kind`/`capabilities`, and callable `query_page`, `query_artists`, `query_stats`, and `tuning_names` methods. Providers with `art.read` may also expose `get_art(song_id)` returning one of: a `Response` object (any media type, served as-is); raw `bytes` or `bytearray` (**assumed PNG** — use a `Response` or a `dict` with `content`+`media_type` keys for JPEG/WebP or other formats); a URL string (http/https → 302 redirect; other schemes are rejected with 400); a filesystem path string or `Path` (served as a file with auto-detected media type); or a `dict` with a `url`, `path`, or `content` key. Providers with `song.sync` may expose `sync_song(song_id)` returning `None` (success with no local file) or a `dict` — the dict is passed through as the JSON response and should include `filename`/`local_filename` if a local playable file was produced.
+- `register_library_provider(provider)` — register a plugin-provided library source. Providers expose `id`, `label`, optional `kind`/`capabilities`, optional `slow: true` (or `is_slow`/`slow_mode`) when responses may take a while, and callable `query_page`, `query_artists`, `query_stats`, and `tuning_names` methods. Providers with `art.read` may also expose `get_art(song_id)` returning one of: a `Response` object (any media type, served as-is); raw `bytes` or `bytearray` (**assumed PNG** — use a `Response` or a `dict` with `content`+`media_type` keys for JPEG/WebP or other formats); a URL string (http/https → 302 redirect; other schemes are rejected with 400); a filesystem path string or `Path` (served as a file with auto-detected media type); or a `dict` with a `url`, `path`, or `content` key. Providers with `song.sync` may expose `sync_song(song_id)` returning `None` (success with no local file) or a `dict` — the dict is passed through as the JSON response and should include `filename`/`local_filename` if a local playable file was produced.
 - `unregister_library_provider(provider_id)` — remove a plugin-provided library source by id. The built-in `local` provider cannot be removed.
 - `get_sloppak_cache_dir()` — sloppak cache path
 - `load_sibling(name)` — loads a sibling module from this plugin's directory under a unique, namespaced module name. See "Sibling imports" below.
@@ -117,6 +117,8 @@ 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
@@ -583,12 +585,13 @@ a local pointer + code map.
 pytest                         # Run all tests
 pytest tests/test_song.py -v   # Specific file
 pytest -k "round_trip" -v      # Pattern match
+uv run pytest                  # Run through the locked local uv environment
 ```
 
 - Framework: pytest
 - Config: `pyproject.toml` sets `pythonpath = [".", "lib"]` and `testpaths = ["tests"]`
 - CI: GitHub Actions runs pytest on push/PR to main (Python 3.12)
-- Test dependencies: `requirements-test.txt`
+- Test dependencies: `requirements-test.txt`; uv reads the mirrored `test` dependency group in `pyproject.toml`
 
 ## Tuning the note_detect plugin
 

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/capability-recipes.md

@@ -80,6 +80,8 @@ A plugin that only reads public events should declare `observer` and no command
 
 A plugin that registers a remote client or generated library source declares itself as a `library` provider. The backend registration call is still made from `routes.py` with `context["register_library_provider"](...)`; the native browser library capability turns the provider registry into runtime provider participants. A thin server wrapper that only exposes the local library over HTTP should not declare `library` as a provider unless it also registers a provider in the library registry.
 
+Provider objects may set `slow: true` when their backing connection can take a while to answer. Core exposes that flag through `/api/library/providers` and the browser library capability so library views show explicit loading indicators instead of looking idle during the wait.
+
 ```json
 {
   "id": "remote_library_client",

docs/perf-baseline.md

@@ -0,0 +1,67 @@
+# 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
+
+### 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/size-exemptions.md

@@ -0,0 +1,62 @@
+# 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,821) · `static/highway.js` (4,154, whole file) · `server.py`
+(13,948) · `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/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/gp2rs.py

@@ -1836,9 +1836,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 +1895,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 +1958,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])
@@ -1498,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

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

@@ -39,6 +39,14 @@ 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,
@@ -136,12 +144,31 @@ def _duration_int(v):
         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 = similarity(song.get("artist"), cand.get("artist"), artist=True)
+    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"))
@@ -154,6 +181,10 @@ def score_candidate(song: dict, cand: dict) -> float:
             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)
 
 
@@ -168,7 +199,7 @@ def classify(song: dict, cand: dict, score: float, auto_min: float | None = None
     """
     if auto_min is None:
         auto_min = AUTO_MIN
-    artist_sim = similarity(song.get("artist"), cand.get("artist"), artist=True)
+    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):
@@ -179,15 +210,34 @@ def classify(song: dict, cand: dict, score: float, auto_min: float | None = None
 
 
 def rank_candidates(song: dict, candidates: list[dict]) -> list[dict]:
-    """Score every candidate against the song and return them sorted by our
-    score (MusicBrainz's own search score is only a tiebreak). Each returned
-    dict is a copy carrying `score` (rounded — it's displayed and stored)."""
+    """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"], c.get("mb_score") or 0), reverse=True)
+    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
 
 
@@ -198,18 +248,63 @@ def _lucene_escape_phrase(s: str) -> str:
     return s.replace("\\", "\\\\").replace('"', '\\"')
 
 
-def build_recording_query(artist, title) -> str:
+# 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."""
+    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))
-    return " AND ".join(parts)
+    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]:
@@ -226,19 +321,33 @@ def _artist_credit(doc: dict) -> tuple[str, str, str]:
     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 Official status and
-    an Album release-group, then the earliest date. Returns {} if none."""
+    """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):
-        status_ok = 0 if str(r.get("status", "")).lower() == "official" else 1
         rg = r.get("release-group") or {}
-        album_ok = 0 if str(rg.get("primary-type", "")).lower() == "album" else 1
+        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")
-        return (status_ok, album_ok, date)
+        # 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]
 
@@ -261,6 +370,7 @@ def parse_recording_doc(doc: dict) -> dict | None:
         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
@@ -281,6 +391,7 @@ def parse_recording_doc(doc: dict) -> dict | None:
         "isrc": isrcs[0] if isrcs else "",
         "genres": _genres(doc),
         "mb_score": int(doc.get("score") or 0),
+        "studio": studio,
     }
 
 

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/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/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)

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/highway_3d/plugin.json

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

plugins/highway_3d/screen.js

@@ -3747,6 +3747,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
@@ -6526,6 +6535,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');
@@ -14829,6 +14858,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
@@ -15154,6 +15192,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/README.md

@@ -3,12 +3,34 @@
 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 colours** (Synthesia convention — C red, D yellow, E blue, …) with hand (rh/lh) as a secondary brightness cue.
+- 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 colour, ~400 ms).
+- **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() }`.

plugins/keys_highway_3d/plugin.json

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

plugins/keys_highway_3d/screen.js

@@ -9,7 +9,7 @@
 //
 // Visual contract is the frame analysis on slopsmith#824 (RS+ reference):
 // 3D perspective highway to a vanishing point, notes landing on a real 3D
-// keyboard, per-key Synthesia-style PITCH-CLASS colours (hand is only a
+// keyboard, per-key Synthesia-style PITCH-CLASS colors (hand is only a
 // secondary brightness cue), active-range key highlighting with letters,
 // a glowing hit-line, bevelled cuboid notes sized by durSec, floating bar
 // numbers, and key-depress + flame feedback driven by the LIVE MIDI input
@@ -59,7 +59,7 @@
     // World scroll speed (units / second) — matches the sibling highways.
     const TS = 130 * K;
 
-    // Per-pitch-class colours (Synthesia convention observed in the RS+
+    // Per-pitch-class colors (Synthesia convention observed in the RS+
     // reference frames: C=red, D=yellow, E=blue, F=light blue-grey, …).
     // Index = midi % 12 (C, C#, D, …, B). Sharps take a dimmed blend of
     // their neighbours so black-key notes stay distinguishable.
@@ -79,10 +79,196 @@
     ];
 
     // Hand cue is SECONDARY (slopsmith#824 design call): right hand renders
-    // at full brightness, left hand slightly darkened — colour stays the
+    // at full brightness, left hand slightly darkened — color stays the
     // pitch class.
     const HAND_BRIGHTNESS = { rh: 1.0, lh: 0.72 };
 
+    // Selectable note-color palettes. Index = midi % 12, same contract as
+    // PITCH_CLASS_COLORS — which stays byte-identical as the 'classic'
+    // entry, so anyone who never touches the setting sees the stock look.
+    // Two palette families:
+    //   per-pitch  — every pitch class gets its own hue (classic/vivid/pastel)
+    //   two-tone   — naturals share one hue, sharps a darker shade of it, so
+    //                a dark gem always telegraphs "black key coming"
+    //                (emerald/ice)
+    const NOTE_PALETTES = {
+        classic: PITCH_CLASS_COLORS,
+        emerald: [
+            0x3fe25f, // C  — bright green (naturals)
+            0x17863a, // C# — dark green (sharps)
+            0x3fe25f, // D
+            0x17863a, // D#
+            0x3fe25f, // E
+            0x3fe25f, // F
+            0x17863a, // F#
+            0x3fe25f, // G
+            0x17863a, // G#
+            0x3fe25f, // A
+            0x17863a, // A#
+            0x3fe25f, // B
+        ],
+        vivid: [
+            0xff2020, // C
+            0xd45a10, // C#
+            0xffe000, // D
+            0xb8c010, // D#
+            0x1e6aff, // E
+            0x9fd0e8, // F
+            0x2fae7e, // F#
+            0x20e050, // G
+            0xa89a20, // G#
+            0xff8a00, // A
+            0xd05888, // A#
+            0xd040ff, // B
+        ],
+        pastel: [
+            0xff9a9a, // C
+            0xd0a078, // C#
+            0xffe9a0, // D
+            0xcfd08a, // D#
+            0x9ec0ff, // E
+            0xc8dde8, // F
+            0x9ecfba, // F#
+            0x9fe8b0, // G
+            0xcfc79a, // G#
+            0xffc890, // A
+            0xd8a8ba, // A#
+            0xe0b0ff, // B
+        ],
+        ice: [
+            0x58c8ff, // C  — bright ice blue (naturals)
+            0x2a6a9a, // C# — deep blue (sharps)
+            0x58c8ff, // D
+            0x2a6a9a, // D#
+            0x58c8ff, // E
+            0x58c8ff, // F
+            0x2a6a9a, // F#
+            0x58c8ff, // G
+            0x2a6a9a, // G#
+            0x58c8ff, // A
+            0x2a6a9a, // A#
+            0x58c8ff, // B
+        ],
+    };
+
+    // Octave-based color scheme ('octaves'): every octave gets a distinct
+    // hue that steps like a rainbow (clear, uniform sections — NOT a smooth
+    // blend — so each octave is uniquely identifiable, but neighbouring
+    // octaves stay close so the change isn't jarring). Loops if a song runs
+    // past the table. Within an octave, sharps/flats take a darker shade of
+    // the same hue — the same two-tone idea as 'emerald'. Octave index =
+    // floor(midi/12) - 1 (so C1..B1 = octave 1). The three keys below C1
+    // (A0/A#0/B0 = octave 0) and anything lower get a distinct cool slate so
+    // the very bottom of the board reads apart from the red start.
+    const OCTAVE_HUES = [
+        0xe23a3a, // oct 1 (C1–B1)  red
+        0xe2803a, // oct 2          orange
+        0xe0c73a, // oct 3          yellow
+        0x5fc23a, // oct 4          green
+        0x3ac2a0, // oct 5          teal
+        0x3a86e2, // oct 6          blue
+        0x6a4ae2, // oct 7          indigo
+        0xc23ae2, // oct 8 (C8)     magenta
+    ];
+    const OCTAVE_SUBC1_HUE = 0x8090a0;  // A0/A#0/B0 and below — cool slate
+    const OCTAVE_SHARP_DARKEN = 0.5;    // sharps render at 50% of the octave hue
+    function _darkenHex(hex, f) {
+        const r = Math.round(((hex >> 16) & 0xff) * f);
+        const g = Math.round(((hex >> 8) & 0xff) * f);
+        const b = Math.round((hex & 0xff) * f);
+        return (r << 16) | (g << 8) | b;
+    }
+    function _isBlackPc(midi) {
+        return [1, 3, 6, 8, 10].indexOf(((midi % 12) + 12) % 12) !== -1;
+    }
+    // Which way a sharp leans to even out the naturals: toward the EDGE
+    // natural next to it. +1 = up (toward the higher natural), −1 = down, 0 =
+    // centred. C#/F# sit below an inner natural so they lean down to C/F;
+    // D#/A# lean up to E/B; G# has an inner natural on both sides, so it can't
+    // lean and stays put.
+    function _sharpLeanDir(pc) {
+        if (pc === 1 || pc === 6) return -1;   // C#, F#
+        if (pc === 3 || pc === 10) return 1;   // D#, A#
+        return 0;                              // G#
+    }
+    // Floor span [left,right] of a key's lane in the FLAT (piano-shaped)
+    // layout, in world units, given the key's centre x (`cx`). Pure/isolated
+    // on purpose — this ONE function defines the layout, so a variant is a
+    // one-function swap. Zero-overlap tiling: a white lane is trimmed by
+    // `sharpHalf` wherever it meets a sharp, and the sharp fills that gap. Each
+    // sharp is nudged `shift` toward the edge natural beside it (see
+    // _sharpLeanDir), which steals a sliver from that edge natural and widens
+    // the squeezed inner natural — at shift = sharpHalf/3 the C-D-E-F-B
+    // naturals come out equal. Lanes still tile edge-to-edge (no overlap, no
+    // gap). With `gaps`, each B→C octave boundary opens an extra `octGap`
+    // divider by shaving half of it off the B and the C (naturals only).
+    // `range`, when given, gates the trim to a neighbouring sharp that is
+    // itself inside `range.activeLow..range.activeHigh`. A white key at the
+    // active-range boundary (see the `midi < range.activeLow ||
+    // midi > range.activeHigh` skip around the lane-strip loop) may sit next
+    // to a sharp pitch-class that falls just outside the active range — that
+    // sharp's lane is never drawn, so trimming the white key's edge for it
+    // leaves a dark, unfilled sliver. Gating on range keeps that edge full
+    // while leaving the normal (fully in-range) zero-overlap tiling intact.
+    // Callers that don't pass `range` (e.g. the unit tests exercising raw
+    // tiling geometry) keep the unconditional trim.
+    function laneSpanFlat(midi, black, cx, dims, gaps, range) {
+        const { whiteW, sharpHalf, shift, octGap } = dims;
+        if (black) {
+            const c = cx + _sharpLeanDir(((midi % 12) + 12) % 12) * shift;
+            return { left: c - sharpHalf, right: c + sharpHalf };
+        }
+        const neighborActive = (m) => !range || (m >= range.activeLow && m <= range.activeHigh);
+        // White: each side that meets a sharp is trimmed to that (leaned) sharp's
+        // near edge; a side that meets another white keeps the half-slot edge.
+        let left = cx - whiteW / 2;
+        let right = cx + whiteW / 2;
+        if (_isBlackPc(midi - 1) && neighborActive(midi - 1)) {
+            const bc = (cx - whiteW / 2) + _sharpLeanDir(((midi - 1) % 12 + 12) % 12) * shift;
+            left = bc + sharpHalf;
+        }
+        if (_isBlackPc(midi + 1) && neighborActive(midi + 1)) {
+            const bc = (cx + whiteW / 2) + _sharpLeanDir(((midi + 1) % 12 + 12) % 12) * shift;
+            right = bc - sharpHalf;
+        }
+        const pc = ((midi % 12) + 12) % 12;
+        if (gaps) {
+            if (pc === 11) right -= octGap / 2; // B: gap on its right (→ C)
+            if (pc === 0) left += octGap / 2;   // C: gap on its left (← B)
+        }
+        return { left, right };
+    }
+    // 'realistic' layout span: every bar sized to the physical key it lands on.
+    // Naturals are the same full width (2·natHalf) centred on the key; sharps are
+    // the full black-key width (2·sharpHalf) at their standard half-slot, which
+    // makes them overlap — the caller draws sharps on top. A natural therefore
+    // always renders full and is only covered where a sharp note actually
+    // coincides in time. `gaps` widens the B→C divider (naturals only).
+    function laneSpanReal(midi, black, cx, dims, gaps) {
+        const half = black ? dims.sharpHalf : dims.natHalf;
+        let left = cx - half, right = cx + half;
+        if (gaps && !black) {
+            const pc = ((midi % 12) + 12) % 12;
+            if (pc === 11) right -= dims.octGap / 2;
+            if (pc === 0) left += dims.octGap / 2;
+        }
+        return { left, right };
+    }
+    // Color (24-bit int) for a midi note under the octave scheme: hue by
+    // octave, darker for sharps. Pure (no THREE) so it is unit-testable.
+    function octaveNoteColor(midi) {
+        const oct = Math.floor(midi / 12) - 1;      // C1..B1 => 1
+        let hex = (oct <= 0)
+            ? OCTAVE_SUBC1_HUE
+            : OCTAVE_HUES[(oct - 1) % OCTAVE_HUES.length];
+        if (_isBlackPc(midi)) hex = _darkenHex(hex, OCTAVE_SHARP_DARKEN);
+        return hex;
+    }
+    // Every valid palette id: the 12-entry pitch-class tables PLUS the
+    // procedural 'octaves' scheme (which is not a 12-array, so it lives
+    // outside NOTE_PALETTES and is validated through this list).
+    const PALETTE_IDS = [...Object.keys(NOTE_PALETTES), 'octaves'];
+
     // Note block cross-section height and bevel (world units). The bevel
     // turns the flat slabs into glossy gem-like blocks that catch the light
     // on their edges — the RS+ reference look.
@@ -97,8 +283,8 @@
     // Gem vertical gradient (bottom shade → top highlight), baked per-vertex into
     // the note geometry so a block reads as a lit 3D gem instead of a flat fill —
     // same approach as the bundled guitar highway_3d (`gNoteGrad`). The ramp is
-    // greyscale so one geometry serves every pitch-class colour; the material
-    // multiplies its colour by it via vertexColors.
+    // greyscale so one geometry serves every pitch-class color; the material
+    // multiplies its color by it via vertexColors.
     const GEM_SHADE_BOT = 0.12, GEM_SHADE_TOP = 1.1; // strong gem gradient (top slightly blows toward a highlight)
 
     const NOTE_NAMES = ['C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B'];
@@ -913,7 +1099,35 @@
         scoreFx: true,    // 2D overlay: +N pops, combo rings, streak-break wash
         bgIntensity: 0.5, // background-ambience density/strength
         bgReactive: true, // background reacts to the audio analyser
+        // Highway-layout options (apply on the next chart build via init()'s
+        // fx re-read). The sharp LAYOUT is a separate string setting
+        // (keys3d_bg_sharpMode); these two are the booleans.
+        octaveGaps: true,      // ON: wider divider gap at each B→C octave boundary
+        laneOpacity: 0.0,      // 0–1: lane-color strength. 0 (default) = dark floor +
+        //                        block guide lines (E→F, B→C); 1 = full colored lanes; crossfades.
+        octaveContrast: 0.5,   // 0–1: how strongly the B→C octave line stands out. It
+        //                        auto-darkens with lane opacity and brightens as it fades.
+        // Camera base-rig fine-tune. These shift the BASE vantage point the
+        // auto-pan/zoom follow-motion is built on (they multiply/offset the
+        // active CAM_PRESET before the per-frame pan + dolly), so the camera
+        // still tracks the notes — just from a nudged height/distance/tilt.
+        camHeight: 1.0,   // ×preset camera height (higher = more overhead)
+        camDist: 1.0,     // ×preset camera distance (larger = further back)
+        camTilt: 0.0,     // aim offset up(+)/down(−); 0 = neutral — the tuned overhead aim lives in CAM_PRESETS.overhead, so this fine-tune only nudges from a preset (and Classic + tilt 0 == the historical rig)
     };
+    // Numeric FX keys clamp to a declared [min, max]; keys absent from this
+    // table keep the historical 0–1 slider range. The camera fine-tune knobs
+    // are multipliers/offsets centred on 1 (or 0), so they need headroom and a
+    // floor a 0–1 range couldn't express.
+    const FX_RANGES = {
+        camHeight: [0.4, 2.2],
+        camDist: [0.4, 2.2],
+        camTilt: [-1.0, 1.0],
+    };
+    function _fxClamp(key, n) {
+        const r = FX_RANGES[key] || [0, 1];
+        return Math.min(r[1], Math.max(r[0], n));
+    }
     const FX_LS_PREFIX = 'keys3d_bg_';
     // Theme id lives OUTSIDE FX_DEFAULTS (string, not bool/number) — its own
     // localStorage key + validation against BG_THEMES.
@@ -1090,6 +1304,88 @@
         } catch (_) { /* dispatch unavailable — persisted value applies next init */ }
     };
 
+    // Note-color palette id — string-valued like the theme, so it gets its
+    // own validated key + setter rather than an FX_DEFAULTS slot.
+    const FX_LS_PALETTE = 'keys3d_bg_palette';
+    function readPaletteSetting() {
+        try {
+            const id = localStorage.getItem(FX_LS_PALETTE);
+            if (id && PALETTE_IDS.indexOf(id) !== -1) return id;
+        } catch (_) {}
+        // Default: the octave scheme (each octave its own color, darker
+        // sharps) — the plug-and-play piano look. Emerald/classic/etc. remain
+        // selectable.
+        return 'octaves';
+    }
+    window.keys3dSetPalette = function (id) {
+        if (PALETTE_IDS.indexOf(id) === -1) return;
+        try { localStorage.setItem(FX_LS_PALETTE, id); } catch (_) {}
+        try {
+            window.dispatchEvent(new CustomEvent('keys3d:settings', { detail: { palette: id } }));
+        } catch (_) { /* dispatch unavailable — persisted value applies next init */ }
+    };
+
+    // Sharp-display layout id — string-valued (3-way), its own validated key +
+    // setter. 'floating' = the original raised-plane sharps with white-only
+    // lanes; 'flat' = every note on one plane with piano-shaped tiled lanes
+    // (sharps leaned to even the naturals); 'realistic'
+    // = one plane with note bars sized like the physical keys (full naturals,
+    // full sharps overlapping on top). Geometry-time — applied on the next chart
+    // build via init()'s re-read.
+    const FX_LS_SHARPMODE = 'keys3d_bg_sharpMode';
+    const SHARP_MODES = ['floating', 'flat', 'realistic'];
+    function readSharpModeSetting() {
+        try {
+            const id = localStorage.getItem(FX_LS_SHARPMODE);
+            if (id && SHARP_MODES.indexOf(id) !== -1) return id;
+        } catch (_) {}
+        return 'realistic'; // default layout: physical-key-sized bars on one plane
+    }
+    window.keys3dSetSharpMode = function (id) {
+        if (SHARP_MODES.indexOf(id) === -1) return;
+        try { localStorage.setItem(FX_LS_SHARPMODE, id); } catch (_) {}
+        try {
+            window.dispatchEvent(new CustomEvent('keys3d:settings', { detail: { sharpMode: id } }));
+        } catch (_) { /* dispatch unavailable — persisted value applies next init */ }
+    };
+
+    // Camera-rig presets. 'classic' is the original low, near-telephoto rig
+    // (numerically identical to the historical constants, so 'classic' with the
+    // neutral camTilt default reproduces the exact stock framing). y/z/lookY/lookZ
+    // are in pre-K world units — the instance multiplies by K at the use sites,
+    // same as the old constants did. Zoom scales position AND look-at every
+    // frame, so all presets inherit the adaptive dolly behaviour unchanged.
+    // Each preset carries its OWN tuned aim in lookY: 'overhead' bakes in the
+    // plug-and-play downward tilt (the −0.6 × CAM_TILT_UNITS = −33 that used to
+    // ship as the camTilt default) so the default look is unchanged while
+    // camTilt now defaults to 0 (a neutral nudge from whatever preset is picked).
+    const CAM_PRESETS = {
+        classic:  { fov: 40, y: 46,  z: 112, lookY: 8,   lookZ: -165 },
+        elevated: { fov: 44, y: 78,  z: 118, lookY: 4,   lookZ: -150 },
+        overhead: { fov: 48, y: 118, z: 74,  lookY: -33, lookZ: -115 },
+    };
+    // Camera preset id — string-valued like the theme, so it gets its own
+    // validated key + setter rather than an FX_DEFAULTS slot.
+    const FX_LS_CAMERA = 'keys3d_bg_camera';
+    function readCameraSetting() {
+        try {
+            const id = localStorage.getItem(FX_LS_CAMERA);
+            if (id && CAM_PRESETS[id]) return id;
+        } catch (_) {}
+        // Default: the overhead reading rig — its lookY already carries the
+        // tuned downward aim, so with the neutral camTilt default it gives the
+        // plug-and-play piano view out of the box. Others selectable ('classic'
+        // + neutral tilt = the exact historical rig).
+        return 'overhead';
+    }
+    window.keys3dSetCamera = function (id) {
+        if (!CAM_PRESETS[id]) return;
+        try { localStorage.setItem(FX_LS_CAMERA, id); } catch (_) {}
+        try {
+            window.dispatchEvent(new CustomEvent('keys3d:settings', { detail: { camera: id } }));
+        } catch (_) { /* dispatch unavailable — persisted value applies next init */ }
+    };
+
     function readFxSettings() {
         const fx = Object.assign({}, FX_DEFAULTS);
         try {
@@ -1104,10 +1400,10 @@
                     else if (raw === '0' || raw === 'false') fx[k] = false;
                 } else {
                     const n = parseFloat(raw);
-                    // All numeric FX keys are 0-1 sliders — clamp so a
-                    // corrupt/foreign write can't overdrive opacities
-                    // or the camera pulse.
-                    if (Number.isFinite(n)) fx[k] = Math.min(1, Math.max(0, n));
+                    // Numeric FX keys clamp to their declared range
+                    // (default 0-1) so a corrupt/foreign write can't
+                    // overdrive opacities or the geometry multipliers.
+                    if (Number.isFinite(n)) fx[k] = _fxClamp(k, n);
                 }
             }
         } catch (_) { /* localStorage unavailable — use defaults */ }
@@ -1127,7 +1423,7 @@
         } else {
             v = Number(value);
             if (!Number.isFinite(v)) return;
-            v = Math.min(1, Math.max(0, v));   // all numeric FX keys are 0-1
+            v = _fxClamp(key, v);   // declared range, default 0-1
         }
         try {
             localStorage.setItem(FX_LS_PREFIX + key, typeof v === 'boolean' ? (v ? '1' : '0') : String(v));
@@ -1369,6 +1665,8 @@
         // Theme/material handles (built by buildScene/buildKeyboardAndHighway;
         // _applyTheme / _applyCinematic / the glow slider retune them live).
         let _theme = readThemeSetting();
+        let _palette = readPaletteSetting();
+        let _sharpMode = readSharpModeSetting(); // 'floating' | 'flat' | 'realistic'
         let ambLight = null, dirLight = null;
         let _floorMat = null;
         const _railMats = [];      // lane-edge rail materials (theme laneDim)
@@ -1432,8 +1730,20 @@
             return [1, 3, 6, 8, 10].includes(((midi % 12) + 12) % 12);
         }
 
+        function _paletteColor(pc) {
+            return (NOTE_PALETTES[_palette] || PITCH_CLASS_COLORS)[pc];
+        }
+
+        // Base color (24-bit int, no hand dimming) for a midi note under the
+        // active palette — the octave scheme is procedural, every other
+        // palette is a 12-entry pitch-class table.
+        function _noteHex(midi) {
+            if (_palette === 'octaves') return octaveNoteColor(midi);
+            return _paletteColor(((midi % 12) + 12) % 12);
+        }
+
         function noteColor(midi, hand) {
-            const base = new T.Color(PITCH_CLASS_COLORS[((midi % 12) + 12) % 12]);
+            const base = new T.Color(_noteHex(midi));
             const b = HAND_BRIGHTNESS[hand] != null ? HAND_BRIGHTNESS[hand] : 1.0;
             base.multiplyScalar(b);
             return base;
@@ -1460,15 +1770,51 @@
         const WHITE_W = 12 * K, WHITE_L = 46 * K, WHITE_H = 5 * K;
         const BLACK_W = 6.4 * K, BLACK_L = 28 * K, BLACK_H = 6.5 * K;
         const HIGHWAY_LEN = 1150 * K; // longer runway → ~8.8s of lookahead visible
+        // 'flat' piano-shaped-lane geometry (see laneSpanFlat). Zero-overlap tiling:
+        // white lanes are trimmed by FLAT_SHARP_HALF where they meet a sharp and
+        // the sharp fills the gap, so nothing overlaps. To keep the naturals
+        // even, each sharp is nudged FLAT_SHARP_SHIFT toward the EDGE natural
+        // beside it (C#→C, D#→E, F#→F, A#→B; G# stays centred, no edge to lean
+        // on) — that steals a sliver from the edge natural and hands it to the
+        // squeezed inner natural. At shift = sharpHalf/3 the C-D-E-F-B naturals
+        // come out exactly equal; G/A land a hair smaller (G# can't lean). The
+        // sharps ride the same flat plane (no lift — they never overlap a
+        // natural). OCT_GAP is the extra divider opened at each octave boundary
+        // when the octaveGaps option is on.
+        const FLAT_SHARP_HALF = 2.2 * K;                 // sharp half-width (4.4K wide)
+        const FLAT_SHARP_SHIFT = FLAT_SHARP_HALF / 3;    // sharp lean that evens the naturals
+        const OCT_GAP = 0.9 * K;
+        const LANE_DIMS_FLAT = {
+            whiteW: WHITE_W, sharpHalf: FLAT_SHARP_HALF, shift: FLAT_SHARP_SHIFT, octGap: OCT_GAP,
+        };
+        // 'realistic' layout (laneSpanReal): every note bar is the size of the
+        // physical key it lands on — naturals the full white-key width (always
+        // rendered full, only occluded where a sharp note actually overlaps in
+        // time) and sharps the full black-key width at their standard positions,
+        // drawn on top with a hair of REAL_SHARP_LIFT (anti z-fight).
+        const REAL_NAT_HALF = WHITE_W * 0.47;   // natural bar ≈ physical white key (~11.3K)
+        const REAL_SHARP_HALF = BLACK_W / 2;    // sharp bar = physical black key (6.4K)
+        const REAL_SHARP_LIFT = 0.3 * K;
+        const LANE_DIMS_REAL = { natHalf: REAL_NAT_HALF, sharpHalf: REAL_SHARP_HALF, octGap: OCT_GAP };
+        // Lane span for the active non-floating sharp mode. `range`
+        // (activeLow/activeHigh) is optional and only consulted by the flat
+        // layout, to gate the boundary-key edge trim (see laneSpanFlat).
+        const _flatMode = () => _sharpMode === 'flat' || _sharpMode === 'realistic';
+        function laneSpanFor(midi, black, cx, gaps, range) {
+            return _sharpMode === 'realistic'
+                ? laneSpanReal(midi, black, cx, LANE_DIMS_REAL, gaps)
+                : laneSpanFlat(midi, black, cx, LANE_DIMS_FLAT, gaps, range);
+        }
 
-        // Camera — low, near-telephoto rig (RS+-style): a narrow FOV from low
-        // and back gives a deep receding runway and frames ~2 octaves instead
-        // of cramming the whole note range full-width. The x position pans to
-        // follow the active notes (see updateScene), so wide pieces stay zoomed
-        // in on the played hand rather than shrinking every key.
-        const CAM_FOV = 40;
-        const CAM_Y = 46 * K, CAM_Z = 112 * K;
-        const LOOK_Y = 8 * K, LOOK_Z = -165 * K;
+        // Camera — the default 'classic' preset is a low, near-telephoto rig
+        // (RS+-style): a narrow FOV from low and back gives a deep receding
+        // runway and frames ~2 octaves instead of cramming the whole note
+        // range full-width. The x position pans to follow the active notes
+        // (see updateScene), so wide pieces stay zoomed in on the played hand
+        // rather than shrinking every key. The rig numbers now come from the
+        // user-selectable CAM_PRESETS table; switching applies live because
+        // position/lookAt are re-derived every frame.
+        let _camPreset = CAM_PRESETS[readCameraSetting()] || CAM_PRESETS.classic;
         // Pan-follow: a slow ease toward a wide, gently-weighted centroid so the
         // camera glides with the melody instead of darting as notes enter/leave.
         const CAM_PAN_LERP = 0.022;      // per-frame ease (~1s glide @60fps)
@@ -1484,7 +1830,26 @@
         const CAM_ZOOM_BASE_KEYS = 11;   // white keys framed at zoom = 1
         const CAM_ZOOM_MIN = 0.9, CAM_ZOOM_MAX = 4.8;
         const CAM_ZOOM_LERP = 0.025;     // smooth zoom ease
-        // Per-key approach glow: a key lights in its pitch-class colour ONLY while a
+        // Full-swing of the camTilt aim offset (pre-K units) at slider ±1.
+        const CAM_TILT_UNITS = 55;
+
+        // Base rig with the live fine-tune knobs applied — height/distance
+        // multiply the preset, tilt offsets the aim height. Returns the
+        // effective {y, z, lookY, lookZ} in pre-K units; the caller scales by
+        // K and the auto-zoom. Keeps the pan/dolly follow-motion intact —
+        // these only move the vantage point it orbits around. Writes into a
+        // reusable object (returned live) so the per-frame camera update stays
+        // allocation-free — the callers read it synchronously and never retain
+        // it, so a single shared instance is safe.
+        const _rigOut = { y: 0, z: 0, lookY: 0, lookZ: 0 };
+        function _rig() {
+            _rigOut.y = _camPreset.y * fx.camHeight;
+            _rigOut.z = _camPreset.z * fx.camDist;
+            _rigOut.lookY = _camPreset.lookY + fx.camTilt * CAM_TILT_UNITS;
+            _rigOut.lookZ = _camPreset.lookZ;
+            return _rigOut;
+        }
+        // Per-key approach glow: a key lights in its pitch-class color ONLY while a
         // note is heading for it, ramping up the closer that note gets to the hit-line.
         const KEY_GLOW_AHEAD = 2.0;      // seconds before the hit-line a key starts to light
         const KEY_GLOW_STRENGTH = 1.15;  // peak emissive intensity (note at the hit-line)
@@ -1945,10 +2310,9 @@
             _envRT = _makeStudioEnv(T, ren);
             if (_envRT) scene.environment = _envRT.texture;
 
-            cam = new T.PerspectiveCamera(CAM_FOV, 1, 0.1, 2000 * K);
+            cam = new T.PerspectiveCamera(_camPreset.fov, 1, 0.1, 2000 * K);
             _camX = 0; _camTargetX = 0; _camZoom = 1; _camTargetZoom = 1;
-            cam.position.set(0, CAM_Y, CAM_Z);
-            cam.lookAt(0, LOOK_Y, LOOK_Z);
+            { const r = _rig(); cam.position.set(0, r.y * K, r.z * K); cam.lookAt(0, r.lookY * K, r.lookZ * K); }
 
             ambLight = new T.AmbientLight(0xffffff, 0.75);
             dirLight = new T.DirectionalLight(0xffffff, 1.1);
@@ -2074,9 +2438,9 @@
             });
             // Extrusion spans z ∈ [-bevel, depth + bevel]; centre it.
             geo.translate(0, 0, -depth / 2);
-            // Bake a vertical brightness ramp into vertex colours (bottom shade →
+            // Bake a vertical brightness ramp into vertex colors (bottom shade →
             // top highlight) so the gem reads 3D; the material multiplies its
-            // pitch-class colour by this (vertexColors).
+            // pitch-class color by this (vertexColors).
             geo.computeBoundingBox();
             const y0 = geo.boundingBox.min.y, yr = (geo.boundingBox.max.y - y0) || 1;
             const pos = geo.attributes.position;
@@ -2091,13 +2455,16 @@
             return geo;
         }
 
-        // Glossy note material, cached per (pitch class, hand).
+        // Glossy note material, cached per resolved color. Keying by the
+        // final color int (hand brightness already baked in by noteColor)
+        // works for every palette — including 'octaves', where two notes of
+        // the same pitch class in different octaves are DIFFERENT colors and
+        // must not share a material (a pitch-class key would collide them).
         function _noteMaterial(midi, hand) {
-            const handKey = HAND_BRIGHTNESS[hand] != null ? hand : 'rh';
-            const key = (((midi % 12) + 12) % 12) + '|' + handKey;
+            const col = noteColor(midi, hand);
+            const key = col.getHex();
             let mat = _noteMatCache.get(key);
             if (mat) return mat;
-            const col = noteColor(midi, hand);
             // MeshPhysicalMaterial with a clearcoat: lacquered glass-gem
             // look — a sharp coat highlight over a colored body, lit by the
             // studio env map. This is the "not plastic" ask: the old matte
@@ -2107,7 +2474,7 @@
             // share one shader program.)
             mat = new T.MeshPhysicalMaterial({
                 color: col,
-                vertexColors: true,         // multiply colour by the baked gem ramp
+                vertexColors: true,         // multiply color by the baked gem ramp
                 emissive: col,
                 emissiveIntensity: NOTE_EMISSIVE_BASE * _glowMul(),
                 roughness: 0.32,
@@ -2129,7 +2496,10 @@
             return 0.72 + 0.22 * Math.min(1, Math.max(0, fx.vibrancy));
         }
         function _laneGuideOpacity() {
-            return 0.10 + 0.12 * Math.min(1, Math.max(0, fx.vibrancy));
+            // Vibrancy sets the ceiling (much brighter than the old subtle
+            // 0.10–0.22 range); the laneOpacity slider then scales 0 → ceiling.
+            const vib = 0.32 + 0.52 * Math.min(1, Math.max(0, fx.vibrancy)); // ~0.32..0.84
+            return vib * Math.min(1, Math.max(0, fx.laneOpacity));
         }
 
         // Live vibrancy slider: retint everything already built — the
@@ -2145,6 +2515,39 @@
             for (const m of _laneGuideMats) m.opacity = lop;
         }
 
+        // Live palette switch: recolor everything already built — cached
+        // note materials (future clones), per-note clones, key emissives
+        // (incl. the wrong-flash restore state), lane guides — and drop the
+        // pitch-class flame textures so the next spawn bakes the new hues.
+        // Same no-rebuild approach as _applyVibrancy.
+        function _applyPalette() {
+            // The base-material cache is keyed by resolved color, so old
+            // entries are simply stale under a new palette — drop them and let
+            // the next build re-cache. The live per-note clones below are
+            // retinted directly from each note's midi (palette-correct).
+            for (const m of _noteMatCache.values()) m.dispose();
+            _noteMatCache.clear();
+            for (const nm of noteMeshes) {
+                if (!nm.mesh || !nm.mesh.material) continue;
+                const col = noteColor(nm.note.midi, nm.note.hand);
+                nm.mesh.material.color.copy(col);
+                nm.mesh.material.emissive.copy(col);
+            }
+            for (const [midi, km] of keyMeshes) {
+                const col = noteColor(midi, 'rh');
+                km.material.emissive.copy(col);
+                km.userData.origEmissive = col.getHex();
+            }
+            for (const m of _laneGuideMats) {
+                if (m.userData.midi != null) m.color.copy(noteColor(m.userData.midi, 'rh'));
+            }
+            _clearFlameTextures();
+            // Re-arm the pool so no slot keeps rendering a disposed texture
+            // (a flame mid-flight briefly re-tints — next spawn sets its
+            // true pitch texture).
+            for (const s of _flamePool) s.mat.map = _flameTexture(0);
+        }
+
         function _barNumberTexture(idx) {
             let tex = _barTexCache.get(idx);
             if (tex) return tex;
@@ -2181,13 +2584,15 @@
             return _glowTex;
         }
 
-        // Vertical flame texture for hit flares: white-hot base fading up
-        // into the pitch-class colour, with a horizontal falloff. Cached per
-        // pitch class (bounded, 12 entries).
-        function _flameTexture(pc) {
-            let tex = _flameTexCache.get(pc);
+        // Vertical flame texture for hit flares / held-key halos: white-hot
+        // base fading up into the note's color, with a horizontal falloff.
+        // Cached per resolved color (bounded — 12 for pitch-class palettes,
+        // up to ~one-per-octave for 'octaves'), so a flare always matches the
+        // struck note's color whatever the palette.
+        function _flameTexture(midi) {
+            const c = _noteHex(midi);
+            let tex = _flameTexCache.get(c);
             if (tex) return tex;
-            const c = PITCH_CLASS_COLORS[pc];
             const r = (c >> 16) & 0xff, g = (c >> 8) & 0xff, b = c & 0xff;
             const cnv = document.createElement('canvas');
             cnv.width = 64;
@@ -2207,7 +2612,7 @@
             ctx.fillStyle = falloff;
             ctx.fillRect(0, 0, 64, 128);
             tex = new T.CanvasTexture(cnv);
-            _flameTexCache.set(pc, tex);
+            _flameTexCache.set(c, tex);
             return tex;
         }
 
@@ -2294,7 +2699,7 @@
             if (!entry) return;
             const slot = _flamePool[_flameIdx];
             _flameIdx = (_flameIdx + 1) % _flamePool.length;
-            slot.mat.map = _flameTexture(((midi % 12) + 12) % 12);
+            slot.mat.map = _flameTexture(midi);
             slot.start = wallNow;
             slot.baseY = entry.black ? BLACK_H + WHITE_H * 0.6 : WHITE_H;
             slot.sprite.position.x = keyX(entry, _layoutInfo.whiteCount);
@@ -2363,9 +2768,9 @@
                 }
             }
 
-            // Lane guides: a faint colour strip running up the runway from each
-            // active key, in that key's pitch-class colour. A falling note shares
-            // its target key's colour, so the player can trace it straight down
+            // Lane guides: a faint color strip running up the runway from each
+            // active key, in that key's pitch-class color. A falling note shares
+            // its target key's color, so the player can trace it straight down
             // its lane to the right key even when it sits near the frame edge.
             //
             // The lanes sit at the NOTES' travel height (coplanar), not on the
@@ -2375,28 +2780,87 @@
             // lane, perfectly aligned with the lane and its key.
             const guideLen = HIGHWAY_LEN - WHITE_L;
             const laneY = WHITE_H + NOTE_H / 2 + 0.5 * K; // == white-note travel height
+            const gaps = fx.octaveGaps;
+            const floating = _sharpMode === 'floating';
+            const t = Math.min(1, Math.max(0, fx.laneOpacity));       // lane-color opacity
+            const octC = Math.min(1, Math.max(0, fx.octaveContrast)); // 0..1 line-contrast
+            const themeLaneDim = (() => { const c = _bgThemeColors(_theme); return c.laneDim != null ? c.laneDim : 0x2a2a3e; })();
+            // A vertical guide line running the full runway at world x (skips
+            // near-transparent lines so the crossfade never builds dead meshes).
+            const addLine = (x, color, opacity, wpx, trackTheme) => {
+                if (opacity < 0.02) return;
+                const m = new T.MeshBasicMaterial({ color, transparent: true, opacity, depthWrite: false });
+                if (trackTheme) _railMats.push(m); // theme retint tracks these; fixed guides stay put
+                const line = new T.Mesh(new T.PlaneGeometry(wpx, guideLen), m);
+                line.rotation.x = -Math.PI / 2;
+                line.position.set(x, laneY + 0.06 * K, hitZ - guideLen / 2);
+                keyboardGroup.add(line);
+            };
             for (const [midi, entry] of layout) {
                 if (midi < range.activeLow || midi > range.activeHigh) continue;
-                if (entry.black) continue; // one strip per semitone-slot lands on whites
-                const gmat = new T.MeshBasicMaterial({
-                    color: noteColor(midi, 'rh'), transparent: true,
-                    opacity: _laneGuideOpacity(), depthWrite: false,
-                });
-                _laneGuideMats.push(gmat);
-                const strip = new T.Mesh(new T.PlaneGeometry(WHITE_W * 0.84, guideLen), gmat);
-                strip.rotation.x = -Math.PI / 2;
-                strip.position.set(keyX(entry, whiteCount), laneY, hitZ - guideLen / 2);
-                keyboardGroup.add(strip);
-                // Thin brighter rails at the lane edges for crisp separation.
-                const railMat = new T.MeshBasicMaterial({
-                    color: (() => { const c = _bgThemeColors(_theme); return c.laneDim != null ? c.laneDim : 0x2a2a3e; })(),
-                    transparent: true, opacity: 0.5, depthWrite: false,
-                });
-                _railMats.push(railMat);
-                const rail = new T.Mesh(new T.PlaneGeometry(0.6 * K, guideLen), railMat);
-                rail.rotation.x = -Math.PI / 2;
-                rail.position.set(keyX(entry, whiteCount) - WHITE_W / 2, laneY + 0.05 * K, hitZ - guideLen / 2);
-                keyboardGroup.add(rail);
+                // Floating: white-only lanes (blacks float, lane-less). Flat/
+                // realistic: every key gets a piano-shaped lane.
+                if (entry.black && floating) continue;
+                // Lane footprint per mode.
+                let left, right, stripY = laneY;
+                if (floating) {
+                    const cx = keyX(entry, whiteCount);
+                    left = cx - WHITE_W / 2; right = cx + WHITE_W / 2;
+                    if (gaps) {
+                        const pc = ((midi % 12) + 12) % 12;
+                        if (pc === 11) right -= OCT_GAP / 2; // B → C boundary
+                        if (pc === 0) left += OCT_GAP / 2;
+                    }
+                } else {
+                    const span = laneSpanFor(midi, entry.black, keyX(entry, whiteCount), gaps, range);
+                    left = span.left; right = span.right;
+                    if (_sharpMode === 'realistic' && entry.black) stripY = laneY + REAL_SHARP_LIFT;
+                }
+                const center = (left + right) / 2;
+                // Colored lane strip + a subtle per-lane separator — fade in with
+                // lane opacity. (As lanes fade, the block/octave lines below take
+                // over as the guide.)
+                if (t > 0.02) {
+                    // Floating keeps the historical 0.84-wide white strip; the
+                    // piano-shaped lanes inset a touch for a dark separator.
+                    const stripW = floating ? (right - left) - WHITE_W * 0.16 : (right - left) * 0.9;
+                    const gmat = new T.MeshBasicMaterial({
+                        color: noteColor(midi, 'rh'), transparent: true,
+                        opacity: _laneGuideOpacity(), depthWrite: false, // includes lane opacity
+                    });
+                    gmat.userData.midi = midi; // palette retint needs the lane's pitch
+                    _laneGuideMats.push(gmat);
+                    const strip = new T.Mesh(new T.PlaneGeometry(stripW, guideLen), gmat);
+                    strip.rotation.x = -Math.PI / 2;
+                    strip.position.set(center, stripY, hitZ - guideLen / 2);
+                    keyboardGroup.add(strip);
+                    // Per-lane separator, fading with the strips. Skip realistic
+                    // sharps (they overlap the white columns).
+                    if (!(entry.black && _sharpMode === 'realistic')) {
+                        addLine(left, themeLaneDim, 0.5 * t, 0.6 * K, true);
+                    }
+                }
+            }
+            // Structural divider lines: ONE per "block" boundary — E→F and B→C —
+            // so each block of keys (C-D-E, F-G-A-B) is bounded, not every lane.
+            // They crossfade IN as the lanes fade OUT. The B→C octave line is a
+            // dark layer (reads over bright lanes, scales with lane opacity) plus
+            // a bright layer (reads over the dark floor, scales with the inverse),
+            // so it auto-shifts dark→bright as you fade lanes; octaveContrast
+            // scales the whole thing.
+            for (let midi = range.activeLow; midi <= range.activeHigh; midi++) {
+                const pc = ((midi % 12) + 12) % 12;
+                const isEF = pc === 4;   // E → F block boundary
+                const isBC = pc === 11;  // B → C octave boundary
+                if (!isEF && !isBC) continue;
+                const boundaryX = keyX(layout.get(midi), whiteCount) + WHITE_W / 2;
+                if (isBC) {
+                    addLine(boundaryX, 0x05060a, octC * 0.92 * t, 1.1 * K, false);              // dark, over lanes
+                    addLine(boundaryX, 0xd8dcec, (0.42 + octC * 0.5) * (1 - t), 1.1 * K, false); // bright, over floor
+                } else {
+                    // E→F block divider — a guide that appears as the lanes fade.
+                    addLine(boundaryX, 0x6a6a7a, 0.5 * (1 - t), 0.8 * K, false);
+                }
             }
 
             // Keys (whites first so blacks overlay). Geometries are shared
@@ -2416,7 +2880,7 @@
                 const inRange = midi >= range.activeLow && midi <= range.activeHigh;
                 const material = new T.MeshStandardMaterial({
                     color: black ? 0x070708 : 0xe8e8ee,
-                    // Pitch-class colour preset on emissive but OFF at rest — the key
+                    // Pitch-class color preset on emissive but OFF at rest — the key
                     // is neutral until a note approaches, when updateScene ramps the
                     // intensity up by proximity.
                     emissive: noteColor(midi, 'rh'),
@@ -2502,11 +2966,31 @@
                 const entry = layout.get(note.midi);
                 if (!entry) continue;
                 const len = Math.max(4 * K, note.durSec * TS);
-                const w = (entry.black ? BLACK_W : WHITE_W * 0.94) * 0.9;
+                // Non-floating layouts: notes ride the naturals' plane and take
+                // their piano-shaped lane's width/centre. Floating (default):
+                // original elevated sharps, key-centred bars.
+                let w, x, y;
+                if (_flatMode()) {
+                    const span = laneSpanFor(
+                        note.midi, entry.black, keyX(entry, whiteCount), fx.octaveGaps, range);
+                    // 'realistic' bars are full (physical-key size); 'flat' bars are
+                    // inset a touch for a dark separator in the tight tiling.
+                    const inset = _sharpMode === 'realistic' ? 1.0 : 0.9;
+                    w = (span.right - span.left) * inset;
+                    x = (span.left + span.right) / 2;
+                    // Coplanar; in 'realistic' the sharps ride a hair proud so they
+                    // draw over the naturals they overlap without z-fighting.
+                    const lift = (_sharpMode === 'realistic' && entry.black) ? REAL_SHARP_LIFT : 0;
+                    y = WHITE_H + NOTE_H / 2 + 0.5 * K + lift;
+                } else {
+                    w = (entry.black ? BLACK_W : WHITE_W * 0.94) * 0.9;
+                    x = keyX(entry, whiteCount);
+                    y = (entry.black ? BLACK_H + WHITE_H : WHITE_H) + NOTE_H / 2 + 0.5 * K;
+                }
                 // Clone per note so each can glow independently while being consumed.
                 const mesh = new T.Mesh(_noteGeometry(w, len), _noteMaterial(note.midi, note.hand).clone());
-                mesh.position.x = keyX(entry, whiteCount);
-                mesh.position.y = (entry.black ? BLACK_H + WHITE_H : WHITE_H) + NOTE_H / 2 + 0.5 * K;
+                mesh.position.x = x;
+                mesh.position.y = y;
                 mesh.visible = false;
                 notesGroup.add(mesh);
                 // Note-name label: a camera-facing sprite (readable at this low camera
@@ -2775,8 +3259,7 @@
             }
             _camX += (_camTargetX - _camX) * CAM_PAN_LERP;
             _camZoom += (_camTargetZoom - _camZoom) * CAM_ZOOM_LERP;
-            cam.position.set(_camX, CAM_Y * _camZoom, CAM_Z * _camZoom);
-            cam.lookAt(_camX, LOOK_Y * _camZoom, LOOK_Z * _camZoom);
+            { const r = _rig(); cam.position.set(_camX, r.y * K * _camZoom, r.z * K * _camZoom); cam.lookAt(_camX, r.lookY * K * _camZoom, r.lookZ * K * _camZoom); }
 
             for (const km of keyMeshes.values()) km.userData.glow = 0;
             for (const { mesh, note, len, label } of noteMeshes) {
@@ -3217,9 +3700,13 @@
                 if (_isReady) teardown();
                 highwayCanvas = canvas;
                 fx = readFxSettings();
-                // Persisted string settings refresh here too — a theme saved
-                // while no instance was listening must not come up stale on a
-                // later init().
+                // Persisted string settings refresh here too — a palette,
+                // camera, theme or background style saved while no instance was
+                // listening (e.g. changed on the Settings screen, where the live
+                // viz is torn down) must not come up stale on a later init().
+                _palette = readPaletteSetting();
+                _sharpMode = readSharpModeSetting();
+                _camPreset = CAM_PRESETS[readCameraSetting()] || CAM_PRESETS.classic;
                 _theme = readThemeSetting();
                 _bgStyle = readBgStyleSetting();
                 loadThree().then(() => {
@@ -3265,6 +3752,23 @@
                             _bgStyle = d.bgStyle;
                             _bgMountStyle();
                         }
+                        if (d && d.palette && PALETTE_IDS.indexOf(d.palette) !== -1) {
+                            _palette = d.palette;
+                            _applyPalette();
+                        }
+                        if (d && d.sharpMode && SHARP_MODES.indexOf(d.sharpMode) !== -1) {
+                            // Geometry-time — takes effect on the next chart build.
+                            _sharpMode = d.sharpMode;
+                        }
+                        if (d && d.camera && CAM_PRESETS[d.camera]) {
+                            _camPreset = CAM_PRESETS[d.camera];
+                            // Position/lookAt re-derive next frame; only the
+                            // projection needs an explicit poke.
+                            if (cam) {
+                                cam.fov = _camPreset.fov;
+                                cam.updateProjectionMatrix();
+                            }
+                        }
                     };
                     window.addEventListener('keys3d:settings', _fxThemeHandler);
                     window.addEventListener('keys3d:settings', _fxHandler);
@@ -3470,10 +3974,24 @@
         readFxSettings,
         readThemeSetting,
         readBgStyleSetting,
+        readPaletteSetting,
+        readCameraSetting,
+        readSharpModeSetting,
+        SHARP_MODES,
         _bgThemeColors,
         BG_THEMES,
         BG_STYLE_IDS,
+        NOTE_PALETTES,
+        PITCH_CLASS_COLORS,
+        PALETTE_IDS,
+        OCTAVE_HUES,
+        octaveNoteColor,
+        _isBlackPc,
+        laneSpanFlat,
+        laneSpanReal,
+        CAM_PRESETS,
         FX_DEFAULTS,
+        FX_RANGES,
         _classifyTiming,
     };
 

plugins/keys_highway_3d/settings.html

@@ -12,6 +12,22 @@
     <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)"
@@ -30,7 +46,117 @@
         </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. Pitch-class note colours never change.
+            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">
@@ -116,7 +242,7 @@
         <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 colours
+            Timing colors
         </label>
         <p class="text-xs text-gray-500 mt-1">
             Tint the sparks by timing — on-time green, early cyan, late
@@ -179,6 +305,9 @@
             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;
@@ -190,6 +319,26 @@
             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)) {
@@ -200,6 +349,16 @@
             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);
         }

plugins/keys_highway_3d/tests/fx_settings.test.js

@@ -148,3 +148,405 @@ test('FX defaults: ambience + score FX ship enabled', () => {
     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/tuner/plugin.json

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

plugins/tuner/utils/ui.js

@@ -869,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,94 @@
+// 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]
+//
+// 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 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 };
+}
+
+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`;
+out += `\n> **Requires a seeded library** (not captured by this run): playback frame-time p95\n`;
+out += `> on the 2D + 3D highway, and screen-entry (plugin inject → interactive) for\n`;
+out += `> editor / notedetect / highway_3d with a real chart loaded. Run this harness\n`;
+out += `> against an environment with charts in \`DLC_DIR\` to fill those in.\n`;
+
+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:
@@ -1870,7 +1871,10 @@ function _setLibraryLoadingMessage(containerId, countId, message) {
     const count = document.getElementById(countId);
     if (count) count.textContent = 'Loading source...';
     if (container) {
-        container.innerHTML = `<div class="rounded-xl border border-gray-800/50 bg-dark-700/30 px-4 py-6 text-sm text-gray-300">${esc(message || 'Loading library...')}</div>`;
+        container.innerHTML = `<div role="status" aria-live="polite" class="rounded-xl border border-gray-800/50 bg-dark-700/30 px-4 py-6 text-sm text-gray-300 flex items-center gap-3">
+            <span class="inline-block h-4 w-4 rounded-full border-2 border-gray-600 border-t-accent animate-spin" aria-hidden="true"></span>
+            <span>${esc(message || 'Loading library...')}</span>
+        </div>`;
     }
 }
 
@@ -1879,6 +1883,9 @@ function _libraryLoadingText() {
     if (!provider || provider.id === 'local' || provider.kind === 'local') {
         return 'Loading library...';
     }
+    if (provider.slow === true) {
+        return `Loading ${provider.label || provider.id}... this source may take a while.`;
+    }
     return `Connecting to ${provider.label || provider.id}...`;
 }
 
@@ -2078,6 +2085,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 +2285,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)
@@ -2870,6 +2880,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
@@ -2906,6 +2920,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' },
@@ -4371,7 +4389,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) {
@@ -5556,9 +5574,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,
@@ -6215,7 +6248,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));
 });
@@ -6781,7 +6814,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) { /* */ }
         }
@@ -7923,6 +7965,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) {
@@ -8083,6 +8129,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() {
@@ -8109,12 +8175,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;
@@ -8126,14 +8189,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;
@@ -10988,20 +11051,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 {
@@ -11143,17 +11205,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);
                 }
@@ -11166,6 +11234,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;
@@ -11193,7 +11273,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) => {
@@ -11202,7 +11285,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
@@ -11490,6 +11573,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;

static/capabilities.js

@@ -86,6 +86,7 @@
     // operation is still completing through the provider.
     const COMMAND_TIMEOUTS_MS = {
         'audio-mix': { 'get-fader-value': 2100, 'set-fader-value': 2100 },
+        'library': { 'refresh-providers': 15000, 'sync-song': 15000 },
         'midi-input': { 'discover': 15000, 'open-source': 15000 },
     };
     function _commandTimeoutFor(capability, commandName) {

static/capabilities/library.js

@@ -13,6 +13,7 @@
         label: 'My Library',
         kind: 'local',
         capabilities: ['library.read', 'art.read', 'song.play', 'favorite.write', 'metadata.write', 'retune.write'],
+        slow: false,
         default: true,
     });
     const PROVIDER_OPERATIONS = Object.freeze({
@@ -72,6 +73,7 @@
             label: String(provider.label || provider.name || providerId),
             kind: String(provider.kind || (providerId === 'local' ? 'local' : 'remote')),
             capabilities: _strings(provider.capabilities),
+            slow: provider.slow === true || provider.is_slow === true || provider.slow_mode === true,
             default: provider.default === true || providerId === 'local',
         };
     }
@@ -141,6 +143,7 @@
                         label: provider.label || providerId,
                         kind: provider.kind || (providerId === 'local' ? 'local' : 'remote'),
                         capabilities: _strings(provider.capabilities),
+                        slow: provider.slow === true,
                         ownerPluginId: _ownerPluginId(provider) || null,
                         default: provider.default === true || providerId === 'local',
                     },

static/highway.js

@@ -2004,18 +2004,32 @@ function createHighway() {
                 const seedBase = (_frameIdx + n.s + ((n.t * 60) | 0)) | 0;
                 ctx.save();
                 ctx.fillStyle = col;
-                ctx.shadowColor = col;
-                ctx.shadowBlur = (8 + 6 * _shimmerNoise(seedBase)) * a;          // shimmering glow
-                ctx.globalAlpha = (0.45 + 0.45 * a) * (0.78 + 0.22 * _shimmerNoise(seedBase + 17));
-                ctx.beginPath();
-                ctx.moveTo(x0 - sw0, y0);
-                ctx.lineTo(x0 + sw0, y0);
-                ctx.lineTo(x1 + sw1, y1);
-                ctx.lineTo(x1 - sw1, y1);
-                ctx.fill();
+                // Shimmering glow WITHOUT ctx.shadowBlur: blur cost scales with
+                // the blurred DEVICE-pixel area, and a held sustain's trail can
+                // span half the (DPR-scaled) canvas — profiling the "stutters
+                // while playing" report put this per-frame blur pass at the top
+                // exactly while a sustain is held. Three inflated low-alpha
+                // fills of the same quad read as the same soft glow at a flat,
+                // area-independent cost. The shimmer LUT still drives the
+                // per-frame size/brightness flicker (feedBack#254 intent).
+                const glowPx = (8 + 6 * _shimmerNoise(seedBase)) * a;
+                const baseA = (0.45 + 0.45 * a) * (0.78 + 0.22 * _shimmerNoise(seedBase + 17));
+                const fillTrail = (inflate) => {
+                    ctx.beginPath();
+                    ctx.moveTo(x0 - sw0 - inflate, y0);
+                    ctx.lineTo(x0 + sw0 + inflate, y0);
+                    ctx.lineTo(x1 + sw1 + inflate, y1);
+                    ctx.lineTo(x1 - sw1 - inflate, y1);
+                    ctx.fill();
+                };
+                ctx.globalAlpha = baseA * 0.22;
+                fillTrail(glowPx);
+                ctx.globalAlpha = baseA * 0.4;
+                fillTrail(glowPx * 0.45);
+                ctx.globalAlpha = baseA;
+                fillTrail(0);
                 // Crackling "current" — a jittery white core line down
                 // the trail, re-randomised each frame.
-                ctx.shadowBlur = 0;
                 ctx.globalCompositeOperation = 'lighter';
                 ctx.globalAlpha = a * (0.55 + 0.45 * _shimmerNoise(seedBase + 31));
                 ctx.strokeStyle = '#ffffff';

static/index.html

@@ -119,6 +119,8 @@
                         <option value="year-desc">Year (newest)</option>
                         <option value="year">Year (oldest)</option>
                         <option value="tuning">Tuning</option>
+                        <option value="difficulty">Difficulty (easiest first)</option>
+                        <option value="difficulty-desc">Difficulty (hardest first)</option>
                     </select>
                     <!-- Format filter (shared) -->
                     <select id="lib-format" onchange="sortLibrary()"

static/v3/badges.js

@@ -451,6 +451,12 @@
                 pill('inst', v, v[0].toUpperCase() + v.slice(1), settings.instrument === v)).join('')) +
             instRow('Strings', STRING_COUNTS[settings.instrument].map((v) =>
                 pill('strings', v, v + '', settings.string_count === v)).join('')) +
+            // Handedness — a left-hander flips the whole highway (frets mirror).
+            // Lives with the other player-orientation choices so it's part of the
+            // same "Choose your instrument" step the onboarding tour spotlights —
+            // i.e. set before you ever tune up or calibrate.
+            instRow('Handedness', pill('hand', 'right', 'Right', !_leftyPref()) +
+                pill('hand', 'left', 'Left', _leftyPref())) +
             '<div><div class="text-[0.625rem] uppercase tracking-wider text-fb-textDim mb-1">Tuning</div>' +
             '<select data-inst-tuning class="w-full bg-gray-800/50 border border-gray-700 rounded-md px-2 py-1.5 text-xs text-fb-text outline-none focus:border-fb-primary">' +
             // An offset-array tuning has no named option — surface it as a
@@ -513,6 +519,10 @@
             setWorkingInstrument(settings.instrument, newSc);
             renderInstrument(); keepOpen();
         }));
+        menu.querySelectorAll('[data-pill="hand"]').forEach((b) => b.addEventListener('click', () => {
+            _setLeftyPref(b.getAttribute('data-val') === 'left');
+            renderInstrument(); keepOpen();   // reflect the active pill; keep the menu open
+        }));
         menu.querySelector('[data-inst-tuning]').addEventListener('change', (e) => saveSettings({ tuning: e.target.value }));
         menu.querySelector('[data-inst-pathway]').addEventListener('change', (e) => saveSettings({ pathway: e.target.value }));
         const ref = menu.querySelector('[data-inst-ref]');
@@ -528,6 +538,22 @@
     function instRow(label, inner) {
         return '<div><div class="text-[0.625rem] uppercase tracking-wider text-fb-textDim mb-1">' + label + '</div><div class="flex flex-wrap gap-1">' + inner + '</div></div>';
     }
+    // Handedness (left-handed) preference. The canonical store is the highway's
+    // `lefty` localStorage key; when a live highway exists, setLefty() also flips
+    // it immediately. Feature-detected so it works on the dashboard before any
+    // highway has been created (the value is read on the highway's next init).
+    function _leftyPref() {
+        try { if (window.highway && typeof window.highway.getLefty === 'function') return !!window.highway.getLefty(); } catch (_) { /* */ }
+        try { return localStorage.getItem('lefty') === '1'; } catch (_) { return false; }
+    }
+    function _setLeftyPref(on) {
+        try {
+            if (window.highway && typeof window.highway.setLefty === 'function') window.highway.setLefty(!!on);
+            else localStorage.setItem('lefty', on ? '1' : '0');
+        } catch (_) { /* storage blocked — the pill still reflects the choice via re-render */ }
+        // Keep the Settings "Left-handed" checkbox in sync when it's mounted.
+        try { const cb = document.getElementById('setting-lefty'); if (cb) cb.checked = !!on; } catch (_) { /* */ }
+    }
     function pill(group, val, label, active) {
         return '<button type="button" data-pill="' + group + '" data-val="' + val + '" class="px-2 py-1 rounded-md text-xs ' +
             (active ? 'bg-fb-primary text-white' : 'bg-gray-800/50 text-fb-textDim hover:text-fb-text') + '">' + esc(label) + '</button>';

static/v3/image-picker.js

@@ -0,0 +1,350 @@
+// Cover-art picker (PR-C — multi-candidate "change cover", media-server
+// style). ONE component: window.__fbOpenImagePicker({filename, title}),
+// reached from the Details drawer's art click and the card ⋮ "Change cover…".
+//
+// Anatomy mirrors match-review.js (body-appended singleton: overlay +
+// centred panel, light focus trap, Esc closes, overlay click closes) but
+// layers at z-[200] — the songs.js centered-modal tier — because one of its
+// openers is the details drawer (z-[61]), which sits above match-review's
+// z-40/50 pair.
+//
+// The design's key trick (§7-§9/§11 of the launch charrette): a pick never
+// grows a new write path. Choosing a CAA candidate POSTs its thumb URL to
+// the EXISTING …/art/url route (the override lane: never evicted, survives
+// a re-match); "Pack original" DELETEs the override; Upload POSTs the
+// existing …/art/upload (GIF stays upload-only + local-only; the server's
+// 10MB / http(s) guards apply to URLs). Success is silent (hearing-safe,
+// like the match layer): the modal just closes and the art refreshes.
+(function () {
+    'use strict';
+
+    const esc = (s) => String(s == null ? '' : s).replace(/[&<>"']/g, (c) => (
+        { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+    const enc = encodeURIComponent;
+
+    // Provenance badge text — same vocabulary as the match layer.
+    const PROV_LABEL = { yours: 'Yours', pack: 'Pack', matched: 'Matched' };
+
+    let _cur = null;        // {filename, title} while the picker is open
+    let _abort = null;      // in-flight candidates fetch — cancelled on close
+    let _busy = false;      // an apply is running — ignore further tile clicks
+    let _lastFocus = null;
+
+    const artBase = (fn) => '/api/song/' + enc(fn) + '/art';
+
+    // Post-apply refresh — the grid's cache-buster idiom (`?v=`): re-src
+    // every rendered <img> pointing at this song's art with a fresh v so the
+    // new pick paints everywhere it's currently shown (grid card, drawer
+    // preview, list row) without a full reload.
+    function refreshArt(fn) {
+        const base = artBase(fn);
+        document.querySelectorAll('img').forEach((img) => {
+            const src = img.getAttribute('src') || '';
+            if (src.split('?')[0] === base) {
+                img.src = base + '?v=' + Date.now();
+                img.style.visibility = 'visible';
+            }
+        });
+    }
+
+    function ensureModal() {
+        let m = document.getElementById('v3-imgpick-modal');
+        if (m) return m;
+        const overlay = document.createElement('div');
+        overlay.id = 'v3-imgpick-overlay';
+        overlay.className = 'fixed inset-0 bg-black/60 z-[200] hidden';
+        overlay.addEventListener('click', close);
+        document.body.appendChild(overlay);
+        m = document.createElement('div');
+        m.id = 'v3-imgpick-modal';
+        // Appended after the overlay: same z tier, DOM order paints it above.
+        m.className = 'fixed inset-0 z-[200] hidden flex items-center justify-center p-4 pointer-events-none';
+        m.innerHTML = '<div id="v3-imgpick-panel" class="pointer-events-auto w-full max-w-2xl max-h-[85vh] bg-fb-sidebar border border-fb-border/50 rounded-xl shadow-2xl flex flex-col" role="dialog" aria-label="Change cover"></div>';
+        m.addEventListener('keydown', onKeydown);
+        document.body.appendChild(m);
+        return m;
+    }
+
+    function onKeydown(e) {
+        if (e.key === 'Escape') { e.stopPropagation(); close(); return; }
+        if (e.key !== 'Tab') return;
+        // Light focus trap: cycle within the panel (mirrors match-review).
+        const panel = document.getElementById('v3-imgpick-panel');
+        if (!panel) return;
+        // Only trap VISIBLE focusables: hidden tiles (?source=pack 404 →
+        // onerror .hidden, unloadable candidates, .hidden buttons) must never
+        // catch a Tab. offsetParent is null for display:none / .hidden.
+        const foci = Array.from(
+            panel.querySelectorAll('button:not(.hidden), input:not(.hidden), [tabindex="0"]'),
+        ).filter((el) => el.offsetParent !== null);
+        if (!foci.length) return;
+        const first = foci[0], last = foci[foci.length - 1];
+        if (e.shiftKey && document.activeElement === first) { e.preventDefault(); last.focus(); }
+        else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus(); }
+    }
+
+    function close() {
+        if (_abort) { try { _abort.abort(); } catch (_) { /* already done */ } _abort = null; }
+        document.getElementById('v3-imgpick-modal')?.classList.add('hidden');
+        document.getElementById('v3-imgpick-overlay')?.classList.add('hidden');
+        _cur = null;
+        _busy = false;
+        if (_lastFocus && _lastFocus.isConnected) { try { _lastFocus.focus(); } catch (_) { /* */ } }
+        _lastFocus = null;
+    }
+
+    // One tile: a 6rem square art/icon face + a caption underneath.
+    function tileHtml(attrs, face, label, hidden) {
+        return '<button ' + attrs + ' class="group w-24 shrink-0 text-center' + (hidden ? ' hidden' : '') + '">' +
+            '<span class="w-24 h-24 rounded-lg overflow-hidden bg-fb-card border border-fb-border/50 hover:border-fb-primary/60 flex items-center justify-center">' + face + '</span>' +
+            '<span class="block text-xs text-fb-textDim group-hover:text-fb-text truncate pt-1">' + esc(label) + '</span></button>';
+    }
+    const imgFace = (src) => '<img src="' + esc(src) + '" alt="" loading="lazy" class="w-full h-full object-cover">';
+    const iconFace = (glyph) => '<span class="text-2xl text-fb-textDim">' + glyph + '</span>';
+
+    const SKELETON_TILE = '<span class="w-24 h-24 rounded-lg bg-fb-card animate-pulse shrink-0"></span>';
+
+    function render(panel) {
+        const fn = _cur.filename;
+        // Fresh ?v so a reopened picker never shows a stale "current".
+        const curSrc = artBase(fn) + '?v=' + Date.now();
+        panel.innerHTML =
+            '<div class="flex items-center justify-between gap-3 p-5 pb-3 border-b border-fb-border/40 shrink-0">' +
+            '<div class="min-w-0"><h3 class="text-lg font-semibold text-fb-text">Change cover</h3>' +
+            '<div class="text-xs text-fb-textDim truncate">' + esc(_cur.title || fn) + '</div></div>' +
+            '<button data-ip-close class="text-fb-textDim hover:text-fb-text" aria-label="Close">✕</button></div>' +
+
+            '<div class="p-5 flex flex-col sm:flex-row items-start gap-5 overflow-y-auto v3-scroll">' +
+            // Left: the current cover + its provenance.
+            '<div class="shrink-0">' +
+            '<img data-ip-current src="' + esc(curSrc) + '" alt="" class="w-24 h-24 rounded-lg object-cover bg-fb-card" onerror="this.style.visibility=\'hidden\'">' +
+            '<div class="pt-1 flex items-center gap-1.5">' +
+            '<span class="text-xs text-fb-textDim">Current</span>' +
+            '<span data-ip-prov class="hidden text-[0.625rem] px-1.5 py-0.5 rounded-full bg-gray-800/70 text-fb-textDim border border-gray-700"></span>' +
+            '</div></div>' +
+            // Right: the candidate tiles. First row acts instantly; CAA
+            // candidates land behind the one /art/candidates fetch.
+            '<div class="min-w-0 flex-1 space-y-3">' +
+            '<div class="flex flex-wrap gap-3">' +
+            tileHtml('data-ip-act="keep"', imgFace(curSrc), 'Current') +
+            // Pack tile renders instantly and self-hides when the song ships
+            // no art of its own (?source=pack 404s → img onerror); the
+            // candidates response reconciles it either way.
+            tileHtml('data-ip-act="pack"', imgFace(artBase(fn) + '?source=pack'), 'Pack original') +
+            tileHtml('data-ip-act="upload"', iconFace('⤒'), 'Upload') +
+            tileHtml('data-ip-act="url"', iconFace('🔗'), 'Paste URL') +
+            '</div>' +
+            '<div data-ip-caa>' +
+            '<div class="flex flex-wrap gap-3">' + SKELETON_TILE + SKELETON_TILE + SKELETON_TILE + '</div>' +
+            '<div class="text-xs text-fb-textDim pt-2">Fetching covers… the source is rate-limited.</div>' +
+            '</div>' +
+            // Search Cover Art Archive — find an album cover even when the song has
+            // no match (the auto candidates above are empty then). Pre-filled from
+            // the song's artist + album/title; the source is rate-limited.
+            '<div class="space-y-2 pt-1">' +
+            '<div class="text-xs font-semibold uppercase tracking-wider text-fb-textDim">Search covers</div>' +
+            '<div class="flex gap-2">' +
+            '<input data-ip-search-input type="text" value="' + esc(_cur.query || '') + '" placeholder="artist album" class="flex-1 bg-gray-800/50 border border-gray-700 rounded-md px-2 py-1 text-sm text-fb-text outline-none focus:border-fb-primary">' +
+            '<button data-ip-search-go class="text-sm text-fb-primary hover:text-fb-primaryHi border border-fb-primary/40 rounded-md px-3">Search</button>' +
+            '</div>' +
+            '<div data-ip-search-results class="flex flex-wrap gap-3"></div>' +
+            '</div>' +
+            '<div data-ip-status class="hidden text-xs text-fb-accent"></div>' +
+            '</div></div>' +
+            '<input type="file" accept="image/*" data-ip-file class="hidden">';
+
+        wire(panel);
+    }
+
+    function wire(panel) {
+        panel.querySelector('[data-ip-close]')?.addEventListener('click', close);
+        // The pack tile self-hides when there is no pack art to show.
+        const packTile = panel.querySelector('[data-ip-act="pack"]');
+        const packImg = packTile ? packTile.querySelector('img') : null;
+        if (packImg) packImg.onerror = () => packTile.classList.add('hidden');
+
+        const file = panel.querySelector('[data-ip-file]');
+        file?.addEventListener('change', () => {
+            const f = file.files && file.files[0];
+            if (!f) return;
+            const rd = new FileReader();
+            rd.onload = (e) => apply('upload', e.target.result);
+            rd.readAsDataURL(f);
+        });
+
+        panel.querySelectorAll('[data-ip-act]').forEach((btn) => {
+            btn.addEventListener('click', async () => {
+                if (_busy) return;
+                const act = btn.getAttribute('data-ip-act');
+                if (act === 'keep') { close(); return; }
+                if (act === 'pack') { apply('pack'); return; }
+                if (act === 'upload') { file?.click(); return; }
+                if (act === 'url') {
+                    // window.prompt is a silent no-op in Electron — use the
+                    // project's injection-safe async modal; fall back to prompt
+                    // only if it isn't loaded (mirrors other v3 callers' guard).
+                    const ask = (typeof window.uiPrompt === 'function')
+                        ? window.uiPrompt({
+                            title: 'Paste URL',
+                            label: 'Paste an image link (http or https)',
+                            okLabel: 'Set cover',
+                            placeholder: 'https://…',
+                        })
+                        : Promise.resolve(window.prompt('Paste an image link (http or https)'));
+                    const u = String((await ask) || '').trim();
+                    if (u) apply('url', u);
+                }
+            });
+        });
+        const searchInput = panel.querySelector('[data-ip-search-input]');
+        const runSearch = () => coverSearch(panel, (searchInput && searchInput.value) || '');
+        panel.querySelector('[data-ip-search-go]')?.addEventListener('click', runSearch);
+        searchInput?.addEventListener('keydown', (e) => { if (e.key === 'Enter') { e.preventDefault(); runSearch(); } });
+        panel.querySelector('[data-ip-close]')?.focus();
+    }
+
+    // Search Cover Art Archive (via the song-scoped cover-search endpoint) and
+    // render the album covers as pickable tiles — the same apply('url') path as
+    // the auto candidates. Covers with no CAA art self-hide (img onerror).
+    async function coverSearch(panel, query) {
+        const out = panel.querySelector('[data-ip-search-results]');
+        const fn = _cur && _cur.filename;
+        if (!out || !fn) return;
+        out.innerHTML = '<div class="flex flex-wrap gap-3">' + SKELETON_TILE + SKELETON_TILE + '</div>';
+        let body = null;
+        try {
+            const r = await fetch('/api/song/' + enc(fn) + '/art/cover-search?q=' + enc(String(query).trim()));
+            if (r.ok) body = await r.json();
+        } catch (_) { /* falls through to the empty state */ }
+        if (!_cur || _cur.filename !== fn) return;   // closed / changed song while searching
+        const covers = (body && body.covers) || [];
+        if (!covers.length) {
+            out.innerHTML = '<div class="text-xs text-fb-textDim">' +
+                ((body && body.error) ? 'Cover search is unavailable right now.' : 'No covers found — try a different search.') +
+                '</div>';
+            return;
+        }
+        out.innerHTML = covers.map((c, i) =>
+            tileHtml('data-ip-cover="' + i + '"', imgFace(c.thumb_url), c.label || 'Cover')).join('');
+        out.querySelectorAll('[data-ip-cover]').forEach((btn) => {
+            const img = btn.querySelector('img');
+            if (img) img.onerror = () => btn.classList.add('hidden');   // no CAA art for this album → hide
+            btn.addEventListener('click', () => {
+                if (_busy) return;
+                const c = covers[Number(btn.getAttribute('data-ip-cover'))];
+                if (c) apply('url', c.thumb_url);
+            });
+        });
+    }
+
+    // The one candidates fetch, cancelled if the modal closes first. Failure
+    // (offline, demo mode, aborted) is silent: the skeletons just clear and
+    // the instant tiles remain — never an error wall.
+    function loadCandidates(panel) {
+        const fn = _cur.filename;
+        // Reopening without an intervening close() can leave a prior fetch in
+        // flight — cancel it so only the newest request settles the tiles.
+        if (_abort) { try { _abort.abort(); } catch (_) { /* already done */ } }
+        _abort = new AbortController();
+        fetch('/api/song/' + enc(fn) + '/art/candidates', { signal: _abort.signal })
+            .then((r) => (r.ok ? r.json() : null))
+            .then((body) => { if (_cur && _cur.filename === fn) patchCandidates(panel, body); })
+            .catch(() => { if (_cur && _cur.filename === fn) patchCandidates(panel, null); });
+    }
+
+    function patchCandidates(panel, body) {
+        const wrap = panel.querySelector('[data-ip-caa]');
+        if (!wrap) return;
+        const list = (body && body.candidates) || [];
+        // Reconcile the instant tiles with what the server actually knows.
+        const cur = list.find((c) => c.kind === 'current');
+        const badge = panel.querySelector('[data-ip-prov]');
+        if (badge && cur && PROV_LABEL[cur.provenance]) {
+            badge.textContent = PROV_LABEL[cur.provenance];
+            badge.classList.remove('hidden');
+        }
+        const packTile = panel.querySelector('[data-ip-act="pack"]');
+        if (packTile) packTile.classList.toggle('hidden', !list.some((c) => c.kind === 'pack'));
+
+        const caa = list.filter((c) => c.kind === 'caa' && c.thumb_url);
+        if (!caa.length) { wrap.innerHTML = ''; return; }
+        wrap.innerHTML = '<div class="text-xs font-semibold uppercase tracking-wider text-fb-textDim pb-2">Online covers</div>' +
+            '<div class="flex flex-wrap gap-3">' +
+            caa.map((c, i) => tileHtml(
+                'data-ip-cand="' + i + '"',
+                imgFace(c.thumb_url),
+                c.label || 'Cover')).join('') +
+            '</div>';
+        wrap.querySelectorAll('[data-ip-cand]').forEach((btn) => {
+            // A candidate whose thumb can't load isn't offerable — hide it
+            // rather than let a click apply an image nobody saw.
+            const img = btn.querySelector('img');
+            if (img) img.onerror = () => btn.classList.add('hidden');
+            btn.addEventListener('click', () => {
+                if (_busy) return;
+                const c = caa[Number(btn.getAttribute('data-ip-cand'))];
+                if (c) apply('url', c.thumb_url);
+            });
+        });
+    }
+
+    // Apply a pick through the EXISTING routes; silent on success (close +
+    // cache-busted refresh), inline note on failure (the modal stays open so
+    // another tile can be tried).
+    async function apply(kind, arg) {
+        const fn = _cur && _cur.filename;
+        if (!fn || _busy) return;
+        _busy = true;
+        let ok = false;
+        try {
+            let r = null;
+            if (kind === 'url') {
+                r = await fetch('/api/song/' + enc(fn) + '/art/url', {
+                    method: 'POST', headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ url: arg }),
+                });
+            } else if (kind === 'upload') {
+                r = await fetch('/api/song/' + enc(fn) + '/art/upload', {
+                    method: 'POST', headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ image: arg }),
+                });
+            } else if (kind === 'pack') {
+                r = await fetch('/api/art/' + enc(fn) + '/override', { method: 'DELETE' });
+            }
+            if (r && r.ok) {
+                // The art routes report soft failures as {error} bodies.
+                const body = await r.json().catch(() => ({}));
+                ok = !body.error;
+            }
+        } catch (_) { ok = false; }
+        _busy = false;
+        if (ok) { close(); refreshArt(fn); return; }
+        const status = document.querySelector('#v3-imgpick-panel [data-ip-status]');
+        if (status) {
+            status.textContent = 'Couldn’t set that cover — try another image.';
+            status.classList.remove('hidden');
+        }
+    }
+
+    function openImagePicker(opts) {
+        const filename = opts && opts.filename;
+        if (!filename) return;
+        _lastFocus = document.activeElement;
+        const title = (opts && opts.title) || filename;
+        const artist = (opts && opts.artist) || '';
+        const album = (opts && opts.album) || '';
+        // Pre-fill the cover search: "artist album" when the album is known, else
+        // just the artist, else the title — the server default backs it up.
+        const query = [artist, album].filter(Boolean).join(' ').trim() || title;
+        _cur = { filename: filename, title: title, query: query };
+        _busy = false;
+        const m = ensureModal();
+        const panel = document.getElementById('v3-imgpick-panel');
+        render(panel);
+        m.classList.remove('hidden');
+        document.getElementById('v3-imgpick-overlay')?.classList.remove('hidden');
+        loadCandidates(panel);
+    }
+
+    window.__fbOpenImagePicker = openImagePicker;
+})();

static/v3/index.html

@@ -122,7 +122,7 @@
          the inline brand is the no-JS fallback. -->
     <aside id="v3-sidebar" class="w-64 border-r border-fb-border/50 flex-col shrink-0 hidden md:flex">
         <div id="v3-brand" class="p-6">
-            <span class="font-extrabold tracking-tight text-fb-text text-xl">fee<span class="text-fb-primary">[dB]</span>ack</span>
+            <img src="/static/v3/brand/feedback-logo-light.png" alt="fee[dB]ack" style="width:100%;height:auto;display:block">
         </div>
         <nav id="v3-nav" class="flex-1 overflow-y-auto px-3 pb-6 space-y-6" aria-label="Primary"></nav>
     </aside>
@@ -194,7 +194,7 @@
 
     <!-- Hidden file input shared by the navbar "Upload" link. Kept at body
          level so it stays reachable regardless of which screen is active. -->
-    <input type="file" id="upload-songs-file" accept=".sloppak" multiple class="hidden" onchange="uploadSongs(this.files); this.value=''">
+    <input type="file" id="upload-songs-file" accept=".feedpak,.sloppak" multiple class="hidden" onchange="uploadSongs(this.files); this.value=''">
 
     <!-- ══ HOME (Hero + Library) — reused as the v3 "Songs" screen ════════ -->
     <div id="home" class="screen">
@@ -641,7 +641,12 @@
                             </div>
                         </div>
                         <div class="fb-srow-control">
+                            <!-- Autosave on blur/enter via a single-key POST (like every other v3
+                                 setting), so setting the address never depends on the shared Save
+                                 button — whose bundled dlc_dir could otherwise block it. Save button
+                                 kept for discoverability. -->
                             <input type="text" id="demucs-server-url" placeholder="http://192.168.1.100:7865"
+                                onchange="persistSetting('demucs_server_url', this.value.trim())"
                                 class="bg-dark-700 border border-gray-800 rounded-xl px-4 py-2.5 text-sm text-gray-300 placeholder-gray-600 focus:border-accent/50 outline-none">
                             <button onclick="saveSettings()" class="bg-accent hover:bg-accent-light px-6 py-2.5 rounded-xl text-sm font-semibold text-white transition">Save</button>
                         </div>
@@ -788,6 +793,13 @@
                             </div>
                             <div class="text-[11px] text-gray-600 mt-1">What a confident match may fill in on its own — matches you confirm in the review queue always apply in full.</div>
                         </div>
+                        <!-- Audio fingerprint (AcoustID) — opt-in, default OFF. Wired by match-review.js. -->
+                        <div class="fb-srow-wide mb-1">
+                            <div class="text-[10px] uppercase tracking-wide text-gray-500 mb-1">Audio fingerprint (AcoustID)</div>
+                            <label class="flex items-center gap-2 text-xs text-gray-400 mb-1"><input type="checkbox" id="acoustid-enabled" class="rounded border-gray-600 bg-dark-700 text-accent"> Identify by audio — reads the recording itself for the exact version (studio vs live/extended)</label>
+                            <input type="text" id="acoustid-api-key" placeholder="AcoustID application key" class="w-full bg-dark-700 border border-gray-800 rounded-xl px-2 py-1.5 text-xs text-gray-300 outline-none">
+                            <div class="text-[11px] text-gray-600 mt-1">Opt-in. Get a free key at acoustid.org/new-application; the fpcalc (Chromaprint) binary must be on the server's PATH.</div>
+                        </div>
                         <div class="grid grid-cols-2 gap-2 mb-1 text-xs text-gray-400 fb-srow-wide">
                             <label class="flex items-center gap-2">Review queue order
                                 <select id="enrich-review-order" class="bg-dark-700 border border-gray-800 rounded-xl px-2 py-1.5 text-xs text-gray-300 outline-none">
@@ -802,6 +814,19 @@
                             <span id="enrich-status" class="text-xs text-gray-500"></span>
                         </div>
                     </div>
+                    <!-- Artist pages (PR-B — wired by static/v3/match-review.js). Sits
+                         beside the Metadata matching card; the Settings→Library tab
+                         regroup is a separate PR. -->
+                    <div class="fb-srow fb-srow-stack">
+                        <div class="fb-srow-main">
+                            <div class="fb-srow-title">Artist pages</div>
+                            <div class="fb-srow-desc">A page for every artist in your library — their songs, albums and your practice progress, built entirely from your local collection. External links (official site, tour dates, videos, social) come from one MusicBrainz lookup per matched artist and always open in your browser — nothing plays in-app, and they stay off until you opt in.</div>
+                        </div>
+                        <div class="grid grid-cols-2 gap-2 mb-1 text-xs text-gray-400 fb-srow-wide">
+                            <label class="flex items-center gap-2"><input type="checkbox" id="artist-pages-enabled" checked class="rounded border-gray-600 bg-dark-700 text-accent"> Artist pages</label>
+                            <label class="flex items-center gap-2"><input type="checkbox" id="artist-external-links" class="rounded border-gray-600 bg-dark-700 text-accent"> Show external links (opens your browser)</label>
+                        </div>
+                    </div>
                     <!-- Backup -->
                     <div class="fb-srow fb-srow-stack">
                         <div class="fb-srow-main">
@@ -1242,6 +1267,9 @@
     <!-- Before songs.js: the songs toolbar calls the match-review chip hook
          on build, so the module must already be registered. -->
     <script src="/static/v3/match-review.js"></script>
+    <!-- Before songs.js: the drawer art click + card ⋮ "Change cover…" open
+         the cover picker (window.__fbOpenImagePicker). -->
+    <script src="/static/v3/image-picker.js"></script>
     <script src="/static/v3/songs.js"></script>
     <script src="/static/v3/lessons.js"></script>
     <script src="/static/v3/dashboard.js"></script>

static/v3/match-review.js

@@ -35,9 +35,52 @@
     // ── Ambient chip + the Settings card's status line ───────────────────────
     // songs.js renders `#v3-songs-match-review` (hidden) in its toolbar and
     // calls window.__fbMatchReviewChip() after each toolbar build; review
-    // actions here re-call it. The same fetch feeds the Settings status line.
+    // actions here re-call it. The same fetch feeds the Settings status line
+    // and, while a pass is running, a quiet toolbar progress line (below).
     // Silent on failure — surfaces just stay as they are.
     let _chipBusy = false;
+    let _pollTimer = null;   // 5s status poll, alive ONLY while a pass runs
+
+    // Quiet library-visible progress (launch polish): a plain text line next
+    // to the review chip while the background pass is working through the
+    // queue — "Matching your library — X of Y". No toast, no sound; it simply
+    // disappears when the pass finishes (hearing-safe, design §11).
+    function _setProgressLine(running, states, total) {
+        let el = document.getElementById('v3-songs-match-progress');
+        const unscanned = states.unscanned || 0;
+        if (!running || unscanned <= 0 || total <= 0) {
+            if (el) el.remove();
+            return;
+        }
+        if (!el) {
+            const chip = document.getElementById('v3-songs-match-review');
+            if (!chip || !chip.parentElement) return;   // songs toolbar not on screen
+            el = document.createElement('span');
+            el.id = 'v3-songs-match-progress';
+            el.className = 'text-xs text-fb-textDim';
+            chip.insertAdjacentElement('afterend', el);
+        }
+        el.textContent = 'Matching your library — ' + Math.max(0, total - unscanned) + ' of ' + total;
+    }
+
+    // One-time transparency toast (launch polish): the first time this
+    // install is observed actually matching a real library, say plainly what
+    // is contacted, where results live, and where the switch is. Wrapped like
+    // app.js's fbNotify calls so a blocked localStorage / absent notifier can
+    // never break the chip.
+    function _announceOnce(running, total) {
+        try {
+            if (!running || total <= 0) return;
+            if (localStorage.getItem('fb_enrich_announce_v1')) return;
+            localStorage.setItem('fb_enrich_announce_v1', '1');
+            window.fbNotify?.show({
+                title: 'Library matching is on',
+                message: 'Song info and covers come from MusicBrainz and Cover Art Archive, stored locally. Your files are never changed unless you choose to write to them. Adjust in Settings → Library.',
+                icon: '📚',
+            });
+        } catch (_) { /* storage/notifier unavailable — skip quietly */ }
+    }
+
     async function refreshChip() {
         if (_chipBusy) return;
         _chipBusy = true;
@@ -62,7 +105,24 @@
                 if (st.unscanned) parts.push(st.unscanned + ' queued');
                 line.textContent = (body.running ? 'Matching… · ' : '') + parts.join(' · ');
             }
-        } catch (_) { /* offline — leave as-is */ } finally {
+            const running = !!body.running;
+            const total = body.total_songs || 0;
+            _setProgressLine(running, st, total);
+            _announceOnce(running, total);
+            // Poll only while a pass is actually running; a single guarded
+            // interval, cleared the moment the pass stops (no leaks).
+            if (running && !_pollTimer) {
+                _pollTimer = setInterval(refreshChip, 5000);
+            } else if (!running && _pollTimer) {
+                clearInterval(_pollTimer);
+                _pollTimer = null;
+            }
+        } catch (_) {
+            // Offline — leave surfaces as they are, but stop any poll so a
+            // dead server isn't pinged every 5s forever (the next toolbar
+            // build / settings open restarts it if a pass is still running).
+            if (_pollTimer) { clearInterval(_pollTimer); _pollTimer = null; }
+        } finally {
             _chipBusy = false;
         }
     }
@@ -71,7 +131,8 @@
     let _queue = [];
     let _idx = 0;
     let _lastFocus = null;
-    let _single = false;   // Fix-match mode: one song, no queue navigation
+    let _single = false;   // Fix-metadata mode: one song, no queue navigation
+    let _tab = 'details';  // active tab in single mode: details | cover | match
 
     function ensureModal() {
         let m = document.getElementById('v3-match-modal');
@@ -120,14 +181,17 @@
         loadQueue();
     }
 
-    // Fix-match (R2): the same modal for ONE song — the escape hatch for a
-    // wrong (or missing) match, reachable from the card's ⋮ / right-click
-    // menu. No stored candidates are required: the search panel opens
-    // pre-filled, and a pick pins the match exactly like the review flow.
+    // Fix metadata (R2 → popup slice 4): the tabbed per-song editor for ONE
+    // song, reachable from the card's ⋮ / right-click menu. Three tabs —
+    // Details (type + lock the displayed fields), Cover art (launch the picker),
+    // Match (pin a MusicBrainz identity). Opens on Details: for the obscure /
+    // blank-artist packs this exists to fix, typing the right title is the tool,
+    // and Match is the escape hatch when text search can surface a record.
     function fixMatch(song) {
         if (!song || !song.filename) return;
         _lastFocus = document.activeElement;
         _single = true;
+        _tab = 'details';
         _queue = [{
             filename: song.filename, title: song.title || song.filename,
             artist: song.artist || '', album: song.album || '',
@@ -138,10 +202,7 @@
         const m = ensureModal();
         m.classList.remove('hidden');
         document.getElementById('v3-match-overlay')?.classList.remove('hidden');
-        renderCurrent();
-        // Straight to the point: the search panel is why this mode exists.
-        document.getElementById('v3-match-panel')
-            ?.querySelector('[data-mr-search-toggle]')?.click();
+        renderCurrent();   // _single ⇒ renderTabbed()
     }
 
     function closeModal() {
@@ -154,7 +215,7 @@
     }
 
     function nav(step) {
-        if (!_queue.length) return;
+        if (_single || !_queue.length) return;   // single mode has no queue to page
         _idx = Math.min(Math.max(_idx + step, 0), _queue.length - 1);
         renderCurrent();
     }
@@ -242,20 +303,20 @@
             '<span class="text-xs text-fb-textDim shrink-0">' + esc(pct) + '</span></span>' +
             '<span class="block text-xs text-fb-textDim truncate">' + esc(meta) + '</span>' +
             diffChips(song, c) +
+            (_single ? '<span class="block text-xs text-fb-primary pt-1">Use these values →</span>' : '') +
             '</button>';
     }
 
-    function renderCurrent() {
-        const panel = document.getElementById('v3-match-panel');
-        if (!panel) return;
-        if (!_queue.length) { renderDone(); return; }
-        _idx = Math.min(_idx, _queue.length - 1);
-        const song = _queue[_idx];
-        if (song._sel == null) song._sel = 0;
+    // The middle content shared by the queue-review render and the single-song
+    // popup's Match tab: the chart being matched, its candidate list, and the
+    // "search instead" panel. Header + footer differ per surface. When there
+    // are no stored candidates (a manual fix), the search panel opens pre-filled
+    // — searching IS the point in that case.
+    function reviewBodyHtml(song) {
         const sub = [song.artist, song.album, song.year, fmtDur(song.duration)].filter(Boolean).join(' · ');
-
-        panel.innerHTML = headerHtml() +
-            '<div class="p-5 space-y-4 overflow-y-auto v3-scroll">' +
+        const noCands = !(song.candidates || []).length;
+        const prefill = noCands ? [song.artist, song.title].filter(Boolean).join(' – ') : '';
+        return '<div class="p-5 space-y-4 overflow-y-auto v3-scroll min-h-0">' +
             // The chart being matched
             '<div class="flex items-start gap-3">' +
             '<img data-mr-art src="' + esc(artUrl(song)) + '" alt="" loading="lazy" class="w-16 h-16 rounded-lg object-cover bg-fb-card shrink-0">' +
@@ -265,82 +326,391 @@
             '<div class="text-xs text-fb-textDim/70 truncate" title="' + esc(song.filename) + '">' + esc(song.filename) + '</div>' +
             missingChips(song) +
             '</div></div>' +
-            // Candidates (Fix-match mode arrives with none — the search panel
-            // is its whole point, so the empty header is suppressed).
-            ((song.candidates || []).length
-                ? '<div class="space-y-1" role="radiogroup" aria-label="Candidates">' +
+            (noCands
+                ? ''
+                : '<div class="space-y-1" role="radiogroup" aria-label="Candidates">' +
                 '<div class="text-xs font-semibold uppercase tracking-wider text-fb-textDim">Candidates (MusicBrainz)</div>' +
                 song.candidates.map((c, i) => candRowHtml(song, c, i, i === song._sel)).join('') +
-                '</div>'
-                : '') +
-            // Search-instead panel
-            '<div data-mr-search-panel class="hidden space-y-2">' +
+                '</div>') +
+            // Search panel — hidden when candidates exist (a "Search instead…"
+            // toggle reveals it); open + pre-filled when there are none.
+            '<div data-mr-search-panel class="' + (noCands ? '' : 'hidden') + ' space-y-2">' +
             '<div class="flex gap-2">' +
-            '<input data-mr-search-input type="text" class="flex-1 bg-gray-800/50 border border-gray-700 rounded-md px-2 py-1 text-sm text-fb-text outline-none focus:border-fb-primary" placeholder="Artist – Title">' +
+            '<input data-mr-search-input type="text" value="' + esc(prefill) + '" class="flex-1 bg-gray-800/50 border border-gray-700 rounded-md px-2 py-1 text-sm text-fb-text outline-none focus:border-fb-primary" placeholder="Artist – Title">' +
             '<button data-mr-search-go class="text-sm text-fb-primary hover:text-fb-primaryHi border border-fb-primary/40 rounded-md px-3">Search</button></div>' +
             '<div data-mr-search-results class="space-y-1"></div></div>' +
-            '</div>' +
-            // Footer actions. Fix-match mode drops Skip (no queue) and the
-            // accept button when there is nothing to accept — search-result
-            // rows carry their own pick action.
-            '<div class="flex items-center justify-between gap-3 p-5 pt-3 border-t border-fb-border/40 shrink-0">' +
+            '</div>';
+    }
+
+    // Footer actions. Single mode drops Skip / Not-a-match (no queue); the
+    // accept button only shows when there is a stored candidate to accept —
+    // search-result rows carry their own pick action.
+    function footerHtml(song) {
+        return '<div class="flex items-center justify-between gap-3 p-5 pt-3 border-t border-fb-border/40 shrink-0">' +
             '<div class="flex items-center gap-3">' +
             (_single ? '' : '<button data-mr-reject class="text-sm text-fb-textDim hover:text-fb-text">Not a match</button>') +
-            '<button data-mr-search-toggle class="text-sm text-fb-textDim hover:text-fb-text">Search instead…</button></div>' +
+            '<button data-mr-search-toggle class="text-sm text-fb-textDim hover:text-fb-text">Search instead…</button>' +
+            '<button data-mr-identify class="text-sm text-fb-primary hover:text-fb-primaryHi" title="Fingerprint this song\'s audio to find the exact recording">Identify by audio</button></div>' +
             '<div class="flex items-center gap-2">' +
             (_single ? '' : '<button data-mr-skip class="text-sm text-fb-textDim hover:text-fb-text px-3 py-2">Skip</button>') +
             ((song.candidates || []).length ? '<button data-mr-accept class="bg-fb-primary hover:bg-fb-primaryHi text-white px-4 py-2 rounded-md text-sm">Use selected</button>' : '') +
             '</div></div>';
-
-        wireCurrent(panel, song);
     }
 
-    function wireCurrent(panel, song) {
+    function renderCurrent() {
+        const panel = document.getElementById('v3-match-panel');
+        if (!panel) return;
+        if (_single) { renderTabbed(); return; }   // popup: the tabbed shell
+        if (!_queue.length) { renderDone(); return; }
+        _idx = Math.min(_idx, _queue.length - 1);
+        const song = _queue[_idx];
+        if (song._sel == null) song._sel = 0;
+        panel.innerHTML = headerHtml() + reviewBodyHtml(song) + footerHtml(song);
         panel.querySelector('[data-mr-close]')?.addEventListener('click', closeModal);
         panel.querySelector('[data-mr-prev]')?.addEventListener('click', () => nav(-1));
         panel.querySelector('[data-mr-next]')?.addEventListener('click', () => nav(1));
         panel.querySelector('[data-mr-skip]')?.addEventListener('click', () => nav(1));
+        wireReviewBody(panel, song);
+    }
+
+    // Candidate / search / accept-reject wiring shared by the queue render and
+    // the popup's Match tab. Scoped to `root` so the tabbed shell can wire just
+    // its tab body — its close + tab chrome live in the header (wired once by
+    // renderTabbed), so wiring here must NOT touch close/prev/next/skip.
+    function wireReviewBody(root, song) {
         // Art failure → flag + re-render once so the "cover art" chip shows.
-        const img = panel.querySelector('[data-mr-art]');
+        const img = root.querySelector('[data-mr-art]');
         if (img) img.onerror = () => {
             img.style.visibility = 'hidden';
             if (!song._artMissing) { song._artMissing = true; renderCurrent(); }
         };
-        panel.querySelectorAll('[data-mr-cand]').forEach((btn) => {
+        root.querySelectorAll('[data-mr-cand]').forEach((btn) => {
             btn.addEventListener('click', () => {
                 song._sel = Number(btn.getAttribute('data-mr-cand'));
                 renderCurrent();
             });
         });
-        panel.querySelector('[data-mr-accept]')?.addEventListener('click', async () => {
+        root.querySelector('[data-mr-accept]')?.addEventListener('click', async () => {
             const cand = (song.candidates || [])[song._sel || 0];
             if (!cand) return;
             await post('/api/enrichment/review/' + enc(song.filename) + '/accept',
                 { recording_id: cand.recording_id });
             settle(song);
         });
-        panel.querySelector('[data-mr-reject]')?.addEventListener('click', async () => {
+        root.querySelector('[data-mr-reject]')?.addEventListener('click', async () => {
             await post('/api/enrichment/review/' + enc(song.filename) + '/reject');
             settle(song);
         });
-        const sp = panel.querySelector('[data-mr-search-panel]');
-        const input = panel.querySelector('[data-mr-search-input]');
-        panel.querySelector('[data-mr-search-toggle]')?.addEventListener('click', () => {
+        const sp = root.querySelector('[data-mr-search-panel]');
+        const input = root.querySelector('[data-mr-search-input]');
+        root.querySelector('[data-mr-search-toggle]')?.addEventListener('click', () => {
             sp?.classList.toggle('hidden');
             if (sp && !sp.classList.contains('hidden') && input && !input.value) {
                 input.value = [song.artist, song.title].filter(Boolean).join(' – ');
                 input.focus();
             }
         });
-        const go = () => runSearch(panel, song);
-        panel.querySelector('[data-mr-search-go]')?.addEventListener('click', go);
+        const go = () => runSearch(root, song);
+        root.querySelector('[data-mr-search-go]')?.addEventListener('click', go);
         input?.addEventListener('keydown', (e) => { if (e.key === 'Enter') { e.preventDefault(); go(); } });
+        // Identify-by-audio (AcoustID, #759) renders its hits into the same
+        // search-results area — scope to `root` (the tab body / panel), not the
+        // out-of-scope `panel` the pre-refactor #759 wiring referenced.
+        root.querySelector('[data-mr-identify]')?.addEventListener('click', () => runIdentify(root, song));
+    }
+
+    // ── Tabbed single-song popup (slice 4) ───────────────────────────────────
+    // Header + tab bar, then the active tab's body. The queue-review render
+    // above is untouched; this is only reached in _single mode.
+    function tabHeaderHtml() {
+        const tab = (id, label) =>
+            '<button data-mr-tab="' + id + '" role="tab" aria-selected="' + (_tab === id ? 'true' : 'false') + '" ' +
+            'class="px-3 py-2 text-sm -mb-px border-b-2 ' + (_tab === id
+                ? 'border-fb-primary text-fb-text'
+                : 'border-transparent text-fb-textDim hover:text-fb-text') + '">' + label + '</button>';
+        return '<div class="flex items-center justify-between gap-3 px-5 pt-4 shrink-0">' +
+            '<h3 class="text-lg font-semibold text-fb-text">Fix metadata</h3>' +
+            '<button data-mr-close class="text-fb-textDim hover:text-fb-text" aria-label="Close">✕</button></div>' +
+            '<div role="tablist" class="flex gap-1 px-4 border-b border-fb-border/40 shrink-0">' +
+            tab('details', 'Details') + tab('cover', 'Cover art') + tab('match', 'Match') + '</div>';
+    }
+
+    function renderTabbed() {
+        const panel = document.getElementById('v3-match-panel');
+        if (!panel) return;
+        const song = _queue[0];
+        if (!song) { closeModal(); return; }
+        panel.innerHTML = tabHeaderHtml() +
+            '<div data-mr-tabbody role="tabpanel" class="flex flex-col min-h-0 flex-1 overflow-hidden"></div>';
+        panel.querySelector('[data-mr-close]')?.addEventListener('click', closeModal);
+        panel.querySelectorAll('[data-mr-tab]').forEach((b) => b.addEventListener('click', () => {
+            const t = b.getAttribute('data-mr-tab');
+            if (t !== _tab) { _tab = t; renderTabbed(); }
+        }));
+        const body = panel.querySelector('[data-mr-tabbody]');
+        if (_tab === 'details') { renderDetailsTab(body, song); }
+        else if (_tab === 'cover') { renderCoverTab(body, song); }
+        else {
+            body.innerHTML = reviewBodyHtml(song) + footerHtml(song);
+            wireReviewBody(body, song);
+            if (!(song.candidates || []).length) body.querySelector('[data-mr-search-input]')?.focus();
+        }
+    }
+
+    // Details tab: type + lock the DISPLAYED fields. Values ride the reversible
+    // override store (GET/PUT /api/song/{fn}/overrides) — never the pack file.
+    // Each field sits on its pack value: editing above the pack makes it an
+    // override ("Yours"); a lock pins it so an auto-match can't recanonicalize
+    // it; revert (↺) drops back to the pack value.
+    const DETAIL_FIELDS = [['title', 'Title'], ['artist', 'Artist'], ['album', 'Album'], ['year', 'Year'], ['genre', 'Genre']];
+    // Only these four are written into the pack file; genre is a library-only
+    // overlay (drives the genre filter/facet + the auto-match lock), never baked
+    // to the file — so Write to file leaves genre's override in place.
+    const WRITE_FIELDS = ['title', 'artist', 'album', 'year'];
+
+    async function renderDetailsTab(body, song) {
+        body.innerHTML = '<div class="p-5"><p class="text-sm text-fb-textDim">Loading…</p></div>';
+        let data = { overrides: {}, pack: {} };
+        try {
+            const r = await fetch('/api/song/' + enc(song.filename) + '/overrides');
+            if (r.ok) data = await r.json();
+        } catch (_) { /* offline — fall back to the empty baseline */ }
+        if (!_single || _tab !== 'details') return;   // tab/modal changed while fetching
+        const pack = data.pack || {};
+        const ov = data.overrides || {};
+        const st = {};
+        for (const [f] of DETAIL_FIELDS) {
+            const o = ov[f] || {};
+            st[f] = {
+                pack: pack[f] || '',
+                value: (o.value != null ? o.value : (pack[f] || '')),
+                locked: !!o.locked,
+            };
+        }
+        song._detailsState = st;
+        // Match→Details bridge: a candidate picked with "Use these values" lands
+        // its fields here as the pending (unsaved) input values, shown pre-filled
+        // for review — the grid never adopts a match silently, so the user still
+        // Saves (or Writes to file).
+        const adopted = song._pendingDetails;
+        if (adopted) {
+            for (const [f] of DETAIL_FIELDS) {
+                if (f in adopted) st[f].value = String(adopted[f] || '');
+            }
+            song._pendingDetails = null;
+        }
+        paintDetails(body, song);
+        if (adopted) {
+            const s = body.querySelector('[data-df-status]');
+            if (s) { s.className = 'text-xs leading-relaxed text-fb-textDim'; s.textContent = 'Filled from the match — review, then Save or Write to file.'; }
+        }
+    }
+
+    // Match→Details bridge: adopt a candidate's display fields into the Details
+    // tab (opt-in — never silent). Pin the match too so the art/canon follow,
+    // then land on Details pre-filled for review.
+    async function useTheseValues(song, cand) {
+        if (!cand) return;
+        // Smart adopt for an English base: KEEP the readable name + title the card
+        // already shows (the author's romaji, e.g. "Junko Yagami / BAY CITY") — the
+        // match is often native script (kanji/kana). Take only what the pack lacks
+        // — album / year / genre — from the match; the pin below still brings the
+        // correct art + identity. The user can still edit any field.
+        song._pendingDetails = {
+            artist: String(song.artist || cand.artist || ''),
+            title:  String(song.title  || cand.title  || ''),
+            album:  String(cand.album  || song.album  || ''),
+            year:   String(cand.year   || song.year   || ''),
+            genre:  String((Array.isArray(cand.genres) && cand.genres[0]) || cand.genre || ''),
+        };
+        try {
+            await post('/api/enrichment/review/' + enc(song.filename) + '/pick', { candidate: cand });
+        } catch (_) { /* pin is best-effort; the values still populate Details */ }
+        try { window.feedBack?.emit('library:changed', { reason: 'match' }); } catch (_) { }
+        _tab = 'details';
+        renderTabbed();
+    }
+
+    function paintDetails(body, song) {
+        const st = song._detailsState;
+        const row = ([f, label]) => {
+            const s = st[f];
+            const isYours = !!(String(s.value).trim() && String(s.value).trim() !== String(s.pack).trim());
+            return '<div class="space-y-1">' +
+                '<div class="flex items-center justify-between">' +
+                '<label class="text-xs font-semibold uppercase tracking-wider text-fb-textDim">' + esc(label) + '</label>' +
+                (isYours
+                    ? '<span class="text-[0.625rem] px-1.5 py-0.5 rounded bg-fb-primary/15 text-fb-primary">Yours</span>'
+                    : '<span class="text-[0.625rem] px-1.5 py-0.5 rounded bg-fb-card text-fb-textDim">Pack</span>') +
+                '</div>' +
+                '<div class="flex items-center gap-2">' +
+                '<input data-df-input="' + f + '" type="text" value="' + esc(s.value) + '" ' +
+                'class="flex-1 bg-gray-800/50 border border-gray-700 rounded-md px-2 py-1.5 text-sm text-fb-text outline-none focus:border-fb-primary" ' +
+                'placeholder="' + esc(s.pack || label) + '">' +
+                '<button data-df-lock="' + f + '" type="button" aria-pressed="' + (s.locked ? 'true' : 'false') + '" ' +
+                'title="' + (s.locked ? 'Locked — auto-match won’t change this field' : 'Lock this field against auto-match') + '" ' +
+                'class="px-2 py-1.5 rounded-md border ' + (s.locked ? 'border-fb-primary text-fb-primary bg-fb-primary/10' : 'border-fb-border/50 text-fb-textDim hover:text-fb-text') + '">' +
+                (s.locked ? '🔒' : '🔓') + '</button>' +
+                '<button data-df-revert="' + f + '" type="button" title="Revert to the pack value" ' +
+                'class="px-2 py-1.5 rounded-md border border-fb-border/50 text-fb-textDim hover:text-fb-text">↺</button>' +
+                '</div></div>';
+        };
+        body.innerHTML =
+            '<div class="p-5 space-y-4 overflow-y-auto v3-scroll min-h-0">' +
+            '<div class="flex items-start gap-3">' +
+            '<img src="' + esc(artUrl(song)) + '" alt="" onerror="this.style.visibility=\'hidden\'" class="w-14 h-14 rounded-lg object-cover bg-fb-card shrink-0">' +
+            '<p class="text-xs text-fb-textDim pt-1"><span class="text-fb-text">Save</span> keeps edits as a reversible library overlay — the song files aren\'t touched. <span class="text-fb-text">Write to file</span> bakes the title, artist, album and year into the pack (genre stays a library-only tag). Lock a field to keep an auto-match from changing it.</p>' +
+            '</div>' +
+            DETAIL_FIELDS.map(row).join('') +
+            '<p data-df-status class="text-xs leading-relaxed"></p>' +
+            '</div>' +
+            '<div class="flex items-center justify-between gap-2 p-5 pt-3 border-t border-fb-border/40 shrink-0">' +
+            '<button data-df-write type="button" title="Write these values into the song file itself — permanent, survives a full rescan. The rest of the pack is untouched." class="text-sm text-fb-textDim hover:text-fb-text border border-fb-border/50 rounded-md px-3 py-2">Write to file</button>' +
+            '<button data-df-save class="bg-fb-primary hover:bg-fb-primaryHi text-white px-4 py-2 rounded-md text-sm">Save</button>' +
+            '</div>';
+        body.querySelectorAll('[data-df-input]').forEach((inp) => {
+            inp.addEventListener('input', () => { st[inp.getAttribute('data-df-input')].value = inp.value; });
+        });
+        body.querySelectorAll('[data-df-lock]').forEach((b) => {
+            b.addEventListener('click', () => { const f = b.getAttribute('data-df-lock'); st[f].locked = !st[f].locked; paintDetails(body, song); });
+        });
+        body.querySelectorAll('[data-df-revert]').forEach((b) => {
+            b.addEventListener('click', () => { const f = b.getAttribute('data-df-revert'); st[f].value = st[f].pack || ''; st[f].locked = false; paintDetails(body, song); });
+        });
+        body.querySelector('[data-df-save]')?.addEventListener('click', () => saveDetails(body, song));
+        body.querySelector('[data-df-write]')?.addEventListener('click', () => writeToFile(body, song));
+    }
+
+    async function saveDetails(body, song) {
+        const st = song._detailsState;
+        const overrides = {};
+        for (const [f] of DETAIL_FIELDS) {
+            const v = String(st[f].value || '').trim();
+            const p = String(st[f].pack || '').trim();
+            // Only store a value that differs from the pack; equal / blank clears
+            // the override (the server drops a value-less, unlocked row).
+            overrides[f] = { value: (v && v !== p) ? v : null, locked: !!st[f].locked };
+        }
+        const status = body.querySelector('[data-df-status]');
+        const saveBtn = body.querySelector('[data-df-save]');
+        if (saveBtn) saveBtn.disabled = true;
+        let ok = false;
+        try {
+            const r = await fetch('/api/song/' + enc(song.filename) + '/overrides', {
+                method: 'PUT',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ overrides }),
+            });
+            ok = r.ok;
+        } catch (_) { ok = false; }
+        if (saveBtn) saveBtn.disabled = false;
+        if (!ok) {
+            if (status) { status.className = 'text-xs h-4 text-fb-accent'; status.textContent = 'Could not save — try again.'; }
+            return;
+        }
+        // Reflect the new effective values on the in-memory song (keeps the Match
+        // tab header consistent) and repaint the library so the card shows them —
+        // the grid reloads on library:changed (slice 3 overlay does the rest).
+        for (const [f] of DETAIL_FIELDS) {
+            const v = String(st[f].value || '').trim(); const p = String(st[f].pack || '').trim();
+            song[f] = (v && v !== p) ? v : (st[f].pack || '');
+        }
+        try { window.feedBack?.emit('library:changed', { reason: 'override' }); } catch (_) { }
+        if (status) { status.className = 'text-xs h-4 text-fb-good'; status.textContent = 'Saved.'; }
+    }
+
+    // "Write to file" — bake the shown title/artist/album/year INTO the pack
+    // itself (the one action here that touches the file), via the existing
+    // POST /api/song/{fn}/meta (writes the manifest, re-stats, coalesces a
+    // rescan). On a real file write the display overrides for those fields are
+    // now redundant, so clear their VALUES (keeping any locks) and re-render —
+    // the field then reads from the file as "Pack". Loose-folder / unwritable
+    // packs fall back to a DB-only update: we say so and keep the overlay.
+    async function writeToFile(body, song) {
+        const st = song._detailsState;
+        const fields = {};
+        for (const f of WRITE_FIELDS) fields[f] = String(st[f].value || '').trim();
+        const status = body.querySelector('[data-df-status]');
+        const writeBtn = body.querySelector('[data-df-write]');
+        const saveBtn = body.querySelector('[data-df-save]');
+        if (writeBtn) writeBtn.disabled = true;
+        if (saveBtn) saveBtn.disabled = true;
+        if (status) { status.className = 'text-xs leading-relaxed text-fb-textDim'; status.textContent = 'Writing to the song file…'; }
+        let ok = false, persisted = false;
+        try {
+            const r = await fetch('/api/song/' + enc(song.filename) + '/meta', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(fields),
+            });
+            ok = r.ok;
+            const j = await r.json().catch(() => ({}));
+            persisted = !!(j && j.persisted);
+        } catch (_) { ok = false; }
+        if (writeBtn) writeBtn.disabled = false;
+        if (saveBtn) saveBtn.disabled = false;
+        if (!ok) {
+            if (status) { status.className = 'text-xs leading-relaxed text-fb-accent'; status.textContent = 'Could not write to the file — try again.'; }
+            return;
+        }
+        // Keep the in-memory song + grid in step with what was *persisted*, not
+        // the raw input: the server coerces a non-numeric/empty year to "" (see
+        // update_song_meta), so mirror that here or the grid card flashes the
+        // typed text (e.g. "abcd") until the next natural refresh corrects it.
+        const applied = { ...fields };
+        if ('year' in applied) {
+            const yr = /^[+-]?\d+$/.test(applied.year) ? parseInt(applied.year, 10) : 0;
+            applied.year = yr ? String(yr) : '';
+        }
+        for (const f of WRITE_FIELDS) song[f] = applied[f];
+        try { window.feedBack?.emit('library:changed', { reason: 'write' }); } catch (_) { }
+        if (persisted) {
+            const clear = {};
+            for (const f of WRITE_FIELDS) clear[f] = { value: null, locked: !!st[f].locked };
+            try {
+                await fetch('/api/song/' + enc(song.filename) + '/overrides', {
+                    method: 'PUT',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ overrides: clear }),
+                });
+            } catch (_) { /* the file write still succeeded; the overlay just lingers */ }
+            await renderDetailsTab(body, song);   // re-fetch: pack now = written values, overrides cleared
+            const s2 = body.querySelector('[data-df-status]');
+            if (s2) { s2.className = 'text-xs leading-relaxed text-fb-good'; s2.textContent = 'Written to the song file.'; }
+        } else if (status) {
+            status.className = 'text-xs leading-relaxed text-fb-textDim';
+            status.textContent = 'Saved to the library — this pack’s file couldn’t be written, so it may revert on a full rescan.';
+        }
+    }
+
+    // Cover-art tab: the current art + a button that hands off to the shared
+    // cover picker (image-picker.js, its own z-[200] modal). A pick there
+    // refreshes every <img> for this song's art — including this thumbnail — so
+    // there's nothing to wire back.
+    function renderCoverTab(body, song) {
+        body.innerHTML =
+            '<div class="p-5 space-y-4 overflow-y-auto v3-scroll min-h-0 flex flex-col items-center text-center">' +
+            '<img src="' + esc(artUrl(song)) + '" alt="" onerror="this.style.visibility=\'hidden\'" class="w-40 h-40 rounded-xl object-cover bg-fb-card">' +
+            '<p class="text-sm text-fb-textDim max-w-sm">Choose from the Cover Art Archive, paste an image link, or upload your own. Your song files are never changed.</p>' +
+            '<button data-cover-open class="bg-fb-primary hover:bg-fb-primaryHi text-white px-4 py-2 rounded-md text-sm">Choose cover art…</button>' +
+            '</div>';
+        body.querySelector('[data-cover-open]')?.addEventListener('click', () => {
+            if (window.__fbOpenImagePicker) {
+                window.__fbOpenImagePicker({ filename: song.filename, title: song.title || song.filename, artist: song.artist, album: song.album });
+            }
+        });
     }
 
     // Silent-on-success: the chart just leaves the queue and the next one
     // renders; the last one renders the done state. No toasts, no sounds.
     function settle(song) {
-        if (_single) { closeModal(); return; }   // Fix-match: done means done
+        if (_single) {
+            // Popup Match tab: a pinned identity can change the art/canon — nudge
+            // the grid to repaint (silent otherwise, like the queue flow).
+            try { window.feedBack?.emit('library:changed', { reason: 'match' }); } catch (_) { }
+            closeModal();
+            return;
+        }
         const i = _queue.indexOf(song);
         if (i >= 0) _queue.splice(i, 1);
         if (_idx >= _queue.length) _idx = Math.max(0, _queue.length - 1);
@@ -380,6 +750,60 @@
             btn.addEventListener('click', async () => {
                 const cand = cands[Number(btn.getAttribute('data-mr-cand'))];
                 if (!cand) return;
+                if (_single) { useTheseValues(song, cand); return; }   // popup → adopt into Details
+                await post('/api/enrichment/review/' + enc(song.filename) + '/pick',
+                    { candidate: cand });
+                settle(song);
+            });
+        });
+    }
+
+    // "Identify by audio" — fingerprint the song's OWN master audio (AcoustID)
+    // and render the hits into the same search-results area. The reliable path
+    // when text search can't tell the studio take from live/comp versions.
+    async function runIdentify(panel, song) {
+        const out = panel.querySelector('[data-mr-search-results]');
+        const sp = panel.querySelector('[data-mr-search-panel]');
+        if (!out) return;
+        sp?.classList.remove('hidden');   // give the results somewhere to render
+        out.innerHTML = '<p class="text-xs text-fb-textDim">Fingerprinting audio…</p>';
+        let body = null, status = 0;
+        try {
+            const r = await fetch('/api/enrichment/identify/' + enc(song.filename), { method: 'POST' });
+            status = r.status;
+            body = await r.json().catch(() => null);
+        } catch (_) { /* falls through to the no-results line */ }
+        // Honest states — never a fake hit. Each says plainly WHICH outcome this
+        // is, so an empty result reads as "it ran, found nothing" (not "broken")
+        // and points at the manual fallback when there's nothing to pick.
+        const note = (html) => { out.innerHTML = '<p class="text-xs text-fb-textDim leading-relaxed">' + html + '</p>'; };
+        const manual = _single
+            ? ' Try <b class="text-fb-text">Search</b>, or just set the album in <b class="text-fb-text">Details</b> and the cover in <b class="text-fb-text">Cover art</b> by hand.'
+            : ' Try <b class="text-fb-text">Search instead</b>.';
+        if (status === 412 || (body && body.needs_setup)) {
+            note('Audio identification is <b class="text-fb-text">off</b>. Turn it on and add a free AcoustID API key in Settings → Library to use it.');
+            return;
+        }
+        if (status === 404) {
+            note('This pack has <b class="text-fb-text">no full mix to fingerprint</b> (it\'s chart-only or stems-only).' + manual);
+            return;
+        }
+        if (status === 503) {
+            note('Could not run the fingerprint right now — the audio tool or network is unavailable. Try again in a moment.');
+            return;
+        }
+        const cands = (body && body.candidates) || [];
+        if (!cands.length) {
+            note('<span class="text-fb-good">✓ Fingerprinted the audio</span> — but AcoustID has <b class="text-fb-text">no match</b> for this exact recording (common for obscure or import tracks).' + manual);
+            return;
+        }
+        out.innerHTML = '<div class="text-xs font-semibold uppercase tracking-wider text-fb-good mb-1">✓ Fingerprint matches (AcoustID)</div>' +
+            cands.map((c, i) => candRowHtml(song, c, i, false)).join('');
+        out.querySelectorAll('[data-mr-cand]').forEach((btn) => {
+            btn.addEventListener('click', async () => {
+                const cand = cands[Number(btn.getAttribute('data-mr-cand'))];
+                if (!cand) return;
+                if (_single) { useTheseValues(song, cand); return; }   // popup → adopt into Details
                 await post('/api/enrichment/review/' + enc(song.filename) + '/pick',
                     { candidate: cand });
                 settle(song);
@@ -415,14 +839,27 @@
             ['enrich-apply-year', 'enrich_apply_year'],
             ['enrich-apply-genres', 'enrich_apply_genres'],
             ['enrich-apply-art', 'enrich_apply_art'],
+            // Artist pages (PR-B): the page itself — local-only, default ON.
+            ['artist-pages-enabled', 'artist_pages_enabled'],
         ].map(([id, key]) => [document.getElementById(id), key]).filter(([el]) => el);
-        if (!toggles.length && !sel && !btn) return;
+        // Default-OFF toggles load with the opposite absent-key semantic
+        // (checked only when explicitly true): the external-links row is
+        // opt-IN per the dev-chat thread.
+        const optInToggles = [
+            ['artist-external-links', 'artist_external_links'],
+            // Audio fingerprinting is opt-in (needs a key + fpcalc), default OFF.
+            ['acoustid-enabled', 'acoustid_enabled'],
+        ].map(([id, key]) => [document.getElementById(id), key]).filter(([el]) => el);
+        const acoustidKeyEl = document.getElementById('acoustid-api-key');
+        if (!toggles.length && !optInToggles.length && !sel && !btn) return;
         (async () => {
             try {
                 const r = await fetch('/api/settings');
                 if (r.ok) {
                     const cfg = await r.json();
                     for (const [el, key] of toggles) el.checked = cfg[key] !== false;
+                    for (const [el, key] of optInToggles) el.checked = cfg[key] === true;
+                    if (acoustidKeyEl) acoustidKeyEl.value = cfg.acoustid_api_key || '';
                     if (sel) {
                         const t = Number(cfg.enrich_auto_threshold);
                         const want = Number.isFinite(t) ? t : 0.9;
@@ -442,11 +879,12 @@
             refreshChip();   // also fills #enrich-status
         })();
         const save = (key, value) => post('/api/settings', { [key]: value });
-        for (const [el, key] of toggles) {
+        for (const [el, key] of toggles.concat(optInToggles)) {
             el.addEventListener('change', () => save(key, !!el.checked));
         }
         sel?.addEventListener('change', () => save('enrich_auto_threshold', Number(sel.value)));
         order?.addEventListener('change', () => save('enrich_review_order', order.value));
+        acoustidKeyEl?.addEventListener('change', () => save('acoustid_api_key', acoustidKeyEl.value.trim()));
         btn?.addEventListener('click', async () => {
             await post('/api/enrichment/kick');
             const line = document.getElementById('enrich-status');
@@ -455,10 +893,34 @@
         });
     }
 
+    // Stop the 5s poll when the library screen is left — the progress line and
+    // chip only live in the songs toolbar, so polling off-screen is pure waste
+    // (benign but tidy). Re-entering v3-songs re-arms it: songs.js re-calls
+    // window.__fbMatchReviewChip() on screen enter, and we also refresh here so
+    // this stays self-contained. Same single-guarded-interval invariant as
+    // refreshChip — no double-interval, cleared to null.
+    function wireScreenTeardown() {
+        const sm = window.feedBack;
+        if (!sm || typeof sm.on !== 'function') return;
+        sm.on('screen:changed', (e) => {
+            const id = e && e.detail && e.detail.id;
+            if (id === 'v3-songs') {
+                refreshChip();   // returning while a pass runs re-arms the poll
+            } else if (_pollTimer) {
+                clearInterval(_pollTimer);
+                _pollTimer = null;
+            }
+        });
+    }
+
     if (document.readyState === 'loading') {
-        document.addEventListener('DOMContentLoaded', wireSettingsCard, { once: true });
+        document.addEventListener('DOMContentLoaded', () => {
+            wireSettingsCard();
+            wireScreenTeardown();
+        }, { once: true });
     } else {
         wireSettingsCard();
+        wireScreenTeardown();
     }
 
     window.__fbMatchReviewChip = refreshChip;

static/v3/onboarding-tour.js

@@ -42,7 +42,7 @@
                 id: 'instrument', shape: 'spotlight', position: 'bottom',
                 selector: '#v3-instrument-wrap', waitFor: '#v3-instrument-wrap',
                 title: 'Choose your instrument',
-                content: 'Set your instrument, string count and tuning here. The highway, tuner and scoring all adapt to this selection.',
+                content: 'Set your instrument, string count and tuning here — and if you play left-handed, flip Handedness to Left so the whole highway mirrors. The highway, tuner and scoring all adapt to this selection.',
             },
             {
                 id: 'tuner', shape: 'spotlight', position: 'bottom',

static/v3/playlists.js

@@ -211,7 +211,12 @@
             '<div class="flex items-center justify-between mb-6 gap-3">' +
             '<h2 class="text-3xl font-bold text-fb-text truncate">' + (isAlbum ? '💿 ' : '') + esc(pl.name) + '</h2>' +
             '<div class="flex gap-2 shrink-0 items-center">' +
-            (pl.songs.length ? '<button id="v3-pl-playall" class="bg-fb-primary hover:bg-fb-primaryHi text-white text-sm font-medium px-4 py-2 rounded-md">▶ Play ' + (isAlbum ? 'album' : 'all') + '</button>' : '') +
+            (pl.songs.length
+                ? '<button id="v3-pl-shuffle" class="px-2 py-2 rounded-md" aria-pressed="false">' +
+                  '<svg class="w-5 h-5" fill="none" stroke="currentColor" stroke-width="2" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" d="M16 3h5v5M4 20L21 3M21 16v5h-5M15 15l6 6M4 4l5 5"/></svg>' +
+                  '</button>' +
+                  '<button id="v3-pl-playall" class="bg-fb-primary hover:bg-fb-primaryHi text-white text-sm font-medium px-4 py-2 rounded-md">▶ Play ' + (isAlbum ? 'album' : 'all') + '</button>'
+                : '') +
             (isSystem ? '' :
                 '<button id="v3-pl-cover" class="text-sm text-fb-textDim hover:text-fb-text px-2">Cover</button>' +
                 (pl.cover_url ? '<button id="v3-pl-cover-rm" class="text-sm text-fb-textDim hover:text-fb-accent px-2">Remove cover</button>' : '') +
@@ -226,6 +231,26 @@
                 : '<p class="text-fb-textDim">Empty — add songs from the library' + (isAlbum ? ' (the ⋮ menu or the batch bar\'s "Add to playlist")' : '') + '.</p>') +
             '</div>';
         root.querySelector('#v3-pl-back')?.addEventListener('click', renderPlaylists);
+        // Shuffle toggle (crossing arrows, next to Play). Persisted globally —
+        // one preference, not per playlist. The queue is shuffled once when
+        // Play starts (playQueue.start's shuffle opt); the stored playlist
+        // order is never touched.
+        const shuffleBtn = root.querySelector('#v3-pl-shuffle');
+        const shuffleOn = () => { try { return localStorage.getItem('v3PlaylistShuffle') === '1'; } catch (_) { return false; } };
+        const paintShuffle = () => {
+            if (!shuffleBtn) return;
+            const on = shuffleOn();
+            shuffleBtn.className = on
+                ? 'px-2 py-2 rounded-md border border-fb-primary bg-fb-primary hover:bg-fb-primaryHi text-white'
+                : 'px-2 py-2 rounded-md border border-fb-border text-fb-textDim hover:text-fb-text';
+            shuffleBtn.title = on ? 'Shuffle: on' : 'Shuffle: off';
+            shuffleBtn.setAttribute('aria-pressed', on ? 'true' : 'false');
+        };
+        paintShuffle();
+        shuffleBtn?.addEventListener('click', () => {
+            try { localStorage.setItem('v3PlaylistShuffle', shuffleOn() ? '0' : '1'); } catch (_) { /* private mode */ }
+            paintShuffle();
+        });
         // Play all: start the play-queue with this playlist's songs (auto-advances
         // track to track). Falls back to playing the first song on an older core
         // without the queue, so the button always does something. An ALBUM plays
@@ -244,8 +269,8 @@
             if (!files.length) return;
             if (window.feedBack && window.feedBack.playQueue) {
                 window.feedBack.playQueue.start(files, isAlbum
-                    ? { source: pl.name, arrangements: arrs }
-                    : { source: pl.name });
+                    ? { source: pl.name, arrangements: arrs, shuffle: shuffleOn() }
+                    : { source: pl.name, shuffle: shuffleOn() });
             } else if (typeof window.playSong === 'function') window.playSong(encodeURIComponent(files[0]));
         });
         const listEl = root.querySelector('#v3-pl-songs');

static/v3/shell.js

@@ -192,6 +192,9 @@
     }
 
     // ── Topbar ───────────────────────────────────────────────────────────---
+    // Funding cleared to come back online 2026-06-30 (offending functionality
+    // removed). feedBack-branded Patreon page.
+    const PATREON_URL = 'https://patreon.com/got_feedback';
     function renderTopbar() {
         const bar = document.getElementById('v3-topbar');
         if (!bar) return;
@@ -209,6 +212,12 @@
             '<input id="v3-search" type="search" placeholder="Search songs…" aria-label="Search songs" ' +
             'class="w-full bg-gray-800/50 border border-gray-700 rounded-md pl-10 pr-4 py-2 text-sm ' +
             'text-fb-text placeholder-fb-textDim focus:border-fb-primary focus:ring-1 focus:ring-fb-primary outline-none"></div>' +
+            // Support Us! — stays on this top utility row (NOT the title row),
+            // pushed to the right with ml-auto; hidden on the smallest widths.
+            '<a href="' + PATREON_URL + '" target="_blank" rel="noopener" class="ml-auto ' +
+            'hidden sm:inline-flex items-center gap-2 bg-fb-accent hover:bg-red-600 text-white text-sm font-medium px-4 py-2 rounded-md shadow-lg shadow-fb-accent/20 transition-colors">' +
+            '<svg class="w-4 h-4" fill="currentColor" viewBox="0 0 24 24"><path d="M14.8 3c-3 0-5.4 2.4-5.4 5.4S11.8 13.9 14.8 13.9 20.2 11.5 20.2 8.4 17.8 3 14.8 3zM3.8 3h3.4v18H3.8z"/></svg>' +
+            'Support Us!</a>' +
             '</div>' +
             // Row 2 — page header: title + ONLY the tuner/instrument/profile
             // badge cluster on the same line as the header.
@@ -329,7 +338,8 @@
 
     // ── Boot ────────────────────────────────────────────────────────────────
     async function boot() {
-        if (window.fbBrand) window.fbBrand.renderWordmark(document.getElementById('v3-brand'), { size: 'text-xl' });
+        var _v3brand = document.getElementById('v3-brand');
+        if (_v3brand) _v3brand.innerHTML = '<img src="/static/v3/brand/feedback-logo-light.png" alt="fee[dB]ack" style="width:100%;height:auto;display:block">';
         renderSidebar();
         renderTopbar();
         ensureBackdrop();

tailwind.config.js

@@ -45,7 +45,7 @@ module.exports = {
                     cardMuted: '#0b1220', // inset wells
                     primary: '#0ea5e9',   // sky — primary actions, active nav, progress fill
                     primaryHi: '#38bdf8', // hover
-                    accent: '#ef4444',    // red — destructive, low-accuracy
+                    accent: '#ef4444',    // red — Support Us, destructive, low-accuracy
                     text: '#f8fafc',      // primary text
                     textDim: '#94a3b8',   // secondary text
                     border: '#334155',    // hairlines / card borders

tests/js/badges_handedness.test.js

@@ -0,0 +1,47 @@
+// Pins the onboarding handedness control: a Right/Left choice lives in the
+// instrument selector (the "Choose your instrument" onboarding step, which the
+// tour spotlights BEFORE the tuner/audio-calibration steps) and writes the
+// highway 'lefty' preference. Source-level, matching the other tests/js/
+// browser-heavy regression guards (the runtime path is DOM/WebGL-heavy).
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ROOT = path.join(__dirname, '..', '..');
+const BADGES = fs.readFileSync(path.join(ROOT, 'static', 'v3', 'badges.js'), 'utf8');
+const TOUR = fs.readFileSync(path.join(ROOT, 'static', 'v3', 'onboarding-tour.js'), 'utf8');
+
+test('instrument selector offers a Handedness Right/Left choice', () => {
+    assert.match(BADGES, /instRow\('Handedness'/, 'a Handedness row must be in the instrument menu');
+    assert.match(BADGES, /pill\('hand',\s*'right'/, 'Right handedness pill');
+    assert.match(BADGES, /pill\('hand',\s*'left'/, 'Left handedness pill');
+});
+
+test('clicking a handedness pill writes the lefty preference from its value', () => {
+    assert.match(
+        BADGES,
+        /\[data-pill="hand"\][\s\S]*?_setLeftyPref\(\s*b\.getAttribute\('data-val'\)\s*===\s*'left'\s*\)/,
+        'the handedness click handler sets lefty from the pill value');
+});
+
+test('_setLeftyPref prefers highway.setLefty and falls back to the lefty localStorage key', () => {
+    const setter = BADGES.match(/function _setLeftyPref\(on\)\s*\{[\s\S]*?\n    \}/);
+    assert.ok(setter, '_setLeftyPref must exist');
+    assert.match(setter[0], /highway\.setLefty/, 'prefers highway.setLefty (flips a live highway + persists)');
+    assert.match(setter[0], /localStorage\.setItem\('lefty'/, 'falls back to the lefty localStorage key the highway reads on init');
+});
+
+test('_leftyPref reads highway.getLefty with a localStorage fallback', () => {
+    assert.match(
+        BADGES,
+        /function _leftyPref\(\)\s*\{[\s\S]*?getLefty[\s\S]*?localStorage\.getItem\('lefty'\)/,
+        '_leftyPref reads the current handedness with a storage fallback');
+});
+
+test('onboarding instrument step calls out left-handed players + the Handedness control', () => {
+    assert.match(TOUR, /Choose your instrument/);
+    assert.match(TOUR, /left-handed/i, 'the instrument step must call out left-handed players');
+    assert.match(TOUR, /Handedness/, 'and name the Handedness control');
+});

tests/js/capabilities_lifecycle.test.js

@@ -77,4 +77,34 @@ test('failed no-op registrations do not block reload and rehydrate replacement',
     assert.equal(participants.length, 1);
     assert.equal(result.status, 'applied');
     assert.equal(result.payload.generation, 2);
-});
+});
+
+test('library long-running commands override the default handler timeout', async () => {
+    const window = loadCapabilities();
+    const api = window.feedBack.capabilities;
+    const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+    api.registerParticipant('stems', {
+        stems: {
+            roles: ['owner'],
+            commands: ['slow-probe'],
+            handlers: { 'slow-probe': async () => { await delay(300); return { outcome: 'handled' }; } },
+            runtime: true,
+        },
+    });
+    const timedOut = await api.dispatch({ capability: 'stems', command: 'slow-probe', source: 'test' });
+    assert.equal(timedOut.outcome, 'failed');
+    assert.match(timedOut.reason, /timed out after 250 ms/);
+
+    api.registerParticipant('core.library', {
+        library: {
+            roles: ['owner'],
+            commands: ['sync-song'],
+            handlers: { 'sync-song': async () => { await delay(300); return { outcome: 'handled', payload: { ok: true } }; } },
+            runtime: true,
+        },
+    });
+    const synced = await api.dispatch({ capability: 'library', command: 'sync-song', source: 'test' });
+    assert.equal(synced.status, 'applied');
+    assert.equal(synced.payload.ok, true);
+});

tests/js/editor_pending_view.test.js

@@ -0,0 +1,47 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const src = fs.readFileSync(path.join(__dirname, '..', '..', 'static', 'app.js'), 'utf8');
+const m = src.match(/\/\* @pure:editor-pending-view:start \*\/[\s\S]*?\/\* @pure:editor-pending-view:end \*\//);
+if (!m) throw new Error('pending-view helper block not found');
+
+const api = new Function('"use strict";' + m[0] + '\nreturn { _buildEditorPendingViewPure };')();
+
+test('edit-region handoff defaults cursor to region start and marks return path', () => {
+    const out = api._buildEditorPendingViewPure('song.sloppak', 2, { a: 12.5, b: 20 }, { returnToHighway: true });
+    assert.deepStrictEqual(out, {
+        filename: 'song.sloppak',
+        arrangement: 2,
+        barSel: { startTime: 12.5, endTime: 20 },
+        returnToHighway: true,
+        cursorTime: 12.5,
+    });
+});
+
+test('return-trip handoff preserves explicit viewport state', () => {
+    const out = api._buildEditorPendingViewPure('song.sloppak', 1, { a: 8, b: 14 }, {
+        scrollX: -4,
+        zoom: 160,
+        cursorTime: 9.25,
+    });
+    assert.deepStrictEqual(out, {
+        filename: 'song.sloppak',
+        arrangement: 1,
+        barSel: { startTime: 8, endTime: 14 },
+        cursorTime: 9.25,
+        scrollX: 0,
+        zoom: 160,
+    });
+});
+
+test('missing region still produces a stable pending view shell', () => {
+    const out = api._buildEditorPendingViewPure('song.sloppak', -1, null, {});
+    assert.deepStrictEqual(out, {
+        filename: 'song.sloppak',
+        arrangement: 0,
+        barSel: null,
+    });
+});

tests/js/highway_3d_context_loss.test.js

@@ -0,0 +1,45 @@
+// Contract test: 3D Highway WebGL context-loss recovery.
+//
+// Switching the active window / alt-tabbing (especially on Windows) can trigger
+// a GPU context reset. Without a handler the lost WebGL context escalates into a
+// render-process crash. The renderer owns its own WebGL canvas + heavy Three.js
+// lifecycle (too much to construct in a vm sandbox), so — like the other
+// highway_* source-contract tests here — this pins the wiring at the source
+// level: the loss must be preventDefault()'d (so the browser restores it), draw
+// must bail while lost, and the listeners must be torn down.
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SCREEN_JS = path.join(__dirname, '..', '..', 'plugins', 'highway_3d', 'screen.js');
+const src = fs.readFileSync(SCREEN_JS, 'utf8');
+
+test('binds webglcontextlost + webglcontextrestored on the renderer canvas', () => {
+    assert.match(src, /ren\.domElement\.addEventListener\(\s*['"]webglcontextlost['"]/,
+        'must listen for webglcontextlost on ren.domElement (the WebGL canvas)');
+    assert.match(src, /ren\.domElement\.addEventListener\(\s*['"]webglcontextrestored['"]/,
+        'must listen for webglcontextrestored on ren.domElement');
+});
+
+test('the context-lost handler preventDefaults and pauses drawing', () => {
+    // Without preventDefault() the browser will not attempt to restore the
+    // context and the loss can escalate to a renderer crash.
+    const m = src.match(/_onCtxLost\s*=\s*\(e\)\s*=>\s*\{[\s\S]*?\};/);
+    assert.ok(m, '_onCtxLost handler must exist');
+    assert.match(m[0], /preventDefault\(\)/, 'context-lost handler must call preventDefault()');
+    assert.match(m[0], /_ctxLost\s*=\s*true/, 'context-lost handler must set _ctxLost = true');
+});
+
+test('draw() early-returns while the context is lost', () => {
+    assert.match(src, /draw\(bundle\)\s*\{[\s\S]*?if\s*\(_ctxLost\)\s*return;/,
+        'draw() must bail while _ctxLost is set so no GL work runs on a dead context');
+});
+
+test('teardown removes the context-loss listeners', () => {
+    assert.match(src, /removeEventListener\(\s*['"]webglcontextlost['"]/,
+        'teardown must remove the webglcontextlost listener');
+    assert.match(src, /removeEventListener\(\s*['"]webglcontextrestored['"]/,
+        'teardown must remove the webglcontextrestored listener');
+});

tests/js/highway_colors_facade.test.js

@@ -35,10 +35,11 @@ function buildFacade() {
         'return _hwcInstallFacade;',
     ].join('\n');
     const params = [
-        'window', 'HWC_SLOTS', 'console',
+        'window', 'HWC_SLOTS', 'HWC_PRESETS', 'console',
         'getHighwayStringColors', 'getHighwayDefaultSlotColors', '_hwcMergedSlotColors',
         '_hwcSlotKeysForChart', '_hwcEffectiveIndexColors', '_hwcChartShape',
-        'applyHighwayStringColors', 'encodeHighwayColorShare', 'decodeHighwayColorShare',
+        'applyHighwayStringColors', 'applyHighwayStringPreset',
+        'encodeHighwayColorShare', 'decodeHighwayColorShare',
     ];
 
     const listeners = {};
@@ -64,14 +65,19 @@ function buildFacade() {
         _hwcEffectiveIndexColors: (map, sc, isBass) => ['eff', sc, isBass],
         _hwcChartShape: () => ({ sc: 6, isBass: false }),
         applyHighwayStringColors: (m) => { calls.push(['apply', m]); },
+        applyHighwayStringPreset: (id) => { calls.push(['preset', id]); return true; },
         encodeHighwayColorShare: (n, m) => 'SLOPHWY2.CODE',
         decodeHighwayColorShare: (c) => ({ name: 'x', colors: {} }),
     };
+    const HWC_PRESETS = [
+        { id: 'stock', label: 'Stock', colors: { lowE: '#cc0000' } },
+    ];
     const installer = new Function(...params, body)(
-        win, HWC_SLOTS, console,
+        win, HWC_SLOTS, HWC_PRESETS, console,
         stubs.getHighwayStringColors, stubs.getHighwayDefaultSlotColors, stubs._hwcMergedSlotColors,
         stubs._hwcSlotKeysForChart, stubs._hwcEffectiveIndexColors, stubs._hwcChartShape,
-        stubs.applyHighwayStringColors, stubs.encodeHighwayColorShare, stubs.decodeHighwayColorShare,
+        stubs.applyHighwayStringColors, stubs.applyHighwayStringPreset,
+        stubs.encodeHighwayColorShare, stubs.decodeHighwayColorShare,
     );
     installer();
     return { api: win.feedBack.highwayColors, win, bus, calls, installer, stubs };
@@ -87,11 +93,13 @@ test('facade exposes the documented surface', () => {
     const { api } = buildFacade();
     assert.equal(api.version, 1);
     for (const m of ['get', 'getDefaults', 'getResolved', 'keysForChart', 'toEffective',
-        'getCurrent', 'apply', 'encodeShare', 'decodeShare', 'onChange', 'offChange']) {
+        'getCurrent', 'apply', 'applyPreset', 'encodeShare', 'decodeShare', 'onChange', 'offChange']) {
         assert.equal(typeof api[m], 'function', `highwayColors.${m} must be a function`);
     }
     assert.deepEqual(api.slots.map((s) => s.key),
         ['highE', 'B', 'G', 'D', 'A', 'lowE', 'low7', 'low8'], 'slots in display order');
+    // One-click presets: exposed as detached [{ id, label, colors }] copies.
+    assert.deepEqual(api.presets, [{ id: 'stock', label: 'Stock', colors: { lowE: '#cc0000' } }]);
 });
 
 test('facade read methods delegate to the manager', () => {

tests/js/legacy_shim_hits.test.js

@@ -74,7 +74,10 @@ const APP_JS = path.join(ROOT, 'static', 'app.js');
 const LIBRARY_JS = path.join(ROOT, 'static', 'capabilities', 'library.js');
 
 function source(file) {
-    return fs.readFileSync(file, 'utf8');
+    // Normalize CRLF: region() slices fixed CHARACTER windows, so on a
+    // Windows checkout (autocrlf) every line costs one extra char and the
+    // assertion target can fall outside the window.
+    return fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n');
 }
 
 function region(src, needle, length = 1200) {

tests/js/live_guitar_tone_source.test.js

@@ -40,7 +40,9 @@ test('settings UI exposes tone source select with all options', () => {
     assert.match(html, /value="external_hardware"/);
     assert.match(html, /value="spark_control_x"/);
     assert.match(html, /Live guitar tone source/);
-    assert.match(html, /won’t warn that no internal amp tone is loaded/);
+    // Apostrophe form drifted from the ’ entity to the literal ’ in a
+    // copy pass — accept entity, typographic, or plain apostrophe.
+    assert.match(html, /won(?:’|’|')t warn that no internal amp tone is loaded/);
 });
 
 test('player audio rail exposes tone source select', () => {

tests/js/loop_api.test.js

@@ -107,6 +107,7 @@ function loadFunctions(sandbox, src) {
             sectionPracticeModeCalls.push({ on, opts: opts || {} });
         }
         function _updateSectionPracticeHighlight(ct) {}
+        function _updateEditRegionBtn() {}
         ${extractFunction(src, 'function clearLoop(')}
         ${extractFunction(src, 'function _syncSavedLoopSelection()')}
         ${extractFunction(src, 'async function setLoop(')}

tests/js/play_queue_shuffle.test.js

@@ -0,0 +1,86 @@
+// playQueue.start({ shuffle: true }): the queue is Fisher-Yates-shuffled ONCE
+// at start. Per-slot arrangements must swap in lockstep with their files
+// (albums pass arrangements aligned by index, #685), the caller's arrays must
+// not be mutated, and shuffle:false / absent must preserve order. Extract the
+// playQueue IIFE from app.js and drive it against a playSong stub.
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const path = require('node:path');
+
+function makeQueue() {
+    const src = fs.readFileSync(path.join(__dirname, '..', '..', 'static', 'app.js'), 'utf8');
+    const start = src.indexOf('window.feedBack.playQueue = (function () {');
+    assert.ok(start !== -1, 'playQueue IIFE found in app.js');
+    const end = src.indexOf('})();', start);
+    assert.ok(end !== -1, 'playQueue IIFE terminator found');
+    const iife = src.slice(start, end + 5);
+    const played = [];
+    const sandbox = {
+        window: {
+            feedBack: {},
+            playSong: (fn, arr, opts) => played.push({ fn: decodeURIComponent(fn), arr, opts }),
+            fbNotify: null,
+        },
+    };
+    // eslint-disable-next-line no-new-func
+    new Function('window', 'encodeURIComponent', iife)(sandbox.window, encodeURIComponent);
+    return { q: sandbox.window.feedBack.playQueue, played };
+}
+
+function drain(q, played) {
+    while (q.hasNext()) q.advance();
+    return played.map((p) => p.fn);
+}
+
+test('shuffle: same multiset, order from the seeded RNG, arrangements follow files', () => {
+    const files = ['a.sloppak', 'b.sloppak', 'c.sloppak', 'd.sloppak'];
+    const arrs = [0, 1, 2, 3]; // arrangement i belongs to files[i]
+    const origRandom = Math.random;
+    try {
+        // Deterministic RNG so the expected order is checkable.
+        let calls = 0;
+        const seq = [0.1, 0.9, 0.5];
+        Math.random = () => seq[calls++ % seq.length];
+        const { q, played } = makeQueue();
+        q.start(files.slice(), { arrangements: arrs.slice(), shuffle: true });
+        const order = drain(q, played);
+        assert.deepStrictEqual(order.slice().sort(), files.slice().sort()); // nothing lost/duplicated
+        // Each played file carries the arrangement it started with.
+        played.forEach((p) => {
+            assert.strictEqual(p.arr, arrs[files.indexOf(p.fn)]);
+        });
+    } finally {
+        Math.random = origRandom;
+    }
+});
+
+test('shuffle can change the order', () => {
+    const origRandom = Math.random;
+    try {
+        Math.random = () => 0; // j = 0 every swap → deterministic rotation, ≠ input order
+        const { q, played } = makeQueue();
+        q.start(['a', 'b', 'c'], { shuffle: true });
+        const order = drain(q, played);
+        assert.notDeepStrictEqual(order, ['a', 'b', 'c']);
+    } finally {
+        Math.random = origRandom;
+    }
+});
+
+test('no shuffle opt preserves order and caller arrays are never mutated', () => {
+    const files = ['a', 'b', 'c'];
+    const arrs = [2, 0, 1];
+    const { q, played } = makeQueue();
+    q.start(files, { arrangements: arrs });
+    assert.deepStrictEqual(drain(q, played), ['a', 'b', 'c']);
+    assert.deepStrictEqual(files, ['a', 'b', 'c']);
+    assert.deepStrictEqual(arrs, [2, 0, 1]);
+
+    // shuffle:true must also leave the caller's arrays alone (start slices).
+    const { q: q2 } = makeQueue();
+    q2.start(files, { arrangements: arrs, shuffle: true });
+    assert.deepStrictEqual(files, ['a', 'b', 'c']);
+    assert.deepStrictEqual(arrs, [2, 0, 1]);
+});

tests/js/plugin_hydration_wipe.test.js

@@ -0,0 +1,115 @@
+// Verify loadPlugins' plugin-DOM wipe loops in static/app.js: a plugin that is
+// merely ABSENT from the current /api/plugins response (transient partial
+// response while the backend's plugin registry is repopulating after a
+// restart) must keep its settings panel and screen DOM. Wiping it while its
+// _loadedPluginScripts entry survives made the next refetch fail the
+// DOM-existence check and re-evaluate the plugin's screen.js mid-session —
+// which duplicated the desktop audio_engine's native signal chain. Plugins
+// the response knows about but that failed hydration are still wiped, as is
+// junk DOM carrying no plugin id.
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+
+const APP_JS = path.join(__dirname, '..', '..', 'static', 'app.js');
+
+// Slice the wipe block out of loadPlugins by its stable landmarks: from the
+// nav reset that opens it to the comment introducing the next section.
+function extractWipeBlock(src) {
+    const start = src.indexOf("navContainer.innerHTML = '';");
+    assert.ok(start !== -1, 'wipe block start (nav reset) not found');
+    const end = src.indexOf('// Plugin settings area hosts', start);
+    assert.ok(end !== -1, 'wipe block end marker not found');
+    return src.slice(start, end);
+}
+
+function makeEl(pluginId, id) {
+    return {
+        dataset: pluginId != null ? { pluginId } : {},
+        id: id || (pluginId != null ? `plugin-${pluginId}` : ''),
+        removed: false,
+        remove() {
+            this.removed = true;
+            const idx = this._parent ? this._parent.indexOf(this) : -1;
+            if (idx >= 0) this._parent.splice(idx, 1);
+        },
+    };
+}
+
+function runWipe({ respondedIds, alreadyHydrated, settingsChildren, screens }) {
+    const src = fs.readFileSync(APP_JS, 'utf8');
+    const block = extractWipeBlock(src);
+    settingsChildren.forEach((el) => { el._parent = settingsChildren; });
+    const container = { children: settingsChildren };
+    const sandbox = {
+        navContainer: { innerHTML: 'seed' },
+        mobileNavContainer: { innerHTML: 'seed' },
+        _pluginSettingsContainers: () => [container],
+        respondedIds,
+        alreadyHydrated,
+        document: {
+            querySelectorAll: (sel) => {
+                assert.equal(sel, '.screen[id^="plugin-"]');
+                return screens.slice();
+            },
+        },
+    };
+    vm.runInNewContext(block, sandbox, { filename: 'wipe-block.js' });
+    return sandbox;
+}
+
+test('plugin absent from the response keeps its settings + screen DOM', () => {
+    const settings = makeEl('audio_engine');
+    const screen = makeEl('audio_engine');
+    runWipe({
+        respondedIds: new Set(),               // partial response: plugin missing
+        alreadyHydrated: new Set(),            // scan loop never saw it either
+        settingsChildren: [settings],
+        screens: [screen],
+    });
+    assert.equal(settings.removed, false, 'settings panel must survive a partial response');
+    assert.equal(screen.removed, false, 'screen must survive a partial response');
+});
+
+test('plugin present in the response but not hydrated is wiped', () => {
+    const settings = makeEl('stale_plugin');
+    const screen = makeEl('stale_plugin');
+    runWipe({
+        respondedIds: new Set(['stale_plugin']),
+        alreadyHydrated: new Set(),
+        settingsChildren: [settings],
+        screens: [screen],
+    });
+    assert.equal(settings.removed, true);
+    assert.equal(screen.removed, true);
+});
+
+test('hydrated plugin present in the response is preserved', () => {
+    const settings = makeEl('audio_engine');
+    const screen = makeEl('audio_engine');
+    runWipe({
+        respondedIds: new Set(['audio_engine']),
+        alreadyHydrated: new Set(['audio_engine']),
+        settingsChildren: [settings],
+        screens: [screen],
+    });
+    assert.equal(settings.removed, false);
+    assert.equal(screen.removed, false);
+});
+
+test('junk DOM without a plugin id is still removed', () => {
+    const junkSettings = makeEl(null);
+    // Screen whose id strips to '' (no dataset.pluginId, bare "plugin-" id).
+    const junkScreen = makeEl(null, 'plugin-');
+    runWipe({
+        respondedIds: new Set(['whatever']),
+        alreadyHydrated: new Set(),
+        settingsChildren: [junkSettings],
+        screens: [junkScreen],
+    });
+    assert.equal(junkSettings.removed, true);
+    assert.equal(junkScreen.removed, true);
+});

tests/js/plugin_loader_script_type.test.js

@@ -0,0 +1,59 @@
+// Guards the R0 module-migration loader change in static/app.js: a migrated
+// plugin (manifest scriptType:"module", surfaced as plugin.script_type) must be
+// injected as <script type="module"> so its screen.js `import './src/main.js'`
+// graph loads, while classic plugins stay untouched.
+//
+// The injection is a single line inside the large async loadPlugins() closure
+// (it depends on loadedScripts, _removePluginScriptTags, and the
+// _loadingPluginId completion window), so a faithful behavioural harness would
+// need to stub the whole loader. Instead this asserts the *structural*
+// contract in source — the guard exists, is gated (not unconditional), and sits
+// inside the screen.js injection block before appendChild. The behavioural proof
+// is the R0 end-to-end live-edit check (a real module plugin booting in-browser).
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const APP_JS = path.join(__dirname, '..', '..', 'static', 'app.js');
+const src = fs.readFileSync(APP_JS, 'utf8');
+
+// Isolate the screen.js <script> injection block: from where its src is built
+// to where the element is appended.
+function injectionBlock() {
+    const start = src.indexOf('/api/plugins/${plugin.id}/screen.js');
+    assert.ok(start !== -1, 'screen.js injection src not found — loader moved?');
+    const end = src.indexOf('document.body.appendChild(script)', start);
+    assert.ok(end !== -1, 'appendChild(script) not found after screen.js src');
+    return src.slice(start, end);
+}
+
+test('module plugins are injected as <script type="module">', () => {
+    const block = injectionBlock();
+    assert.match(
+        block,
+        /if\s*\(\s*plugin\.script_type\s*===\s*['"]module['"]\s*\)\s*script\.type\s*=\s*['"]module['"]\s*;/,
+        'expected a guarded `script.type = "module"` keyed on plugin.script_type === "module"',
+    );
+});
+
+test('the module type is gated, never set unconditionally', () => {
+    const block = injectionBlock();
+    // Every assignment of script.type in the block must be on the same line as
+    // the plugin.script_type guard (i.e. no bare `script.type = 'module'`).
+    for (const line of block.split('\n')) {
+        if (/script\.type\s*=/.test(line)) {
+            assert.match(line, /plugin\.script_type\s*===\s*['"]module['"]/,
+                `unguarded script.type assignment: ${line.trim()}`);
+        }
+    }
+});
+
+test('the module guard sits before appendChild, after the src assignment', () => {
+    const guardAt = src.indexOf('script.type = \'module\'');
+    const srcAt = src.indexOf('/api/plugins/${plugin.id}/screen.js');
+    const appendAt = src.indexOf('document.body.appendChild(script)', srcAt);
+    assert.ok(guardAt > srcAt && guardAt < appendAt,
+        'the module guard must live inside the screen.js injection block');
+});

tests/js/plugin_style_injection.test.js

@@ -204,15 +204,20 @@ test('does not collide tags across two different plugins', () => {
     assert.deepEqual(headLinks.map((l) => l.dataset.pluginId).sort(), ['a', 'b']);
 });
 
-test('reconcile removes the <link> of a plugin that vanished from /api/plugins', () => {
+test('reconcile keeps the <link> of a plugin absent from a partial response', () => {
     const { inject, reconcile, headLinks } = setupSandbox();
     inject(plug({ id: 'a' }));
     inject(plug({ id: 'b' }));
     assert.equal(headLinks.length, 2);
-    // `a` is no longer returned (uninstalled) — its stylesheet must be dropped.
+    // `a` is missing from this response. That happens transiently during a
+    // backend restart (the plugin registry repopulates while HTTP stays up),
+    // so absence is NOT an uninstall signal — the still-loaded plugin must
+    // keep its stylesheet or it renders visible-but-unstyled until it
+    // reappears. Explicit removal still happens via the not-ready/unstyled
+    // paths (tests below).
     reconcile([plug({ id: 'b' })]);
-    assert.equal(headLinks.length, 1);
-    assert.equal(headLinks[0].dataset.pluginId, 'b');
+    assert.equal(headLinks.length, 2);
+    assert.deepEqual(headLinks.map((l) => l.dataset.pluginId).sort(), ['a', 'b']);
 });
 
 test('reconcile removes the <link> of a plugin that is no longer ready', () => {

tests/js/song_close.test.js

@@ -42,7 +42,10 @@ function loadClose(sandbox, src) {
         globalThis.__seekCalls = 0;
         globalThis.__playSongCalls = 0;
         globalThis.__clearLoopCalls = 0;
+        globalThis.__queueClearCalls = 0;
         globalThis.__audioCurrentTimeSets = [];
+        // closeCurrentSong abandons any play-queue before leaving the player.
+        var window = { feedBack: { playQueue: { clear() { globalThis.__queueClearCalls++; } } } };
         var audio = {
             _t: 42,
             get currentTime() { return this._t; },
@@ -75,6 +78,7 @@ test('closeCurrentSong uses _playerOriginScreen when set', async () => {
     await sandbox.__closeCurrentSong();
     assert.equal(sandbox.__showScreenCalls.length, 1);
     assert.equal(sandbox.__showScreenCalls[0], 'favorites');
+    assert.equal(sandbox.__queueClearCalls, 1, 'a real close abandons the play-queue');
     assert.equal(sandbox.__restartCalls, 0);
     assert.equal(sandbox.__seekCalls, 0);
     assert.equal(sandbox.__playSongCalls, 0);

tests/js/v3_keep_practicing.test.js

@@ -31,21 +31,23 @@ test('the home is the unfiltered grid front door, local provider only', () => {
     );
 });
 
-test('the shelf is recently-played, not-yet-mastered songs (per-song, deduped)', () => {
-    assert.match(src, /\/api\/stats\/recent\?limit=/);
-    // Mastery is gated on the per-SONG best (state.accuracy, what the badge
-    // shows), not the per-arrangement recents row, and each filename appears
-    // once — so no green-badged "keep practicing" card and no duplicates.
+test('the shelf is the server-side practice-suggestions recommender', () => {
+    // The old client-side pipeline (fetch /api/stats/recent, dedupe by
+    // filename, gate on state.accuracy) moved server-side: the growth-edge
+    // recommender gates (not-mastered) + aggregates per song and picks the
+    // arrangement closest to mastery. The client renders its rows as-is.
+    assert.match(src, /\/api\/library\/practice-suggestions\?limit=/);
+    // A shelf card click opens the row's recommended arrangement, not the
+    // song's default.
     assert.match(
         src,
-        /const\s+best\s*=\s*acc\[r\.filename\][\s\S]*?best\s*>=\s*MASTERY_ACCURACY/,
-        'the shelf must gate on the per-song best (state.accuracy) at MASTERY_ACCURACY',
+        /data-arr="[\s\S]*?getAttribute\('data-arr'\)[\s\S]*?playSong\(enc\(fn\), arr === '' \? undefined : Number\(arr\)\)/,
+        'shelf cards must pass the recommended arrangement to playSong',
     );
-    assert.match(src, /seen\.has\(r\.filename\)/, 'the shelf must dedupe recents by filename');
 });
 
 test('the meter + shelf fetch together and a stale render is discarded', () => {
-    assert.match(src, /Promise\.all\(\[[\s\S]*?library\/stats[\s\S]*?stats\/recent/,
+    assert.match(src, /Promise\.all\(\[[\s\S]*?library\/stats[\s\S]*?practice-suggestions/,
         'the two reads must be issued together (Promise.all), not sequentially');
     assert.match(src, /_homeToken[\s\S]*?_homeToken !== myToken/,
         'a stale render must be superseded by a newer one via a token');

tests/js/v3_slow_provider_loading.test.js

@@ -0,0 +1,36 @@
+// Pins the slow-library-provider loading states in the classic and v3 library
+// surfaces. Providers can declare `slow: true`; the UI should show explicit
+// wait copy plus a status region instead of silently blanking while fetches run.
+
+'use strict';
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const root = path.join(__dirname, '..', '..');
+const SONGS = fs.readFileSync(path.join(root, 'static', 'v3', 'songs.js'), 'utf8');
+const APP = fs.readFileSync(path.join(root, 'static', 'app.js'), 'utf8');
+
+test('v3 Songs slow providers get explicit loading copy', () => {
+    assert.match(SONGS, /function providerLoadingText\(\)[\s\S]*?provider\.slow\s*===\s*true[\s\S]*?this source may take a while\./,
+        'v3 providerLoadingText must branch on provider.slow and explain the longer wait');
+    assert.match(SONGS, /function loadingPanelHtml\(\)[\s\S]*?providerLoadingText\(\)/,
+        'v3 grid loading panel must render the provider-aware loading message');
+});
+
+test('v3 loading indicators are announced as polite status regions', () => {
+    assert.match(SONGS, /function loadingPanelHtml\(\)[\s\S]*?role="status"\s+aria-live="polite"/,
+        'v3 grid loading panel must be a polite status region');
+    assert.match(SONGS, /loadAlbums[\s\S]*role="status"\s+aria-live="polite"[\s\S]*providerLoadingText\(\)/,
+        'v3 albums loading state must be a polite status region');
+    assert.match(SONGS, /loadTree[\s\S]*role="status"\s+aria-live="polite"[\s\S]*providerLoadingText\(\)/,
+        'v3 list loading state must be a polite status region');
+});
+
+test('classic library loading indicator is announced and uses slow provider copy', () => {
+    assert.match(APP, /function _setLibraryLoadingMessage[\s\S]*?role="status"\s+aria-live="polite"/,
+        'classic library loading card must be a polite status region');
+    assert.match(APP, /function _libraryLoadingText\(\)[\s\S]*?provider\.slow\s*===\s*true[\s\S]*?this source may take a while\./,
+        'classic library loading text must branch on provider.slow');
+});

tests/js/v3_songs_tuning.test.js

@@ -64,7 +64,9 @@ const helpers = loadTuningHelpers();
 
 test('v3 songs.js uses display helpers for album-art tuning badge', () => {
     const src = fs.readFileSync(SONGS_JS, 'utf8');
-    assert.match(src, /displayTuningName\(song\.tuning_name \|\| song\.tuning\)/);
+    // The card renderer's row variable was renamed song → shown when grouped
+    // cards landed (the badge reads the representative chart); accept either.
+    assert.match(src, /displayTuningName\((?:song|shown)\.tuning_name \|\| (?:song|shown)\.tuning\)/);
     assert.match(src, /displayTuningTargets/);
     assert.match(src, /parseRawTuningOffsets/);
 });

tests/js/v3_songs_window_recycle.test.js

@@ -0,0 +1,143 @@
+'use strict';
+const { test } = require('node:test');
+const assert = require('node:assert');
+
+// Mirror of static/v3/songs.js _cardSig / _buildCardNode / _syncWindow (the
+// windowed-grid recycle path, #636 item 3 follow-up) — keep in sync. Exercised
+// against a minimal DOM shim so the reconcile invariants are covered off-browser:
+//   (1) after every slide the grid's children are exactly [start,end) ascending,
+//   (2) card nodes for indices that stay in-window are REUSED (identity kept) —
+//       i.e. sliding one row never tears down + rebuilds the whole window (the
+//       per-slide stall behind the "skips every so many scrolls" report), and
+//   (3) a select-mode toggle rebuilds the visible window (checkbox/ring change).
+
+let NODE_SEQ = 0;
+function makeNode() {
+    const attrs = {};
+    return {
+        _uid: ++NODE_SEQ,
+        parent: null,
+        getAttribute(k) { return k in attrs ? attrs[k] : null; },
+        setAttribute(k, v) { attrs[k] = String(v); },
+        get nextSibling() {
+            const p = this.parent; if (!p) return null;
+            const i = p._kids.indexOf(this);
+            return i >= 0 && i + 1 < p._kids.length ? p._kids[i + 1] : null;
+        },
+        remove() {
+            const p = this.parent; if (!p) return;
+            const i = p._kids.indexOf(this);
+            if (i >= 0) p._kids.splice(i, 1);
+            this.parent = null;
+        },
+    };
+}
+function makeGrid() {
+    return {
+        _kids: [],
+        get children() { return this._kids.slice(); },
+        get firstChild() { return this._kids[0] || null; },
+        insertBefore(node, ref) {
+            if (node.parent) node.remove();
+            if (ref == null) this._kids.push(node);
+            else { const i = this._kids.indexOf(ref); this._kids.splice(i < 0 ? this._kids.length : i, 0, node); }
+            node.parent = this;
+            return node;
+        },
+    };
+}
+
+// --- state + the three helpers, mirrored from songs.js ---
+const state = { songs: [], selectMode: false };
+for (let i = 0; i < 5000; i++) state.songs[i] = { filename: 'song' + i };
+
+function _cardSig(i) { return (state.songs[i] ? 'r' : 's') + (state.selectMode ? '1' : '0'); }
+function _buildCardNode(i) {
+    const node = makeNode();
+    node.setAttribute('data-idx', String(i));
+    node.setAttribute('data-sig', _cardSig(i));
+    return node;
+}
+function _syncWindow(grid, start, end) {
+    for (const el of Array.from(grid.children)) {
+        const a = el.getAttribute('data-idx');
+        const idx = a == null ? NaN : Number(a);
+        if (!(idx >= start && idx < end) || el.getAttribute('data-sig') !== _cardSig(idx)) el.remove();
+    }
+    const existing = new Map();
+    for (const el of grid.children) existing.set(Number(el.getAttribute('data-idx')), el);
+    let ref = grid.firstChild;
+    for (let i = start; i < end; i++) {
+        let node = existing.get(i);
+        if (!node) node = _buildCardNode(i);
+        if (node === ref) ref = ref.nextSibling;
+        else grid.insertBefore(node, ref);
+    }
+}
+
+const idxOf = (g) => g._kids.map((n) => Number(n.getAttribute('data-idx')));
+const uidOf = (g) => { const m = new Map(); for (const n of g._kids) m.set(Number(n.getAttribute('data-idx')), n._uid); return m; };
+function assertContig(g, start, end) {
+    const a = idxOf(g);
+    assert.strictEqual(a.length, end - start, `len == ${end - start}`);
+    for (let k = 0; k < a.length; k++) assert.strictEqual(a[k], start + k, `child ${k} == ${start + k}`);
+}
+
+const COLS = 6, WIN = 12 * COLS; // 12 rows visible
+
+test('window stays [start,end) contiguous scrolling down, one row at a time', () => {
+    const grid = makeGrid();
+    for (let row = 0; row < 40; row++) {
+        const start = row * COLS;
+        _syncWindow(grid, start, start + WIN);
+        assertContig(grid, start, start + WIN);
+    }
+});
+
+test('in-window card nodes are reused across a slide (no whole-window teardown)', () => {
+    const grid = makeGrid();
+    _syncWindow(grid, 0, WIN);
+    const before = uidOf(grid);
+    _syncWindow(grid, COLS, COLS + WIN); // slide down one row
+    const after = uidOf(grid);
+    let reused = 0, built = 0;
+    for (const [i, uid] of after) (before.get(i) === uid ? reused++ : built++);
+    assert.strictEqual(built, COLS, `only the entering row is built (${COLS}), got ${built}`);
+    assert.strictEqual(reused, WIN - COLS, 'every overlapping card node is reused');
+});
+
+test('scrolling back UP reuses nodes too and keeps order', () => {
+    const grid = makeGrid();
+    for (let row = 0; row < 30; row++) _syncWindow(grid, row * COLS, row * COLS + WIN);
+    let prev = uidOf(grid);
+    for (let row = 29; row >= 0; row--) {
+        const start = row * COLS;
+        _syncWindow(grid, start, start + WIN);
+        assertContig(grid, start, start + WIN);
+        const now = uidOf(grid);
+        for (const [i, uid] of prev) if (i >= start && i < start + WIN) assert.strictEqual(now.get(i), uid, `idx ${i} reused going up`);
+        prev = now;
+    }
+});
+
+test('a select-mode toggle rebuilds the visible window', () => {
+    const grid = makeGrid();
+    const start = 6 * COLS;
+    _syncWindow(grid, start, start + WIN);
+    const before = uidOf(grid);
+    state.selectMode = true;
+    _syncWindow(grid, start, start + WIN);
+    const after = uidOf(grid);
+    let rebuilt = 0;
+    for (const [i, uid] of before) if (after.get(i) !== uid) rebuilt++;
+    assert.strictEqual(rebuilt, WIN, 'select-mode change rebuilds every visible card');
+    assertContig(grid, start, start + WIN);
+    state.selectMode = false;
+});
+
+test('a large jump (rail seek) rebuilds cleanly with no stale survivors', () => {
+    const grid = makeGrid();
+    _syncWindow(grid, 0, WIN);
+    _syncWindow(grid, 1000 * COLS, 1000 * COLS + WIN); // non-overlapping jump
+    assertContig(grid, 1000 * COLS, 1000 * COLS + WIN);
+});

tests/plugins/achievements/conftest.py

@@ -7,6 +7,8 @@ import pytest
 from fastapi import FastAPI
 from fastapi.testclient import TestClient
 
+# Drop a sibling 'routes' cached by another plugin's tests (bare-name collision).
+sys.modules.pop('routes', None)
 import routes as ach_routes
 
 
@@ -26,3 +28,17 @@ def client(tmp_path):
     app = FastAPI()
     ach_routes.setup(app, {"config_dir": str(tmp_path)})
     return TestClient(app)
+
+
+@pytest.fixture(autouse=True)
+def _bind_ach_routes():
+    """Keep sys.modules['routes'] pointing at THIS plugin's routes for these tests."""
+    prev = sys.modules.get('routes')
+    sys.modules['routes'] = ach_routes
+    try:
+        yield
+    finally:
+        if prev is not None:
+            sys.modules['routes'] = prev
+        else:
+            sys.modules.pop('routes', None)

tests/plugins/tuner/conftest.py

@@ -5,6 +5,8 @@ sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent / 'plugins' /
 import pytest
 from fastapi import FastAPI
 from fastapi.testclient import TestClient
+# Drop a sibling 'routes' cached by another plugin's tests (bare-name collision).
+sys.modules.pop('routes', None)
 import routes as tuner_routes
 
 
@@ -22,3 +24,19 @@ def client(config_dir):
         "unregister_tuning_provider": lambda pid: None,
     })
     return TestClient(app)
+
+
+@pytest.fixture(autouse=True)
+def _bind_tuner_routes():
+    """Keep sys.modules['routes'] pointing at THIS plugin's routes for these
+    tests, so a runtime `import routes` in a test body resolves correctly
+    regardless of which other plugin's bare-named routes ran first."""
+    prev = sys.modules.get('routes')
+    sys.modules['routes'] = tuner_routes
+    try:
+        yield
+    finally:
+        if prev is not None:
+            sys.modules['routes'] = prev
+        else:
+            sys.modules.pop('routes', None)

tests/plugins/tuner/js/inject_player_button.test.js

@@ -0,0 +1,191 @@
+// Regression test for feedBack#800: tuner injectPlayerButton() must anchor the
+// injected button to a DIRECT-child button of #player-controls. The old
+// `controls.querySelector('button:last-child')` could resolve to a NESTED
+// button, and `controls.insertBefore(btn, nestedButton)` then throws
+// NotFoundError — which propagated out of the player-screen transition and
+// aborted its render.
+//
+// Same isolation strategy as the core tests/js suite: extract the real function
+// from source with extractFunction() and run it in a vm sandbox over a small
+// but faithful DOM model. The model's insertBefore() enforces the real DOM
+// invariant (reference node must be a direct child, else NotFoundError), and
+// querySelector() implements the exact semantics of both the old
+// (`button:last-child`) and new (`:scope > button:last-of-type`) selectors — so
+// reverting the fix makes this test throw.
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+
+const { extractFunction } = require('../../../js/test_utils');
+
+const UI_JS = path.join(__dirname, '..', '..', '..', '..', 'plugins', 'tuner', 'utils', 'ui.js');
+const SRC = fs.readFileSync(UI_JS, 'utf8');
+const FN_SRC = extractFunction(SRC, 'function injectPlayerButton(');
+
+// ── Minimal, faithful DOM model ──────────────────────────────────────────────
+
+class El {
+    constructor(tag, id = '') {
+        this.tagName = tag.toUpperCase();
+        this.id = id;
+        this.children = [];
+        this.parentNode = null;
+        this.textContent = '';
+        this.title = '';
+        this.onclick = null;
+    }
+    appendChild(node) {
+        node.parentNode = this;
+        this.children.push(node);
+        return node;
+    }
+    insertBefore(node, ref) {
+        const idx = this.children.indexOf(ref);
+        if (ref == null || idx === -1) {
+            // Faithful to the browser: ref must be a direct child.
+            const e = new Error(
+                "Failed to execute 'insertBefore' on 'Node': The node before which the "
+                + 'new node is to be inserted is not a child of this node.'
+            );
+            e.name = 'NotFoundError';
+            throw e;
+        }
+        node.parentNode = this;
+        this.children.splice(idx, 0, node);
+        return node;
+    }
+    querySelector(sel) {
+        if (sel === ':scope > button:last-of-type') {
+            // Last direct-child <button>.
+            const btns = this.children.filter((c) => c.tagName === 'BUTTON');
+            return btns.length ? btns[btns.length - 1] : null;
+        }
+        if (sel === 'button:last-child') {
+            // First descendant <button> (document order) that is the last child
+            // of its own parent — the buggy legacy anchor.
+            let found = null;
+            const walk = (node) => {
+                for (const c of node.children) {
+                    if (found) return;
+                    const isLast = c.parentNode.children[c.parentNode.children.length - 1] === c;
+                    if (c.tagName === 'BUTTON' && isLast) { found = c; return; }
+                    walk(c);
+                }
+            };
+            walk(this);
+            return found;
+        }
+        throw new Error(`unhandled selector in stub: ${sel}`);
+    }
+}
+
+function findById(node, id) {
+    if (!node) return null;
+    if (node.id === id) return node;
+    for (const c of node.children) {
+        const r = findById(c, id);
+        if (r) return r;
+    }
+    return null;
+}
+
+// Run the extracted injectPlayerButton() against a given controls tree.
+// Returns { controls, threw }.
+function run({ controls, isV3 = false, slot = null }) {
+    const roots = [controls, slot].filter(Boolean);
+    const document = {
+        getElementById(id) {
+            if (id === 'player-controls') return controls;
+            for (const r of roots) {
+                const hit = findById(r, id);
+                if (hit) return hit;
+            }
+            return null;
+        },
+        createElement(tag) { return new El(tag); },
+    };
+    const window = {
+        feedBack: isV3
+            ? { uiVersion: 'v3', ui: { playerControlSlot: () => slot } }
+            : { uiVersion: 'v2' },
+        tuner: { toggle: () => {} },
+    };
+    const sandbox = {
+        window,
+        document,
+        Element: El,
+        updatePlayerButton: () => {},
+    };
+    vm.createContext(sandbox);
+    let threw = null;
+    try {
+        vm.runInContext(FN_SRC + '\nglobalThis.__run = injectPlayerButton;\n__run();', sandbox);
+    } catch (e) {
+        threw = e;
+    }
+    return { controls, slot, threw };
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+test('does not throw when the last button is nested (feedBack#800 repro)', () => {
+    // controls > div.transport > [play, close]; `close` is button:last-child of
+    // the div but NOT a direct child of controls. The old anchor threw here.
+    const controls = new El('div', 'player-controls');
+    const transport = new El('div');
+    transport.appendChild(new El('button', 'play'));
+    transport.appendChild(new El('button', 'close'));
+    controls.appendChild(transport);
+
+    const { threw } = run({ controls });
+    assert.equal(threw, null, threw && threw.message);
+    // With no direct-child button, it appends to controls.
+    assert.ok(findById(controls, 'btn-tuner-player'), 'tuner button was added');
+    assert.equal(controls.children[controls.children.length - 1].id, 'btn-tuner-player');
+});
+
+test('inserts before the last direct-child button when one exists', () => {
+    const controls = new El('div', 'player-controls');
+    controls.appendChild(new El('button', 'play'));
+    controls.appendChild(new El('button', 'close'));
+
+    const { threw } = run({ controls });
+    assert.equal(threw, null, threw && threw.message);
+    const ids = controls.children.map((c) => c.id);
+    // tuner button sits immediately before the last direct-child button.
+    assert.deepEqual(ids, ['play', 'btn-tuner-player', 'close']);
+});
+
+test('appends when controls has no buttons at all', () => {
+    const controls = new El('div', 'player-controls');
+    controls.appendChild(new El('span'));
+    const { threw } = run({ controls });
+    assert.equal(threw, null, threw && threw.message);
+    assert.equal(controls.children[controls.children.length - 1].id, 'btn-tuner-player');
+});
+
+test('is idempotent — a second call does not add a duplicate', () => {
+    const controls = new El('div', 'player-controls');
+    controls.appendChild(new El('button', 'close'));
+    run({ controls });
+    run({ controls });
+    const injected = controls.children.filter((c) => c.id === 'btn-tuner-player');
+    assert.equal(injected.length, 1);
+});
+
+test('v3 mounts into the plugin-control slot and never uses the legacy anchor', () => {
+    const slot = new El('div', 'plugin-control-slot');
+    // A nested button in the slot would trip the legacy anchor; v3 must ignore it.
+    const inner = new El('div');
+    inner.appendChild(new El('button', 'other'));
+    slot.appendChild(inner);
+    const controls = new El('div', 'player-controls');
+
+    const { threw } = run({ controls, isV3: true, slot });
+    assert.equal(threw, null, threw && threw.message);
+    assert.ok(findById(slot, 'btn-tuner-player'), 'tuner button mounted into the slot');
+    assert.equal(findById(controls, 'btn-tuner-player'), null, 'not mounted into #player-controls');
+});

tests/test_acoustid_match.py

@@ -0,0 +1,120 @@
+"""Pure-function tests for AcoustID fingerprint response parsing + config
+gating. No network, no fpcalc binary — server.py owns those seams."""
+import acoustid_match as a
+
+
+def _resp(score=0.97, rec_id="rec-1", title="Highway to Hell", artist="AC/DC",
+          rg_title="Highway to Hell", rg_type="Album", secondary=None,
+          year=1979, duration=208.4):
+    return {
+        "status": "ok",
+        "results": [{
+            "id": "acoustid-uuid",
+            "score": score,
+            "recordings": [{
+                "id": rec_id,
+                "title": title,
+                "duration": duration,
+                "artists": [{"id": "a1", "name": artist}],
+                "releasegroups": [{
+                    "id": "rg1", "title": rg_title, "type": rg_type,
+                    "secondarytypes": secondary or [],
+                    "releases": [{"date": {"year": year}}],
+                }],
+            }],
+        }],
+    }
+
+
+def test_parse_maps_the_studio_recording():
+    out = a.parse_lookup_response(_resp())
+    assert len(out) == 1
+    c = out[0]
+    assert c["recording_id"] == "rec-1"
+    assert c["title"] == "Highway to Hell"
+    assert c["artist"] == "AC/DC"
+    assert c["album"] == "Highway to Hell"
+    assert c["year"] == "1979"
+    assert c["duration"] == 208
+    assert c["studio"] is True
+    assert c["source"] == "acoustid"
+    assert c["mb_score"] == 97           # 0.97 → 0..100 confidence band
+    assert c["score"] == 0.97
+
+
+def test_live_release_group_is_not_studio():
+    out = a.parse_lookup_response(_resp(rg_type="Album", secondary=["Live"]))
+    assert out[0]["studio"] is False
+
+
+def test_compilation_is_not_studio():
+    out = a.parse_lookup_response(_resp(secondary=["Compilation"]))
+    assert out[0]["studio"] is False
+
+
+def test_prefers_studio_group_for_album_display():
+    resp = _resp()
+    # Add a comp release-group first; the studio one must win the album pick.
+    resp["results"][0]["recordings"][0]["releasegroups"].insert(0, {
+        "id": "rg0", "title": "Greatest Hits", "type": "Album",
+        "secondarytypes": ["Compilation"], "releases": [{"date": {"year": 2000}}],
+    })
+    c = a.parse_lookup_response(resp)[0]
+    assert c["album"] == "Highway to Hell"
+    assert c["studio"] is True
+
+
+def test_earliest_studio_album_wins_over_later_one():
+    # Two studio "Album" groups (e.g. a later soundtrack typed Album). The
+    # ORIGINAL — earliest release year — must win the album pick, not whichever
+    # AcoustID happened to list first. (Real case: "Machine Head" over a later
+    # comp for "Smoke on the Water".)
+    resp = _resp(rg_title="Machine Head", year=1972)
+    resp["results"][0]["recordings"][0]["releasegroups"].insert(0, {
+        "id": "rg-late", "title": "Later Studio Album", "type": "Album",
+        "secondarytypes": [], "releases": [{"date": {"year": 1997}}],
+    })
+    c = a.parse_lookup_response(resp)[0]
+    assert c["album"] == "Machine Head"
+    assert c["year"] == "1972"
+
+
+def test_year_is_earliest_release_not_a_reissue():
+    # A group's first-listed release is often a reissue; the year must be the
+    # EARLIEST across the group's releases (real case: British Steel's 1980
+    # original, not a 2010 reissue listed first).
+    resp = _resp(rg_title="British Steel", year=2010)
+    resp["results"][0]["recordings"][0]["releasegroups"][0]["releases"].append(
+        {"date": {"year": 1980}})
+    c = a.parse_lookup_response(resp)[0]
+    assert c["year"] == "1980"
+
+
+def test_dedupes_recording_across_results():
+    resp = _resp()
+    resp["results"].append(dict(resp["results"][0]))  # same recording again
+    assert len(a.parse_lookup_response(resp)) == 1
+
+
+def test_non_ok_status_and_garbage_return_empty():
+    assert a.parse_lookup_response({"status": "error"}) == []
+    assert a.parse_lookup_response({}) == []
+    assert a.parse_lookup_response(None) == []
+    assert a.parse_lookup_response({"status": "ok", "results": []}) == []
+
+
+def test_higher_acoustid_score_ranks_first():
+    resp = _resp(score=0.55, rec_id="low")
+    resp["results"].append(_resp(score=0.99, rec_id="high")["results"][0])
+    out = a.parse_lookup_response(resp)
+    assert out[0]["recording_id"] == "high"
+
+
+def test_config_gating(monkeypatch):
+    monkeypatch.delenv("ACOUSTID_API_KEY", raising=False)
+    assert a.api_key() == ""
+    assert a.is_configured() is False
+    assert a.is_configured("explicit-key") is True
+    monkeypatch.setenv("ACOUSTID_API_KEY", "envkey")
+    assert a.api_key() == "envkey"
+    assert a.is_configured() is True

tests/test_albums_view.py

@@ -23,6 +23,7 @@ def server(tmp_path, monkeypatch, isolate_logging):
     finally:
         conn = getattr(getattr(srv, "meta_db", None), "conn", None)
         if conn is not None:
+            getattr(__import__("sys").modules.get("server"), "_join_background_db_threads", lambda: None)()
             conn.close()
         sys.modules.pop("server", None)
 

tests/test_art_candidates.py

@@ -0,0 +1,371 @@
+"""Tests for the PR-C cover picker's server side: the /art/candidates
+assembly (current + pack + Cover Art Archive index candidates), the
+`caa_index_{id}.json` TTL-less cache around the new `_caa_release_index`
+seam, the `?source=pack` art-route variant, and the redirect-following
+art-by-URL fetch that lets a CAA pick apply through the existing
+override lane.
+
+Both network seams (`_caa_release_index`, `requests.get` under
+`_fetch_art_url`) are faked — nothing here opens a socket, and the
+offline default is itself asserted. Fixture patterns mirror
+tests/test_art_layer.py.
+"""
+
+import importlib
+import io as _io
+import sys
+
+import pytest
+from fastapi.testclient import TestClient
+from PIL import Image
+
+
+@pytest.fixture()
+def server(tmp_path, monkeypatch, isolate_logging):
+    monkeypatch.setenv("CONFIG_DIR", str(tmp_path / "config"))
+    dlc = tmp_path / "dlc"
+    dlc.mkdir()
+    monkeypatch.setenv("DLC_DIR", str(dlc))
+    monkeypatch.setenv("FEEDBACK_SKIP_STARTUP_TASKS", "1")
+    sys.modules.pop("server", None)
+    srv = importlib.import_module("server")
+    try:
+        yield srv
+    finally:
+        conn = getattr(getattr(srv, "meta_db", None), "conn", None)
+        if conn is not None:
+            getattr(__import__("sys").modules.get("server"), "_join_background_db_threads", lambda: None)()
+            conn.close()
+        sys.modules.pop("server", None)
+
+
+@pytest.fixture()
+def client(server):
+    return TestClient(server.app)
+
+
+def png_bytes(color=(200, 30, 30)):
+    buf = _io.BytesIO()
+    Image.new("RGB", (4, 4), color).save(buf, "PNG")
+    return buf.getvalue()
+
+
+def b64(data):
+    import base64
+    return base64.b64encode(data).decode()
+
+
+def make_sloppak(server, name, with_cover=False, title="Song", artist="Artist"):
+    d = server.DLC_DIR / name
+    d.mkdir(parents=True)
+    (d / "manifest.yaml").write_text(
+        f"title: {title}\nartist: {artist}\nduration: 100\n"
+        "arrangements: []\nstems: []\n", encoding="utf-8")
+    if with_cover:
+        (d / "cover.jpg").write_bytes(png_bytes((10, 200, 10)))
+    server.meta_db.put(name, 0, 0, {
+        "title": title, "artist": artist, "album": "", "year": "",
+        "duration": 100, "arrangements": [{"name": "Lead", "index": 0}],
+    })
+    return d
+
+
+def _match_row(server, fn, release_id="rel-1", state="matched"):
+    """Seed a matched/manual enrichment row with a release id (as the P8
+    matcher would have written)."""
+    song = server.meta_db.enrichment_song_row(fn)
+    h = server.meta_db.enrichment_content_hash(
+        song["artist"], song["title"], song["album"], song["duration"])
+    server.meta_db.apply_enrichment_match(
+        fn, h, state, source="text", score=1.0,
+        cand={"recording_id": "rec-1", "release_id": release_id,
+              "title": song["title"], "artist": song["artist"]})
+
+
+def _review_row(server, fn, candidates):
+    """Seed a review-tier row: no canonical release of its own, releases
+    live only in the stored candidates JSON."""
+    song = server.meta_db.enrichment_song_row(fn)
+    h = server.meta_db.enrichment_content_hash(
+        song["artist"], song["title"], song["album"], song["duration"])
+    server.meta_db.apply_enrichment_match(
+        fn, h, "review", source="text", score=0.75, candidates=candidates)
+
+
+def _img(img_id, *, front=False, approved=True, sizes=("500",)):
+    """One CAA index image dict, with thumbnails for the given size keys."""
+    return {
+        "id": img_id,
+        "front": front,
+        "approved": approved,
+        "types": ["Front"] if front else ["Back"],
+        "image": f"https://caa.example/full/{img_id}.jpg",
+        "thumbnails": {s: f"https://caa.example/{img_id}-{s}.jpg" for s in sizes},
+    }
+
+
+@pytest.fixture()
+def caa_index(server, monkeypatch):
+    """Fake CAA index transport + network flag on (mirrors the art-layer
+    `caa` fixture; this is the picker's own seam)."""
+    calls = []
+    indexes = {
+        "rel-1": {"images": [_img(101, front=True),
+                             _img(102, approved=False, sizes=("250",))]},
+        "rel-2": {"images": [_img(201, front=True)]},
+    }
+
+    def fake(release_id):
+        calls.append(release_id)
+        return indexes.get(release_id)   # unknown release → None (a CAA 404)
+    fake.calls, fake.indexes = calls, indexes
+    monkeypatch.setattr(server, "_caa_release_index", fake)
+    monkeypatch.setattr(server, "_enrich_network_enabled", lambda: True)
+    return fake
+
+
+def _get(client, fn="a.sloppak"):
+    r = client.get(f"/api/song/{fn}/art/candidates")
+    assert r.status_code == 200
+    return r.json()
+
+
+def _caa(body):
+    return [c for c in body["candidates"] if c["kind"] == "caa"]
+
+
+def _current(body):
+    return next(c for c in body["candidates"] if c["kind"] == "current")
+
+
+# ── candidate assembly ────────────────────────────────────────────────────────
+
+def test_matched_row_lists_index_images(server, client, caa_index):
+    make_sloppak(server, "a.sloppak")                 # no pack art
+    _match_row(server, "a.sloppak", release_id="rel-1")
+    body = _get(client)
+    assert body["pending"] is False
+    cur = _current(body)
+    assert cur["provenance"] == "none"                # nothing served yet
+    assert not any(c["kind"] == "pack" for c in body["candidates"])
+    caa = _caa(body)
+    assert [c["thumb_url"] for c in caa] == [
+        "https://caa.example/101-500.jpg",            # front, 500px
+        "https://caa.example/102-250.jpg",            # 250 fallback
+    ]
+    assert caa[0]["provenance"] == "matched"
+    assert caa[0]["approved"] is True and caa[1]["approved"] is False
+    assert caa[0]["release_id"] == "rel-1"
+    assert caa_index.calls == ["rel-1"]               # one index fetch
+
+
+def test_review_row_includes_candidate_releases(server, client, caa_index):
+    make_sloppak(server, "a.sloppak")
+    _review_row(server, "a.sloppak", [
+        {"recording_id": "rec-1", "title": "Song", "release_id": "rel-1"},
+        {"recording_id": "rec-2", "title": "Song", "release_id": "rel-2"},
+        {"recording_id": "rec-3", "title": "Song", "release_id": "rel-1"},  # dupe
+        {"recording_id": "rec-4", "title": "Song"},   # no release — skipped
+    ])
+    body = _get(client)
+    assert caa_index.calls == ["rel-1", "rel-2"]      # deduped, in order
+    assert {c["release_id"] for c in _caa(body)} == {"rel-1", "rel-2"}
+    assert len(_caa(body)) == 3
+
+
+def test_rejected_row_skips_caa_fetch(server, client, caa_index):
+    """A row the user rejected (failed/rejected) has no accepted match, so the
+    picker must not spend the shared CAA budget on its stale candidates. The
+    Current tile still serves; the index seam is never asked."""
+    make_sloppak(server, "a.sloppak")
+    _review_row(server, "a.sloppak", [
+        {"recording_id": "rec-1", "title": "Song", "release_id": "rel-1"}])
+    assert server.meta_db.set_enrichment_rejected("a.sloppak")
+    body = _get(client)
+    assert _caa(body) == []
+    assert caa_index.calls == []
+    assert _current(body)["kind"] == "current"
+
+
+def test_unmatched_instant_tiles_only(server, client, caa_index):
+    """No enrichment row at all → current (+ pack when it exists), empty
+    caa list, and the index seam is never asked."""
+    make_sloppak(server, "a.sloppak", with_cover=True)
+    body = _get(client)
+    kinds = [c["kind"] for c in body["candidates"]]
+    assert kinds == ["current", "pack"]
+    assert _current(body)["provenance"] == "pack"
+    pack = body["candidates"][1]
+    assert pack["thumb_url"].endswith("?source=pack")
+    assert caa_index.calls == []
+
+
+def test_override_provenance_is_yours(server, client, caa_index):
+    make_sloppak(server, "a.sloppak", with_cover=True)
+    assert client.post("/api/song/a.sloppak/art/upload",
+                       json={"image": b64(png_bytes((1, 2, 3)))}).json()["ok"]
+    body = _get(client)
+    assert _current(body)["provenance"] == "yours"
+    # Pack original stays offered even while the override is what serves.
+    assert any(c["kind"] == "pack" for c in body["candidates"])
+
+
+def test_offline_empty_caa_list_no_error(server, client):
+    """Under the plain test env the REAL index seam refuses (offline guard);
+    the endpoint still answers 200 with the instant tiles and caches
+    nothing (a later open retries)."""
+    make_sloppak(server, "a.sloppak")
+    _match_row(server, "a.sloppak", release_id="rel-1")
+    body = _get(client)
+    assert _caa(body) == []
+    assert _current(body)["kind"] == "current"
+    assert list(server.ART_CACHE_DIR.glob("caa_index_*.json")) == []
+
+
+def test_index_cached_second_call_no_refetch(server, client, caa_index):
+    make_sloppak(server, "a.sloppak")
+    _match_row(server, "a.sloppak", release_id="rel-1")
+    first = _get(client)
+    assert len(caa_index.calls) == 1
+    cache = server.ART_CACHE_DIR / "caa_index_rel-1.json"
+    assert cache.is_file()                            # TTL-less on-disk cache
+    # Even a changed upstream index is not re-asked — indexes are stable.
+    caa_index.indexes["rel-1"] = {"images": []}
+    second = _get(client)
+    assert len(caa_index.calls) == 1                  # no refetch
+    assert _caa(second) == _caa(first)
+
+
+def test_404_release_cached_as_empty(server, client, caa_index):
+    """A coverless release (CAA 404 → seam returns None) yields no tiles and
+    is never re-asked either."""
+    make_sloppak(server, "a.sloppak")
+    _match_row(server, "a.sloppak", release_id="rel-missing")
+    assert _caa(_get(client)) == []
+    assert _caa(_get(client)) == []
+    assert caa_index.calls == ["rel-missing"]
+
+
+def test_caa_candidates_capped_at_12(server, client, caa_index):
+    make_sloppak(server, "a.sloppak")
+    caa_index.indexes["rel-big"] = {
+        "images": [_img(300 + i, front=(i == 0)) for i in range(20)]}
+    _match_row(server, "a.sloppak", release_id="rel-big")
+    assert len(_caa(_get(client))) == server._ART_PICKER_MAX_CAA == 12
+
+
+def test_demo_mode_blocks_candidates(server, client, monkeypatch):
+    """Read-only, but it spends the shared CAA rate budget — blocked in demo
+    like enrichment search/kick."""
+    make_sloppak(server, "a.sloppak")
+    monkeypatch.setenv("FEEDBACK_DEMO_MODE", "1")
+    r = client.get("/api/song/a.sloppak/art/candidates")
+    assert r.status_code == 403
+    assert r.json() == {"error": "demo mode: read-only"}
+
+
+def test_unknown_song_404(server, client):
+    assert client.get("/api/song/ghost.sloppak/art/candidates").status_code == 404
+
+
+# ── traversal / injection hardening ───────────────────────────────────────────
+
+def test_malicious_release_id_rejected_no_fetch_no_write(server, caa_index):
+    """A crafted release id (path traversal) never matches _CAA_ID_RE, so it
+    yields no images, opens no socket, and writes no cache file — inside the
+    art dir or anywhere else."""
+    art_dir = server._enrichment_art_dir()
+    before = set(art_dir.glob("*"))
+    assert not server._CAA_ID_RE.match("../../etc/x")
+    assert server._caa_index_cached("../../etc/x") == []
+    assert caa_index.calls == []                       # the seam was never asked
+    assert set(art_dir.glob("*")) == before            # nothing written
+    # And nothing landed at the traversal target beside the cache dir either.
+    assert not (art_dir.parent / "etc").exists()
+
+
+def test_candidates_route_rejects_traversal_filename(server, client, caa_index):
+    """A traversal filename resolves outside DLC_DIR → _resolve_dlc_path
+    refuses it, the route 404s, and the CAA seam is never touched."""
+    for path in ("..%2F..%2Fsecret", "%2e%2e%2f%2e%2e%2fsecret", "../../secret"):
+        r = client.get(f"/api/song/{path}/art/candidates")
+        assert r.status_code == 404, path
+    assert caa_index.calls == []
+
+
+# ── the ?source=pack serve variant ────────────────────────────────────────────
+
+def test_pack_source_serves_pack_under_override(server, client):
+    """The Pack-original tile's thumb must show the pack's own art even while
+    an override is what the plain route serves — and 404 when the song ships
+    no art of its own."""
+    make_sloppak(server, "a.sloppak", with_cover=True)
+    assert client.post("/api/song/a.sloppak/art/upload",
+                       json={"image": b64(png_bytes((1, 2, 3)))}).json()["ok"]
+    assert client.get("/api/song/a.sloppak/art").headers["content-type"] == "image/png"
+    r = client.get("/api/song/a.sloppak/art?source=pack")
+    assert r.status_code == 200
+    assert r.headers["content-type"] == "image/jpeg"  # the pack cover, not the override
+    make_sloppak(server, "bare.sloppak")
+    assert client.get("/api/song/bare.sloppak/art?source=pack").status_code == 404
+
+
+# ── art-by-URL redirect handling (what makes a CAA pick applyable) ────────────
+
+class _FakeResp:
+    def __init__(self, status, headers=None, chunks=()):
+        self.status_code = status
+        self.headers = headers or {}
+        self._chunks = chunks
+
+    def iter_content(self, _size):
+        return iter(self._chunks)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        return False
+
+
+def test_fetch_art_url_follows_redirects_validating_each_hop(server, monkeypatch):
+    import requests
+    fetched, checked = [], []
+
+    def fake_get(url, **kw):
+        fetched.append(url)
+        assert kw.get("allow_redirects") is False     # hops stay manual
+        if "coverartarchive.example" in url:
+            return _FakeResp(307, {"Location": "https://archive.example/img.png"})
+        return _FakeResp(200, chunks=[b"IMGDATA"])
+
+    monkeypatch.setattr(requests, "get", fake_get)
+    monkeypatch.setattr(server, "_enrich_network_enabled", lambda: True)
+    monkeypatch.setattr(server, "_url_host_is_internal",
+                        lambda u: (checked.append(u), False)[1])
+    data = server._fetch_art_url("https://coverartarchive.example/release/x/front-500")
+    assert data == b"IMGDATA"
+    assert fetched == ["https://coverartarchive.example/release/x/front-500",
+                       "https://archive.example/img.png"]
+    assert checked == fetched                          # every hop was gated
+
+
+def test_fetch_art_url_blocks_redirect_to_internal(server, monkeypatch):
+    import requests
+    monkeypatch.setattr(requests, "get", lambda url, **kw: _FakeResp(
+        302, {"Location": "http://internal.example/x.png"}))
+    monkeypatch.setattr(server, "_enrich_network_enabled", lambda: True)
+    monkeypatch.setattr(server, "_url_host_is_internal",
+                        lambda u: "internal" in u)
+    with pytest.raises(ValueError):
+        server._fetch_art_url("https://public.example/x.png")
+
+
+def test_fetch_art_url_redirect_budget(server, monkeypatch):
+    import requests
+    monkeypatch.setattr(requests, "get", lambda url, **kw: _FakeResp(
+        307, {"Location": "https://public.example/next.png"}))
+    monkeypatch.setattr(server, "_enrich_network_enabled", lambda: True)
+    monkeypatch.setattr(server, "_url_host_is_internal", lambda u: False)
+    with pytest.raises(server.EnrichTransportError):
+        server._fetch_art_url("https://public.example/x.png")

tests/test_art_layer.py

@@ -29,6 +29,7 @@ def server(tmp_path, monkeypatch, isolate_logging):
     finally:
         conn = getattr(getattr(srv, "meta_db", None), "conn", None)
         if conn is not None:
+            getattr(__import__("sys").modules.get("server"), "_join_background_db_threads", lambda: None)()
             conn.close()
         sys.modules.pop("server", None)
 

tests/test_artist_alias.py

@@ -22,6 +22,7 @@ def server(tmp_path, monkeypatch, isolate_logging):
     finally:
         conn = getattr(getattr(srv, "meta_db", None), "conn", None)
         if conn is not None:
+            getattr(__import__("sys").modules.get("server"), "_join_background_db_threads", lambda: None)()
             conn.close()
         sys.modules.pop("server", None)
 
@@ -209,3 +210,47 @@ def test_list_aliases_sorted(client, server):
     _alias(client, "guns n roses", "Guns N' Roses")
     aliases = client.get("/api/artist-aliases").json()["aliases"]
     assert {a["raw_name"] for a in aliases} == {"ACDC", "guns n roses"}
+
+
+# ── Search (q) matches merged aliases (launch polish) ─────────────────────────
+
+def _search(client, q):
+    return {s["filename"] for s in
+            client.get("/api/library", params={"q": q}).json()["songs"]}
+
+
+def test_search_canonical_finds_raw_variants(client, server):
+    """Searching the canonical name must also find songs whose raw tag is a
+    merged variant — after ACDC→AC/DC, q="AC/DC" returns both."""
+    _seed(server, "a.archive", "ACDC")
+    _seed(server, "b.archive", "AC/DC")
+    _seed(server, "c.archive", "Other")
+    _alias(client, "ACDC", "AC/DC")
+    assert _search(client, "AC/DC") == {"a.archive", "b.archive"}
+
+
+def test_search_partial_canonical_finds_raw_variants(client, server):
+    """The alias term is a LIKE, matching the substring semantics of the
+    plain artist term."""
+    _seed(server, "a.archive", "ACDC")
+    _seed(server, "b.archive", "Other")
+    _alias(client, "ACDC", "AC/DC")
+    assert _search(client, "c/d") == {"a.archive"}
+
+
+def test_search_without_aliases_unchanged(client, server):
+    """No aliases → the fast path keeps the original 3-term search."""
+    _seed(server, "a.archive", "ACDC")
+    _seed(server, "b.archive", "AC/DC")
+    assert _search(client, "ACDC") == {"a.archive"}
+
+
+def test_search_title_album_unaffected_by_alias_term(client, server):
+    """With aliases present (extra placeholder appended), title/album search
+    still works — guards the parameter order."""
+    _seed(server, "a.archive", "ACDC")                       # title "a"
+    _alias(client, "ACDC", "AC/DC")
+    server.meta_db.put("t.archive", 0, 0,
+                       {"title": "Thunder Road", "artist": "Boss", "album": "Born"})
+    assert _search(client, "Thunder") == {"t.archive"}
+    assert _search(client, "Born") == {"t.archive"}

tests/test_artist_page.py

@@ -0,0 +1,408 @@
+"""Server tests for the artist-pages layer (PR-B, artist-pages launch charrette).
+
+Two halves, mirroring the design's split:
+
+* GET /api/artist/{name}/page — the all-LOCAL payload. Covers the counts /
+  albums / alias variants, the DENOMINATOR LAW (mastered counts songs YOU OWN,
+  never anything external — locked position 2), similar-in-library genre
+  co-occurrence (in-library artists only, self excluded, empty → empty), and
+  mb_artist_id resolution from matched/manual rows only.
+
+* GET /api/artist/{name}/links + POST .../links/refresh — the lazy, cached,
+  opt-in external-links layer. The HTTP transport is a fake over
+  `server._mb_http_get` (the ONE network seam — same pattern as
+  tests/test_mb_enrichment.py), so nothing here opens a socket. Covers the
+  url-rel whitelist mapping, the http(s) scheme gate (a hostile javascript:
+  resource never reaches a link slot), cache-hit second calls making no
+  network call, the offline guard, the default-OFF setting gate, and the
+  demo-mode blocks.
+"""
+
+import importlib
+import json
+import sys
+from urllib.parse import quote
+
+import pytest
+from fastapi.testclient import TestClient
+
+
+@pytest.fixture()
+def server(tmp_path, monkeypatch, isolate_logging):
+    monkeypatch.setenv("CONFIG_DIR", str(tmp_path / "config"))
+    dlc = tmp_path / "dlc"
+    dlc.mkdir()
+    monkeypatch.setenv("DLC_DIR", str(dlc))
+    monkeypatch.setenv("FEEDBACK_SKIP_STARTUP_TASKS", "1")
+    sys.modules.pop("server", None)
+    srv = importlib.import_module("server")
+    try:
+        yield srv
+    finally:
+        conn = getattr(getattr(srv, "meta_db", None), "conn", None)
+        if conn is not None:
+            getattr(__import__("sys").modules.get("server"), "_join_background_db_threads", lambda: None)()
+            conn.close()
+        sys.modules.pop("server", None)
+
+
+@pytest.fixture()
+def client(server):
+    return TestClient(server.app)
+
+
+MBID = "66c662b6-6e2f-4930-8610-912e24c63ed1"
+
+
+def _put(server, fn, title=None, artist="AC/DC", album="", year="",
+         genre="", duration=200):
+    server.meta_db.put(fn, 0, 0, {
+        "title": title or fn.split(".")[0], "artist": artist, "album": album,
+        "year": year, "genre": genre, "duration": duration,
+        "arrangements": [{"name": "Lead", "index": 0}],
+    })
+
+
+def _pin_match(server, fn, artist_id=MBID):
+    """Give a song a user-pinned (manual) match carrying an artist MBID."""
+    assert server.meta_db.set_enrichment_manual(fn, {
+        "recording_id": "rec-1", "title": "T", "artist": "AC/DC",
+        "artist_id": artist_id,
+    })
+
+
+def _page(client, name="AC/DC"):
+    r = client.get("/api/artist/" + quote(name, safe="") + "/page")
+    assert r.status_code == 200
+    return r.json()
+
+
+class FakeMBArtist:
+    """Canned MusicBrainz artist lookup over the _mb_http_get seam."""
+
+    def __init__(self, srv):
+        self._srv = srv
+        self.calls = []
+        self.doc = artist_doc()
+        self.raise_transport = False
+
+    def __call__(self, path, params):
+        if self.raise_transport:
+            raise self._srv.EnrichTransportError("fake network down")
+        self.calls.append((path, dict(params)))
+        if path == f"artist/{MBID}":
+            return self.doc
+        raise AssertionError(f"unexpected MB path {path!r}")
+
+
+@pytest.fixture()
+def mb_artist(server, monkeypatch):
+    """Install the fake transport AND enable the network flag (the test env
+    disables it by default — see test_links_offline_returns_empty)."""
+    fake = FakeMBArtist(server)
+    monkeypatch.setattr(server, "_mb_http_get", fake)
+    monkeypatch.setattr(server, "_enrich_network_enabled", lambda: True)
+    return fake
+
+
+def artist_doc():
+    """An MB artist doc exercising the whole whitelist: a hostile javascript:
+    URL and an ftp:// URL (both must be scheme-gated out), non-whitelisted rel
+    types (must be dropped), one of each slot, and both wiki rels (wikipedia
+    must win over wikidata)."""
+    rel = lambda rtype, url: {"type": rtype, "url": {"resource": url}}
+    return {
+        "id": MBID,
+        "name": "AC/DC",
+        "relations": [
+            rel("official homepage", "javascript:alert(1)"),        # scheme-gated
+            rel("official homepage", "https://www.acdc.com"),       # first valid wins
+            rel("official homepage", "https://second.example"),
+            rel("setlistfm", "https://www.setlist.fm/setlists/acdc"),
+            rel("youtube", "https://www.youtube.com/acdc"),
+            rel("social network", "https://www.instagram.com/acdc"),
+            rel("bandcamp", "ftp://bad.example/acdc"),               # scheme-gated
+            rel("soundcloud", "https://soundcloud.com/acdc"),
+            rel("wikidata", "https://www.wikidata.org/wiki/Q27593"),
+            rel("wikipedia", "https://en.wikipedia.org/wiki/AC/DC"),
+            rel("streaming", "https://stream.example/acdc"),         # not whitelisted
+            rel("purchase for download", "https://store.example"),   # not whitelisted
+        ],
+        "genres": [{"name": "hard rock", "count": 10}, {"name": "rock", "count": 5}],
+    }
+
+
+def _enable_links(client):
+    r = client.post("/api/settings", json={"artist_external_links": True})
+    assert r.status_code == 200 and "error" not in r.json()
+
+
+# ── /page: counts, albums, variants ──────────────────────────────────────────
+
+def test_page_counts_albums_and_files(client, server):
+    _put(server, "a.sloppak", album="The Razors Edge", year="1990")
+    _put(server, "b.sloppak", album="The Razors Edge", year="1990")
+    _put(server, "c.sloppak", album="Back in Black", year="1980")
+    _put(server, "d.sloppak", album="")                      # loose, no album
+    _put(server, "x.sloppak", artist="Other Band", album="Elsewhere")
+    page = _page(client)
+    assert page["artist"] == "AC/DC"
+    assert page["song_count"] == 4                            # never the other artist
+    assert page["album_count"] == 2                           # empty album ≠ an album
+    albums = {a["name"]: a for a in page["albums"]}
+    assert albums["The Razors Edge"]["count"] == 2
+    assert albums["The Razors Edge"]["year"] == "1990"
+    assert albums["Back in Black"]["count"] == 1
+    assert set(page["files"]) == {"a.sloppak", "b.sloppak", "c.sloppak", "d.sloppak"}
+    # Mosaic art comes from the artist's own songs.
+    assert page["art_urls"] and all("/art" in u for u in page["art_urls"])
+
+
+def test_page_unknown_artist_is_zero_count_not_error(client, server):
+    page = _page(client, "Nobody Here")
+    assert page["artist"] == "Nobody Here"
+    assert page["song_count"] == 0
+    assert page["albums"] == [] and page["similar"] == []
+    assert page["mb_artist_id"] is None
+
+
+def test_page_canonicalizes_aliases_and_lists_variants(client, server):
+    _put(server, "a.sloppak", artist="ACDC", album="Alb")
+    _put(server, "b.sloppak", artist="AC/DC", album="Alb")
+    r = client.post("/api/artist-aliases",
+                    json={"raw_name": "ACDC", "canonical_name": "AC/DC"})
+    assert r.status_code == 200
+    # Asking by the RAW name lands on the same canonical page.
+    for name in ("AC/DC", "ACDC"):
+        page = _page(client, name)
+        assert page["artist"] == "AC/DC"
+        assert page["song_count"] == 2                        # both variants counted
+        assert page["variants"] == [{"name": "ACDC", "count": 1}]
+
+
+# ── /page: the denominator law ────────────────────────────────────────────────
+
+def test_mastered_counts_only_owned_songs(client, server):
+    """Locked position 2: 'N mastered' is over songs in YOUR library — a
+    song_stats row whose file left the library can never inflate it."""
+    _put(server, "a.sloppak")
+    _put(server, "b.sloppak")
+    _put(server, "c.sloppak")
+    server.meta_db.record_session("a.sloppak", 0, score=100, accuracy=0.95)   # mastered
+    server.meta_db.record_session("b.sloppak", 0, score=50, accuracy=0.5)     # in progress
+    # A mastered score for a song NOT in the library (deleted / renamed) —
+    # must not count: the denominator is ownership.
+    server.meta_db.record_session("gone.sloppak", 0, score=100, accuracy=0.99)
+    page = _page(client)
+    assert page["song_count"] == 3
+    assert page["mastered_count"] == 1
+    assert page["has_stats"] is True
+
+
+def test_mastered_uses_best_accuracy_across_arrangements(client, server):
+    _put(server, "a.sloppak")
+    server.meta_db.record_session("a.sloppak", 0, score=10, accuracy=0.4)
+    server.meta_db.record_session("a.sloppak", 1, score=90, accuracy=0.93)
+    assert _page(client)["mastered_count"] == 1
+
+
+def test_no_practice_data_reports_zero_and_flag(client, server):
+    """The frontend omits the mastered segment when it is 0 (invitational —
+    never '0 mastered'); the payload carries the honest numbers + flag."""
+    _put(server, "a.sloppak")
+    page = _page(client)
+    assert page["mastered_count"] == 0
+    assert page["has_stats"] is False
+
+
+# ── /page: similar-in-library ─────────────────────────────────────────────────
+
+def test_similar_ranks_genre_overlap_in_library_only(client, server):
+    _put(server, "a1.sloppak", artist="AC/DC", genre="Rock")
+    _put(server, "a2.sloppak", artist="AC/DC", genre="Blues")
+    _put(server, "b1.sloppak", artist="Band B", genre="rock")     # case folds
+    _put(server, "b2.sloppak", artist="Band B", genre="Blues")    # 2 shared genres
+    _put(server, "c1.sloppak", artist="Band C", genre="Rock")     # 1 shared genre
+    _put(server, "d1.sloppak", artist="Band D", genre="Jazz")     # no overlap
+    similar = _page(client)["similar"]
+    names = [s["artist"] for s in similar]
+    assert names[0] == "Band B"                                   # most shared genres
+    assert "Band C" in names
+    assert "Band D" not in names                                  # never non-overlapping
+    assert "AC/DC" not in names                                   # never self
+
+
+def test_similar_empty_without_genre_data(client, server):
+    _put(server, "a.sloppak", genre="")
+    _put(server, "b.sloppak", artist="Band B", genre="Rock")
+    assert _page(client)["similar"] == []
+
+
+def test_similar_folds_alias_variants(client, server):
+    _put(server, "a.sloppak", artist="AC/DC", genre="Rock")
+    _put(server, "b.sloppak", artist="Band B", genre="Rock")
+    _put(server, "b2.sloppak", artist="band b", genre="Rock")
+    client.post("/api/artist-aliases",
+                json={"raw_name": "band b", "canonical_name": "Band B"})
+    similar = _page(client)["similar"]
+    assert [s["artist"] for s in similar] == ["Band B"]           # one entry, folded
+    assert similar[0]["count"] == 2
+
+
+# ── /page: mb_artist_id resolution ────────────────────────────────────────────
+
+def test_page_mb_artist_id_from_matched_rows(client, server):
+    _put(server, "a.sloppak")
+    _pin_match(server, "a.sloppak")
+    assert _page(client)["mb_artist_id"] == MBID
+
+
+def test_page_ignores_unmatched_rows_artist_id(client, server):
+    """Only matched/manual rows are identity authority — a failed row's
+    leftover artist_id must not resurface."""
+    _put(server, "a.sloppak")
+    server.meta_db.conn.execute(
+        "INSERT INTO song_enrichment (filename, match_state, mb_artist_id) "
+        "VALUES ('a.sloppak', 'failed', ?)", (MBID,))
+    server.meta_db.conn.commit()
+    assert _page(client)["mb_artist_id"] is None
+
+
+# ── /links: setting gate, whitelist, scheme gate ─────────────────────────────
+
+def test_links_disabled_by_default_no_network(client, server, mb_artist):
+    _put(server, "a.sloppak")
+    _pin_match(server, "a.sloppak")
+    r = client.get("/api/artist/AC%2FDC/links")
+    assert r.status_code == 200
+    body = r.json()
+    assert body["links"] == {} and body.get("disabled") is True
+    assert mb_artist.calls == []                        # opt-in means opt-in
+
+
+def test_links_whitelist_mapping_and_scheme_gate(client, server, mb_artist):
+    _put(server, "a.sloppak")
+    _pin_match(server, "a.sloppak")
+    _enable_links(client)
+    r = client.get("/api/artist/AC%2FDC/links")
+    assert r.status_code == 200
+    body = r.json()
+    assert body["matched"] is True and body["cached"] is False
+    links = body["links"]
+    # The javascript: homepage is scheme-gated out; the first VALID one wins.
+    assert links["official"] == "https://www.acdc.com"
+    assert links["tour"] == "https://www.setlist.fm/setlists/acdc"
+    assert links["video"] == "https://www.youtube.com/acdc"
+    # Social collects; the ftp:// bandcamp is scheme-gated out.
+    assert links["social"] == ["https://www.instagram.com/acdc",
+                               "https://soundcloud.com/acdc"]
+    # Wikipedia preferred over wikidata when both exist.
+    assert links["wikipedia"] == "https://en.wikipedia.org/wiki/AC/DC"
+    # Nothing hostile or non-whitelisted anywhere in the payload.
+    dumped = json.dumps(body)
+    for bad in ("javascript:", "ftp://", "stream.example", "store.example"):
+        assert bad not in dumped
+    # One throttled lookup, with the url-rels include.
+    assert len(mb_artist.calls) == 1
+    path, params = mb_artist.calls[0]
+    assert path == f"artist/{MBID}"
+    assert "url-rels" in params.get("inc", "")
+
+
+def test_links_wikidata_fallback_when_no_wikipedia(client, server, mb_artist):
+    _put(server, "a.sloppak")
+    _pin_match(server, "a.sloppak")
+    _enable_links(client)
+    mb_artist.doc = {"id": MBID, "relations": [
+        {"type": "wikidata", "url": {"resource": "https://www.wikidata.org/wiki/Q27593"}},
+    ], "genres": []}
+    links = client.get("/api/artist/AC%2FDC/links").json()["links"]
+    assert links["wikipedia"] == "https://www.wikidata.org/wiki/Q27593"
+
+
+def test_links_cached_second_call_makes_no_network_call(client, server, mb_artist):
+    _put(server, "a.sloppak")
+    _pin_match(server, "a.sloppak")
+    _enable_links(client)
+    first = client.get("/api/artist/AC%2FDC/links").json()
+    assert first["cached"] is False and len(mb_artist.calls) == 1
+    second = client.get("/api/artist/AC%2FDC/links").json()
+    assert second["cached"] is True
+    assert second["links"] == first["links"]
+    assert len(mb_artist.calls) == 1                    # cache hit — no re-fetch
+
+
+def test_links_refresh_refetches_and_updates_cache(client, server, mb_artist):
+    _put(server, "a.sloppak")
+    _pin_match(server, "a.sloppak")
+    _enable_links(client)
+    client.get("/api/artist/AC%2FDC/links")
+    mb_artist.doc = {"id": MBID, "relations": [
+        {"type": "official homepage", "url": {"resource": "https://new.example"}},
+    ], "genres": []}
+    r = client.post("/api/artist/AC%2FDC/links/refresh")
+    assert r.status_code == 200
+    assert r.json()["links"]["official"] == "https://new.example"
+    assert len(mb_artist.calls) == 2
+    # And the refreshed value is what the next GET serves from cache.
+    again = client.get("/api/artist/AC%2FDC/links").json()
+    assert again["cached"] is True
+    assert again["links"]["official"] == "https://new.example"
+
+
+# ── /links: offline / unmatched / hostile-id guards ──────────────────────────
+
+def test_links_offline_returns_empty(client, server):
+    """The test env's offline default (FEEDBACK_SKIP_STARTUP_TASKS) doubles as
+    the kill-switch test: matched artist + links on, but no network → empty
+    links, no error, nothing cached."""
+    _put(server, "a.sloppak")
+    _pin_match(server, "a.sloppak")
+    _enable_links(client)
+    body = client.get("/api/artist/AC%2FDC/links").json()
+    assert body["links"] == {} and body.get("offline") is True
+    assert server.meta_db.get_artist_enrichment(MBID) is None
+
+
+def test_links_unmatched_artist_reports_matched_false(client, server, mb_artist):
+    _put(server, "a.sloppak")                            # no enrichment match
+    _enable_links(client)
+    body = client.get("/api/artist/AC%2FDC/links").json()
+    assert body == {"links": {}, "matched": False}
+    assert mb_artist.calls == []
+
+
+def test_links_rejects_malformed_stored_mbid(client, server, mb_artist):
+    """A hand-rolled /pick body can stuff junk into mb_artist_id — the strict
+    MBID shape gate must keep it off the MB request line."""
+    _put(server, "a.sloppak")
+    _pin_match(server, "a.sloppak", artist_id="evil/../../path")
+    _enable_links(client)
+    body = client.get("/api/artist/AC%2FDC/links").json()
+    assert body == {"links": {}, "matched": False}
+    assert mb_artist.calls == []
+
+
+# ── demo mode ─────────────────────────────────────────────────────────────────
+
+def test_links_routes_demo_blocked_page_stays_open(client, server, monkeypatch):
+    _put(server, "a.sloppak")
+    _pin_match(server, "a.sloppak")
+    monkeypatch.setenv("FEEDBACK_DEMO_MODE", "1")
+    assert client.get("/api/artist/AC%2FDC/links").status_code == 403
+    assert client.post("/api/artist/AC%2FDC/links/refresh").status_code == 403
+    # The all-local page read stays available to demo visitors.
+    assert client.get("/api/artist/AC%2FDC/page").status_code == 200
+
+
+# ── settings keys ─────────────────────────────────────────────────────────────
+
+def test_artist_page_settings_defaults_and_validation(client, server):
+    cfg = client.get("/api/settings").json()
+    assert cfg["artist_pages_enabled"] is True           # page is local-only → ON
+    assert cfg["artist_external_links"] is False         # links are opt-in → OFF
+    # Bool pattern: non-bool shapes return a structured error, not a 500.
+    for key in ("artist_pages_enabled", "artist_external_links"):
+        assert "error" in client.post("/api/settings", json={key: "yes"}).json()
+        assert "error" not in client.post("/api/settings", json={key: True}).json()
+        assert client.get("/api/settings").json()[key] is True

tests/test_artist_sort_title_order.py

@@ -22,6 +22,7 @@ def server(tmp_path, monkeypatch, isolate_logging):
     finally:
         conn = getattr(getattr(srv, "meta_db", None), "conn", None)
         if conn is not None:
+            getattr(__import__("sys").modules.get("server"), "_join_background_db_threads", lambda: None)()
             conn.close()
         sys.modules.pop("server", None)
 

tests/test_audio_effect_mappings.py

@@ -18,6 +18,7 @@ def client(tmp_path, monkeypatch):
             for attr in ("meta_db", "audio_effect_mappings"):
                 conn = getattr(getattr(server, attr, None), "conn", None)
                 if conn is not None:
+                    getattr(__import__("sys").modules.get("server"), "_join_background_db_threads", lambda: None)()
                     conn.close()
 
 

tests/test_audio_local_path.py

@@ -34,6 +34,7 @@ def client_and_server(tmp_path, monkeypatch):
         meta_db = getattr(server, "meta_db", None)
         conn = getattr(meta_db, "conn", None)
         if conn is not None:
+            getattr(__import__("sys").modules.get("server"), "_join_background_db_threads", lambda: None)()
             conn.close()
 
 
@@ -60,6 +61,7 @@ def non_loopback_client(tmp_path, monkeypatch):
         meta_db = getattr(server, "meta_db", None)
         conn = getattr(meta_db, "conn", None)
         if conn is not None:
+            getattr(__import__("sys").modules.get("server"), "_join_background_db_threads", lambda: None)()
             conn.close()
 
 

tests/test_batch_user_meta.py

@@ -22,6 +22,7 @@ def server(tmp_path, monkeypatch, isolate_logging):
     finally:
         conn = getattr(getattr(srv, "meta_db", None), "conn", None)
         if conn is not None:
+            getattr(__import__("sys").modules.get("server"), "_join_background_db_threads", lambda: None)()
             conn.close()
         sys.modules.pop("server", None)
 

tests/test_builtin_starter_seed.py

@@ -0,0 +1,234 @@
+"""Tests for one-time builtin starter-content seeding into DLC."""
+
+from __future__ import annotations
+
+import importlib
+import sys
+
+import pytest
+
+
+@pytest.fixture()
+def server_mod(tmp_path, monkeypatch, isolate_logging):
+    monkeypatch.setenv("CONFIG_DIR", str(tmp_path / "config"))
+    (tmp_path / "config").mkdir()
+    monkeypatch.delenv("DLC_DIR", raising=False)
+    sys.modules.pop("server", None)
+    mod = importlib.import_module("server")
+    yield mod
+
+
+def _source(server_mod):
+    return (
+        server_mod._feedBack_server_root()
+        / server_mod._BUILTIN_STARTER_SOURCES[0][1]
+    )
+
+
+def _dest(server_mod, dlc):
+    return (
+        dlc
+        / server_mod._BUILTIN_STARTER_SUBDIR
+        / server_mod._BUILTIN_STARTER_SOURCES[0][0]
+    )
+
+
+def test_seed_creates_starter_content_and_marker(tmp_path, server_mod):
+    """First run copies the bundled feedpak into starter/ and writes the marker."""
+    dlc = tmp_path / "dlc"
+    dlc.mkdir()
+    source = _source(server_mod)
+    if not source.is_file():
+        pytest.skip(f"starter source not present in checkout: {source}")
+
+    server_mod._seed_builtin_starter_content(dlc)
+
+    dest = _dest(server_mod, dlc)
+    assert dest.is_file()
+    assert dest.stat().st_size == source.stat().st_size
+    assert (server_mod.CONFIG_DIR / server_mod._STARTER_SEED_MARKER).is_file()
+
+
+def test_seed_preserves_source_mtime(tmp_path, server_mod):
+    """The seeded pack keeps the bundle's mtime so the diagnostic refresh check
+    (source newer than dest -> update) stays correct across both write paths."""
+    dlc = tmp_path / "dlc"
+    dlc.mkdir()
+    source = _source(server_mod)
+    if not source.is_file():
+        pytest.skip(f"starter source not present in checkout: {source}")
+
+    server_mod._seed_builtin_starter_content(dlc)
+
+    assert _dest(server_mod, dlc).stat().st_mtime_ns == source.stat().st_mtime_ns
+
+
+def test_starter_is_not_carved_out_of_the_library():
+    """`starter/` must NOT collide with the diagnostics/tutorials carve-out —
+    otherwise seeded songs would never appear in the library listing."""
+    assert "starter" not in {"diagnostics-builtin", "tutorials-builtin"}
+
+
+def test_seed_runs_only_once_and_respects_deletion(tmp_path, server_mod):
+    """After the first seed, deleting the song does NOT bring it back: the
+    marker makes starter seeding a one-time welcome."""
+    dlc = tmp_path / "dlc"
+    dlc.mkdir()
+    source = _source(server_mod)
+    if not source.is_file():
+        pytest.skip(f"starter source not present in checkout: {source}")
+
+    server_mod._seed_builtin_starter_content(dlc)
+    dest = _dest(server_mod, dlc)
+    assert dest.is_file()
+
+    # User removes the starter song.
+    dest.unlink()
+
+    # A subsequent launch must not re-seed it.
+    server_mod._seed_builtin_starter_content(dlc)
+    assert not dest.exists()
+
+
+def test_seed_deferred_until_dlc_configured(tmp_path, server_mod):
+    """With no DLC folder, seeding is skipped WITHOUT writing the marker, so it
+    retries once a library folder exists."""
+    source = _source(server_mod)
+    if not source.is_file():
+        pytest.skip(f"starter source not present in checkout: {source}")
+
+    # dlc is None and DLC_DIR unset -> _get_dlc_dir() returns None.
+    server_mod._seed_builtin_starter_content(None)
+    assert not (server_mod.CONFIG_DIR / server_mod._STARTER_SEED_MARKER).exists()
+
+    # Now a DLC is configured: the deferred seed runs.
+    dlc = tmp_path / "dlc"
+    dlc.mkdir()
+    server_mod._seed_builtin_starter_content(dlc)
+    assert _dest(server_mod, dlc).is_file()
+    assert (server_mod.CONFIG_DIR / server_mod._STARTER_SEED_MARKER).is_file()
+
+
+def test_seed_refuses_symlinked_seed_directory(tmp_path, server_mod):
+    """A symlinked starter/ dir is refused so copies can't escape the DLC tree."""
+    dlc = tmp_path / "dlc"
+    dlc.mkdir()
+    source = _source(server_mod)
+    if not source.is_file():
+        pytest.skip(f"starter source not present in checkout: {source}")
+
+    outside_dir = tmp_path / "outside"
+    outside_dir.mkdir()
+    (dlc / server_mod._BUILTIN_STARTER_SUBDIR).symlink_to(outside_dir)
+
+    server_mod._seed_builtin_starter_content(dlc)
+
+    assert list(outside_dir.iterdir()) == []
+    # An incomplete seed must NOT write the marker, so a later launch retries.
+    assert not (server_mod.CONFIG_DIR / server_mod._STARTER_SEED_MARKER).exists()
+
+
+def test_seed_never_overwrites_an_existing_user_file(tmp_path, server_mod):
+    """One-time starter seeding must never replace a user's own file at the
+    destination, even if the bundled pack has a newer mtime."""
+    import os as _os
+
+    dlc = tmp_path / "dlc"
+    dlc.mkdir()
+    dest = _dest(server_mod, dlc)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_bytes(b"user's own edited pack")
+    _os.utime(dest, (1_000_000, 1_000_000))  # far older than the bundled source
+
+    server_mod._seed_builtin_starter_content(dlc)
+
+    assert dest.read_bytes() == b"user's own edited pack"  # untouched
+    # counted as already-present, so the one-time seed considers itself done
+    assert (server_mod.CONFIG_DIR / server_mod._STARTER_SEED_MARKER).is_file()
+
+
+def test_seed_does_not_mark_when_destination_is_a_directory(tmp_path, server_mod):
+    """A directory sitting at the destination name is neither clobbered nor
+    counted as present, so the marker stays unwritten and seeding retries."""
+    dlc = tmp_path / "dlc"
+    dlc.mkdir()
+    source = _source(server_mod)
+    if not source.is_file():
+        pytest.skip(f"starter source not present in checkout: {source}")
+
+    bogus = _dest(server_mod, dlc)
+    bogus.parent.mkdir(parents=True, exist_ok=True)
+    bogus.mkdir()  # user (or junk) placed a directory where the pack goes
+
+    server_mod._seed_builtin_starter_content(dlc)
+
+    assert bogus.is_dir()  # untouched
+    assert not (server_mod.CONFIG_DIR / server_mod._STARTER_SEED_MARKER).exists()
+
+
+def test_seed_does_not_mark_when_source_missing(tmp_path, server_mod, monkeypatch):
+    """If a starter source can't be found, the marker stays unwritten and the
+    seed is retried on the next launch (rather than permanently skipped)."""
+    dlc = tmp_path / "dlc"
+    dlc.mkdir()
+    monkeypatch.setattr(
+        server_mod,
+        "_BUILTIN_STARTER_SOURCES",
+        [("missing.feedpak", "content/starter/does-not-exist.feedpak")],
+    )
+
+    server_mod._seed_builtin_starter_content(dlc)
+
+    assert not (dlc / server_mod._BUILTIN_STARTER_SUBDIR / "missing.feedpak").exists()
+    assert not (server_mod.CONFIG_DIR / server_mod._STARTER_SEED_MARKER).exists()
+
+
+def test_every_starter_source_file_is_present(server_mod):
+    """Every entry in _BUILTIN_STARTER_SOURCES must have its bundled file on
+    disk — otherwise the all-present gate never fires and NOTHING seeds (a
+    listed-but-missing pack silently disables starter seeding entirely). In CI
+    the checkout is clean, so "on disk" == committed."""
+    root = server_mod._feedBack_server_root()
+    missing = [
+        rel for _, rel in server_mod._BUILTIN_STARTER_SOURCES
+        if not (root / rel).is_file()
+    ]
+    assert not missing, f"listed starter sources missing on disk: {missing}"
+
+
+def test_seed_lands_every_listed_starter_pack(tmp_path, server_mod):
+    """A real seed run copies every listed pack into starter/ and marks done."""
+    root = server_mod._feedBack_server_root()
+    for _, rel in server_mod._BUILTIN_STARTER_SOURCES:
+        if not (root / rel).is_file():
+            pytest.skip(f"starter source not present in checkout: {rel}")
+
+    dlc = tmp_path / "dlc"
+    dlc.mkdir()
+    server_mod._seed_builtin_starter_content(dlc)
+
+    for dest_name, _ in server_mod._BUILTIN_STARTER_SOURCES:
+        dest = dlc / server_mod._BUILTIN_STARTER_SUBDIR / dest_name
+        assert dest.is_file(), f"pack not seeded: {dest_name}"
+    assert (server_mod.CONFIG_DIR / server_mod._STARTER_SEED_MARKER).is_file()
+
+
+def test_no_unlisted_starter_pack_on_disk(server_mod):
+    """The inverse guard: every content/starter/*.feedpak on disk must be wired
+    into _BUILTIN_STARTER_SOURCES. An unlisted pack bundles into builds as dead
+    weight and never seeds — exactly how the raw Ode-to-Joy pack slipped onto
+    main before being wired up. In CI the checkout is clean, so this flags any
+    stray/committed pack that isn't listed."""
+    root = server_mod._feedBack_server_root()
+    listed = {rel for _, rel in server_mod._BUILTIN_STARTER_SOURCES}
+    if not listed:
+        pytest.skip("no starter sources declared")
+    content_dir = (root / next(iter(listed))).parent  # all sources share this dir
+    if not content_dir.is_dir():
+        pytest.skip(f"starter content dir absent: {content_dir}")
+    on_disk = {p.relative_to(root).as_posix() for p in content_dir.glob("*.feedpak")}
+    unlisted = on_disk - listed
+    assert not unlisted, (
+        "committed but not in _BUILTIN_STARTER_SOURCES (would bundle as dead "
+        f"weight and never seed): {sorted(unlisted)}"
+    )

tests/test_collections_api.py

@@ -21,6 +21,7 @@ def server_mod(tmp_path, monkeypatch):
     yield mod
     conn = getattr(getattr(mod, "meta_db", None), "conn", None)
     if conn is not None:
+        getattr(__import__("sys").modules.get("server"), "_join_background_db_threads", lambda: None)()
         conn.close()
 
 

tests/test_context_menu_api.py

@@ -24,6 +24,7 @@ def server(tmp_path, monkeypatch, isolate_logging):
     finally:
         conn = getattr(getattr(srv, "meta_db", None), "conn", None)
         if conn is not None:
+            getattr(__import__("sys").modules.get("server"), "_join_background_db_threads", lambda: None)()
             conn.close()
         sys.modules.pop("server", None)
 

tests/test_correlation_id.py

@@ -36,6 +36,7 @@ def client(tmp_path, monkeypatch):
         finally:
             conn = getattr(getattr(server, "meta_db", None), "conn", None)
             if conn is not None:
+                getattr(__import__("sys").modules.get("server"), "_join_background_db_threads", lambda: None)()
                 conn.close()
 
 
@@ -169,6 +170,7 @@ def test_server_app_request_id_propagated_to_logs(monkeypatch, tmp_path):
         ]
         conn = getattr(getattr(server_mod, "meta_db", None), "conn", None)
         if conn is not None:
+            getattr(__import__("sys").modules.get("server"), "_join_background_db_threads", lambda: None)()
             conn.close()
 
     lines = [ln for ln in buf.getvalue().splitlines() if "server_probe_event" in ln]

tests/test_curated_album.py

@@ -20,6 +20,7 @@ def server(tmp_path, monkeypatch, isolate_logging):
     finally:
         conn = getattr(getattr(srv, "meta_db", None), "conn", None)
         if conn is not None:
+            getattr(__import__("sys").modules.get("server"), "_join_background_db_threads", lambda: None)()
             conn.close()
         sys.modules.pop("server", None)
 

tests/test_demo_mode.py

@@ -60,6 +60,7 @@ def _cleanup(server, client):
         server._DEMO_JANITOR_HOOKS.clear()
     conn = getattr(getattr(server, "meta_db", None), "conn", None)
     if conn is not None:
+        getattr(__import__("sys").modules.get("server"), "_join_background_db_threads", lambda: None)()
         conn.close()
 
 
@@ -311,6 +312,7 @@ def test_register_demo_janitor_hook_in_plugin_context(tmp_path, monkeypatch):
 
     conn = getattr(getattr(server, "meta_db", None), "conn", None)
     if conn is not None:
+        getattr(__import__("sys").modules.get("server"), "_join_background_db_threads", lambda: None)()
         conn.close()
     # Clean up janitor state so it doesn't bleed into other tests.
     server._DEMO_JANITOR_STOP.set()

tests/test_diagnostics_bundle.py

@@ -204,7 +204,7 @@ def test_client_audio_session_contribution_redacts_paths(tmp_path):
     kw["client_contributions"] = {
         "note_detect": {
             "schema": "feedBack.audio_session.diagnostics.v1",
-            "session": {"sessionId": str(home_path / "DLC" / "private-song.archive")},
+            "session": {"sessionId": str(home_path / "DLC" / "private-song.feedpak")},
             "domains": {"audio-input": {"sources": [{"label": str(home_path / "devices" / "raw-id")}]}},
         }
     }
@@ -1541,7 +1541,7 @@ def test_console_error_object_args_are_redacted(tmp_path):
     kw = _basic_kwargs(tmp_path)
     kw["include"]["console"] = True
     kw["redact"] = True
-    secret_path = "/home/alice/Music/DLC/my_song.archive"
+    secret_path = "/home/alice/Music/DLC/my_song.feedpak"
     kw["client_console"] = [
         {
             "level": "error",
@@ -1567,13 +1567,13 @@ def test_console_string_args_still_redacted(tmp_path):
     kw["include"]["console"] = True
     kw["redact"] = True
     kw["client_console"] = [
-        {"level": "log", "msg": "ok", "args": ["loaded /home/alice/Music/DLC/my_song.archive ok"]},
+        {"level": "log", "msg": "ok", "args": ["loaded /home/alice/Music/DLC/my_song.feedpak ok"]},
     ]
     zip_bytes, _name, _m = db.build_bundle(**kw)
     with _open_zip(zip_bytes) as zf:
         console = json.loads(zf.read("client/console.json"))
     # The song filename should be replaced with a hash token, not appear verbatim.
-    assert "my_song.archive" not in console["entries"][0]["args"][0]
+    assert "my_song.feedpak" not in console["entries"][0]["args"][0]
 
 
 def test_console_non_string_non_dict_args_pass_through(tmp_path):

tests/test_diagnostics_redact.py

@@ -5,7 +5,7 @@ from diagnostics_redact import Redactor
 
 def test_dlc_path_replaced():
     r = Redactor(dlc_dir=Path("/dlc/songs"))
-    out = r.redact_text("loaded from /dlc/songs/foo.archive")
+    out = r.redact_text("loaded from /dlc/songs/foo.feedpak")
     assert "<DLC_DIR>" in out
     assert "/dlc/songs" not in out
     assert r.counts["paths_replaced"] == 1
@@ -13,8 +13,8 @@ def test_dlc_path_replaced():
 
 def test_song_filename_redacted_consistently():
     r = Redactor()
-    a = r.redact_text("Loading Test-Artist_Test-Song.archive")
-    b = r.redact_text("Replaying Test-Artist_Test-Song.archive again")
+    a = r.redact_text("Loading Test-Artist_Test-Song.feedpak")
+    b = r.redact_text("Replaying Test-Artist_Test-Song.feedpak again")
     token_a = a.split("Loading ")[1].strip()
     token_b = b.split("Replaying ")[1].split(" ")[0]
     assert token_a == token_b
@@ -63,8 +63,8 @@ def test_home_dir_replaced():
 def test_different_redactors_produce_different_tokens():
     a = Redactor()
     b = Redactor()
-    out_a = a.redact_text("Foo.archive")
-    out_b = b.redact_text("Foo.archive")
+    out_a = a.redact_text("Foo.feedpak")
+    out_b = b.redact_text("Foo.feedpak")
     assert out_a != out_b
 
 

tests/test_dlc_junction.py

@@ -0,0 +1,92 @@
+"""Unit tests for ``server._resolve_dlc_path`` — the DLC-library containment
+guard.
+
+It must (1) allow a library mounted through a directory JUNCTION/symlink (the
+shared-library-across-installs / desktop-app case that a ``.resolve()``-based
+check wrongly rejected, breaking album art + song load), while (2) still
+rejecting ``..`` traversal and absolute paths — the only escapes a ``:path``
+filename can express. ``safe_join`` stays strict on purpose (zip-slip guard),
+so the contrast is pinned here too.
+"""
+
+import importlib
+import os
+import sys
+
+import pytest
+
+
+@pytest.fixture()
+def server(tmp_path, monkeypatch):
+    (tmp_path / "cfg").mkdir()
+    monkeypatch.setenv("CONFIG_DIR", str(tmp_path / "cfg"))
+    monkeypatch.setenv("FEEDBACK_SKIP_STARTUP_TASKS", "1")
+    sys.modules.pop("server", None)
+    srv = importlib.import_module("server")
+    try:
+        yield srv
+    finally:
+        conn = getattr(getattr(srv, "meta_db", None), "conn", None)
+        if conn is not None:
+            getattr(sys.modules.get("server"), "_join_background_db_threads", lambda: None)()
+            conn.close()
+        sys.modules.pop("server", None)
+
+
+def _dlc(tmp_path):
+    d = tmp_path / "dlc"
+    d.mkdir()
+    return d
+
+
+# ── still-rejected escapes (the security contract) ────────────────────────────
+
+def test_dotdot_traversal_rejected(server, tmp_path):
+    dlc = _dlc(tmp_path)
+    assert server._resolve_dlc_path(dlc, "../../etc/passwd") is None
+    # a Windows-style backslash traversal is normalised + rejected identically
+    assert server._resolve_dlc_path(dlc, "..\\..\\secret") is None
+    assert server._resolve_dlc_path(dlc, "a/../../b") is None
+
+
+def test_absolute_path_rejected(server, tmp_path):
+    dlc = _dlc(tmp_path)
+    assert server._resolve_dlc_path(dlc, "/etc/passwd") is None
+    assert server._resolve_dlc_path(dlc, "C:/Windows/system32/x") is None
+
+
+def test_empty_and_nul_rejected(server, tmp_path):
+    dlc = _dlc(tmp_path)
+    assert server._resolve_dlc_path(dlc, "") is None
+    assert server._resolve_dlc_path(dlc, "a\x00b") is None
+
+
+# ── allowed: legitimate in-library paths ──────────────────────────────────────
+
+def test_safe_relative_allowed(server, tmp_path):
+    dlc = _dlc(tmp_path)
+    p = server._resolve_dlc_path(dlc, "CDLC/City Pop/song.feedpak")
+    assert p is not None
+    assert p.is_relative_to(dlc.resolve())
+
+
+def test_junction_subfolder_allowed(server, tmp_path):
+    """A library mounted through a directory junction/symlink must resolve —
+    the case that broke album art for Christian's shared city-pop library."""
+    dlc = _dlc(tmp_path)
+    real = tmp_path / "real_library"
+    real.mkdir()
+    (real / "song.feedpak").write_bytes(b"pack")
+    link = dlc / "CDLC"
+    try:
+        os.symlink(real, link, target_is_directory=True)
+    except (OSError, NotImplementedError):
+        pytest.skip("symlink/junction creation not permitted on this host")
+
+    p = server._resolve_dlc_path(dlc, "CDLC/song.feedpak")
+    assert p is not None, "a junctioned library subfolder was wrongly rejected"
+    assert p.exists(), "the resolved path should reach the file through the junction"
+    # Contrast: safe_join stays strict (it .resolve()s and follows the junction
+    # to its real target outside the root), which is correct for its zip-slip
+    # callers but is exactly why _resolve_dlc_path can't reuse it here.
+    assert server.safe_join(dlc, "CDLC/song.feedpak") is None

tests/test_enrichment_plumbing.py

@@ -22,6 +22,7 @@ def server(tmp_path, monkeypatch, isolate_logging):
     finally:
         conn = getattr(getattr(srv, "meta_db", None), "conn", None)
         if conn is not None:
+            getattr(__import__("sys").modules.get("server"), "_join_background_db_threads", lambda: None)()
             conn.close()
         sys.modules.pop("server", None)
 
@@ -149,3 +150,152 @@ def test_art_cache_dir_created(server):
     d = server._enrichment_art_dir()
     assert d.is_dir()
     assert d.name == "art_cache"
+
+
+# ── Refresh Metadata batch: per-tile states, progress, Stop ───────────────────
+
+def test_states_for_returns_only_known_filenames(server):
+    _put(server, "a.archive")
+    server._background_enrich()
+    got = server.meta_db.enrichment_states_for(["a.archive", "nope.archive"])
+    assert got == {"a.archive": "unscanned"}          # unknown filename absent
+    assert server.meta_db.enrichment_states_for([]) == {}
+
+
+def test_states_endpoint(client, server):
+    _put(server, "a.archive")
+    _put(server, "b.archive", title="Other")
+    server._background_enrich()
+    body = client.post("/api/enrichment/states",
+                       json={"filenames": ["a.archive", "zzz.missing"]}).json()
+    assert body["states"] == {"a.archive": "unscanned"}
+    assert body["running"] is False
+    assert body["current"] is None
+
+
+def test_status_exposes_progress_fields(client, server):
+    _put(server, "a.archive")
+    server._background_enrich()
+    body = client.get("/api/enrichment/status").json()
+    for k in ("total", "matched", "current", "cancelling"):
+        assert k in body
+    assert body["cancelling"] is False
+
+
+def test_cancel_is_noop_when_idle(client, server):
+    body = client.post("/api/enrichment/cancel").json()
+    assert body == {"ok": True, "was_running": False}
+    # A no-op must not arm the flag (which would then poison the next pass).
+    assert server._enrich_cancel.is_set() is False
+
+
+def test_cancel_flag_halts_matching_loop_between_songs(server, monkeypatch):
+    for i in range(4):
+        _put(server, f"s{i}.archive", title=f"Song {i}")
+    # Force the matcher path on (the test env is offline by default) and stub the
+    # per-song matcher so nothing touches the network — it just trips Stop after
+    # the first song, exactly as the /cancel route would mid-pass.
+    monkeypatch.setattr(server, "_enrich_network_enabled", lambda: True)
+    calls = []
+
+    def fake_enrich_one(row, **_kw):
+        calls.append(row["filename"])
+        server._enrich_cancel.set()
+
+    monkeypatch.setattr(server, "_enrich_one", fake_enrich_one)
+    server._enrich_cancel.clear()
+    server._background_enrich()
+    # The loop checks cancel BEFORE each song, so exactly one is processed before
+    # it breaks — not the whole 4-row queue.
+    assert calls == ["s0.archive"]
+    assert server._enrich_status["total"] == 4
+    assert server._enrich_status["matched"] == 1
+
+
+def test_rematch_requeues_visible_but_skips_manual(server, client):
+    _put(server, "a.archive")                       # will be 'matched'
+    _put(server, "b.archive", title="Other")        # will be 'failed'
+    _put(server, "c.archive", title="Pinned")       # will be 'manual' — untouchable
+    server._background_enrich()
+    with server.meta_db._lock:
+        server.meta_db.conn.execute(
+            "UPDATE song_enrichment SET match_state='matched' WHERE filename='a.archive'")
+        server.meta_db.conn.execute(
+            "UPDATE song_enrichment SET match_state='failed' WHERE filename='b.archive'")
+        server.meta_db.conn.execute(
+            "UPDATE song_enrichment SET match_state='manual' WHERE filename='c.archive'")
+        server.meta_db.conn.commit()
+    body = client.post("/api/enrichment/rematch", json={
+        "filenames": ["a.archive", "b.archive", "c.archive", "nope.archive"]}).json()
+    # A per-view refresh re-runs everything shown EXCEPT the manual pin (and an
+    # unknown filename); matched + failed are both re-queued.
+    assert set(body["queued"]) == {"a.archive", "b.archive"}
+    assert body["count"] == 2
+    server._join_background_db_threads()
+    assert server.meta_db.get_enrichment("a.archive")["match_state"] == "unscanned"
+    assert server.meta_db.get_enrichment("b.archive")["match_state"] == "unscanned"
+    assert server.meta_db.get_enrichment("c.archive")["match_state"] == "manual"
+
+
+# ── filename-derived artist/title fallback (blank-artist packs) ───────────────
+
+def test_filename_artist_title_parse(server):
+    f = server._artist_title_from_filename
+    assert f("CDLC/0 - City Pop/Tatsuro-Yamashita_Ride-On-Time_v1_p.feedpak") == \
+        {"artist": "Tatsuro Yamashita", "title": "Ride On Time"}
+    assert f("Anri_Windy-Summer_v1_p.feedpak") == {"artist": "Anri", "title": "Windy Summer"}
+    # a trailing "(440Hz)" retune tag is stripped before parsing
+    assert f("Cindy_Watashitachi-o-Shinjite-Ite_v1_p (440Hz).feedpak") == \
+        {"artist": "Cindy", "title": "Watashitachi o Shinjite Ite"}
+    # doesn't fit the convention → no guess
+    assert f("nounderscore.feedpak") is None
+
+
+def test_blank_artist_seeds_match_from_filename(server, monkeypatch):
+    server.meta_db.put("Tatsuro-Yamashita_Ride-On-Time_v1_p.feedpak", 0, 0, {
+        "title": "Tatsuro-Yamashita_Ride-On-Time_v1_p", "artist": "", "album": "",
+        "duration": 240, "arrangements": [{"name": "Bass", "index": 0}]})
+    monkeypatch.setattr(server, "_enrich_network_enabled", lambda: True)
+    monkeypatch.setattr(server, "_manifest_exact_ids", lambda fn: {})
+    seen = {}
+
+    def fake_search(artist, title, limit=8):
+        seen["artist"], seen["title"] = artist, title
+        return []
+
+    monkeypatch.setattr(server, "_mb_search_recordings", fake_search)
+    row = next(r for r in server.meta_db.enrichment_pending()
+               if r["filename"].startswith("Tatsuro"))
+    server._enrich_one(row)
+    # the blank pack artist was replaced by the filename-derived identity for
+    # the search (this is exactly what rescues the 'failed' pile)
+    assert seen == {"artist": "Tatsuro Yamashita", "title": "Ride On Time"}
+
+
+def test_present_artist_is_not_overridden_by_filename(server, monkeypatch):
+    server.meta_db.put("Weird-Filename_x_y.feedpak", 0, 0, {
+        "title": "Real Title", "artist": "Real Artist", "album": "", "duration": 100,
+        "arrangements": [{"name": "Lead", "index": 0}]})
+    monkeypatch.setattr(server, "_enrich_network_enabled", lambda: True)
+    monkeypatch.setattr(server, "_manifest_exact_ids", lambda fn: {})
+    seen = {}
+
+    def fake_search(artist, title, limit=8):
+        seen["artist"], seen["title"] = artist, title
+        return []
+
+    monkeypatch.setattr(server, "_mb_search_recordings", fake_search)
+    row = next(r for r in server.meta_db.enrichment_pending()
+               if r["filename"].startswith("Weird"))
+    server._enrich_one(row)
+    # a pack that DOES carry an artist keeps it — the filename is never consulted
+    assert seen == {"artist": "Real Artist", "title": "Real Title"}
+
+
+def test_kick_clears_a_stale_cancel(server):
+    # A cancelled-then-rekicked pass must start clean: _kick_enrich clears the
+    # flag so the fresh pass isn't aborted the instant it checks.
+    server._enrich_cancel.set()
+    server._kick_enrich()
+    server._join_background_db_threads()
+    assert server._enrich_cancel.is_set() is False

tests/test_feedpak_extension.py

@@ -100,6 +100,7 @@ def scan_server(tmp_path, monkeypatch, isolate_logging):
     yield mod
     conn = getattr(getattr(mod, "meta_db", None), "conn", None)
     if conn is not None:
+        getattr(__import__("sys").modules.get("server"), "_join_background_db_threads", lambda: None)()
         conn.close()
 
 
@@ -161,6 +162,7 @@ def upload_client(tmp_path, monkeypatch):
         tc.close()
         conn = getattr(getattr(server, "meta_db", None), "conn", None)
         if conn is not None:
+            getattr(__import__("sys").modules.get("server"), "_join_background_db_threads", lambda: None)()
             conn.close()
 
 
@@ -228,6 +230,7 @@ def settings_server(tmp_path, monkeypatch):
     finally:
         conn = getattr(getattr(server, "meta_db", None), "conn", None)
         if conn is not None:
+            getattr(__import__("sys").modules.get("server"), "_join_background_db_threads", lambda: None)()
             conn.close()
 
 

tests/test_field_overrides.py

@@ -0,0 +1,274 @@
+"""Tests for the per-field metadata override + lock store (Fix-metadata popup).
+
+A reversible DISPLAY overlay, never written to the pack: filename-keyed, so it
+survives a rescan (never purged by delete_missing) and is dropped only with the
+song (delete_song). Locks pin a field against a later auto-match.
+"""
+
+import importlib
+import sys
+
+import pytest
+from fastapi.testclient import TestClient
+
+
+@pytest.fixture()
+def server(tmp_path, monkeypatch, isolate_logging):
+    monkeypatch.setenv("CONFIG_DIR", str(tmp_path))
+    monkeypatch.setenv("FEEDBACK_SKIP_STARTUP_TASKS", "1")
+    sys.modules.pop("server", None)
+    srv = importlib.import_module("server")
+    try:
+        yield srv
+    finally:
+        conn = getattr(getattr(srv, "meta_db", None), "conn", None)
+        if conn is not None:
+            getattr(sys.modules.get("server"), "_join_background_db_threads", lambda: None)()
+            conn.close()
+        sys.modules.pop("server", None)
+
+
+@pytest.fixture()
+def client(server):
+    return TestClient(server.app)
+
+
+def _put(server, fn, **meta):
+    base = {"title": "Song", "artist": "Artist", "album": "", "duration": 100,
+            "arrangements": [{"name": "Lead", "index": 0}]}
+    base.update(meta)
+    server.meta_db.put(fn, 0, 0, base)
+
+
+# ── store semantics ───────────────────────────────────────────────────────────
+
+def test_set_get_and_partial_upsert(server):
+    db = server.meta_db
+    assert db.get_song_overrides("a.archive") == {}
+    db.set_song_override("a.archive", "artist", value="AC/DC")
+    assert db.get_song_overrides("a.archive") == {"artist": {"value": "AC/DC", "locked": False}}
+    # partial: lock without touching the value
+    db.set_song_override("a.archive", "artist", locked=True)
+    assert db.get_song_overrides("a.archive")["artist"] == {"value": "AC/DC", "locked": True}
+    # partial: change the value, keep the lock
+    db.set_song_override("a.archive", "artist", value="AC/DC (fixed)")
+    assert db.get_song_overrides("a.archive")["artist"] == {"value": "AC/DC (fixed)", "locked": True}
+
+
+def test_lock_only_row_persists_without_a_value(server):
+    db = server.meta_db
+    db.set_song_override("a.archive", "year", locked=True)
+    # a pure lock (no override value) is a valid, kept row
+    assert db.get_song_overrides("a.archive") == {"year": {"value": None, "locked": True}}
+
+
+def test_empty_and_unlocked_drops_the_row(server):
+    db = server.meta_db
+    db.set_song_override("a.archive", "album", value="X", locked=True)
+    db.set_song_override("a.archive", "album", value="", locked=False)
+    assert db.get_song_overrides("a.archive") == {}          # no empty shell
+
+
+def test_clear_one_field_leaves_others(server):
+    db = server.meta_db
+    db.set_song_override("a.archive", "title", value="T")
+    db.set_song_override("a.archive", "artist", value="A")
+    db.clear_song_override("a.archive", "title")
+    assert set(db.get_song_overrides("a.archive")) == {"artist"}
+
+
+# ── lifecycle: rescan survival vs explicit delete ─────────────────────────────
+
+def test_rescan_never_purges_overrides_delete_does(server):
+    _put(server, "a.archive")
+    server.meta_db.set_song_override("a.archive", "artist", value="AC/DC", locked=True)
+    server.meta_db.delete_missing(set())                     # file vanished from a scan
+    assert server.meta_db.get_song_overrides("a.archive")["artist"]["value"] == "AC/DC"
+    server.meta_db.purge_song_user_data("a.archive")         # the delete_song purge
+    assert server.meta_db.get_song_overrides("a.archive") == {}
+
+
+def test_overrides_map_batches(server):
+    db = server.meta_db
+    db.set_song_override("a.archive", "artist", value="A")
+    db.set_song_override("b.archive", "title", value="B", locked=True)
+    m = db.overrides_map(["a.archive", "b.archive", "missing.archive"])
+    assert m["a.archive"]["artist"]["value"] == "A"
+    assert m["b.archive"]["title"] == {"value": "B", "locked": True}
+    assert "missing.archive" not in m
+    assert db.overrides_map([]) == {}
+
+
+# ── API ───────────────────────────────────────────────────────────────────────
+
+def test_api_put_get_and_clear(client, server):
+    _put(server, "a.archive")
+    r = client.put("/api/song/a.archive/overrides",
+                   json={"overrides": {"artist": {"value": "AC/DC", "locked": True},
+                                       "year": {"value": "1979"}}})
+    assert r.status_code == 200
+    ov = r.json()["overrides"]
+    assert ov["artist"] == {"value": "AC/DC", "locked": True}
+    assert ov["year"] == {"value": "1979", "locked": False}
+    assert client.get("/api/song/a.archive/overrides").json()["overrides"]["artist"]["value"] == "AC/DC"
+    # clear via PUT (value null + unlocked) — DELETE is shadowed by /api/song/{path}
+    client.put("/api/song/a.archive/overrides",
+               json={"overrides": {"artist": {"value": None, "locked": False}}})
+    assert "artist" not in client.get("/api/song/a.archive/overrides").json()["overrides"]
+
+
+def test_api_get_returns_pack_values(client, server):
+    _put(server, "a.archive", title="Pack Title", artist="Pack Artist",
+         album="Pack Album", year="1988")
+    server.meta_db.set_song_override("a.archive", "title", value="Fixed Title")
+    body = client.get("/api/song/a.archive/overrides").json()
+    # the override rides "overrides"; the pack baseline rides "pack" (all 5 fields)
+    assert body["overrides"]["title"]["value"] == "Fixed Title"
+    assert body["pack"] == {"title": "Pack Title", "artist": "Pack Artist",
+                            "album": "Pack Album", "year": "1988", "genre": ""}
+    # a song with no row still gets an all-empty pack (popup always has values)
+    assert client.get("/api/song/ghost.archive/overrides").json()["pack"]["title"] == ""
+
+
+def test_api_rejects_unknown_field(client, server):
+    _put(server, "a.archive")
+    r = client.put("/api/song/a.archive/overrides",
+                   json={"overrides": {"tuning": {"value": "Drop D"}}})
+    assert r.status_code == 400
+    assert "unknown field" in r.json()["error"]
+
+
+# ── lock enforcement (slice 2) ────────────────────────────────────────────────
+
+def test_locked_fields_reader(server):
+    db = server.meta_db
+    db.set_song_override("a.archive", "artist", value="X", locked=True)
+    db.set_song_override("a.archive", "title", value="Y")            # override, not locked
+    db.set_song_override("a.archive", "year", locked=True)           # lock only
+    assert db.locked_fields("a.archive") == {"artist", "year"}
+
+
+def test_compose_lock_filter_strips_locked_cand_keys(server):
+    f = server._compose_lock_filter(None, {"artist", "year"})
+    cand = {"recording_id": "r", "artist": "X", "artist_sort": "X", "title": "T",
+            "year": "1990", "album": "A", "genres": ["rock"]}
+    out = f(cand)
+    # locked display keys stripped (artist maps to artist + artist_sort)…
+    assert not ({"artist", "artist_sort", "year"} & set(out))
+    # …identity + unlocked display fields survive
+    assert out["recording_id"] == "r" and out["title"] == "T" and out["album"] == "A"
+    # no locks → base filter returned unchanged (zero-copy common path)
+    assert server._compose_lock_filter(None, set()) is None
+
+
+# ── display overlay in the grid (slice 3) ─────────────────────────────────────
+# "Grid shows only overrides": the effective cell is the user's override else the
+# pack value. Display-only + keyset-safe — the seek stays on the raw column.
+
+def _grid(server, **kw):
+    songs, _ = server.meta_db.query_page(**kw)
+    return {s["filename"]: s for s in songs}
+
+
+def test_grid_shows_override_value_over_pack(server):
+    _put(server, "a.archive", title="Wrong Title", artist="Wrong",
+         album="Pack Album", year="1999")
+    server.meta_db.set_song_override("a.archive", "title", value="Right Title")
+    server.meta_db.set_song_override("a.archive", "artist", value="Right Artist")
+    server.meta_db.set_song_override("a.archive", "year", value="1979")
+    s = _grid(server)["a.archive"]
+    assert s["title"] == "Right Title"
+    assert s["artist"] == "Right Artist"
+    assert s["year"] == "1979"
+    assert s["album"] == "Pack Album"            # no override → pack value shows
+    assert s["_sort_title"] == "Wrong Title"     # raw title stashed for the cursor
+
+
+def test_grid_ignores_lock_only_override(server):
+    _put(server, "a.archive", title="Pack Title")
+    server.meta_db.set_song_override("a.archive", "title", locked=True)   # lock, no value
+    s = _grid(server)["a.archive"]
+    assert s["title"] == "Pack Title"            # a lock without a value never retitles
+    assert "_sort_title" not in s                # …and stashes nothing
+
+
+def test_override_beats_alias_relabel_for_artist(server):
+    _put(server, "a.archive", artist="ACDC")
+    server.meta_db.set_artist_alias("ACDC", "AC/DC")                 # P4 alias
+    assert _grid(server)["a.archive"]["artist"] == "AC/DC"          # alias applies alone
+    server.meta_db.set_song_override("a.archive", "artist", value="AC-DC (mine)")
+    assert _grid(server)["a.archive"]["artist"] == "AC-DC (mine)"   # override wins over alias
+
+
+def test_route_strips_private_sort_title(client, server):
+    _put(server, "a.archive", title="Pack")
+    server.meta_db.set_song_override("a.archive", "title", value="Shown")
+    row = next(s for s in client.get("/api/library?sort=title").json()["songs"]
+               if s["filename"] == "a.archive")
+    assert row["title"] == "Shown"
+    assert "_sort_title" not in row              # private keyset stash never leaks to the client
+
+
+def test_genre_override_drives_facet_and_filter(client, server):
+    # a.archive: pack genre "Rock"; b.archive: blank genre, overridden to "City Pop".
+    _put(server, "a.archive", title="A", genre="Rock")
+    _put(server, "b.archive", title="B", genre="")
+    server.meta_db.set_song_override("b.archive", "genre", value="City Pop")
+    # Facet lists the EFFECTIVE genres (override surfaces; empty raw doesn't).
+    genres = client.get("/api/library/genres").json()["genres"]
+    assert "City Pop" in genres and "Rock" in genres
+    # Filtering by the override genre returns the overridden song…
+    fns = [s["filename"] for s in client.get("/api/library?genre=City%20Pop").json()["songs"]]
+    assert fns == ["b.archive"]
+    # …and its raw (blank) genre no longer matches a stale query for it.
+    rock = [s["filename"] for s in client.get("/api/library?genre=Rock").json()["songs"]]
+    assert rock == ["a.archive"]
+
+
+def test_lock_only_genre_does_not_change_facet(server):
+    # A pure lock (no value) must not invent an effective genre.
+    _put(server, "a.archive", title="A", genre="Metal")
+    server.meta_db.set_song_override("a.archive", "genre", locked=True)
+    assert server.meta_db._has_genre_overrides() is False   # value-less rows don't count
+    assert server.meta_db._effective_genre_expr() == "genre"
+
+
+def test_romaji_fallback_for_blank_artist_pack(server):
+    fn = "CDLC/0 - City Pop/Junko-Yagami_BAY-CITY_v1_p.feedpak"
+    _put(server, fn, title="Junko-Yagami_BAY-CITY_v1_p", artist="")   # scanner fell back to the filename
+    s = {x["filename"]: x for x in server.meta_db.query_page()[0]}[fn]
+    # the grid shows the author's romaji, not blank / the raw filename / kanji
+    assert s["artist"] == "Junko Yagami"
+    assert s["title"] == "BAY CITY"
+    # the Details baseline (pack_fields) matches, so the popup agrees with the grid
+    pack = server.meta_db.pack_fields(fn)
+    assert pack["artist"] == "Junko Yagami" and pack["title"] == "BAY CITY"
+
+
+def test_romaji_fallback_left_alone_when_pack_has_artist(server):
+    _put(server, "a.archive", title="Real Title", artist="Real Artist")
+    s = {x["filename"]: x for x in server.meta_db.query_page()[0]}["a.archive"]
+    assert s["artist"] == "Real Artist" and s["title"] == "Real Title"
+
+
+def test_title_keyset_paging_is_complete_with_overrides(client, server):
+    # Raw titles A/B/C → title-sort order is A, B, C on the RAW column.
+    _put(server, "b.archive", title="B")
+    _put(server, "a.archive", title="A")
+    _put(server, "c.archive", title="C")
+    # Overrides that would reshuffle the order IF the cursor wrongly used the
+    # displayed value — the seek must stay on the raw title, so paging still
+    # covers every row exactly once (no skip/dupe).
+    server.meta_db.set_song_override("a.archive", "title", value="ZZZ")
+    server.meta_db.set_song_override("c.archive", "title", value="AAA")
+    seen, cursor = [], None
+    for _ in range(10):
+        url = "/api/library?sort=title&size=1" + (f"&after={cursor}" if cursor else "")
+        data = client.get(url).json()
+        if not data["songs"]:
+            break
+        seen.append(data["songs"][0]["filename"])
+        cursor = data["next_cursor"]
+        if not cursor:
+            break
+    assert sorted(seen) == ["a.archive", "b.archive", "c.archive"]   # each exactly once