fix(pack overwrite): reject revert-original on non-package targets (mirror write-path guard)

The POST /api/song/{fn}/revert-original handler restored a .bak over its
target after only checking that a backup existed — unlike the write path
(gap-fill/overwrite), which refuses non-sloppak targets via is_sloppak. A
non-package path under DLC_DIR with a sibling .bak (or a plain directory
carrying manifest.yaml.bak) could therefore be mutated by a feature meant
only for song packages.

Add the same is_sloppak guard after path resolution and before any restore
or DB resync, returning the 404 the art/source endpoints use for a
non-package target. Existing behaviors (404 when no backup, .bak preserved
after a successful revert, demo-block, path-traversal safety) are intact.

Regression test: a non-package file under the DLC dir with a sibling .bak is
refused (404) and left byte-for-byte unchanged.

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

.github/workflows/ci.yml

@@ -52,7 +52,7 @@ jobs:
         run: pytest
 
       - name: Run JS plugin-API tests
-        run: node --test tests/js/*.test.js 'tests/plugins/*/js/*.test.js'
+        run: node --test tests/js/*.test.js 'tests/plugins/*/js/*.test.js' 'plugins/*/tests/*.test.js'
 
   tailwind-fresh:
     # Guard that the committed static/tailwind.min.css is in sync with source.

.gitignore

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

CHANGELOG.md

@@ -7,7 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### 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
+- **Edit Metadata now writes into `.feedpak` files, not just legacy `.sloppak` ones.** `lib/songmeta.py`'s suffix gate predated the format rename — core reads both suffixes everywhere else (`sloppak.SONG_EXTS`), but the metadata writer only dispatched on `.sloppak`, so editing a zip-form `.feedpak`'s title/artist/album/year silently fell back to a DB-only update. That looked fine until the next **full library rescan** re-derived metadata from the file and reverted the edit (directory-form packages were unaffected — they dispatch on manifest presence, not suffix). The gate now accepts both package suffixes. Tests: `tests/test_songmeta.py` `TestWriteSongMetadata` (both zip suffixes, mixed-case suffix, directory form, unknown-suffix fallback).
+- **3D Drum & Keys highways now re-frame on fullscreen/layout drift under splitscreen.** The guitar/bass `highway_3d` self-detects when its panel canvas changes size and re-runs `applySize()` every frame, because the splitscreen host overrides `hw.resize` and never calls `renderer.resize()`. The drum and keys highways lacked that fallback — they only re-framed when the host explicitly called `resize(w, h)` — so their panels stayed framed for the pre-fullscreen size while the guitar/bass panels adapted (visible as a too-small, off-center highway after maximizing a split-screen session). Both draw loops now port `highway_3d`'s per-frame drift check: they re-apply on backing-store change (`canvas.width/height`) AND on CSS-box drift (`clientWidth/clientHeight` vs the last applied logical size, throttled to every 10th frame), and reset the tracking in `destroy()` so a reused instance re-frames on the next song. `plugins/drum_highway_3d` → 0.3.1, `plugins/keys_highway_3d` → 0.1.1. Tests: `tests/js/drum_keys_highway_3d_resize_reframe.test.js`.
+- **Tuner: finished the "remove unused settings" cleanup and fixed the sidebar panel position.** The Floating Button and Tuning Visibility settings sections were removed, but their config was still live: `disabledTunings` still filtered the tuner menu (with no UI left to re-enable a hidden tuning — a one-way trap) and `showFloatingButton` still gated the floating launcher. Both are now fully retired — the enforcement paths in `plugins/tuner/screen.js`/`utils/ui.js` and the persistence in `plugins/tuner/routes.py` are gone (and `routes.py` strips the retired keys on write, so stale values are purged). The tuner panel opened from the v3 sidebar Plugins rail popover now anchors beside it via the host's stable plugin-control slot API (falling back to the popover id), is **clamped to the viewport** so it can't open off the right/bottom edge on narrow/short windows, and re-anchors on window resize. `plugins/tuner` → 1.3.3.
+
 ### Added
+- **Host theme read surface — `window.feedBack.theme` + always-present `--fbv-*` tokens — so a plugin feature can render correctly under any theme instead of binding to whichever one the developer happened to see.** The cosmetics applier (`static/v3/theme-core.js`) previously only *applied* themes and emitted `--fbv-*` vars **only while a theme was equipped** (nothing for a plugin to read in the default, un-themed state) with no read/capability API — so plugins reinvented their own theming and a new visual *device* (a glow, a gradient) silently bound to one look. It now: (1) emits the default `fb` palette as **always-present `--fbv-*` on `:root`** (additive — the un-themed look is unchanged; the `fb-*` utilities still use their compiled defaults; this only hands plugins a stable host token to read + derive surfaces from), plus two keystone ROLES the palette lacked — **`on-accent`** (a foreground legible *on* the accent fill — the missing piece behind white-on-accent contrast bugs) and **`focus-ring`**; (2) adds **`window.feedBack.theme`** — `get()` → `{id, isThemed, tokens}`, **`capabilities()`** → `{glow, gradients, motion}` (the device-affordance signal a feature reads to choose a glow vs. a solid device; recolor-only themes report defaults, a theme may opt out via a `capabilities` block in its payload, and `motion` is additionally reduced-motion-gated), and **`prefersReducedMotion()`** (one central matchMedia wrapper); and (3) emits a normalized **`theme:changed`** event (`{id, isThemed, tokens, capabilities}`) from the single `apply()` chokepoint. All additive + feature-detected (the apply side stays on `window.v3Theme`; the read surface is attached defensively so it survives the `feedBack` bus being (re)built by `capabilities.js` regardless of load order). First slice of the host theme contract (got-feedback/feedBack#644) — the framework fix so a plugin UI feature can't accidentally carve itself into a single theme; see `docs/host-theme-contract.md`. Verified by a headless render (apply/unequip intact, defaults present + restored, capability opt-out honored, event payload correct). Tests: `tests/js/v3_theme_read_api.test.js`.
+- **3D Keys Highway: audio-reactive background ambience + score effects (parity slice 4 — completes the keys side of the visual-parity epic).** The gradient sky behind the highway gains the guitar's **background ambience styles** — drifting **Particles**, pitch-class-colored pulsing **Stage lights**, wireframe **Geometric** shapes, or Off — driven by the shared audio-analyser bridge (stems-first on sloppaks, one-shot `#audio` fallback; bass/mid/treble bands, 5 ms cache) with an **Ambience intensity** slider and an **Audio-reactive** toggle. And the score talks back: a **score-FX overlay** canvas draws rising **“+1” pops** off each scored key, an **expanding ring every 10-combo tier**, **milestone bursts** at 25/50/100 streak, and a brief **red flicker** when a 3+ streak breaks (wrong notes and swept misses both count). All settings-gated and on by default (`keys3d_bg_*`), pooled, cleared when idle, torn down with the scene. Butterchurn/image/video remain out of scope. The `#audio` analyser tap is also **shared across visualizers** now (`window.__feedBackAudioTap` — whoever taps first publishes, everyone else adopts, `highway_3d` included), so switching between or splitting the guitar/drum/keys highways can't strand a permanently non-reactive backdrop, and the tap is never created before the page has user activation (a suspended AudioContext would silence live playback). Tests: bg-style id validation + FX defaults (30 total).
+- **3D Keys Highway: the anti-plastic pass — lacquered note gems, glossy piano-black keys, a studio environment, scene themes and a gradient sky (parity slice 3).** The note gems move to `MeshPhysicalMaterial` with a full **clearcoat** (roughness 0.32, clearcoat 1.0/0.18, envMapIntensity 0.9): a sharp lacquer highlight over the colored body instead of the old dead matte surface — glass, not plastic. What sells it is **image-based lighting**: the same procedural PMREM "studio" environment as the drum highway (dark room + cool overhead / warm+cool side light strips, no addon dependency) feeds `scene.environment`, so the **black keys finally read as glossy piano black** (roughness 0.55 → 0.22, envMapIntensity 1.3) with visible strip reflections, whites keep an ivory sheen (0.42/0.55), and the highway floor gets a stage sheen (roughness 0.9 → 0.55, metalness 0.15). The flat background becomes a **vertical gradient** (lighter above the horizon → theme color → darker toward the keyboard), and the guitar highway's **11 scene themes** arrive (same names/values — your look carries across instruments; `default` preserves the original keys palette; pitch-class note/key colors are never themed — themes own the scene, Synthesia colors own the notes). Plus **Cinematic lighting** (ambient 0.55/key 1.3, on by default) and a **Glow strength** slider multiplying the note glow, key approach-glow and the sustain consume-flash (0.5 = stock). All live-applying from the Graphics settings (`keys3d_bg_theme` + `keys3d_bg_*`); the PMREM target and gradient texture are disposed with the scene. Tests: theme-table id parity + default-look preservation + fallbacks (28 total).
+- **3D Drum Highway: audio-reactive background ambience + score effects (parity slice 4 — completes the drum side of the visual-parity epic).** The empty fog band behind the kit gains the guitar highway's **background ambience styles**: drifting **Particles**, palette-colored pulsing **Stage lights**, and slowly-tumbling wireframe **Geometric** shapes (plus Off) — driven by the same audio-analyser bridge the guitar uses (prefers the stems plugin's per-song analyser on sloppaks, falls back to a one-shot `#audio` tap; bass/mid/treble bands with a 5 ms cache), with an **Ambience intensity** slider and an **Audio-reactive** toggle (off = the styles animate on time only; a permanently-tapped `#audio` in a mixed split degrades the same way). The guitar's butterchurn/image/video styles are deliberately out of scope (vendored megabytes / upload plumbing; the style enum is extensible). And your combo finally talks back: a **score-FX overlay** (2D canvas over the WebGL scene, guitar `drawScoreFx` adapted to this plugin's internal scoring) draws rising **“+1” pops** off each scored lane, an **expanding ring pulse every 10-combo tier**, **milestone particle bursts** at 25/50/100 streak, and a brief **red flicker** when a 3+ streak breaks. Everything is settings-gated (Background ambience dropdown + intensity + reactive, Score effects toggle — all on by default, live-applying, `drum_h3d_bg_*` keys), pooled (zero per-frame allocation), and torn down with the scene across kit changes. Tests: bg-style id validation + FX defaults (15 total).
+- **3D Drum Highway: real materials + scene themes (parity slice 3).** The scene gets **image-based lighting**: a procedural PMREM "studio" environment (dark room + three emissive light strips — cool overhead key, warm/cool side fills; no vendored-addon dependency) feeds `scene.environment`, so the cymbals' metalness **finally reads as metal** (retuned to roughness 0.2 / metalness 0.85 / envMapIntensity 1.2 — the old 0.7-metalness look was matte because there was nothing to reflect), drumheads get a satin sheen, and the floor (roughness 0.95 → 0.7) catches the strips without turning into a mirror. **Scene themes arrive** — the same 11 theme names as the guitar highway (Midnight, Charcoal, Deep Purple, Forest, Warm Slate, Deep Focus, Deep Sea, Cathode, Cathode Green, Hearth) retint the background/fog, floor and lane stripes so your look carries across instruments; `default` preserves the original drum palette byte-for-byte, and piece colours stay with the existing Palette picker (themes own the scene, palettes own the kit). Plus **Cinematic lighting** (dimmer ambient / stronger key, on by default), a **Glow strength** slider (0–1, 0.5 = stock) multiplying every emissive base — notes, hit line, snare wires — and a **Lane vibrancy** slider driving stripe/halo/ghost-ring strength (the hit-FX approach highlight stacks on top). Everything applies live from the plugin settings (`drum_h3d_bg_theme` + `drum_h3d_bg_*` keys); the PMREM render target is rebuilt across kit-change renderer recreation and disposed in both teardown paths — and the floor/hit-bar geometry+materials that previously leaked on every kit change are now tracked and disposed too. Tests: theme-table parity with the guitar ids + default-look preservation + fallbacks (13 total).
+- **3D Drum Highway: hit FX — sparks, timing-colored lane flashes, kick camera pulse, approach glow, and open hi-hat notation (parity slice 2).** Striking a pad now *feels* struck: a pooled additive **spark burst** fires at the lane (ported from the guitar highway's Points-cloud system, pool 160), colored by **timing** — on-time green, early cyan, late amber (same `_timingHex` vocabulary as `highway_3d`, classified against the ±50 ms hit window with the inner 40% reading as on-time); with **Streak feedback** on, bursts grow with your combo. The **lane flash** feedback that was removed when note-recoloring landed is resurrected properly: pooled additive quads with a soft gaussian falloff light up the struck lane at the hit line (timing-colored; red for wrong-pad hits), and a **kick** hit fires triple amber bursts across the bar plus a subtle **camera dip + amber floor wash** that decays exponentially. Lanes also glow ahead of time: each stripe brightens as its next note approaches the hit line, so the eye is led to where the next hit lands. **Open hi-hat finally renders distinctly** — `hh_open` chart hits get a thin warm ring around the cymbal gem (standard notation's "o"), closing the long-standing TODO; the flag is orthogonal to accents/ghosts/flams so combined cues stack. All of it is settings-gated (Graphics → Hit sparks / Timing colours / Streak feedback / a 0–1 **Hit feedback intensity** slider driving flashes, approach glow and the kick pulse; everything on by default, `drum_h3d_bg_*` keys, live-applying) and GPU-frugal: every new visual is pooled or shares geometry/materials — zero per-note allocation on top of the per-frame notes rebuild, all registered in both dispose paths (kit-change renderer recreation included). Tests: timing-classifier boundaries + FX defaults added to `plugins/drum_highway_3d/tests/data_layer.test.js` (10 total).
+- **3D Keys Highway: hit FX — vibrant note gems, timing-colored sparks, and a hit-line that reacts to your playing (parity slice 2).** The washed-out note look is gone: gem opacity is now driven by a **Note vibrancy** slider (default 0.85 → opacity 0.92, up from a fixed 0.8; lane guides scale with it too, live-applying without a chart rebuild) and the resting emissive glow rises 0.08 → 0.22, so the falling notes finally read saturated against the dark floor. Scored key presses fire a pooled additive **spark burst** at the struck key (guitar-highway port, pool 96) **colored by timing** — on-time green, early cyan, late amber, classified against the ±100 ms window with the inner 40% reading as on-time (the timing delta is recovered from the matched note's key, so `judgeHit`'s tested contract is untouched); the per-pitch-class flame sprite keeps its identity color so pitch and timing stay separate signals. With **Streak feedback** on, bursts grow with the combo. The **hit line kicks brighter** for a beat on every scored press (exponential decay, scaled by a 0–1 **Hit feedback intensity** slider). All new controls live in the plugin's Graphics settings (on by default, `keys3d_bg_*` keys, live-applying), and the spark pool is disposed with the scene like every other GPU resource. Tests: timing-classifier boundaries, the noteKey time round-trip that the delta recovery relies on, and the new FX defaults (26 total).
+- **3D Drum Highway: bloom glow + adaptive-resolution support — the first slice of visual parity with the guitar highway.** The drum highway now renders through the same post-processing path as `highway_3d`: an `UnrealBloomPass` (strength 0.65, radius 0.5, threshold 0.82 — high, so only emissive/bright surfaces bleed) on a multisampled HalfFloat target with ACES filmic tone mapping, so the white hit-line bar and proximity-lit notes get a real glow instead of a flat emissive tint. **On by default**, with a new **Graphics → "Glow (bloom)"** toggle in the plugin settings (`drum_h3d_bg_bloom`, applies live, no reload); if the vendored postprocessing addons can't load (older self-hosted core), the plugin silently falls back to the direct render path. The plugin also now honors the host's **adaptive render scale** (`bundle.renderScale` — the Quality/"Min res" controls that the guitar highway already respected), multiplying it into the device pixel ratio, and caps DPR at 1.25 when more than one viz instance is live (splitscreen) so two panels don't double the GPU fill cost. Groundwork for the rest of the parity series: an FX-settings scaffold (`FX_DEFAULTS`/`readFxSettings`/`window.drumH3dSetFx`, `drum_h3d_bg_*` localStorage keys) that the sparks/themes/backgrounds PRs extend, plus a first node test suite for the plugin (`plugins/drum_highway_3d/tests/data_layer.test.js` — vm-loaded like the keys plugin's, covering the hit-variant precedence, the Auto-mode steal-guard predicate, and FX defaults; 8 tests, runs in CI via the `plugins/*/tests/*.test.js` glob).
+- **3D Keys Highway: sharp HiDPI rendering, bloom glow, a live combo HUD, and a graphics settings panel — the first slice of visual parity with the guitar highway.** The biggest single fix is resolution: the plugin never called `setPixelRatio`, so on HiDPI/retina displays (and Windows display scaling) it rendered at CSS resolution and was upscaled — soft and aliased. It now multiplies the device pixel ratio (capped at 2, or 1.25 when two viz panels are live in splitscreen) with the host's **adaptive render scale** (`bundle.renderScale`, the Quality/"Min res" controls), exactly like `highway_3d`. On top of that: the same **bloom** post-processing path as the guitar highway (UnrealBloomPass 0.65/0.5/0.82 on a multisampled HalfFloat target + ACES tone mapping — the cyan hit-line, hit flames and the sustain "consume" glow finally bleed light instead of reading flat), **on by default** with a graceful direct-render fallback when the vendored addons can't load. The plugin gains its first **settings panel** (`settings.html`, Settings → graphics category, `"settings"` block in plugin.json) with a live-applying "Glow (bloom)" toggle (`keys3d_bg_bloom`), plus the FX scaffold (`FX_DEFAULTS`/`readFxSettings`/`window.keys3dSetFx`, `keys3d_bg_*` keys) the later parity PRs extend. And the score state the plugin was already tracking is finally visible: a **combo / accuracy / best-streak HUD** overlay (drum-highway pattern), shown only while a MIDI keyboard session is wired so it never renders a frozen 0× combo. Tests: `plugins/keys_highway_3d/tests/fx_settings.test.js` (defaults, localStorage overrides + type coercion, setter persist/dispatch/unknown-key guard; 3 tests alongside the existing 20).
+- **The 3D Drum Highway and 3D Keys Highway are now bundled core plugins** (`plugins/drum_highway_3d/`, `plugins/keys_highway_3d/`), imported from their former standalone repos (`feedBack-plugin-drum-highway-3d`, `feedBack-plugin-keys-highway-3d`, now archived) via `git subtree` so their history is preserved. They join the other in-tree plugins-as-plugins: the loader treats them identically to user-installed ones, both are marked `"bundled": true` in their manifests, and `.gitignore` gains the matching `!plugins/<id>/` exceptions. This puts all three 3D highways (guitar, drums, keys) in one repo ahead of a visual-parity pass that ports the guitar highway's polish (bloom, sparks, themes, reactive backgrounds) to the other two — shared helper code and theme tables can now be reviewed and kept in sync in a single place. The keys plugin's existing node test suite is wired into CI (the JS test step gains a `plugins/*/tests/*.test.js` glob, +20 tests), and `static/tailwind.min.css` is regenerated since the core Tailwind build scans `plugins/**`. One deliberate behavior change ships with the bundling: the drum highway's Auto-mode predicate is **narrowed** (it used to claim any pack with `has_drum_tab` — a pack-level flag — which, now that the plugin ships to everyone and sorts before `highway_3d` in first-match-wins Auto order, would have stolen full-band packs from the guitar highway even on Lead/Bass arrangements; it now claims only drum arrangements, or packs nothing more specific can render). Picking the drum highway manually from the viz picker is unchanged.
+- **The tuner now tracks what tuning your instrument is *actually* in, so it prompts you to retune in BOTH directions — down to a song's tuning, and back up when the next song needs it.** The coverage check used to compare each song against your fixed instrument-profile tuning, so it only ever prompted you *away* from "home" (e.g. E → Drop C#) and stayed silent coming back (Drop C# → E), even though you'd physically retuned. It now reads the host's live **per-instrument working tuning** (`window.feedBack.workingTuning`) — what your selected instrument is currently in — so coverage is measured against your *actual* tuning and fires both ways. When you clear an auto-opened tuner, the tuner publishes that song's tuning as your instrument's live working tuning (`assumed` — an explicit "I tuned / Skip" refines it in a later PR), so the next song is judged against where you now are. **Per-instrument** — your guitar's and bass's tunings are tracked separately (keyed like the selector), so switching instruments uses the right one. Feature-detected: on a host without the working-tuning capability it falls back to the static `/api/settings` tuning (today's behavior). `plugins/tuner/screen.js` (`_playerTuning` reads `workingTuning` keyed by the selected instrument; `_publishWorkingTuning` writes on clear). Builds on the host `workingTuning` foundation (PR 1 of the series) + the instrument→chart routing (PR 2). Tests: `tests/js/tuner_auto_open.test.js` (both-directions coverage via a live Drop-D working tuning; publish-on-clear targets the right instrument slot) — 29 pass.
+- **`.jsonc` support for feedpak data files** (feedpak-spec §8, FEP #3 / PR #13). Hand-edited packs may now use the `.jsonc` extension (JSON with C-style `//` line and `/* */` block comments) for any data file the manifest points at — arrangements, notation sidecars, `drum_tab`, `song_timeline`, `lyrics`, and `keys`. New shared `lib/jsonc.py` provides `parse_jsonc(text)` + `load_json(path)` (auto-detects `.jsonc` by suffix, string-aware so comment-like text inside JSON string values is preserved) and is now used by every reader in `lib/sloppak.py` (six side-file sites) and `scripts/lift_keys_notation.py` (three arrangement / song_timeline read sites). The strip regex mirrors the reference validator in `feedpak-spec/tools/validate.py`. This is an additive (MINOR) change: `.jsonc` is opt-in, so any pack that keeps its data files as `.json` is unaffected and needs no regeneration. Note that a `.jsonc` file containing real comments only loads on a reader that implements §8 — a pre-this-change reader calls bare `json.loads` and fails on the comments rather than ignoring them, so don't hand out `.jsonc` packs to older hosts. Tests: `tests/test_sloppak_jsonc_load.py` (covers all six side-file types, the lift helper, and the string-boundary preservation rule end-to-end).
+- **The highway now loads the part that matches your selected instrument — a bass player gets the Bass arrangement, not the default Lead/guitar chart.** When you open a song without an explicit arrangement, the WebSocket handler (`server.py` `highway_ws`) reads your selected `instrument` from `config.json` (the same file it already reads for your default-arrangement preference) and routes to the matching part: **bass → the Bass arrangement**; guitar — and any unknown/future instrument (drums, keys) — falls through to the existing preference/most-notes default, which already lands on a guitar part. Previously the instrument selector only fed the tuner, so a bass player was handed a guitar chart (and a tune/coverage check then compared a 4-string bass against a 6-string part). An **explicit arrangement request always wins** (a manual arrangement switch is untouched), and a bass player's saved default-arrangement preference is still honored **within** the bass parts (so a preferred `Bass 2` / `Alt. Bass` wins over the canonical Bass), so this only changes the *default* part chosen on load. Server-only — every launch path already flows through the WS, so there's no client change. This is the instrument↔chart-routing piece the working-tuning series leans on (otherwise coverage compares across instruments). Tests: `tests/test_highway_ws_instrument_routing.py` (bass→Bass, bass-honors-pref, bass-no-bass-part→guitar, guitar→default, explicit-wins).
+- **Host "working tuning" — a live, app-wide record of what tuning your instrument is *actually* in right now (foundation; no behavior change yet).** Introduces `window.feedBack.workingTuning`, a host-owned, session-lived state distinct from any one song's tuning and from a soft opt-in default: the offsets + string-count + reference pitch the player's instrument is currently in, plus an `assumed`/`verified` provenance flag. It's **per-instrument** — your guitar's current tuning and your bass's are kept *separately* (keyed like the instrument selector, e.g. `guitar-6` / `bass-4`), so switching instruments surfaces that instrument's own remembered tuning and you only ever deal with the one you've selected. It exists so a retune — or an instrument swap mid-session — is reflected **everywhere** (the highway, the library/song-picker, and plugins like the tuner, Virtuoso, and the minigames) instead of being re-derived per surface or wrongly assumed from a fixed profile. Modeled on the shipped `tuning` capability + the `feedBack.theme` read-API: a **synchronous `get(instrument?)`** (returns the selected instrument's state, defaulting to the seed until known), a `set(state, {provenance, instrument})` mutator (the tuner becomes the sole writer in the next change), `setCurrentInstrument()` for the selector, `resetToDefault()`, and a `working-tuning-changed` event that fires on every change **and once on hydration** (carrying which instrument changed) so a late-mounting consumer is never stuck on stale state. State is **in-memory, seeded from `/api/settings` on boot and reset on restart** — a stale "you're in drop-A" assumption is worse than re-asking. Registered as a separate `working-tuning` **exclusive-owner** capability (tuner = writer, the rest = requesters). This is the foundation (plumbing only — nothing writes to it yet) of the working-tuning series, which fixes the tuner gate only ever prompting *away from* a fixed "home" tuning (never back) and makes the current tuning a first-class signal the whole app shares. Offsets use the same per-string semitone vocabulary as song tunings, so fully custom/extended tunings (e.g. a drop-A 8-string) are first-class. Frontend-only: new `static/capabilities/working-tuning.js`, loaded from `static/index.html` + `static/v3/index.html`.
 - **The v3 Songs grid is now DOM-virtualized — card-node count stays bounded no matter how big the library is or how far you scroll.** The grid used to append every scrolled page and never let go, so a 2000-song library grew the DOM from 24 → 624 → 2001 card nodes as you scrolled (layout/memory cost scaling with depth). It now renders only the **visible window** of cards (± a small overscan); a sizer element sized to the whole library (`ceil(total/cols) × rowH`) gives the scrollbar its full geometry while the grid is absolutely positioned to the first visible row. `state.songs` is a sparse, absolutely-indexed store fetched a page at a time on demand — using the stage-1 **keyset cursor** for contiguous forward scroll (O(page)) and falling back to `OFFSET page=` for jumps/restore/non-keyset providers (collections, remote). Verified bounded (~60 nodes for a 2001-song library while the count still reads "2001 songs"). The **A–Z rail now seeks directly**: `sort_letters` gives a letter's first-row index (cumulative of prior buckets), converted to a scrollTop in O(1) — no more paging through every intervening row (a bounded forward scan covers the rare legacy provider without `sort_letters`). Select-mode selections, accuracy badges, the ⋮ card menu, plugin card actions, scroll-restore (now scrollTop-based, since geometry is stable), and the tree/folder views all survive cards leaving and re-entering the DOM. Plugins that decorate cards get a stable `window.v3Songs.visibleCards()` accessor + a `v3:library-window-rendered` event instead of assuming every card is present (the highway-stutter lesson). Stage 2 of the virtualized-grid project (got-feedback/feedBack#636 item 3), building on the stage-1 keyset data layer below. Frontend-only: `static/v3/songs.js`, `static/v3/v3.css`. Tests: `tests/browser/v3-grid-virtualization.spec.ts` (bounded-DOM invariant across a 2001-song scroll + direct rail jump), updated `tests/js/v3_az_rail.test.js` + `tests/js/v3_songs_scroll.test.js`.
 - **Keyset (cursor) pagination for the library grid — the data layer for an upcoming virtualized grid, and a latent paging bug fixed along the way.** Every library sort now carries a unique `filename` tiebreak, making the order **total** — which fixes a latent bug where rows sharing a sort key (e.g. two songs by the same artist) could be skipped or duplicated across `OFFSET` pages. `GET /api/library` gains an opaque `after` cursor + a `next_cursor` in the response: passing the cursor back fetches the next page with a **WHERE-seek** instead of `OFFSET`, so deep paging is O(page) regardless of depth. The seek is NULL-aware and exactly `OFFSET`-equivalent (verified across artist/title/recent, ascending + descending, including the legacy `dir=desc` shape and NULL sort keys); unknown/compound sorts and bad cursors fall back to `OFFSET`, and only the local provider is handed a cursor (collections/remote page by `OFFSET`). New composite `(artist NOCASE, filename)` / `(title NOCASE, filename)` / `(mtime, filename)` indexes cover the order. This is stage 1 of the virtualized-grid project (got-feedback/feedBack#636 item 3); the DOM-recycling render window builds on it next. Tests: `tests/test_library_keyset.py` (keyset==OFFSET parity, stable tiebreak, dir=desc, NULL keys, cursor fallback).
 - **Smart collections — save a set of library filters as a live, auto-updating source.** A collection is a saved `/api/library` query (e.g. "Drop-D tunings", "sloppak only", "recently added") that stays live: it's registered as a **library provider**, so it shows up in the v3 Songs source picker and inherits the whole grid UI — paging, stats, the A–Z rail, art — for free, with **no new screen**. Storage reuses the playlist subsystem (a `playlists.rules` JSON blob = a smart collection; membership is the live filter result, not stored songs, and collections are excluded from the manual-playlist list + read-only to playlist mutations). New `GET`/`POST`/`PUT`/`DELETE /api/collections`; a per-collection `SmartCollectionProvider` delegates `query_page`/`query_stats`/`query_artists` to the local DB with the stored rules applied; providers are re-registered from a boot scan so collections survive a restart. Rules mirror the raw `/api/library` query params (unknown keys dropped, never 500). Frontend: a "＋ Save as collection" action in the v3 filter drawer (shown when filters are active) names the current filter set and switches to it. The charrette's "the homelab primitive FeedBack was missing" pick (got-feedback/feedBack#636 item 2); richer rule fields (accuracy, genre, difficulty) follow as the metadata work lands. Tests: `tests/test_collections_api.py`, `tests/js/v3_collections.test.js`.
@@ -47,6 +69,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **v3 library: exact artist/album filters + scroll/page-depth restore** (feedBack#857). The v3 Songs toolbar gains Artist and Album dropdowns (Album populates from the selected artist and stays disabled until one is chosen), backed by new exact, case-insensitive (`COLLATE NOCASE`) `artist` / `album` query params threaded through `MetadataDB._build_where` → `query_page` / `query_artists` / `query_stats` and the `/api/library`, `/api/library/artists`, `/api/library/stats` endpoints (the free-text `q` search stays fuzzy and composes with the exact filters). The artist/album catalog is fetched independently of the active artist/album selection so the dropdowns always list the full set for the current provider/search. The toolbar is now sticky so filter controls stay reachable when browsing deep libraries, and returning from the player restores the previous scroll position **and** the loaded infinite-scroll page depth via a `sessionStorage` snapshot keyed by a filter/sort/view state hash (invalidated whenever those change, so a filter change still resets to the top). Tests: `tests/test_library_filters.py` (backend artist/album filters), `tests/js/v3_songs_scroll.test.js` (state-hash + snapshot helpers).
 
 ### Fixed
+- **GP8 multi-staff (piano/keys) tracks now import both hands — the bass stave was being silently dropped, and hand-splits landed on the wrong hand.** A GP8 grand-staff keyboard part is one `<Track>` with two `<Staff>` entries, and `MasterBar/Bars` lists one bar id per **stave**, not per track (`lib/gp2rs_gpx.py`). Two bugs fell out of assuming one stave per track: (1) the bar-column lookup used a raw `enumerate(Tracks)` index, so every track *after* a multi-stave track read the wrong column; (2) the string-tuning parse scanned all `.//Property` descendants and let the last stave's `<Tuning>` overwrite the first, so a treble note indexed against the 5-entry bass tuning fell out of range in `_note_midi` and was **dropped without a trace**. The importer now advances a bar-column counter by each track's stave count, reads tuning **per stave** (with a per-staff fall-back to the track-level property so an untuned staff never yields empty pitches), and folds **every** extra stave's notes into the arrangement (not just stave 1), keeping the `note_count` import-preview honest. A grand-staff track is now classified as keys end-to-end so the stave-0 and folded stave-1+ notes share one encoding. Separately, `notation_lift.split_hands` no longer forces a hard middle-C split when doing so produces a physically unplayable hand (e.g. a bass note under an Em7-shape voicing dipping below C4 would put a 19-semitone span in one hand) — it uses the middle-C boundary only when both resulting hands are within `HAND_SPLIT_SPAN_SEMITONES`, else falls back to the largest-gap heuristic. The GPX LH/RH pair merge and the GP8 stave fold now share one `_collect_column_notes` / `_merge_lh_notes` pair so the two formats can't drift in tie/timing/dedup handling. Companion editor change: got-feedback/feedBack-plugin-editor#38. Tests: `tests/test_gp2notation.py` (grand-staff fold + bar-column offset), `tests/test_notation_lift.py` (both middle-C split cases). Follow-up: `lib/gp_autosync.py` still carries the pre-fix bar-column + tuning logic (CLI/tests only, no production caller).
+- **Tuner auto-open is now opt-in and persists instead of flashing open-then-shut.** When you entered a song (or switched arrangement) whose tuning differed from the last, the tuner auto-opened and — for some testers — vanished ~1s later (reported macOS+Windows, 0.3.0). Root cause: the tuner closes itself on `song:play` (`plugins/tuner/utils/ui.js` — you don't tune while playing), so a **song switch** fired autoplay → `song:play` → the just-auto-opened tuner closed; an **arrangement switch** (which never arms autoplay) had no `song:play`, so it stayed open — exactly why two testers saw opposite behaviour (it wasn't the mic). Now: (1) the feature is a **new opt-in setting** ("Auto-open on tuning change", in the tuner's Settings panel, persisted as `autoOpenOnTuningChange`, **default OFF**); (2) an **auto**-opened tuner *persists* — it ignores the autoplay `song:play`, stray outside-clicks, and same-screen re-emits, closing only via the new in-panel **`×`** / **"Skip"** buttons or when you leave the song. A *manually* opened tuner keeps its classic click-away / play-to-close behaviour. The panel previously had no in-box close at all; this adds one (`×` + contextual Skip). All in the tuner plugin (`routes.py` config, `screen.js` gate + persist, `utils/ui.js` buttons + `song:play` guard, `settings.html` toggle) — **no core `app.js` changes**. Tests: `tests/js/tuner_auto_open.test.js` (opt-in gate, `{ auto: true }` persist mode, play/click-proofing). **Default (opt-in vs opt-out) is teed up for Byron to decide — flip one boolean.**
+- **Tuner auto-open is now tuning-coverage-aware — extended-range players aren't nagged for songs their instrument already covers.** With the opt-in auto-open on, it now prompts only when your **current physical tuning** (from your instrument selection in Settings) doesn't already cover the song. FeedBack is tune-to-song — the highway draws tab in the song's tuning — so the check aligns the song's open-string tuning string-for-string against your instrument: an **8-string F♯-standard** player gets **no** prompt for a 6- or 7-string standard song (its top strings already match those tunings), while a song needing an open string you don't have (e.g. a **Drop-A 7-string**, whose low A isn't an open string on an F♯ 8-string) **still** prompts. A whole-instrument reference difference also prompts — A440 vs A432, or an octave-down `centOffset` (which the auto-open now accounts for; it was previously ignored). The player's instrument is read from core **`/api/settings`** (the v3 instrument selector — a stable physical reference, not the tuner's song-tracking selection); when nothing's declared or the lookup is unavailable it falls back to a conservative prompt, so a real retune is never silently skipped. **v3-only** (the instrument selector is v3). All in the tuner plugin (`plugins/tuner/screen.js`) — **no core changes**. Tests: `tests/js/tuner_auto_open.test.js` (covered vs uncovered, the Drop-A case, reference-pitch mismatch, contiguous alignment). _Follow-up (E1.6): a passive "different tuning" badge cue that names the string(s) to retune, plus the splitscreen / no-usable-input guards._
+- **The tuner badge now passively flags when a song needs a different tuning — and names the retune.** Building on the coverage check: when you enter a song your current instrument doesn't cover, the topbar tuner badge gets an amber ring and a tooltip that **names the change** — e.g. *"retune B→A"* for a Drop-A song on an F♯ 8-string, or *"the reference pitch"* for an A440-vs-A432 mismatch. It's purely **advisory** (it never auto-opens the panel — tap the badge to tune), recomputed on `song:ready` and cleared when a new song loads or you leave the player. The retune diff comes from the tuner plugin's coverage report (`window._tunerAutoOpen.coverageReport` → `{ covered, retune: [{ from, to }], reference, cantCover }`); the cue is CSS-free (an inline ring + native tooltip — no Tailwind rebuild) and no-ops when the tuner plugin isn't installed. **v3-only.** Touches `static/v3/badges.js` (the cue) + `plugins/tuner/screen.js` (the report). Tests: `tests/js/tuner_auto_open.test.js` (the report names the strings; reference mismatch; the badge wiring). _(The splitscreen-suppress and no-usable-input guards move to the playback-gate stage, where they matter for its no-trap rule.)_
+- **Tuner auto-open can now gate playback until you've tuned — the "tune before you play" model — via a new core `holdAutoplay()` hook.** With the opt-in auto-open on, when a song needs a retune the tuner opens and **playback waits** for your choice — **Skip** (you've tuned → play, and record the song's tuning as your instrument's current working tuning), **Back to library** / **Esc** (leave the song; a gated retune is never a one-way trap), or press **Play** (always wins). For an auto-open the in-panel **×** is dropped — Skip / Back to library / Esc are its dismiss surface. Previously the song played with the tuner overlaid; now it holds — which also definitively kills the original flash, since autoplay's `song:play` can't fire while playback is held. Implemented as a small **core hook** `window.feedBack.holdAutoplay()` (mirrors the existing `holdAutoExit()`): a plugin claims it **synchronously on `song:loading`** (so it beats the `song:ready` autostart), and `release()` — or a **12-second fail-open backstop** — runs the deferred start. **Generation-guarded** (a new song invalidates a stale hold) and **fail-open** (a wedged or crashed plugin can never permanently strand a song); **manual Play always wins** (it doesn't flow through the autostart path). The tuner claims the gate only when the feature is on, and **releases it the instant** it decides not to open (song already covered / tuning unchanged) or when you Skip. Touches core `static/app.js` (the hook + an autostart refactor) and the tuner plugin (`plugins/tuner/screen.js` — the claim/release; `plugins/tuner/utils/ui.js` — the Skip / Back-to-library buttons, × dropped on auto-open); the hook is generic and shell-agnostic (a test asserts `app.js` still doesn't reference the tuner's internals). Tests: `tests/js/tuner_auto_open.test.js` (claim on `song:loading`, release on dismiss, feature-off no-claim, the core hook + fail-open backstop, the Skip / Back-to-library / Esc escape-hatch) + a `speed_reset.test.js` stub. ⚠️ **Needs a manual smoke-test before shipping** — this is a core playback change; verify on desktop that the tuner mic doesn't contend with note_detect's scoring input (ASIO/exclusive mode), per the design charrette.
+- **v3 Songs List View: favoriting a song now turns the heart red immediately (no re-search needed).** In the tree / "List View" (Songs → List → expand an artist), clicking the heart flipped the glyph ♡→♥ but it stayed dim grey until you re-searched the library — reported on macOS + Windows, open since 0.3.0 / 2026-06-25. One shared `wireCards()` `[data-fav]` handler (`static/v3/songs.js`) serves both the grid card and the List-View row, but the two render with different idle colours — grid `text-white`, List View `text-fb-textDim` — and the handler only ever removed the grid's `text-white`. So in List View the row kept `text-fb-textDim` alongside the freshly-added `text-fb-accent`, and the dim class won by CSS source order (glyph changed, colour didn't). Each heart now declares its idle colour via a `data-fav-idle` attribute and the handler swaps exactly that class, so only one colour class is ever present; the handler also writes the new state back onto the in-memory song model so a re-render / virtualized-grid recycle agrees instead of reverting. Tests: `tests/js/v3_favorites_toggle.test.js`.
+- **v3 Songs A–Z rail: taps now land reliably, a drag releases exactly on the let-go letter, and the rail is large enough to hit on hi-res displays.** Follow-up to the rail's debut (#634); three bugs reported on macOS + Windows (0.3.0, 2026-06-29): a tap often did nothing ("clicked O, nothing happened"), a drag "got you kind of there but where you release isn't where you get sent," and the rail was "way too small" at 1440p and didn't scale with resolution. Root causes & fixes, all in `static/v3/songs.js` + `static/v3/v3.css` (`bindRailOnce`/`jumpToLetter`/`.v3-azrail`): (1) **taps** — `pointerdown` calls `setPointerCapture`, after which the browser **retargets the follow-up `click` to the rail container**, so the click handler's `closest('.v3-azrail-letter')` resolved `null` and a plain tap (no `pointermove`) had no other path → no-op. The jump is now driven from `pointerdown` itself (seek on press); the `click` handler is reduced to **keyboard activation only** (`e.detail === 0`, Enter/Space). (2) **drag precision** — every letter crossed fired `jumpToLetter` with `behavior:'smooth'`; stacked smooth-scroll animations over the virtualized grid lagged and settled short of the release. `jumpToLetter(letter, smooth)` now scrolls **instantly while scrubbing** (`'auto'`) and only animates discrete taps/keyboard jumps, so the grid tracks the finger and the release lands on the let-go letter. (3) **size** — the letters were a fixed `.62rem` glued at `right:2px` (~13px-tall target on the screen edge); they now scale with the viewport (`clamp(.72rem, 1.4vh, 1.05rem)`), sit off the edge with taller/wider equal-width hit targets and a hover/active highlight so the scrub target is visible. Keyboard arrow-nav + the present-letter gating are unchanged. Reported by =Scr4tch= and MajorMokoto. Tests: `tests/js/v3_az_rail.test.js` (pointerdown-seek, keyboard-only click guard, instant-vs-smooth scroll).
 - **v3 player: opening another rail popover now closes the Section Practice popover (no more two stacked popovers).** Opening the **Practice** pill's popover and then clicking a different player-rail icon (e.g. **Plugins**) left the Practice popover open underneath the new one — looked broken (reported on macOS, 0.3.0 / 2026-06-28). The rail icons call `e.stopPropagation()` in their click handler (`static/v3/player-chrome.js`), which killed bubbling before it reached the Practice popover's outside-click dismiss bound on `document`. The dismiss (`_installSectionPracticeDismiss` in `static/app.js`) now binds in the **capture phase**, which runs before the target's handler so a descendant's `stopPropagation()` can't swallow it — mirroring how the audio-mixer popover already dismisses. Esc handling stays bubble-phase (the player's Escape-to-exit ordering is unchanged). v2 shares `app.js` and is only hardened (no rail `stopPropagation` there). Tests: `tests/js/section_practice_dismiss.test.js`.
 - **v3 UI no longer lets you accidentally text-select the chrome.** Dragging or double-clicking across the interface used to marquee-highlight buttons, labels, the sidebar, the transport, and the note-highway HUD — which looks broken (reported on Mac + Windows). The v3 shell now defaults to `user-select: none` on `html` (`static/v3/v3.css`), then opts *content* back in — so chrome is non-selectable but the text you actually copy still works. Decided by a 4-lens panel (UX / accessibility / dev-ops / plugin-ecosystem); the guardrails are deliberate: **form fields are always re-enabled** (never break the caret / IME — no `* { user-select:none }`, which trips a WebKit input bug); **plugin screens (`.screen[id^="plugin-"]`) stay selectable by default** so a plugin's copyable text (lyrics, chord names, results) — including community plugins that don't know about this — isn't silently locked; and **core read-only content opts back in by container** via a new hand-authored **`.fb-selectable`** class — applied to the whole **Settings** panel (paths, device names, version, diagnostics, About — answering "is settings still copyable?": yes), the **now-playing song metadata** (with `pointer-events` re-enabled so the HUD text is actually reachable), and the focused **modals / dialogs / toasts / scan banner** that carry copyable errors, IDs, paths, and file names. It's cosmetic only (it protects nothing) and never used to lock copy-worthy text — errors, IDs, paths, versions, and metadata stay selectable per WCAG 2.2 (copy-paste as a permitted mechanism). Dense card lists (library grid, dashboard, profile) stay non-selectable by design — making them selectable would reintroduce the marquee-mess across cards. **v3-only** (v2 unchanged); plain CSS, no Tailwind rebuild; no desktop changes (standard OS-framed window). Plugin authors: `.fb-selectable` is documented in `CLAUDE.md` for re-enabling copyable content rendered outside a plugin screen. Tests: `tests/js/v3_user_select_policy.test.js`.
 - **Input-setup wizard no longer collapses an audio device's driver-type variants into one entry.** On Windows the desktop engine enumerates the same interface once per host API (ASIO / Windows Audio / DirectSound), and the wizard's audio picker (`plugins/input_setup/screen.js`) de-duped the source list by display **label** — so the variants (which share a name) collapsed to a single choice, silently keeping whichever sorted first (often *not* the low-latency ASIO one the player wants). The audio-input capability already collapses true duplicates by `logicalSourceKey` (`_visibleInputSources` in `static/capabilities/audio-session.js`), and the variants each have a **distinct** key, so the wizard's extra label-collapse was redundant for real dupes and destructive for these — it also could drop the variant that was actually `selected`. Removed it; the picker now lists every selectable input. Pairs with feedBack-desktop's change to label each source with its driver type (e.g. "Focusrite (ASIO)") so the now-distinct entries are legible.

CLAUDE.md

@@ -231,6 +231,18 @@ window.feedBackViz_my_viz = function () {
             // toneChanges, toneBase, mastery, hasPhraseData, inverted,
             // lefty, renderScale, lyricsVisible, the 2D coordinate
             // helpers project and fretX, and getNoteState (see below).
+            // The bundle OBJECT is reused across frames (mutated in
+            // place — no per-frame allocation): never cache it or
+            // compare its identity between frames; field values are
+            // only valid for the current draw call. Array FIELDS still
+            // swap reference when chart data changes, so field-identity
+            // caches (`myRef !== bundle.chords`) remain valid.
+            // Windowed-iteration helpers (stable fn refs): bundle
+            // .lowerBoundT(arr, time) is a lower-bound binary search on
+            // `.t` (notes/chords); bundle.lowerBoundTime(arr, time) on
+            // `.time` (beats/anchors/sections). Use these to cull to
+            // the visible window instead of full-scanning chart arrays
+            // per frame.
             // `stringCount` is the active arrangement's string count (4
             // for bass, 6 for guitar, 7+ for extended-range GP imports —
             // size string-indexed geometry against this, not a hardcoded

docs/working-tuning-on-device-tests.md

@@ -0,0 +1,53 @@
+# Working-tuning — on-device test checklist
+
+The working-tuning series (PRs 1–9) ships with headless unit tests for every state
+machine (`tests/js/working_tuning*.test.js`, `tests/js/tuner_auto_open.test.js`). The
+items below are the parts that **cannot** be covered headlessly — they need a real mic,
+a real instrument, and (for the ASIO item) a specific audio backend. Run these on a
+build before shipping the feature to users.
+
+Prereq: enable the opt-in in **Tuner → settings → "Auto-open on tuning change"** (it's
+off by default). Have a guitar (and a bass, for the per-instrument checks) on hand.
+
+## 1. Auto-open + gate ("tune before you play")
+- [ ] Load a song whose tuning differs from your instrument's current tuning → the tuner
+      **auto-opens** and playback **waits** (does not start underneath it).
+- [ ] Load a song already covered by your tuning → **no** auto-open, playback starts.
+- [ ] **Skip** ("I've tuned") → playback starts, and the tuner badge stops flagging this
+      song's tuning (a working tuning was recorded).
+- [ ] **Back to library** / **Esc** → leaves the song, records **nothing** (re-enter the
+      same song → it still prompts).
+- [ ] Take **longer than 12 s** to tune with the panel open → playback does **not** start
+      underneath you (the fail-open backstop was settled once the panel opened).
+- [ ] Hit **Play** manually while the panel is open → Play wins; no double-start.
+
+## 2. Both-directions retune prompt
+- [ ] From standard, load a Drop-C# song → prompted **down** (E→C#). Tune down, Skip.
+- [ ] Now load a standard song → prompted **back up** (C#→E). (Pre-series, this direction
+      was silent.)
+- [ ] Switch guitar↔bass in the instrument card → each instrument remembers its **own**
+      working tuning; the card label follows the selection (dim = home, amber = retuned).
+
+## 3. Mic-verify (assumed → verified)
+- [ ] With a selected (non-free) tuning, tap **Verify tuning** and play each string in tune.
+      Each string needs ~8 stable in-tune frames (±6 ¢); the per-string progress advances.
+- [ ] Play a string **out of tune** → it never completes; drifting out mid-streak resets it.
+- [ ] Complete all strings → the instrument card's provenance glyph flips to the **filled**
+      (verified) diamond, and the recorded working tuning carries the tuning you verified
+      (not a stale one).
+- [ ] Load the **next** song → the verified state **decays to assumed** (per-session only).
+- [ ] Verify against a **manually-selected** tuning (tuner opened off a song) → the stamped
+      offsets match that tuning, not the last song's.
+
+## 4. Mic contention with note-detection (the ASIO / exclusive-mode risk)
+This is the item flagged in the design charrette: the tuner's mic capture must not starve
+note_detect's scoring input.
+- [ ] Desktop, **ASIO / WASAPI-exclusive** device: auto-open the tuner mid-song, tune, Skip
+      → scoring resumes cleanly; no dropped input, no device-in-use error, no crash.
+- [ ] Shared/`auto` device: same flow → both the tuner and scoring read the mic without a
+      stall.
+- [ ] Leave the tuner's background badge audio running + start a scored song → note_detect
+      still scores (the badge auto-start doesn't hold the device exclusively).
+
+Log the build hash and OS/audio backend with results; file any failure against the
+working-tuning series.

lib/gp2rs_gpx.py

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

lib/jsonc.py

@@ -0,0 +1,56 @@
+"""JSONC support — JSON with C-style comments.
+
+Per feedpak-spec §8: when a manifest pointer resolves to a ``.jsonc`` file, a
+Reader MUST strip ``//`` line comments and ``/* */`` block comments before
+parsing the JSON content. This module implements that stripping in a single
+shared place so every sloppak/feedpak reader in this repo parses ``.jsonc``
+the same way (string-aware so comment-like text inside JSON strings survives).
+
+The regex mirrors the reference implementation in ``feedpak-spec/tools/validate.py``.
+``load_json(path)`` auto-detects ``.jsonc`` by suffix; plain ``.json`` (and any
+other extension) goes straight through ``json.loads``. Use it as a drop-in
+replacement for ``json.loads(path.read_text(encoding="utf-8"))``.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+# Match JSON string literals (preserved), // line comments, and /* block */
+# comments. A single combined alternation processed by `sub` with a callback
+# that keeps strings and replaces comments with the empty string — so
+# comment-like text inside a string literal is never stripped.
+_JSONC_STRIP_RE = re.compile(
+    r'"(?:[^"\\]|\\.)*"|'   # string literal — keep as-is
+    r'//.*|'                 # // line comment — strip
+    r'/\*[\s\S]*?\*/',       # /* block comment */ — strip
+)
+
+
+def parse_jsonc(text: str) -> object:
+    """Parse a JSONC string, stripping C-style comments before JSON parsing.
+
+    Handles ``//`` line comments and ``/* */`` block comments, respecting
+    string boundaries so that comment-like text inside strings is preserved.
+    Raises ``json.JSONDecodeError`` on malformed JSON (after stripping).
+    """
+    stripped = _JSONC_STRIP_RE.sub(
+        lambda m: m.group(0) if m.group(0).startswith('"') else '',
+        text,
+    )
+    return json.loads(stripped)
+
+
+def load_json(path: Path) -> object:
+    """Read and parse a JSON/JSONC file by path.
+
+    Files ending in ``.jsonc`` are stripped of comments via :func:`parse_jsonc`;
+    all other files are parsed as plain JSON. UTF-8 encoded, matching every
+    other reader in this repo.
+    """
+    raw = path.read_text(encoding="utf-8")
+    if path.name.lower().endswith(".jsonc"):
+        return parse_jsonc(raw)
+    return json.loads(raw)

lib/mb_match.py

@@ -0,0 +1,295 @@
+"""Text-matching engine for MusicBrainz metadata enrichment (P8).
+
+Pure functions only — no network, no database, no server imports — so the
+whole matching pipeline is unit-testable in isolation. server.py owns the
+throttled HTTP transport and the song_enrichment writes; this module owns:
+
+* denoise/tokenize: fold community chart-title noise (author suffixes,
+  ``(440Hz)``/``(Live)``/``(No Lead)``/``(v2)`` parentheticals, punctuation,
+  diacritics, ``AC DC``/``ACDC``/``AC/DC`` spelling drift) into a comparable
+  token form,
+* similarity + scoring: token-set similarity on artist+title with year and
+  duration proximity as corroborating bonuses,
+* tier classification: auto (high) / review (medium) / none (low) — the
+  design rule is that a WRONG match is worse than no match, so the auto
+  tier is deliberately strict and medium confidence goes to a human,
+* MusicBrainz JSON parsing: normalize ``/ws/2`` recording documents into
+  the flat candidate dicts the review UI and song_enrichment store.
+"""
+
+import re
+import unicodedata
+
+# ── Tier thresholds ───────────────────────────────────────────────────────────
+# Combined score = 0.5*artist_sim + 0.5*title_sim + corroboration bonuses
+# (capped at 1.0). Wrong-match is worse than slow (design §5), so `auto`
+# additionally requires BOTH fields to individually agree — a perfect title
+# with a mismatched artist (a cover) must never auto-canonicalize, whatever
+# the combined threshold is set to. AUTO_MIN is only the DEFAULT: the host
+# surfaces it as the user-configurable "auto-apply confidence" setting and
+# passes the chosen value into classify(auto_min=…).
+AUTO_MIN = 0.90
+AUTO_ARTIST_MIN = 0.8
+AUTO_TITLE_MIN = 0.6
+REVIEW_MIN = 0.65
+
+YEAR_BONUS = 0.05        # candidate year within ±1 of the chart's year
+DURATION_BONUS = 0.05    # candidate length within 5s of the chart's audio
+DURATION_BONUS_LOOSE = 0.025   # …within 15s
+_DURATION_TIGHT = 5
+_DURATION_LOOSE = 15
+
+# ── Denoise ───────────────────────────────────────────────────────────────────
+# A parenthetical/bracketed group is dropped when it contains any of these
+# noise terms as a whole word (chart-variant markers, tuning/pitch notes,
+# performance qualifiers) or when it reads as an author credit ("by X",
+# "charted by X"). Both sides of a comparison are denoised symmetrically, so
+# over-stripping a meaningful group costs a little precision but never
+# produces an asymmetric mismatch.
+_NOISE_TERMS = (
+    r"440\s*hz", r"a440", r"432\s*hz",
+    r"live", r"acoustic", r"instrumental",
+    r"no\s+(?:lead|rhythm|bass|vocals?|drums)",
+    r"(?:lead|rhythm|bass)\s+only",
+    r"v\d+", r"ver(?:sion)?\s*\d+",
+    r"remaster(?:ed)?(?:\s*\d{4})?", r"re-?recorded?",
+    r"fix(?:ed)?", r"updated?",
+    r"bonus", r"custom",
+)
+_NOISE_GROUP_RE = re.compile(
+    r"[(\[][^)\]]*\b(?:" + "|".join(_NOISE_TERMS) + r")\b[^)\]]*[)\]]",
+    re.IGNORECASE,
+)
+# Author credits: "(by SomeCharter)", "[charted by X]", "(chart by X)".
+_AUTHOR_GROUP_RE = re.compile(
+    r"[(\[]\s*(?:chart(?:ed)?\s+)?by\s+[^)\]]*[)\]]", re.IGNORECASE)
+# Trailing "- by SomeCharter" outside parens.
+_AUTHOR_TAIL_RE = re.compile(r"\s+-\s+(?:chart(?:ed)?\s+)?by\s+.+$", re.IGNORECASE)
+
+_PUNCT_RE = re.compile(r"[^\w\s]|_")
+_WS_RE = re.compile(r"\s+")
+
+
+def _strip_diacritics(s: str) -> str:
+    return "".join(
+        ch for ch in unicodedata.normalize("NFKD", s)
+        if not unicodedata.combining(ch)
+    )
+
+
+def denoise(s, *, strip_leading_the: bool = False) -> str:
+    """Fold a community metadata string into its comparable form:
+    lowercase, diacritics stripped, noise parentheticals and author credits
+    removed, punctuation collapsed to spaces. ``strip_leading_the`` drops a
+    leading "The " — used for ARTIST comparison only ("The Beatles" ==
+    "Beatles"), never titles ("The Trooper" must keep its "the")."""
+    s = str(s or "")
+    s = _NOISE_GROUP_RE.sub(" ", s)
+    s = _AUTHOR_GROUP_RE.sub(" ", s)
+    s = _AUTHOR_TAIL_RE.sub(" ", s)
+    s = _strip_diacritics(s).casefold()
+    s = s.replace("&", " and ")
+    s = _PUNCT_RE.sub(" ", s)
+    s = _WS_RE.sub(" ", s).strip()
+    if strip_leading_the and s.startswith("the "):
+        s = s[4:]
+    return s
+
+
+def tokens(s, **kw) -> list[str]:
+    d = denoise(s, **kw)
+    return d.split() if d else []
+
+
+def _compact(toks: list[str]) -> str:
+    return "".join(toks)
+
+
+def similarity(a, b, *, artist: bool = False) -> float:
+    """Token-set similarity in [0, 1]. Dice coefficient over the denoised
+    token sets, with a compacted-string equality fold so spelling drift that
+    only moves token boundaries ("ACDC" / "AC DC" / "AC/DC", "Greenday" /
+    "Green Day") counts as identical."""
+    kw = {"strip_leading_the": artist}
+    ta, tb = tokens(a, **kw), tokens(b, **kw)
+    if not ta or not tb:
+        return 0.0
+    if _compact(ta) == _compact(tb):
+        return 1.0
+    sa, sb = set(ta), set(tb)
+    return 2.0 * len(sa & sb) / (len(sa) + len(sb))
+
+
+def _year_int(v):
+    try:
+        y = int(str(v)[:4])
+        return y if y > 0 else None
+    except (TypeError, ValueError):
+        return None
+
+
+def _duration_int(v):
+    try:
+        d = int(round(float(v)))
+        return d if d > 0 else None
+    except (TypeError, ValueError):
+        return None
+
+
+def 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)
+    title_sim = similarity(song.get("title"), cand.get("title"))
+    score = 0.5 * artist_sim + 0.5 * title_sim
+    sy, cy = _year_int(song.get("year")), _year_int(cand.get("year"))
+    if sy and cy and abs(sy - cy) <= 1:
+        score += YEAR_BONUS
+    sd, cd = _duration_int(song.get("duration")), _duration_int(cand.get("duration"))
+    if sd and cd:
+        diff = abs(sd - cd)
+        if diff <= _DURATION_TIGHT:
+            score += DURATION_BONUS
+        elif diff <= _DURATION_LOOSE:
+            score += DURATION_BONUS_LOOSE
+    return min(score, 1.0)
+
+
+def classify(song: dict, cand: dict, score: float, auto_min: float | None = None) -> str:
+    """Tier for a scored candidate: 'auto' | 'review' | 'none'.
+
+    `auto` (tier-2) needs the combined score AND per-field agreement AND
+    both fields present — a perfect-title/wrong-artist cover, or a chart
+    with no artist at all, is at best a review item, never an auto match.
+    `auto_min` overrides the default combined-score threshold (the user's
+    "auto-apply confidence" setting); the per-field floors always apply.
+    """
+    if auto_min is None:
+        auto_min = AUTO_MIN
+    artist_sim = similarity(song.get("artist"), cand.get("artist"), artist=True)
+    title_sim = similarity(song.get("title"), cand.get("title"))
+    if (score >= auto_min and artist_sim >= AUTO_ARTIST_MIN
+            and title_sim >= AUTO_TITLE_MIN):
+        return "auto"
+    if score >= REVIEW_MIN:
+        return "review"
+    return "none"
+
+
+def rank_candidates(song: dict, candidates: list[dict]) -> list[dict]:
+    """Score every candidate against the song and return them sorted 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)."""
+    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)
+    return ranked
+
+
+# ── MusicBrainz query + response parsing ──────────────────────────────────────
+
+def _lucene_escape_phrase(s: str) -> str:
+    """Escape a string for use inside a quoted Lucene phrase."""
+    return s.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def build_recording_query(artist, title) -> 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."""
+    t = denoise(title)
+    a = denoise(artist)
+    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)
+
+
+def _artist_credit(doc: dict) -> tuple[str, str, str]:
+    """(display name, artist mbid, sort name) from an artist-credit array."""
+    credits = doc.get("artist-credit") or []
+    name = ""
+    for part in credits:
+        if isinstance(part, dict):
+            name += str(part.get("name", "")) + str(part.get("joinphrase", "") or "")
+        else:  # ws/2 can emit bare join strings in older serializations
+            name += str(part)
+    first = next((p for p in credits if isinstance(p, dict)), None) or {}
+    artist = first.get("artist") or {}
+    return name, str(artist.get("id", "") or ""), str(artist.get("sort-name", "") or "")
+
+
+def _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."""
+    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
+        date = str(r.get("date", "") or "9999")
+        return (status_ok, album_ok, date)
+
+    return sorted(releases, key=sort_key)[0]
+
+
+def _genres(doc: dict, limit: int = 5) -> list[str]:
+    """Genre names from a recording doc. Search results carry folksonomy
+    `tags`; lookups with inc=genres carry curated `genres`. Both are
+    [{name, count}] — take the most-voted few."""
+    raw = doc.get("genres") or doc.get("tags") or []
+    entries = [e for e in raw if isinstance(e, dict) and e.get("name")]
+    entries.sort(key=lambda e: e.get("count") or 0, reverse=True)
+    return [str(e["name"]) for e in entries[:limit]]
+
+
+def parse_recording_doc(doc: dict) -> dict | None:
+    """Normalize one /ws/2 recording document (search hit or direct lookup)
+    into the flat candidate dict stored in song_enrichment.candidates and
+    rendered by the review drawer. Returns None for malformed docs."""
+    if not isinstance(doc, dict) or not doc.get("id") or not doc.get("title"):
+        return None
+    artist_name, artist_id, artist_sort = _artist_credit(doc)
+    release = _best_release(doc)
+    length = doc.get("length")
+    try:
+        duration = int(round(float(length) / 1000.0)) if length else None
+    except (TypeError, ValueError):
+        duration = None
+    isrcs = doc.get("isrcs") or []
+    isrcs = [str(i) for i in isrcs if isinstance(i, (str,))]
+    return {
+        "recording_id": str(doc["id"]),
+        "title": str(doc.get("title", "")),
+        "artist": artist_name,
+        "artist_id": artist_id,
+        "artist_sort": artist_sort,
+        "release_id": str(release.get("id", "") or ""),
+        "album": str(release.get("title", "") or ""),
+        "year": str(release.get("date", "") or "")[:4],
+        "duration": duration,
+        "isrc": isrcs[0] if isrcs else "",
+        "genres": _genres(doc),
+        "mb_score": int(doc.get("score") or 0),
+    }
+
+
+def parse_search_response(body: dict) -> list[dict]:
+    """Candidates from a /ws/2/recording search response."""
+    docs = (body or {}).get("recordings") or []
+    out = []
+    for doc in docs:
+        cand = parse_recording_doc(doc)
+        if cand:
+            out.append(cand)
+    return out

lib/notation_lift.py

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

lib/scan_worker.py

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

lib/sloppak.py

@@ -13,7 +13,6 @@ See the format spec in the project's sloppak plan for the full layout.
 
 from __future__ import annotations
 
-import json
 import logging
 import math
 import shutil
@@ -37,6 +36,7 @@ SONG_EXTS = (FEEDPAK_EXT, SLOPPAK_EXT)  # accepted on read/discovery
 
 import yaml
 
+from jsonc import load_json
 from safepath import safe_join
 from song import (
     Song,
@@ -423,7 +423,7 @@ def load_song(
             if not arr_path.exists():
                 continue
             try:
-                data = json.loads(arr_path.read_text(encoding="utf-8"))
+                data = load_json(arr_path)
             except Exception as e:
                 log.debug("sloppak: failed to parse arrangement %r: %s", rel, e)
                 continue
@@ -489,7 +489,7 @@ def load_song(
         raw_nt = None
         if nt_path is not None and nt_path.exists():
             try:
-                raw_nt = json.loads(nt_path.read_text(encoding="utf-8"))
+                raw_nt = load_json(nt_path)
             except Exception as e:
                 log.warning("sloppak: failed to parse notation %r: %s", notation_rel, e)
         if raw_nt is not None:
@@ -528,7 +528,7 @@ def load_song(
             dt_path = None
         if dt_path is not None and dt_path.exists():
             try:
-                raw = json.loads(dt_path.read_text(encoding="utf-8"))
+                raw = load_json(dt_path)
             except Exception as e:
                 log.warning("sloppak: failed to parse drum_tab %r: %s", drum_tab_rel, e)
                 raw = None
@@ -588,7 +588,7 @@ def load_song(
             st_path = None
         if st_path is not None and st_path.exists():
             try:
-                raw = json.loads(st_path.read_text(encoding="utf-8"))
+                raw = load_json(st_path)
             except Exception as e:
                 log.warning("sloppak: failed to parse song_timeline %r: %s", song_timeline_rel, e)
                 raw = None
@@ -686,7 +686,7 @@ def load_song(
             lyr_path = None
         if lyr_path is not None and lyr_path.exists():
             try:
-                raw = json.loads(lyr_path.read_text(encoding="utf-8"))
+                raw = load_json(lyr_path)
             except Exception as e:
                 log.debug("sloppak: failed to parse lyrics %r: %s", lyrics_rel, e)
                 raw = None
@@ -773,7 +773,7 @@ def load_song(
             k_path = None
         if k_path is not None and k_path.exists():
             try:
-                raw = json.loads(k_path.read_text(encoding="utf-8"))
+                raw = load_json(k_path)
             except Exception as e:
                 log.warning("sloppak: failed to parse keys %r: %s", keys_rel, e)
                 raw = None
@@ -919,6 +919,12 @@ def extract_meta(path: Path) -> dict:
         "artist": str(manifest.get("artist", "")),
         "album": str(manifest.get("album", "")),
         "year": str(manifest.get("year", "") or ""),
+        # Primary genre from the feedpak `genres` list (spec 1.12.0); [0] = primary.
+        "genre": (lambda g: str(g[0]) if isinstance(g, list) and g else "")(manifest.get("genres")),
+        # Album track order from the feedpak `track`/`disc` fields (spec 1.12.0);
+        # None when unauthored (the album view then falls back to title order).
+        "track_number": (lambda v: int(v) if str(v if v is not None else "").strip().isdigit() else None)(manifest.get("track")),
+        "disc": (lambda v: int(v) if str(v if v is not None else "").strip().isdigit() else None)(manifest.get("disc")),
         "duration": float(manifest.get("duration", 0) or 0),
         "tuning_offsets": tuning_offsets,  # caller maps to a name via tunings.tuning_name
         "arrangements": arrangements,

lib/songmeta.py

@@ -10,9 +10,9 @@ source of truth, so the change survives both incremental and full rescans.
 only the keys present are overwritten, so an edit of just the title can't blank
 out the artist.
 
-Only feedBack's own ``.sloppak`` format (zip- or directory-form) is writable.
-Unknown / unsupported shapes return False and the caller keeps the DB-only
-update.
+Only feedBack's own song-package format (zip- or directory-form, ``.feedpak``
+or the legacy ``.sloppak`` suffix) is writable. Unknown / unsupported shapes
+return False and the caller keeps the DB-only update.
 """
 from __future__ import annotations
 
@@ -49,6 +49,15 @@ def _apply_to_sloppak_manifest(manifest: dict, fields: dict) -> bool:
     if "year" in fields:
         manifest["year"] = _coerce_year(fields["year"])
         dirty = True
+    # `genres` is the feedpak list field (spec 1.12.0). Accepts a list/tuple
+    # (stringified item-wise) or a single name (wrapped); None leaves the
+    # existing value alone, mirroring the string fields above. Sent by the
+    # overwrite lane (R4b) — the manual Edit Metadata path never includes it.
+    if fields.get("genres") is not None:
+        raw = fields["genres"]
+        manifest["genres"] = ([str(g) for g in raw]
+                              if isinstance(raw, (list, tuple)) else [str(raw)])
+        dirty = True
     # Opportunistically declare the format version (spec §4) when we're already
     # rewriting because a metadata field was supplied. Gated on `dirty` (i.e. a
     # field was given) so this never forces a *standalone* rewrite with no fields
@@ -102,24 +111,89 @@ def write_sloppak_metadata(path: Path, fields: dict) -> bool:
         mf = path / "manifest.yaml"
         if not mf.exists() and (path / "manifest.yml").exists():
             mf = path / "manifest.yml"
-        mf.write_text(dumped, encoding="utf-8")
+        # One-time backup + temp + atomic replace, exactly like the zip
+        # rewriter and gap_fill_sloppak's dir branch: the FIRST backup is the
+        # pristine author original and is never clobbered by a later write —
+        # it's what "Revert file to original" (R4b) restores.
+        backup = mf.with_name(mf.name + ".bak")
+        if mf.exists() and not backup.exists():
+            shutil.copy2(mf, backup)
+        tmp = mf.with_name(mf.name + ".tmp")
+        tmp.write_text(dumped, encoding="utf-8")
+        tmp.replace(mf)
         return True
     return _rewrite_zip_manifest(path, dumped)
 
 
+def gap_fill_sloppak(path: Path, additions: dict) -> bool:
+    """Append ABSENT top-level keys to a sloppak manifest (the gap-fill
+    contract: user-initiated, adds missing keys only, never replaces
+    anything the author set).
+
+    Unlike ``write_sloppak_metadata`` this does NOT re-serialize the
+    manifest — because every added key is absent by definition, the new
+    lines can simply be appended, so the author's existing bytes (key
+    order, comments, formatting) survive verbatim. Directory form gets a
+    one-time ``manifest.yaml.bak`` + temp + atomic replace; zip form goes
+    through the same backup/temp/replace rewriter the metadata editor
+    uses. Returns True if anything was written; raises ``ValueError`` if
+    a requested key already exists (callers are expected to have checked
+    — this is the last-line never-clobber guard)."""
+    import sloppak as sloppak_mod
+
+    path = Path(path)
+    if not additions:
+        return False
+    manifest = sloppak_mod.load_manifest(path) or {}
+    clash = sorted(k for k in additions if k in manifest)
+    if clash:
+        raise ValueError("gap-fill refused: key(s) already present: " + ", ".join(clash))
+
+    if path.is_dir():
+        mf = path / "manifest.yaml"
+        if not mf.exists() and (path / "manifest.yml").exists():
+            mf = path / "manifest.yml"
+        original = mf.read_text(encoding="utf-8")
+    else:
+        with zipfile.ZipFile(str(path), "r") as zin:
+            names = zin.namelist()
+            manifest_name = "manifest.yaml"
+            for cand in ("manifest.yaml", "manifest.yml"):
+                if cand in names:
+                    manifest_name = cand
+                    break
+            original = zin.read(manifest_name).decode("utf-8")
+
+    appended = original if original.endswith("\n") or not original else original + "\n"
+    appended += yaml.safe_dump(additions, sort_keys=False, allow_unicode=True)
+
+    if path.is_dir():
+        backup = mf.with_name(mf.name + ".bak")
+        if not backup.exists():
+            shutil.copy2(mf, backup)
+        tmp = mf.with_name(mf.name + ".tmp")
+        tmp.write_text(appended, encoding="utf-8")
+        tmp.replace(mf)
+        return True
+    return _rewrite_zip_manifest(path, appended)
+
+
 def write_song_metadata(path: Path, fields: dict) -> bool:
     """Persist edited title/artist/album/year into the song's file.
 
-    Dispatches by shape: ``.sloppak`` files and sloppak directories
+    Dispatches by shape: zip-form song packages (``.feedpak`` / legacy
+    ``.sloppak``, per ``sloppak.SONG_EXTS``) and package directories
     (manifest.yaml present). Loose-folder and unknown shapes return False
     (caller keeps the DB-only update). Returns True if the file was modified.
     """
+    from sloppak import SONG_EXTS
+
     path = Path(path)
     suffix = path.suffix.lower()
     if path.is_dir():
         if (path / "manifest.yaml").exists() or (path / "manifest.yml").exists():
             return write_sloppak_metadata(path, fields)
         return False
-    if suffix == ".sloppak":
+    if suffix in SONG_EXTS:
         return write_sloppak_metadata(path, fields)
     return False

plugins/drum_highway_3d/.gitignore

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

plugins/drum_highway_3d/LICENSE

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

plugins/drum_highway_3d/README.md

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

plugins/drum_highway_3d/assets/thumb.svg

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

plugins/drum_highway_3d/plugin.json

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

plugins/drum_highway_3d/settings.html

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

plugins/drum_highway_3d/tests/data_layer.test.js

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

plugins/highway_3d/CLAUDE.md

@@ -157,6 +157,8 @@ Every per-frame renderer call receives a `bundle` from feedBack core. Fields use
 
 `tuning` and `capo` aren't consumed by this plugin.
 
+Core reuses the bundle OBJECT across frames (mutated in place); never cache it or compare its identity between frames — field values are only valid for the current draw call. Field-identity caches on ARRAY fields (this plugin's `_mergeCacheChordsRef === bundle.chords` etc.) remain valid: arrays still swap reference when chart data changes. Core also exposes `bundle.lowerBoundT(arr, time)` (lower-bound on `.t`, notes/chords) and `bundle.lowerBoundTime(arr, time)` (on `.time`, beats/anchors/sections) — prefer these over the local `lowerBoundT` helper when a downlevel-host fallback isn't needed.
+
 ### Score FX (notedetect game-scoring layer)
 
 - **"+N" score pops** → `_fxSpawnPop()` from `drawNote()` (just after the provider verdict-override block), drawn by `drawScoreFx()` (called from the `lyricsCtx` block in `draw()`, right after `drawNotedetectLabels()`). Fixed 24-slot pool (`_fxPops`), deduped per `popKey` via the TTL'd `_fxSeen` map (pruned in `drawScoreFx`). Pops rise/fade over 700 ms; font size scales with the multiplier tier.

plugins/highway_3d/plugin.json

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

plugins/keys_highway_3d/LICENSE

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

plugins/keys_highway_3d/README.md

@@ -0,0 +1,54 @@
+# Keys Highway 3D
+
+RS+-style falling-note 3D piano highway for [Slopsmith](https://github.com/got-feedback/feedback), fed by the **Sloppak Notation Format** (sloppak-spec §5.3) — part of the piano/keys first-class epic (slopsmith#828, plugin workstream slopsmith#824).
+
+- Consumes the `notation_info` / `notation_measures` highway-WS stream over a private per-instance socket and flattens measure → staff → voice → beat → note into `{midi, t, durSec, hand}` (durations derived from written `dur`/`dot`/`tu` at the running tempo; ties extend; overlap-clamped).
+- 3D perspective highway to a vanishing point with a real white/black-key keyboard; per-key **pitch-class colours** (Synthesia convention — C red, D yellow, E blue, …) with hand (rh/lh) as a secondary brightness cue.
+- 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.
+- **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).
+- **End-of-run stats**: POSTs `/api/stats` `{filename, arrangement, score, accuracy}` exactly once per run with the same formula as the guitar notedetect path (`accuracy = hits / max(1, hits+misses)`, `score = round(hits·100·accuracy)`), then notifies the progression core when present.
+- **Capability wiring** (all guarded for servers without the hosts): registers as a note-detection `midi` provider (`keys-midi`, `verify.target`), opens a per-song binding scoped to the chart's keys range, reports hit/miss observability events, and exposes Web MIDI inputs to the audio-input domain with pseudonymized labels (`midi-input-1`, …) via `source.enumerate/describe/open/close`.
+- Headless test hook: `window.__keysHwTest = { injectNoteOn(midi, when), getScore() }`.
+
+## Tests
+
+```
+node --test tests/*.test.js
+```
+
+## Ported helpers (keep in sync with highway_3d)
+
+Visual-parity code copied from `plugins/highway_3d/screen.js` — same
+function names, signatures, and constants on purpose, marked with
+`PORTED FROM highway_3d` comments at each site. If the guitar highway
+tunes one of these, mirror the change here (and in `drum_highway_3d`):
+
+- `_bloomEnsure()` / `_bloomDispose()` — EffectComposer + UnrealBloomPass
+  (0.65/0.5/0.82) on a multisampled HalfFloat target, ACES↔None tone-
+  mapping switch in `draw()`; addons dynamic-imported from
+  `/static/vendor/three/addons/` (no CDN fallback — direct render is the
+  graceful degrade)
+- `_sparkBurst()` / `_sparkUpdate()` — pooled additive Points hit sparks
+  (pool 96 here — the flame sprites carry most of the hit feedback)
+- `_timingHex()` / `_classifyTiming()` — early/late/on-time feedback
+  colors (green/cyan/amber) + the 40%-window classifier
+- `_ssActive()` — host splitscreen probe (minus the guitar's focus-API
+  checks, which it needs for input routing and we don't)
+- `BG_THEMES` / `_bgThemeColors()` — the scene theme table (same ids/values
+  as the guitar's, except `default` which is this plugin's original
+  palette); one pick drives background gradient + floor + lane rails
+- `_makeStudioEnv()` — procedural PMREM studio environment (shared with
+  drum_highway_3d; RoomEnvironment isn't vendored)
+- `_applyCinematic()` — ambient/key rebalance (values tuned per plugin)
+- `BG_STYLES` (off/particles/lights/geometric) + `_bgGetAnalyser()` /
+  `_bgReadBands()` — background ambience + the stems-first audio-analyser
+  bridge (shared with drum_highway_3d)
+- `_drawScoreFx()` — score overlay (pops / tier rings / milestone bursts /
+  streak-break wash), drum_highway_3d pattern
+
+## License
+
+AGPL-3.0.

plugins/keys_highway_3d/assets/thumb.svg

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

plugins/keys_highway_3d/plugin.json

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

plugins/keys_highway_3d/settings.html

@@ -0,0 +1,208 @@
+<div role="group" aria-labelledby="keysh3d-heading">
+    <h3 id="keysh3d-heading" class="text-sm font-medium text-gray-400 mb-2">3D Keys Highway</h3>
+    <p class="text-xs text-gray-500 mb-3">
+        Pick a song with keys notation (sloppak-spec §5.3) and choose
+        <em>Keys Highway 3D</em> from the viz picker (Auto selects it for
+        notation charts). The plugin auto-attaches to your MIDI keyboard;
+        device, channel and transpose are configured from the player for
+        now — this panel holds the graphics controls.
+    </p>
+
+    <!-- Graphics -->
+    <div class="mt-3">
+        <h4 class="text-xs font-medium text-gray-300 mb-2">Graphics</h4>
+
+        <label for="keysh3d-fx-theme" class="text-xs font-medium text-gray-400 mb-1 block">Scene theme</label>
+        <select id="keysh3d-fx-theme"
+            onchange="window.keys3dSetTheme && window.keys3dSetTheme(this.value)"
+            class="w-full bg-dark-700 border border-gray-800 rounded-lg px-3 py-2 text-xs text-gray-300 outline-none">
+            <option value="default">Default (original)</option>
+            <option value="midnight">Midnight</option>
+            <option value="charcoal">Charcoal</option>
+            <option value="deeppurple">Deep Purple</option>
+            <option value="forest">Forest</option>
+            <option value="warmslate">Warm Slate</option>
+            <option value="deepfocus">Deep Focus</option>
+            <option value="deepsea">Deep Sea</option>
+            <option value="cathode">Cathode</option>
+            <option value="cathodegreen">Cathode Green</option>
+            <option value="hearth">Hearth</option>
+        </select>
+        <p class="text-xs text-gray-500 mt-1 mb-3">
+            Background gradient, floor and lane rails — the same theme names
+            as the guitar highway. Pitch-class note colours never change.
+        </p>
+
+        <label for="keysh3d-fx-cinematic" class="flex items-center gap-2 text-xs text-gray-300 cursor-pointer">
+            <input type="checkbox" id="keysh3d-fx-cinematic" checked
+                onchange="window.keys3dSetFx && window.keys3dSetFx('cinematic', this.checked)">
+            Cinematic lighting
+        </label>
+        <p class="text-xs text-gray-500 mt-1">
+            Dimmer ambience, stronger key light — deeper shading on the keys
+            and gems.
+        </p>
+
+        <label for="keysh3d-fx-glow" class="text-xs font-medium text-gray-400 mb-1 mt-3 block">
+            Glow strength <span id="keysh3d-fx-glow-val" class="text-gray-500 font-mono">0.50</span>
+        </label>
+        <input type="range" id="keysh3d-fx-glow"
+            min="0" max="1" step="0.05" value="0.5"
+            oninput="window.keys3dSetFx && window.keys3dSetFx('glow', this.value); document.getElementById('keysh3d-fx-glow-val').textContent = parseFloat(this.value).toFixed(2)"
+            class="w-full">
+        <p class="text-xs text-gray-500 mt-1">
+            How hard the notes, key glow and sustain consume-flash
+            self-illuminate (0.5 = stock). Pairs with bloom.
+        </p>
+
+        <label for="keysh3d-fx-bgstyle" class="text-xs font-medium text-gray-400 mb-1 mt-3 block">Background ambience</label>
+        <select id="keysh3d-fx-bgstyle"
+            onchange="window.keys3dSetBgStyle && window.keys3dSetBgStyle(this.value)"
+            class="w-full bg-dark-700 border border-gray-800 rounded-lg px-3 py-2 text-xs text-gray-300 outline-none">
+            <option value="off">Off</option>
+            <option value="particles" selected>Particles</option>
+            <option value="lights">Stage lights</option>
+            <option value="geometric">Geometric</option>
+        </select>
+        <label for="keysh3d-fx-bgintensity" class="text-xs font-medium text-gray-400 mb-1 mt-2 block">
+            Ambience intensity <span id="keysh3d-fx-bgintensity-val" class="text-gray-500 font-mono">0.50</span>
+        </label>
+        <input type="range" id="keysh3d-fx-bgintensity"
+            min="0" max="1" step="0.05" value="0.5"
+            oninput="window.keys3dSetFx && window.keys3dSetFx('bgIntensity', this.value); document.getElementById('keysh3d-fx-bgintensity-val').textContent = parseFloat(this.value).toFixed(2)"
+            class="w-full">
+        <label for="keysh3d-fx-bgreactive" class="flex items-center gap-2 text-xs text-gray-300 cursor-pointer mt-2">
+            <input type="checkbox" id="keysh3d-fx-bgreactive" checked
+                onchange="window.keys3dSetFx && window.keys3dSetFx('bgReactive', this.checked)">
+            Audio-reactive ambience
+        </label>
+        <p class="text-xs text-gray-500 mt-1">
+            The backdrop pulses with the mix (stems analyser when a sloppak
+            is loaded). Off = it animates on time only.
+        </p>
+
+        <label for="keysh3d-fx-scorefx" class="flex items-center gap-2 text-xs text-gray-300 cursor-pointer mt-3">
+            <input type="checkbox" id="keysh3d-fx-scorefx" checked
+                onchange="window.keys3dSetFx && window.keys3dSetFx('scoreFx', this.checked)">
+            Score effects
+        </label>
+        <p class="text-xs text-gray-500 mt-1">
+            +1 pops on scored presses, a ring pulse every 10-combo,
+            milestone bursts at 25/50/100, and a brief red flicker when a
+            streak breaks.
+        </p>
+
+        <label for="keysh3d-fx-bloom" class="flex items-center gap-2 text-xs text-gray-300 cursor-pointer mt-3">
+            <input type="checkbox" id="keysh3d-fx-bloom" checked
+                onchange="window.keys3dSetFx && window.keys3dSetFx('bloom', this.checked)">
+            Glow (bloom)
+        </label>
+        <p class="text-xs text-gray-500 mt-1">
+            Soft light-bleed around the hit line, hit flames and consumed
+            sustains. Applies live; turn off to reclaim GPU headroom on
+            weak machines.
+        </p>
+
+        <label for="keysh3d-fx-sparks" class="flex items-center gap-2 text-xs text-gray-300 cursor-pointer mt-3">
+            <input type="checkbox" id="keysh3d-fx-sparks" checked
+                onchange="window.keys3dSetFx && window.keys3dSetFx('sparks', this.checked)">
+            Hit sparks
+        </label>
+        <p class="text-xs text-gray-500 mt-1">
+            A small particle burst on every scored key press, beside the
+            pitch-colored flame.
+        </p>
+
+        <label for="keysh3d-fx-timing" class="flex items-center gap-2 text-xs text-gray-300 cursor-pointer mt-3">
+            <input type="checkbox" id="keysh3d-fx-timing" checked
+                onchange="window.keys3dSetFx && window.keys3dSetFx('timingFx', this.checked)">
+            Timing colours
+        </label>
+        <p class="text-xs text-gray-500 mt-1">
+            Tint the sparks by timing — on-time green, early cyan, late
+            amber. Off = always green.
+        </p>
+
+        <label for="keysh3d-fx-streak" class="flex items-center gap-2 text-xs text-gray-300 cursor-pointer mt-3">
+            <input type="checkbox" id="keysh3d-fx-streak" checked
+                onchange="window.keys3dSetFx && window.keys3dSetFx('streakFx', this.checked)">
+            Streak feedback
+        </label>
+        <p class="text-xs text-gray-500 mt-1">
+            Spark bursts grow with your combo.
+        </p>
+
+        <label for="keysh3d-fx-hitfx" class="text-xs font-medium text-gray-400 mb-1 mt-3 block">
+            Hit feedback intensity <span id="keysh3d-fx-hitfx-val" class="text-gray-500 font-mono">0.70</span>
+        </label>
+        <input type="range" id="keysh3d-fx-hitfx"
+            min="0" max="1" step="0.05" value="0.7"
+            oninput="window.keys3dSetFx && window.keys3dSetFx('hitFx', this.value); document.getElementById('keysh3d-fx-hitfx-val').textContent = parseFloat(this.value).toFixed(2)"
+            class="w-full">
+        <p class="text-xs text-gray-500 mt-1">
+            Drives the hit-line brightness kick on scored presses. 0 turns
+            it off.
+        </p>
+
+        <label for="keysh3d-fx-vibrancy" class="text-xs font-medium text-gray-400 mb-1 mt-3 block">
+            Note vibrancy <span id="keysh3d-fx-vibrancy-val" class="text-gray-500 font-mono">0.85</span>
+        </label>
+        <input type="range" id="keysh3d-fx-vibrancy"
+            min="0" max="1" step="0.05" value="0.85"
+            oninput="window.keys3dSetFx && window.keys3dSetFx('vibrancy', this.value); document.getElementById('keysh3d-fx-vibrancy-val').textContent = parseFloat(this.value).toFixed(2)"
+            class="w-full">
+        <p class="text-xs text-gray-500 mt-1">
+            Note-gem solidity and lane-guide strength — lower to see more of
+            the keyboard through the notes.
+        </p>
+    </div>
+
+    <script>
+    (function () {
+        'use strict';
+        // Hydrate controls from stored config on first paint. Narrow the
+        // try/catch to just the localStorage reads (drum_highway_3d
+        // settings-hydration convention).
+        try {
+            // FX toggles (keys3d_bg_* — guitar-parity graphics controls).
+            // Only explicit values override; absent/corrupt keys keep the
+            // default (ON), matching screen.js readFxSettings.
+            const hydrateFxBool = (key, elId) => {
+                const raw = localStorage.getItem('keys3d_bg_' + key);
+                if (raw === '1' || raw === 'true') document.getElementById(elId).checked = true;
+                else if (raw === '0' || raw === 'false') document.getElementById(elId).checked = false;
+            };
+            hydrateFxBool('bloom', 'keysh3d-fx-bloom');
+            hydrateFxBool('sparks', 'keysh3d-fx-sparks');
+            hydrateFxBool('timingFx', 'keysh3d-fx-timing');
+            hydrateFxBool('streakFx', 'keysh3d-fx-streak');
+            hydrateFxBool('cinematic', 'keysh3d-fx-cinematic');
+            hydrateFxBool('bgReactive', 'keysh3d-fx-bgreactive');
+            hydrateFxBool('scoreFx', 'keysh3d-fx-scorefx');
+            const hydrateFxRange = (key, elId, valId) => {
+                const n = parseFloat(localStorage.getItem('keys3d_bg_' + key));
+                if (!Number.isFinite(n)) return;
+                const v = Math.min(1, Math.max(0, n));
+                document.getElementById(elId).value = String(v);
+                document.getElementById(valId).textContent = v.toFixed(2);
+            };
+            hydrateFxRange('hitFx', 'keysh3d-fx-hitfx', 'keysh3d-fx-hitfx-val');
+            hydrateFxRange('vibrancy', 'keysh3d-fx-vibrancy', 'keysh3d-fx-vibrancy-val');
+            hydrateFxRange('glow', 'keysh3d-fx-glow', 'keysh3d-fx-glow-val');
+            hydrateFxRange('bgIntensity', 'keysh3d-fx-bgintensity', 'keysh3d-fx-bgintensity-val');
+            const storedStyle = localStorage.getItem('keys3d_bg_style');
+            const styleSel = document.getElementById('keysh3d-fx-bgstyle');
+            if (storedStyle && Array.from(styleSel.options).some(o => o.value === storedStyle)) {
+                styleSel.value = storedStyle;
+            }
+            const storedTheme = localStorage.getItem('keys3d_bg_theme');
+            const themeSel = document.getElementById('keysh3d-fx-theme');
+            if (storedTheme && Array.from(themeSel.options).some(o => o.value === storedTheme)) {
+                themeSel.value = storedTheme;
+            }
+        } catch (e) {
+            console.warn('[Keys-Hwy3D settings] hydration failed:', e);
+        }
+    })();
+    </script>
+</div>

plugins/keys_highway_3d/tests/data_layer.test.js

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

plugins/keys_highway_3d/tests/fx_settings.test.js

@@ -0,0 +1,150 @@
+// FX-settings scaffold tests (guitar-highway parity controls). Same bare-vm
+// harness as data_layer.test.js — no DOM, no localStorage — which doubles as
+// a lint that the new module-scope FX code stays side-effect safe.
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+
+function load(extraWindow) {
+    const window = {
+        console,
+        location: { protocol: 'http:', host: 'localhost' },
+        slopsmith: {},
+        ...extraWindow,
+    };
+    window.window = window;
+    window.globalThis = window;
+    const context = vm.createContext(window);
+    const src = fs.readFileSync(path.join(__dirname, '..', 'screen.js'), 'utf8');
+    vm.runInContext(src, context, { filename: 'screen.js' });
+    return window;
+}
+
+test('readFxSettings: defaults survive a localStorage-less environment', () => {
+    const { readFxSettings, FX_DEFAULTS } = load().slopsmithViz_keys_highway_3d.__test;
+    assert.deepEqual(readFxSettings(), FX_DEFAULTS);
+    assert.equal(FX_DEFAULTS.bloom, true); // effects on by default
+});
+
+test('readFxSettings: reads keys3d_bg_* overrides and coerces types', () => {
+    const store = { keys3d_bg_bloom: '0' };
+    const win = load({
+        localStorage: {
+            getItem: (k) => (k in store ? store[k] : null),
+            setItem: (k, v) => { store[k] = v; },
+        },
+    });
+    const { readFxSettings } = win.slopsmithViz_keys_highway_3d.__test;
+    assert.equal(readFxSettings().bloom, false);
+    store.keys3d_bg_bloom = 'true';
+    assert.equal(readFxSettings().bloom, true);
+    store.keys3d_bg_bloom = 'false';
+    assert.equal(readFxSettings().bloom, false);
+    // Corrupt/foreign value → keep the default rather than silently
+    // disabling the effect.
+    store.keys3d_bg_bloom = 'banana';
+    assert.equal(readFxSettings().bloom, true);
+});
+
+test('keys3dSetFx: persists, coerces, and ignores unknown keys', () => {
+    const store = {};
+    const events = [];
+    const win = load({
+        localStorage: {
+            getItem: (k) => (k in store ? store[k] : null),
+            setItem: (k, v) => { store[k] = v; },
+        },
+        dispatchEvent: (ev) => { events.push(ev); return true; },
+        CustomEvent: class CustomEvent {
+            constructor(type, opts) { this.type = type; this.detail = opts && opts.detail; }
+        },
+    });
+    win.keys3dSetFx('bloom', false);
+    assert.equal(store.keys3d_bg_bloom, '0');
+    // String forms round-trip like the reader's accepted representations.
+    win.keys3dSetFx('bloom', 'false');
+    assert.equal(store.keys3d_bg_bloom, '0');
+    win.keys3dSetFx('bloom', 'true');
+    assert.equal(store.keys3d_bg_bloom, '1');
+    win.keys3dSetFx('bloom', false);
+    assert.equal(events.length, 4);
+    assert.equal(events[0].type, 'keys3d:settings');
+    // Field-wise (the detail object was built inside the vm realm, so a
+    // deep-strict compare would trip on its foreign Object.prototype).
+    assert.equal(events[0].detail.fx.bloom, false);
+    assert.deepEqual(Object.keys(events[0].detail.fx), ['bloom']);
+    // Unknown key: no write, no event.
+    win.keys3dSetFx('nonsense', 1);
+    assert.equal(events.length, 4);
+    assert.ok(!('keys3d_bg_nonsense' in store));
+});
+
+test('_classifyTiming: OK band is 40% of the window, sign maps early/late', () => {
+    const { _classifyTiming } = load().slopsmithViz_keys_highway_3d.__test;
+    const tol = 0.10;                    // keys HIT_TOLERANCE_S
+    assert.equal(_classifyTiming(0, tol), 'OK');
+    assert.equal(_classifyTiming(tol * 0.4, tol), 'OK');
+    assert.equal(_classifyTiming(-tol * 0.4, tol), 'OK');
+    // delta = note.t - now: positive → struck before the note → EARLY.
+    assert.equal(_classifyTiming(tol * 0.41, tol), 'EARLY');
+    assert.equal(_classifyTiming(-tol * 0.41, tol), 'LATE');
+    assert.equal(_classifyTiming(NaN, tol), 'OK');
+});
+
+test('noteKey prefix round-trips the matched note time (timing-delta source)', () => {
+    const { noteKey } = load().slopsmithViz_keys_highway_3d.__test;
+    // _checkHit derives the timing delta as parseFloat(judgeHit's key) - t;
+    // this pins the serialization that makes that recovery valid.
+    assert.equal(parseFloat(noteKey(12.3456, 60)), 12.346);
+    assert.equal(parseFloat(noteKey(0, 21)), 0);
+});
+
+test('FX defaults: hit-FX + vibrancy controls ship enabled', () => {
+    const { FX_DEFAULTS } = load().slopsmithViz_keys_highway_3d.__test;
+    assert.equal(FX_DEFAULTS.sparks, true);
+    assert.equal(FX_DEFAULTS.timingFx, true);
+    assert.equal(FX_DEFAULTS.streakFx, true);
+    assert.equal(FX_DEFAULTS.hitFx, 0.7);
+    assert.equal(FX_DEFAULTS.vibrancy, 0.85);
+});
+
+test('themes: table ids match the guitar highway, default is the stock palette', () => {
+    const { BG_THEMES, _bgThemeColors, readThemeSetting } = load().slopsmithViz_keys_highway_3d.__test;
+    assert.deepEqual(Object.keys(BG_THEMES), [
+        'default', 'midnight', 'charcoal', 'deeppurple', 'forest', 'warmslate',
+        'deepfocus', 'deepsea', 'cathode', 'cathodegreen', 'hearth',
+    ]);
+    // 'default' preserves THIS plugin's original look.
+    assert.equal(BG_THEMES.default.clear, 0x1a1a2e);
+    assert.equal(BG_THEMES.default.board, 0x141422);
+    assert.equal(BG_THEMES.default.laneDim, 0x2a2a3e);
+    assert.equal(_bgThemeColors('nonsense'), BG_THEMES.default);
+    assert.equal(readThemeSetting(), 'default'); // no localStorage in the vm
+    for (const [id, t] of Object.entries(BG_THEMES)) {
+        assert.equal(t.clear, t.fog, id + ' clear==fog (horizon dissolve)');
+        assert.ok(t.laneDim != null, id + ' rail color');
+    }
+});
+
+test('FX defaults: theme-PR controls ship enabled at stock-neutral values', () => {
+    const { FX_DEFAULTS } = load().slopsmithViz_keys_highway_3d.__test;
+    assert.equal(FX_DEFAULTS.cinematic, true);
+    assert.equal(FX_DEFAULTS.glow, 0.5);   // 0.5 = 1.0x multiplier (stock)
+});
+
+
+test('bg styles: validated id set, particles default', () => {
+    const { BG_STYLE_IDS, readBgStyleSetting } = load().slopsmithViz_keys_highway_3d.__test;
+    // Host-realm copy — the vm array's foreign prototype trips deepEqual.
+    assert.deepEqual([...BG_STYLE_IDS], ['off', 'particles', 'lights', 'geometric']);
+    assert.equal(readBgStyleSetting(), 'particles');
+});
+
+test('FX defaults: ambience + score FX ship enabled', () => {
+    const { FX_DEFAULTS } = load().slopsmithViz_keys_highway_3d.__test;
+    assert.equal(FX_DEFAULTS.scoreFx, true);
+    assert.equal(FX_DEFAULTS.bgIntensity, 0.5);
+    assert.equal(FX_DEFAULTS.bgReactive, true);
+});

plugins/keys_highway_3d/tests/scoring.test.js

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

plugins/tuner/plugin.json

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

plugins/tuner/routes.py

@@ -33,10 +33,9 @@ def setup(app: FastAPI, context: dict):
             "lastInstrument": DEFAULT_INSTRUMENT,
             "freeTune": False,
             "customTunings": {},
-            "disabledTunings": [],
-            "showFloatingButton": True,
             "visualizationMode": "default",
             "audioInputMode": "auto",
+            "autoOpenOnTuningChange": False,
         }
         if not config_file.exists():
             return defaults
@@ -50,16 +49,17 @@ def setup(app: FastAPI, context: dict):
             res["lastInstrument"] = str(data.get("lastInstrument", DEFAULT_INSTRUMENT))
             res["freeTune"] = bool(data.get("freeTune", False))
             res["customTunings"] = data.get("customTunings", {})
-            res["disabledTunings"] = data.get("disabledTunings", [])
-            res["showFloatingButton"] = bool(data.get("showFloatingButton", True))
             res["visualizationMode"] = str(data.get("visualizationMode", "default"))
             raw_mode = str(data.get("audioInputMode", "auto"))
             res["audioInputMode"] = raw_mode if raw_mode in ("auto", "browser") else "auto"
+            # Fail closed: only a real JSON boolean enables the opt-in. A hand-edited /
+            # migrated / bad-client value (e.g. the string "false" or "0") must NOT be
+            # coerced to True by bool().
+            _auto_open = data.get("autoOpenOnTuningChange", False)
+            res["autoOpenOnTuningChange"] = _auto_open if isinstance(_auto_open, bool) else False
 
             if not isinstance(res["customTunings"], dict):
                 res["customTunings"] = {}
-            if not isinstance(res["disabledTunings"], list):
-                res["disabledTunings"] = []
 
             # Migrate custom tunings from old flat-list format
             res["customTunings"] = {
@@ -67,12 +67,6 @@ def setup(app: FastAPI, context: dict):
                 for name, val in res["customTunings"].items()
             }
 
-            # Strip legacy disabledTunings entries that lack compound "instrument:name" format
-            res["disabledTunings"] = [
-                e for e in res["disabledTunings"]
-                if isinstance(e, str) and ":" in e
-            ]
-
             return res
         except Exception:
             return defaults
@@ -80,8 +74,10 @@ def setup(app: FastAPI, context: dict):
     def _write(data: dict) -> None:
         config_dir.mkdir(parents=True, exist_ok=True)
         current = _read()
-        # Strip keys that belong to core, not to this plugin's config.
-        for key in ("defaultTunings", "referencePitch"):
+        # Strip keys that belong to core, not to this plugin's config, plus
+        # retired keys (disabledTunings/showFloatingButton — their settings UI
+        # was removed) so a stale client can't re-persist them.
+        for key in ("defaultTunings", "referencePitch", "disabledTunings", "showFloatingButton"):
             data = {k: v for k, v in data.items() if k != key}
         current.update(data)
         config_file.write_text(json.dumps(current, indent=2), encoding="utf-8")

plugins/tuner/screen.js

@@ -13,8 +13,17 @@
     let _lastAutoOpenSessionKey = null;
     let _autoOpenDismissedSessionKey = null;
     let _autoOpenGeneration = 0;
+    // Bumped on every enable()/disable() so an in-flight open (which awaits audio start
+    // with the panel already visible) can detect it was dismissed mid-open and NOT flip
+    // _state.enabled on afterwards — avoiding a zombie enabled-but-hidden tuner.
+    let _openGen = 0;
     let _onAutoOpenSongLoading = null;
     let _onAutoOpenSongReady = null;
+    // Autoplay gate (E2): when the feature is on, hold playback on song:loading and
+    // release it once we know we won't open (covered / unchanged) or the tuner is
+    // dismissed — so playback waits behind a genuinely-needed retune.
+    let _autoplayRelease = null;
+    let _gateClaimed = false;
 
     // ── Shared mutable state (read/written by screen.js; UI reads via closure) ──
     const _state = {
@@ -33,7 +42,6 @@
         _allTunings: {},
         referencePitch: 440,
         visualizationMode: 'default',
-        showFloatingButton: true,
         currentSongOffsets: null,
         currentSongIsBass: false,
         currentSongStringCount: 0,
@@ -83,10 +91,6 @@
     }
 
     // ── Tuning helpers ────────────────────────────────────────────────
-    function _isTuningEnabled(instrument, name) {
-        return !((_state._serverConfig ? _state._serverConfig.disabledTunings : null) || []).includes(instrument + ':' + name);
-    }
-
     function _instrumentForTuning(name) {
         for (var key in _state._allTunings) {
             if (_state._allTunings[key] && _state._allTunings[key][name]) return key;
@@ -95,11 +99,7 @@
     }
 
     function _buildTuningsForInstrument(instrument) {
-        const all = _state._allTunings[instrument] || {};
-        const disabled = (_state._serverConfig ? _state._serverConfig.disabledTunings : null) || [];
-        return Object.fromEntries(
-            Object.entries(all).filter(([name]) => !disabled.includes(instrument + ':' + name))
-        );
+        return { ...(_state._allTunings[instrument] || {}) };
     }
 
     function _tuningIdentityKey(songInfo) {
@@ -133,15 +133,259 @@
         return filename + '::' + arr;
     }
 
+    // ── §4 instrument-coverage ────────────────────────────────────────────────
+    // FeedBack is tune-to-song: the highway draws tab in the SONG's tuning, so the
+    // player tunes their instrument to match. We therefore only auto-open when the
+    // player's CURRENT physical tuning doesn't already cover the song — i.e. the
+    // song's open-string tuning isn't an exact contiguous run inside the player's
+    // strings, OR the global reference differs. So an 8-string F# player isn't
+    // nagged for a 6-/7-string standard song (its top strings already match), but a
+    // Drop-A song whose dropped open string the player lacks still prompts.
+    function _openMidisFromFreqs(freqs) {
+        const u = window._tunerUtils;
+        if (!u || !Array.isArray(freqs)) return null;
+        return freqs.map((f) => Math.round(u.freqToMidi(f)));
+    }
+
+    // The song's open-string MIDI (at A440; centOffset handled separately as a
+    // global). Mirrors _tuningIdentityKey's isBass / string-count derivation.
+    function _songOpenMidis(songInfo) {
+        const u = window._tunerUtils;
+        if (!u || !songInfo || !Array.isArray(songInfo.tuning) || !songInfo.tuning.length) return null;
+        const ctx = (typeof window.feedBack?.songTuningContext === 'function')
+            ? window.feedBack.songTuningContext(songInfo)
+            : { stringCount: songInfo.stringCount, arrangement: songInfo.arrangement, arrangement_smart_name: songInfo.arrangement_smart_name };
+        const isBass = (typeof window.feedBack?.isBassArrangement === 'function')
+            ? window.feedBack.isBassArrangement(ctx)
+            : (songInfo.arrangement || '').toLowerCase().includes('bass');
+        const sc = (typeof window.feedBack?.effectiveStringCount === 'function')
+            ? window.feedBack.effectiveStringCount(songInfo.tuning, ctx)
+            : (songInfo.stringCount || songInfo.tuning.length);
+        if (!sc || sc <= 0) return null;
+        const offsets = songInfo.tuning.slice(0, sc);
+        if (!offsets.length) return null;
+        return _openMidisFromFreqs(u.offsetsToFreqs(offsets, isBass));
+    }
+
+    // The player's CURRENT physical tuning. Prefer the host-owned live working
+    // tuning (window.feedBack.workingTuning) — what the instrument is *actually* in
+    // right now, which advances as the player retunes — so coverage prompts fire in
+    // BOTH directions (E→C# and back), not only away from a fixed profile. Feature-
+    // detected: on a host without the working-tuning capability, or before it's been
+    // set, we fall back to the static /api/settings instrument tuning (today's
+    // behavior). Returns { midis, refCents } or null.
+    // The SELECTED physical instrument's working-tuning slot identity, from /api/settings.
+    // The read (_playerTuning) and the write (_publishWorkingTuning) MUST agree on this
+    // key — the working tuning is a property of the player's selected instrument, not of
+    // any one song — or a published tuning lands in a slot coverage never reads back.
+    // Returns { isBass, sc, key }.
+    function _selectedInstrument(s) {
+        const isBass = !!(s && s.instrument === 'bass');
+        const sc = (s && Number(s.string_count)) || (isBass ? 4 : 6);
+        return { isBass, sc, key: (isBass ? 'bass' : 'guitar') + '-' + sc };
+    }
+
+    // Memoize the player's tuning: it depends only on /api/settings + the working
+    // tuning, which change on instrument:changed / working-tuning-changed (NOT per song).
+    // Without this, a consumer that evaluates coverage for many items at once — the
+    // library's per-song tuning-match chips — would fire one /api/settings fetch PER item
+    // per paint. Cache the promise so they all share one read; invalidate on the events
+    // that change the answer, AND expire after a short TTL so a settings write that
+    // doesn't emit an event (e.g. the input-setup flow) still heals within seconds.
+    let _playerTuningPromise = null;
+    let _playerTuningAt = 0;
+    const _PLAYER_TUNING_TTL_MS = 3000;
+    function _playerTuning() {
+        const now = (typeof Date !== 'undefined' && Date.now) ? Date.now() : 0;
+        if (!_playerTuningPromise || (now - _playerTuningAt) > _PLAYER_TUNING_TTL_MS) {
+            _playerTuningAt = now;
+            const p = _computePlayerTuning();
+            _playerTuningPromise = p;
+            // Never pin a transient failure: if the read yields null (or rejects), drop
+            // the cache so the next call retries. A real result stays until invalidation/TTL.
+            p.then((r) => { if (r == null && _playerTuningPromise === p) _playerTuningPromise = null; },
+                () => { if (_playerTuningPromise === p) _playerTuningPromise = null; });
+        }
+        return _playerTuningPromise;
+    }
+    function _invalidatePlayerTuning() { _playerTuningPromise = null; }
+
+    async function _computePlayerTuning() {
+        const u = window._tunerUtils;
+        if (!u) return null;
+        // Instrument IDENTITY (which instrument is selected) + the static fallback
+        // tuning, from /api/settings.
+        let s = null;
+        try { s = await fetch('/api/settings').then((r) => (r && r.ok ? r.json() : null)); }
+        catch (_) { s = null; }
+        const { isBass, sc, key } = _selectedInstrument(s);
+        // Cache the resolved selection so the (synchronous) publish-on-clear writes to
+        // the EXACT slot this read path uses — no second /api/settings fetch that could
+        // race an instrument switch. Only cache when settings were actually read: on a
+        // fetch failure we keep the last confident selection (or none → publish skips)
+        // rather than recording a bogus default-instrument slot to publish into later.
+        // Coverage runs before any auto-open, so this is set by the time a clear can publish.
+        if (s) {
+            _state._playerSelected = { isBass, sc, key, refPitch: Number(s.reference_pitch) || 440 };
+        }
+        // The LIVE per-instrument working tuning (advances as the player retunes) —
+        // this is what makes coverage prompt in BOTH directions, not only away from a
+        // fixed profile. Feature-detected; falls back to the static settings tuning
+        // when unset / no host capability.
+        const wt = (window.feedBack && window.feedBack.workingTuning
+            && typeof window.feedBack.workingTuning.get === 'function')
+            ? window.feedBack.workingTuning.get(key) : null;
+        const wtHasOffsets = !!(wt && Array.isArray(wt.offsets) && wt.offsets.length);
+        let freqs = null;
+        if (wtHasOffsets) {
+            freqs = u.offsetsToFreqs(wt.offsets.slice(0, sc), isBass);
+        } else if (s && Array.isArray(s.tuning)) {
+            freqs = u.offsetsToFreqs(s.tuning.slice(0, sc), isBass);
+        } else if (s && typeof s.tuning === 'string') {
+            const named = _state._allTunings && _state._allTunings[key];
+            if (named && Array.isArray(named[s.tuning])) freqs = named[s.tuning];
+        }
+        if (!freqs) {
+            // No confident instrument identity — settings absent, OR present but carrying
+            // no instrument/string_count/tuning (a fresh profile: /api/settings omits them)
+            // — and no live working tuning. We can't tell the player's tuning, so fail
+            // toward prompting (null → not-covered) rather than silently assuming standard
+            // and suppressing a genuinely-needed prompt.
+            const hasIdentity = !!(s && (s.instrument || s.string_count || s.tuning));
+            if (!hasIdentity && !wtHasOffsets) return null;
+            freqs = u.offsetsToFreqs(new Array(sc).fill(0), isBass);   // standard fallback
+        }
+        const midis = _openMidisFromFreqs(freqs);
+        if (!midis) return null;
+        const refPitch = (wt && Number(wt.referencePitch)) || (s && Number(s.reference_pitch)) || 440;
+        return { midis, refCents: 1200 * Math.log2(refPitch / 440) };
+    }
+
+    // PR: host workingTuning — when the player clears an AUTO-OPENED tuner we assume
+    // they tuned their (selected) instrument to the song, so publish the song's tuning
+    // as the live working tuning for that instrument ('assumed' — PR 4's explicit
+    // "I tuned / Skip" will replace this heuristic). After the instrument->chart routing
+    // PR the loaded arrangement matches the selected instrument, so the song's tuning IS
+    // the player's instrument's new tuning.
+    //
+    // We write to the SELECTED instrument's slot (the exact key _playerTuning reads),
+    // NOT a song-derived one, so the publish can't be stranded in a slot coverage never
+    // looks at. If the cleared song is a chart for the OTHER instrument (a manual switch
+    // to e.g. the bass part while guitar is selected), we skip — that isn't evidence the
+    // selected instrument was retuned, and writing it would pollute the wrong slot.
+    //
+    // Synchronous, off the selection _playerTuning last resolved (`_state._playerSelected`)
+    // — an auto-open always runs a coverage check first, so it's populated by the time a
+    // clear can publish. Reusing it (rather than re-fetching /api/settings here) keeps the
+    // write key identical to the read key and avoids racing an instrument switch.
+    function _publishWorkingTuning(songInfo) {
+        const wt = window.feedBack && window.feedBack.workingTuning;
+        if (!wt || typeof wt.set !== 'function') return;
+        if (!songInfo || !Array.isArray(songInfo.tuning) || !songInfo.tuning.length) return;
+        const sel = _state._playerSelected;
+        if (!sel || !sel.key || !(sel.sc > 0)) return;   // coverage hasn't resolved the instrument yet
+        const ctx = (typeof window.feedBack?.songTuningContext === 'function')
+            ? window.feedBack.songTuningContext(songInfo)
+            : { stringCount: songInfo.stringCount, arrangement: songInfo.arrangement, arrangement_smart_name: songInfo.arrangement_smart_name };
+        const songIsBass = (typeof window.feedBack?.isBassArrangement === 'function')
+            ? window.feedBack.isBassArrangement(ctx)
+            : (songInfo.arrangement || '').toLowerCase().includes('bass');
+        if (songIsBass !== sel.isBass) return;   // cross-instrument chart — don't pollute the selected slot
+        wt.set({
+            offsets: songInfo.tuning.slice(0, sel.sc),
+            stringCount: sel.sc,
+            instrument: sel.isBass ? 'bass' : 'guitar',
+            referencePitch: sel.refPitch,
+            source: 'tuner',
+        }, { instrument: sel.key, provenance: 'assumed' });
+    }
+
+    // The retune the player would need to match this song, as a structured report:
+    //   { covered, retune: [{ from, to }], reference, cantCover }
+    // — covered: the physical tuning already matches (the song's open strings are an
+    //   exact contiguous run inside the player's strings) → no retune;
+    // — retune: the per-string note changes (e.g. { from:'B', to:'A' }) of the best
+    //   contiguous alignment — what the badge cue names;
+    // — reference: a whole-instrument A4/centOffset mismatch (A440 vs A432, octave);
+    // — cantCover: the song needs more strings than the instrument has.
+    // Conservative: any missing data → { covered:false } so a needed prompt/cue is
+    // never silently dropped on a fetch hiccup.
+    async function _computeCoverageReport(songInfo) {
+        const u = window._tunerUtils;
+        const none = { covered: false, retune: [], reference: false, cantCover: false };
+        if (!u) return none;
+        const song = _songOpenMidis(songInfo);
+        if (!song || !song.length) return none;
+        const player = await _playerTuning();
+        if (!player || !player.midis.length) return none;
+        const reference = Math.abs((Number(songInfo?.centOffset) || 0) - player.refCents) > 25;
+        if (player.midis.length < song.length) return { covered: false, retune: [], reference, cantCover: true };
+        // Best contiguous alignment = the run with the fewest per-string mismatches
+        // (extended-range adds strings at the ends — match by pitch, not index).
+        let best = null;
+        for (let start = 0; start + song.length <= player.midis.length; start++) {
+            const diffs = [];
+            for (let i = 0; i < song.length; i++) {
+                const pm = player.midis[start + i];
+                if (pm !== song[i]) diffs.push({ from: u.midiToNote(pm, false), to: u.midiToNote(song[i], false) });
+            }
+            if (!best || diffs.length < best.length) best = diffs;
+            if (!diffs.length) break;
+        }
+        const covered = !reference && best.length === 0;
+        return { covered, retune: covered ? [] : best, reference, cantCover: false };
+    }
+
+    // Dedup the coverage computation (which fetches /api/settings): the auto-open gate
+    // AND the badge cue both call this on the same song:ready. Cache the in-flight/last
+    // result per song so they share ONE fetch. Invalidated when anything that changes the
+    // answer happens — a new song (song:loading), an instrument switch (instrument:changed),
+    // or a retune (working-tuning-changed) — so the cache can never go stale within a song.
+    let _coverageCache = null;   // { key, promise }
+    function _coverageReport(songInfo) {
+        const key = _autoOpenSessionKey(songInfo) + '|'
+            + (songInfo && Array.isArray(songInfo.tuning) ? songInfo.tuning.join(',') : '')
+            + '|' + (songInfo && songInfo.centOffset != null ? songInfo.centOffset : '');   // coverage uses centOffset
+        if (_coverageCache && _coverageCache.key === key) return _coverageCache.promise;
+        const promise = _computeCoverageReport(songInfo);
+        _coverageCache = { key, promise };
+        return promise;
+    }
+    function _invalidateCoverageCache() { _coverageCache = null; }
+
+    // Boolean form used to gate the auto-open prompt.
+    async function _coveredByPlayerInstrument(songInfo) {
+        return (await _coverageReport(songInfo)).covered;
+    }
+
+    function _releaseGate() {
+        if (_autoplayRelease) { try { _autoplayRelease(); } catch (_) { /* */ } _autoplayRelease = null; }
+    }
+
     function _onAutoOpenSongLoadingHandler() {
         _autoOpenGeneration++;
         _autoOpenDismissedSessionKey = null;
         _lastAutoOpenSessionKey = null;
+        _invalidateCoverageCache();
+        // Claim the autoplay gate NOW (synchronously, before song:ready) when the
+        // feature is on, so playback can wait behind a needed retune. Released on
+        // song:ready if we don't open, or when the tuner is dismissed.
+        _releaseGate();
+        _gateClaimed = false;
+        _autoplayRelease = (_state._serverConfig && _state._serverConfig.autoOpenOnTuningChange
+            && window.feedBack && typeof window.feedBack.holdAutoplay === 'function')
+            ? window.feedBack.holdAutoplay() : null;
     }
 
     async function _maybeAutoOpenOnTuningChange() {
         if (!document.getElementById('player')?.classList.contains('active')) return;
 
+        // Opt-in (default off): only auto-open when the user enabled it in the
+        // tuner settings. Ensure config is loaded so the first song:ready after
+        // boot still reads the real flag; fail closed if it can't load.
+        if (!_state._serverConfig) { try { await loadConfig(); } catch (_) { /* */ } }
+        if (!_state._serverConfig || !_state._serverConfig.autoOpenOnTuningChange) return;
+
         const songInfo = window.highway?.getSongInfo?.() || window.feedBack?.currentSong;
         if (!songInfo) return;
 
@@ -165,10 +409,21 @@
         if (_lastAutoOpenSessionKey === sessionKey) return;
         if (!window.tuner || typeof window.tuner.enable !== 'function') return;
 
+        // §4: skip the prompt when the player's physical instrument already covers
+        // this song's tuning (e.g. an 8-string F# playing a 6-/7-string standard
+        // song). Async (fetches /api/settings) — re-check the generation after.
+        const covered = await _coveredByPlayerInstrument(songInfo);
+        if (myGen !== _autoOpenGeneration) return;
+        if (covered) return;
+
         _lastAutoOpenSessionKey = sessionKey;
         try {
-            await window.tuner.enable();
+            await window.tuner.enable({ auto: true });
             if (myGen !== _autoOpenGeneration) return;
+            _gateClaimed = true;   // tuner is open → keep the autoplay gate until it's dismissed
+            // The hold is now intentional and user-dismissable — cancel the fail-open
+            // backstop so it can't start playback while the player is still tuning.
+            if (_autoplayRelease && typeof _autoplayRelease.settle === 'function') _autoplayRelease.settle();
         } catch (e) {
             console.warn('Tuner: auto-open failed:', e && e.message ? e.message : e);
             if (_lastAutoOpenSessionKey === sessionKey) _lastAutoOpenSessionKey = null;
@@ -183,9 +438,26 @@
     function _installAutoOpenListeners() {
         if (_onAutoOpenSongLoading || !window.feedBack?.on) return;
         _onAutoOpenSongLoading = _onAutoOpenSongLoadingHandler;
-        _onAutoOpenSongReady = () => { _maybeAutoOpenOnTuningChange(); };
+        _onAutoOpenSongReady = async () => {
+            const myGen = _autoOpenGeneration;
+            await _maybeAutoOpenOnTuningChange();
+            // A newer song:loading may have superseded us while awaiting — it owns the
+            // gate/_gateClaimed now, so don't release its hold based on our stale view.
+            if (myGen !== _autoOpenGeneration) return;
+            if (!_gateClaimed) _releaseGate();   // not gating this song → let it play
+        };
         window.feedBack.on('song:loading', _onAutoOpenSongLoading);
         window.feedBack.on('song:ready', _onAutoOpenSongReady);
+        // The badge (static/v3/badges.js) emits this on the feedBack bus when the player
+        // switches instrument. Drop the cached selection so a publish-on-clear can't write
+        // to the previously-selected instrument's slot; the next coverage read re-resolves
+        // it. Until then _publishWorkingTuning skips (safe — no mis-slotted write).
+        window.feedBack.on('instrument:changed', () => {
+            _state._playerSelected = null; _invalidatePlayerTuning(); _invalidateCoverageCache();
+        });
+        // A retune (working tuning published on a tuner clear) changes coverage for the
+        // current song — drop the cached player tuning + report so a re-evaluation recomputes.
+        window.feedBack.on('working-tuning-changed', () => { _invalidatePlayerTuning(); _invalidateCoverageCache(); });
     }
 
     // ── Player sync helpers ───────────────────────────────────────────
@@ -209,6 +481,12 @@
             const sc = (typeof window.feedBack?.effectiveStringCount === 'function')
                 ? window.feedBack.effectiveStringCount(songInfo.tuning, ctx)
                 : (songInfo.stringCount || songInfo.tuning.length);
+            // A tuning change invalidates an in-flight mic-verify — its captured targets
+            // and offsets are now stale, so it must not complete against the old tuning.
+            if (_verify && String(songInfo.tuning.slice(0, sc)) !== String(_verify.offsets)) {
+                verifyCancel();
+                _tunerUIApi?.resetVerify?.();
+            }
             _state.currentSongOffsets = songInfo.tuning.slice(0, sc);
             _state.currentSongIsBass = isBass;
             _state.currentSongStringCount = sc;
@@ -267,7 +545,6 @@
             _state._serverConfig = config;
             _state._allTunings = tuningsData.tunings || {};
             _state.referencePitch = tuningsData.referencePitch || 440;
-            _state.showFloatingButton = config.showFloatingButton !== false;
             _state.visualizationMode = config.visualizationMode || 'default';
             _state.audioInputMode = config.audioInputMode || 'auto';
 
@@ -341,8 +618,16 @@
         }
     }
 
-    async function enable() {
+    async function enable(opts) {
         if (_state.enabled) return;
+        const myOpen = ++_openGen;   // this open's token; a disable()/newer open invalidates it
+        // An AUTO-open (the "this song needs a different tuning" nudge) must
+        // PERSIST: it is NOT dismissed by the autoplay song:play that follows
+        // song entry, a stray click, or a same-screen re-emit — only by the
+        // Skip/× buttons or leaving the song. A manual open keeps the classic
+        // click-away / play-to-close behaviour.
+        const auto = !!(opts && opts.auto);
+        _state.autoOpened = auto;
         await _loadScript('/api/plugins/tuner/utils/tuning-utils.js');
         await _loadScript('/api/plugins/tuner/utils/audio.js');
         await _loadScript('/api/plugins/tuner/utils/ui.js');
@@ -371,15 +656,33 @@
         _state.uiContainer.classList.add('flex');
         _tunerUIApi.positionPanel();
         _tunerUIApi.updateFreeTuneUI();
+        // "Skip" is the auto-open nudge's explicit dismiss; hidden for a manual
+        // open (the × / click-away already close those).
+        if (_state.skipBtn) _state.skipBtn.classList.toggle('hidden', !auto);
+        // Auto-open shows the "Back to library" escape hatch and hides the ×:
+        // the Skip / Back buttons + Esc are the auto-open's dismiss surface, so a
+        // gated retune always offers a way forward AND a way out.
+        if (_state.backBtn) _state.backBtn.classList.toggle('hidden', !auto);
+        if (_state.closeBtn) _state.closeBtn.classList.toggle('hidden', !!auto);
 
-        // Close when clicking outside the panel. Deferred so the badge's
-        // opening click doesn't bubble up to the document and fire immediately.
-        if (_outsideClickClose) document.removeEventListener('click', _outsideClickClose);
-        _outsideClickClose = () => { if (_state.enabled) disable(); };
-        setTimeout(() => { if (_outsideClickClose) document.addEventListener('click', _outsideClickClose, { once: true }); }, 0);
+        // Close when clicking outside the panel. Deferred so the badge's opening
+        // click doesn't bubble up to the document and fire immediately. Skipped
+        // for an auto-open: the user never clicked to open it, so their first
+        // unrelated click must not dismiss it (it persists until Skip / Back to
+        // library / Esc).
+        if (!auto) {
+            if (_outsideClickClose) document.removeEventListener('click', _outsideClickClose);
+            _outsideClickClose = () => { if (_state.enabled) disable(); };
+            setTimeout(() => { if (_outsideClickClose) document.addEventListener('click', _outsideClickClose, { once: true }); }, 0);
+        }
 
         if (window.feedBack && !_onScreenChanged) {
-            _onScreenChanged = () => { disable(); };
+            // Auto-opened: close only when we actually LEAVE the song — a player
+            // re-emit while staying put must not tear down the nudge. Manual:
+            // unchanged (any screen change closes it).
+            _onScreenChanged = () => {
+                if (!_state.autoOpened || !document.getElementById('player')?.classList.contains('active')) disable();
+            };
             _onSongReady = () => {
                 _tunerUIApi.renderTuningOptions();
                 if (_state.selectedTuningName === '_current') _syncCurrentTuning();
@@ -396,6 +699,10 @@
                 { deviceId: _state.selectedDeviceId, channel: _state.selectedChannel, audioInputMode: _state.audioInputMode },
                 _tunerUIApi.updateUI
             );
+            // The panel is visible (with ×/Skip) across the audio-start await above, so a
+            // dismiss can land here. If so, disable() already tore the panel down and
+            // bumped _openGen — do NOT flip enabled on (that would leave enabled-but-hidden).
+            if (myOpen !== _openGen) return;
             _state.enabled = true;
             if (window.tuner?.updateButtons) window.tuner.updateButtons();
         } catch (e) {
@@ -406,10 +713,16 @@
     }
 
     function disable() {
+        _openGen++;   // invalidate any in-flight enable() so it won't re-enable after this teardown
         const wasEnabled = _state.enabled;
+        const wasAutoOpened = _state.autoOpened;
         const onPlayer = document.getElementById('player')?.classList.contains('active');
         _state.enabled = false;
+        _state.autoOpened = false;
+        _releaseGate();   // dismissing a gated auto-open releases playback (it starts now)
         _state.manualTargetFreq = null;
+        verifyCancel();                       // a running mic-verify ends when the panel closes
+        _tunerUIApi?.resetVerify?.();
         if (_outsideClickClose) { document.removeEventListener('click', _outsideClickClose); _outsideClickClose = null; }
         if (_state.activeViz) { _state.activeViz.destroy(); _state.activeViz = null; }
         if (_state.uiContainer) { _state.uiContainer.classList.add('hidden'); _state.uiContainer.classList.remove('flex'); }
@@ -427,8 +740,17 @@
         }
         if (wasEnabled && onPlayer) {
             const songInfo = window.highway?.getSongInfo?.() || window.feedBack?.currentSong;
-            if (songInfo) _autoOpenDismissedSessionKey = _autoOpenSessionKey(songInfo);
+            if (songInfo) {
+                _autoOpenDismissedSessionKey = _autoOpenSessionKey(songInfo);
+                // Clearing an auto-opened tuner = the player tuned to this song:
+                // publish the song's tuning as their instrument's live working tuning
+                // so coverage stops nagging for it (and prompts on the way back). But
+                // if a mic-verify already wrote 'verified' this session, a plain
+                // 'assumed' publish would immediately clobber it — leave it verified.
+                if (wasAutoOpened && !_verifiedPublished) _publishWorkingTuning(songInfo);
+            }
         }
+        _verifiedPublished = false;   // consumed — fresh for the next tuner session
     }
 
     window.tuner = {
@@ -472,10 +794,110 @@
         _installAutoOpenListeners();
     }).catch(e => console.error(e));
     _installAutoOpenListeners();
+
+    // ── Mic-verify (working-tuning PR 9b) ──────────────────────────────────────
+    // A choreographed per-string check that promotes the current working tuning
+    // from 'assumed' to 'verified' — the ONLY thing that may ever claim 'verified'
+    // (audio-engine's honesty rule). The player plays each string; once every one
+    // reads in-tune (±VERIFY_TOL_CENTS) and holds for VERIFY_STABLE frames we stamp
+    // provenance:'verified' + verifiedStrings. Cancels on tuner close / tuning change.
+    const VERIFY_TOL_CENTS = 6;
+    const VERIFY_STABLE = 8;
+    let _verify = null;
+    let _verifiedPublished = false;   // set when a mic-verify wrote 'verified' this session
+
+    function verifyState() {
+        if (!_verify) return null;
+        return {
+            complete: _verify.complete,
+            done: _verify.targets.map((t) => t.done),
+            remaining: _verify.targets.filter((t) => !t.done).length,
+        };
+    }
+    // Start a verify session for `targets` (freqs; defaults to the selected tuning).
+    // Captures the tuning's OFFSETS now (explicit arg, else the current song's) so that
+    // when it completes we stamp 'verified' onto the exact tuning that was confirmed.
+    // Per-string semitone offsets (from standard) of the tuning we're verifying, derived
+    // from its target freqs. This is authoritative for BOTH the song ('_current') tuning
+    // and a manually-selected tuning — unlike _state.currentSongOffsets, which for a manual
+    // tuning is a stale/different song's tuning that must NOT be stamped 'verified'. The
+    // player's reference pitch scales both the targets and the standard, so it cancels.
+    function _tuningOffsetsFromFreqs(freqs) {
+        const u = window._tunerUtils;
+        if (!u || typeof u.offsetsToFreqs !== 'function' || typeof u.freqToMidi !== 'function') return null;
+        const isBass = /^bass/.test(_state.selectedInstrument || '');   // the selected instrument, not the song's
+        const refScale = (Number(_state.referencePitch) || 440) / 440;
+        const std = u.offsetsToFreqs(new Array(freqs.length).fill(0), isBass);
+        if (!Array.isArray(std) || std.length !== freqs.length) return null;
+        const out = [];
+        for (let i = 0; i < freqs.length; i++) {
+            const f = Number(freqs[i]);
+            const s = Number(std[i]) * refScale;
+            if (!(f > 0) || !(s > 0)) return null;
+            out.push(Math.round(u.freqToMidi(f) - u.freqToMidi(s)) || 0);   // normalize -0 → 0
+        }
+        return out;
+    }
+    function verifyStart(targets, offsets) {
+        const freqs = (Array.isArray(targets) && targets.length) ? targets : _state.selectedTuning;
+        if (!Array.isArray(freqs) || !freqs.length) return null;
+        // Explicit offsets win (callers/tests that already have them); otherwise derive
+        // them from the tuning actually being verified.
+        const offs = (Array.isArray(offsets) && offsets.length) ? offsets.slice() : _tuningOffsetsFromFreqs(freqs);
+        _verify = { targets: freqs.map((f) => ({ freq: f, streak: 0, done: false })), complete: false, offsets: offs };
+        _verifiedPublished = false;
+        return verifyState();
+    }
+    function verifyCancel() { _verify = null; }
+    // Feed one processed frame (its matched target freq + cents-off). Requires
+    // CONSECUTIVE in-tune frames per string: the one confirmed string advances, and
+    // every other not-yet-done string's streak resets — so a run can't accumulate across
+    // silence / wrong-string / out-of-tune frames. Completes + stamps 'verified' when all pass.
+    function verifyFeed(targetFreq, cents) {
+        if (!_verify || _verify.complete) return verifyState();
+        let hit = null;
+        if (targetFreq != null) {
+            const t = _verify.targets.find((x) => Math.abs(x.freq - targetFreq) < 0.5);
+            if (t && !t.done && isFinite(cents) && Math.abs(cents) <= VERIFY_TOL_CENTS) hit = t;
+        }
+        for (const t of _verify.targets) {
+            if (t.done) continue;
+            if (t === hit) { if (++t.streak >= VERIFY_STABLE) t.done = true; }
+            else t.streak = 0;
+        }
+        if (_verify.targets.every((x) => x.done)) {
+            _verify.complete = true;
+            _publishVerified();
+        }
+        return verifyState();
+    }
+    // Promote the working tuning to 'verified'. Write the CONFIRMED tuning's offsets
+    // atomically with provenance + verifiedStrings (into the selected instrument's slot),
+    // so 'verified' can never attach to stale offsets the slot happened to hold.
+    function _publishVerified() {
+        const wt = window.feedBack && window.feedBack.workingTuning;
+        if (!wt || typeof wt.set !== 'function') return;
+        const offsets = (_verify && Array.isArray(_verify.offsets)) ? _verify.offsets.slice() : null;
+        if (!offsets || !offsets.length) return;   // nothing concrete to claim verified
+        const sel = _state._playerSelected;
+        const next = { offsets: offsets, stringCount: offsets.length, verifiedStrings: offsets.map(() => true) };
+        if (sel && sel.key) { next.instrument = sel.isBass ? 'bass' : 'guitar'; next.referencePitch = sel.refPitch; }
+        const opts = (sel && sel.key) ? { instrument: sel.key, provenance: 'verified' } : { provenance: 'verified' };
+        try { wt.set(next, opts); _verifiedPublished = true; } catch (_) { /* noop */ }
+    }
+
     window._tunerAutoOpen = {
         tuningIdentityKey: _tuningIdentityKey,
         sessionKey: _autoOpenSessionKey,
         maybeAutoOpenOnTuningChange: _maybeAutoOpenOnTuningChange,
+        coveredByPlayerInstrument: _coveredByPlayerInstrument,
+        coverageReport: _coverageReport,
+        playerTuning: _playerTuning,
+        publishWorkingTuning: _publishWorkingTuning,
+        verifyStart: verifyStart,
+        verifyFeed: verifyFeed,
+        verifyCancel: verifyCancel,
+        verifyState: verifyState,
         onSongLoading: _onAutoOpenSongLoadingHandler,
         getState() {
             return {

plugins/tuner/settings.html

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

plugins/tuner/utils/ui.js

@@ -305,6 +305,12 @@ window._tunerUI = function(state, actions) {
     function renderStringNotes() {
         if (!state.stringNoteContainer) return;
         state.stringNoteContainer.innerHTML = '';
+        // Show the mic-verify control only for a selected (non-free) tuning.
+        if (state.verifyRow) {
+            const hasTuning = !!(state.selectedTuning && state.selectedTuning.length && !state.freeTune);
+            state.verifyRow.classList.toggle('hidden', !hasTuning);
+            if (!hasTuning) resetVerifyUI();
+        }
         if (!state.selectedTuning || state.selectedTuning.length === 0) {
             _syncStringOrderHelp(0);
             return;
@@ -327,6 +333,41 @@ window._tunerUI = function(state, actions) {
         _syncStringOrderHelp(total);
     }
 
+    // ── Mic-verify UI (working-tuning PR 9b) ───────────────────────────────────
+    function _markVerifiedStrings(done) {
+        if (!state.stringNoteContainer) return;
+        state.stringNoteContainer.querySelectorAll('[data-freq]').forEach((btn, i) => {
+            btn.classList.toggle('ring-2', !!done[i]);
+            btn.classList.toggle('ring-emerald-400', !!done[i]);
+        });
+    }
+    function _syncVerifyProgress(vs) {
+        if (!vs || !state.verifyStatus) return;
+        const total = vs.done.length;
+        const done = vs.done.filter(Boolean).length;
+        state.verifyStatus.classList.remove('hidden');
+        state.verifyStatus.textContent = vs.complete
+            ? '✓ In tune — tuning verified'
+            : (done + ' of ' + total + ' strings in tune');
+        _markVerifiedStrings(vs.done);
+        if (vs.complete && state.verifyBtn) state.verifyBtn.textContent = 'Verify tuning';
+    }
+    function _startVerify() {
+        if (!window._tunerAutoOpen || typeof window._tunerAutoOpen.verifyStart !== 'function') return;
+        const vs = window._tunerAutoOpen.verifyStart();
+        if (!vs) return;
+        if (state.verifyBtn) state.verifyBtn.textContent = 'Verifying — play each string…';
+        _syncVerifyProgress(vs);
+    }
+    function resetVerifyUI() {
+        if (window._tunerAutoOpen && typeof window._tunerAutoOpen.verifyCancel === 'function') {
+            window._tunerAutoOpen.verifyCancel();
+        }
+        if (state.verifyBtn) state.verifyBtn.textContent = 'Verify tuning';
+        if (state.verifyStatus) { state.verifyStatus.classList.add('hidden'); state.verifyStatus.textContent = ''; }
+        _markVerifiedStrings([]);
+    }
+
     function updateUI(result) {
         const { smoothedFreq, rms, hasSignal } = result;
         const vizMode = state.manualTargetFreq ? 'manual'
@@ -387,13 +428,20 @@ window._tunerUI = function(state, actions) {
         if (window.feedBack && window.feedBack.emit) {
             window.feedBack.emit('tuner:frame', { note, cents, freq: displayFreq, hasSignal: true });
         }
+        // Mic-verify: feed the matched string + cents to a running verify session
+        // and reflect per-string progress on the panel.
+        if (!isManual && !state.freeTune && window._tunerAutoOpen
+            && typeof window._tunerAutoOpen.verifyFeed === 'function') {
+            const vs = window._tunerAutoOpen.verifyFeed(targetFreq, Math.round(cents));
+            if (vs) _syncVerifyProgress(vs);
+        }
     }
 
     function updateFloatingButtonVisibility() {
         const btn = document.getElementById('tuner-toggle-btn');
         if (!btn) return;
         const isPlayer = document.querySelector('.screen.active')?.id === 'player';
-        if (!state.showFloatingButton || isPlayer || window.feedBack?.isPlaying) {
+        if (isPlayer || window.feedBack?.isPlaying) {
             btn.classList.add('hidden');
         } else {
             btn.classList.remove('hidden');
@@ -565,6 +613,17 @@ window._tunerUI = function(state, actions) {
         title.textContent = 'TUNER';
         header.appendChild(title);
 
+        // Explicit close (the panel had no in-box dismiss before; persist mode
+        // needs one). Mirrors the settings gear on the opposite side.
+        const closeBtn = document.createElement('button');
+        closeBtn.className = 'absolute left-0 text-fb-textDim hover:text-fb-text transition-colors text-lg leading-none';
+        closeBtn.setAttribute('aria-label', 'Close tuner');
+        closeBtn.title = 'Close';
+        closeBtn.textContent = '×';
+        closeBtn.onclick = () => actions.disable();
+        state.closeBtn = closeBtn;
+        header.appendChild(closeBtn);
+
         const settingsBtn = document.createElement('button');
         settingsBtn.className = 'absolute right-0 text-fb-textDim hover:text-fb-text transition-colors';
         settingsBtn.innerHTML = `<svg xmlns="http://www.w3.org/2000/svg" class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10.325 4.317c.426-1.756 2.924-1.756 3.35 0a1.724 1.724 0 002.573 1.066c1.543-.94 3.31.826 2.37 2.37a1.724 1.724 0 001.065 2.572c1.756.426 1.756 2.924 0 3.35a1.724 1.724 0 00-1.066 2.573c.94 1.543-.826 3.31-2.37 2.37a1.724 1.724 0 00-2.572 1.065c-.426 1.756-2.924 1.756-3.35 0a1.724 1.724 0 00-2.573-1.066c-1.543.94-3.31-.826-2.37-2.37a1.724 1.724 0 00-1.065-2.572c-1.756-.426-1.756-2.924 0-3.35a1.724 1.724 0 001.066-2.573c-.94-1.543.826-3.31 2.37-2.37.996.608 2.296.07 2.572-1.065z"/><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 12a3 3 0 11-6 0 3 3 0 016 0z"/></svg>`;
@@ -624,8 +683,77 @@ window._tunerUI = function(state, actions) {
         state.vizContainer.className = 'w-full';
         state.uiContainer.appendChild(state.vizContainer);
 
+        // Mic-verify control (working-tuning PR 9b): play each string in tune to
+        // confirm your tuning — promotes 'assumed' → 'verified'. Shown only for a
+        // selected (non-free) tuning; visibility managed in renderStringNotes().
+        state.verifyRow = document.createElement('div');
+        state.verifyRow.className = 'w-full mt-2 hidden';
+        state.verifyBtn = document.createElement('button');
+        state.verifyBtn.className = 'tuner-verify-btn w-full text-[11px] text-fb-textDim hover:text-fb-text border border-fb-border/40 hover:border-fb-border/70 rounded-lg py-1.5 transition-colors';
+        state.verifyBtn.textContent = 'Verify tuning';
+        state.verifyBtn.title = 'Play each string in tune to confirm — marks your tuning verified';
+        state.verifyBtn.onclick = () => _startVerify();
+        state.verifyRow.appendChild(state.verifyBtn);
+        state.verifyStatus = document.createElement('div');
+        state.verifyStatus.className = 'text-[10px] text-fb-textDim text-center mt-1 hidden';
+        state.verifyRow.appendChild(state.verifyStatus);
+        state.uiContainer.appendChild(state.verifyRow);
+
+        // Auto-open nudge's explicit dismiss (hidden unless auto-opened; enable()
+        // toggles it). Closes the same way as the × — disable().
+        const skipBtn = document.createElement('button');
+        skipBtn.className = 'tuner-skip-btn hidden w-full mt-3 text-[11px] text-fb-textDim hover:text-fb-text border border-fb-border/40 hover:border-fb-border/70 rounded-lg py-1.5 transition-colors';
+        skipBtn.textContent = 'Skip';
+        skipBtn.title = "I've tuned — play the song";
+        skipBtn.onclick = () => actions.disable();
+        state.skipBtn = skipBtn;
+        state.uiContainer.appendChild(skipBtn);
+
+        // Auto-open escape hatch: leave the song entirely instead of committing to
+        // the play-now choice — so a gated retune is never a one-way trap. Mirrors
+        // Escape (the player's "Back to library" shortcut) and, like Escape, does
+        // NOT record a tuning (you're leaving, not asserting you tuned).
+        const backBtn = document.createElement('button');
+        backBtn.className = 'tuner-back-btn hidden w-full mt-2 text-[11px] text-fb-textDim hover:text-fb-text border border-fb-border/40 hover:border-fb-border/70 rounded-lg py-1.5 transition-colors';
+        backBtn.textContent = 'Back to library';
+        backBtn.title = 'Leave the song (Esc)';
+        backBtn.onclick = () => {
+            const exit = window.feedBack && window.feedBack.requestExitSong;
+            if (typeof exit === 'function') exit();
+            else if (typeof window.requestExitSong === 'function') window.requestExitSong();
+        };
+        state.backBtn = backBtn;
+        state.uiContainer.appendChild(backBtn);
+
         document.body.appendChild(state.uiContainer);
         state.uiContainer.addEventListener('click', (e) => e.stopPropagation());
+
+        // Re-anchor while the panel is open: the popover it hugs is
+        // vertically centered, so its rect shifts with viewport height.
+        // initUI() runs once (guarded above), so this binds a single listener.
+        window.addEventListener('resize', () => {
+            if (state.uiContainer && !state.uiContainer.classList.contains('hidden')) positionPanel();
+        });
+    }
+
+    // Resolve the sidebar Plugins popover to anchor the panel beside it.
+    // Prefer the host's stable plugin-control slot API and derive its popover
+    // container; fall back to the known popover id only if that's unavailable.
+    // Returns a visible rect, or null (→ caller uses the fixed fallback slot).
+    function _pluginsPopoverRect() {
+        let pop = null;
+        try {
+            if (window.feedBack?.ui && typeof window.feedBack.ui.playerControlSlot === 'function') {
+                const slot = window.feedBack.ui.playerControlSlot();
+                if (slot instanceof Element) pop = slot.closest('.v3-rail-pop') || slot;
+            }
+        } catch (_e) { /* host slot API failure → fall back to id lookup */ }
+        if (!pop) pop = document.getElementById('v3-rail-pop-plugins');
+        // offsetParent === null covers display:none on the element or any
+        // ancestor (more robust than testing a specific `hidden` class).
+        if (!pop || pop.offsetParent === null) return null;
+        const rect = pop.getBoundingClientRect();
+        return (rect.width || rect.height) ? rect : null;
     }
 
     function positionPanel() {
@@ -645,7 +773,20 @@ window._tunerUI = function(state, actions) {
                 .replace('right-0', '')
                 .replace('top-full', '')
                 .trim();
-            state.uiContainer.style.cssText = 'top:5rem;right:11rem';
+            const anchor = _pluginsPopoverRect();
+            if (anchor) {
+                // Anchor to the right of the Plugins popover, clamped to the
+                // viewport so the panel never opens off-screen (right/bottom)
+                // on a narrow or short window.
+                const GAP = 8, MARGIN = 8;
+                const pw = state.uiContainer.offsetWidth || 288;   // w-72
+                const ph = state.uiContainer.offsetHeight || 0;
+                const left = Math.max(MARGIN, Math.min(anchor.right + GAP, window.innerWidth - pw - MARGIN));
+                const top = Math.max(MARGIN, Math.min(anchor.top, window.innerHeight - ph - MARGIN));
+                state.uiContainer.style.cssText = `top:${top}px;left:${left}px`;
+            } else {
+                state.uiContainer.style.cssText = 'top:5rem;right:11rem';
+            }
             return;
         }
 
@@ -683,7 +824,11 @@ window._tunerUI = function(state, actions) {
 
         const handlePlay = () => {
             updateFloatingButtonVisibility();
-            if (state.enabled) actions.disable();
+            // A manually-opened tuner closes when playback starts (you don't tune
+            // while playing). An AUTO-opened tuner PERSISTS through the autoplay
+            // song:play that immediately follows song entry — that auto-close was
+            // the "opens then vanishes ~1s later" flash. It closes via Skip/×/leave.
+            if (state.enabled && !state.autoOpened) actions.disable();
         };
         const handleStop = () => updateFloatingButtonVisibility();
 
@@ -737,6 +882,7 @@ window._tunerUI = function(state, actions) {
         renderTuningOptions,
         renderStringNotes,
         updateUI,
+        resetVerify: resetVerifyUI,
         updateInstrumentDisplay: _updateInstrumentDisplay,
         updateSaveAsCustomVisibility: _updateSaveAsCustomVisibility,
         updateFreeTuneUI,

scripts/lift_keys_notation.py

@@ -60,6 +60,8 @@ import yaml  # noqa: E402
 
 import notation as notation_mod  # noqa: E402, F401  (re-exported for tests)
 
+from jsonc import load_json  # noqa: E402
+
 # The wire→notation heuristic core lives in ``lib/notation_lift.py`` so it can
 # be reused in-process (e.g. by the Arrangement Editor's notation save path)
 # rather than being copy-pasted out of this one-time CLI. Re-exported here so
@@ -106,15 +108,16 @@ def _parse_time_signature(raw: object) -> tuple[int, int]:
 
 
 def _load_song_beats(pak: Path, manifest: dict) -> list[dict]:
-    """Song-level beats: ``song_timeline.json`` when present, else the first
+    """Song-level beats: the ``song_timeline`` file when present, else the first
     arrangement JSON that carries a non-empty ``beats`` array (the loader's
-    legacy convention)."""
+    legacy convention). Both the timeline and arrangement files are read via
+    ``load_json``, so either may be ``.json`` or ``.jsonc``."""
     st_rel = manifest.get("song_timeline")
     if isinstance(st_rel, str) and st_rel:
         st_path = _safe_child(pak, st_rel)
         if st_path is not None and st_path.is_file():
             try:
-                data = json.loads(st_path.read_text(encoding="utf-8"))
+                data = load_json(st_path)
                 # An empty beats list is not an authoritative timeline — fall
                 # through to the arrangement JSONs rather than ending up with
                 # zero downbeats and skipping the whole sloppak.
@@ -134,7 +137,7 @@ def _load_song_beats(pak: Path, manifest: dict) -> list[dict]:
         if arr_path is None or not arr_path.is_file():
             continue
         try:
-            data = json.loads(arr_path.read_text(encoding="utf-8"))
+            data = load_json(arr_path)
         except (OSError, ValueError):
             continue
         if isinstance(data, dict):
@@ -219,7 +222,7 @@ def lift_sloppak(pak: Path, *, dry_run: bool = False) -> list[str]:
             continue
 
         try:
-            arr_data = json.loads(arr_path.read_text(encoding="utf-8"))
+            arr_data = load_json(arr_path)
         except (OSError, ValueError) as e:
             log.warning("%s/%s: unreadable arrangement JSON (%s) — skipped",
                         pak.name, arr_id, e)

static/app.js

@@ -5990,6 +5990,56 @@ function _resolvePlayerOrigin() {
 // next song:ready. song:ready also fires on arrangement switches / seeks,
 // which never arm the flag, so those don't auto-restart.
 let _pendingAutostart = false;
+// Autoplay gate (window.feedBack.holdAutoplay): a plugin (the tuner) can defer the
+// auto-start of a freshly-loaded song until it's cleared — "tune before you play".
+// The hold is claimed synchronously on song:loading (so it beats this song:ready
+// autostart); release() — or a fail-open backstop — runs the deferred start.
+// Generation-guarded so a newer song invalidates a stale hold. Manual Play never
+// flows through here, so Play always wins.
+let _autoplayHeld = false;
+let _autoplayStart = null;
+let _autoplayGen = 0;
+let _autoplayBackstop = null;
+const AUTOPLAY_HOLD_BACKSTOP_MS = 12000;
+function _clearAutoplayHold() {
+    if (_autoplayBackstop) { clearTimeout(_autoplayBackstop); _autoplayBackstop = null; }
+    _autoplayHeld = false;
+    _autoplayStart = null;
+    _autoplayGen++;
+}
+function _releaseAutoplay(gen) {
+    if (gen !== _autoplayGen) return;            // a newer song superseded this hold
+    if (_autoplayBackstop) { clearTimeout(_autoplayBackstop); _autoplayBackstop = null; }
+    _autoplayHeld = false;
+    const start = _autoplayStart;
+    _autoplayStart = null;
+    if (typeof start === 'function') start();
+}
+let _autoplayHoldToken = 0;
+window.feedBack.holdAutoplay = function () {
+    const gen = _autoplayGen;
+    const token = ++_autoplayHoldToken;   // this hold's identity — a stale release from an earlier hold is a no-op
+    _autoplayHeld = true;
+    if (_autoplayBackstop) clearTimeout(_autoplayBackstop);
+    // Fail-open: a hold that's never released (a plugin that claimed but wedged before
+    // it could decide) must never permanently block the song. Once the holder commits
+    // to an intentional, user-dismissable hold it calls release.settle() to cancel this
+    // — so the backstop can't cut off e.g. a user still tuning past the timeout.
+    _autoplayBackstop = setTimeout(() => _releaseAutoplay(gen), AUTOPLAY_HOLD_BACKSTOP_MS);
+    let released = false;
+    function release() {
+        if (released || gen !== _autoplayGen || token !== _autoplayHoldToken) return;
+        released = true;
+        _releaseAutoplay(gen);
+    }
+    // Cancel the fail-open backstop WITHOUT releasing: the holder has taken explicit
+    // responsibility for releasing (on dismiss), and a song switch clears the hold anyway.
+    release.settle = function () {
+        if (gen !== _autoplayGen || token !== _autoplayHoldToken) return;
+        if (_autoplayBackstop) { clearTimeout(_autoplayBackstop); _autoplayBackstop = null; }
+    };
+    return release;
+};
 window.feedBack.on('song:ready', () => {
     if (!_pendingAutostart) return;
     _pendingAutostart = false;
@@ -6014,27 +6064,30 @@ window.feedBack.on('song:ready', () => {
         if (authors.length) _creditsTimer = setTimeout(hideSongCreditsOverlay, _CREDITS_HOLD_MS);
         return;
     }
-    // "Countdown before song": play a 4-beat count-in, then start. Otherwise
-    // reuse the Play button's start path directly (handles HTML5 + _juceMode).
-    if (_countdownBeforeSongEnabled()) {
-        // The count-in (~2.5s) gives the credits their on-screen dwell.
-        Promise.resolve(startSongCountIn()).catch((err) => console.warn('[app] song count-in failed:', err));
-    } else if (authors.length) {
-        // No count-in window — hold the credits a couple seconds, then start.
-        // _cancelCountIn() and changeArrangement() both clear _creditsTimer, so
-        // a teardown / arrangement switch during the hold cancels this play.
-        _creditsTimer = setTimeout(() => {
-            _creditsTimer = null;
-            // If playback doesn't actually start (e.g. HTML5 autoplay rejection),
-            // song:play never fires — clear the credits promptly rather than
-            // waiting for the backstop. On success the song:play listener owns it.
+    // The actual auto-start: a count-in (which handles HTML5 + _juceMode) or the
+    // Play path directly. Guarded so a manual Play during a gate / credits hold
+    // can't double-toggle, and so a stale (released-after-leaving) start never
+    // begins playback off the player.
+    const start = () => {
+        if (isPlaying) return;
+        if (!document.getElementById('player')?.classList.contains('active')) { hideSongCreditsOverlay(); return; }
+        if (_countdownBeforeSongEnabled()) {
+            Promise.resolve(startSongCountIn()).catch((err) => console.warn('[app] song count-in failed:', err));
+        } else {
             Promise.resolve(togglePlay())
                 .then(() => { if (!isPlaying) hideSongCreditsOverlay(); })
                 .catch((err) => { console.warn('[app] autoplay failed:', err); hideSongCreditsOverlay(); });
-        }, _CREDITS_HOLD_MS);
-    } else {
-        Promise.resolve(togglePlay()).catch((err) => console.warn('[app] autoplay failed:', err));
-    }
+        }
+    };
+    // A plugin (the tuner) may gate playback until it's cleared. The hold was
+    // claimed on song:loading; stash the start and let release()/the backstop run
+    // it. _cancelCountIn()/changeArrangement() clear _creditsTimer below, so a
+    // teardown during the credits dwell still cancels a non-gated play.
+    if (_autoplayHeld) { _autoplayStart = start; return; }
+    // Not gated: a count-in starts now (it owns its on-screen dwell); otherwise
+    // let the credits dwell a couple seconds first, then start.
+    if (_countdownBeforeSongEnabled() || !authors.length) start();
+    else _creditsTimer = setTimeout(() => { _creditsTimer = null; start(); }, _CREDITS_HOLD_MS);
 });
 
 // ── Resume last session ────────────────────────────────────────────────────
@@ -6328,9 +6381,17 @@ let artAbortController = null;
 
 async function playSong(filename, arrangement, options) {
     console.log('playSong called:', filename);
+    // A manual (non-queue) play abandons any active play-queue, so a stale queue
+    // can't hijack the next song's end. The queue passes fromQueue to keep itself.
+    if ((!options || !options.fromQueue) && window.feedBack && window.feedBack.playQueue) {
+        window.feedBack.playQueue.clear();
+    }
     if (!options || options.bridge !== false) {
         _recordPlaybackBridge('playback.window-play-song', 'window.playSong', 'legacy playSong entry point used');
     }
+    // Invalidate any prior song's autoplay gate before plugins re-claim it on the
+    // song:loading emit below.
+    _clearAutoplayHold();
     window.feedBack.emit('song:loading', { filename, arrangement: arrangement ?? null });
 
     // Cancel any pending art/metadata requests
@@ -6667,11 +6728,83 @@ if (window.feedBack) window.feedBack.restartCurrentSong = restartCurrentSong;
 // (Esc shortcut uses the same origin-aware target). showScreen() owns the
 // full teardown: song:stop, audio unload, highway.stop(), count-in cancel.
 function closeCurrentSong() {
+    // A real close (user Escape/✕, or the queue-aware wrapper once the queue is
+    // exhausted) abandons any play-queue so a stale one can't advance later.
+    if (window.feedBack && window.feedBack.playQueue) window.feedBack.playQueue.clear();
     return showScreen(_playerOriginScreen || 'home');
 }
 window.closeCurrentSong = closeCurrentSong;
 if (window.feedBack) window.feedBack.closeCurrentSong = closeCurrentSong;
 
+// ── Play-queue: sequential playback of a playlist / album ──────────────────
+// Playing a list should advance to the next track when a song ends, instead of
+// returning to the menu (the long-standing "plays one song then boots to menu"
+// gap — a queue was simply never implemented). Advancing rides the SAME exit
+// choke point as auto-exit and a results-card close: window.closeCurrentSong().
+// Song-end paths call window.closeCurrentSong() (the auto-exit grace timer, and
+// a results screen's release()), so wrapping it lets the queue advance on song
+// end AND after the user dismisses a score card. A *user* exit (Escape / the ✕)
+// calls the bareword closeCurrentSong(), which we deliberately leave alone, so
+// leaving the player still leaves — and abandons the queue.
+window.feedBack.playQueue = (function () {
+    let list = [], idx = -1, source = '', arrangements = null;
+    const active = () => idx >= 0 && idx < list.length;
+    const hasNext = () => active() && idx < list.length - 1;
+    function clear() { list = []; idx = -1; source = ''; arrangements = null; }
+    function _play(i) {
+        const fn = list[i];
+        // fromQueue keeps the queue from clearing itself; playSong decodeURIs.
+        window.playSong(encodeURIComponent(fn), arrangements ? arrangements[i] : undefined, { fromQueue: true });
+    }
+    function start(files, opts) {
+        files = (files || []).filter(Boolean);
+        if (!files.length) return false;
+        list = files.slice(); idx = 0;
+        source = (opts && opts.source) || '';
+        arrangements = (opts && opts.arrangements) || null;
+        if (window.fbNotify) {
+            try { window.fbNotify.show({ title: 'Playing ' + (source || 'queue'), message: files.length + ' songs', icon: '▶' }); } catch (e) { /* */ }
+        }
+        _play(idx);
+        return true;
+    }
+    function advance() {
+        if (!hasNext()) { clear(); return false; }
+        idx++;
+        _play(idx);
+        return true;
+    }
+    return {
+        start: start, advance: advance, hasNext: hasNext, active: active, clear: clear,
+        source: function () { return source; },
+        remaining: function () { return active() ? list.length - idx - 1 : 0; },
+        // What's coming, for consumers that RENDER the queue (a results
+        // screen's "Up next: … starting in 10s" strip) without reaching into
+        // queue internals. Null when nothing follows.
+        peekNext: function () {
+            return hasNext()
+                ? { filename: list[idx + 1], index: idx + 1, total: list.length }
+                : null;
+        },
+    };
+})();
+
+// Make the song-end exit queue-aware (see above). Wrap window.closeCurrentSong
+// (and feedBack.closeCurrentSong) so that when a queue has a next track, we play
+// it instead of returning to the menu. The bareword closeCurrentSong() used by a
+// user-initiated exit is unaffected.
+(function () {
+    const realClose = window.closeCurrentSong;
+    function queueAwareClose() {
+        const q = window.feedBack.playQueue;
+        if (q && q.hasNext()) { q.advance(); return; }
+        if (q) q.clear();
+        return realClose.apply(this, arguments);
+    }
+    window.closeCurrentSong = queueAwareClose;
+    if (window.feedBack) window.feedBack.closeCurrentSong = queueAwareClose;
+})();
+
 // ── "Ask before leaving a song" (Gameplay tab, default OFF) ────────────────
 // Client-only localStorage pref (`confirmExitSong`); absence = OFF. When ON, a
 // *user-initiated* exit (Escape, or the player ✕) opens a small confirm instead
@@ -9652,6 +9785,12 @@ async function startSongCountIn() {
 
 // Time display + highway sync
 let lastAudioTime = 0;
+// hud-time write cache: the 60 Hz tick below used to rewrite textContent
+// (and getElementById) every tick even though the mm:ss display only
+// changes once a second — each write invalidates layout. Write-on-change
+// with a cached element ref (re-resolved if detached).
+let _hudTimeEl = null;
+let _hudTimeLast = '';
 setInterval(() => {
     let ct = _audioTime();
     const dur = _audioDuration();
@@ -9679,7 +9818,12 @@ setInterval(() => {
             ct = lastAudioTime;
         }
         lastAudioTime = ct;
-        document.getElementById('hud-time').textContent = `${formatTime(ct)} / ${formatTime(dur)}`;
+        const hudText = `${formatTime(ct)} / ${formatTime(dur)}`;
+        if (hudText !== _hudTimeLast) {
+            if (!_hudTimeEl || !_hudTimeEl.isConnected) _hudTimeEl = document.getElementById('hud-time');
+            if (_hudTimeEl) _hudTimeEl.textContent = hudText;
+            _hudTimeLast = hudText;
+        }
         if (dur) {
             _maybeRefreshSectionPracticeDuration(dur);
         }

static/capabilities/interface-scale.js

@@ -0,0 +1,119 @@
+// Core interface-scale capability — the app-wide "Interface size" preference.
+//
+// Owns a single user setting: a multiplier applied to the ROOT font-size, so
+// the rem-based v3 chrome (menus, buttons, text, spacing) scales together. This
+// is the DOM lever — it deliberately does NOT touch the gameplay highway canvas
+// (which is sized in device pixels, not rem), so scaling the UI never changes
+// playback resolution or FPS.
+//
+// It is exposed as a host read/write API on `window.feedBack.scale` so surfaces
+// that can't inherit `rem` — canvas / WebGL renderers such as the note-highway
+// HUD or results scorecards — can read the number via `feedBack.scale.get()`
+// and follow `scale:changed`. Shape mirrors the other host capabilities (a
+// frozen, versioned object) and the working-tuning read-API: synchronous
+// `get()`, a `set()` mutator, and a change event that also fires once on load.
+//
+// The visual apply ALSO runs pre-paint from a tiny inline <head> script (see
+// index.html) so there is no flash-of-reflow on load; this module is the
+// authoritative owner and re-applies idempotently.
+(function () {
+    'use strict';
+    window.feedBack = window.feedBack || {};
+    if (window.feedBack.scale && window.feedBack.scale.version === 1) return;
+
+    var STORE_KEY = 'v3-interface-scale';
+    var MIN = 0.85, MAX = 1.50, DEFAULT = 1.0;
+    // The named presets rendered by the Settings segmented control. Kept here so
+    // the control and any consumer read the ladder from one source of truth.
+    var PRESETS = [
+        { step: 'small', value: 0.90 },
+        { step: 'medium', value: 1.00 },
+        { step: 'large', value: 1.15 },
+        { step: 'x-large', value: 1.30 },
+    ];
+
+    function clamp(n) {
+        n = Number(n);
+        if (!isFinite(n)) return DEFAULT;
+        return Math.min(MAX, Math.max(MIN, n));
+    }
+
+    function stepFor(value) {
+        for (var i = 0; i < PRESETS.length; i++) {
+            if (Math.abs(PRESETS[i].value - value) < 0.001) return PRESETS[i].step;
+        }
+        return 'custom';
+    }
+
+    function read() {
+        try {
+            var raw = localStorage.getItem(STORE_KEY);
+            if (raw == null) return DEFAULT;
+            return clamp(parseFloat(raw));
+        } catch (_) { return DEFAULT; }
+    }
+
+    var current = read();
+
+    // Apply to the DOM. The lever is a RELATIVE root font-size (a percentage of
+    // the user-agent base), never a px literal — so a user who raised their
+    // browser/OS base font size is respected, not silently overridden. We also
+    // publish the always-present `--fb-scale` token for canvas consumers and CSS.
+    function apply(value) {
+        var el = document.documentElement;
+        if (!el) return;
+        el.style.setProperty('--fb-scale', String(value));
+        // Medium (1.0) clears the inline override so default rendering is
+        // byte-identical to before this feature existed (zero blast radius).
+        el.style.fontSize = (Math.abs(value - 1) < 0.001) ? '' : (value * 100).toFixed(2) + '%';
+    }
+
+    function persist(value) {
+        try {
+            if (Math.abs(value - DEFAULT) < 0.001) localStorage.removeItem(STORE_KEY);
+            else localStorage.setItem(STORE_KEY, String(value));
+        } catch (_) { /* private mode */ }
+    }
+
+    function announce() {
+        try {
+            if (typeof window.feedBack.emit === 'function') {
+                window.feedBack.emit('scale:changed', { value: current, step: stepFor(current) });
+            }
+        } catch (_) { /* noop */ }
+    }
+
+    // Hydrate on load (idempotent with the pre-paint inline script).
+    apply(current);
+
+    window.feedBack.scale = Object.freeze({
+        version: 1,
+        min: MIN,
+        max: MAX,
+        default: DEFAULT,
+        // Synchronous — valid immediately after this module parses.
+        get: function () { return { value: current, step: stepFor(current) }; },
+        // A copy of the preset ladder, so a UI can render it from one source.
+        presets: function () {
+            return PRESETS.map(function (p) { return { step: p.step, value: p.value }; });
+        },
+        // Set + apply + persist + announce. Pass { persist:false } for a
+        // transient preview (e.g. a live slider drag) that shouldn't be written.
+        set: function (value, opts) {
+            var v = clamp(value);
+            current = v;
+            apply(v);
+            if (!opts || opts.persist !== false) persist(v);
+            announce();
+            return current;
+        },
+    });
+
+    // Announce once after the document parses, so any listener wired during page
+    // load can sync without special-casing (consumers may also just call get()).
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', announce, { once: true });
+    } else {
+        announce();
+    }
+})();

static/capabilities/working-tuning.js

@@ -0,0 +1,390 @@
+// Core "working tuning" capability domain — the live, host-authoritative CURRENT
+// instrument tuning (session state), distinct from the soft opt-in default and from
+// any one song's tuning. This is the single source of truth the whole app reads:
+// the highway, the library/song-picker, Virtuoso, and the minigames all consult it,
+// and the tuner is the sole WRITER (it updates this when the player retunes, clears
+// the gate, or switches instruments).
+//
+// PER-INSTRUMENT: a player has separate physical instruments, each in its OWN tuning
+// ("I'm not tuning two instruments when I pick a song"). So state is a MAP keyed by
+// instrument — `${instrument}-${stringCount}` (e.g. "guitar-6", "bass-4"), the same key
+// the v3 instrument selector uses. `get()` returns the CURRENTLY-SELECTED instrument's
+// tuning; switching the selector surfaces that instrument's own remembered tuning. You
+// only ever deal with the one you've picked.
+//
+// Design: WORKING-TUNING-STATE-DESIGN.md (host-first PR series, PR 1 = this file).
+// Pattern mirrors `capabilities/tuning.js` (capability registration) + the host theme
+// read-API (`window.feedBack.theme`): a synchronous `get()` plus a `working-tuning-
+// changed` event that also fires once on hydration.
+//
+// State is IN-MEMORY and NOT persisted — reset-to-home on restart is deliberate (a
+// stale "you're in drop-A" assumption is worse than re-asking). The opt-in "default
+// tuning on app open" lands later; for now we seed the selected instrument from
+// /api/settings.
+//
+// PR 1 is PURE PLUMBING: it introduces the state + read/write surface + event, but
+// nothing writes to it yet and no behavior changes. The tuner becomes the writer (and
+// the gate's E->C# asymmetry is fixed) in a later PR.
+(function () {
+    'use strict';
+
+    window.feedBack = window.feedBack || {};
+    // Idempotent: a second injection of this module must not replace the live state
+    // with a fresh (empty) one — once we're registered, re-running is a no-op.
+    if (window.feedBack.workingTuning && window.feedBack.workingTuning.version === 1) return;
+    const capabilities = window.feedBack.capabilities;
+
+    const _byInstrument = {};   // key -> tuning state (the per-instrument map)
+    let _currentKey = null;     // the selected instrument's key; cached so get() is sync
+    let _hydrated = false;
+    let _touched = false;       // set once anything explicitly writes/selects; gates the async seed
+
+    function _normInstrument(instrument) {
+        return instrument === 'bass' ? 'bass' : 'guitar';
+    }
+    function _keyOf(instrument, stringCount) {
+        const inst = _normInstrument(instrument);
+        const sc = Number(stringCount) || (inst === 'bass' ? 4 : 6);
+        return inst + '-' + sc;
+    }
+    // Like _keyOf, but when the caller omits a string count we resolve it against the
+    // current selection (if it's the same instrument) before falling back to the
+    // per-instrument default — so `set({instrument:'bass'})` targets the selected
+    // bass-5, not a hard-coded bass-4.
+    function _keyOfResolved(instrument, stringCount) {
+        const inst = _normInstrument(instrument);
+        let sc = Number(stringCount);
+        if (!sc) {
+            if (_currentKey) {
+                const cur = _splitKey(_currentKey);
+                if (cur.instrument === inst) sc = cur.stringCount;
+            }
+            if (!sc) sc = (inst === 'bass' ? 4 : 6);
+        }
+        return inst + '-' + sc;
+    }
+    function _splitKey(key) {
+        const parts = (typeof key === 'string' ? key : '').split('-');
+        const inst = parts[0] === 'bass' ? 'bass' : 'guitar';
+        return { instrument: inst, stringCount: Number(parts[1]) || (inst === 'bass' ? 4 : 6) };
+    }
+
+    // The shape every consumer reads. `offsets` are per-string semitone offsets from
+    // standard (same vocabulary as song_info.tuning and /api/tunings); `instrument`
+    // disambiguates the open-string base so offsets resolve to real pitches. A drop-A
+    // 8-string is just an offsets array — fully custom tunings are first-class.
+    // `provenance` is the honesty flag: 'verified' means the tuner did a choreographed
+    // per-string mic check this session; everything else is 'assumed'.
+    function _defaultState(key) {
+        const id = _splitKey(key);
+        return {
+            offsets: null,
+            stringCount: id.stringCount,
+            instrument: id.instrument,
+            referencePitch: 440,
+            provenance: 'assumed',
+            verifiedStrings: null,
+            verifiedAt: null,
+            source: 'default',
+        };
+    }
+
+    // Resolve which instrument key a get/set targets: an explicit arg wins (a string
+    // key "guitar-6", a bare "guitar"/"bass", or { instrument, stringCount }); else the
+    // cached current selection.
+    function _resolveKey(instrument) {
+        if (instrument && typeof instrument === 'object') return _keyOfResolved(instrument.instrument, instrument.stringCount);
+        if (typeof instrument === 'string' && instrument) {
+            return instrument.indexOf('-') > 0 ? instrument : _keyOfResolved(instrument, null);
+        }
+        return _currentKey || _keyOf('guitar', 6);
+    }
+
+    // Synchronous read of an instrument's current tuning (default = selected
+    // instrument). Returns a deep-enough copy — the object plus its mutable array
+    // fields (`offsets`, `verifiedStrings`) — so a reader can't mutate the live state.
+    function get(instrument) {
+        const key = _resolveKey(instrument);
+        const state = Object.assign(_defaultState(key), _byInstrument[key] || {});
+        if (Array.isArray(state.offsets)) state.offsets = state.offsets.slice();
+        if (Array.isArray(state.verifiedStrings)) state.verifiedStrings = state.verifiedStrings.slice();
+        return state;
+    }
+
+    function _emitChanged(key) {
+        if (window.feedBack && typeof window.feedBack.emit === 'function') {
+            window.feedBack.emit('working-tuning-changed', { key: key, instrument: _splitKey(key).instrument, tuning: get(key) });
+        }
+    }
+
+    // The single mutator. The tuner calls this on retune / gate-clear / swap. Writes to
+    // the instrument the state targets (opts.instrument, or next.instrument+stringCount,
+    // or the current selection) and makes that the active instrument. `opts.provenance`
+    // stamps 'verified' (mic-confirmed) vs the default 'assumed'. Changing the tuning
+    // invalidates a prior verification unless fresh verifiedStrings are supplied — fail
+    // toward "assumed".
+    function set(next, opts) {
+        opts = opts || {};
+        next = next || {};
+        // Resolve the target key. An explicit opts.instrument wins; otherwise a
+        // next.instrument/next.stringCount targets that slot — but a bare stringCount
+        // (no instrument) applies to the CURRENTLY-SELECTED instrument, not a hard-coded
+        // guitar, so `set({stringCount:5})` on a selected bass writes bass-5.
+        let key;
+        if (opts.instrument) {
+            key = _resolveKey(opts.instrument);
+        } else if (next.instrument || next.stringCount) {
+            const inst = next.instrument ? _normInstrument(next.instrument)
+                : (_currentKey ? _splitKey(_currentKey).instrument : 'guitar');
+            key = _keyOfResolved(inst, next.stringCount);
+        } else {
+            key = _currentKey || _resolveKey();
+        }
+        const id = _splitKey(key);
+        const merged = Object.assign(get(key), next);   // get() gives copies, so `merged` is ours to mutate
+        merged.instrument = id.instrument;              // keep coherent with the key
+        merged.stringCount = id.stringCount;            // the key is authoritative for string count
+        const tuningChanged = ('offsets' in next) || ('stringCount' in next) || ('referencePitch' in next);
+
+        // Provenance: explicit opts wins; a bare tuning change downgrades to 'assumed'.
+        if (opts.provenance) {
+            merged.provenance = opts.provenance;
+        } else if (tuningChanged) {
+            merged.provenance = 'assumed';
+        }
+
+        // Verification metadata is coherent by construction: a tuning change invalidates
+        // prior per-string verification unless the caller supplies a fresh bundle, and the
+        // metadata exists ONLY while provenance === 'verified'. So verified <=> we hold
+        // verifiedStrings — a "verified with no strings" state is impossible.
+        if (!('verifiedStrings' in next) && tuningChanged) {
+            merged.verifiedStrings = null;
+        }
+        if (merged.provenance === 'verified' && !Array.isArray(merged.verifiedStrings)) {
+            merged.provenance = 'assumed';              // claimed verified but no evidence — fail toward assumed
+        }
+        if (merged.provenance === 'verified') {
+            // verified always carries a real timestamp — a caller-supplied null/NaN/absent
+            // verifiedAt is stamped now, so 'verified' can never mean "at no known time".
+            if (typeof merged.verifiedAt !== 'number' || !isFinite(merged.verifiedAt)) {
+                merged.verifiedAt = Date.now();
+            }
+        } else {
+            merged.verifiedStrings = null;
+            merged.verifiedAt = null;
+        }
+
+        // Store copies of the mutable arrays so a caller can't mutate live state post-set.
+        if (Array.isArray(merged.offsets)) merged.offsets = merged.offsets.slice();
+        if (Array.isArray(merged.verifiedStrings)) merged.verifiedStrings = merged.verifiedStrings.slice();
+        _byInstrument[key] = merged;
+        _currentKey = key;        // writing a tuning makes that instrument the active one
+        _touched = true;          // an explicit write must not be clobbered by the async seed
+        _emitChanged(key);
+        return get(key);
+    }
+
+    // Tell the host which instrument is now selected (the v3 selector calls this when
+    // the player switches guitar<->bass / string count) so get() returns the right
+    // instrument's tuning. Emits if the selection actually changed.
+    function setCurrentInstrument(instrument, stringCount) {
+        const key = (typeof instrument === 'string' && instrument.indexOf('-') > 0) ? instrument : _keyOfResolved(instrument, stringCount);
+        _touched = true;          // an explicit selection must not be reverted by the async seed
+        if (key === _currentKey) return get(key);
+        _currentKey = key;
+        _emitChanged(key);
+        return get(key);
+    }
+
+    // Reset an instrument's live tuning back to its baseline (the home/default).
+    function resetToDefault(instrument) {
+        const key = _resolveKey(instrument);
+        _byInstrument[key] = _defaultState(key);
+        _touched = true;
+        _emitChanged(key);
+        return get(key);
+    }
+
+    // Per-string semitone offsets of a named tuning relative to Standard, derived from
+    // the /api/tunings frequency tables. The reference pitch cancels in the ratio, so
+    // this is pitch-independent. Returns null if either row is missing/mismatched.
+    function _offsetsFromFreqs(named, standard) {
+        if (!Array.isArray(named) || !Array.isArray(standard) || named.length !== standard.length) return null;
+        const out = [];
+        for (let i = 0; i < named.length; i++) {
+            const a = Number(named[i]);
+            const b = Number(standard[i]);
+            if (!(a > 0) || !(b > 0)) return null;
+            out.push(Math.round(12 * Math.log2(a / b)));
+        }
+        return out;
+    }
+
+    // ---- Opt-in "launch tuning" default (soft, per-instrument) -------------------
+    // A convenience the player opts into: "start me in THIS tuning on app open." Off
+    // by default (nothing stored) → boot seeds from /api/settings as before. It is
+    // only a SEED — the live working tuning still resets on restart.
+    const LAUNCH_KEY = 'v3-working-tuning-launch-default';
+    function _readLaunchMap() {
+        try { return JSON.parse(localStorage.getItem(LAUNCH_KEY) || '{}') || {}; }
+        catch (_) { return {}; }
+    }
+    function _writeLaunchMap(map) {
+        try {
+            if (map && Object.keys(map).length) localStorage.setItem(LAUNCH_KEY, JSON.stringify(map));
+            else localStorage.removeItem(LAUNCH_KEY);
+        } catch (_) { /* private mode */ }
+    }
+    function getLaunchDefault(instrument) {
+        const key = _resolveKey(instrument);
+        const d = _readLaunchMap()[key];
+        return d ? Object.assign(_defaultState(key), d, { source: 'launch-default' }) : null;
+    }
+    // Remember an instrument's CURRENT working tuning (or a supplied state) as its
+    // launch default. Opt-in — nothing calls this unless the player asks.
+    function setLaunchDefault(instrument, state) {
+        const key = _resolveKey(instrument);
+        const src = state || get(key);
+        const map = _readLaunchMap();
+        map[key] = {
+            offsets: Array.isArray(src.offsets) ? src.offsets.slice() : null,
+            stringCount: src.stringCount,
+            instrument: _splitKey(key).instrument,
+            referencePitch: src.referencePitch || 440,
+        };
+        _writeLaunchMap(map);
+        return getLaunchDefault(key);
+    }
+    function clearLaunchDefault(instrument) {
+        const key = _resolveKey(instrument);
+        const map = _readLaunchMap();
+        if (key in map) { delete map[key]; _writeLaunchMap(map); }
+    }
+
+    // Seed the SELECTED instrument's slot on boot (best-effort 'assumed' starting
+    // point, NOT a persisted working tuning): the player's opt-in launch default if one
+    // is set for this instrument, else /api/settings — where a NAMED tuning ("Drop D") is
+    // resolved to offsets via /api/tunings so it isn't lost. If neither can be read we
+    // still hydrate so consumers aren't stuck waiting; an explicit set()/select before we
+    // resolve wins (no clobber).
+    function _seedFromSettings() {
+        fetch('/api/settings')
+            .then(function (r) { return r && r.ok ? r.json() : null; })
+            .then(function (s) {
+                if (!s || _touched) return;   // nothing to seed, or a consumer already wrote — don't clobber
+                const inst = _normInstrument(s.instrument);
+                const sc = Number(s.string_count) || (inst === 'bass' ? 4 : 6);
+                const key = _keyOf(inst, sc);
+
+                function commit(offsets) {
+                    if (_touched) return;     // re-check: a write may have raced the /api/tunings fetch
+                    _currentKey = key;
+                    // Opt-in launch default wins over the raw profile; otherwise use the
+                    // resolved `offsets` (a named settings tuning was already turned into
+                    // offsets via /api/tunings before commit()).
+                    const launch = _readLaunchMap()[key];
+                    _byInstrument[key] = launch
+                        ? {
+                            offsets: Array.isArray(launch.offsets) ? launch.offsets.slice(0, sc) : null,
+                            stringCount: sc, instrument: inst,
+                            referencePitch: Number(launch.referencePitch) || 440,
+                            provenance: 'assumed', verifiedStrings: null, verifiedAt: null,
+                            source: 'launch-default',
+                        }
+                        : {
+                            offsets: Array.isArray(offsets) ? offsets.slice(0, sc) : null,
+                            stringCount: sc, instrument: inst,
+                            referencePitch: Number(s.reference_pitch) || 440,
+                            provenance: 'assumed', verifiedStrings: null, verifiedAt: null,
+                            source: 'settings',
+                        };
+                }
+
+                if (Array.isArray(s.tuning)) { commit(s.tuning); return; }
+                if (typeof s.tuning === 'string' && s.tuning) {
+                    return fetch('/api/tunings')
+                        .then(function (r) { return r && r.ok ? r.json() : null; })
+                        .then(function (t) {
+                            const byName = t && t[key];
+                            commit(byName ? _offsetsFromFreqs(byName[s.tuning], byName.Standard) : null);
+                        })
+                        .catch(function () { commit(null); });
+                }
+                commit(null);
+            })
+            .catch(function () { /* keep defaults */ })
+            .then(function () { _hydrate(); });
+    }
+
+    function _hydrate() {
+        if (_hydrated) return;
+        _hydrated = true;
+        _emitChanged(_currentKey || _resolveKey());
+    }
+
+    // A per-string mic verification is only trustworthy for the context it was done
+    // in — a new song means the player may have retuned, so a stale 'verified' must
+    // never suppress a needed prompt (fail toward re-checking). Decay the CURRENT
+    // instrument's verification back to 'assumed' on each song load; offsets are kept.
+    function _decayVerifiedOnSongLoad() {
+        const key = _currentKey || _resolveKey();
+        const st = _byInstrument[key];
+        if (st && st.provenance === 'verified') {
+            st.provenance = 'assumed';
+            st.verifiedStrings = null;
+            st.verifiedAt = null;
+            _emitChanged(key);
+        }
+    }
+    if (typeof window.feedBack.on === 'function') {
+        window.feedBack.on('song:loading', _decayVerifiedOnSongLoad);
+    }
+
+    // ---- Capability registration (mirrors capabilities/tuning.js) ----------------
+    if (capabilities && capabilities.version === 1 &&
+        !(window.feedBack.workingTuning && window.feedBack.workingTuning.version === 1)) {
+        capabilities.registerOwner('working-tuning', {
+            description: 'The live, host-authoritative current instrument tuning (session state), per ' +
+                'instrument: offsets + string-count + reference pitch + assumed/verified provenance. ' +
+                'Written by the tuner, read by the highway/library/Virtuoso/minigames.',
+            operations: ['get-working-tuning', 'set-working-tuning'],
+            events: ['working-tuning-changed'],
+            kind: 'command',
+            ownership: 'exclusive-owner',
+        });
+        capabilities.registerParticipant('plugin.tuner', {
+            'working-tuning': {
+                roles: ['contributor', 'requester'],
+                operations: ['get-working-tuning', 'set-working-tuning'],
+                emits: ['working-tuning-changed'],
+                mode: 'active',
+                compatibility: 'none',
+                safety: 'safe',
+            },
+        });
+        capabilities.registerParticipant('core.settings.instruments', {
+            'working-tuning': {
+                roles: ['requester'],
+                operations: ['get-working-tuning'],
+                events: ['working-tuning-changed'],
+                mode: 'active',
+                compatibility: 'none',
+                safety: 'safe',
+            },
+        });
+    }
+
+    // ---- Public read/write surface (attached defensively, like feedBack.theme) ----
+    window.feedBack.workingTuning = Object.freeze({
+        version: 1,
+        get: get,
+        set: set,
+        setCurrentInstrument: setCurrentInstrument,
+        resetToDefault: resetToDefault,
+        getLaunchDefault: getLaunchDefault,
+        setLaunchDefault: setLaunchDefault,
+        clearLaunchDefault: clearLaunchDefault,
+    });
+
+    _seedFromSettings();
+})();

static/highway.js

@@ -122,6 +122,24 @@ function createHighway() {
     // where offsetParent === null isn't enough.
     let _visibleOverride = null;
     let _lastVisible = null;
+    // Throttled DOM visibility sampling. Reading canvas.offsetParent
+    // every rAF frame forces a style/layout recalc — profiled at ~0.5 s
+    // main-thread self-time over a 63 s session. The displayed state
+    // changes rarely (navigate / splitscreen panel toggle), so the DOM
+    // is only re-sampled every _DOM_VIS_CHECK_FRAMES frames; the cached
+    // value serves the frames in between (worst-case transition latency
+    // ~10 frames ≈ 166 ms at 60 Hz — fine for a hide/show pause signal).
+    // Set _domVisSampledFrame to NaN to force a fresh sample on the next
+    // check (done on init, canvas replace, resize, and override-clear so
+    // deliberate transitions don't wait out the throttle window).
+    // NOTE those manual resets are LATENCY optimizations, not correctness
+    // requirements: the periodic re-sample runs every _DOM_VIS_CHECK_FRAMES
+    // frames regardless, so a visibility-affecting path that forgets to
+    // reset self-heals within ~10 frames — stale visibility can never be
+    // served indefinitely.
+    const _DOM_VIS_CHECK_FRAMES = 10;
+    let _domVisCached = false;
+    let _domVisSampledFrame = NaN;
     let animFrame = null;
     // Paused-render throttle (feedBack#654). The rAF loop runs
     // unconditionally and only gates on visibility + ready, never on
@@ -733,103 +751,121 @@ function createHighway() {
     // on the freshly-mounted canvas.
     let _currentCanvasContextType = '2d';
 
+    // One persistent bundle object per createHighway() instance —
+    // _makeBundle() mutates its fields in place each call instead of
+    // allocating a fresh ~35-field object per rAF frame (steady GC churn
+    // on weak hardware, ×N under splitscreen). Consequences for
+    // consumers: the bundle OBJECT's identity is stable across frames
+    // and carries no meaning; its field values are only valid for the
+    // duration of the current draw call. Array fields (`notes`,
+    // `chords`, `handShapes`, `chordTemplates`, ...) still swap
+    // reference whenever chart data changes — field-identity caches
+    // (e.g. highway_3d's merge caches) rely on that invariant.
+    const _bundleReused = {};
+
     function _makeBundle() {
         // Snapshot of current factory state passed to each renderer call.
-        // Arrays and songInfo are LIVE references, not copies — the bundle
-        // itself is rebuilt each frame but its `notes`, `chords`,
-        // `anchors`, `beats`, etc. point at closure state. Renderers
-        // MUST NOT mutate these; treat them as read-only. We don't
-        // Object.freeze or deep-copy for per-frame allocation cost reasons.
-        return {
-            // Timing
-            currentTime,
-            songInfo,
-            isReady: ready,
-            // True while the chart clock is actively advancing; false when
-            // audio is paused / stalled / mid-seek (setTime has kept getting
-            // the same t for > _CHART_MAX_INTERP_MS). This is the same
-            // predicate getTime() uses to decide raw-vs-interpolated, and the
-            // no-anchor boot state reads as not-playing — matching getTime()
-            // returning raw chartTime there. Renderers that run their own
-            // sub-frame clock (highway_3d's smoothNow) gate on this to fall
-            // back to raw instead of extrapolating forward against a frozen
-            // audio sample. Undefined on downlevel hosts → those renderers
-            // keep their own staleness-based fallback.
-            isPlaying: !Number.isNaN(_chartAnchorPerfNow)
-                && (performance.now() - _chartLastAdvanceAt) <= _CHART_MAX_INTERP_MS,
+        // Arrays and songInfo are LIVE references, not copies — the
+        // bundle's `notes`, `chords`, `anchors`, `beats`, etc. point at
+        // closure state. Renderers MUST NOT mutate these; treat them as
+        // read-only. We don't Object.freeze or deep-copy for per-frame
+        // cost reasons.
+        const b = _bundleReused;
+        // Timing
+        b.currentTime = currentTime;
+        b.songInfo = songInfo;
+        b.isReady = ready;
+        // True while the chart clock is actively advancing; false when
+        // audio is paused / stalled / mid-seek (setTime has kept getting
+        // the same t for > _CHART_MAX_INTERP_MS). This is the same
+        // predicate getTime() uses to decide raw-vs-interpolated, and the
+        // no-anchor boot state reads as not-playing — matching getTime()
+        // returning raw chartTime there. Renderers that run their own
+        // sub-frame clock (highway_3d's smoothNow) gate on this to fall
+        // back to raw instead of extrapolating forward against a frozen
+        // audio sample. Undefined on downlevel hosts → those renderers
+        // keep their own staleness-based fallback.
+        b.isPlaying = !Number.isNaN(_chartAnchorPerfNow)
+            && (performance.now() - _chartLastAdvanceAt) <= _CHART_MAX_INTERP_MS;
 
-            // Chart content (filter-aware — difficulty-filtered arrays
-            // preferred; raw arrays are the fallback when no ladder data).
-            notes: _filteredNotes !== null ? _filteredNotes : notes,
-            chords: _filteredChords !== null ? _filteredChords : chords,
-            anchors: _filteredAnchors !== null ? _filteredAnchors : anchors,
-            beats,
-            sections,
-            chordTemplates,
-            stringCount,
-            // Mirrors song_info tuning capo offsets (±semitones from the
-            // instrument’s standard open-string layout). Live reference.
-            tuning: songInfo?.tuning,
-            capo: songInfo?.capo,
-            lyrics,
-            lyricsSource,
-            toneChanges,
-            toneBase,
-            // Drum tab payload (or null when the active arrangement has
-            // no drum_tab). Live reference — renderers MUST treat as
-            // read-only. Plugins should prefer this over decoding the
-            // standard `notes` stream when present; absence is the
-            // signal to fall back to legacy MIDI-encoded drums.
-            drumTab,
+        // Chart content (filter-aware — difficulty-filtered arrays
+        // preferred; raw arrays are the fallback when no ladder data).
+        b.notes = _filteredNotes !== null ? _filteredNotes : notes;
+        b.chords = _filteredChords !== null ? _filteredChords : chords;
+        b.anchors = _filteredAnchors !== null ? _filteredAnchors : anchors;
+        b.beats = beats;
+        b.sections = sections;
+        b.chordTemplates = chordTemplates;
+        b.stringCount = stringCount;
+        // Mirrors song_info tuning capo offsets (±semitones from the
+        // instrument’s standard open-string layout). Live reference.
+        b.tuning = songInfo?.tuning;
+        b.capo = songInfo?.capo;
+        b.lyrics = lyrics;
+        b.lyricsSource = lyricsSource;
+        b.toneChanges = toneChanges;
+        b.toneBase = toneBase;
+        // Drum tab payload (or null when the active arrangement has
+        // no drum_tab). Live reference — renderers MUST treat as
+        // read-only. Plugins should prefer this over decoding the
+        // standard `notes` stream when present; absence is the
+        // signal to fall back to legacy MIDI-encoded drums.
+        b.drumTab = drumTab;
 
-            // Master-difficulty (feedBack#48)
-            mastery: _mastery,
-            hasPhraseData: !!(_phrases && _phrases.length > 0),
-            // When phrase data authored ANY handshape, respect the filtered
-            // list strictly (even when this difficulty leaves it empty) —
-            // otherwise low-mastery levels would surface arp hints that
-            // don't belong. Only fall back to the flat list when the
-            // phrase data carries no handshapes at all (common on DLC
-            // where handshapes ship on the arrangement root).
-            handShapes: (_filteredHandShapes !== null && _phrasesHaveHandShapes)
-                ? _filteredHandShapes
-                : handShapes,
+        // Master-difficulty (feedBack#48)
+        b.mastery = _mastery;
+        b.hasPhraseData = !!(_phrases && _phrases.length > 0);
+        // When phrase data authored ANY handshape, respect the filtered
+        // list strictly (even when this difficulty leaves it empty) —
+        // otherwise low-mastery levels would surface arp hints that
+        // don't belong. Only fall back to the flat list when the
+        // phrase data carries no handshapes at all (common on DLC
+        // where handshapes ship on the arrangement root).
+        b.handShapes = (_filteredHandShapes !== null && _phrasesHaveHandShapes)
+            ? _filteredHandShapes
+            : handShapes;
 
-            // Display flags
-            inverted: _inverted,
-            lefty: _lefty,
-            renderScale: _effectiveRenderScale(),
-            lyricsVisible: showLyrics,
-            // Teaching marks sd/ch overlay pref (§6.2.2) so custom renderers
-            // (e.g. the 3D highway) can mirror the 2D opt-in toggle. The fg
-            // finger-hint pref rides alongside (default on, independently hideable).
-            teachingMarksVisible: _showTeachingMarks,
-            fingerHintsVisible: _showFingerHints,
+        // Display flags
+        b.inverted = _inverted;
+        b.lefty = _lefty;
+        b.renderScale = _effectiveRenderScale();
+        b.lyricsVisible = showLyrics;
+        // Teaching marks sd/ch overlay pref (§6.2.2) so custom renderers
+        // (e.g. the 3D highway) can mirror the 2D opt-in toggle. The fg
+        // finger-hint pref rides alongside (default on, independently hideable).
+        b.teachingMarksVisible = _showTeachingMarks;
+        b.fingerHintsVisible = _showFingerHints;
 
-            // 2D-style helpers (renderers that don't need these can ignore).
-            // `fillTextUnmirrored` is deliberately NOT exposed here —
-            // the factory-level version writes to the default renderer's
-            // closure ctx, which is null for custom renderers. Renderers
-            // that need lefty-aware text should check `bundle.lefty` and
-            // apply the mirror transform themselves on their own context.
-            project,
-            fretX,
+        // 2D-style helpers (renderers that don't need these can ignore).
+        // `fillTextUnmirrored` is deliberately NOT exposed here —
+        // the factory-level version writes to the default renderer's
+        // closure ctx, which is null for custom renderers. Renderers
+        // that need lefty-aware text should check `bundle.lefty` and
+        // apply the mirror transform themselves on their own context.
+        b.project = project;
+        b.fretX = fretX;
+        // Windowed-iteration helpers (stable references): lower-bound
+        // binary searches so custom viz don't full-scan chart arrays per
+        // frame. lowerBoundT keys on `.t` (notes / chords); lowerBoundTime
+        // keys on `.time` (beats / anchors / sections).
+        b.lowerBoundT = bsearch;
+        b.lowerBoundTime = bsearchTime;
 
-            // Per-note judgment overlay (feedBack#254). Renderers call
-            // this per visible note / chord-note to find out whether a
-            // scorer (note_detect) has flagged it hit / actively-held /
-            // missed, so the gem itself can light up instead of relying
-            // on an overlay ring. Returns null when no provider is set
-            // or it reports nothing for this note; otherwise
-            // { state: 'hit'|'active'|'miss', alpha: 0..1, color: string|null }.
-            getNoteState: _noteState,   // stable reference — no per-frame allocation
-            // Lets custom renderers (e.g. highway_3d) tell "is a provider
-            // attached" apart from "no provider, getNoteState always
-            // returns null" — `getNoteState` always exists on the bundle
-            // so its presence alone isn't a useful "detect mode" signal.
-            // Renderers gate verdict-window cull / draw extensions on this.
-            getNoteStateProvider: _getNoteStateProvider, // stable — see above
-        };
+        // Per-note judgment overlay (feedBack#254). Renderers call
+        // this per visible note / chord-note to find out whether a
+        // scorer (note_detect) has flagged it hit / actively-held /
+        // missed, so the gem itself can light up instead of relying
+        // on an overlay ring. Returns null when no provider is set
+        // or it reports nothing for this note; otherwise
+        // { state: 'hit'|'active'|'miss', alpha: 0..1, color: string|null }.
+        b.getNoteState = _noteState;   // stable reference
+        // Lets custom renderers (e.g. highway_3d) tell "is a provider
+        // attached" apart from "no provider, getNoteState always
+        // returns null" — `getNoteState` always exists on the bundle
+        // so its presence alone isn't a useful "detect mode" signal.
+        // Renderers gate verdict-window cull / draw extensions on this.
+        b.getNoteStateProvider = _getNoteStateProvider; // stable — see above
+        return b;
     }
 
     const _defaultRenderer = {
@@ -1047,6 +1083,7 @@ function createHighway() {
         // suppress the first transition. Reset to null so the next
         // rAF tick re-emits unconditionally.
         _lastVisible = null;
+        _domVisSampledFrame = NaN; // fresh canvas → fresh DOM sample
         // Defensive notify for plugins / overlays that cache the
         // canvas element across events. Lazy lookups via
         // getElementById('highway') do not need this — they'll pick
@@ -1246,7 +1283,14 @@ function createHighway() {
     // hosts that need those use setVisible() instead.
     function _isHighwayVisible() {
         if (_visibleOverride !== null) return _visibleOverride;
-        return !!(canvas && canvas.offsetParent !== null);
+        // Throttled offsetParent read — see _DOM_VIS_CHECK_FRAMES above.
+        if (Number.isNaN(_domVisSampledFrame)
+            || ((_frameIdx - _domVisSampledFrame) | 0) >= _DOM_VIS_CHECK_FRAMES
+            || ((_frameIdx - _domVisSampledFrame) | 0) < 0) {
+            _domVisCached = !!(canvas && canvas.offsetParent !== null);
+            _domVisSampledFrame = _frameIdx;
+        }
+        return _domVisCached;
     }
 
     // Emit only on transition so renderer-side listeners aren't woken
@@ -1513,7 +1557,13 @@ function createHighway() {
     }
 
     function drawBeats(W, H) {
-        for (const beat of beats) {
+        // Window the beat scan — a long song carries thousands of beats
+        // and iterating (and projecting) all of them per frame was pure
+        // waste; project() culling stays as the safety net.
+        const lo = bsearchTime(beats, currentTime - 0.25);
+        const hi = bsearchTime(beats, currentTime + VISIBLE_SECONDS + 0.25);
+        for (let i = lo; i < hi; i++) {
+            const beat = beats[i];
             const tOff = beat.time - currentTime;
             const p = project(tOff);
             if (!p || p.scale < 0.06) continue;
@@ -2624,6 +2674,19 @@ function createHighway() {
         }
         return lo;
     }
+    // Lower-bound binary search for `.time`-keyed arrays (beats, anchors,
+    // sections) — bsearch/bsearchChords key on `.t` and would compare
+    // against undefined here. Exposed to custom viz as
+    // bundle.lowerBoundTime.
+    function bsearchTime(arr, time) {
+        let lo = 0, hi = arr.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if (arr[mid].time < time) lo = mid + 1;
+            else hi = mid;
+        }
+        return lo;
+    }
 
     // ── Chord rendering — chains, frames, fretline preview (feedBack#88) ──
     //
@@ -2956,6 +3019,7 @@ function createHighway() {
         init(canvasEl, container) {
             canvas = canvasEl;
             _resizeContainer = container || null;
+            _domVisSampledFrame = NaN; // new mount → fresh DOM sample
             // Size the canvas BEFORE installing the renderer so
             // _setRenderer's init/resize calls see the real dimensions
             // instead of the default 300x150 backing store. Otherwise
@@ -2997,6 +3061,9 @@ function createHighway() {
 
         resize() {
             if (!canvas) return;
+            // Layout just changed (window resize / container swap) —
+            // re-sample DOM visibility on the next check.
+            _domVisSampledFrame = NaN;
             let w, h;
             if (_resizeContainer) {
                 const rect = _resizeContainer.getBoundingClientRect();
@@ -3771,6 +3838,10 @@ function createHighway() {
         // rAF tick.
         setVisible(v) {
             _visibleOverride = (v === null || v === undefined) ? null : !!v;
+            // Clearing the override resumes DOM-based detection — force a
+            // fresh offsetParent sample so the resulting transition (if
+            // any) emits now, not after the throttle window.
+            if (_visibleOverride === null) _domVisSampledFrame = NaN;
             _emitVisibilityIfChanged();
         },
         // Snapshot of the current visibility state (the override if
@@ -3779,6 +3850,12 @@ function createHighway() {
         // can call this once to sync their initial state — the event
         // is transition-only and won't re-fire for late subscribers.
         isVisible() {
+            // Force a fresh DOM sample — this is a documented "live DOM
+            // check" for late subscribers seeding initial state, so it
+            // must not serve the rAF loop's throttled cache (up to
+            // ~166 ms stale). Called rarely; the layout-read cost that
+            // motivated the throttle only matters per-frame.
+            _domVisSampledFrame = NaN;
             return _isHighwayVisible();
         },
         getNotes() { return notes; },

static/index.html

@@ -24,6 +24,7 @@
     <script src="/static/capabilities.js"></script>
     <script src="/static/capabilities/library.js"></script>
     <script src="/static/capabilities/tuning.js"></script>
+    <script src="/static/capabilities/working-tuning.js"></script>
     <script src="/static/capabilities/audio-session.js"></script>
     <script src="/static/capabilities/audio-effects.js"></script>
     <script src="/static/capabilities/playback.js"></script>
@@ -71,7 +72,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) ══════════════════════════════════════════ -->
     <div id="home" class="screen active">

static/v3/audio-routing.js

@@ -71,7 +71,7 @@
             '<div class="flex items-center gap-2 text-xs text-fb-textDim mb-3">' +
             '<svg class="w-4 h-4 text-cyan-400" fill="none" stroke="currentColor" stroke-width="2" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" d="M9 18V5l12-2v13M9 13l12-2"/><circle cx="6" cy="18" r="3"/><circle cx="18" cy="16" r="3"/></svg>' +
             '<span>Audio Routing</span></div>' +
-            '<div class="flex items-center gap-2 text-[11px] text-fb-textDim">' +
+            '<div class="flex items-center gap-2 text-[0.6875rem] text-fb-textDim">' +
             dot(st.inputAvailable) + '<span>Input</span>' +
             '<span class="flex-1 border-t border-dashed border-fb-border/70"></span>' +
             dot(st.effectActive) + '<span>VST/NAM/IR</span>' +

static/v3/badges.js

@@ -25,6 +25,13 @@
     // Tuning names per instrument key (e.g. 'guitar-6', 'bass-4'), loaded from
     // GET /api/tunings. Falls back to empty arrays until the fetch resolves.
     let _tuningsByKey = {};
+    // Last instrument-coverage report for the current song (from the tuner plugin) —
+    // drives a passive "different tuning" cue on the tuner badge. null = covered /
+    // unknown / off the player.
+    let _lastCoverageReport = null;
+    // Monotonic token so a slow coverage fetch can't restore a stale cue after a newer
+    // song started loading / we left the player. Bumped on every refresh and clear.
+    let _coverageCueToken = 0;
     function _tuningsForKey(key) { return Object.keys(_tuningsByKey[key] || {}); }
     function _tuningsForInstrument(instrument, string_count) {
         return _tuningsForKey(instrument + '-' + string_count);
@@ -53,6 +60,52 @@
         return typeof settings.tuning === 'string' ? settings.tuning : 'Custom';
     }
 
+    // The SELECTED instrument's live working tuning (host `workingTuning` capability).
+    // Feature-detected: returns null when the host doesn't expose it, so the card
+    // quietly falls back to the profile tuning. `offsets` are named via the shared
+    // displayTuningName resolver; "home" = still in the profile/default tuning.
+    function workingTuningInfo() {
+        var wt = window.feedBack && window.feedBack.workingTuning;
+        var st = wt && typeof wt.get === 'function' ? wt.get() : null;
+        if (!st) return null;
+        var offsets = Array.isArray(st.offsets) ? st.offsets : null;
+        var nameFor = window.displayTuningName
+            || (window.feedBack && window.feedBack.displayTuningName);
+        // Resolve BOTH the home tuning and the working tuning through the SAME namer so
+        // "home?" is a like-for-like comparison — comparing a raw settings string ('Custom'
+        // / 'E Standard') against a from-offsets name would mislabel a real home tuning.
+        var homeLabel = (typeof nameFor === 'function')
+            ? (nameFor(typeof settings.tuning === 'string' ? settings.tuning : null,
+                Array.isArray(settings.tuning) ? settings.tuning : null) || tuningLabel())
+            : tuningLabel();
+        var label = (offsets && typeof nameFor === 'function') ? nameFor(null, offsets) : homeLabel;
+        return {
+            label: label,
+            short: label.replace(/ Standard\b/, ' Std').replace(/Custom Tuning/, 'Custom'),
+            // Home = no explicit working offsets, OR the working tuning names the same as
+            // the profile's home tuning (both via `nameFor`, so the compare is consistent).
+            isHome: !offsets || label === homeLabel,
+            provenance: st.provenance === 'verified' ? 'verified' : 'assumed',
+        };
+    }
+
+    // Honesty glyph: a hollow diamond for an assumed tuning, a filled one for a
+    // per-string mic-verified tuning (see the workingTuning provenance flag).
+    function provenanceGlyph(p) {
+        return p === 'verified'
+            ? '<span title="Verified by a per-string mic check" class="text-emerald-400">&#9670;</span>'
+            : '<span title="Assumed — not mic-verified" class="text-fb-textDim">&#9671;</span>';
+    }
+
+    // Tell the host which instrument is now selected, so workingTuning.get()
+    // surfaces THIS instrument's own remembered tuning. No-op without the capability.
+    function setWorkingInstrument(inst, sc) {
+        var wt = window.feedBack && window.feedBack.workingTuning;
+        if (wt && typeof wt.setCurrentInstrument === 'function') {
+            try { wt.setCurrentInstrument(inst, sc); } catch (_) { /* noop */ }
+        }
+    }
+
     let settings = { instrument: 'guitar', string_count: 6, tuning: 'Standard', reference_pitch: 440 };
 
     async function loadTunings() {
@@ -122,13 +175,14 @@
                 accepted = !(body && body.error);
             }
         } catch (e) { /* non-fatal — leave settings unchanged */ }
-        if (!accepted) return;
+        if (!accepted) return false;
         Object.assign(settings, patch);
         if (sm && sm.emit) sm.emit('instrument:changed', {
             instrument: settings.instrument, stringCount: settings.string_count, tuning: settings.tuning,
         });
         pushToTuner();
         renderTuner(); // reflect new tuning on the tuner card
+        return true;
     }
 
     // Drive the tuner plugin's instrument + tuning from the selection.
@@ -242,7 +296,7 @@
             '<div class="shrink-0 flex flex-col gap-[3px] items-center justify-center">' + meter + '</div>' +
             '<div class="min-w-0 text-white text-center leading-none">' +
             '<div data-tuner-note class="text-2xl font-black italic tracking-tighter leading-none">' + esc(initNote) + '</div>' +
-            '<div data-tuner-hz class="text-[9px] text-gray-400 mt-0.5 tracking-wider truncate">' + hz + 'hz</div>' +
+            '<div data-tuner-hz class="text-[0.5625rem] text-gray-400 mt-0.5 tracking-wider truncate">' + hz + 'hz</div>' +
             '</div></button>' +
             '</div>';
         host.querySelector('[data-open-tuner]').addEventListener('click', (e) => {
@@ -257,6 +311,52 @@
             openTuner();
         });
         _applyFrame(_lastFrame);
+        _applyCoverageCue(_lastCoverageReport);
+    }
+
+    // Passive "different tuning" cue on the tuner badge: an amber ring + a tooltip
+    // naming the retune (e.g. "B→A"). The diff comes from the tuner plugin's coverage
+    // report; an absent plugin or a covered song → no cue. CSS-free (inline ring +
+    // native title) so it needs no Tailwind rebuild, and it never auto-opens the
+    // panel — it's advisory; the user taps the badge to tune.
+    function _applyCoverageCue(report) {
+        const btn = document.querySelector('#v3-badge-tuner [data-open-tuner]');
+        if (!btn) return;
+        const needs = !!(report && !report.covered);
+        btn.style.boxShadow = needs ? '0 0 0 2px #fbbf24' : '';
+        if (!needs) { btn.title = 'Open tuner'; return; }
+        const summary = report.cantCover ? 'a different instrument'
+            : (report.retune && report.retune.length)
+                ? report.retune.map((d) => d.from + '→' + d.to).join(', ')
+                : 'the reference pitch';
+        btn.title = 'This song needs a different tuning — retune ' + summary + '. Click to tune.';
+    }
+
+    // A coverage report only drives the cue when it carries an actual signal: covered
+    // (clears the ring) or a nameable mismatch (retune / reference / cantCover). The
+    // plugin returns a conservative all-false report on a fetch hiccup / missing data —
+    // that's "unknown", NOT "needs retune", so collapse it to null (no cue) rather than
+    // painting an amber "retune the reference pitch" ring with no evidence.
+    function _meaningfulReport(report) {
+        if (!report) return null;
+        if (report.covered) return report;
+        if (report.cantCover || report.reference || (report.retune && report.retune.length)) return report;
+        return null;
+    }
+
+    async function _refreshCoverageCue() {
+        const myToken = ++_coverageCueToken;
+        const songInfo = window.highway && window.highway.getSongInfo && window.highway.getSongInfo();
+        const api = window._tunerAutoOpen;
+        if (!songInfo || !api || typeof api.coverageReport !== 'function') {
+            _lastCoverageReport = null; _applyCoverageCue(null); return;
+        }
+        let report = null;
+        try { report = await api.coverageReport(songInfo); }
+        catch (_e) { report = null; }
+        if (myToken !== _coverageCueToken) return;   // superseded by a newer song / a clear
+        _lastCoverageReport = _meaningfulReport(report);
+        _applyCoverageCue(_lastCoverageReport);
     }
 
     // ── Instrument selector card (Stitch RightInstrumentSelector) ──────────--
@@ -290,26 +390,41 @@
     function renderInstrument() {
         const host = document.getElementById('v3-badge-instrument');
         if (!host) return;
+        const wt = workingTuningInfo();
         host.innerHTML =
             '<div id="v3-instrument-wrap" class="relative">' +
-            '<button type="button" data-inst-toggle title="Instrument: ' + esc(settings.string_count + '-str ' + tuningLabel()) + '" ' +
-            'class="bg-fb-card border border-fb-border/50 rounded-2xl h-[92px] w-16 flex flex-col items-center justify-center gap-2 hover:ring-1 hover:ring-fb-primary/40 transition">' +
+            '<button type="button" data-inst-toggle title="Instrument: ' + esc(settings.string_count + '-str ' + (wt ? wt.label : tuningLabel())) + '" ' +
+            'class="bg-fb-card border border-fb-border/50 rounded-2xl h-[92px] w-16 flex flex-col items-center justify-center gap-1.5 hover:ring-1 hover:ring-fb-primary/40 transition">' +
             guitarIcon +
+            // Live working-tuning label: dim while you're still in your home tuning,
+            // amber once you've retuned. Omitted if the host doesn't expose
+            // workingTuning (feature-detect → the card looks exactly as before).
+            (wt ? '<span class="text-[0.5625rem] leading-none font-semibold max-w-full truncate px-0.5 ' +
+                (wt.isHome ? 'text-fb-textDim' : 'text-amber-400') + '">' + esc(wt.short) + '</span>' : '') +
             '<svg class="w-4 h-4 text-white" fill="none" stroke="currentColor" stroke-width="3" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" d="m19.5 8.25-7.5 7.5-7.5-7.5"/></svg>' +
             '</button>' +
             '<div data-inst-menu class="hidden absolute right-0 mt-2 w-60 bg-fb-card border border-fb-border/50 rounded-xl shadow-xl p-3 z-50 space-y-3">' +
+            // "Now in" banner + one-tap back-to-default — shown only once you've
+            // retuned off your home tuning (workingTuning present and not home).
+            ((wt && !wt.isHome)
+                ? '<div class="flex items-center justify-between gap-2 pb-1 border-b border-fb-border/40">' +
+                  '<div class="min-w-0"><div class="text-[0.625rem] uppercase tracking-wider text-fb-textDim">Now in</div>' +
+                  '<div class="text-xs font-semibold text-amber-400 truncate flex items-center gap-1">' + esc(wt.label) + ' ' + provenanceGlyph(wt.provenance) + '</div></div>' +
+                  '<button type="button" data-inst-reset title="Reset this instrument to its home tuning" class="shrink-0 text-[0.6875rem] text-fb-textDim hover:text-fb-text border border-fb-border/40 hover:border-fb-border/70 rounded-md px-2 py-1 transition-colors">Back to default</button>' +
+                  '</div>'
+                : '') +
             instRow('Instrument', ['guitar', 'bass'].map((v) =>
                 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('')) +
-            '<div><div class="text-[10px] uppercase tracking-wider text-fb-textDim mb-1">Tuning</div>' +
+            '<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
             // disabled, selected 'Custom' entry so the dropdown reflects reality
             // (picking a named tuning still works and replaces the custom one).
             (typeof settings.tuning === 'string' ? '' : '<option selected disabled>Custom</option>') +
             _tuningsForInstrument(settings.instrument, settings.string_count).map((t) => '<option' + (t === settings.tuning ? ' selected' : '') + '>' + esc(t) + '</option>').join('') + '</select></div>' +
-            '<div><div class="flex justify-between text-[10px] uppercase tracking-wider text-fb-textDim mb-1"><span>Reference pitch</span><span data-ref-val>' + settings.reference_pitch + ' Hz</span></div>' +
+            '<div><div class="flex justify-between text-[0.625rem] uppercase tracking-wider text-fb-textDim mb-1"><span>Reference pitch</span><span data-ref-val>' + settings.reference_pitch + ' Hz</span></div>' +
             '<input data-inst-ref type="range" min="430" max="450" step="1" value="' + settings.reference_pitch + '" class="w-full slider-input"></div>' +
             '</div></div>';
 
@@ -335,23 +450,35 @@
             // unsupported instrument+tuning combo.
             const newSc = counts.includes(settings.string_count) ? settings.string_count : counts[0];
             const tunings = _tuningsForInstrument(v, newSc);
-            await saveSettings({
+            const ok = await saveSettings({
                 instrument: v,
                 string_count: newSc,
                 tuning: tunings.includes(settings.tuning) ? settings.tuning : (tunings[0] || settings.tuning),
             });
+            // Only move the working-tuning context once the switch was actually persisted —
+            // otherwise the selector stays on the old instrument while the card shows the
+            // new one's tuning (settings and workingTuning desync on a rejected save).
+            if (ok) setWorkingInstrument(v, newSc);   // surface THIS instrument's own working tuning
             renderInstrument(); keepOpen();
         }));
         menu.querySelectorAll('[data-pill="strings"]').forEach((b) => b.addEventListener('click', async () => {
-            await saveSettings({ string_count: Number(b.getAttribute('data-val')) }); renderInstrument(); keepOpen();
+            await saveSettings({ string_count: Number(b.getAttribute('data-val')) });
+            setWorkingInstrument(settings.instrument, settings.string_count);
+            renderInstrument(); keepOpen();
         }));
         menu.querySelector('[data-inst-tuning]').addEventListener('change', (e) => saveSettings({ tuning: e.target.value }));
         const ref = menu.querySelector('[data-inst-ref]');
         ref.addEventListener('input', (e) => { menu.querySelector('[data-ref-val]').textContent = e.target.value + ' Hz'; });
         ref.addEventListener('change', (e) => saveSettings({ reference_pitch: Number(e.target.value) }));
+        const resetBtn = menu.querySelector('[data-inst-reset]');
+        if (resetBtn) resetBtn.addEventListener('click', () => {
+            const wtCap = window.feedBack && window.feedBack.workingTuning;
+            if (wtCap && typeof wtCap.resetToDefault === 'function') wtCap.resetToDefault();
+            renderInstrument(); keepOpen();
+        });
     }
     function instRow(label, inner) {
-        return '<div><div class="text-[10px] uppercase tracking-wider text-fb-textDim mb-1">' + label + '</div><div class="flex flex-wrap gap-1">' + inner + '</div></div>';
+        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>';
     }
     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 ' +
@@ -362,6 +489,11 @@
 
     async function boot() {
         await Promise.all([loadTunings(), loadSettings()]);
+        // NB: we deliberately do NOT call setWorkingInstrument() here. The host seeds its
+        // current instrument from the same /api/settings on boot and emits
+        // working-tuning-changed on hydration (which re-renders this card), so the card
+        // aligns without us pre-touching the state — calling setCurrentInstrument() early
+        // would set the capability's `_touched` flag and suppress that seed.
         renderInstrument();
         renderTuner();
         pushToTuner(); // sync the tuner to the persisted selection on load
@@ -374,6 +506,16 @@
                 await loadTunings();
                 renderInstrument();
             });
+            // Passive coverage cue: recompute when a song is ready; clear when a new
+            // song starts loading or we leave the player screen.
+            sm.on('song:ready', () => { _refreshCoverageCue(); });
+            sm.on('song:loading', () => { _coverageCueToken++; _lastCoverageReport = null; _applyCoverageCue(null); });
+            sm.on('screen:changed', (e) => {
+                if (!e || !e.detail || e.detail.id !== 'player') { _coverageCueToken++; _lastCoverageReport = null; _applyCoverageCue(null); }
+            });
+            // The tuner (or a reset) changed the live working tuning → re-render the
+            // card label + the "Now in" banner. No-op if the host lacks the capability.
+            sm.on('working-tuning-changed', () => renderInstrument());
         }
     }
     if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', boot, { once: true });

static/v3/card-actions-core.js

@@ -23,11 +23,18 @@
     reg.register({
         id: 'core.edit-metadata',
         pluginId: 'core',
-        label: 'Edit metadata',
+        label: 'Details',
         placement: 'menu',
         order: 10,
         applies: (song) => !!(song && song.filename),
         run: (song) => {
+            // Prefer the v3 Details drawer (identity + personal difficulty / tags
+            // / notes); fall back to the legacy edit-metadata modal where the v3
+            // songs screen hasn't defined the opener (e.g. an older shell).
+            if (typeof window.__fbOpenSongDetails === 'function') {
+                window.__fbOpenSongDetails(song);
+                return;
+            }
             if (typeof window.openEditModal !== 'function') return;
             window.openEditModal({
                 f: song.filename, t: song.title || '', a: song.artist || '',

static/v3/dashboard.js

@@ -67,7 +67,7 @@
         const l = fmtName(song);
         if (!l) return '';
         const c = l === 'FEEDPAK' ? 'bg-fb-primary text-white' : 'bg-black/70 text-fb-textDim';
-        return '<span class="absolute bottom-0 left-0 ' + c + ' text-[9px] font-bold px-1.5 py-0.5 rounded-tr-md tracking-wide">' + l + '</span>';
+        return '<span class="absolute bottom-0 left-0 ' + c + ' text-[0.5625rem] font-bold px-1.5 py-0.5 rounded-tr-md tracking-wide">' + l + '</span>';
     }
     // Inline pill for the hero (Pick/Continue) card, where the art is text-overlaid
     // and a corner badge would collide — sits next to the card's label instead.
@@ -75,7 +75,7 @@
         const l = fmtName(song);
         if (!l) return '';
         const c = l === 'FEEDPAK' ? 'bg-fb-primary/20 text-fb-primary' : 'bg-fb-card/80 text-fb-textDim';
-        return '<span class="' + c + ' text-[9px] font-bold px-1.5 py-0.5 rounded tracking-wide shrink-0">' + l + '</span>';
+        return '<span class="' + c + ' text-[0.5625rem] font-bold px-1.5 py-0.5 rounded tracking-wide shrink-0">' + l + '</span>';
     }
 
     // ── Continue-Playing resume ──────────────────────────────────────────---

static/v3/index.html

@@ -60,6 +60,24 @@
             } catch (_) { /* file:// or sandboxed iframe */ }
         })();
     </script>
+    <!-- Interface size (Accessibility): apply the saved UI scale to the root
+         font-size BEFORE any stylesheet paints, so there is no flash-of-reflow
+         on load. Mirrors capabilities/interface-scale.js, which is the
+         authoritative owner and re-applies once it parses. Relative % (never a
+         px literal) so a raised browser/OS base font size is respected. -->
+    <script>
+        (function () {
+            try {
+                var raw = localStorage.getItem('v3-interface-scale');
+                if (raw == null) return;
+                var v = Math.min(1.5, Math.max(0.85, parseFloat(raw)));
+                if (!isFinite(v) || Math.abs(v - 1) < 0.001) return;
+                var el = document.documentElement;
+                el.style.setProperty('--fb-scale', String(v));
+                el.style.fontSize = (v * 100).toFixed(2) + '%';
+            } catch (_) { /* file:// or private mode */ }
+        })();
+    </script>
     <!-- fee[dB]ack mark (the [dB] motif). SVG primary, PNG fallback. -->
     <link rel="icon" type="image/svg+xml" href="/static/v3/brand/favicon.svg">
     <link rel="icon" type="image/png" sizes="32x32" href="/static/v3/brand/favicon-32.png">
@@ -87,6 +105,7 @@
     <script src="/static/capabilities.js"></script>
     <script src="/static/capabilities/library.js"></script>
     <script src="/static/capabilities/tuning.js"></script>
+    <script src="/static/capabilities/working-tuning.js"></script>
     <script src="/static/capabilities/audio-session.js"></script>
     <script src="/static/capabilities/audio-effects.js"></script>
     <script src="/static/capabilities/playback.js"></script>
@@ -95,6 +114,7 @@
     <script src="/static/capabilities/visualization.js"></script>
     <script src="/static/capabilities/note-detection.js"></script>
     <script src="/static/capabilities/midi-input.js"></script>
+    <script src="/static/capabilities/interface-scale.js"></script>
 </head>
 <body class="h-screen flex overflow-hidden bg-fb-sidebar text-fb-text font-display">
 
@@ -358,6 +378,7 @@
                  panels (manifest settings.category routes the others). -->
             <div class="fb-tabbar" id="settings-tabbar">
                 <button type="button" class="fb-tab" data-tab="gameplay">Gameplay</button>
+                <button type="button" class="fb-tab" data-tab="accessibility">Accessibility</button>
                 <button type="button" class="fb-tab" data-tab="audio">Audio</button>
                 <button type="button" class="fb-tab" data-tab="graphics">Graphics</button>
                 <button type="button" class="fb-tab" data-tab="keybinds">Keybinds</button>
@@ -539,6 +560,40 @@
                 </div>
             </div>
 
+            <!-- ══ ACCESSIBILITY ═══════════════════════════════════════════ -->
+            <div class="fb-tabpanel" data-tab="accessibility">
+                <div class="fb-tabpanel-head"><h3>Accessibility</h3></div>
+                <div class="fb-srows">
+                    <!-- Interface size -->
+                    <div class="fb-srow fb-srow-stack">
+                        <div style="display:flex; align-items:center; gap:1rem;">
+                            <span class="fb-srow-icon"><svg fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 7V5a1 1 0 011-1h14a1 1 0 011 1v2M9 20h6M12 4v16"/></svg></span>
+                            <div class="fb-srow-main">
+                                <div class="fb-srow-title">Interface size</div>
+                                <div class="fb-srow-desc">Make the app&rsquo;s menus, buttons and text larger or smaller. This changes the <strong>app interface</strong> &mdash; not the notes on the note highway (set those under <strong>Graphics</strong>). On desktop you can also press <strong>Ctrl&nbsp;+</strong> / <strong>Ctrl&nbsp;&minus;</strong> to zoom the whole window.</div>
+                            </div>
+                        </div>
+                        <div class="fb-seg" id="setting-interface-size" role="group" aria-label="Interface size">
+                            <button type="button" class="fb-seg-btn" data-scale="0.90" aria-pressed="false" onclick="window.feedBack.scale.set(0.90)">Small</button>
+                            <button type="button" class="fb-seg-btn" data-scale="1.00" aria-pressed="false" onclick="window.feedBack.scale.set(1.00)">Medium</button>
+                            <button type="button" class="fb-seg-btn" data-scale="1.15" aria-pressed="false" onclick="window.feedBack.scale.set(1.15)">Large</button>
+                            <button type="button" class="fb-seg-btn" data-scale="1.30" aria-pressed="false" onclick="window.feedBack.scale.set(1.30)">Extra&nbsp;Large</button>
+                        </div>
+                        <p class="fb-srow-desc" style="margin-top:.55rem;">Larger sizes are recommended for large or high-resolution displays.</p>
+                        <details class="fb-finetune">
+                            <summary>Fine-tune size</summary>
+                            <div class="fb-finetune-body">
+                                <input type="range" id="setting-interface-size-slider" min="85" max="150" step="5" value="100"
+                                    oninput="window.feedBack.scale.set(this.value / 100, { persist: false })"
+                                    onchange="window.feedBack.scale.set(this.value / 100)" class="fb-srow-wide slider-input"
+                                    aria-label="Interface size percent">
+                                <span class="fb-seg-val"><span id="setting-interface-size-val">100</span>%</span>
+                            </div>
+                        </details>
+                    </div>
+                </div>
+            </div>
+
             <!-- ══ AUDIO ═══════════════════════════════════════════════════ -->
             <div class="fb-tabpanel" data-tab="audio">
                 <div class="fb-tabpanel-head"><h3>Audio Settings</h3></div>
@@ -680,6 +735,66 @@
                             <span id="rescan-status" class="text-xs text-gray-500"></span>
                         </div>
                     </div>
+                    <!-- Metadata matching (P8 — wired by static/v3/match-review.js) -->
+                    <div class="fb-srow fb-srow-stack">
+                        <div class="fb-srow-main">
+                            <div class="fb-srow-title">Metadata matching</div>
+                            <div class="fb-srow-desc">Matches your charts against MusicBrainz in the background to tidy names, years and genres — display only, your files are never modified. Matches at or above the confidence level apply automatically; the rest wait in the library's review queue. Turning this off never disables manual match fixes.</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="enrich-enabled" checked class="rounded border-gray-600 bg-dark-700 text-accent"> Match songs automatically</label>
+                            <label class="flex items-center gap-2">Auto-apply confidence
+                                <select id="enrich-threshold" class="bg-dark-700 border border-gray-800 rounded-xl px-2 py-1.5 text-xs text-gray-300 outline-none">
+                                    <option value="0.85">85% — more auto-matches</option>
+                                    <option value="0.9" selected>90% (recommended)</option>
+                                    <option value="0.95">95% — cautious</option>
+                                    <option value="1.01">Always review</option>
+                                </select>
+                            </label>
+                        </div>
+                        <!-- R1 scraper options: sources (who may be contacted) ×
+                             auto-apply fields (what a confident match fills in). -->
+                        <div class="fb-srow-wide mb-1">
+                            <div class="text-[10px] uppercase tracking-wide text-gray-500 mb-1">Sources</div>
+                            <div class="grid grid-cols-2 gap-2 text-xs text-gray-400">
+                                <label class="flex items-center gap-2"><input type="checkbox" id="enrich-src-musicbrainz" checked class="rounded border-gray-600 bg-dark-700 text-accent"> MusicBrainz — names, years, genres</label>
+                                <label class="flex items-center gap-2"><input type="checkbox" id="enrich-src-caa" checked class="rounded border-gray-600 bg-dark-700 text-accent"> Cover Art Archive — album covers</label>
+                            </div>
+                        </div>
+                        <div class="fb-srow-wide mb-1">
+                            <div class="text-[10px] uppercase tracking-wide text-gray-500 mb-1">Auto-apply</div>
+                            <div class="grid grid-cols-4 gap-2 text-xs text-gray-400">
+                                <label class="flex items-center gap-2"><input type="checkbox" id="enrich-apply-names" checked class="rounded border-gray-600 bg-dark-700 text-accent"> Names</label>
+                                <label class="flex items-center gap-2"><input type="checkbox" id="enrich-apply-year" checked class="rounded border-gray-600 bg-dark-700 text-accent"> Year</label>
+                                <label class="flex items-center gap-2"><input type="checkbox" id="enrich-apply-genres" checked class="rounded border-gray-600 bg-dark-700 text-accent"> Genres</label>
+                                <label class="flex items-center gap-2"><input type="checkbox" id="enrich-apply-art" checked class="rounded border-gray-600 bg-dark-700 text-accent"> Cover art</label>
+                            </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>
+                        <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">
+                                    <option value="missing_first" selected>Missing info first</option>
+                                    <option value="artist">Artist A–Z</option>
+                                    <option value="recent">Recently added</option>
+                                </select>
+                            </label>
+                        </div>
+                        <div class="fb-srow-control">
+                            <button id="enrich-match-now" class="bg-dark-600 hover:bg-dark-500 px-5 py-2.5 rounded-xl text-sm text-gray-300 transition">Match Now</button>
+                            <span id="enrich-status" class="text-xs text-gray-500"></span>
+                        </div>
+                    </div>
+                    <!-- Writing to your files (R4a gap-fill + R4b overwrite — wired by static/v3/match-review.js) -->
+                    <div class="fb-srow fb-srow-stack">
+                        <div class="fb-srow-main">
+                            <div class="fb-srow-title">Writing to your files</div>
+                            <div class="fb-srow-desc">"Write missing info to file" in a song's details only ever adds fields the pack is missing. Overwriting additionally lets a match you confirmed replace existing fields — always per-field, never automatic.</div>
+                        </div>
+                        <div class="fb-srow-wide">
+                            <label class="flex items-center gap-2 text-xs text-gray-400"><input type="checkbox" id="allow-pack-overwrite" class="rounded border-gray-600 bg-dark-700 text-accent"> Allow overwriting existing pack fields — per-field confirmation, a backup of the original is always kept</label>
+                        </div>
+                    </div>
                     <!-- Backup -->
                     <div class="fb-srow fb-srow-stack">
                         <div class="fb-srow-main">
@@ -1117,14 +1232,19 @@
     <script src="/static/v3/pedal-cables.js"></script>
     <script src="/static/v3/plugins-page.js"></script>
     <script src="/static/v3/card-actions-core.js"></script>
+    <!-- Before songs.js: the songs toolbar calls the match-review chip hook
+         on build, so the module must already be registered. -->
+    <script src="/static/v3/match-review.js"></script>
     <script src="/static/v3/songs.js"></script>
     <script src="/static/v3/lessons.js"></script>
     <script src="/static/v3/dashboard.js"></script>
     <script src="/static/v3/settings.js"></script>
+    <script src="/static/v3/interface-size-ui.js"></script>
     <!-- First-run home tour: spotlights the home cards via the shared tour
          engine (tour-engine.js, loaded above). Auto-runs once after onboarding
          (triggered from profile.js finish()); replayable from the "?" menu. -->
     <script src="/static/v3/onboarding-tour.js"></script>
+    <script src="/static/v3/interface-size-nudge.js"></script>
     <script src="/static/v3/feedbarcade.js"></script>
     <script src="/static/v3/player-chrome.js"></script>
     <script>

static/v3/interface-size-nudge.js

@@ -0,0 +1,79 @@
+// v3 first-run "Interface size" nudge.
+//
+// The Accessibility → Interface size control is the primary discovery path, but
+// the exact person who needs it — someone on a large, low-DPI display (e.g. a
+// 32" 1440p panel with no OS scaling) — is the one least likely to go hunting
+// for it. So, ONCE, for that specific display profile, surface a gentle,
+// dismissible toast that deep-links to the control. Never fires if the user has
+// already touched the setting, on smaller/high-DPI displays, or more than once.
+//
+// Plain non-module script; degrades to a no-op without the bus, fbNotify, or DOM.
+(function () {
+    'use strict';
+
+    var SEEN_KEY = 'v3-interface-size-nudged';
+    var SCALE_KEY = 'v3-interface-scale';
+
+    function alreadyHandled() {
+        try {
+            return localStorage.getItem(SEEN_KEY) === '1' || localStorage.getItem(SCALE_KEY) != null;
+        } catch (_) { return true; }
+    }
+
+    // The target profile: a physically large viewport rendered near 1:1 (so the
+    // OS isn't already enlarging things). This is the eye-strain case.
+    function isLargeLowDpiDisplay() {
+        var w = window.innerWidth || 0;
+        var dpr = window.devicePixelRatio || 1;
+        return w >= 1800 && dpr <= 1.25;
+    }
+
+    // Don't interrupt a first-run modal (e.g. profile onboarding). If one is up,
+    // leave the flag UNSET so the nudge gets another chance on a later launch.
+    function aModalIsOpen() {
+        var dialogs = document.querySelectorAll('[role="dialog"], .fixed.inset-0');
+        for (var i = 0; i < dialogs.length; i++) {
+            var el = dialogs[i];
+            if (el.offsetParent !== null && el.getClientRects().length) return true;
+        }
+        return false;
+    }
+
+    function openSetting() {
+        try {
+            if (typeof window.showScreen === 'function') window.showScreen('settings');
+            document.querySelectorAll('#settings-tabbar .fb-tab').forEach(function (b) {
+                if (b.dataset.tab === 'accessibility') b.click();
+            });
+        } catch (_) { /* noop */ }
+    }
+
+    function maybeNudge() {
+        if (alreadyHandled()) return;
+        if (!isLargeLowDpiDisplay()) return;
+        if (!window.fbNotify || typeof window.fbNotify.show !== 'function') return;
+        if (aModalIsOpen()) return; // try again next launch
+
+        try { localStorage.setItem(SEEN_KEY, '1'); } catch (_) { /* private mode */ }
+
+        var card = window.fbNotify.show({
+            title: 'Text looking small?',
+            message: 'Make the menus and text larger — tap to open Interface size.',
+            icon: '🔍',
+            accent: '#0ea5e9',
+            durationMs: 9000,
+        });
+        if (card && card.addEventListener) card.addEventListener('click', openSetting);
+    }
+
+    function start() {
+        // Let the app settle (boot, any onboarding) before offering the nudge.
+        setTimeout(maybeNudge, 4000);
+    }
+
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', start, { once: true });
+    } else {
+        start();
+    }
+})();

static/v3/interface-size-ui.js

@@ -0,0 +1,55 @@
+// v3 Settings → Accessibility: keeps the "Interface size" control in sync with
+// the host `feedBack.scale` capability. The buttons/slider WRITE via inline
+// `feedBack.scale.set(...)`; this module only REFLECTS current state (active
+// preset, slider position, % readout) so the control mirrors the live value on
+// load, on every change, and each time Settings is opened.
+//
+// Plain non-module script, matching the rest of static/v3/*. Null-guarded so it
+// no-ops on the classic v2 page (which has no Accessibility panel).
+(function () {
+    'use strict';
+
+    function sync(state) {
+        if (!state) {
+            var cap = window.feedBack && window.feedBack.scale;
+            state = cap && typeof cap.get === 'function' ? cap.get() : null;
+        }
+        if (!state) return;
+
+        var seg = document.getElementById('setting-interface-size');
+        if (seg) {
+            seg.querySelectorAll('.fb-seg-btn').forEach(function (b) {
+                var on = Math.abs(parseFloat(b.dataset.scale) - state.value) < 0.001;
+                b.classList.toggle('active', on);
+                b.setAttribute('aria-pressed', on ? 'true' : 'false');
+            });
+        }
+        var slider = document.getElementById('setting-interface-size-slider');
+        if (slider && document.activeElement !== slider) {
+            slider.value = String(Math.round(state.value * 100));
+        }
+        var val = document.getElementById('setting-interface-size-val');
+        if (val) val.textContent = String(Math.round(state.value * 100));
+    }
+
+    if (window.feedBack && typeof window.feedBack.on === 'function') {
+        // Fires on every set() and once on load. The bus delivers a CustomEvent,
+        // so we ignore the arg and read the authoritative value via sync() → get().
+        window.feedBack.on('scale:changed', function () { sync(); });
+        // Re-sync when the user opens Settings (the panel may have re-rendered).
+        window.feedBack.on('screen:changed', function (e) {
+            var id = e && (e.detail ? e.detail.id : e.id);
+            if (id === 'settings') sync();
+        });
+    }
+    // Settings markup is static, but re-sync when settings.js signals it wired.
+    document.addEventListener('v3:settings-rendered', function () { sync(); });
+
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', function () { sync(); }, { once: true });
+    } else {
+        sync();
+    }
+
+    window.feedBackInterfaceSize = { sync: sync };
+})();

static/v3/lessons.js

@@ -56,8 +56,8 @@
         const shown = arr.slice(0, max || 6);
         const extra = arr.length - shown.length;
         let html = shown.map((t) =>
-            '<span class="text-[10px] uppercase tracking-wider text-fb-textDim bg-black/30 border border-fb-border/50 rounded px-1.5 py-0.5">' + esc(t) + '</span>').join('');
-        if (extra > 0) html += '<span class="text-[10px] text-fb-textDim">+' + extra + '</span>';
+            '<span class="text-[0.625rem] uppercase tracking-wider text-fb-textDim bg-black/30 border border-fb-border/50 rounded px-1.5 py-0.5">' + esc(t) + '</span>').join('');
+        if (extra > 0) html += '<span class="text-[0.625rem] text-fb-textDim">+' + extra + '</span>';
         return '<div class="flex flex-wrap gap-1">' + html + '</div>';
     }
     function progressBar(passed, total) {

static/v3/match-review.js

@@ -0,0 +1,474 @@
+// Match-Review UI (P8 — library-metadata design §5/§11). A self-contained
+// module: the ambient "⚑ N to review" chip lives in the songs toolbar
+// (songs.js renders the element and calls the hooks below); the review MODAL,
+// the per-field available/missing detail, and the Settings → Library
+// "Metadata matching" card behaviour all live here.
+//
+// The modal reviews ONE chart at a time (the scraper-review model from
+// media-server / emulation-frontend apps): the chart's current metadata —
+// with explicit "Missing: …" chips — above the candidate list, each
+// candidate carrying "Adds / Shows as" chips, with Skip / Not a match /
+// Search instead / Use selected plus ‹ › navigation.
+//
+// Engagement guardrails (§11): opt-in tool-state, not a score. The chip only
+// appears when there is something to review, matching is silent on success
+// (no toasts, no sounds — hearing-safe), and nothing here ever writes to
+// pack files; a confirmed match only improves the local display cache.
+(function () {
+    'use strict';
+
+    const esc = (s) => String(s == null ? '' : s).replace(/[&<>"']/g, (c) => (
+        { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+    const enc = encodeURIComponent;
+
+    function artUrl(song) {
+        const v = song.mtime ? ('?v=' + Math.floor(song.mtime)) : '';
+        return '/api/song/' + enc(song.filename) + '/art' + v;
+    }
+
+    function fmtDur(sec) {
+        if (!sec && sec !== 0) return '';
+        const s = Math.max(0, Math.round(sec));
+        return Math.floor(s / 60) + ':' + String(s % 60).padStart(2, '0');
+    }
+
+    // ── 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.
+    // Silent on failure — surfaces just stay as they are.
+    let _chipBusy = false;
+    async function refreshChip() {
+        if (_chipBusy) return;
+        _chipBusy = true;
+        try {
+            const r = await fetch('/api/enrichment/status');
+            if (!r.ok) return;
+            const body = await r.json();
+            const st = body.states || {};
+            const n = st.review || 0;
+            const chip = document.getElementById('v3-songs-match-review');
+            if (chip) {
+                chip.textContent = '⚑ ' + n + ' to review';
+                chip.classList.toggle('hidden', !n);
+            }
+            const line = document.getElementById('enrich-status');
+            if (line) {
+                const parts = [
+                    ((st.matched || 0) + (st.manual || 0)) + ' matched',
+                    n + ' to review',
+                    (st.failed || 0) + ' unmatched',
+                ];
+                if (st.unscanned) parts.push(st.unscanned + ' queued');
+                line.textContent = (body.running ? 'Matching… · ' : '') + parts.join(' · ');
+            }
+        } catch (_) { /* offline — leave as-is */ } finally {
+            _chipBusy = false;
+        }
+    }
+
+    // ── Review modal (body-appended singleton, one chart at a time) ─────────
+    let _queue = [];
+    let _idx = 0;
+    let _lastFocus = null;
+    let _single = false;   // Fix-match mode: one song, no queue navigation
+
+    function ensureModal() {
+        let m = document.getElementById('v3-match-modal');
+        if (m) return m;
+        const overlay = document.createElement('div');
+        overlay.id = 'v3-match-overlay';
+        overlay.className = 'fixed inset-0 bg-black/60 z-40 hidden';
+        overlay.addEventListener('click', closeModal);
+        document.body.appendChild(overlay);
+        m = document.createElement('div');
+        m.id = 'v3-match-modal';
+        m.className = 'fixed inset-0 z-50 hidden flex items-center justify-center p-4 pointer-events-none';
+        m.innerHTML = '<div id="v3-match-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="Match review"></div>';
+        m.addEventListener('keydown', onModalKeydown);
+        document.body.appendChild(m);
+        return m;
+    }
+
+    function isTyping(e) {
+        const t = e.target;
+        return t && (t.tagName === 'INPUT' || t.tagName === 'TEXTAREA');
+    }
+
+    function onModalKeydown(e) {
+        if (e.key === 'Escape') { e.stopPropagation(); closeModal(); return; }
+        if (e.key === 'ArrowLeft' && !isTyping(e)) { e.preventDefault(); nav(-1); return; }
+        if (e.key === 'ArrowRight' && !isTyping(e)) { e.preventDefault(); nav(1); return; }
+        if (e.key !== 'Tab') return;
+        // Light focus trap: cycle within the panel.
+        const panel = document.getElementById('v3-match-panel');
+        if (!panel) return;
+        const foci = panel.querySelectorAll('button, input, [tabindex="0"]');
+        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 openModal() {
+        _lastFocus = document.activeElement;
+        _single = false;
+        const m = ensureModal();
+        renderLoading();
+        m.classList.remove('hidden');
+        document.getElementById('v3-match-overlay')?.classList.remove('hidden');
+        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.
+    function fixMatch(song) {
+        if (!song || !song.filename) return;
+        _lastFocus = document.activeElement;
+        _single = true;
+        _queue = [{
+            filename: song.filename, title: song.title || song.filename,
+            artist: song.artist || '', album: song.album || '',
+            year: song.year || '', duration: song.duration,
+            mtime: song.mtime, candidates: [],
+        }];
+        _idx = 0;
+        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();
+    }
+
+    function closeModal() {
+        document.getElementById('v3-match-modal')?.classList.add('hidden');
+        document.getElementById('v3-match-overlay')?.classList.add('hidden');
+        _single = false;
+        refreshChip();
+        if (_lastFocus && _lastFocus.isConnected) { try { _lastFocus.focus(); } catch (_) { } }
+        _lastFocus = null;
+    }
+
+    function nav(step) {
+        if (!_queue.length) return;
+        _idx = Math.min(Math.max(_idx + step, 0), _queue.length - 1);
+        renderCurrent();
+    }
+
+    async function loadQueue() {
+        try {
+            const r = await fetch('/api/enrichment/review?limit=200');
+            _queue = r.ok ? ((await r.json()).songs || []) : [];
+        } catch (_) { _queue = []; }
+        _idx = 0;
+        renderCurrent();
+    }
+
+    function headerHtml() {
+        const counter = (_queue.length && !_single)
+            ? '<span class="flex items-center gap-1 text-xs text-fb-textDim">' +
+            '<button data-mr-prev class="px-2 py-1 rounded hover:text-fb-text' + (_idx === 0 ? ' opacity-30' : '') + '" aria-label="Previous">‹</button>' +
+            (_idx + 1) + ' of ' + _queue.length +
+            '<button data-mr-next class="px-2 py-1 rounded hover:text-fb-text' + (_idx >= _queue.length - 1 ? ' opacity-30' : '') + '" aria-label="Next">›</button></span>'
+            : '';
+        return '<div class="flex items-center justify-between gap-3 p-5 pb-3 border-b border-fb-border/40 shrink-0">' +
+            '<h3 class="text-lg font-semibold text-fb-text">' + (_single ? 'Fix match' : 'Match review') + '</h3>' + counter +
+            '<button data-mr-close class="text-fb-textDim hover:text-fb-text" aria-label="Close">✕</button></div>';
+    }
+
+    function renderLoading() {
+        const panel = document.getElementById('v3-match-panel');
+        if (!panel) return;
+        panel.innerHTML = headerHtml() +
+            '<div class="p-5"><p class="text-sm text-fb-textDim">Loading…</p></div>';
+        panel.querySelector('[data-mr-close]')?.addEventListener('click', closeModal);
+    }
+
+    function renderDone() {
+        const panel = document.getElementById('v3-match-panel');
+        if (!panel) return;
+        panel.innerHTML = headerHtml() +
+            '<div class="p-5 space-y-2"><p class="text-sm text-fb-text">Nothing waiting for review.</p>' +
+            '<p class="text-xs text-fb-textDim">Medium-confidence matches queue here while the library is matched in the background. Matching options live in Settings → Library.</p></div>';
+        panel.querySelector('[data-mr-close]')?.addEventListener('click', closeModal);
+    }
+
+    // Amber "what this chart lacks" chips. Album/year come from the library
+    // row; cover art is detected from the art request failing (flagged onto
+    // the song object by the <img> onerror handler, then re-rendered).
+    function missingChips(song) {
+        const missing = [];
+        if (!String(song.album || '').trim()) missing.push('album');
+        if (!String(song.year || '').trim()) missing.push('year');
+        if (song._artMissing) missing.push('cover art');
+        if (!missing.length) return '';
+        return '<div class="flex flex-wrap items-center gap-1 pt-1">' +
+            '<span class="text-xs text-fb-textDim">Missing:</span>' +
+            missing.map((f) => '<span class="text-xs px-1.5 py-0.5 rounded border border-amber-400/40 text-amber-300/90 bg-amber-400/10">' + esc(f) + '</span>').join('') +
+            '</div>';
+    }
+
+    // Per-candidate "what accepting this gets you": fields the chart lacks
+    // that the candidate supplies, and fields whose DISPLAYED value would
+    // change (never the file).
+    function diffChips(song, cand) {
+        const adds = [];
+        const changes = [];
+        const have = (v) => String(v == null ? '' : v).trim();
+        const differ = (a, b) => have(a) && have(b) && have(a).toLowerCase() !== have(b).toLowerCase();
+        if (have(cand.album)) { if (!have(song.album)) adds.push('album'); else if (differ(song.album, cand.album)) changes.push('album'); }
+        if (have(cand.year)) { if (!have(song.year)) adds.push('year'); else if (differ(song.year, cand.year)) changes.push('year'); }
+        if (cand.genres && cand.genres.length) adds.push('genres');
+        if (have(cand.isrc)) adds.push('ISRC');
+        if (differ(song.artist, cand.artist)) changes.push(have(song.artist) + ' → ' + have(cand.artist));
+        if (differ(song.title, cand.title)) changes.push('title');
+        let html = '';
+        if (adds.length) html += '<span class="text-xs text-fb-good">Adds: ' + esc(adds.join(' · ')) + '</span>';
+        if (changes.length) html += (html ? ' ' : '') + '<span class="text-xs text-fb-textDim">Shows as: ' + esc(changes.join(' · ')) + '</span>';
+        return html ? '<span class="block truncate pt-0.5">' + html + '</span>' : '';
+    }
+
+    function candRowHtml(song, c, i, selected) {
+        const meta = [c.artist, c.album, c.year, fmtDur(c.duration)].filter(Boolean).join(' · ');
+        const pct = c.score != null ? Math.round(c.score * 100) + '%' : '';
+        return '<button data-mr-cand="' + i + '" role="radio" aria-checked="' + (selected ? 'true' : 'false') + '" class="w-full text-left px-3 py-2 rounded-md border ' +
+            (selected ? 'border-fb-primary bg-fb-primary/10' : 'border-fb-border/50 bg-gray-800/50 hover:border-fb-primary/60') + '">' +
+            '<span class="flex items-baseline justify-between gap-2">' +
+            '<span class="text-sm text-fb-text truncate">' + esc(c.title) + '</span>' +
+            '<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) +
+            '</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;
+        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">' +
+            // 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">' +
+            '<div class="min-w-0">' +
+            '<div class="text-base text-fb-text font-medium truncate">' + esc(song.title) + '</div>' +
+            '<div class="text-xs text-fb-textDim truncate">' + esc(sub) + '</div>' +
+            '<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">' +
+                '<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 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">' +
+            '<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 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>' +
+            '<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) {
+        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));
+        // Art failure → flag + re-render once so the "cover art" chip shows.
+        const img = panel.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) => {
+            btn.addEventListener('click', () => {
+                song._sel = Number(btn.getAttribute('data-mr-cand'));
+                renderCurrent();
+            });
+        });
+        panel.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 () => {
+            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', () => {
+            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);
+        input?.addEventListener('keydown', (e) => { if (e.key === 'Enter') { e.preventDefault(); go(); } });
+    }
+
+    // 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
+        const i = _queue.indexOf(song);
+        if (i >= 0) _queue.splice(i, 1);
+        if (_idx >= _queue.length) _idx = Math.max(0, _queue.length - 1);
+        refreshChip();
+        renderCurrent();
+    }
+
+    async function runSearch(panel, song) {
+        const input = panel.querySelector('[data-mr-search-input]');
+        const out = panel.querySelector('[data-mr-search-results]');
+        if (!input || !out) return;
+        const qRaw = input.value.trim();
+        if (!qRaw) return;
+        // "Artist – Title" splits on the first dash; a plain phrase searches
+        // as a title, which MusicBrainz handles well enough.
+        const m = qRaw.split(/\s+[–—-]\s+/);
+        const artist = m.length > 1 ? m[0] : '';
+        const title = m.length > 1 ? m.slice(1).join(' - ') : qRaw;
+        out.innerHTML = '<p class="text-xs text-fb-textDim">Searching…</p>';
+        let body = null;
+        try {
+            const r = await fetch('/api/enrichment/search?artist=' + enc(artist) +
+                '&title=' + enc(title) + '&filename=' + enc(song.filename));
+            if (r.status === 503) {
+                out.innerHTML = '<p class="text-xs text-fb-textDim">MusicBrainz is unavailable — try again later.</p>';
+                return;
+            }
+            if (r.ok) body = await r.json();
+        } catch (_) { /* falls through to the no-results line */ }
+        const cands = (body && body.candidates) || [];
+        if (!cands.length) {
+            out.innerHTML = '<p class="text-xs text-fb-textDim">No results.</p>';
+            return;
+        }
+        out.innerHTML = 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;
+                await post('/api/enrichment/review/' + enc(song.filename) + '/pick',
+                    { candidate: cand });
+                settle(song);
+            });
+        });
+    }
+
+    async function post(url, payload) {
+        try {
+            await fetch(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(payload || {}),
+            });
+        } catch (_) { /* offline — the row simply stays queued */ }
+    }
+
+    // ── Settings → Library → "Metadata matching" card ────────────────────────
+    // Markup lives statically in index.html (the v3 settings pattern); this
+    // wires it. All null-guarded so v2 (which lacks the elements) no-ops.
+    function wireSettingsCard() {
+        const sel = document.getElementById('enrich-threshold');
+        const order = document.getElementById('enrich-review-order');
+        const btn = document.getElementById('enrich-match-now');
+        // Boolean toggles, element id → settings key. enrich-enabled is the
+        // master background switch; the rest are the R1 scraper options
+        // (per-source + per-field auto-apply) plus the R4b overwrite gate.
+        const toggles = [
+            ['enrich-enabled', 'enrich_enabled'],
+            ['enrich-src-musicbrainz', 'enrich_src_musicbrainz'],
+            ['enrich-src-caa', 'enrich_src_caa'],
+            ['enrich-apply-names', 'enrich_apply_names'],
+            ['enrich-apply-year', 'enrich_apply_year'],
+            ['enrich-apply-genres', 'enrich_apply_genres'],
+            ['enrich-apply-art', 'enrich_apply_art'],
+            // R4b pack-overwrite gate — the one DEFAULT-OFF key in this list
+            // (see the load logic below).
+            ['allow-pack-overwrite', 'allow_pack_overwrite'],
+        ].map(([id, key]) => [document.getElementById(id), key]).filter(([el]) => el);
+        if (!toggles.length && !sel && !btn) return;
+        (async () => {
+            try {
+                const r = await fetch('/api/settings');
+                if (r.ok) {
+                    const cfg = await r.json();
+                    // The enrich keys default ON (absent → checked); the
+                    // overwrite gate defaults OFF (only an explicit true ticks it).
+                    for (const [el, key] of toggles) {
+                        el.checked = key === 'allow_pack_overwrite' ? cfg[key] === true : cfg[key] !== false;
+                    }
+                    if (sel) {
+                        const t = Number(cfg.enrich_auto_threshold);
+                        const want = Number.isFinite(t) ? t : 0.9;
+                        // Snap to the nearest offered option.
+                        let best = sel.options[0];
+                        for (const o of sel.options) {
+                            if (Math.abs(Number(o.value) - want) < Math.abs(Number(best.value) - want)) best = o;
+                        }
+                        if (best) sel.value = best.value;
+                    }
+                    if (order) {
+                        const v = String(cfg.enrich_review_order || 'missing_first');
+                        order.value = ['missing_first', 'artist', 'recent'].includes(v) ? v : 'missing_first';
+                    }
+                }
+            } catch (_) { /* leave markup defaults */ }
+            refreshChip();   // also fills #enrich-status
+        })();
+        const save = (key, value) => post('/api/settings', { [key]: value });
+        for (const [el, key] of toggles) {
+            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));
+        btn?.addEventListener('click', async () => {
+            await post('/api/enrichment/kick');
+            const line = document.getElementById('enrich-status');
+            if (line) line.textContent = 'Matching…';
+            setTimeout(refreshChip, 1500);
+        });
+    }
+
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', wireSettingsCard, { once: true });
+    } else {
+        wireSettingsCard();
+    }
+
+    window.__fbMatchReviewChip = refreshChip;
+    window.__fbOpenMatchReview = openModal;
+    window.__fbFixMatch = fixMatch;
+})();

static/v3/player-chrome.js

@@ -24,6 +24,18 @@
     let rafId = null, running = false;
     let lastMove = 0, lastUpNext = 0;
     let openPop = null;       // { btn, pop }
+    // Hover state over #player-controls, maintained by mouseenter/mouseleave
+    // (wired in start()). tickIdle previously called matches(':hover') every
+    // rAF frame, which forces a style recalc — profiled hot (feedBack perf).
+    let overControls = false;
+    const _onControlsEnter = () => { overControls = true; };
+    const _onControlsLeave = () => { overControls = false; };
+    // Up-Next pill: cached element refs (re-resolved when detached) and
+    // last-written values, so the 6 Hz recompute only touches the DOM when
+    // something actually changed — unconditional textContent/width writes
+    // re-triggered layout every tick.
+    let upnextEls = null;     // { pill, nm, eta, fill }
+    let upnextLast = { name: null, eta: null, prog: -1, hidden: null };
 
     // ── v3 UI signal + plugin-control slot API ───────────────────────────────
     // Lets plugins detect v3 (window.feedBack.uiVersion === 'v3') and mount
@@ -169,28 +181,52 @@
     }
 
     // ── Up Next pill ─────────────────────────────────────────────────────────
+    function _upnextRefs() {
+        // Cache refs; re-resolve only when a node detached (screen re-mount).
+        if (!upnextEls || !upnextEls.pill || !upnextEls.pill.isConnected) {
+            const pill = $('v3-upnext');
+            if (!pill) return null;
+            upnextEls = {
+                pill,
+                nm: $('v3-upnext-name'),
+                eta: $('v3-upnext-eta'),
+                fill: $('v3-upnext-bar-fill'),
+            };
+            // Fresh nodes → forget last-written state so everything re-syncs.
+            upnextLast = { name: null, eta: null, prog: -1, hidden: null };
+        }
+        return upnextEls;
+    }
+    function _upnextSetHidden(els, hidden) {
+        if (upnextLast.hidden === hidden) return;
+        upnextLast.hidden = hidden;
+        els.pill.classList.toggle('hidden', hidden);
+    }
     function updateUpNext() {
-        const pill = $('v3-upnext');
-        if (!pill) return;
+        const els = _upnextRefs();
+        if (!els) return;
         // Gated by the core "Show 'Up Next'" pref (Gameplay tab, default ON).
-        if (window.feedBack && window.feedBack.showUpNext === false) { pill.classList.add('hidden'); return; }
+        if (window.feedBack && window.feedBack.showUpNext === false) { _upnextSetHidden(els, true); return; }
         const hw = window.highway;
         const secs = (hw && typeof hw.getSections === 'function') ? hw.getSections() : null;
         const t = (hw && typeof hw.getTime === 'function') ? hw.getTime() : null;
-        if (!Array.isArray(secs) || !secs.length || t == null || isNaN(t)) { pill.classList.add('hidden'); return; }
+        if (!Array.isArray(secs) || !secs.length || t == null || isNaN(t)) { _upnextSetHidden(els, true); return; }
         let next = null;
         for (let i = 0; i < secs.length; i++) {
             if (typeof secs[i].time === 'number' && secs[i].time > t + 0.05) { next = secs[i]; break; }
         }
-        if (!next) { pill.classList.add('hidden'); return; }
+        if (!next) { _upnextSetHidden(els, true); return; }
         const dt = Math.max(0, next.time - t);
-        const nm = $('v3-upnext-name'), eta = $('v3-upnext-eta');
-        if (nm) nm.textContent = next.name || '—';
-        if (eta) eta.textContent = 'in ' + dt.toFixed(1) + 's';
+        // Coarsened eta (whole seconds from 10 s out, 1 decimal inside) +
+        // write-on-change: drops textContent writes (each a layout pass)
+        // from ~6/s to ~1/s.
+        const name = next.name || '—';
+        const etaText = 'in ' + (dt >= 10 ? Math.round(dt) + '' : dt.toFixed(1)) + 's';
+        if (els.nm && name !== upnextLast.name) { upnextLast.name = name; els.nm.textContent = name; }
+        if (els.eta && etaText !== upnextLast.eta) { upnextLast.eta = etaText; els.eta.textContent = etaText; }
         // Progress bar: fraction of the current section elapsed toward `next`.
         // Previous boundary is the last section at/before now (else song start).
-        const fill = $('v3-upnext-bar-fill');
-        if (fill) {
+        if (els.fill) {
             let prevT = 0;
             for (let i = 0; i < secs.length; i++) {
                 if (typeof secs[i].time === 'number' && secs[i].time <= t) prevT = secs[i].time;
@@ -198,9 +234,15 @@
             }
             const span = next.time - prevT;
             const prog = span > 0 ? Math.max(0, Math.min(1, (t - prevT) / span)) : 0;
-            fill.style.width = (prog * 100).toFixed(1) + '%';
+            const q = Math.round(prog * 1000) / 1000;
+            if (q !== upnextLast.prog) {
+                upnextLast.prog = q;
+                // scaleX is compositor-only — width writes re-ran layout.
+                // Pairs with transform-origin:left on #v3-upnext-bar-fill.
+                els.fill.style.transform = 'scaleX(' + q + ')';
+            }
         }
-        pill.classList.remove('hidden');
+        _upnextSetHidden(els, false);
     }
 
     // ── Speed visual (bars + chevrons reflect #speed-slider) ──────────────────
@@ -230,8 +272,8 @@
         if (!p) return;
         const playBtn = $('btn-play');
         const playing = playBtn && playBtn.getAttribute('aria-pressed') === 'true';
-        const controls = $('player-controls');
-        const overControls = controls && typeof controls.matches === 'function' && controls.matches(':hover');
+        // overControls maintained by mouseenter/mouseleave (see start()) —
+        // matches(':hover') here forced a per-frame style recalc.
         // Keep the transport up while paused, hovering it, or a popover is open.
         if (openPop || overControls || !playing) { lastMove = now(); return; }
         if (now() - lastMove > IDLE_MS) {
@@ -249,6 +291,16 @@
             // Re-sync the lyrics icon so programmatic highway.setLyricsVisible()
             // (e.g. from lyrics_karaoke) isn't left stale; cheap + idempotent.
             syncLyricsIcon();
+            // Reconcile the edge-driven hover flag against ground truth at
+            // this throttled cadence (~6 Hz, not per frame). Covers both
+            // failure modes of pure mouseenter/mouseleave tracking: a
+            // missed mouseleave (controls hidden/detached under the
+            // pointer → flag stuck true, transport never auto-hides) and
+            // a re-created #player-controls node whose listeners were
+            // lost (flag stuck false-ish / dead). matches(':hover') on a
+            // detached node is simply false, so this also self-clears.
+            const c = $('player-controls');
+            overControls = !!(c && typeof c.matches === 'function' && c.matches(':hover'));
         }
         tickIdle();
         rafId = requestAnimationFrame(loop);
@@ -263,6 +315,12 @@
         wireRail();
         p.addEventListener('mousemove', revealChrome);
         p.addEventListener('touchstart', revealChrome, { passive: true });
+        const c = $('player-controls');
+        if (c) {
+            overControls = typeof c.matches === 'function' && c.matches(':hover');
+            c.addEventListener('mouseenter', _onControlsEnter);
+            c.addEventListener('mouseleave', _onControlsLeave);
+        }
         const s = $('speed-slider');
         if (s && !s.dataset.pcVizWired) { s.dataset.pcVizWired = '1'; s.addEventListener('input', updateSpeedViz); }
         updateSpeedViz();
@@ -281,6 +339,12 @@
             p.removeEventListener('touchstart', revealChrome);
             p.classList.remove('chrome-active', 'chrome-idle');
         }
+        const c = $('player-controls');
+        if (c) {
+            c.removeEventListener('mouseenter', _onControlsEnter);
+            c.removeEventListener('mouseleave', _onControlsLeave);
+        }
+        overControls = false;
         closePop();
     }
     function syncActivation() {

static/v3/playlists.js

@@ -37,26 +37,59 @@
         if (p.cover_url) return '<div class="' + box + '">' + img(p.cover_url, 'w-full h-full object-cover') + '</div>';
         const arts = Array.isArray(p.art_urls) ? p.art_urls : [];
         if (!arts.length) {
-            return '<div class="' + box + ' flex items-center justify-center text-5xl text-fb-textDim">' + (p.system_key ? '🔖' : '🎵') + '</div>';
+            return '<div class="' + box + ' flex items-center justify-center text-5xl text-fb-textDim">' + (p.kind === 'album' ? '💿' : p.system_key ? '🔖' : '🎵') + '</div>';
         }
         if (arts.length < 4) return '<div class="' + box + '">' + img(arts[0], 'w-full h-full object-cover') + '</div>';
         return '<div class="' + box + ' grid grid-cols-2 grid-rows-2 gap-px">' +
             arts.slice(0, 4).map((u) => img(u, 'w-full h-full object-cover')).join('') + '</div>';
     }
 
+    // The slot's pinned-arrangement INDEX, resolved from the stored NAME
+    // against the slot's current chart (names survive rescans; an index
+    // wouldn't). null = no pin / the name isn't on this chart → full song.
+    function _slotArrIndex(s) {
+        if (!s.arrangement || !Array.isArray(s.arrangements)) return null;
+        const m = s.arrangements.find((a) => a && (a.smart_name === s.arrangement || a.name === s.arrangement));
+        return (m && m.index != null) ? m.index : null;
+    }
+
     function songRow(s, opts) {
         opts = opts || {};
         const handle = opts.draggable
             ? '<span class="cursor-grab text-fb-textDim/60 px-1" title="Drag to reorder">⠿</span>' : '';
         const tuning = s.tuning_name
-            ? '<span class="ml-2 text-[10px] bg-fb-mid text-black font-bold px-1.5 py-0.5 rounded-sm">' + esc(s.tuning_name) + '</span>' : '';
-        return '<li data-fn="' + esc(s.filename) + '"' + (opts.draggable ? ' draggable="true"' : '') +
-            ' class="flex items-center gap-3 px-3 py-2 rounded-lg hover:bg-fb-card/50 group">' +
+            ? '<span class="ml-2 text-[0.625rem] bg-fb-mid text-black font-bold px-1.5 py-0.5 rounded-sm">' + esc(s.tuning_name) + '</span>' : '';
+        // ── Curated-album slot extras (P6) — mixes/saved emit none of this ──
+        // A slot plays its RESOLVED chart (data-play-fn: the pinned file, or
+        // the work's current keeper when the pinned file is gone) with its
+        // pinned arrangement (data-play-arr); `missing` = the whole work left
+        // the library, so the row dims and loses play (denominator stays
+        // honest). ▾ opens the slot editor (chart + arrangement pin).
+        const isAlbum = !!opts.album;
+        const missing = isAlbum && !!s.missing;
+        const playFn = s.resolved_filename || s.filename;
+        const arrIdx = isAlbum ? _slotArrIndex(s) : null;
+        const playAttrs = isAlbum && !missing
+            ? ' data-play-fn="' + esc(playFn) + '"' + (arrIdx != null ? ' data-play-arr="' + arrIdx + '"' : '')
+            : '';
+        const acc = (isAlbum && typeof opts.acc === 'number')
+            ? '<span class="text-xs font-bold shrink-0 ' + (opts.acc >= 0.9 ? 'text-fb-good' : opts.acc >= 0.5 ? 'text-fb-mid' : 'text-fb-low') + '">' + Math.round(opts.acc * 100) + '%</span>'
+            : '';
+        const pin = (isAlbum && s.arrangement)
+            ? '<span class="ml-2 text-[0.625rem] bg-fb-primary/20 text-fb-primary font-bold px-1.5 py-0.5 rounded-sm" title="Pinned arrangement">' + esc(s.arrangement) + '</span>' : '';
+        const orphan = (isAlbum && s.resolved_from_orphan)
+            ? '<span class="ml-2 text-[0.625rem] text-fb-textDim" title="The pinned chart is gone — playing this song\'s current keeper instead">(auto)</span>' : '';
+        const slotBtn = (isAlbum && !missing)
+            ? '<button data-slot aria-label="Choose chart / arrangement" title="Choose chart / arrangement" class="opacity-0 group-hover:opacity-100 text-fb-textDim hover:text-fb-text text-sm px-2">▾</button>' : '';
+        return '<li data-fn="' + esc(s.filename) + '"' + playAttrs + (opts.draggable ? ' draggable="true"' : '') +
+            ' class="flex items-center gap-3 px-3 py-2 rounded-lg hover:bg-fb-card/50 group' + (missing ? ' opacity-50' : '') + '">' +
             handle +
             '<img src="' + esc(s.art_url) + '" alt="" class="w-10 h-10 rounded object-cover bg-fb-card" onerror="this.style.visibility=\'hidden\'">' +
-            '<span class="flex-1 min-w-0"><span class="block text-sm text-fb-text truncate">' + esc(s.title) + tuning + '</span>' +
-            '<span class="block text-xs text-fb-textDim truncate">' + esc(s.artist) + '</span></span>' +
-            '<button data-v3-play aria-label="Play" class="opacity-0 group-hover:opacity-100 text-fb-primary hover:text-fb-primaryHi text-sm px-2" title="Play">▶</button>' +
+            '<span class="flex-1 min-w-0"><span class="block text-sm text-fb-text truncate">' + esc(s.title) + tuning + pin + orphan + '</span>' +
+            '<span class="block text-xs text-fb-textDim truncate">' + (missing ? 'Missing — no version of this song is in your library' : esc(s.artist)) + '</span></span>' +
+            acc +
+            (missing ? '' : '<button data-v3-play aria-label="Play" class="opacity-0 group-hover:opacity-100 text-fb-primary hover:text-fb-primaryHi text-sm px-2" title="Play">▶</button>') +
+            slotBtn +
             '<button data-remove aria-label="Remove from playlist" class="opacity-0 group-hover:opacity-100 text-fb-textDim hover:text-fb-accent text-sm px-2" title="Remove">✕</button>' +
             '</li>';
     }
@@ -68,7 +101,14 @@
                 // playSong decodeURIComponent()s its arg for the highway WS, so
                 // pass an encoded filename (like the rest of v3) — a raw name
                 // with %/#/?/ in it would otherwise misroute or throw.
-                if (typeof window.playSong === 'function') window.playSong(encodeURIComponent(fn));
+                // Album slots override the play target (data-play-fn = the
+                // orphan-resolved chart) + pass the pinned arrangement index;
+                // mix/saved rows carry neither attribute and behave as before.
+                const pfn = li.getAttribute('data-play-fn') || fn;
+                const pa = li.getAttribute('data-play-arr');
+                if (typeof window.playSong === 'function') {
+                    window.playSong(encodeURIComponent(pfn), pa == null ? undefined : Number(pa));
+                }
             });
             li.querySelector('[data-remove]')?.addEventListener('click', async () => {
                 await fetch('/api/playlists/' + pid + '/songs/' + encodeURIComponent(fn), { method: 'DELETE' });
@@ -106,7 +146,10 @@
         const lists = (await jget('/api/playlists')) || [];
         root.innerHTML =
             '<div class="max-w-5xl mx-auto px-6 md:px-8 pb-8">' +
-            '<div class="flex items-center justify-end mb-6">' +
+            '<div class="flex items-center justify-end gap-2 mb-6">' +
+            // Curated album (P6): a hand-picked ORDERED set with a chosen chart
+            // per track — same machinery as a playlist, kind='album'.
+            '<button id="v3-pl-new-album" title="A hand-picked, ordered set of songs — your version of an album, with your chosen chart per track" class="bg-fb-card/80 hover:bg-fb-card border border-fb-border/60 text-fb-text px-4 py-2 rounded-md text-sm font-medium">💿 New album</button>' +
             '<button id="v3-pl-new" class="bg-fb-primary hover:bg-fb-primaryHi text-white px-4 py-2 rounded-md text-sm font-medium shadow-lg shadow-fb-primary/20">New playlist</button>' +
             '</div>' +
             (lists.length
@@ -114,7 +157,7 @@
                     '<button data-pl="' + p.id + '" class="text-left bg-fb-card/80 backdrop-blur rounded-xl p-4 border border-fb-border/50 hover:border-fb-primary/40 transition">' +
                     playlistCoverHtml(p) +
                     '<div class="text-sm font-medium text-fb-text truncate">' + esc(p.name) + '</div>' +
-                    '<div class="text-xs text-fb-textDim">' + p.count + ' song' + (p.count === 1 ? '' : 's') + '</div>' +
+                    '<div class="text-xs text-fb-textDim">' + (p.kind === 'album' ? '💿 Album · ' : '') + p.count + ' song' + (p.count === 1 ? '' : 's') + '</div>' +
                     '</button>').join('') + '</div>'
                 : '<p class="text-fb-textDim">No playlists yet. Create one to group songs.</p>') +
             '</div>';
@@ -124,6 +167,12 @@
             await jsend('POST', '/api/playlists', { name });
             renderPlaylists();
         });
+        root.querySelector('#v3-pl-new-album')?.addEventListener('click', async () => {
+            const name = ((await window.uiPrompt({ title: 'New Album', label: 'Album name', okLabel: 'Create', placeholder: 'My Album' })) || '').trim();
+            if (!name) return;
+            await jsend('POST', '/api/playlists', { name, kind: 'album' });
+            renderPlaylists();
+        });
         root.querySelectorAll('[data-pl]').forEach((b) =>
             b.addEventListener('click', () => renderPlaylistDetail(parseInt(b.getAttribute('data-pl'), 10))));
     }
@@ -134,26 +183,83 @@
         const pl = await jget('/api/playlists/' + pid);
         if (!pl) { renderPlaylists(); return; }
         const isSystem = !!pl.system_key;
+        const isAlbum = pl.kind === 'album';
+        // Set-scoped repertoire (P6, §7.2): an album is a bounded practice SET
+        // with a denominator — "N of M mastered", per-track accuracy, never one
+        // album score. Same 0.9 threshold as the library meter/green badge.
+        let best = {};
+        if (isAlbum) best = (await jget('/api/stats/best')) || {};
+        const slotAcc = (s) => best[s.resolved_filename || s.filename];
+        let meter = '';
+        if (isAlbum && pl.songs.length) {
+            const tracks = pl.songs.filter((s) => !s.missing);
+            const mastered = tracks.filter((s) => (slotAcc(s) || 0) >= 0.9).length;
+            const started = tracks.filter((s) => { const b = slotAcc(s); return typeof b === 'number' && b > 0 && b < 0.9; }).length;
+            const pct = tracks.length ? Math.max(0, Math.min(100, Math.round((mastered / tracks.length) * 100))) : 0;
+            meter =
+                '<div class="mb-6">' +
+                '<div class="flex items-baseline justify-between gap-3 mb-1">' +
+                '<span class="text-sm font-semibold text-fb-text">Album repertoire</span>' +
+                '<span class="text-xs text-fb-textDim">' + mastered + ' of ' + tracks.length + ' mastered' +
+                (started ? ' &middot; ' + started + ' in progress' : '') + '</span></div>' +
+                '<div class="v3-rep-track"><div class="v3-rep-fill" style="width:' + pct + '%"></div></div>' +
+                '</div>';
+        }
         root.innerHTML =
             '<div class="max-w-3xl mx-auto p-6 md:p-8">' +
             '<button id="v3-pl-back" class="text-sm text-fb-textDim hover:text-fb-text mb-4">← Playlists</button>' +
             '<div class="flex items-center justify-between mb-6 gap-3">' +
-            '<h2 class="text-3xl font-bold text-fb-text truncate">' + esc(pl.name) + '</h2>' +
+            '<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>' : '') +
             (isSystem ? '' :
-                '<div class="flex gap-2 shrink-0">' +
                 '<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>' : '') +
                 '<button id="v3-pl-rename" class="text-sm text-fb-textDim hover:text-fb-text px-2">Rename</button>' +
                 '<button id="v3-pl-delete" class="text-sm text-fb-textDim hover:text-fb-accent px-2">Delete</button>' +
-                '<input type="file" id="v3-pl-cover-file" accept="image/*" class="hidden"></div>') +
+                '<input type="file" id="v3-pl-cover-file" accept="image/*" class="hidden">') +
             '</div>' +
+            '</div>' +
+            meter +
             (pl.songs.length
-                ? '<ul id="v3-pl-songs" class="space-y-1">' + pl.songs.map((s) => songRow(s, { draggable: !isSystem })).join('') + '</ul>'
-                : '<p class="text-fb-textDim">Empty — add songs from the library.</p>') +
+                ? '<ul id="v3-pl-songs" class="space-y-1">' + pl.songs.map((s) => songRow(s, { draggable: !isSystem, album: isAlbum, acc: isAlbum ? slotAcc(s) : undefined })).join('') + '</ul>'
+                : '<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);
+        // 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
+        // each slot's resolved chart with its pinned arrangement (playQueue's
+        // per-index arrangements array, #685) and skips missing works.
+        root.querySelector('#v3-pl-playall')?.addEventListener('click', () => {
+            const files = [], arrs = [];
+            (pl.songs || []).forEach((s) => {
+                if (isAlbum && s.missing) return;
+                const fn = s.resolved_filename || s.filename;
+                if (!fn) return;
+                files.push(fn);
+                const idx = isAlbum ? _slotArrIndex(s) : null;
+                arrs.push(idx == null ? undefined : idx);
+            });
+            if (!files.length) return;
+            if (window.feedBack && window.feedBack.playQueue) {
+                window.feedBack.playQueue.start(files, isAlbum
+                    ? { source: pl.name, arrangements: arrs }
+                    : { source: pl.name });
+            } else if (typeof window.playSong === 'function') window.playSong(encodeURIComponent(files[0]));
+        });
         const listEl = root.querySelector('#v3-pl-songs');
         if (listEl) wireSongRows(listEl, pid, () => renderPlaylistDetail(pid));
+        // Album slot editor (▾ per row): pick the slot's chart + arrangement.
+        if (listEl && isAlbum) {
+            listEl.querySelectorAll('li[data-fn]').forEach((li) => {
+                li.querySelector('[data-slot]')?.addEventListener('click', () => {
+                    const fn = li.getAttribute('data-fn');
+                    const slot = (pl.songs || []).find((x) => x.filename === fn);
+                    if (slot) openSlotPicker(pid, slot, () => renderPlaylistDetail(pid));
+                });
+            });
+        }
         root.querySelector('#v3-pl-rename')?.addEventListener('click', async () => {
             const name = ((await window.uiPrompt({ title: 'Rename Playlist', label: 'Playlist name', value: pl.name, okLabel: 'Rename' })) || '').trim();
             if (!name) return;
@@ -186,6 +292,94 @@
         });
     }
 
+    // ── Curated-album slot editor (P6, §7.2) ─────────────────────────────────
+    // Pins THIS slot's chart + arrangement. The per-slot pick is deliberately
+    // independent of the work's global preferred — a rehearsed set must stay
+    // the same notes even if the global keeper is re-picked later. Charts come
+    // from the work-charts API; the arrangement pin is stored as a NAME (it
+    // survives rescans; the index is resolved at play). A compact overlay for
+    // now — unifying with the library's Charts drawer (slot-scoped mode) is a
+    // follow-up once the in-flight drawer changes land.
+    async function openSlotPicker(pid, slot, onChange) {
+        const curFn = slot.resolved_filename || slot.filename;
+        let wk = slot.work_key;
+        if (!wk) {
+            const w = await jget('/api/chart/' + encodeURIComponent(curFn) + '/work');
+            wk = w && w.work_key;
+        }
+        const charts = wk ? await jget('/api/work/' + encodeURIComponent(wk) + '/charts') : null;
+        const chartList = (charts && Array.isArray(charts.charts)) ? charts.charts : [];
+        const radio = (name, value, checked, label, sub) =>
+            '<label class="flex items-start gap-2 px-2 py-1.5 rounded hover:bg-fb-card/60 cursor-pointer">' +
+            '<input type="radio" name="' + name + '" value="' + esc(value) + '"' + (checked ? ' checked' : '') + ' class="accent-fb-primary mt-0.5">' +
+            '<span class="min-w-0 flex-1"><span class="block text-sm text-fb-text truncate">' + label + '</span>' +
+            (sub ? '<span class="block text-[0.625rem] text-fb-textDim truncate">' + sub + '</span>' : '') +
+            '</span></label>';
+        // Checked = the stored pin; an orphaned slot (stored file gone from the
+        // list) pre-checks the chart it currently resolves to, so Apply re-pins
+        // what's actually playing.
+        const slotInList = chartList.some((x) => x.filename === slot.filename);
+        const chartRows = chartList.map((c) => radio(
+            'slot-chart', c.filename,
+            c.filename === slot.filename || (!slotInList && c.filename === curFn),
+            esc(c.title) + (c.is_representative ? ' <span class="text-[0.625rem] text-fb-primary">● preferred</span>' : ''),
+            esc((c.tuning_name ? c.tuning_name + ' · ' : '') + c.filename))).join('');
+        const arrRows = [radio('slot-arr', '', !slot.arrangement, 'Full song <span class="text-[0.625rem] text-fb-textDim">(default)</span>', '')]
+            .concat((slot.arrangements || []).map((a) => {
+                const name = (a && (a.smart_name || a.name)) || '';
+                if (!name) return '';
+                return radio('slot-arr', name,
+                    slot.arrangement === name || slot.arrangement === a.name,
+                    esc(name), '');
+            })).join('');
+        const overlay = document.createElement('div');
+        overlay.className = 'fixed inset-0 z-[200] bg-black/60 backdrop-blur-sm flex items-center justify-center p-4';
+        overlay.innerHTML =
+            '<div class="bg-fb-card w-full max-w-md rounded-xl border border-fb-border/60 p-5 space-y-4 max-h-[80vh] overflow-y-auto v3-scroll">' +
+            '<div class="flex items-center justify-between gap-2">' +
+            '<h3 class="text-lg font-semibold text-fb-text truncate">' + esc(slot.title) + '</h3>' +
+            '<button type="button" data-x class="text-fb-textDim hover:text-fb-text text-xl leading-none" aria-label="Close">✕</button></div>' +
+            (chartRows
+                ? '<div><div class="text-xs font-semibold uppercase tracking-wider text-fb-textDim mb-1">Chart for this slot</div>' + chartRows + '</div>'
+                : '') +
+            '<div><div class="text-xs font-semibold uppercase tracking-wider text-fb-textDim mb-1">Arrangement</div>' + arrRows + '</div>' +
+            '<div data-err class="hidden text-xs text-red-400"></div>' +
+            '<div class="flex justify-end gap-2">' +
+            '<button type="button" data-cancel class="text-sm text-fb-textDim hover:text-fb-text px-3 py-2">Cancel</button>' +
+            '<button type="button" data-apply class="bg-fb-primary hover:bg-fb-primaryHi text-white text-sm font-medium px-5 py-2 rounded-md">Apply</button>' +
+            '</div></div>';
+        const onKey = (e) => { if (e.key === 'Escape') { e.preventDefault(); close(); } };
+        function close() { overlay.remove(); document.removeEventListener('keydown', onKey); }
+        document.addEventListener('keydown', onKey);
+        overlay.addEventListener('click', (e) => { if (e.target === overlay) close(); });
+        overlay.querySelector('[data-x]').addEventListener('click', close);
+        overlay.querySelector('[data-cancel]').addEventListener('click', close);
+        overlay.querySelector('[data-apply]').addEventListener('click', async () => {
+            const chart = overlay.querySelector('input[name="slot-chart"]:checked');
+            const arr = overlay.querySelector('input[name="slot-arr"]:checked');
+            const body = {};
+            if (chart && chart.value && chart.value !== slot.filename) body.chart_filename = chart.value;
+            if (arr) {
+                const v = arr.value || null;
+                if (v !== (slot.arrangement || null)) body.arrangement = v;
+            }
+            if (Object.keys(body).length) {
+                // jsend → null on a non-2xx (e.g. swap-to-other-work rejected, or
+                // the resolved target duplicates another slot's pin). Surfacing it
+                // and keeping the picker open beats silently closing "as saved".
+                const res = await jsend('PATCH', '/api/playlists/' + pid + '/songs/' + encodeURIComponent(slot.filename), body);
+                if (!res) {
+                    const err = overlay.querySelector('[data-err]');
+                    if (err) { err.textContent = 'Could not update this slot.'; err.classList.remove('hidden'); }
+                    return;   // keep the picker open — not a success
+                }
+            }
+            close();
+            onChange();
+        });
+        document.body.appendChild(overlay);
+    }
+
     // ── #v3-saved ─────────────────────────────────────────────────────────--
     async function renderSaved() {
         const root = document.getElementById('v3-saved');

static/v3/profile.js

@@ -82,10 +82,10 @@
             '<span class="text-base font-extrabold tracking-tight leading-none">' + (p.current_streak || 0) + ' DAYS</span></div>' +
             '<div class="flex items-end gap-2">' +
             '<div class="flex flex-col leading-none">' +
-            '<span class="text-gray-400 text-[10px] font-medium">Rank:</span>' +
+            '<span class="text-gray-400 text-[0.625rem] font-medium">Rank:</span>' +
             '<span class="text-xl font-bold leading-none">' + rank + '</span></div>' +
             '<div class="flex items-end gap-1">' + bars + '</div>' +
-            '<span class="text-[10px] font-semibold text-fb-gold leading-none">' + Number(balance).toLocaleString() + ' dB</span>' +
+            '<span class="text-[0.625rem] font-semibold text-fb-gold leading-none">' + Number(balance).toLocaleString() + ' dB</span>' +
             '</div></div></button>';
         // Equipped avatar frame (spec 010 cosmetics).
         if (window.v3Theme && typeof window.v3Theme.applyFrame === 'function') {
@@ -178,7 +178,7 @@
             '<div id="v3-profile-bests" class="text-sm text-fb-textDim">Play a song to start tracking your accuracy and best scores.</div>' +
             '</div>';
         const playerIdFooter = (_profile && _profile.player_hash
-            ? '<p class="text-center text-[10px] uppercase tracking-wider text-fb-textDim/60">player id ' + esc(_profile.player_hash.slice(0, 12)) + '</p>'
+            ? '<p class="text-center text-[0.625rem] uppercase tracking-wider text-fb-textDim/60">player id ' + esc(_profile.player_hash.slice(0, 12)) + '</p>'
             : '');
         root.innerHTML =
             '<div class="max-w-4xl mx-auto p-6 md:p-8">' +

static/v3/shell.js

@@ -36,7 +36,7 @@
         { key: 'plugins',    screen: 'v3-plugins',       label: 'Plugins',         group: 'HOME',    icon: 'plug' },
         { key: 'settings',   screen: 'settings',         label: 'Settings',        group: 'HOME',    icon: 'gear' },
         { key: 'playlists',  screen: 'v3-playlists',     label: 'Playlists',       group: 'LIBRARY', icon: 'list' },
-        { key: 'songs',      screen: 'v3-songs',         label: 'Songs',           group: 'LIBRARY', icon: 'disc' },
+        { key: 'songs',      screen: 'v3-songs',         label: 'Song Library',    group: 'LIBRARY', icon: 'disc' },
         { key: 'lessons',    screen: 'v3-lessons',       label: 'Lessons',         group: 'LIBRARY', icon: 'lessons' },
         { key: 'favorites',  screen: 'favorites',        label: 'Favorites',       group: 'LIBRARY', icon: 'star' },
         { key: 'saved',      screen: 'v3-saved',         label: 'Saved for Later', group: 'LIBRARY', icon: 'bookmark' },
@@ -179,7 +179,7 @@
             const items = NAV.filter((n) => n.group === group);
             if (!items.length) continue;
             const itemsHTML = items.map((it) => navItemHTML(it) + promotedSlotHTML(it.key)).join('');
-            html += '<div><div class="v3-nav-group px-3 mb-1 text-[10px] uppercase tracking-wider font-semibold text-fb-textDim/70">' +
+            html += '<div><div class="v3-nav-group px-3 mb-1 text-[0.625rem] uppercase tracking-wider font-semibold text-fb-textDim/70">' +
                 group + '</div><div class="space-y-0.5">' + itemsHTML + '</div></div>';
         }
         nav.innerHTML = html;

static/v3/theme-core.js

@@ -23,7 +23,24 @@
     const OPACITY = { 95: '0.95', 90: '0.9', 80: '0.8', 70: '0.7', 60: '0.6',
                       50: '0.5', 40: '0.4', 30: '0.3', 20: '0.2', 10: '0.1' };
 
+    // Default fb palette (mirrors tailwind.config.js `fb`). Emitted as
+    // always-present `--fbv-*` on :root so `var(--fbv-accent)` resolves even
+    // un-themed — the un-themed look is unchanged (the fb-* utilities still use
+    // their compiled defaults; this only hands plugins a stable host token to
+    // read + derive from). Adds two keystone ROLES the palette lacked:
+    // `on-accent` (a foreground legible ON the accent fill — the missing piece
+    // behind white-on-accent contrast bugs) and `focus-ring`.
+    const DEFAULTS = {
+        bg: '#0f172a', sidebar: '#111827', card: '#1e293b', cardMuted: '#0b1220',
+        primary: '#0ea5e9', primaryHi: '#38bdf8', accent: '#ef4444',
+        text: '#f8fafc', textDim: '#94a3b8', border: '#334155',
+        good: '#22c55e', mid: '#eab308', low: '#ef4444', gold: '#e8c040',
+        'on-accent': '#f8fafc', 'focus-ring': '#38bdf8',
+    };
+
     let _frameStyle = '';   // equipped avatar-frame CSS fragment ('' = none)
+    let _themeId = null;    // equipped theme id (null = default look)
+    let _themeCaps = null;  // equipped theme's declared device capabilities, or null
 
     function hexToRgb(hex) {
         const m = /^#?([0-9a-f]{6})$/i.exec(String(hex || '').trim());
@@ -73,12 +90,14 @@
         return 'html[data-fb-theme] {\n' + vars + '}\n' + rules;
     }
 
-    function apply(payload) {
+    function apply(payload, meta) {
         const colors = payload && payload.colors;
         let styleEl = document.getElementById(STYLE_ID);
         if (!colors) {
             if (styleEl) styleEl.remove();
             document.documentElement.removeAttribute('data-fb-theme');
+            _themeId = null; _themeCaps = null;
+            _emitThemeChanged();
             return;
         }
         if (!styleEl) {
@@ -88,6 +107,13 @@
         }
         styleEl.textContent = cssFor(colors);
         document.documentElement.setAttribute('data-fb-theme', '1');
+        // Track identity + declared device capabilities for the read API. A
+        // theme MAY carry `capabilities` (e.g. {glow:false}) in its payload;
+        // recolor-only themes carry none (→ default affordances reported).
+        _themeId = (meta && meta.id) || (payload && payload.id) || 'custom';
+        _themeCaps = (payload && payload.capabilities)
+            || (meta && meta.capabilities) || null;
+        _emitThemeChanged();
     }
 
     function setFrame(payload) {
@@ -106,7 +132,7 @@
 
     function applyCosmetics(cosmetics) {
         cosmetics = cosmetics || {};
-        apply((cosmetics.theme || {}).payload || null);
+        apply((cosmetics.theme || {}).payload || null, cosmetics.theme || null);
         setFrame((cosmetics.avatar_frame || {}).payload || null);
     }
 
@@ -123,6 +149,83 @@
         } catch (e) { /* offline — keep current look */ }
     }
 
+    // ── Host theme READ surface (window.feedBack.theme) ──────────────────────
+    // The apply side stays on window.v3Theme; this is the read/capability side
+    // plugins consume so a feature can render correctly under any theme instead
+    // of binding to the one the dev happened to see. See docs/host-theme-contract.md.
+
+    // Always-present `--fbv-*` defaults on :root (see DEFAULTS). Additive: the
+    // un-themed look is unchanged; this only makes var(--fbv-*) resolve so a
+    // plugin can derive surfaces from host tokens whether or not a theme is on.
+    function _injectDefaults() {
+        if (document.getElementById('fb-theme-defaults')) return;
+        let vars = '';
+        for (const key in DEFAULTS) {
+            const rgb = hexToRgb(DEFAULTS[key]);
+            if (rgb) vars += '  --fbv-' + key + ': ' + rgb + ';\n';
+        }
+        const el = document.createElement('style');
+        el.id = 'fb-theme-defaults';
+        el.textContent = ':root {\n' + vars + '}\n';
+        (document.head || document.documentElement).appendChild(el);
+    }
+
+    function prefersReducedMotion() {
+        try {
+            return !!(window.matchMedia
+                && window.matchMedia('(prefers-reduced-motion: reduce)').matches);
+        } catch (e) { return false; }
+    }
+
+    // Live snapshot of the resolved role tokens ("r g b" triplets; use as
+    // rgb(var(--fbv-<key>)) in CSS). Reflects the themed values when a theme is
+    // equipped, the :root defaults otherwise.
+    function _readTokens() {
+        const t = {};
+        try {
+            const cs = getComputedStyle(document.documentElement);
+            for (const key in DEFAULTS) {
+                const v = cs.getPropertyValue('--fbv-' + key).trim();
+                if (v) t[key] = v;
+            }
+        } catch (e) { /* no computed style available yet */ }
+        return t;
+    }
+
+    // Whether the ACTIVE theme permits decorative DEVICES — the signal a feature
+    // reads to pick a device (glow vs. solid) rather than hardcoding one. Today's
+    // recolor-only themes declare nothing → default affordances; a theme may opt
+    // out via `capabilities` in its payload (e.g. a clean theme = {glow:false}).
+    // `motion` is additionally gated by the OS reduced-motion preference.
+    function capabilities() {
+        const c = _themeCaps || {};
+        const allowMotion = c.motion !== undefined ? !!c.motion : true;
+        return {
+            glow: c.glow !== undefined ? !!c.glow : true,
+            gradients: c.gradients !== undefined ? !!c.gradients : true,
+            motion: allowMotion && !prefersReducedMotion(),
+        };
+    }
+
+    function get() {
+        return {
+            id: _themeId,
+            isThemed: document.documentElement.hasAttribute('data-fb-theme'),
+            tokens: _readTokens(),
+        };
+    }
+
+    function _emitThemeChanged() {
+        if (window.feedBack && typeof window.feedBack.emit === 'function') {
+            window.feedBack.emit('theme:changed', {
+                id: _themeId,
+                isThemed: document.documentElement.hasAttribute('data-fb-theme'),
+                tokens: _readTokens(),
+                capabilities: capabilities(),
+            });
+        }
+    }
+
     window.v3Theme = {
         apply,            // preview/apply a theme payload directly (null = default)
         applyCosmetics,   // apply a {theme, avatar_frame} equipped map
@@ -131,6 +234,13 @@
         refresh,          // re-read equipped cosmetics from /api/profile
     };
 
+    // Host-owned theme READ surface. Attached defensively so it survives the
+    // feedBack bus being (re)built by capabilities.js regardless of load order
+    // (the bus constructor copies pre-existing keys onto itself).
+    window.feedBack = window.feedBack || {};
+    window.feedBack.theme = { get, capabilities, prefersReducedMotion };
+
+    _injectDefaults();
     refresh();
     // Re-apply when an equip/unequip happens anywhere (shop screen, capability
     // command from a plugin).

static/v3/v3.css

@@ -4,6 +4,12 @@
  * `fb` palette in tailwind.config.js.
  */
 
+/* Interface-size (Accessibility): the always-present UI-scale token. JS
+   (capabilities/interface-scale.js) overrides it on :root and drives the
+   visible scaling through the root font-size; this default keeps
+   `var(--fb-scale)` resolvable for any canvas/CSS consumer even when unset. */
+:root { --fb-scale: 1; }
+
 /* ── Text-selection policy (v3) ──────────────────────────────────────────────
    Accidental drag/double-click selection of app chrome (sidebar, transport, the
    note highway/HUD, buttons, labels) makes the UI look broken and is never
@@ -367,10 +373,15 @@ input, textarea, select,
 }
 #player-hud .v3-upnext .v3-upnext-bar-fill {
     height: 100%;
-    width: 0%;
+    /* Fill is driven via transform: scaleX(0..1) from player-chrome.js —
+       compositor-only, unlike the previous width writes which re-ran
+       layout on every update tick. */
+    width: 100%;
+    transform: scaleX(0);
+    transform-origin: left;
     border-radius: inherit;
     background: linear-gradient(90deg, #22d3ee, #a855f7, #f472b6);
-    transition: width .12s linear;
+    transition: transform .12s linear;
 }
 
 /* — Live performance HUD (top-right, read-only) — */
@@ -599,7 +610,7 @@ html[data-scoreboard="off"] #v3-live-performance-hud { display: none !important;
     align-items: center;
     justify-content: center;
     z-index: 1;
-    font-size: 32px;
+    font-size: 2rem;
     line-height: 1;
 }
 #v3-player-rail .section-practice-control--v3 .section-practice-pill-icon .v3-rail-svg,
@@ -872,7 +883,7 @@ html[data-scoreboard="off"] #v3-live-performance-hud { display: none !important;
     padding: 0 4px;
     display: flex; align-items: center; justify-content: center;
     background: #22d3ee; color: #0f172a;
-    font-size: 10px; font-weight: 800; line-height: 1;
+    font-size: 0.625rem; font-weight: 800; line-height: 1;
     border-radius: 999px; z-index: 2;
 }
 .v3-rail-badge[hidden] { display: none; }
@@ -1114,6 +1125,32 @@ body.font-display { font-family: Rubik, system-ui, sans-serif; }
 .fb-srow-stack .fb-srow-control input[type="text"] { flex: 1 1 auto; min-width: 0; }
 .fb-srow-wide { width: 100%; }
 
+/* Segmented control + fine-tune (Accessibility → Interface size) */
+.fb-seg {
+    display: inline-flex; flex-wrap: wrap; gap: .25rem;
+    background: #0f172a; border: 1px solid rgba(51, 65, 85, .55);
+    border-radius: .7rem; padding: .3rem;
+}
+.fb-seg-btn {
+    appearance: none; border: none; cursor: pointer;
+    padding: .5rem .9rem; min-height: 2rem; border-radius: .5rem;
+    font-size: .82rem; font-weight: 600; color: #94a3b8; background: transparent;
+    transition: background .15s, color .15s;
+}
+.fb-seg-btn:hover { color: #e2e8f0; }
+.fb-seg-btn.active { background: #0ea5e9; color: #04263a; }
+.fb-seg-btn:focus-visible { outline: 2px solid #38bdf8; outline-offset: 2px; }
+.fb-finetune { margin-top: .6rem; }
+.fb-finetune > summary {
+    font-size: .78rem; font-weight: 600; color: #94a3b8; cursor: pointer;
+    list-style: none; display: inline-flex; align-items: center; gap: .35rem;
+}
+.fb-finetune > summary::-webkit-details-marker { display: none; }
+.fb-finetune > summary::before { content: "\25B8"; font-size: .7rem; transition: transform .15s; }
+.fb-finetune[open] > summary::before { transform: rotate(90deg); }
+.fb-finetune-body { display: flex; align-items: center; gap: 1rem; margin-top: .6rem; }
+.fb-seg-val { font-size: .8rem; color: #94a3b8; min-width: 3rem; text-align: right; }
+
 /* Toggle switch */
 .fb-switch { position: relative; display: inline-block; width: 2.6rem; height: 1.5rem; flex: none; }
 .fb-switch input { position: absolute; opacity: 0; width: 0; height: 0; }
@@ -1200,14 +1237,14 @@ html.fb-immersive #v3-main > .screen.active {
    centered. Shown only for the grid view + alphabetical (artist/title) sorts. */
 .v3-azrail {
     position: fixed;
-    right: 2px;
+    right: 4px;                 /* off the very edge so letters aren't clipped */
     top: 50%;
     transform: translateY(-50%);
     z-index: 25;
     display: flex;
     flex-direction: column;
-    align-items: center;
-    max-height: 84vh;
+    align-items: stretch;       /* equal-width buttons → one wide, even hit column */
+    max-height: 92vh;
     padding: 4px 1px;
     user-select: none;
     -webkit-user-select: none;
@@ -1219,17 +1256,23 @@ html.fb-immersive #v3-main > .screen.active {
     background: none;
     border: 0;
     color: #94a3b8;              /* fb-textDim */
-    font-size: .62rem;
+    /* Scale with viewport height so the 27-letter rail grows on tall / hi-res
+       displays (a fixed size looked tiny at 1440p) while still fitting 27 rows
+       within max-height on short screens. */
+    font-size: clamp(.72rem, 1.4vh, 1.05rem);
     font-weight: 700;
-    line-height: 1.05;
-    padding: 1px 4px;
+    line-height: 1.04;
+    /* Vertical padding fattens the tap target (was ~13px tall → easy to miss). */
+    padding: clamp(2px, .55vh, 6px) 9px;
     margin: 0;
     cursor: pointer;
     border-radius: 4px;
+    text-align: center;
 }
 .v3-azrail-letter:hover:not([disabled]),
 .v3-azrail-letter.is-active {
     color: #0ea5e9;             /* fb-primary */
+    background: rgba(14, 165, 233, .15); /* visible target under the scrub */
 }
 .v3-azrail-letter:focus-visible {
     outline: 2px solid #38bdf8; /* fb-primaryHi */
@@ -1242,7 +1285,7 @@ html.fb-immersive #v3-main > .screen.active {
 /* Drag indicator bubble (Android fast-scroll pattern). */
 .v3-azbubble {
     position: fixed;
-    right: 2.6rem;
+    right: 2.9rem;              /* clear the (now wider) rail */
     top: 50%;
     transform: translateY(-50%);
     z-index: 26;
@@ -1264,7 +1307,7 @@ html.fb-immersive #v3-main > .screen.active {
 /* Coarse-pointer / short viewports: the 27-letter rail can crowd a phone edge.
    Tighten it; a collapse-to-anchors pass is a follow-up. */
 @media (max-height: 640px) {
-    .v3-azrail-letter { font-size: .55rem; padding: 0 4px; }
+    .v3-azrail-letter { font-size: clamp(.5rem, 1.3vh, .62rem); padding: 0 7px; }
 }
 
 /* — Practice-aware library home: repertoire meter + "Keep practicing" shelf — */

tests/js/drum_keys_highway_3d_resize_reframe.test.js

@@ -0,0 +1,83 @@
+// Pins the auto-reframe-on-layout-drift behaviour ported into the drum and
+// keys 3D highway renderers from plugins/highway_3d/screen.js.
+//
+// Bug it guards against: under splitscreen the host resizes each panel's
+// canvas but overrides hw.resize and never calls renderer.resize(). The
+// guitar/bass highway_3d self-detects this in draw(); the drum and keys
+// highways originally only re-framed when the host called resize(w,h), so
+// their panels did NOT resize when the app went fullscreen — they stayed
+// framed for the pre-fullscreen size while the guitar/bass panels adapted.
+//
+// The fix ports highway_3d's per-frame drift check into both draw() loops:
+// compare the live canvas backing store (canvas.width/height) AND the CSS box
+// (clientWidth/Height) against the last applied logical size, re-running
+// applySize() on either drift. A refactor that drops this check, stops
+// recording _appliedW/_appliedH, or reverts to resize()-only sizing would
+// silently bring the fullscreen-split bug back.
+//
+// Source-level only — same strategy as highway_3d_resize_reframe.test.js.
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const PLUGINS = path.join(__dirname, '..', '..', 'plugins');
+const CASES = [
+    { name: 'drum_highway_3d', file: path.join(PLUGINS, 'drum_highway_3d', 'screen.js') },
+    { name: 'keys_highway_3d', file: path.join(PLUGINS, 'keys_highway_3d', 'screen.js') },
+];
+
+for (const { name, file } of CASES) {
+    const src = fs.readFileSync(file, 'utf8');
+
+    test(`${name}: applied-size tracking is declared as instance state`, () => {
+        assert.match(
+            src,
+            /let\s+_appliedW\s*=\s*0\s*,\s*_appliedH\s*=\s*0\s*;/,
+            '_appliedW / _appliedH must be declared as per-instance state',
+        );
+        assert.match(
+            src,
+            /let\s+_lastHwW\s*=\s*0\s*,\s*_lastHwH\s*=\s*0\s*;/,
+            '_lastHwW / _lastHwH must be declared as per-instance state',
+        );
+    });
+
+    test(`${name}: applySize records the logical w/h it applied`, () => {
+        assert.match(
+            src,
+            /_appliedW\s*=\s*[wW]\s*;\s*_appliedH\s*=\s*[hH]\s*;/,
+            'applySize must record _appliedW / _appliedH',
+        );
+    });
+
+    test(`${name}: draw() preserves the backing-store drift branch (splitscreen path)`, () => {
+        assert.match(
+            src,
+            /const\s+_bsChanged\s*=\s*highwayCanvas\.width\s*!==\s*_lastHwW\s*\|\|\s*highwayCanvas\.height\s*!==\s*_lastHwH\s*;/,
+            'the backing-store (canvas.width/height) comparison must run every frame',
+        );
+        assert.match(
+            src,
+            /if\s*\(\s*_bsChanged\s*\)\s*\{\s*_lastHwW\s*=\s*highwayCanvas\.width\s*;\s*_lastHwH\s*=\s*highwayCanvas\.height\s*;[\s\S]*?applySize\(\s*_bw\s*,\s*_bh\s*\)\s*;/,
+            'the backing-store drift branch must re-apply',
+        );
+    });
+
+    test(`${name}: draw() re-applies on CSS-box drift without a backing-store change`, () => {
+        assert.match(
+            src,
+            /else if\s*\(\s*_bw\s*>\s*0\s*&&\s*_bh\s*>\s*0\s*&&\s*\(\s*Math\.abs\(\s*_bw\s*-\s*_appliedW\s*\)\s*>\s*1\s*\|\|\s*Math\.abs\(\s*_bh\s*-\s*_appliedH\s*\)\s*>\s*1\s*\)\s*\)\s*\{\s*applySize\(\s*_bw\s*,\s*_bh\s*\)\s*;/,
+            'draw() must re-apply when the live box drifts >1px from _appliedW/_appliedH',
+        );
+    });
+
+    test(`${name}: destroy() resets the applied-size tracking`, () => {
+        assert.match(
+            src,
+            /_lastHwW\s*=\s*0\s*;\s*_lastHwH\s*=\s*0\s*;\s*_appliedW\s*=\s*0\s*;\s*_appliedH\s*=\s*0\s*;/,
+            'destroy() must reset the drift-tracking state to 0',
+        );
+    });
+}

tests/js/handshapes_pipeline.test.js

@@ -62,7 +62,7 @@ test('bundle exposes handShapes to renderers with flat-list fallback', () => {
     const src = fs.readFileSync(HIGHWAY_JS, 'utf8');
     assert.match(
         src,
-        /\bhandShapes:\s*\([^)]*_filteredHandShapes[^)]*\)\s*\?\s*_filteredHandShapes\s*:\s*handShapes\b/,
+        /\bhandShapes\s*[:=]\s*\([^)]*_filteredHandShapes[^)]*\)\s*\?\s*_filteredHandShapes\s*:\s*handShapes\b/,
         'bundle must expose handShapes with the _filteredHandShapes-vs-handShapes ternary fallback',
     );
 });

tests/js/highway_3d_lefty.test.js

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

tests/js/highway_3d_resize_reframe.test.js

@@ -61,10 +61,25 @@ test('draw() reads the live canvas box once per frame', () => {
 test('backing-store drift branch is preserved (splitscreen path)', () => {
     // The original check that catches the splitscreen hw.resize override
     // resizing the element without calling renderer.resize() must remain.
+    // The comparison is hoisted into _bsChanged (checked with cheap property
+    // reads every frame, and it forces the throttled box read to run on the
+    // same frame); the branch body is unchanged.
     assert.match(
         src,
-        /if\s*\(\s*highwayCanvas\.width\s*!==\s*_lastHwW\s*\|\|\s*highwayCanvas\.height\s*!==\s*_lastHwH\s*\)\s*\{\s*_lastHwW\s*=\s*highwayCanvas\.width\s*;\s*_lastHwH\s*=\s*highwayCanvas\.height\s*;\s*if\s*\(\s*box\.w\s*>\s*0\s*&&\s*box\.h\s*>\s*0\s*\)\s*applySize\(\s*box\.w\s*,\s*box\.h\s*\)\s*;/,
-        'the backing-store (canvas.width/height) drift branch must still re-apply',
+        /const\s+_bsChanged\s*=\s*highwayCanvas\.width\s*!==\s*_lastHwW\s*\|\|\s*highwayCanvas\.height\s*!==\s*_lastHwH\s*;/,
+        'the backing-store (canvas.width/height) comparison must run every frame',
+    );
+    assert.match(
+        src,
+        /if\s*\(\s*_bsChanged\s*\)\s*\{\s*_lastHwW\s*=\s*highwayCanvas\.width\s*;\s*_lastHwH\s*=\s*highwayCanvas\.height\s*;\s*if\s*\(\s*box\.w\s*>\s*0\s*&&\s*box\.h\s*>\s*0\s*\)\s*applySize\(\s*box\.w\s*,\s*box\.h\s*\)\s*;/,
+        'the backing-store drift branch must still re-apply',
+    );
+    // The throttle must never delay the backing-store path: _bsChanged is
+    // part of the gate that forces the box read on the same frame.
+    assert.match(
+        src,
+        /if\s*\(\s*_bsChanged\s*\|\|\s*!_wrapPinned\s*\|\|\s*_boxCheckCountdown\s*===\s*0\s*\)/,
+        'the box-read gate must include _bsChanged so backing-store changes re-apply immediately',
     );
 });
 

tests/js/highway_3d_smooth_clock_pause.test.js

@@ -43,13 +43,13 @@ test('core _makeBundle exposes isPlaying derived from the chart-clock anchor', (
     const src = fs.readFileSync(highwayJs, 'utf8');
     const fn = extractBlock(src, 'function _makeBundle()');
     // Field present in the bundle.
-    assert.match(fn, /\bisPlaying\s*:/, 'bundle must expose isPlaying');
+    assert.match(fn, /\bisPlaying\s*[:=]/, 'bundle must expose isPlaying');
     // It is computed from the same anchor/advance state getTime() uses, not a
     // hardcoded literal — anchor must exist AND the clock must have advanced
     // within the interp cap.
     assert.match(
         fn,
-        /isPlaying\s*:\s*!Number\.isNaN\(\s*_chartAnchorPerfNow\s*\)/,
+        /isPlaying\s*[:=]\s*!Number\.isNaN\(\s*_chartAnchorPerfNow\s*\)/,
         'isPlaying must gate on a live anchor (_chartAnchorPerfNow not NaN)',
     );
     assert.match(

tests/js/highway_3d_wide_fov.test.js

@@ -120,11 +120,11 @@ test('applySize caches the pane aspect for camUpdate', () => {
     );
 });
 
-test('camUpdate reads the live tune bridge and respects splitOnly', () => {
+test('camUpdate resolves a per-pane tune and respects splitOnly', () => {
     assert.match(
         src,
-        /const\s+_aspTune\s*=\s*_aspectTune\(\)\s*;[\s\S]*?_aspTune\.splitOnly\s*&&\s*!_ssActive\(\)/,
-        'camUpdate must read the bridge via _aspectTune() and gate splitOnly on _ssActive()',
+        /const\s+_aspTune\s*=\s*_resolveTuneFor\(\s*_paneKey\s*\)\s*;[\s\S]*?_aspTune\.splitOnly\s*&&\s*!_ssActive\(\)/,
+        'camUpdate must resolve the tune per pane via _resolveTuneFor(_paneKey) and gate splitOnly',
     );
 });
 
@@ -136,11 +136,151 @@ test('the tune bridge seeds from localStorage (persisted sessions apply on load)
     );
 });
 
-test('a floating tuner panel is built and toggled with the A/B state', () => {
+test('a floating tuner panel is built and can be shown/hidden', () => {
     assert.match(src, /function\s+_ensureAspectPanel\s*\(\)/,
         '_ensureAspectPanel() must exist to build the live panel');
     assert.match(src, /function\s+_setAspectPanelVisible\s*\(/,
-        '_setAspectPanelVisible() must show/hide the panel with the feature');
+        '_setAspectPanelVisible() must show/hide the panel');
+});
+
+// ── Per-pane targeting ────────────────────────────────────────────────────────
+
+test('the tune resolves per pane with a sparse override map', () => {
+    // _resolveTuneFor overlays a pane's __panels[key] overrides onto the base so
+    // one split pane can be framed independently of the others.
+    assert.match(
+        src,
+        /function\s+_resolveTuneFor\s*\(\s*paneKey\s*\)[\s\S]*?base\.__panels\s*&&\s*base\.__panels\[\s*paneKey\s*\]/,
+        '_resolveTuneFor must overlay per-pane overrides from base.__panels',
+    );
+});
+
+test('panel writes route to the selected target (base or a pane override)', () => {
+    // _aspectWriteVal writes to the base when target is empty, else into the
+    // pane override sub-object; camUpdate consumes it via _resolveTuneFor.
+    assert.match(
+        src,
+        /function\s+_aspectWriteVal\s*\([\s\S]*?if\s*\(\s*!_aspectEditTarget\s*\)[\s\S]*?base\.__panels\b[\s\S]*?\[\s*_aspectEditTarget\s*\]/,
+        '_aspectWriteVal must target base for "all" and __panels[target] for a pane',
+    );
+});
+
+test('a Target select and pane registry drive the per-pane picker', () => {
+    assert.match(src, /_aspectTargetSel\s*=\s*document\.createElement\(\s*'select'\s*\)/,
+        'the panel must build a Target <select>');
+    assert.match(src, /function\s+_aspectRegisterPane\s*\(/,
+        '_aspectRegisterPane must record live panes for the picker');
+    assert.match(src, /if\s*\(\s*window\.__h3dAspectPanelOpen\s*\)\s*_aspectRegisterPane\(\s*_paneKey\s*\)/,
+        'camUpdate must register its pane only while the tuner panel is open');
+});
+
+test('panes are keyed by arrangement (stable across songs, no split-API dep)', () => {
+    // 'arr:<name>' keys are distinct between split panes AND stable across
+    // songs, without depending on the external splitscreen panel index (which
+    // isn't always available). A per-instance id is the no-arrangement fallback.
+    assert.match(
+        src,
+        /function\s+_aspectPaneKey\s*\(\s*arrangement\s*,\s*uid\s*\)[\s\S]*?'arr:'\s*\+\s*a[\s\S]*?'pane:'\s*\+\s*uid/,
+        '_aspectPaneKey must prefer arr:<name> and fall back to pane:<uid>',
+    );
+    assert.match(
+        src,
+        /const\s+_paneKey\s*=\s*_aspectPaneKey\(\s*[\s\S]*?songInfo[\s\S]*?arrangement\s*,\s*_paneUid\s*\)\s*;/,
+        'camUpdate must key the pane by arrangement (with the uid fallback)',
+    );
+});
+
+test('arrangement-keyed overrides persist; instance-id keys stay session-only', () => {
+    assert.match(
+        src,
+        /function\s+_aspectPersist\s*\(\)[\s\S]*?k\.slice\(0,\s*4\)\s*===\s*'arr:'[\s\S]*?out\.__panels\s*=\s*p/,
+        '_aspectPersist must persist only arr:* overrides so they carry across songs',
+    );
+});
+
+test('the target dropdown prunes dead panes and does not rebuild while focused', () => {
+    assert.match(src, /function\s+_aspectPrunePanes\s*\(\)[\s\S]*?delete\s+reg\[k\]/,
+        '_aspectPrunePanes must drop panes not seen recently');
+    assert.match(src, /_aspectPrunePanes\(\)\s*;[\s\S]*?if\s*\(\s*_aspectPanesDirty\s*\)\s*_aspectBuildTargets\(\)/,
+        'the readout tick must prune then rebuild only when dirty');
+    assert.match(src, /function\s+_aspectBuildTargets\s*\(\)[\s\S]*?document\.activeElement\s*===\s*_aspectTargetSel[\s\S]*?return/,
+        '_aspectBuildTargets must skip rebuilding while the select is focused');
+});
+
+test('programmatic sync does not write back into the tune', () => {
+    // _syncAspectPanel dispatches synthetic input events to refresh labels; the
+    // slider handler must skip the write while syncing, else opening/switching a
+    // target would populate a full override for every field.
+    assert.match(src, /_aspectSyncing\s*=\s*true[\s\S]*?finally[\s\S]*?_aspectSyncing\s*=\s*false/,
+        '_syncAspectPanel must set/reset the _aspectSyncing guard');
+    assert.match(src, /if\s*\(\s*!_aspectSyncing\s*\)\s*_aspectWriteVal\(\s*f\.k\s*,/,
+        'the slider input handler must skip the write while syncing');
+});
+
+test('unchecking hfov override clears a pane override key (re-inherits base)', () => {
+    assert.match(
+        src,
+        /function\s+_aspectClearVal\s*\(\s*k\s*\)[\s\S]*?delete\s+ov\[k\][\s\S]*?delete\s+m\[\s*_aspectEditTarget\s*\]/,
+        '_aspectClearVal must delete the pane override key (and empty object)',
+    );
+    assert.match(src, /else\s+_aspectClearVal\(\s*'hfovDeg'\s*\)/,
+        'unchecking the hfov override must call _aspectClearVal');
+});
+
+test('pruning drops the matching readout slot and a dangling __last', () => {
+    assert.match(
+        src,
+        /delete\s+reg\[k\]\s*;[\s\S]*?delete\s+ro\[k\]\s*;\s*if\s*\(\s*ro\.__last\s*===\s*k\s*\)\s*delete\s+ro\.__last/,
+        '_aspectPrunePanes must prune the readout cache alongside the registry',
+    );
+});
+
+test('single-pane forces the edit target back to All (no hidden pane edits)', () => {
+    assert.match(
+        src,
+        /if\s*\(\s*keys\.length\s*<=\s*1\s*\|\|\s*\(\s*_aspectEditTarget\s*&&\s*!reg\[_aspectEditTarget\]\s*\)\s*\)\s*\{\s*_aspectEditTarget\s*=\s*''/,
+        '_aspectBuildTargets must reset the edit target to "" when the Target row is hidden',
+    );
+});
+
+test('resolved per-pane tune is memoized and invalidated by a revision', () => {
+    assert.match(src, /_aspectRev\s*\+\+/, 'a mutation revision must be bumped on persist');
+    assert.match(
+        src,
+        /_aspectResolveCache\.get\(\s*paneKey\s*\)[\s\S]*?c\.rev\s*===\s*_aspectRev[\s\S]*?return\s+c\.obj/,
+        '_resolveTuneFor must return a cached object when the revision is unchanged',
+    );
+});
+
+test('the pane clock falls back to Date.now so pruning keeps working', () => {
+    assert.match(
+        src,
+        /function\s+_aspectNowMs\s*\(\)[\s\S]*?performance\.now\(\)[\s\S]*?return\s+Date\.now\(\)/,
+        '_aspectNowMs must fall back to Date.now() when the Performance API is absent',
+    );
+});
+
+test('opening the panel prunes before the first dropdown build', () => {
+    assert.match(
+        src,
+        /if\s*\(\s*on\s*\)\s*\{\s*_aspectPrunePanes\(\)\s*;\s*_aspectBuildTargets\(\)/,
+        '_setAspectPanelVisible must prune stale panes before building the dropdown',
+    );
+});
+
+test('Reset on All restores defaults exactly (no forced enabled)', () => {
+    // Panel visibility is independent of the enabled flag now, so Reset must not
+    // force enabled true — it should restore _ASPECT_DEFAULTS verbatim.
+    assert.doesNotMatch(src, /Object\.keys\(_ASPECT_DEFAULTS\)[\s\S]*?base\.enabled\s*=\s*true/,
+        'Reset must not override the default enabled state');
+});
+
+test('the panel has a dismiss (close) control', () => {
+    assert.match(
+        src,
+        /close\.textContent\s*=\s*'×'[\s\S]*?_setAspectPanelVisible\(\s*false\s*\)/,
+        'the panel header must have a × button that hides the panel',
+    );
 });
 
 test('camUpdate only writes cam.fov when it actually changes', () => {
@@ -153,14 +293,16 @@ test('camUpdate only writes cam.fov when it actually changes', () => {
     );
 });
 
-// ── A/B toggle + lifecycle reset ──────────────────────────────────────────────
+// ── Shortcut (open/close) + lifecycle reset ───────────────────────────────────
 
-test('an A/B toggle shortcut flips the tune enabled flag', () => {
+test('the shortcut opens/closes the tuner panel', () => {
     assert.match(
         src,
-        /registerShortcut\(\{[\s\S]*?const\s+t\s*=\s*_aspectTune\(\)\s*;[\s\S]*?t\.enabled\s*=\s*!\s*t\.enabled/,
-        'a registerShortcut handler must toggle the bridge enabled flag',
+        /registerShortcut\(\{[\s\S]*?_toggleAspectPanel\(\)/,
+        'a registerShortcut handler must toggle the tuner panel',
     );
+    assert.match(src, /function\s+_toggleAspectPanel\s*\(\)/,
+        '_toggleAspectPanel() must exist to reveal/dismiss the panel');
 });
 
 test('destroy() resets the pane aspect and restores the base fov', () => {

tests/js/highway_adaptive_scale.test.js

@@ -82,7 +82,7 @@ test('draw() only adapts during active playback and feeds the HUD', () => {
 
 test('bundle + canvas sizing use the effective scale, not the raw user value', () => {
     const src = fs.readFileSync(highwayJs, 'utf8');
-    assert.match(src, /renderScale:\s*_effectiveRenderScale\(\)/, 'bundle.renderScale must be the effective scale');
+    assert.match(src, /renderScale\s*[:=]\s*_effectiveRenderScale\(\)/, 'bundle.renderScale must be the effective scale');
     assert.match(src, /canvas\.width\s*=\s*Math\.round\(w\s*\*\s*_effectiveRenderScale\(\)\)/, 'canvas backing store must use effective scale');
 });
 

tests/js/highway_note_state.test.js

@@ -51,7 +51,7 @@ test('_makeBundle exposes getNoteState (stable reference, no per-frame alloc)',
     const fn = extractBlock(src, 'function _makeBundle()');
     // The bundle field must point straight at _noteState — not a fresh
     // arrow each frame (the per-frame allocation the review flagged).
-    assert.match(fn, /getNoteState:\s*_noteState\b/, 'bundle.getNoteState must be the stable _noteState reference');
+    assert.match(fn, /getNoteState\s*[:=]\s*_noteState\b/, 'bundle.getNoteState must be the stable _noteState reference');
 });
 
 test('_makeBundle exposes getNoteStateProvider as a stable reference (feedBack#254)', () => {
@@ -64,7 +64,7 @@ test('_makeBundle exposes getNoteStateProvider as a stable reference (feedBack#2
     // identity-based guards in renderer code.
     assert.match(
         fn,
-        /getNoteStateProvider:\s*_getNoteStateProvider\b/,
+        /getNoteStateProvider\s*[:=]\s*_getNoteStateProvider\b/,
         'bundle.getNoteStateProvider must be the stable _getNoteStateProvider reference (not a per-frame arrow)'
     );
     // Sanity: the stable accessor exists per-createHighway-instance

tests/js/play_queue_peek.test.js

@@ -0,0 +1,51 @@
+// playQueue.peekNext() (queue-advance UX): consumers that render "Up next"
+// (the results card's countdown strip) need to know WHAT follows without
+// reaching into queue internals. 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, arr, opts }),
+            fbNotify: null,
+        },
+        encodeURIComponent,
+    };
+    // eslint-disable-next-line no-new-func
+    new Function('window', 'encodeURIComponent', iife)(sandbox.window, encodeURIComponent);
+    return { q: sandbox.window.feedBack.playQueue, played };
+}
+
+test('peekNext exposes the following track without mutating the queue', () => {
+    const { q, played } = makeQueue();
+    assert.strictEqual(q.peekNext(), null);              // idle queue → null
+    q.start(['a.sloppak', 'b.sloppak', 'c.sloppak'], { source: 'My list' });
+    assert.deepStrictEqual(q.peekNext(), { filename: 'b.sloppak', index: 1, total: 3 });
+    assert.deepStrictEqual(q.peekNext(), { filename: 'b.sloppak', index: 1, total: 3 }); // pure
+    assert.strictEqual(played.length, 1);                // peeking never plays
+    q.advance();
+    assert.deepStrictEqual(q.peekNext(), { filename: 'c.sloppak', index: 2, total: 3 });
+    q.advance();
+    assert.strictEqual(q.peekNext(), null);              // last track → nothing next
+    assert.strictEqual(q.remaining(), 0);
+});
+
+test('peekNext is null after clear', () => {
+    const { q } = makeQueue();
+    q.start(['a.sloppak', 'b.sloppak']);
+    q.clear();
+    assert.strictEqual(q.peekNext(), null);
+});

tests/js/speed_reset.test.js

@@ -148,6 +148,7 @@ function loadPlaySong(sandbox) {
         var _playerOriginScreen = null;
         var _pendingAutostart = false;
         function _clearAutoExit() {}
+        function _clearAutoplayHold() {}
         function _resolvePlayerOrigin() { return 'home'; }
         function _recordPlaybackBridge() {}
         function _cancelCountIn() {}

tests/js/tuner_auto_open.test.js

@@ -8,6 +8,8 @@ const vm = require('node:vm');
 
 const APP_JS = path.join(__dirname, '..', '..', 'static', 'app.js');
 const TUNER_SCREEN_JS = path.join(__dirname, '..', '..', 'plugins', 'tuner', 'screen.js');
+const TUNING_UTILS_JS = path.join(__dirname, '..', '..', 'plugins', 'tuner', 'utils', 'tuning-utils.js');
+const TUNER_UI_JS = path.join(__dirname, '..', '..', 'plugins', 'tuner', 'utils', 'ui.js');
 
 function loadTuningHelpers() {
     const src = fs.readFileSync(APP_JS, 'utf8');
@@ -26,7 +28,14 @@ function loadTuningHelpers() {
 
 const feedBackHelpers = loadTuningHelpers();
 
-function createTunerSandbox() {
+function createTunerSandbox(opts) {
+    // Auto-open is opt-in (default off in prod). The sandbox defaults it ON so the
+    // behaviour tests exercise the feature; pass { autoOpen: false } to gate it off.
+    const autoOpen = !opts || opts.autoOpen !== false;
+    // The player's physical instrument for the §4 coverage check (core /api/settings).
+    // Absent → the endpoint reports not-ok → coverage stays conservative (can't
+    // decide → don't suppress the prompt), preserving the pre-coverage behaviour.
+    const playerSettings = (opts && opts.player) || null;
     const enableCalls = [];
     let playerActive = true;
     let songInfo = null;
@@ -38,16 +47,21 @@ function createTunerSandbox() {
         setTimeout(fn) { fn(); return 0; },
         clearTimeout() {},
         fetch(url) {
-            if (String(url).includes('/config')) {
+            const _u = String(url);
+            if (_u.includes('/api/settings')) {
+                return Promise.resolve(playerSettings
+                    ? { ok: true, json: () => Promise.resolve(playerSettings) }
+                    : { ok: false, json: () => Promise.resolve({}) });
+            }
+            if (_u.includes('/config')) {
                 return Promise.resolve({
                     json: () => Promise.resolve({
-                        showFloatingButton: true,
                         visualizationMode: 'default',
                         audioInputMode: 'auto',
+                        autoOpenOnTuningChange: autoOpen,
                         lastInstrument: 'guitar-6',
                         lastTuning: 'Standard',
                         freeTune: false,
-                        disabledTunings: [],
                         customTunings: {},
                     }),
                 });
@@ -120,12 +134,8 @@ function createTunerSandbox() {
     sandbox.window.highway = {
         getSongInfo: () => songInfo,
     };
-    sandbox.window._tunerUtils = {
-        preferFlats: () => false,
-        offsetsToFreqs: (offsets) => offsets.map((o, i) => 80 + i * 10),
-        freqToMidi: () => 40,
-        midiToNote: () => 'E',
-    };
+    // _tunerUtils comes from the REAL tuning-utils.js (loaded into the sandbox
+    // below) so the §4 coverage check runs real pitch math, not stubbed values.
     sandbox.window._tunerUI = () => ({
         addButton() {},
         initUI() {},
@@ -152,12 +162,13 @@ function createTunerSandbox() {
     });
 
     vm.createContext(sandbox);
+    vm.runInContext(fs.readFileSync(TUNING_UTILS_JS, 'utf8'), sandbox);
     vm.runInContext(fs.readFileSync(TUNER_SCREEN_JS, 'utf8'), sandbox);
 
     const realEnable = sandbox.window.tuner.enable.bind(sandbox.window.tuner);
-    sandbox.window.tuner.enable = async () => {
-        enableCalls.push(1);
-        return realEnable();
+    sandbox.window.tuner.enable = async (enableOpts) => {
+        enableCalls.push(enableOpts || {});
+        return realEnable(enableOpts);
     };
 
     return sandbox;
@@ -315,6 +326,37 @@ test('song:loading clears dismiss state for next load', async () => {
     assert.equal(sandbox.__enableCalls.length, 2);
 });
 
+test('auto-open is gated off when the setting is disabled (opt-in)', async () => {
+    const sandbox = createTunerSandbox({ autoOpen: false });
+    sandbox.window._tunerAutoOpen.resetState();
+    await ready(sandbox, CUSTOM_GUITAR);
+    await ready(sandbox, E_STANDARD);   // a real tuning change, but the setting is off
+    assert.equal(sandbox.__enableCalls.length, 0);
+});
+
+test('auto-open enables in persist mode (passes { auto: true })', async () => {
+    const sandbox = createTunerSandbox();
+    sandbox.window._tunerAutoOpen.resetState();
+    await ready(sandbox, CUSTOM_GUITAR);
+    await ready(sandbox, E_STANDARD);
+    assert.equal(sandbox.__enableCalls.length, 1);
+    assert.equal(sandbox.__enableCalls[0].auto, true);
+});
+
+test('persist: an auto-opened tuner is not torn down by autoplay / stray clicks', () => {
+    const screenSrc = fs.readFileSync(TUNER_SCREEN_JS, 'utf8');
+    const uiSrc = fs.readFileSync(
+        path.join(__dirname, '..', '..', 'plugins', 'tuner', 'utils', 'ui.js'), 'utf8');
+    // The gate is opt-in on the server config flag.
+    assert.match(screenSrc, /autoOpenOnTuningChange/);
+    // enable() records whether this was an auto-open …
+    assert.match(screenSrc, /_state\.autoOpened\s*=\s*auto/);
+    // … the outside-click dismiss is armed only for a manual open …
+    assert.match(screenSrc, /if \(!auto\)[\s\S]*?addEventListener\('click'/);
+    // … and the autoplay song:play closer ignores an auto-opened tuner (the flash fix).
+    assert.match(uiSrc, /state\.enabled && !state\.autoOpened/);
+});
+
 test('screen.js registers song:loading and song:ready auto-open listeners at boot', () => {
     const src = fs.readFileSync(TUNER_SCREEN_JS, 'utf8');
     assert.match(src, /function _installAutoOpenListeners/);
@@ -324,7 +366,400 @@ test('screen.js registers song:loading and song:ready auto-open listeners at boo
     assert.doesNotMatch(src, /restartCurrentSong/);
 });
 
+// ── §4 instrument-coverage (E1.5) ──────────────────────────────────────────
+// Player physical instruments (core /api/settings shape: instrument/string_count/
+// tuning offsets/reference_pitch).
+const PLAYER_GUITAR_8_FS = { instrument: 'guitar', string_count: 8, tuning: [0, 0, 0, 0, 0, 0, 0, 0], reference_pitch: 440 }; // F# standard
+const PLAYER_GUITAR_6 = { instrument: 'guitar', string_count: 6, tuning: [0, 0, 0, 0, 0, 0], reference_pitch: 440 };          // E standard
+const SONG_7B = { filename: '7b.sloppak', arrangement: 'Lead', arrangement_index: 0, stringCount: 7, tuning: [0, 0, 0, 0, 0, 0, 0] };           // B standard 7
+const SONG_DROP_A7 = { filename: 'dropa7.sloppak', arrangement: 'Lead', arrangement_index: 0, stringCount: 7, tuning: [-2, 0, 0, 0, 0, 0, 0] }; // Drop A 7
+
+test('coverage: an 8-string F# player is NOT prompted for a covered 6-/7-string standard song', async () => {
+    const sandbox = createTunerSandbox({ player: PLAYER_GUITAR_8_FS });
+    sandbox.window._tunerAutoOpen.resetState();
+    await ready(sandbox, DROP_D);        // first song → sets lastTuningKey, no open
+    await ready(sandbox, E_STANDARD);    // 6-E lives on the 8-string's top 6 → suppressed
+    assert.equal(sandbox.__enableCalls.length, 0);
+    await ready(sandbox, SONG_7B);       // 7-B lives on the 8-string's top 7 → suppressed
+    assert.equal(sandbox.__enableCalls.length, 0);
+});
+
+test('coverage: a Drop-A 7-string song STILL prompts the 8-string F# player (dropped string absent)', async () => {
+    const sandbox = createTunerSandbox({ player: PLAYER_GUITAR_8_FS });
+    sandbox.window._tunerAutoOpen.resetState();
+    await ready(sandbox, E_STANDARD);    // first → no open
+    await ready(sandbox, SONG_DROP_A7);  // needs an open A1; the 8-string has F#1/B1, not A1 → prompt
+    assert.equal(sandbox.__enableCalls.length, 1);
+});
+
+test('coverage: a 6-string-standard player IS prompted for Drop D', async () => {
+    const sandbox = createTunerSandbox({ player: PLAYER_GUITAR_6 });
+    sandbox.window._tunerAutoOpen.resetState();
+    await ready(sandbox, E_STANDARD);    // first → no open
+    await ready(sandbox, DROP_D);        // low E must drop to D → not covered → prompt
+    assert.equal(sandbox.__enableCalls.length, 1);
+});
+
+test('coverage: a reference-pitch mismatch (A432 player vs A440 song) prompts even when the shape matches', async () => {
+    const sandbox = createTunerSandbox({ player: { ...PLAYER_GUITAR_6, reference_pitch: 432 } });
+    sandbox.window._tunerAutoOpen.resetState();
+    await ready(sandbox, DROP_D);        // first → no open
+    await ready(sandbox, E_STANDARD);    // shape matches, but the whole instrument is ~32¢ flat → prompt
+    assert.equal(sandbox.__enableCalls.length, 1);
+});
+
+test('coverage: covered/uncovered is decided by contiguous pitch alignment (direct)', async () => {
+    const sandbox = createTunerSandbox({ player: PLAYER_GUITAR_8_FS });
+    const cover = (song) => sandbox.window._tunerAutoOpen.coveredByPlayerInstrument(song);
+    assert.equal(await cover(E_STANDARD), true);     // 6-E is a run inside 8-string F#
+    assert.equal(await cover(SONG_7B), true);        // 7-B is a run inside 8-string F#
+    assert.equal(await cover(SONG_DROP_A7), false);  // Drop-A's low A1 isn't an open string on it
+});
+
+test('coverage: with no declared instrument it stays conservative (prompts as before)', async () => {
+    const sandbox = createTunerSandbox();   // no /api/settings instrument
+    sandbox.window._tunerAutoOpen.resetState();
+    await ready(sandbox, CUSTOM_GUITAR);
+    await ready(sandbox, E_STANDARD);
+    assert.equal(sandbox.__enableCalls.length, 1);
+});
+
+// ── §4 coverage report + badge cue (E1.6) ──────────────────────────────────
+test('coverage report names the string(s) to retune', async () => {
+    // Note: report objects come from the vm sandbox realm, so compare fields, not
+    // deepStrictEqual (which checks prototype identity across realms).
+    const sandbox = createTunerSandbox({ player: PLAYER_GUITAR_8_FS });
+    const rep = (s) => sandbox.window._tunerAutoOpen.coverageReport(s);
+    const covered = await rep(E_STANDARD);
+    assert.equal(covered.covered, true);
+    assert.equal(covered.retune.length, 0);
+    assert.equal(covered.reference, false);
+    const dropA = await rep(SONG_DROP_A7);
+    assert.equal(dropA.covered, false);
+    assert.equal(dropA.retune.length, 1);
+    assert.equal(dropA.retune[0].from, 'B');   // the user's exact case → "retune B → A"
+    assert.equal(dropA.retune[0].to, 'A');
+});
+
+test('coverage report flags a whole-instrument reference mismatch', async () => {
+    const sandbox = createTunerSandbox({ player: { ...PLAYER_GUITAR_6, reference_pitch: 432 } });
+    const rep = await sandbox.window._tunerAutoOpen.coverageReport(E_STANDARD);
+    assert.equal(rep.covered, false);
+    assert.equal(rep.reference, true);
+});
+
+test('the tuner badge surfaces a passive coverage cue (badges.js)', () => {
+    const badgesSrc = fs.readFileSync(
+        path.join(__dirname, '..', '..', 'static', 'v3', 'badges.js'), 'utf8');
+    // Recomputes via the tuner plugin's coverageReport on song:ready …
+    assert.match(badgesSrc, /api\.coverageReport/);
+    assert.match(badgesSrc, /sm\.on\('song:ready'/);
+    // … and shows an advisory ring + tooltip naming the retune (it never auto-opens).
+    assert.match(badgesSrc, /function _applyCoverageCue/);
+    assert.match(badgesSrc, /report\.retune/);
+    assert.match(badgesSrc, /boxShadow/);
+});
+
+// ── Autoplay gate (E2) ─────────────────────────────────────────────────────
+test('gate: claims an autoplay hold on song:loading and releases it on dismiss', async () => {
+    const sandbox = createTunerSandbox({ player: PLAYER_GUITAR_6 });
+    let holds = 0, releases = 0;
+    sandbox.window.feedBack.holdAutoplay = () => { holds++; return () => { releases++; }; };
+    const api = sandbox.window._tunerAutoOpen;
+    await ready(sandbox, DROP_D);        // loads config (feature on)
+    api.resetState();
+    api.onSongLoading();                 // song:loading → claim the gate
+    assert.equal(holds, 1);
+    assert.equal(releases, 0);
+    sandbox.window.tuner.disable();      // dismiss → release (playback proceeds)
+    assert.equal(releases, 1);
+});
+
+test('gate: does not claim a hold when the feature is off', async () => {
+    const sandbox = createTunerSandbox({ player: PLAYER_GUITAR_6, autoOpen: false });
+    let holds = 0;
+    sandbox.window.feedBack.holdAutoplay = () => { holds++; return () => {}; };
+    const api = sandbox.window._tunerAutoOpen;
+    await ready(sandbox, DROP_D);        // loads config (feature OFF)
+    api.onSongLoading();
+    assert.equal(holds, 0);
+});
+
+test('the autoplay gate is a generic core hook with a fail-open backstop (app.js)', () => {
+    const appSrc = fs.readFileSync(APP_JS, 'utf8');
+    assert.match(appSrc, /window\.feedBack\.holdAutoplay = function/);
+    assert.match(appSrc, /AUTOPLAY_HOLD_BACKSTOP_MS/);                       // fail-open: never strand the song
+    assert.match(appSrc, /if \(_autoplayHeld\) \{ _autoplayStart = start;/); // a gated start is stashed
+    assert.match(appSrc, /_clearAutoplayHold\(\);[\s\S]{0,160}emit\('song:loading'/); // reset before plugins re-claim
+    // Per-hold identity: a stale release from an earlier hold must not clear a later one.
+    assert.match(appSrc, /token !== _autoplayHoldToken/);
+    // settle(): a committed holder can cancel the fail-open backstop (no timed release).
+    assert.match(appSrc, /release\.settle = function/);
+    // The hook is generic — app.js still doesn't reference the tuner's internals.
+    assert.doesNotMatch(appSrc, /_tunerAutoOpen|maybeAutoOpenOnTuningChange/);
+});
+
+test('the tuner gates playback via holdAutoplay (screen.js)', () => {
+    const src = fs.readFileSync(TUNER_SCREEN_JS, 'utf8');
+    assert.match(src, /window\.feedBack\.holdAutoplay\(\)/);     // claimed on song:loading
+    assert.match(src, /_gateClaimed = true/);                   // kept when the tuner opens
+    assert.match(src, /if \(!_gateClaimed\) _releaseGate\(\)/);  // released when we don't open
+    assert.match(src, /_releaseGate\(\);[\s\S]{0,80}dismissing a gated/); // released on dismiss
+    // Once open, the tuner settles the hold so the 12s backstop can't start playback
+    // while the player is still tuning.
+    assert.match(src, /_autoplayRelease\.settle\(\)/);
+    // The async song:ready handler is generation-guarded so it can't release a NEWER
+    // song's gate after its await.
+    assert.match(src, /_onAutoOpenSongReady = async \(\) => \{[\s\S]{0,320}myGen !== _autoOpenGeneration\) return;[\s\S]{0,120}_releaseGate/);
+});
+
+test('gate escape hatch: auto-open offers "Back to library" (+ Esc) and hides the × (ui.js/screen.js)', () => {
+    const ui = fs.readFileSync(TUNER_UI_JS, 'utf8');
+    assert.match(ui, /Back to library/);          // an explicit way out, not only play-now
+    assert.match(ui, /requestExitSong/);          // reuses the standard song-exit path (mirrors Esc)
+    assert.match(ui, /state\.backBtn =/);
+    assert.match(ui, /state\.closeBtn =/);        // × captured so it can be toggled
+
+    const screen = fs.readFileSync(TUNER_SCREEN_JS, 'utf8');
+    assert.match(screen, /_state\.backBtn[\s\S]{0,60}toggle\('hidden', !auto\)/);   // shown on auto-open
+    assert.match(screen, /_state\.closeBtn[\s\S]{0,60}toggle\('hidden', !!auto\)/); // × hidden on auto-open
+});
+
 test('auto-open does not require app.js changes', () => {
     const appSrc = fs.readFileSync(APP_JS, 'utf8');
     assert.doesNotMatch(appSrc, /_tunerAutoOpen|maybeAutoOpenOnTuningChange/);
 });
+
+// ── PR 3: per-instrument live working tuning (the both-directions fix) ──────
+test('coverage reads the live per-instrument working tuning, so it prompts BOTH directions', async () => {
+    // GUITAR-6 selected; the player's LIVE working tuning is Drop-D (they retuned).
+    const sandbox = createTunerSandbox({ player: { instrument: 'guitar', string_count: 6, tuning: 'Standard' } });
+    sandbox.window.feedBack.workingTuning = {
+        get: () => ({ offsets: [-2, 0, 0, 0, 0, 0], stringCount: 6, instrument: 'guitar', referencePitch: 440 }),
+        set() {},
+    };
+    const rep = (s) => sandbox.window._tunerAutoOpen.coverageReport(s);
+    // The Drop-D song now MATCHES the live tuning → covered (no prompt).
+    assert.equal((await rep(DROP_D)).covered, true);
+    // An E-standard song NO LONGER matches (the player is in Drop-D) → not covered →
+    // prompts to tune the low string back UP to E. The old static-profile logic missed
+    // this "coming back" direction entirely.
+    const estd = await rep(E_STANDARD);
+    assert.equal(estd.covered, false);
+    assert.equal(estd.retune.length, 1);
+    assert.equal(estd.retune[0].from, 'D');   // player low string is D…
+    assert.equal(estd.retune[0].to, 'E');     // …song wants E → "tune D → E" (up)
+});
+
+// Wire a set-capturing workingTuning stub, then run a coverage read so the tuner caches
+// the selected-instrument identity (publish is synchronous and writes to that cached
+// slot — an auto-open always runs coverage first, so this mirrors real ordering).
+async function _primeSets(sandbox, get = () => ({ offsets: null })) {
+    const sets = [];
+    sandbox.window.feedBack.workingTuning = { get, set: (state, opts) => sets.push({ state, opts }) };
+    await sandbox.window._tunerAutoOpen.playerTuning();
+    return sets;
+}
+
+test('clearing the auto-opened tuner publishes the song tuning to the right instrument slot', async () => {
+    const sandbox = createTunerSandbox({ player: { instrument: 'guitar', string_count: 6, tuning: 'Standard' } });
+    const sets = await _primeSets(sandbox);
+    sandbox.window._tunerAutoOpen.publishWorkingTuning(DROP_D);
+    assert.equal(sets.length, 1);
+    assert.deepEqual(sets[0].state.offsets, [-2, 0, 0, 0, 0, 0]);   // the song's tuning
+    assert.equal(sets[0].state.instrument, 'guitar');
+    assert.equal(sets[0].opts.instrument, 'guitar-6');             // targets the guitar slot
+    assert.equal(sets[0].opts.provenance, 'assumed');              // a guess, not mic-verified
+});
+
+test('publish targets the SELECTED instrument slot, not a song-derived one (string-count mismatch)', async () => {
+    // A 5-string bass is selected; the cleared song is a 4-string bass chart. The publish
+    // must land in bass-5 (what coverage reads), NOT bass-4 (where it would be stranded).
+    const sandbox = createTunerSandbox({ player: { instrument: 'bass', string_count: 5, tuning: 'Standard' } });
+    const sets = await _primeSets(sandbox);
+    sandbox.window._tunerAutoOpen.publishWorkingTuning(BASS_EADG);
+    assert.equal(sets.length, 1);
+    assert.equal(sets[0].opts.instrument, 'bass-5');   // the selected instrument's slot
+    assert.equal(sets[0].state.instrument, 'bass');
+});
+
+test('publish skips a cross-instrument chart (bass arrangement while guitar is selected)', async () => {
+    // Guitar selected, but the player manually opened the Bass arrangement and cleared.
+    // That is not evidence the guitar was retuned — do not pollute either slot.
+    const sandbox = createTunerSandbox({ player: { instrument: 'guitar', string_count: 6, tuning: 'Standard' } });
+    const sets = await _primeSets(sandbox);
+    sandbox.window._tunerAutoOpen.publishWorkingTuning(BASS_EADG);
+    assert.equal(sets.length, 0);
+});
+
+test('publish carries the player reference pitch so the slot is self-consistent', async () => {
+    const sandbox = createTunerSandbox({ player: { instrument: 'guitar', string_count: 6, tuning: 'Standard', reference_pitch: 432 } });
+    const sets = await _primeSets(sandbox);
+    sandbox.window._tunerAutoOpen.publishWorkingTuning(DROP_D);
+    assert.equal(sets.length, 1);
+    assert.equal(sets[0].state.referencePitch, 432);
+});
+
+test('publish skips when the instrument could not be confidently resolved (settings unreadable)', async () => {
+    // No player settings → /api/settings reports not-ok → we never cached a confident
+    // selection, so publish must NOT write to a guessed default slot.
+    const sandbox = createTunerSandbox();   // no player
+    const sets = await _primeSets(sandbox);
+    sandbox.window._tunerAutoOpen.publishWorkingTuning(DROP_D);
+    assert.equal(sets.length, 0);
+});
+
+// ── #655 fix: transactional open — a dismiss during the audio-start await must not
+// re-enable the tuner afterward (no zombie enabled-but-hidden state). See issue #675.
+test('dismiss during the audio-start await does not leave a zombie enabled tuner', async () => {
+    const sandbox = createTunerSandbox({ player: { instrument: 'guitar', string_count: 6, tuning: 'Standard' } });
+    // Minimal UI so real enable() gets past the panel-show line to the audio-start await
+    // (the default sandbox _tunerUI is a no-op that never creates uiContainer).
+    const el = () => ({
+        classList: { add() {}, remove() {}, toggle() {}, contains: () => false },
+        querySelector: () => null, appendChild() {}, remove() {}, style: {},
+    });
+    const origTunerUI = sandbox.window._tunerUI;   // the sandbox's full no-op method set
+    sandbox.window._tunerUI = (state, actions) => {
+        const api = origTunerUI(state, actions);
+        state.uiContainer = el();
+        state.vizContainer = el();
+        state.skipBtn = el();
+        api.showMicError = api.showMicError || (() => {});
+        return api;
+    };
+    // The OPEN's audio start resolves only AFTER a ×/Skip dismiss has landed — i.e. the
+    // user dismissed while audio was starting. (disable()'s own background-audio resume
+    // is a later call and resolves at once.)
+    let firstStart = true;
+    sandbox.window._tunerAudio.start = () => {
+        if (!firstStart) return Promise.resolve();
+        firstStart = false;
+        return Promise.resolve().then(() => { sandbox.window.tuner.disable(); });
+    };
+    await sandbox.window.tuner.enable({ auto: true });
+    assert.equal(sandbox.window._tunerAutoOpen.getState().enabled, false,
+        'a mid-open dismiss must win — the tuner stays disabled, not enabled-but-hidden');
+});
+// ── #656 fix: coverage stays conservative when the instrument identity is unknown.
+// A fresh profile (/api/settings omits instrument/string_count/tuning) must NOT be
+// assumed to be standard guitar and silently suppress the prompt. See issue #677.
+test('coverage is conservative when settings carry no instrument identity', async () => {
+    const sandbox = createTunerSandbox({ player: {} });   // settings object, but no instrument fields
+    const covered = await sandbox.window._tunerAutoOpen.coveredByPlayerInstrument(E_STANDARD);
+    assert.equal(covered, false, 'unknown instrument → not covered → still prompt');
+});
+
+test('a configured standard-guitar player still covers a standard song', async () => {
+    const sandbox = createTunerSandbox({ player: { instrument: 'guitar', string_count: 6, tuning: 'Standard' } });
+    const covered = await sandbox.window._tunerAutoOpen.coveredByPlayerInstrument(E_STANDARD);
+    assert.equal(covered, true, 'a known standard guitar covers a standard song (no regression)');
+});
+// ── #657 fix (#680) + #668 fix: coverage is deduped, and the player tuning is memoized
+// across songs (it depends on the selected instrument, not the song). Many coverage
+// calls — the auto-open gate, the badge cue, AND the library's per-song tuning-match
+// chips — share ONE /api/settings fetch until the instrument / working tuning changes.
+test('coverage reports share one /api/settings fetch across songs (player tuning memoized)', async () => {
+    const sandbox = createTunerSandbox({ player: { instrument: 'guitar', string_count: 6, tuning: 'Standard' } });
+    let settingsFetches = 0;
+    const origFetch = sandbox.window.fetch;
+    sandbox.window.fetch = (url) => {
+        if (String(url).includes('/api/settings')) settingsFetches += 1;
+        return origFetch(url);
+    };
+    const api = sandbox.window._tunerAutoOpen;
+    const [a, b] = await Promise.all([api.coverageReport(DROP_D), api.coverageReport(DROP_D)]);
+    assert.equal(settingsFetches, 1, 'concurrent reports for the same song share one fetch');
+    assert.deepEqual(a, b);
+    // A different song re-evaluates coverage but reuses the memoized player tuning — the
+    // player didn't retune or switch instruments, so no second /api/settings read.
+    api.onSongLoading();
+    await api.coverageReport(E_STANDARD);
+    assert.equal(settingsFetches, 1, 'a different song reuses the memoized player tuning — no refetch');
+});
+
+// ── #668 fix: a transient /api/settings failure must NOT be pinned by the player-tuning
+// memo — the next read retries (else one hiccup freezes coverage as "unknown" for good).
+test('a transient /api/settings failure is not cached — the next coverage read retries', async () => {
+    const sandbox = createTunerSandbox({ player: { instrument: 'guitar', string_count: 6, tuning: 'Standard' } });
+    let failNext = true;
+    const origFetch = sandbox.window.fetch;
+    sandbox.window.fetch = (url) => {
+        if (String(url).includes('/api/settings') && failNext) { failNext = false; return Promise.reject(new Error('boom')); }
+        return origFetch(url);
+    };
+    const api = sandbox.window._tunerAutoOpen;
+    const r1 = await api.coverageReport(DROP_D);        // settings read failed → conservative "none" report
+    assert.equal(r1.retune.length, 0, 'a fetch failure yields the empty/unknown report');
+    api.onSongLoading();                                // clear the coverage cache to force a recompute
+    const r2 = await api.coverageReport(DROP_D);        // retry: settings now readable → a real report
+    assert.equal(r2.retune.length, 1, 'the retry actually computes coverage (Drop-D low string vs standard)');
+});
+// ── PR 9b: mic-verify (assumed -> verified via a per-string check) ──────────
+const VERIFY_TARGETS = [82.41, 110, 146.83, 196, 246.94, 329.63];   // guitar-6 standard freqs
+
+test('mic-verify: all strings in-tune-and-stable promotes to verified (with the confirmed offsets)', () => {
+    const sandbox = createTunerSandbox();
+    const sets = [];
+    sandbox.window.feedBack.workingTuning = { get: () => ({ offsets: [0, 0, 0, 0, 0, 0] }), set: (n, o) => sets.push({ n, o }) };
+    const api = sandbox.window._tunerAutoOpen;
+    assert.ok(api.verifyStart(VERIFY_TARGETS, [-2, 0, 0, 0, 0, 0]));   // verifying a Drop-D tuning
+    for (let i = 0; i < 8; i++) api.verifyFeed(82.41, 2);        // one string alone isn't enough
+    assert.equal(api.verifyState().complete, false);
+    for (const f of VERIFY_TARGETS) { for (let i = 0; i < 8; i++) api.verifyFeed(f, 2); }
+    assert.equal(api.verifyState().complete, true);
+    assert.equal(sets.length, 1);
+    assert.equal(sets[0].o.provenance, 'verified');
+    // The stamp carries the CONFIRMED offsets, not whatever stale offsets the slot held.
+    assert.deepEqual(sets[0].n.offsets, [-2, 0, 0, 0, 0, 0]);
+    assert.equal(sets[0].n.verifiedStrings.length, 6);
+});
+
+test('mic-verify: derives the verified offsets from the tuning being checked (no song context)', () => {
+    // A manually-selected tuning (no '_current' song) must still stamp the RIGHT offsets,
+    // derived from the freqs being verified — not a stale currentSongOffsets.
+    const sandbox = createTunerSandbox();
+    const sets = [];
+    sandbox.window.feedBack.workingTuning = { get: () => ({ offsets: [0, 0, 0, 0, 0, 0] }), set: (n, o) => sets.push({ n, o }) };
+    const api = sandbox.window._tunerAutoOpen;
+    const DROP_D_FREQS = [73.42, 110, 146.83, 196, 246.94, 329.63];   // drop-D guitar
+    assert.ok(api.verifyStart(DROP_D_FREQS));   // NO explicit offsets, no song context
+    for (const f of DROP_D_FREQS) { for (let i = 0; i < 8; i++) api.verifyFeed(f, 2); }
+    assert.equal(api.verifyState().complete, true);
+    assert.equal(sets.length, 1);
+    assert.deepEqual(Array.from(sets[0].n.offsets), [-2, 0, 0, 0, 0, 0]);   // derived Drop D
+});
+
+test('mic-verify: an out-of-tune string never completes; cancel clears', () => {
+    const sandbox = createTunerSandbox();
+    sandbox.window.feedBack.workingTuning = { get: () => ({}), set() {} };
+    const api = sandbox.window._tunerAutoOpen;
+    api.verifyStart([82.41, 110]);
+    for (let i = 0; i < 30; i++) api.verifyFeed(82.41, 25);      // 25c off -> never passes
+    assert.equal(api.verifyState().complete, false);
+    assert.deepEqual(api.verifyState().done, [false, false]);
+    api.verifyCancel();
+    assert.equal(api.verifyState(), null);
+});
+
+test('mic-verify: the in-tune streak resets if a frame drifts out', () => {
+    const sandbox = createTunerSandbox();
+    sandbox.window.feedBack.workingTuning = { get: () => ({}), set() {} };
+    const api = sandbox.window._tunerAutoOpen;
+    api.verifyStart([100]);
+    for (let i = 0; i < 5; i++) api.verifyFeed(100, 2);          // 5 in tune (need 8)
+    api.verifyFeed(100, 30);                                     // drift out -> streak resets
+    for (let i = 0; i < 7; i++) api.verifyFeed(100, 2);          // 7 more (not yet 8 in a row)
+    assert.equal(api.verifyState().done[0], false);
+    api.verifyFeed(100, 2);                                      // 8th consecutive -> done
+    assert.equal(api.verifyState().complete, true);
+});
+
+test('the tuner exposes the mic-verify API and only it claims verified (screen.js)', () => {
+    const src = fs.readFileSync(TUNER_SCREEN_JS, 'utf8');
+    assert.match(src, /verifyStart:/);
+    assert.match(src, /verifyFeed:/);
+    assert.match(src, /provenance: 'verified'/);   // the only place that stamps verified
+    // A just-earned 'verified' is not clobbered by the assumed publish-on-clear.
+    assert.match(src, /wasAutoOpened && !_verifiedPublished/);
+});

tests/js/v3_az_rail.test.js

@@ -44,7 +44,7 @@ test('refreshRail reads present letters from the stats endpoint (sort-aware)', (
     assert.match(src, /\/api\/library\/stats\?'\s*\+\s*queryParams/,
         'refreshRail must query /api/library/stats with the active filter params');
     // Opts into the active-sort breakdown so non-rail callers skip the scan.
-    assert.match(src, /queryParams\(\{\s*sort_letters:\s*1\s*\}\)/,
+    assert.match(src, /railParams\s*=\s*\{\s*sort_letters:\s*1\s*\}/,
         'refreshRail must request the sort_letters breakdown');
     assert.match(src, /letters\s*=\s*stats\s*&&\s*stats\.sort_letters/,
         'refreshRail must prefer the active-sort breakdown (sort_letters)');
@@ -92,3 +92,25 @@ test('the rail supports pointer drag-scrub + keyboard arrows', () => {
     assert.match(src, /ArrowUp'[\s\S]*?ArrowDown'|ArrowDown'[\s\S]*?ArrowUp'/,
         'arrow keys must move between present letters');
 });
+
+test('pointer taps are driven by pointerdown, not the retarget-prone click', () => {
+    // A tap must seek on pointerdown (pointer capture retargets the follow-up
+    // click to the rail, so resolving a letter from click is unreliable — taps
+    // would no-op, "clicked O, nothing happened").
+    assert.match(src, /addEventListener\('pointerdown'[\s\S]*?seekToY\(/,
+        'pointerdown must seek immediately so a tap lands without a move');
+    // The click handler must ignore pointer-driven clicks (detail >= 1) and only
+    // handle keyboard Enter/Space activation (synthesized click has detail === 0).
+    assert.match(src, /addEventListener\('click'[\s\S]*?e\.detail\s*!==\s*0/,
+        'the rail click handler must guard on e.detail === 0 (keyboard only)');
+});
+
+test('drag scrubs seek instantly while taps/keys seek smoothly', () => {
+    assert.match(src, /async function\s+jumpToLetter\s*\(\s*letter\s*,\s*smooth/,
+        'jumpToLetter must take a smooth flag');
+    assert.match(src, /behavior:\s*smooth\s*\?\s*'smooth'\s*:\s*'auto'/,
+        'jumpToLetter must scroll instantly during a drag, smoothly on a tap');
+    // pointermove scrubs with smooth=false so RELEASE lands on the let-go letter.
+    assert.match(src, /addEventListener\('pointermove'[\s\S]*?seekToY\([^;]*?,\s*false\)/,
+        'pointermove must seek with smooth=false (precise drag tracking)');
+});

tests/js/v3_favorites_toggle.test.js

@@ -0,0 +1,58 @@
+// Pins the v3 Songs favorite-toggle colour swap in static/v3/songs.js.
+//
+// One shared wireCards() [data-fav] handler serves BOTH the grid card and the
+// tree / "List View" row, but the two render sites use different idle colours
+// (grid = text-white, tree = text-fb-textDim). The handler used to toggle a
+// hardcoded text-white, so in List View it never removed text-fb-textDim — the
+// heart changed glyph (♡→♥) but stayed dim and only turned red after a re-search
+// re-rendered the row (reported macOS+Windows, 0.3.0, open since 06-25). Each
+// button now declares its idle colour via data-fav-idle and the handler swaps
+// exactly that class, so only one colour class is ever present.
+//
+// Source-level only — same strategy as tests/js/v3_az_rail.test.js.
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SONGS_JS = path.join(__dirname, '..', '..', 'static', 'v3', 'songs.js');
+const src = fs.readFileSync(SONGS_JS, 'utf8');
+
+test('both fav render sites declare their idle colour via data-fav-idle', () => {
+    // Grid card heart idles white; the tree / List View heart idles dim.
+    assert.match(src, /data-fav data-fav-idle="text-white"/,
+        'the grid fav button must declare data-fav-idle="text-white"');
+    assert.match(src, /data-fav data-fav-idle="text-fb-textDim"/,
+        'the tree/List-View fav button must declare data-fav-idle="text-fb-textDim"');
+});
+
+test('the shared fav handler swaps the declared idle colour, not a hardcoded one', () => {
+    // Reads the idle colour off the clicked button …
+    assert.match(src, /getAttribute\('data-fav-idle'\)/,
+        'the fav handler must read the idle colour from the button');
+    // … toggles fb-accent (red) on favorite and restores the context idle colour off it.
+    assert.match(src, /classList\.toggle\('text-fb-accent',\s*d\.favorite\)/);
+    assert.match(src, /classList\.toggle\(\s*idle\s*,\s*!d\.favorite\s*\)/,
+        'the fav handler must restore the per-context idle colour (idle), not text-white');
+    // The grid-only hardcoded idle toggle that stranded text-fb-textDim is gone.
+    assert.doesNotMatch(src, /classList\.toggle\('text-white',\s*!d\.favorite\)/,
+        'the hardcoded text-white idle toggle must be removed');
+});
+
+test('the drawer fav-sync (_patchCardFav) swaps the declared idle colour too', () => {
+    // Toggling the like from the Song Details drawer patches the rendered card's
+    // heart via _patchCardFav; it must honour each heart's data-fav-idle the same
+    // way the click handler does, or List-View rows keep the dim-heart bug (#654).
+    assert.match(src, /function _patchCardFav[\s\S]*?getAttribute\('data-fav-idle'\)[\s\S]*?classList\.toggle\(\s*idle\s*,\s*!fav\s*\)/,
+        '_patchCardFav must restore the per-context idle colour (idle), not a hardcoded text-white');
+    assert.doesNotMatch(src, /classList\.toggle\('text-white',\s*!fav\)/,
+        '_patchCardFav must not hardcode the text-white idle toggle');
+});
+
+test('the fav toggle keeps the in-memory song model in sync', () => {
+    // So a virtualized grid recycle / tree re-render renders the new state,
+    // not a stale favorite=false read from state.songsById.
+    assert.match(src, /song\.favorite\s*=\s*d\.favorite/,
+        'the fav handler must write the new favorite state back onto the song model');
+});

tests/js/v3_theme_read_api.test.js

@@ -0,0 +1,57 @@
+// Guard for the host theme READ surface added to the cosmetics applier
+// (static/v3/theme-core.js): always-present `--fbv-*` defaults on :root (so a
+// plugin can read host tokens un-themed), the two keystone roles the palette
+// lacked (on-accent / focus-ring), and the window.feedBack.theme read API +
+// theme:changed event. Source-level guards on the contract surface; runtime
+// behaviour (apply/unequip/defaults-restore/capabilities) is verified
+// separately by a headless render. First slice of the host theme contract
+// (got-feedback/feedBack#644).
+
+'use strict';
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const TC = fs.readFileSync(
+    path.join(__dirname, '..', '..', 'static', 'v3', 'theme-core.js'), 'utf8');
+
+test('always-present --fbv-* defaults are injected on :root', () => {
+    assert.match(TC, /const DEFAULTS = \{/);
+    assert.match(TC, /function _injectDefaults\(\)/);
+    assert.match(TC, /id = 'fb-theme-defaults'/);
+    assert.match(TC, /':root \{/);
+    // injected before the first profile read so var(--fbv-*) resolves immediately
+    assert.match(TC, /_injectDefaults\(\);\s*\n\s*refresh\(\);/);
+});
+
+test('two keystone roles the palette lacked are added as defaults', () => {
+    assert.match(TC, /'on-accent':/);
+    assert.match(TC, /'focus-ring':/);
+});
+
+test('window.feedBack.theme read API is exposed (get/capabilities/prefersReducedMotion)', () => {
+    assert.match(TC, /window\.feedBack = window\.feedBack \|\| \{\};/);
+    assert.match(TC, /window\.feedBack\.theme = \{ get, capabilities, prefersReducedMotion \};/);
+    assert.match(TC, /function get\(\)/);
+    assert.match(TC, /function capabilities\(\)/);
+    assert.match(TC, /function prefersReducedMotion\(\)/);
+});
+
+test('capabilities reports device affordances and gates motion on reduced-motion', () => {
+    assert.match(TC, /glow:/);
+    assert.match(TC, /gradients:/);
+    assert.match(TC, /motion: allowMotion && !prefersReducedMotion\(\)/);
+});
+
+test('apply() tracks theme id + declared capabilities and emits theme:changed', () => {
+    assert.match(TC, /function apply\(payload, meta\)/);
+    assert.match(TC, /_themeId =/);
+    assert.match(TC, /_themeCaps =/);
+    assert.match(TC, /_emitThemeChanged\(\)/);
+    assert.match(TC, /emit\('theme:changed'/);
+});
+
+test('the apply side stays on window.v3Theme (read surface is additive)', () => {
+    assert.match(TC, /window\.v3Theme = \{/);
+});

tests/js/working_tuning.test.js

@@ -0,0 +1,206 @@
+// Behavioral harness for the host `window.feedBack.workingTuning` capability
+// (static/capabilities/working-tuning.js) — the per-instrument, in-memory current
+// tuning. Runs the real capability in a stubbed window (same strategy as
+// midi_input_domain.test.js) with a controllable fetch, and asserts the per-instrument
+// state machine: isolated guitar/bass slots, selector switch, defensive copies, the
+// provenance/verification invariant, unambiguous key routing, named-tuning seeding, and
+// the boot-race guard.
+
+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 { createWindow, ROOT } = require('./capabilities_test_harness');
+
+const CAPABILITIES_JS = path.join(ROOT, 'static', 'capabilities.js');
+const WORKING_TUNING_JS = path.join(ROOT, 'static', 'capabilities', 'working-tuning.js');
+
+// A /api/tunings-shaped fixture (frequencies at 440), enough to resolve names to offsets.
+const TUNINGS = {
+    'guitar-6': {
+        Standard: [82.41, 110.00, 146.83, 196.00, 246.94, 329.63],
+        'Drop D': [73.42, 110.00, 146.83, 196.00, 246.94, 329.63],
+    },
+    'bass-5': {
+        Standard: [30.87, 41.20, 55.00, 73.42, 98.00],
+    },
+};
+
+function deferred() {
+    let resolve;
+    const promise = new Promise((r) => { resolve = r; });
+    return { promise, resolve };
+}
+
+// `routes` maps a URL to: a plain JSON value (served as {ok:true}), a thenable that
+// resolves to a full response object (for deferral/races), or nothing (served {ok:false}).
+function loadWorkingTuning(routes = {}) {
+    const window = createWindow();
+    const changes = [];
+    window.fetch = function (url) {
+        const entry = routes[url];
+        if (entry && typeof entry.then === 'function') return entry;
+        if (entry !== undefined) return Promise.resolve({ ok: true, json: () => Promise.resolve(entry) });
+        return Promise.resolve({ ok: false, json: () => Promise.resolve(null) });
+    };
+    const context = vm.createContext(window);
+    vm.runInContext(fs.readFileSync(CAPABILITIES_JS, 'utf8'), context, { filename: CAPABILITIES_JS });
+    vm.runInContext(fs.readFileSync(WORKING_TUNING_JS, 'utf8'), context, { filename: WORKING_TUNING_JS });
+    // capabilities.js replaces window.feedBack with an EventTarget bus — subscribe on it,
+    // not on window. Attaching after load still catches the async hydration event.
+    window.feedBack.on('working-tuning-changed', (ev) => changes.push(ev.detail));
+    return { window, wt: window.feedBack.workingTuning, changes };
+}
+
+// Rebase a possibly-vm-realm array into this realm so deepStrictEqual compares by value,
+// not by (cross-realm) Array.prototype identity.
+const nums = (a) => (a == null ? a : Array.from(a));
+
+// Drain the seed's fetch/promise chain (settings -> tunings -> hydrate).
+const flush = async () => { for (let i = 0; i < 4; i++) await new Promise((r) => setImmediate(r)); };
+
+test('registers a working-tuning exclusive-owner capability + versioned surface', () => {
+    const { window, wt } = loadWorkingTuning();
+    assert.equal(wt.version, 1);
+    const pipeline = window.feedBack.capabilities.inspect('working-tuning');
+    assert.ok(pipeline, 'working-tuning pipeline exists');
+    const owner = (pipeline.participants || []).find((p) => p.pluginId === 'core.working-tuning');
+    assert.ok(owner, 'core.working-tuning owner registered');
+    for (const op of ['get-working-tuning', 'set-working-tuning']) {
+        assert.ok(owner.operations.includes(op), `owner exposes ${op}`);
+    }
+});
+
+test('get() defaults to a synchronous guitar-6 assumed seed before hydration', () => {
+    const { wt } = loadWorkingTuning();
+    const s = wt.get();
+    assert.equal(s.instrument, 'guitar');
+    assert.equal(s.stringCount, 6);
+    assert.equal(s.provenance, 'assumed');
+    assert.equal(s.offsets, null);
+});
+
+test('per-instrument slots are isolated; the selector surfaces the right one', async () => {
+    const { wt } = loadWorkingTuning();
+    await flush();
+    wt.set({ offsets: [-2, 0, 0, 0, 0, 0] }, { instrument: 'guitar-6' });
+    wt.set({ offsets: [0, 0, 0, 0] }, { instrument: 'bass-4' });
+    assert.deepEqual(nums(wt.get('guitar-6').offsets), [-2, 0, 0, 0, 0, 0]);
+    assert.deepEqual(nums(wt.get('bass-4').offsets), [0, 0, 0, 0]);
+    // Selecting an instrument makes get() (no arg) return that instrument's own state.
+    wt.setCurrentInstrument('guitar', 6);
+    assert.deepEqual(nums(wt.get().offsets), [-2, 0, 0, 0, 0, 0]);
+    wt.setCurrentInstrument('bass', 4);
+    assert.deepEqual(nums(wt.get().offsets), [0, 0, 0, 0]);
+});
+
+test('defensive copies: readers and post-set callers cannot mutate live state', async () => {
+    const { wt } = loadWorkingTuning();
+    await flush();
+    const input = [-2, -2, -2, -2, -2, -2];
+    wt.set({ offsets: input }, { instrument: 'guitar-6' });
+    input[0] = 99;                                   // mutate caller's array after set()
+    assert.deepEqual(nums(wt.get('guitar-6').offsets), [-2, -2, -2, -2, -2, -2], 'set() stored a copy');
+    const read = wt.get('guitar-6');
+    read.offsets[0] = 99;                            // mutate a returned copy
+    assert.deepEqual(nums(wt.get('guitar-6').offsets), [-2, -2, -2, -2, -2, -2], 'get() returned a copy');
+});
+
+test('verification invariant: verified <=> we hold verifiedStrings', async () => {
+    const { wt } = loadWorkingTuning();
+    await flush();
+    // A complete verified bundle stamps verified + a timestamp.
+    let s = wt.set({ offsets: [0, 0, 0, 0, 0, 0], verifiedStrings: [1, 1, 1, 1, 1, 1] },
+        { instrument: 'guitar-6', provenance: 'verified' });
+    assert.equal(s.provenance, 'verified');
+    assert.deepEqual(nums(s.verifiedStrings), [1, 1, 1, 1, 1, 1]);
+    assert.equal(typeof s.verifiedAt, 'number');
+
+    // Claiming verified on a tuning change WITHOUT fresh strings is impossible — it
+    // fails toward assumed and drops the metadata (no "verified with null strings").
+    s = wt.set({ offsets: [-2, 0, 0, 0, 0, 0] }, { instrument: 'guitar-6', provenance: 'verified' });
+    assert.equal(s.provenance, 'assumed');
+    assert.equal(s.verifiedStrings, null);
+    assert.equal(s.verifiedAt, null);
+
+    // verified always carries a real timestamp — an explicit verifiedAt:null is stamped now.
+    s = wt.set({ verifiedStrings: [1, 1, 1, 1, 1, 1], verifiedAt: null },
+        { instrument: 'guitar-6', provenance: 'verified' });
+    assert.equal(s.provenance, 'verified');
+    assert.equal(typeof s.verifiedAt, 'number');
+});
+
+test('a tuning change invalidates a prior verification', async () => {
+    const { wt } = loadWorkingTuning();
+    await flush();
+    wt.set({ offsets: [0, 0, 0, 0, 0, 0], verifiedStrings: [1, 1, 1, 1, 1, 1] },
+        { instrument: 'guitar-6', provenance: 'verified' });
+    const s = wt.set({ offsets: [-2, 0, 0, 0, 0, 0] }, { instrument: 'guitar-6' });
+    assert.equal(s.provenance, 'assumed');
+    assert.equal(s.verifiedStrings, null);
+    assert.equal(s.verifiedAt, null);
+});
+
+test('bare-instrument writes target the current selection, not a hard-coded default', async () => {
+    const { wt } = loadWorkingTuning();
+    await flush();
+    wt.setCurrentInstrument('bass', 5);              // a 5-string bass is selected
+    // A bare instrument string must write bass-5, not bass-4.
+    wt.set({ offsets: [0, 0, 0, 0, 0] }, { instrument: 'bass' });
+    assert.deepEqual(nums(wt.get('bass-5').offsets), [0, 0, 0, 0, 0]);
+    assert.equal(wt.get('bass-4').offsets, null, 'bass-4 slot untouched');
+    // A bare stringCount (no instrument) applies to the selected instrument.
+    const s = wt.set({ stringCount: 5, offsets: [-1, -1, -1, -1, -1] });
+    assert.equal(s.instrument, 'bass');
+    assert.equal(s.stringCount, 5);
+});
+
+test('seed resolves a NAMED tuning to offsets via /api/tunings', async () => {
+    const { wt, changes } = loadWorkingTuning({
+        '/api/settings': { instrument: 'guitar', string_count: 6, tuning: 'Drop D', reference_pitch: 440 },
+        '/api/tunings': TUNINGS,
+    });
+    await flush();
+    const s = wt.get('guitar-6');
+    assert.deepEqual(nums(s.offsets), [-2, 0, 0, 0, 0, 0], 'Drop D resolved to a -2 low string');
+    assert.equal(s.source, 'settings');
+    assert.equal(s.provenance, 'assumed');
+    // Hydration emitted once, carrying the seeded instrument.
+    const hydrations = changes.filter((c) => c.instrument === 'guitar');
+    assert.ok(hydrations.length >= 1, 'a working-tuning-changed fired for the seeded instrument');
+});
+
+test('seed accepts an offsets-list tuning directly', async () => {
+    const { wt } = loadWorkingTuning({
+        '/api/settings': { instrument: 'bass', string_count: 4, tuning: [-2, 0, 0, 0] },
+    });
+    await flush();
+    assert.deepEqual(nums(wt.get('bass-4').offsets), [-2, 0, 0, 0]);
+});
+
+test('boot race: an explicit set() before settings resolve is not clobbered by the seed', async () => {
+    const settings = deferred();
+    const { wt } = loadWorkingTuning({
+        '/api/settings': settings.promise,           // held open
+        '/api/tunings': TUNINGS,
+    });
+    // A consumer writes before the seed lands.
+    wt.set({ offsets: [-5, -5, -5, -5, -5, -5] }, { instrument: 'guitar-6' });
+    // Now the seed resolves with a DIFFERENT tuning.
+    settings.resolve({ ok: true, json: () => Promise.resolve({ instrument: 'guitar', string_count: 6, tuning: 'Drop D' }) });
+    await flush();
+    assert.deepEqual(nums(wt.get('guitar-6').offsets), [-5, -5, -5, -5, -5, -5], 'explicit write survived the seed');
+});
+
+test('resetToDefault clears a slot back to its baseline and emits', async () => {
+    const { wt, changes } = loadWorkingTuning();
+    await flush();
+    wt.set({ offsets: [-2, -2, -2, -2, -2, -2] }, { instrument: 'guitar-6', provenance: 'verified', verifiedStrings: [1, 1, 1, 1, 1, 1] });
+    const before = changes.length;
+    const s = wt.resetToDefault('guitar-6');
+    assert.equal(s.offsets, null);
+    assert.equal(s.provenance, 'assumed');
+    assert.equal(s.verifiedStrings, null);
+    assert.ok(changes.length > before, 'reset emitted working-tuning-changed');
+});

tests/js/working_tuning_capability.test.js

@@ -0,0 +1,144 @@
+'use strict';
+
+// State-machine smoke tests for the host working-tuning capability
+// (static/capabilities/working-tuning.js). Runs the real module in a vm sandbox
+// with stubbed window.feedBack (emit/on + capabilities), localStorage and fetch.
+
+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 SRC = fs.readFileSync(
+    path.join(__dirname, '..', '..', 'static', 'capabilities', 'working-tuning.js'), 'utf8');
+
+function makeSandbox(opts) {
+    opts = opts || {};
+    const listeners = {};
+    const store = opts.localStorage || {};
+    const settings = opts.settings || { instrument: 'guitar', string_count: 6, tuning: 'Standard', reference_pitch: 440 };
+    const localStorage = {
+        getItem: (k) => (k in store ? store[k] : null),
+        setItem: (k, v) => { store[k] = String(v); },
+        removeItem: (k) => { delete store[k]; },
+    };
+    const sandbox = {
+        window: {
+            feedBack: {
+                capabilities: { version: 1, registerOwner() {}, registerParticipant() {} },
+                emit(ev, detail) { (listeners[ev] || []).slice().forEach((fn) => fn(detail)); },
+                on(ev, fn) { (listeners[ev] = listeners[ev] || []).push(fn); },
+            },
+            localStorage,
+        },
+        localStorage,
+        fetch: () => Promise.resolve({ ok: true, json: () => Promise.resolve(settings) }),
+        console, Promise, Date, Array, Object, JSON, Number, isFinite, setTimeout,
+    };
+    vm.createContext(sandbox);
+    vm.runInContext(SRC, sandbox);
+    return {
+        wt: () => sandbox.window.feedBack.workingTuning,
+        emit: (ev, d) => sandbox.window.feedBack.emit(ev, d),
+        on: (ev, fn) => sandbox.window.feedBack.on(ev, fn),
+        reinject: () => vm.runInContext(SRC, sandbox),
+        store,
+    };
+}
+const tick = () => new Promise((r) => setTimeout(r, 0));
+
+test('defaults: an unset instrument is assumed with null offsets', () => {
+    const d = makeSandbox().wt().get('guitar-6');
+    assert.equal(d.offsets, null);
+    assert.equal(d.provenance, 'assumed');
+});
+
+test('set + get round-trips, per-instrument isolation (guitar vs bass)', () => {
+    const s = makeSandbox();
+    s.wt().set({ offsets: [-2, 0, 0, 0, 0, 0], stringCount: 6 }, { instrument: 'guitar-6' });
+    assert.deepEqual(s.wt().get('guitar-6').offsets, [-2, 0, 0, 0, 0, 0]);
+    assert.equal(s.wt().get('bass-4').offsets, null);
+});
+
+test('both directions: E → Drop D → back to E via set()', () => {
+    const s = makeSandbox();
+    s.wt().set({ offsets: [-2, 0, 0, 0, 0, 0] }, { instrument: 'guitar-6' });
+    assert.deepEqual(s.wt().get('guitar-6').offsets, [-2, 0, 0, 0, 0, 0]);
+    s.wt().set({ offsets: [0, 0, 0, 0, 0, 0] }, { instrument: 'guitar-6' });
+    assert.deepEqual(s.wt().get('guitar-6').offsets, [0, 0, 0, 0, 0, 0]);   // came back
+});
+
+test('changing the tuning invalidates a prior verification', () => {
+    const s = makeSandbox();
+    s.wt().set({ offsets: [0, 0, 0, 0, 0, 0], verifiedStrings: [1, 1, 1, 1, 1, 1] }, { instrument: 'guitar-6', provenance: 'verified' });
+    assert.equal(s.wt().get('guitar-6').provenance, 'verified');
+    s.wt().set({ offsets: [-2, 0, 0, 0, 0, 0] }, { instrument: 'guitar-6' });
+    assert.equal(s.wt().get('guitar-6').provenance, 'assumed');
+});
+
+test('verified decays to assumed on song:loading (offsets kept)', () => {
+    const s = makeSandbox();
+    s.wt().set({ offsets: [0, 0, 0, 0, 0, 0], verifiedStrings: [1, 1, 1, 1, 1, 1] }, { instrument: 'guitar-6', provenance: 'verified' });
+    assert.equal(s.wt().get('guitar-6').provenance, 'verified');
+    s.emit('song:loading', { filename: 'x' });
+    assert.equal(s.wt().get('guitar-6').provenance, 'assumed');
+    assert.deepEqual(s.wt().get('guitar-6').offsets, [0, 0, 0, 0, 0, 0]);
+});
+
+test('resetToDefault clears back to defaults', () => {
+    const s = makeSandbox();
+    s.wt().set({ offsets: [-2, 0, 0, 0, 0, 0] }, { instrument: 'guitar-6' });
+    s.wt().resetToDefault('guitar-6');
+    assert.equal(s.wt().get('guitar-6').offsets, null);
+});
+
+test('launch default: setLaunchDefault persists + getLaunchDefault returns it', () => {
+    const s = makeSandbox();
+    s.wt().set({ offsets: [-2, 0, 0, 0, 0, 0], stringCount: 6 }, { instrument: 'guitar-6' });
+    s.wt().setLaunchDefault('guitar-6');
+    assert.deepEqual(s.wt().getLaunchDefault('guitar-6').offsets, [-2, 0, 0, 0, 0, 0]);
+    assert.ok('v3-working-tuning-launch-default' in s.store);
+});
+
+test('launch default is opt-in: none set → getLaunchDefault is null', () => {
+    assert.equal(makeSandbox().wt().getLaunchDefault('guitar-6'), null);
+});
+
+test('launch default seeds a fresh boot and wins over the raw profile', async () => {
+    const store = {};
+    const s1 = makeSandbox({ localStorage: store });
+    s1.wt().set({ offsets: [-2, 0, 0, 0, 0, 0], stringCount: 6 }, { instrument: 'guitar-6' });
+    s1.wt().setLaunchDefault('guitar-6');
+    // Fresh boot with the SAME localStorage; settings say Standard → launch default wins.
+    const s2 = makeSandbox({ localStorage: store, settings: { instrument: 'guitar', string_count: 6, tuning: 'Standard', reference_pitch: 440 } });
+    await tick();
+    assert.deepEqual(s2.wt().get('guitar-6').offsets, [-2, 0, 0, 0, 0, 0]);
+    assert.equal(s2.wt().get('guitar-6').source, 'launch-default');
+});
+
+test('clearLaunchDefault removes it', () => {
+    const s = makeSandbox();
+    s.wt().set({ offsets: [-2, 0, 0, 0, 0, 0], stringCount: 6 }, { instrument: 'guitar-6' });
+    s.wt().setLaunchDefault('guitar-6');
+    s.wt().clearLaunchDefault('guitar-6');
+    assert.equal(s.wt().getLaunchDefault('guitar-6'), null);
+});
+
+test('idempotent re-injection: a second load does NOT clobber live state', () => {
+    const s = makeSandbox();
+    s.wt().set({ offsets: [-2, 0, 0, 0, 0, 0], stringCount: 6 }, { instrument: 'guitar-6' });
+    s.reinject();   // run the module source again in the same context
+    assert.deepEqual(s.wt().get('guitar-6').offsets, [-2, 0, 0, 0, 0, 0]);   // preserved
+});
+
+test('working-tuning-changed fires on set with the changed instrument', () => {
+    const s = makeSandbox();
+    const seen = [];
+    s.on('working-tuning-changed', (e) => seen.push(e));
+    s.wt().set({ offsets: [-2, 0, 0, 0, 0, 0], stringCount: 6 }, { instrument: 'guitar-6' });
+    assert.ok(seen.length >= 1);
+    const last = seen[seen.length - 1];
+    assert.equal(last.instrument, 'guitar');
+    assert.deepEqual(last.tuning.offsets, [-2, 0, 0, 0, 0, 0]);
+});

tests/plugins/tuner/test_config.py

@@ -54,16 +54,21 @@ class TestConfigDefaults:
         assert body["lastTuning"] == "Standard"
         assert body["lastInstrument"] == "guitar-6"
         assert body["audioInputMode"] == "auto"
-        assert body["showFloatingButton"] is True
         assert body["visualizationMode"] == "default"
         assert body["customTunings"] == {}
-        assert body["disabledTunings"] == []
 
     def test_get_does_not_include_default_tunings(self, client):
         # defaultTunings moved to GET /api/tunings (core tuning.read capability).
         body = client.get("/api/plugins/tuner/config").json()
         assert "defaultTunings" not in body
 
+    def test_get_does_not_include_retired_keys(self, client):
+        # disabledTunings + showFloatingButton were retired along with their
+        # settings UI; the config must no longer expose them.
+        body = client.get("/api/plugins/tuner/config").json()
+        assert "disabledTunings" not in body
+        assert "showFloatingButton" not in body
+
 
 class TestConfigPersistence:
     def test_partial_update_persisted(self, client):
@@ -95,14 +100,36 @@ class TestConfigPersistence:
         client.post("/api/plugins/tuner/config", json={"audioInputMode": "browser"})
         assert client.get("/api/plugins/tuner/config").json()["audioInputMode"] == "browser"
 
-    def test_disabled_tunings_strips_entries_without_colon(self, client):
-        client.post("/api/plugins/tuner/config", json={
-            "disabledTunings": ["guitar-6:Drop D", "legacy-entry", "bass-4:Standard"]
+    def test_auto_open_defaults_false(self, client):
+        assert client.get("/api/plugins/tuner/config").json()["autoOpenOnTuningChange"] is False
+
+    def test_auto_open_true_accepted(self, client):
+        client.post("/api/plugins/tuner/config", json={"autoOpenOnTuningChange": True})
+        assert client.get("/api/plugins/tuner/config").json()["autoOpenOnTuningChange"] is True
+
+    def test_auto_open_fail_closed_on_non_bool(self, client):
+        # A hand-edited / bad-client non-boolean (e.g. the string "false") must NOT be
+        # coerced to True by bool() — the opt-in stays off.
+        for bad in ("false", "0", "1", "yes", 1, {}):
+            client.post("/api/plugins/tuner/config", json={"autoOpenOnTuningChange": bad})
+            assert client.get("/api/plugins/tuner/config").json()["autoOpenOnTuningChange"] is False, bad
+
+    def test_retired_keys_ignored_and_not_persisted(self, client, config_dir):
+        # disabledTunings + showFloatingButton were retired: POSTing them must
+        # not break the request, leak back in the response, or hit the file.
+        r = client.post("/api/plugins/tuner/config", json={
+            "disabledTunings": ["guitar-6:Drop D"],
+            "showFloatingButton": False,
+            "lastTuning": "Drop D",
         })
+        assert r.status_code == 200
         body = client.get("/api/plugins/tuner/config").json()
-        assert "legacy-entry" not in body["disabledTunings"]
-        assert "guitar-6:Drop D" in body["disabledTunings"]
-        assert "bass-4:Standard" in body["disabledTunings"]
+        assert "disabledTunings" not in body
+        assert "showFloatingButton" not in body
+        assert body["lastTuning"] == "Drop D"
+        saved = json.loads((config_dir / "tuner.json").read_text())
+        assert "disabledTunings" not in saved
+        assert "showFloatingButton" not in saved
 
     def test_custom_tuning_old_format_migrated_on_read(self, client, config_dir):
         (config_dir / "tuner.json").write_text(json.dumps({

tests/test_albums_view.py

@@ -0,0 +1,93 @@
+"""Tests for the Albums-view follow-up (#689's client half): the feedpak
+`track`/`disc` fields flowing scanner → songs columns → the `track` sort the
+album track list orders by."""
+
+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 / "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:
+            conn.close()
+        sys.modules.pop("server", None)
+
+
+@pytest.fixture()
+def client(server):
+    return TestClient(server.app)
+
+
+def _put(server, fn, title, track=None, disc=None, album="The Album",
+         artist="Artist", genre=""):
+    server.meta_db.put(fn, 0, 0, {
+        "title": title, "artist": artist, "album": album, "year": "1990",
+        "duration": 100, "arrangements": [{"name": "Lead", "index": 0}],
+        "track_number": track, "disc": disc, "genre": genre,
+    })
+
+
+def test_sloppak_extract_meta_reads_track_and_disc(server):
+    d = server.DLC_DIR / "a.sloppak"
+    d.mkdir(parents=True)
+    (d / "manifest.yaml").write_text(
+        "title: Song\nartist: Artist\nduration: 100\n"
+        "arrangements: []\nstems: []\ntrack: 7\ndisc: 2\n", encoding="utf-8")
+    import sloppak
+    meta = sloppak.extract_meta(d)
+    assert meta["track_number"] == 7
+    assert meta["disc"] == 2
+    # Unauthored → None (the album view falls back to title order).
+    (d / "manifest.yaml").write_text(
+        "title: Song\nartist: Artist\nduration: 100\n"
+        "arrangements: []\nstems: []\n", encoding="utf-8")
+    meta = sloppak.extract_meta(d)
+    assert meta["track_number"] is None
+    assert meta["disc"] is None
+
+
+def test_track_sort_orders_by_disc_then_track_nulls_last(server, client):
+    _put(server, "d2t1.sloppak", "Zeta", track=1, disc=2)
+    _put(server, "d1t2.sloppak", "Yankee", track=2, disc=1)
+    _put(server, "d1t1.sloppak", "Xray", track=1, disc=1)
+    _put(server, "nonum-b.sloppak", "Bravo")            # unauthored → bottom,
+    _put(server, "nonum-a.sloppak", "Alpha")            # ordered by title
+    body = client.get("/api/library", params={
+        "artist": "Artist", "album": "The Album", "sort": "track", "size": 50}).json()
+    assert [s["filename"] for s in body["songs"]] == [
+        "d1t1.sloppak", "d1t2.sloppak", "d2t1.sloppak",
+        "nonum-a.sloppak", "nonum-b.sloppak"]
+
+
+def test_track_and_disc_survive_put_roundtrip(server):
+    _put(server, "a.sloppak", "Song", track=3, disc=1)
+    row = server.meta_db.conn.execute(
+        "SELECT track_number, disc FROM songs WHERE filename = 'a.sloppak'").fetchone()
+    assert row == (3, 1)
+
+
+def test_albums_endpoint_honours_genre_filter(server, client):
+    """The albums grid must respect the Genre drawer filter the client sends —
+    without this the /api/library/albums route silently dropped `genre` and
+    surfaced albums with no matching tracks."""
+    _put(server, "rock.sloppak", "Rocker", album="Rock LP", genre="Rock")
+    _put(server, "jazz.sloppak", "Smooth", album="Jazz LP", genre="Jazz")
+    all_albums = client.get("/api/library/albums", params={"artist": "Artist"}).json()
+    assert {a["album"] for a in all_albums["albums"]} == {"Rock LP", "Jazz LP"}
+    filtered = client.get("/api/library/albums",
+                          params={"artist": "Artist", "genre": "Rock"}).json()
+    assert [a["album"] for a in filtered["albums"]] == ["Rock LP"]

tests/test_art_layer.py

@@ -0,0 +1,318 @@
+"""Tests for the R3 art layer: the user>pack>CAA serve chain, user overrides
+(upload / URL / delete, with GIF kept animated and LOCAL-ONLY), and the
+enrichment art worker's Cover Art Archive fetch + LRU cache.
+
+Both network seams (`_caa_http_get`, `_fetch_art_url`) are faked — nothing
+here opens a socket, and the offline default is itself asserted.
+"""
+
+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:
+            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 gif_bytes():
+    """A tiny 2-frame animated GIF."""
+    buf = _io.BytesIO()
+    frames = [Image.new("P", (4, 4), i) for i in (0, 255)]
+    frames[0].save(buf, "GIF", save_all=True, append_images=frames[1:], duration=100)
+    return buf.getvalue()
+
+
+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 b64(data):
+    import base64
+    return base64.b64encode(data).decode()
+
+
+# ── the serve chain: user > pack > CAA ────────────────────────────────────────
+
+def test_user_override_beats_pack_art(server, client):
+    make_sloppak(server, "a.sloppak", with_cover=True)
+    r = client.get("/api/song/a.sloppak/art")
+    assert r.status_code == 200                       # pack art serves
+    assert client.post("/api/song/a.sloppak/art/upload",
+                       json={"image": b64(png_bytes((1, 2, 3)))}).json()["ok"]
+    r = client.get("/api/song/a.sloppak/art")
+    assert r.status_code == 200
+    assert r.headers["content-type"] == "image/png"   # the override, not the pack jpeg
+    # Removing the override falls back to pack art. (The route lives under
+    # /api/art — the DELETE /api/song/{path} catch-all would shadow it.)
+    assert client.delete("/api/art/a.sloppak/override").json()["removed"]
+    r = client.get("/api/song/a.sloppak/art")
+    assert r.status_code == 200
+    assert r.headers["content-type"] == "image/jpeg"
+
+
+def test_gif_override_kept_animated_and_local_only(server, client):
+    make_sloppak(server, "a.sloppak", with_cover=True)
+    raw = gif_bytes()
+    body = client.post("/api/song/a.sloppak/art/upload", json={"image": b64(raw)}).json()
+    assert body == {"ok": True, "kind": "gif"}
+    r = client.get("/api/song/a.sloppak/art")
+    assert r.headers["content-type"] == "image/gif"
+    assert r.content == raw                           # VERBATIM — animation intact
+    # …and the pack file was never touched (GIF never reaches the feedpak).
+    assert (server.DLC_DIR / "a.sloppak" / "cover.jpg").read_bytes() == png_bytes((10, 200, 10))
+    assert not (server.DLC_DIR / "a.sloppak" / "cover.gif").exists()
+    # A later PNG upload replaces the GIF (one override per song).
+    client.post("/api/song/a.sloppak/art/upload", json={"image": b64(png_bytes())})
+    assert client.get("/api/song/a.sloppak/art").headers["content-type"] == "image/png"
+    assert len(server._art_override_paths("a.sloppak")) == 1
+
+
+def test_bad_upload_rejected(server, client):
+    make_sloppak(server, "a.sloppak")
+    assert "error" in client.post("/api/song/a.sloppak/art/upload",
+                                  json={"image": b64(b"GIF89a not really a gif")}).json()
+    assert "error" in client.post("/api/song/a.sloppak/art/upload",
+                                  json={"image": b64(b"plain text")}).json()
+
+
+# ── art by URL ────────────────────────────────────────────────────────────────
+
+def test_art_url_fetches_and_overrides(server, client, monkeypatch):
+    make_sloppak(server, "a.sloppak", with_cover=True)
+    monkeypatch.setattr(server, "_fetch_art_url", lambda url: png_bytes((9, 9, 9)))
+    body = client.post("/api/song/a.sloppak/art/url",
+                       json={"url": "https://example.com/cover.png"}).json()
+    assert body == {"ok": True, "kind": "png"}
+    assert client.get("/api/song/a.sloppak/art").headers["content-type"] == "image/png"
+
+
+def test_art_url_validation(server, client, monkeypatch):
+    make_sloppak(server, "a.sloppak")
+    assert client.post("/api/song/a.sloppak/art/url",
+                       json={"url": "ftp://example.com/x.png"}).status_code == 400
+    assert client.post("/api/song/a.sloppak/art/url", json={}).status_code == 400
+    assert client.post("/api/song/ghost.sloppak/art/url",
+                       json={"url": "https://example.com/x.png"}).status_code == 404
+    # Oversize → 400 (the seam raises ValueError at the cap).
+    def _huge(url):
+        raise ValueError("image larger than 10 MB")
+    monkeypatch.setattr(server, "_fetch_art_url", _huge)
+    assert client.post("/api/song/a.sloppak/art/url",
+                       json={"url": "https://example.com/x.png"}).status_code == 400
+
+
+def test_art_url_offline_by_default(server, client):
+    """The real fetch seam refuses under the test env — pytest can never
+    reach the network even when a test forgets to fake it."""
+    make_sloppak(server, "a.sloppak")
+    r = client.post("/api/song/a.sloppak/art/url",
+                    json={"url": "https://example.com/x.png"})
+    assert r.status_code == 502
+
+
+# ── the enrichment art worker (Cover Art Archive) ─────────────────────────────
+
+def _match_row(server, fn, release_id="rel-1"):
+    """Seed a matched enrichment row with a release id (as the P8 matcher
+    would have written) so the art worker picks it up."""
+    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, "matched", source="text", score=1.0,
+        cand={"recording_id": "rec-1", "release_id": release_id,
+              "title": song["title"], "artist": song["artist"]})
+
+
+@pytest.fixture()
+def caa(server, monkeypatch):
+    """Fake CAA transport + network flag on (mirrors the P8 test fixture)."""
+    calls = []
+    art = {"rel-1": png_bytes((60, 60, 200))}
+
+    def fake(release_id):
+        calls.append(release_id)
+        return art.get(release_id)
+    fake.calls, fake.art = calls, art
+    monkeypatch.setattr(server, "_caa_http_get", fake)
+    monkeypatch.setattr(server, "_enrich_network_enabled", lambda: True)
+    return fake
+
+
+def test_caa_fetch_fills_missing_art(server, client, caa):
+    make_sloppak(server, "a.sloppak")                 # no pack art
+    _match_row(server, "a.sloppak")
+    server._background_enrich()
+    row = server.meta_db.get_enrichment("a.sloppak")
+    assert row["art_state"] == "caa"
+    assert row["art_cache_path"] and row["art_cache_path"].endswith("caa_rel-1.jpg")
+    r = client.get("/api/song/a.sloppak/art")
+    assert r.status_code == 200
+    assert r.headers["content-type"] == "image/jpeg"
+    # Settled: the next pass never re-fetches.
+    n = len(caa.calls)
+    server._background_enrich()
+    assert len(caa.calls) == n
+
+
+def test_caa_skips_pack_art_and_dedupes_by_release(server, caa):
+    make_sloppak(server, "haspack.sloppak", with_cover=True, title="One")
+    make_sloppak(server, "b.sloppak", title="Two")
+    make_sloppak(server, "c.sloppak", title="Three")
+    _match_row(server, "haspack.sloppak")
+    _match_row(server, "b.sloppak")                   # same release as c
+    _match_row(server, "c.sloppak")
+    server._background_enrich()
+    assert server.meta_db.get_enrichment("haspack.sloppak")["art_state"] == "pack"
+    assert server.meta_db.get_enrichment("b.sloppak")["art_state"] == "caa"
+    assert server.meta_db.get_enrichment("c.sloppak")["art_state"] == "caa"
+    assert len(caa.calls) == 1                        # one release → ONE fetch
+
+
+def test_caa_404_marks_none(server, caa):
+    make_sloppak(server, "a.sloppak")
+    _match_row(server, "a.sloppak", release_id="rel-missing")
+    server._background_enrich()
+    assert server.meta_db.get_enrichment("a.sloppak")["art_state"] == "none"
+    n = len(caa.calls)
+    server._background_enrich()
+    assert len(caa.calls) == n                        # never re-hammered
+
+
+def test_caa_transport_error_leaves_row_unevaluated(server, caa, monkeypatch):
+    make_sloppak(server, "a.sloppak")
+    _match_row(server, "a.sloppak")
+
+    def _down(release_id):
+        raise server.EnrichTransportError("down")
+    monkeypatch.setattr(server, "_caa_http_get", _down)
+    server._background_enrich()
+    assert server.meta_db.get_enrichment("a.sloppak")["art_state"] is None
+    # Network back → next pass completes it.
+    monkeypatch.setattr(server, "_caa_http_get", caa)
+    server._background_enrich()
+    assert server.meta_db.get_enrichment("a.sloppak")["art_state"] == "caa"
+
+
+def test_offline_default_skips_art_worker(server, monkeypatch):
+    """Under the plain test env the whole art phase is skipped with the rest
+    of the network work."""
+    calls = []
+    monkeypatch.setattr(server, "_caa_http_get", lambda rid: calls.append(rid))
+    make_sloppak(server, "a.sloppak")
+    _match_row(server, "a.sloppak")
+    server._background_enrich()
+    assert calls == []
+    assert server.meta_db.get_enrichment("a.sloppak")["art_state"] is None
+
+
+def test_lru_prune_evicts_oldest_and_resets_rows(server, caa, monkeypatch):
+    monkeypatch.setattr(server, "_CAA_CACHE_CAP_BYTES", 1)   # everything over cap
+    make_sloppak(server, "a.sloppak", title="One")
+    make_sloppak(server, "b.sloppak", title="Two")
+    caa.art["rel-2"] = png_bytes((1, 1, 1))
+    _match_row(server, "a.sloppak", release_id="rel-1")
+    _match_row(server, "b.sloppak", release_id="rel-2")
+    server._background_enrich()
+    # With a 1-byte cap every fetch immediately evicts — the rows that pointed
+    # at evicted files were reset to unevaluated.
+    caa_files = list(server.ART_CACHE_DIR.glob("caa_*.jpg"))
+    assert len(caa_files) <= 1
+    states = {fn: server.meta_db.get_enrichment(fn)["art_state"]
+              for fn in ("a.sloppak", "b.sloppak")}
+    assert None in states.values() or list(states.values()).count("caa") <= 1
+
+
+def test_delete_song_removes_override(server, client):
+    make_sloppak(server, "a.sloppak")
+    client.post("/api/song/a.sloppak/art/upload", json={"image": b64(png_bytes())})
+    assert server._art_override_paths("a.sloppak")
+    r = client.delete("/api/song/a.sloppak")
+    assert r.status_code == 200
+    assert server._art_override_paths("a.sloppak") == []
+
+
+def test_delete_override_restores_caa_fallback(server, client, caa):
+    """Removing a user override that had settled the row as 'user' must reset
+    the enrichment state so the CAA fallback is fetched and served again —
+    otherwise the song is stranded with no art at all."""
+    make_sloppak(server, "a.sloppak")                 # no pack art
+    _match_row(server, "a.sloppak")
+    # Pin an override BEFORE the art worker runs → the pass stamps art_state='user'.
+    client.post("/api/song/a.sloppak/art/upload", json={"image": b64(png_bytes())})
+    server._background_enrich()
+    assert server.meta_db.get_enrichment("a.sloppak")["art_state"] == "user"
+    # Remove it → the row resets to unevaluated…
+    assert client.delete("/api/art/a.sloppak/override").json()["removed"]
+    assert server.meta_db.get_enrichment("a.sloppak")["art_state"] is None
+    # …and the next pass fetches + serves the release's front cover.
+    server._background_enrich()
+    assert server.meta_db.get_enrichment("a.sloppak")["art_state"] == "caa"
+    r = client.get("/api/song/a.sloppak/art")
+    assert r.status_code == 200
+    assert r.headers["content-type"] == "image/jpeg"
+
+
+def test_upload_rejects_unknown_song_and_oversize(server, client):
+    # Unknown filename → 404 (no stray override file written).
+    assert client.post("/api/song/ghost.sloppak/art/upload",
+                       json={"image": b64(png_bytes())}).status_code == 404
+    assert server._art_override_paths("ghost.sloppak") == []
+    # Oversize decoded payload → 400 (bounds the base64 upload path).
+    make_sloppak(server, "a.sloppak")
+    huge = b64(b"\x00" * (server._ART_URL_MAX_BYTES + 1))
+    assert client.post("/api/song/a.sloppak/art/upload",
+                       json={"image": huge}).status_code == 400
+
+
+def test_fetch_art_url_blocks_internal_hosts(server):
+    """The SSRF guard refuses loopback / link-local / private targets before
+    any request is made (the real seam, not the faked one)."""
+    assert server._url_host_is_internal("http://127.0.0.1/x.png")
+    assert server._url_host_is_internal("http://localhost/x.png")
+    assert server._url_host_is_internal("http://169.254.169.254/latest/meta-data")
+    assert server._url_host_is_internal("http://10.0.0.5/x.png")
+    assert server._url_host_is_internal("http://[::1]/x.png")
+    assert server._url_host_is_internal("http://nonexistent.invalid/x.png")  # unresolvable → closed
+    assert not server._url_host_is_internal("http://93.184.216.34/x.png")    # public literal

tests/test_artist_alias.py

@@ -0,0 +1,211 @@
+"""Tests for artist-name canonicalization (P4): the artist_alias override that
+merges messy artist tags ("ACDC" → "AC/DC") AT DISPLAY — the deduped dropdown/
+tree (query_artists), the artist filter (canonical matches all raw variants),
+and the grid card label — without rewriting songs.artist or the feedpak files.
+Sort/A–Z stay on the raw artist (keyset-safe); that reindex is deferred to P5a."""
+
+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:
+            conn.close()
+        sys.modules.pop("server", None)
+
+
+@pytest.fixture()
+def client(server):
+    return TestClient(server.app)
+
+
+def _seed(server, fn, artist, album="Alb"):
+    server.meta_db.put(fn, 0, 0, {"title": fn.split(".")[0], "artist": artist, "album": album})
+
+
+def _artist_names(client):
+    data = client.get("/api/library/artists?size=100").json()
+    return [a["name"] for a in data["artists"]]
+
+
+def _grid_artist(client, fn):
+    row = next(s for s in client.get("/api/library").json()["songs"] if s["filename"] == fn)
+    return row["artist"]
+
+
+def _alias(client, raw, canonical):
+    return client.post("/api/artist-aliases", json={"raw_name": raw, "canonical_name": canonical})
+
+
+# ── No aliases: raw names, unchanged behaviour ───────────────────────────────
+
+def test_no_aliases_lists_raw_distinct(client, server):
+    _seed(server, "a.archive", "ACDC")
+    _seed(server, "b.archive", "AC/DC")
+    assert set(_artist_names(client)) == {"ACDC", "AC/DC"}
+
+
+# ── Dropdown/tree dedupe on the canonical name ───────────────────────────────
+
+def test_alias_dedupes_artist_list(client, server):
+    _seed(server, "a.archive", "ACDC")
+    _seed(server, "b.archive", "AC/DC")
+    _alias(client, "ACDC", "AC/DC")
+    data = client.get("/api/library/artists?size=100").json()
+    assert [a["name"] for a in data["artists"]] == ["AC/DC"]
+    assert data["total_artists"] == 1
+
+
+# ── Grid card shows the canonical label ──────────────────────────────────────
+
+def test_grid_shows_canonical_artist(client, server):
+    _seed(server, "a.archive", "ACDC")
+    _alias(client, "ACDC", "AC/DC")
+    assert _grid_artist(client, "a.archive") == "AC/DC"
+
+
+# ── Filtering by the canonical matches every raw variant ─────────────────────
+
+def test_filter_by_canonical_matches_all_variants(client, server):
+    _seed(server, "a.archive", "ACDC")
+    _seed(server, "b.archive", "AC/DC")
+    _seed(server, "c.archive", "Other")
+    _alias(client, "ACDC", "AC/DC")
+    got = {s["filename"] for s in
+           client.get("/api/library", params={"artist": "AC/DC"}).json()["songs"]}
+    assert got == {"a.archive", "b.archive"}
+
+
+# ── Merge endpoint ───────────────────────────────────────────────────────────
+
+def test_merge_endpoint(client, server):
+    _seed(server, "a.archive", "Beatles")
+    _seed(server, "b.archive", "The Beatles")
+    r = client.post("/api/artist-aliases/merge",
+                    json={"raw_names": ["Beatles", "The Beatles"], "canonical_name": "The Beatles"})
+    assert r.json()["merged"] == 1   # "The Beatles" self-skip
+    assert _artist_names(client) == ["The Beatles"]
+
+
+def test_merge_requires_canonical_and_list(client, server):
+    assert client.post("/api/artist-aliases/merge", json={"raw_names": ["x"]}).status_code == 400
+    assert client.post("/api/artist-aliases/merge", json={"canonical_name": "y"}).status_code == 400
+
+
+# ── Un-merge: self-alias clears + DELETE ─────────────────────────────────────
+
+def test_self_alias_clears(client, server):
+    _seed(server, "a.archive", "ACDC")
+    _alias(client, "ACDC", "AC/DC")
+    _alias(client, "ACDC", "ACDC")   # self → un-merge
+    assert client.get("/api/artist-aliases").json()["aliases"] == []
+    assert _grid_artist(client, "a.archive") == "ACDC"
+
+
+def test_delete_alias_unmerges(client, server):
+    _seed(server, "a.archive", "ACDC")
+    _alias(client, "ACDC", "AC/DC")
+    assert client.delete("/api/artist-aliases/ACDC").json()["ok"] is True
+    assert _grid_artist(client, "a.archive") == "ACDC"
+
+
+# ── Never purged when songs churn (separate, non-filename-keyed table) ────────
+
+def test_alias_survives_song_reindex(client, server):
+    _seed(server, "a.archive", "ACDC")
+    _alias(client, "ACDC", "AC/DC")
+    # A rescan re-indexes the song (INSERT OR REPLACE INTO songs).
+    server.meta_db.put("a.archive", 1, 1, {"title": "a", "artist": "ACDC", "album": "Alb"})
+    assert _grid_artist(client, "a.archive") == "AC/DC"
+    assert len(client.get("/api/artist-aliases").json()["aliases"]) == 1
+
+
+# ── Raw-artist picker (Tidy-up source) ───────────────────────────────────────
+
+def test_raw_artists_lists_counts_and_canonical(client, server):
+    _seed(server, "a.archive", "ACDC")
+    _seed(server, "b.archive", "ACDC")
+    _seed(server, "c.archive", "AC/DC")
+    _alias(client, "ACDC", "AC/DC")
+    by_name = {a["name"]: a for a in client.get("/api/artists/raw").json()["artists"]}
+    assert by_name["ACDC"]["count"] == 2
+    assert by_name["ACDC"]["canonical"] == "AC/DC"     # shows where it maps
+    assert by_name["AC/DC"]["count"] == 1
+
+
+# ── Transitive chains flatten so sequential merges unify (PR #705 P2) ─────────
+
+def test_sequential_merge_flattens_transitive_chain(client, server):
+    """merge ACDC→AC/DC then AC/DC→AC-DC must unify ALL variants onto the terminal
+    canonical ("AC-DC") — not leave a two-hop chain that grouping/filtering split."""
+    _seed(server, "a.archive", "ACDC")
+    _seed(server, "b.archive", "AC/DC")
+    _seed(server, "c.archive", "AC-DC")
+    client.post("/api/artist-aliases/merge",
+                json={"raw_names": ["ACDC"], "canonical_name": "AC/DC"})
+    client.post("/api/artist-aliases/merge",
+                json={"raw_names": ["AC/DC"], "canonical_name": "AC-DC"})
+    # Both original variants resolve (single hop) to the terminal canonical.
+    assert server.meta_db.effective_artist("ACDC") == "AC-DC"
+    assert server.meta_db.effective_artist("AC/DC") == "AC-DC"
+    # The song tagged "ACDC" displays the terminal, not the intermediate.
+    assert _grid_artist(client, "a.archive") == "AC-DC"
+    # Grouping shows ONE canonical, not two split groups.
+    assert _artist_names(client) == ["AC-DC"]
+    # Stored rows are already terminal (forward-flattened), never AC/DC.
+    canon = {a["canonical_name"] for a in client.get("/api/artist-aliases").json()["aliases"]}
+    assert canon == {"AC-DC"}
+    # Filtering by the terminal matches every original variant.
+    got = {s["filename"] for s in
+           client.get("/api/library", params={"artist": "AC-DC"}).json()["songs"]}
+    assert got == {"a.archive", "b.archive", "c.archive"}
+
+
+def test_cycle_is_refused_and_state_intact(client, server):
+    """A→B then B→A would close a cycle: the second set is refused (409) and the
+    existing A→B mapping is left intact — no loop, no corruption."""
+    _seed(server, "a.archive", "A")
+    _seed(server, "b.archive", "B")
+    client.post("/api/artist-aliases/merge", json={"raw_names": ["A"], "canonical_name": "B"})
+    r = _alias(client, "B", "A")           # B → A closes the cycle
+    assert r.status_code == 409
+    # State unchanged: exactly one alias row, A → B.
+    assert client.get("/api/artist-aliases").json()["aliases"] == [
+        {"raw_name": "A", "canonical_name": "B", "mb_artist_id": None}]
+    assert server.meta_db.effective_artist("A") == "B"
+    assert server.meta_db.effective_artist("B") == "B"
+
+
+def test_terminal_resolution_survives_a_stored_cycle(server):
+    """Even if the table somehow holds a direct cycle (P↔Q), the visited-set makes
+    _terminal_canonical terminate instead of looping forever."""
+    db = server.meta_db
+    with db._lock:
+        db.conn.execute("INSERT INTO artist_alias (raw_name, canonical_name, updated_at) "
+                        "VALUES ('P', 'Q', datetime('now'))")
+        db.conn.execute("INSERT INTO artist_alias (raw_name, canonical_name, updated_at) "
+                        "VALUES ('Q', 'P', datetime('now'))")
+        db.conn.commit()
+    assert db._terminal_canonical("P") in ("P", "Q")
+    assert db._terminal_canonical("Q") in ("P", "Q")
+
+
+def test_list_aliases_sorted(client, server):
+    _seed(server, "a.archive", "ACDC")
+    _seed(server, "b.archive", "guns n roses")
+    _alias(client, "ACDC", "AC/DC")
+    _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"}

tests/test_artist_sort_title_order.py

@@ -0,0 +1,81 @@
+"""The grid's artist sort orders WITHIN an artist by title (tree-view feel),
+not raw filename — the tester's "list is organised by artist, but the cards
+look alphabetical/random" report. Artist sorts page by OFFSET now (the title
+secondary can't ride the two-term keyset cursor), so pagination across an
+artist boundary is pinned too."""
+
+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:
+            conn.close()
+        sys.modules.pop("server", None)
+
+
+@pytest.fixture()
+def client(server):
+    return TestClient(server.app)
+
+
+def _put(server, fn, artist, title):
+    server.meta_db.put(fn, 0, 0, {
+        "title": title, "artist": artist, "album": "", "year": "",
+        "duration": 100, "arrangements": [{"name": "Lead", "index": 0}],
+    })
+
+
+def test_artist_sort_orders_titles_within_artist(server, client):
+    # Filenames deliberately REVERSE the title order, so filename ordering
+    # (the old behaviour) and title ordering disagree.
+    _put(server, "z1.sloppak", "Alpha Band", "Aardvark")
+    _put(server, "a9.sloppak", "Alpha Band", "Zebra")
+    _put(server, "m5.sloppak", "Alpha Band", "Mango")
+    _put(server, "q1.sloppak", "Beta Band", "Only Song")
+    body = client.get("/api/library", params={"sort": "artist", "size": 50}).json()
+    assert [s["title"] for s in body["songs"]] == ["Aardvark", "Mango", "Zebra", "Only Song"]
+    # Z→A flips the ARTIST order; titles stay A→Z within each artist.
+    body = client.get("/api/library", params={"sort": "artist-desc", "size": 50}).json()
+    assert [s["title"] for s in body["songs"]] == ["Only Song", "Aardvark", "Mango", "Zebra"]
+
+
+def test_legacy_dir_desc_flips_artist_like_artist_desc(server, client):
+    # The legacy `sort=artist&dir=desc` shape must match the explicit
+    # `artist-desc` key: the artist clause now bakes in ASC (for the title
+    # secondary), so `dir=desc` is folded into the effective sort BEFORE the
+    # ORDER BY lookup — otherwise the append is suppressed and dir=desc would
+    # silently return A→Z.
+    _put(server, "z1.sloppak", "Alpha Band", "Aardvark")
+    _put(server, "a9.sloppak", "Alpha Band", "Zebra")
+    _put(server, "m5.sloppak", "Alpha Band", "Mango")
+    _put(server, "q1.sloppak", "Beta Band", "Only Song")
+    legacy = client.get("/api/library", params={"sort": "artist", "dir": "desc", "size": 50}).json()
+    explicit = client.get("/api/library", params={"sort": "artist-desc", "size": 50}).json()
+    assert [s["title"] for s in legacy["songs"]] == ["Only Song", "Aardvark", "Mango", "Zebra"]
+    assert [s["title"] for s in legacy["songs"]] == [s["title"] for s in explicit["songs"]]
+
+
+def test_artist_sort_offset_pagination_no_skip_or_dupe(server, client):
+    for i in range(7):
+        _put(server, f"f{6 - i}.sloppak", "One Artist", f"Title {chr(65 + i)}")
+    seen = []
+    for page in range(4):
+        body = client.get("/api/library", params={"sort": "artist", "size": 2, "page": page}).json()
+        seen += [s["title"] for s in body["songs"]]
+    assert seen == [f"Title {chr(65 + i)}" for i in range(7)]
+    # And no keyset cursor is offered for artist sorts (OFFSET path).
+    body = client.get("/api/library", params={"sort": "artist", "size": 2}).json()
+    assert body["next_cursor"] is None

tests/test_batch_user_meta.py

@@ -0,0 +1,152 @@
+"""Tests for the bulk personal-meta endpoint (P2):
+POST /api/songs/user-meta/batch — the apply-to-all behind the Songs batch bar.
+DB-only, never touches files. Additive by design: bulk tag edits ADD/REMOVE
+(never full-replace) and an omitted `set_difficulty` leaves each song's own
+value alone (mixed-state "leave unchanged")."""
+
+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:
+            conn.close()
+        sys.modules.pop("server", None)
+
+
+@pytest.fixture()
+def client(server):
+    return TestClient(server.app)
+
+
+def _seed(server, *filenames):
+    for fn in filenames:
+        server.meta_db.put(fn, 0, 0, {"title": fn.split(".")[0], "artist": "A"})
+
+
+def _um(client, fn):
+    return client.get(f"/api/song/{fn}/user-meta").json()
+
+
+BATCH = "/api/songs/user-meta/batch"
+
+
+# ── Difficulty across a selection ────────────────────────────────────────────
+
+def test_batch_set_difficulty_on_all(client, server):
+    _seed(server, "a.archive", "b.archive", "c.archive")
+    r = client.post(BATCH, json={"filenames": ["a.archive", "b.archive"],
+                                 "set_difficulty": 4})
+    assert r.status_code == 200
+    assert r.json()["updated"] == 2
+    assert _um(client, "a.archive")["user_difficulty"] == 4
+    assert _um(client, "b.archive")["user_difficulty"] == 4
+    # untouched song stays unset
+    assert _um(client, "c.archive")["user_difficulty"] is None
+
+
+def test_batch_clear_difficulty_preserves_notes(client, server):
+    _seed(server, "a.archive", "b.archive")
+    client.put("/api/song/a.archive/user-meta", json={"user_difficulty": 3, "notes": "keep me"})
+    client.put("/api/song/b.archive/user-meta", json={"user_difficulty": 2})
+    r = client.post(BATCH, json={"filenames": ["a.archive", "b.archive"],
+                                 "set_difficulty": None})
+    assert r.status_code == 200
+    # a still has its notes; b (no notes) is fully cleared
+    a = _um(client, "a.archive")
+    assert a["user_difficulty"] is None and a["notes"] == "keep me"
+    assert _um(client, "b.archive") == {"user_difficulty": None, "notes": "", "tags": []}
+
+
+def test_omitting_set_difficulty_leaves_each_value(client, server):
+    """Mixed-state: no set_difficulty key → every song keeps its own difficulty
+    while tags still apply."""
+    _seed(server, "a.archive", "b.archive")
+    client.put("/api/song/a.archive/user-meta", json={"user_difficulty": 1})
+    client.put("/api/song/b.archive/user-meta", json={"user_difficulty": 5})
+    client.post(BATCH, json={"filenames": ["a.archive", "b.archive"],
+                             "add_tags": ["gig"]})
+    assert _um(client, "a.archive")["user_difficulty"] == 1
+    assert _um(client, "b.archive")["user_difficulty"] == 5
+    assert _um(client, "a.archive")["tags"] == ["gig"]
+
+
+# ── Tags: additive, never full-replace ───────────────────────────────────────
+
+def test_batch_add_tags_does_not_clobber_existing(client, server):
+    _seed(server, "a.archive", "b.archive")
+    client.put("/api/song/a.archive/user-meta", json={"tags": ["existing"]})
+    client.post(BATCH, json={"filenames": ["a.archive", "b.archive"],
+                             "add_tags": ["Warm-ups", "warm-ups"]})  # dupe-folds
+    assert _um(client, "a.archive")["tags"] == ["existing", "warm-ups"]
+    assert _um(client, "b.archive")["tags"] == ["warm-ups"]
+
+
+def test_batch_remove_tags(client, server):
+    _seed(server, "a.archive", "b.archive")
+    client.put("/api/song/a.archive/user-meta", json={"tags": ["gig", "riffs"]})
+    client.put("/api/song/b.archive/user-meta", json={"tags": ["gig"]})
+    client.post(BATCH, json={"filenames": ["a.archive", "b.archive"],
+                             "remove_tags": ["gig"]})
+    assert _um(client, "a.archive")["tags"] == ["riffs"]
+    assert _um(client, "b.archive")["tags"] == []
+
+
+def test_add_wins_over_remove_conflict(client, server):
+    _seed(server, "a.archive")
+    client.post(BATCH, json={"filenames": ["a.archive"],
+                             "add_tags": ["keep"], "remove_tags": ["keep"]})
+    assert _um(client, "a.archive")["tags"] == ["keep"]
+
+
+def test_returned_tag_vocabulary_refreshes(client, server):
+    _seed(server, "a.archive", "b.archive")
+    body = client.post(BATCH, json={"filenames": ["a.archive", "b.archive"],
+                                    "add_tags": ["warmups"]}).json()
+    assert {"tag": "warmups", "count": 2} in body["tags"]
+
+
+# ── Validation ───────────────────────────────────────────────────────────────
+
+def test_empty_filenames_is_400(client, server):
+    assert client.post(BATCH, json={"filenames": [], "set_difficulty": 3}).status_code == 400
+    assert client.post(BATCH, json={"set_difficulty": 3}).status_code == 400
+
+
+def test_nothing_to_apply_is_400(client, server):
+    _seed(server, "a.archive")
+    assert client.post(BATCH, json={"filenames": ["a.archive"]}).status_code == 400
+
+
+@pytest.mark.parametrize("bad", [0, 6, 2.5, "x", True])
+def test_bad_set_difficulty_is_400(client, server, bad):
+    _seed(server, "a.archive")
+    assert client.post(BATCH, json={"filenames": ["a.archive"],
+                                    "set_difficulty": bad}).status_code == 400
+
+
+def test_tags_must_be_arrays(client, server):
+    _seed(server, "a.archive")
+    assert client.post(BATCH, json={"filenames": ["a.archive"],
+                                    "add_tags": "gig"}).status_code == 400
+
+
+def test_batch_survives_rescan(client, server):
+    _seed(server, "a.archive")
+    client.post(BATCH, json={"filenames": ["a.archive"],
+                             "set_difficulty": 3, "add_tags": ["t"]})
+    server.meta_db.put("a.archive", 1, 1, {"title": "a", "artist": "A"})
+    m = _um(client, "a.archive")
+    assert m["user_difficulty"] == 3 and m["tags"] == ["t"]

tests/test_context_menu_api.py

@@ -0,0 +1,141 @@
+"""Tests for the R2 context-menu backend: per-song "Refresh metadata"
+(explicit re-match reset + kick) and "Get info" (file location + pack
+contents). The refresh flow reuses the P8 fake-transport pattern — nothing
+here opens a socket."""
+
+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 / "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:
+            conn.close()
+        sys.modules.pop("server", None)
+
+
+@pytest.fixture()
+def client(server):
+    return TestClient(server.app)
+
+
+def _put(server, fn, title="Thunderstruck", artist="AC/DC", album="", year="1990",
+         duration=292):
+    server.meta_db.put(fn, 0, 0, {
+        "title": title, "artist": artist, "album": album, "year": year,
+        "duration": duration, "arrangements": [{"name": "Lead", "index": 0}],
+    })
+
+
+def make_sloppak(server, name, extra_yaml="", title="Thunderstruck", artist="AC/DC"):
+    d = server.DLC_DIR / name
+    d.mkdir(parents=True)
+    (d / "manifest.yaml").write_text(
+        f"title: {title}\nartist: {artist}\nduration: 292\n"
+        "arrangements:\n  - name: Lead\n    id: lead\n"
+        "stems:\n  - id: full\n    file: stems/full.ogg\n" + extra_yaml,
+        encoding="utf-8")
+    _put(server, name, title=title, artist=artist)
+    return d
+
+
+# ── Refresh metadata ──────────────────────────────────────────────────────────
+
+def test_refresh_resets_even_a_manual_pin_and_rematches(server, client, monkeypatch):
+    _put(server, "a.sloppak")
+    server.meta_db.set_enrichment_manual(
+        "a.sloppak", {"recording_id": "old-pin", "title": "Thunderstruck",
+                      "artist": "AC/DC"}, source="search")
+    # The reset itself is synchronous; the kicked pass runs on a daemon
+    # thread, so assert the reset here and drive the re-match inline below.
+    r = client.post("/api/enrichment/refresh/a.sloppak")
+    assert r.status_code == 200
+    for _ in range(200):
+        if not client.get("/api/enrichment/status").json()["running"]:
+            break
+        import time as _t
+        _t.sleep(0.02)
+    row = server.meta_db.get_enrichment("a.sloppak")
+    assert row["match_state"] == "unscanned"        # the pin was discarded
+    assert row["mb_recording_id"] is None
+    assert row["attempts"] == 0
+    # …and the normal pass re-matches it (fake transport, network flag on).
+    def fake(path, params):
+        return {"recordings": [{
+            "id": "rec-new", "score": 100, "title": "Thunderstruck",
+            "length": 292000,
+            "artist-credit": [{"name": "AC/DC", "artist": {
+                "id": "art-1", "name": "AC/DC", "sort-name": "AC/DC"}}],
+            "releases": [{"id": "rel-1", "title": "The Razors Edge",
+                          "status": "Official", "date": "1990-09-24",
+                          "release-group": {"primary-type": "Album"}}],
+        }]}
+    monkeypatch.setattr(server, "_mb_http_get", fake)
+    monkeypatch.setattr(server, "_enrich_network_enabled", lambda: True)
+    server._background_enrich()
+    assert server.meta_db.get_enrichment("a.sloppak")["mb_recording_id"] == "rec-new"
+
+
+def test_refresh_unknown_song_404(server, client):
+    assert client.post("/api/enrichment/refresh/ghost.sloppak").status_code == 404
+
+
+# ── Get info ──────────────────────────────────────────────────────────────────
+
+def test_fileinfo_sloppak_contents(server, client):
+    make_sloppak(server, "a.sloppak",
+                 extra_yaml="mbid: 12345678-abcd-4ef0-9876-0123456789ab\n"
+                            "genres: [rock, hard rock]\ntrack: 3\n")
+    body = client.get("/api/chart/a.sloppak/fileinfo").json()
+    assert body["format"] == "sloppak"
+    assert body["filename"] == "a.sloppak"
+    assert body["path"].endswith("a.sloppak")
+    assert body["size"] > 0
+    m = body["manifest"]
+    assert m["title"] == "Thunderstruck"
+    assert m["arrangements"] == ["Lead"]
+    assert m["stems"] == ["full"]
+    assert m["has_cover"] is False
+    assert m["identity"]["mbid"] == "12345678-abcd-4ef0-9876-0123456789ab"
+    assert m["identity"]["genres"] == ["rock", "hard rock"]
+    assert m["identity"]["track"] == 3
+    assert "isrc" not in m["identity"]              # only keys actually present
+    # No enrichment row yet → no match block (the panel shows "Not scanned").
+    assert "match" not in body
+
+
+def test_fileinfo_includes_match_verdict(server, client):
+    make_sloppak(server, "a.sloppak")
+    server.meta_db.set_enrichment_manual(
+        "a.sloppak", {"recording_id": "rec-1", "title": "Thunderstruck",
+                      "artist": "AC/DC", "album": "The Razors Edge"},
+        source="search")
+    body = client.get("/api/chart/a.sloppak/fileinfo").json()
+    assert body["match"]["match_state"] == "manual"
+    assert body["match"]["canon_album"] == "The Razors Edge"
+
+
+def test_fileinfo_missing_and_traversal(server, client):
+    assert client.get("/api/chart/ghost.sloppak/fileinfo").status_code == 404
+    assert client.get("/api/chart/..%2f..%2fetc%2fpasswd/fileinfo").status_code in (403, 404)
+
+
+def test_fileinfo_non_chart_file_is_404(server, client):
+    """A stray non-song file the user keeps under DLC_DIR must not have its
+    path/size/mtime exposed — the route is charts only, not a filesystem stat."""
+    (server.DLC_DIR / "private-notes.txt").write_text("secret", encoding="utf-8")
+    assert client.get("/api/chart/private-notes.txt/fileinfo").status_code == 404

tests/test_curated_album.py

@@ -0,0 +1,206 @@
+"""Tests for the curated album (P6, metadata-design §7.2): a playlists row with
+kind='album' + per-slot pinned chart/arrangement, work_key stamped at add,
+slot chart-swap validated to the same work, and orphan-at-read self-heal."""
+
+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:
+            conn.close()
+        sys.modules.pop("server", None)
+
+
+@pytest.fixture()
+def client(server):
+    return TestClient(server.app)
+
+
+def _put(server, fn, title, artist, arrangements=("Lead",)):
+    arr = [{"name": n, "index": i} for i, n in enumerate(arrangements)]
+    server.meta_db.put(fn, 0, 0, {"title": title, "artist": artist, "arrangements": arr})
+
+
+def _album(client, name="My Album"):
+    return client.post("/api/playlists", json={"name": name, "kind": "album"}).json()
+
+
+def _add(client, pid, fn):
+    return client.post(f"/api/playlists/{pid}/songs", json={"filename": fn}).json()
+
+
+# ── kind discriminator ────────────────────────────────────────────────────────
+
+def test_create_album_kind(client):
+    pl = _album(client)
+    assert pl["kind"] == "album"
+    listed = {p["id"]: p for p in client.get("/api/playlists").json()}
+    assert listed[pl["id"]]["kind"] == "album"
+
+
+def test_regular_playlist_payload_has_no_album_fields(client, server):
+    _put(server, "a.archive", "Song", "Artist")
+    pl = client.post("/api/playlists", json={"name": "Mix"}).json()
+    assert "kind" not in pl
+    body = _add(client, pl["id"], "a.archive")
+    assert "arrangement" not in body["songs"][0]
+    assert "work_key" not in body["songs"][0]
+
+
+def test_bad_kind_rejected(client):
+    r = client.post("/api/playlists", json={"name": "X", "kind": "boss-fight"})
+    assert r.status_code == 400
+
+
+# ── add stamps work identity; slot payload carries the album fields ──────────
+
+def test_album_add_stamps_work_key(client, server):
+    _put(server, "a.archive", "Song", "Artist")
+    pid = _album(client)["id"]
+    slot = _add(client, pid, "a.archive")["songs"][0]
+    assert slot["work_key"] == server.meta_db.work_key_for("a.archive")
+    assert slot["arrangement"] is None
+    assert [a["name"] for a in slot["arrangements"]] == ["Lead"]
+
+
+# ── slot arrangement pin ──────────────────────────────────────────────────────
+
+def test_slot_arrangement_pin_and_clear(client, server):
+    _put(server, "a.archive", "Song", "Artist", arrangements=("Lead", "Bass"))
+    pid = _album(client)["id"]
+    _add(client, pid, "a.archive")
+    body = client.patch(f"/api/playlists/{pid}/songs/a.archive",
+                        json={"arrangement": "Bass"}).json()
+    assert body["songs"][0]["arrangement"] == "Bass"
+    body = client.patch(f"/api/playlists/{pid}/songs/a.archive",
+                        json={"arrangement": None}).json()
+    assert body["songs"][0]["arrangement"] is None
+
+
+def test_slot_edit_rejected_for_mix(client, server):
+    _put(server, "a.archive", "Song", "Artist")
+    pid = client.post("/api/playlists", json={"name": "Mix"}).json()["id"]
+    _add(client, pid, "a.archive")
+    r = client.patch(f"/api/playlists/{pid}/songs/a.archive", json={"arrangement": "Lead"})
+    assert r.status_code == 400
+
+
+# ── slot chart swap (same work only; position + pin kept) ────────────────────
+
+def test_slot_chart_swap_same_work(client, server):
+    _put(server, "a.archive", "Song", "Artist")
+    _put(server, "b.archive", "Song", "Artist")
+    _put(server, "z.archive", "Closer", "Artist")
+    pid = _album(client)["id"]
+    _add(client, pid, "a.archive")
+    _add(client, pid, "z.archive")
+    client.patch(f"/api/playlists/{pid}/songs/a.archive", json={"arrangement": "Lead"})
+    body = client.patch(f"/api/playlists/{pid}/songs/a.archive",
+                        json={"chart_filename": "b.archive"}).json()
+    slots = body["songs"]
+    assert [s["filename"] for s in slots] == ["b.archive", "z.archive"]   # position kept
+    assert slots[0]["arrangement"] == "Lead"                              # pin kept
+    assert slots[0]["work_key"] == server.meta_db.work_key_for("b.archive")
+
+
+def test_slot_chart_swap_rejects_other_work(client, server):
+    _put(server, "a.archive", "Song", "Artist")
+    _put(server, "x.archive", "Other", "Artist")
+    pid = _album(client)["id"]
+    _add(client, pid, "a.archive")
+    r = client.patch(f"/api/playlists/{pid}/songs/a.archive",
+                     json={"chart_filename": "x.archive"})
+    assert r.status_code == 400
+
+
+def test_slot_chart_swap_rejects_duplicate_member(client, server):
+    _put(server, "a.archive", "Song", "Artist")
+    _put(server, "b.archive", "Song", "Artist")
+    pid = _album(client)["id"]
+    _add(client, pid, "a.archive")
+    _add(client, pid, "b.archive")
+    r = client.patch(f"/api/playlists/{pid}/songs/a.archive",
+                     json={"chart_filename": "b.archive"})
+    assert r.status_code == 400
+
+
+# ── orphan-at-read self-heal (§7.2) ──────────────────────────────────────────
+
+def test_orphan_slot_resolves_to_current_keeper(client, server):
+    _put(server, "a.archive", "Song", "Artist", arrangements=("Lead", "Rhythm"))
+    _put(server, "b.archive", "Song", "Artist")
+    pid = _album(client)["id"]
+    _add(client, pid, "b.archive")                       # pin the 1-arr chart
+    server.meta_db.delete_missing({"a.archive"})         # rescan: b's file is gone
+    slot = client.get(f"/api/playlists/{pid}").json()["songs"][0]
+    assert slot["filename"] == "b.archive"               # membership NOT rewritten
+    assert slot["resolved_from_orphan"] is True
+    assert slot["resolved_filename"] == "a.archive"      # the work's current keeper
+    assert slot["title"] == "Song"
+    assert "missing" not in slot
+
+
+def test_orphan_slot_missing_when_work_gone(client, server):
+    _put(server, "a.archive", "Song", "Artist")
+    pid = _album(client)["id"]
+    _add(client, pid, "a.archive")
+    server.meta_db.delete_missing(set())                 # library emptied
+    slot = client.get(f"/api/playlists/{pid}").json()["songs"][0]
+    assert slot["missing"] is True
+    assert "resolved_filename" not in slot
+
+
+def test_mix_still_hides_dead_songs(client, server):
+    _put(server, "a.archive", "Song", "Artist")
+    pid = client.post("/api/playlists", json={"name": "Mix"}).json()["id"]
+    _add(client, pid, "a.archive")
+    server.meta_db.delete_missing(set())
+    assert client.get(f"/api/playlists/{pid}").json()["songs"] == []
+
+
+# ── list-card count parity: albums count ALL slots (list vs detail) ──────────
+
+def test_album_list_count_includes_orphaned_and_missing_slots(client, server):
+    # The detail view renders / plays EVERY album slot — a self-healing orphan
+    # and a fully-missing work both stay in the denominator (§7.2) — so the
+    # list-card count must agree. Guards against the mix "dead-filter" (count
+    # only songs still in `songs`) leaking into albums, which undercounted a
+    # slot the moment its pinned file was deleted.
+    _put(server, "a.archive", "Song", "Artist")      # work A keeper (survives)
+    _put(server, "b.archive", "Song", "Artist")      # work A, pinned then deleted
+    _put(server, "c.archive", "Closer", "Artist")    # work C, deleted whole
+    pid = _album(client)["id"]
+    _add(client, pid, "a.archive")                   # live slot
+    _add(client, pid, "b.archive")                   # → orphan (self-heals to a)
+    _add(client, pid, "c.archive")                   # → fully missing
+    server.meta_db.delete_missing({"a.archive"})     # rescan: only a survives
+    detail = client.get(f"/api/playlists/{pid}").json()["songs"]
+    assert len(detail) == 3                           # detail keeps all 3 slots
+    listed = {p["id"]: p for p in client.get("/api/playlists").json()}
+    assert listed[pid]["count"] == 3                  # list card agrees (was 1)
+
+
+def test_mix_list_count_still_dead_filters(client, server):
+    # The other side of the discriminator: a mix's list count keeps hiding dead
+    # songs, so the album fix doesn't regress non-album playlists.
+    _put(server, "a.archive", "Song", "Artist")
+    _put(server, "b.archive", "Closer", "Artist")
+    pid = client.post("/api/playlists", json={"name": "Mix"}).json()["id"]
+    _add(client, pid, "a.archive")
+    _add(client, pid, "b.archive")
+    server.meta_db.delete_missing({"a.archive"})     # b's file gone
+    listed = {p["id"]: p for p in client.get("/api/playlists").json()}
+    assert listed[pid]["count"] == 1                  # dead b not counted

tests/test_demo_mode.py

@@ -91,6 +91,21 @@ def test_demo_off_settings_post_not_blocked(tmp_path, monkeypatch):
     ("GET",    "/api/plugins/updates"),
     ("POST",   "/api/plugins/highway_3d/files"),
     ("DELETE", "/api/plugins/highway_3d/files"),
+    # Enrichment (P8): review writes + the MusicBrainz search proxy (the
+    # proxy would spend the shared rate limit for anonymous demo visitors).
+    ("POST",   "/api/enrichment/review/some-file/accept"),
+    ("POST",   "/api/enrichment/review/some-file/reject"),
+    ("POST",   "/api/enrichment/review/some-file/pick"),
+    ("POST",   "/api/enrichment/kick"),
+    ("GET",    "/api/enrichment/search"),
+    # Context menus (R2): per-song re-match + the path-exposing Get info.
+    ("POST",   "/api/enrichment/refresh/some-file"),
+    ("GET",    "/api/chart/some-file/fileinfo"),
+    # Art layer (R3): the base64 upload writes files, the server-side URL fetch
+    # touches the network, and the override delete removes files — all mutations.
+    ("POST",   "/api/song/some-file/art/upload"),
+    ("POST",   "/api/song/some-file/art/url"),
+    ("DELETE", "/api/art/some-file/override"),
 ])
 def test_demo_on_blocked_routes_return_403(tmp_path, monkeypatch, method, path):
     server, client = _make_client(tmp_path, monkeypatch, demo=True)

tests/test_enrichment_plumbing.py

@@ -0,0 +1,151 @@
+"""Tests for the metadata-enrichment plumbing (P7): the song_enrichment cache
+table + identity hashing + the queue/lifecycle around the (for now) no-op
+matcher. The text matcher itself is the next slice; these tests pin the
+contracts it will inherit: rename-survivable idempotent hashing, manual rows
+never auto-reset, never purged on rescan, purged on explicit delete."""
+
+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:
+            conn.close()
+        sys.modules.pop("server", None)
+
+
+@pytest.fixture()
+def client(server):
+    return TestClient(server.app)
+
+
+def _put(server, fn, title="Song", artist="Artist", album="", duration=100):
+    server.meta_db.put(fn, 0, 0, {
+        "title": title, "artist": artist, "album": album, "duration": duration,
+        "arrangements": [{"name": "Lead", "index": 0}],
+    })
+
+
+# ── identity hash ─────────────────────────────────────────────────────────────
+
+def test_hash_is_rename_survivable_and_normalized(server):
+    h = server.meta_db.enrichment_content_hash
+    # keyed on metadata, not the filename → a renamed pack keeps its hash
+    assert h("Artist", "Song", "Album", 100) == h("Artist", "Song", "Album", 100)
+    # case + whitespace folded; duration rounded to whole seconds
+    assert h(" artist ", "SONG", "album", 100.4) == h("Artist", "Song", "Album", 100)
+    # a real identity change means a different hash
+    assert h("Artist", "Song", "Album", 100) != h("Artist", "Other", "Album", 100)
+    assert h("Artist", "Song", "Album", None) == h("Artist", "Song", "Album", 0)
+
+
+# ── queue selection ───────────────────────────────────────────────────────────
+
+def test_pending_covers_new_unscanned_and_changed(server):
+    _put(server, "a.archive")
+    assert [r["filename"] for r in server.meta_db.enrichment_pending()] == ["a.archive"]
+    # stubbed → still unscanned → still pending (the matcher hasn't run)
+    server._background_enrich()
+    assert [r["filename"] for r in server.meta_db.enrichment_pending()] == ["a.archive"]
+    # a matched row with the CURRENT hash is settled…
+    h = server.meta_db.enrichment_content_hash("Artist", "Song", "", 100)
+    with server.meta_db._lock:
+        server.meta_db.conn.execute(
+            "UPDATE song_enrichment SET match_state = 'matched', content_hash = ? "
+            "WHERE filename = 'a.archive'", (h,))
+        server.meta_db.conn.commit()
+    assert server.meta_db.enrichment_pending() == []
+    # …until the song's identity changes, which re-queues it
+    _put(server, "a.archive", title="Song (Remastered)")
+    assert [r["filename"] for r in server.meta_db.enrichment_pending()] == ["a.archive"]
+
+
+def test_hash_change_resets_matched_but_never_manual(server):
+    _put(server, "a.archive")
+    _put(server, "b.archive", title="Other")
+    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 = 'manual' WHERE filename = 'b.archive'")
+        server.meta_db.conn.commit()
+    # identity edits…
+    _put(server, "a.archive", title="Song v2")
+    _put(server, "b.archive", title="Other v2")
+    server._background_enrich()
+    a = server.meta_db.get_enrichment("a.archive")
+    b = server.meta_db.get_enrichment("b.archive")
+    # …drop a stale MATCH back to unscanned with the fresh hash
+    assert a["match_state"] == "unscanned"
+    assert a["content_hash"] == server.meta_db.enrichment_content_hash("Artist", "Song v2", "", 100)
+    # …but a MANUAL pin survives untouched (state AND hash)
+    assert b["match_state"] == "manual"
+    assert b["content_hash"] == server.meta_db.enrichment_content_hash("Artist", "Other", "", 100)
+
+
+def test_failed_rows_not_requeued_by_pending(server):
+    _put(server, "a.archive")
+    server._background_enrich()
+    with server.meta_db._lock:
+        server.meta_db.conn.execute(
+            "UPDATE song_enrichment SET match_state = 'failed' WHERE filename = 'a.archive'")
+        server.meta_db.conn.commit()
+    # backoff/retry policy belongs to the matcher slice, not the queue walk
+    assert server.meta_db.enrichment_pending() == []
+
+
+# ── worker pass ───────────────────────────────────────────────────────────────
+
+def test_enrich_pass_stamps_every_song(server):
+    for i in range(5):
+        _put(server, f"s{i}.archive", title=f"Song {i}")
+    server._background_enrich()
+    for i in range(5):
+        row = server.meta_db.get_enrichment(f"s{i}.archive")
+        assert row is not None
+        assert row["match_state"] == "unscanned"
+        assert row["content_hash"] == server.meta_db.enrichment_content_hash(
+            "Artist", f"Song {i}", "", 100)
+
+
+# ── lifecycle: rescan survival vs explicit delete ─────────────────────────────
+
+def test_rescan_never_purges_enrichment(server):
+    _put(server, "a.archive")
+    server._background_enrich()
+    server.meta_db.delete_missing(set())          # file vanished from a scan snapshot
+    assert server.meta_db.get_enrichment("a.archive") is not None   # row survives
+    # …and is invisible in the read-time-filtered counts
+    assert server.meta_db.enrichment_state_counts() == {}
+    _put(server, "a.archive")                     # the file comes back
+    assert server.meta_db.enrichment_state_counts() == {"unscanned": 1}
+
+
+def test_status_endpoint_counts(client, server):
+    _put(server, "a.archive")
+    _put(server, "b.archive", title="Other")
+    server._background_enrich()
+    body = client.get("/api/enrichment/status").json()
+    assert body["states"] == {"unscanned": 2}
+    assert body["total_songs"] == 2
+    assert body["running"] is False
+    assert body["processed"] == 2
+
+
+def test_art_cache_dir_created(server):
+    d = server._enrichment_art_dir()
+    assert d.is_dir()
+    assert d.name == "art_cache"

tests/test_gap_fill.py

@@ -0,0 +1,270 @@
+"""Tests for the R4a gap-fill write-back — the §7 contract made executable:
+user-initiated, adds ABSENT keys only (author bytes preserved verbatim),
+spec'd-keys allowlist, values only from a CONFIRMED match, atomic + .bak.
+
+No network anywhere: matches are seeded straight into the enrichment cache
+(as the P8 matcher would have written them).
+"""
+
+import importlib
+import sys
+import time
+import zipfile
+
+import pytest
+import yaml
+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:
+        # A write endpoint kicks a background scan (which then kicks the
+        # enrichment worker); both daemon threads share meta_db's sqlite
+        # connection. Drain them before closing it — closing mid-scan
+        # crashes the thread with an access violation on Windows. Network
+        # is off (FEEDBACK_SKIP_STARTUP_TASKS), so both drain in ms.
+        deadline = time.time() + 10
+        while time.time() < deadline and (
+                srv._scan_status.get("running")
+                or srv._enrich_status.get("running")):
+            time.sleep(0.05)
+        conn = getattr(getattr(srv, "meta_db", None), "conn", None)
+        if conn is not None:
+            conn.close()
+        sys.modules.pop("server", None)
+
+
+@pytest.fixture()
+def client(server):
+    return TestClient(server.app)
+
+
+BASE_MANIFEST = ("# my hand-made pack\n"
+                 "title: Thunderstruck\n"
+                 "artist: AC/DC   # the real one\n"
+                 "duration: 292\n"
+                 "arrangements: []\n"
+                 "stems: []\n")
+
+
+def make_dir_sloppak(server, name, manifest=BASE_MANIFEST):
+    d = server.DLC_DIR / name
+    d.mkdir(parents=True)
+    (d / "manifest.yaml").write_text(manifest, encoding="utf-8")
+    _put_db(server, name)
+    return d
+
+
+def make_zip_sloppak(server, name, manifest=BASE_MANIFEST):
+    p = server.DLC_DIR / name
+    with zipfile.ZipFile(p, "w", zipfile.ZIP_DEFLATED) as z:
+        z.writestr("manifest.yaml", manifest)
+        z.writestr("stems/full.ogg", b"OggS-fake")
+    _put_db(server, name)
+    return p
+
+
+def _put_db(server, name):
+    server.meta_db.put(name, 0, 0, {
+        "title": "Thunderstruck", "artist": "AC/DC", "album": "", "year": "",
+        "duration": 292, "arrangements": [{"name": "Lead", "index": 0}],
+    })
+
+
+def seed_match(server, fn, state="matched", **overrides):
+    """Seed a confirmed enrichment row as the P8 matcher would have."""
+    cand = {"recording_id": "12345678-abcd-4ef0-9876-0123456789ab",
+            "release_id": "rel-1", "artist_id": "art-1",
+            "artist": "AC/DC", "title": "Thunderstruck",
+            "album": "The Razors Edge", "year": "1990",
+            "genres": ["hard rock", "rock"], "isrc": "AUAP09000045"}
+    cand.update(overrides)
+    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=cand,
+        candidates=([cand] if state == "review" else None))
+
+
+# ── preview ───────────────────────────────────────────────────────────────────
+
+def test_preview_offers_only_absent_confirmed_keys(server, client):
+    make_dir_sloppak(server, "a.sloppak")
+    seed_match(server, "a.sloppak")
+    d = client.get("/api/song/a.sloppak/gap-fill").json()
+    assert d["eligible"] is True
+    got = {m["key"]: m["value"] for m in d["missing"]}
+    assert got == {"album": "The Razors Edge", "year": 1990,
+                   "genres": ["hard rock", "rock"],
+                   "mbid": "12345678-abcd-4ef0-9876-0123456789ab",
+                   "isrc": "AUAP09000045"}
+
+
+def test_preview_excludes_author_set_keys(server, client):
+    make_dir_sloppak(server, "a.sloppak",
+                     BASE_MANIFEST + "album: Live Bootleg\nyear: 1991\n")
+    seed_match(server, "a.sloppak")
+    got = {m["key"] for m in client.get("/api/song/a.sloppak/gap-fill").json()["missing"]}
+    assert "album" not in got and "year" not in got
+    assert {"genres", "mbid", "isrc"} <= got
+
+
+def test_preview_excludes_present_but_empty_keys(server, client):
+    """Gap-fill is append-only, so a present-but-empty value (album: '',
+    year: 0) is NOT a gap the writer can fill — appending would duplicate the
+    key, and the never-clobber guard refuses any present key. The preview must
+    therefore not offer it (those are the metadata editor's job to re-serialize),
+    while genuinely-absent keys are still offered."""
+    make_dir_sloppak(server, "a.sloppak", BASE_MANIFEST + "album: ''\nyear: 0\n")
+    seed_match(server, "a.sloppak")
+    got = {m["key"] for m in client.get("/api/song/a.sloppak/gap-fill").json()["missing"]}
+    assert "album" not in got and "year" not in got
+    assert {"genres", "mbid", "isrc"} <= got
+
+
+def test_write_present_but_empty_key_is_refused_not_500(server, client):
+    """The preview↔writer contract must agree: a POST for a present-but-empty
+    key is turned away with a clean 409 (never offered → skipped), never a 500
+    from the writer's never-clobber guard, and the file is left untouched."""
+    d = make_dir_sloppak(server, "a.sloppak", BASE_MANIFEST + "album: ''\nyear: 0\n")
+    seed_match(server, "a.sloppak")
+    before = (d / "manifest.yaml").read_text(encoding="utf-8")
+    r = client.post("/api/song/a.sloppak/gap-fill", json={"keys": ["album", "year"]})
+    assert r.status_code == 409
+    assert sorted(r.json()["skipped"]) == ["album", "year"]
+    assert (d / "manifest.yaml").read_text(encoding="utf-8") == before
+    assert not (d / "manifest.yaml.bak").exists()   # nothing written → no backup
+    # A genuinely-absent key alongside the empty ones still writes cleanly.
+    r = client.post("/api/song/a.sloppak/gap-fill", json={"keys": ["album", "genres"]})
+    assert r.status_code == 200
+    assert r.json() == {"ok": True, "written": {"genres": ["hard rock", "rock"]},
+                        "skipped": ["album"]}
+
+
+def test_preview_requires_confirmed_match(server, client):
+    make_dir_sloppak(server, "a.sloppak")
+    d = client.get("/api/song/a.sloppak/gap-fill").json()
+    assert d["eligible"] is False and d["reason"] == "no-match"
+    seed_match(server, "a.sloppak", state="review")
+    d = client.get("/api/song/a.sloppak/gap-fill").json()
+    assert d["eligible"] is False and d["reason"] == "review"
+    # A user-pinned match is confirmed.
+    seed_match(server, "a.sloppak", state="manual")
+    assert client.get("/api/song/a.sloppak/gap-fill").json()["eligible"] is True
+
+
+# ── writing ───────────────────────────────────────────────────────────────────
+
+def test_write_dir_form_appends_and_preserves_author_bytes(server, client):
+    d = make_dir_sloppak(server, "a.sloppak")
+    seed_match(server, "a.sloppak")
+    r = client.post("/api/song/a.sloppak/gap-fill",
+                    json={"keys": ["album", "year", "genres", "mbid", "isrc"]})
+    assert r.status_code == 200
+    body = r.json()
+    assert set(body["written"]) == {"album", "year", "genres", "mbid", "isrc"}
+    text = (d / "manifest.yaml").read_text(encoding="utf-8")
+    # The author's original bytes — comments included — survive verbatim as a
+    # prefix; the additions are appended after them.
+    assert text.startswith(BASE_MANIFEST)
+    manifest = yaml.safe_load(text)
+    assert manifest["album"] == "The Razors Edge"
+    assert manifest["year"] == 1990
+    assert manifest["genres"] == ["hard rock", "rock"]
+    assert manifest["mbid"] == "12345678-abcd-4ef0-9876-0123456789ab"
+    assert manifest["isrc"] == "AUAP09000045"
+    # Backup + DB sync (the row must match what the scanner would derive).
+    assert (d / "manifest.yaml.bak").read_text(encoding="utf-8") == BASE_MANIFEST
+    row = client.get("/api/song/a.sloppak").json()
+    assert row["album"] == "The Razors Edge"
+    assert str(row["year"]) == "1990"
+
+
+def test_write_zip_form_appends_with_backup(server, client):
+    p = make_zip_sloppak(server, "a.sloppak")
+    seed_match(server, "a.sloppak")
+    r = client.post("/api/song/a.sloppak/gap-fill", json={"keys": ["album", "mbid"]})
+    assert r.status_code == 200
+    with zipfile.ZipFile(p) as z:
+        text = z.read("manifest.yaml").decode("utf-8")
+        assert text.startswith(BASE_MANIFEST)
+        manifest = yaml.safe_load(text)
+        assert manifest["album"] == "The Razors Edge"
+        assert manifest["mbid"] == "12345678-abcd-4ef0-9876-0123456789ab"
+        assert "year" not in manifest            # unrequested keys untouched
+        assert z.read("stems/full.ogg") == b"OggS-fake"
+    bak = p.with_name(p.name + ".bak")
+    assert bak.exists()
+    with zipfile.ZipFile(bak) as z:
+        assert z.read("manifest.yaml").decode("utf-8") == BASE_MANIFEST
+
+
+def test_write_never_replaces_author_values(server, client):
+    d = make_dir_sloppak(server, "a.sloppak", BASE_MANIFEST + "album: Live Bootleg\n")
+    seed_match(server, "a.sloppak")
+    # Requesting a present key: skipped, not replaced; nothing else requested
+    # → 409 and the file is untouched.
+    r = client.post("/api/song/a.sloppak/gap-fill", json={"keys": ["album"]})
+    assert r.status_code == 409
+    assert r.json()["skipped"] == ["album"]
+    assert (d / "manifest.yaml").read_text(encoding="utf-8").endswith("album: Live Bootleg\n")
+    # Mixed request: the gap is written, the author value survives.
+    r = client.post("/api/song/a.sloppak/gap-fill", json={"keys": ["album", "year"]})
+    assert r.status_code == 200
+    assert r.json() == {"ok": True, "written": {"year": 1990}, "skipped": ["album"]}
+    manifest = yaml.safe_load((d / "manifest.yaml").read_text(encoding="utf-8"))
+    assert manifest["album"] == "Live Bootleg"
+    assert manifest["year"] == 1990
+
+
+def test_writer_last_line_guard(server):
+    """The lib-level never-clobber guard holds even if a caller skips the
+    proposal check."""
+    import songmeta
+    d = make_dir_sloppak(server, "a.sloppak", BASE_MANIFEST + "album: Kept\n")
+    with pytest.raises(ValueError):
+        songmeta.gap_fill_sloppak(d, {"album": "Clobber"})
+    assert "Kept" in (d / "manifest.yaml").read_text(encoding="utf-8")
+
+
+def test_write_validates_keys(server, client):
+    make_dir_sloppak(server, "a.sloppak")
+    seed_match(server, "a.sloppak")
+    assert client.post("/api/song/a.sloppak/gap-fill",
+                       json={"keys": ["title"]}).status_code == 400
+    assert client.post("/api/song/a.sloppak/gap-fill",
+                       json={"keys": []}).status_code == 400
+    assert client.post("/api/song/a.sloppak/gap-fill", json={}).status_code == 400
+
+
+def test_demo_mode_blocks_write(tmp_path, monkeypatch, isolate_logging):
+    """The middleware turns the write route away before any handler runs —
+    demo visitors can never rewrite pack files."""
+    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")
+    monkeypatch.setenv("FEEDBACK_DEMO_MODE", "1")
+    sys.modules.pop("server", None)
+    srv = importlib.import_module("server")
+    try:
+        r = TestClient(srv.app).post("/api/song/a.sloppak/gap-fill",
+                                     json={"keys": ["album"]})
+        assert r.status_code == 403
+    finally:
+        conn = getattr(getattr(srv, "meta_db", None), "conn", None)
+        if conn is not None:
+            conn.close()
+        sys.modules.pop("server", None)

tests/test_gp2notation.py

@@ -454,6 +454,86 @@ def test_convert_file_writes_notation_sidecar_for_keys_only(tmp_path, monkeypatc
     assert beats[0]["notes"] == [{"midi": 60}]  # 48 + fret 12
 
 
+# A GP8 grand-staff piano (one Track, two <Staff> entries → two MasterBar/Bars
+# columns) followed by a guitar track. The treble stave carries a String=5 note
+# that only decodes against the 6-entry treble tuning — under the old
+# last-stave-tuning-wins bug it indexed out of range against the 5-entry bass
+# tuning and was silently dropped. The guitar's single note sits at column 2,
+# so it also exercises the bar-column offset after a multi-stave predecessor.
+_GPIF_GRAND_STAFF_PIANO = """
+<GPIF>
+  <Score><Title>T</Title><Artist>A</Artist></Score>
+  <Tracks>
+    <Track id="0"><Name>Piano</Name>
+      <Staves>
+        <Staff><Properties><Property name="Tuning">
+          <Pitches>76 71 67 62 57 52</Pitches></Property></Properties></Staff>
+        <Staff><Properties><Property name="Tuning">
+          <Pitches>50 45 40 35 30</Pitches></Property></Properties></Staff>
+      </Staves></Track>
+    <Track id="1"><Name>Lead Guitar</Name>
+      <Property name="Tuning"><Pitches>64 59 55 50 45 40</Pitches></Property></Track>
+  </Tracks>
+  <MasterBars>
+    <MasterBar><Time>4/4</Time><Bars>0 1 2</Bars></MasterBar>
+  </MasterBars>
+  <Bars>
+    <Bar id="0"><Voices>0</Voices></Bar>
+    <Bar id="1"><Voices>1</Voices></Bar>
+    <Bar id="2"><Voices>2</Voices></Bar>
+  </Bars>
+  <Voices>
+    <Voice id="0"><Beats>b0</Beats></Voice>
+    <Voice id="1"><Beats>b1</Beats></Voice>
+    <Voice id="2"><Beats>b2</Beats></Voice>
+  </Voices>
+  <Beats>
+    <Beat id="b0"><Rhythm ref="r0"/><Notes>n0</Notes></Beat>
+    <Beat id="b1"><Rhythm ref="r0"/><Notes>n1</Notes></Beat>
+    <Beat id="b2"><Rhythm ref="r0"/><Notes>n2</Notes></Beat>
+  </Beats>
+  <Notes>
+    <Note id="n0">
+      <Property name="String"><String>5</String></Property>
+      <Property name="Fret"><Fret>0</Fret></Property></Note>
+    <Note id="n1">
+      <Property name="String"><String>0</String></Property>
+      <Property name="Fret"><Fret>0</Fret></Property></Note>
+    <Note id="n2">
+      <Property name="String"><String>0</String></Property>
+      <Property name="Fret"><Fret>3</Fret></Property></Note>
+  </Notes>
+  <Rhythms><Rhythm id="r0"><NoteValue>Quarter</NoteValue></Rhythm></Rhythms>
+</GPIF>
+"""
+
+
+def test_convert_file_folds_grand_staff_and_offsets_bar_column(tmp_path, monkeypatch):
+    monkeypatch.setattr(gp2rs_gpx, "_load_gpif",
+                        lambda _p: ET.fromstring(_GPIF_GRAND_STAFF_PIANO))
+    out_files = gp2rs_gpx.convert_file(
+        "dummy.gpx", str(tmp_path), track_indices=[0, 1],
+        arrangement_names={0: "Keys", 1: "Lead"},
+    )
+    keys_xml = next(p for p in out_files if "Keys" in p)
+    guitar_xml = next(p for p in out_files if "Lead" in p)
+
+    def _notes(xml_path):
+        root = ET.parse(xml_path).getroot()
+        return [(int(n.get("string")), int(n.get("fret"))) for n in root.iter("note")]
+
+    # Both staves are folded into the one keys arrangement (keys encoding =
+    # midi//24, midi%24): treble E3 (52, the String=5 note the old bug dropped)
+    # AND bass D3 (50, the stave-1 column).
+    keys_midi = sorted(s * 24 + f for s, f in _notes(keys_xml))
+    assert keys_midi == [50, 52]
+    # The guitar note lives at bar column 2 (after the 2-column piano). Its own
+    # bar carries fret 3; the bass column it would wrongly read has fret 0, so a
+    # single fret-3 note proves the multi-stave column offset landed correctly.
+    guitar = _notes(guitar_xml)
+    assert len(guitar) == 1 and guitar[0][1] == 3
+
+
 def test_convert_file_sidecar_failure_does_not_break_conversion(tmp_path, monkeypatch):
     monkeypatch.setattr(gp2rs_gpx, "_load_gpif",
                         lambda _p: ET.fromstring(_GPIF_KEYS_AND_GUITAR))

tests/test_group_filter_law.py

@@ -0,0 +1,200 @@
+"""Tests for P5e: the grouped filter law (chart-intrinsic filters match ANY
+member of a work + the display_chart switch), the group-aggregate mastery
+sort, the history-sticky auto-pick, and the split annotations."""
+
+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:
+            conn.close()
+        sys.modules.pop("server", None)
+
+
+@pytest.fixture()
+def client(server):
+    return TestClient(server.app)
+
+
+def _put(server, fn, title, artist, arrangements=1, tuning="E Standard",
+         mtime=0, lyrics=False):
+    arr = [{"name": "Lead", "index": i} for i in range(arrangements)]
+    server.meta_db.put(fn, mtime, 0, {
+        "title": title, "artist": artist, "arrangements": arr,
+        "tuning_name": tuning, "has_lyrics": lyrics,
+    })
+
+
+def _page(client, **params):
+    return client.get("/api/library", params={"group": 1, **params}).json()
+
+
+# ── chart-intrinsic filters: match if ANY member matches ─────────────────────
+
+def test_intrinsic_filter_matches_any_member(client, server):
+    _put(server, "a.archive", "Song", "Artist", arrangements=2, tuning="E Standard")
+    _put(server, "b.archive", "Song", "Artist", arrangements=1, tuning="Drop D")
+    body = _page(client, tunings="Drop D")
+    # the work qualifies through member b even though the representative (a,
+    # most arrangements) is E Standard…
+    assert body["total"] == 1
+    row = body["songs"][0]
+    # …and the ROW stays the representative (sort/cursor identity) while the
+    # card's display/play facts switch to the matching member.
+    assert row["filename"] == "a.archive"
+    assert row["display_chart"]["filename"] == "b.archive"
+    assert row["display_chart"]["tuning_name"] == "Drop D"
+
+
+def test_no_display_chart_when_rep_matches(client, server):
+    _put(server, "a.archive", "Song", "Artist", arrangements=2, tuning="Drop D")
+    _put(server, "b.archive", "Song", "Artist", arrangements=1, tuning="Drop D")
+    row = _page(client, tunings="Drop D")["songs"][0]
+    assert row["filename"] == "a.archive"
+    assert "display_chart" not in row
+
+
+def test_intrinsic_filter_ungrouped_unchanged(client, server):
+    _put(server, "a.archive", "Song", "Artist", arrangements=2, tuning="E Standard")
+    _put(server, "b.archive", "Song", "Artist", arrangements=1, tuning="Drop D")
+    body = client.get("/api/library", params={"tunings": "Drop D"}).json()
+    assert body["total"] == 1
+    assert body["songs"][0]["filename"] == "b.archive"
+    assert "display_chart" not in body["songs"][0]
+
+
+def test_lyrics_filter_matches_any_member(client, server):
+    _put(server, "a.archive", "Song", "Artist", arrangements=2, lyrics=False)
+    _put(server, "b.archive", "Song", "Artist", arrangements=1, lyrics=True)
+    body = _page(client, has_lyrics=1)
+    assert body["total"] == 1
+    assert body["songs"][0]["display_chart"]["filename"] == "b.archive"
+
+
+def test_stats_count_matches_page_under_filter(client, server):
+    _put(server, "a.archive", "Song", "Artist", arrangements=2, tuning="E Standard")
+    _put(server, "b.archive", "Song", "Artist", arrangements=1, tuning="Drop D")
+    _put(server, "c.archive", "Other", "Artist", tuning="E Standard")   # no Drop D chart
+    page = _page(client, tunings="Drop D")
+    stats = client.get("/api/library/stats",
+                       params={"group": 1, "tunings": "Drop D"}).json()
+    assert page["total"] == 1
+    assert stats["total_songs"] == page["total"]
+
+
+# ── work-identity + practice-state stay on the representative ────────────────
+
+def test_practice_state_anchors_on_preferred(client, server):
+    _put(server, "a.archive", "Song", "Artist", arrangements=2)   # unplayed
+    _put(server, "b.archive", "Song", "Artist", arrangements=1)
+    server.meta_db.record_session("b.archive", 0, score=950, accuracy=0.95)
+    # pin the unplayed chart as YOUR pick (without a pin the played chart is
+    # the sticky auto-rep, so the anchor would legitimately read mastered)
+    wk = server.meta_db.work_key_for("a.archive")
+    server.meta_db.set_chart_preferred(wk, "a.archive")
+    # mastered band reads the PREFERRED chart (unplayed) — the work is not
+    # "mastered" just because an alternate chart is (§7.1 practice-state law)
+    assert _page(client, mastery="mastered")["total"] == 0
+    # …but the flat view still finds the mastered chart itself
+    flat = client.get("/api/library", params={"mastery": "mastered"}).json()
+    assert [s["filename"] for s in flat["songs"]] == ["b.archive"]
+
+
+# ── mastery sort aggregates MAX across the group ─────────────────────────────
+
+def test_mastery_sort_aggregates_across_group(client, server):
+    _put(server, "a1.archive", "One", "Artist", arrangements=2)
+    _put(server, "a2.archive", "One", "Artist", arrangements=1)
+    _put(server, "b.archive", "Two", "Artist")                    # singleton work 2
+    server.meta_db.record_session("a2.archive", 0, score=950, accuracy=0.95)
+    server.meta_db.record_session("b.archive", 0, score=500, accuracy=0.5)
+    # pin the UNPLAYED chart as work 1's keeper — the aggregate must still
+    # surface the work via its touched member ("a song surfaces on any chart
+    # you've touched"), even though the preferred chart has no stats
+    wk = server.meta_db.work_key_for("a1.archive")
+    server.meta_db.set_chart_preferred(wk, "a1.archive")
+    desc = [s["filename"] for s in _page(client, sort="mastery-desc")["songs"]]
+    assert desc == ["a1.archive", "b.archive"]                    # 0.95 > 0.5, row = keeper
+    asc = [s["filename"] for s in _page(client, sort="mastery")["songs"]]
+    assert asc == ["b.archive", "a1.archive"]
+
+
+# ── history-sticky auto-pick ──────────────────────────────────────────────────
+
+def test_autopick_sticks_with_played_chart(client, server):
+    _put(server, "a.archive", "Song", "Artist", arrangements=1, mtime=1)
+    server.meta_db.record_session("a.archive", 0, score=500, accuracy=0.5)
+    # a newer, more complete chart imports — the pick must NOT silently migrate
+    _put(server, "b.archive", "Song", "Artist", arrangements=3, mtime=2)
+    assert _page(client)["songs"][0]["filename"] == "a.archive"
+
+
+def test_autopick_completeness_still_wins_when_unplayed(client, server):
+    _put(server, "a.archive", "Song", "Artist", arrangements=1, mtime=1)
+    _put(server, "b.archive", "Song", "Artist", arrangements=3, mtime=2)
+    assert _page(client)["songs"][0]["filename"] == "b.archive"
+
+
+def test_autopick_one_off_try_does_not_steal_pick(client, server):
+    # incumbent: practiced repeatedly, minimal chart; a one-off try of a more
+    # complete alternate must NOT retarget the pick (casual try ≠ adopt)
+    _put(server, "a.archive", "Song", "Artist", arrangements=1, mtime=1)
+    for _ in range(3):
+        server.meta_db.record_session("a.archive", 0, score=500, accuracy=0.5)
+    _put(server, "b.archive", "Song", "Artist", arrangements=3, mtime=2)
+    server.meta_db.record_session("b.archive", 0, score=500, accuracy=0.5)
+    assert _page(client)["songs"][0]["filename"] == "a.archive"
+
+
+# ── split annotations (the ⋮ "Rejoin other versions" undo) ───────────────────
+
+def test_split_flags_on_rows_and_chart_work(client, server):
+    _put(server, "a.archive", "Song", "Artist")
+    _put(server, "b.archive", "Song", "Artist")
+    client.post("/api/chart/b.archive/split")
+    rows = {s["filename"]: s for s in _page(client)["songs"]}
+    assert rows["b.archive"]["is_split"] is True
+    assert rows["a.archive"]["is_split"] is False
+    assert client.get("/api/chart/b.archive/work").json()["is_split"] is True
+    assert client.get("/api/chart/a.archive/work").json()["is_split"] is False
+
+
+# ── keyset paging stays exact under the member-match predicate ────────────────
+
+def test_grouped_keyset_pagination_with_intrinsic_filter(client, server):
+    # 5 works; each has an E-Standard rep (2 arrangements) + a Drop-D member,
+    # so the Drop-D filter admits every work through a NON-representative chart.
+    for i in range(5):
+        _put(server, f"w{i}rep.archive", f"Song {i}", f"Artist {i}",
+             arrangements=2, tuning="E Standard")
+        _put(server, f"w{i}alt.archive", f"Song {i}", f"Artist {i}",
+             arrangements=1, tuning="Drop D")
+    seen, cursor = [], None
+    for _ in range(10):
+        # Title sort — the keyset proof needs a sort that still keysets
+        # (artist sorts page by OFFSET since the title-secondary change).
+        params = {"group": 1, "tunings": "Drop D", "size": 2, "sort": "title"}
+        if cursor:
+            params["after"] = cursor
+        body = client.get("/api/library", params=params).json()
+        if not body["songs"]:
+            break
+        seen += [s["filename"] for s in body["songs"]]
+        cursor = body["next_cursor"]
+        if not cursor:
+            break
+    assert seen == [f"w{i}rep.archive" for i in range(5)]   # no skip, no dupe
+    assert all(s.startswith("w") and "rep" in s for s in seen)

tests/test_highway_ws_instrument_routing.py

@@ -0,0 +1,191 @@
+"""Tests for instrument->chart arrangement routing in the highway WS.
+
+When no explicit arrangement is requested, the WS picks the arrangement matching
+the player's selected instrument (config.json `instrument`) so a bass player gets
+the Bass part instead of the default Lead/guitar chart. An explicit arrangement
+request always wins.
+"""
+
+from __future__ import annotations
+
+import importlib
+import json
+import sys
+
+import pytest
+import yaml
+from fastapi.testclient import TestClient
+
+
+def _arr(notes):
+    return {
+        "notes": notes,
+        "chords": [],
+        "anchors": [],
+        "handshapes": [],
+        "templates": [],
+        "beats": [{"time": 0.0, "measure": 1}],
+        "sections": [{"name": "intro", "number": 1, "time": 0.0}],
+    }
+
+
+def _write_multi_arr_sloppak(dlc_root):
+    """A song with a Lead (guitar) and a Bass arrangement, Lead first (index 0)."""
+    pak = dlc_root / "multi.sloppak"
+    pak.mkdir()
+    (pak / "arrangements").mkdir()
+    (pak / "arrangements" / "lead.json").write_text(json.dumps(_arr([])))
+    (pak / "arrangements" / "bass.json").write_text(json.dumps(_arr([])))
+    manifest = {
+        "title": "Multi",
+        "artist": "Tester",
+        "album": "",
+        "year": 2026,
+        "duration": 10.0,
+        "arrangements": [
+            {"id": "lead", "name": "Lead", "file": "arrangements/lead.json"},
+            {"id": "bass", "name": "Bass", "file": "arrangements/bass.json"},
+        ],
+        "stems": [],
+    }
+    (pak / "manifest.yaml").write_text(yaml.safe_dump(manifest, sort_keys=False))
+    return pak
+
+
+def _write_sloppak(dlc_root, name, arrangements):
+    """Write a .sloppak whose arrangements are (id, display-name) pairs, in order."""
+    pak = dlc_root / f"{name}.sloppak"
+    pak.mkdir()
+    (pak / "arrangements").mkdir()
+    manifest_arrs = []
+    for arr_id, arr_name in arrangements:
+        (pak / "arrangements" / f"{arr_id}.json").write_text(json.dumps(_arr([])))
+        manifest_arrs.append(
+            {"id": arr_id, "name": arr_name, "file": f"arrangements/{arr_id}.json"}
+        )
+    manifest = {
+        "title": name,
+        "artist": "Tester",
+        "album": "",
+        "year": 2026,
+        "duration": 10.0,
+        "arrangements": manifest_arrs,
+        "stems": [],
+    }
+    (pak / "manifest.yaml").write_text(yaml.safe_dump(manifest, sort_keys=False))
+    return pak
+
+
+@pytest.fixture()
+def make_client(tmp_path, monkeypatch):
+    def _make(instrument=None, default_arrangement=None):
+        cfg = tmp_path / "config"
+        cfg.mkdir(exist_ok=True)
+        conf = {}
+        if instrument is not None:
+            conf["instrument"] = instrument
+        if default_arrangement is not None:
+            conf["default_arrangement"] = default_arrangement
+        if conf:
+            (cfg / "config.json").write_text(json.dumps(conf), encoding="utf-8")
+        monkeypatch.setenv("CONFIG_DIR", str(cfg))
+        monkeypatch.setenv("DLC_DIR", str(tmp_path / "dlc"))
+        monkeypatch.setenv("FEEDBACK_SYNC_STARTUP", "1")
+        sys.modules.pop("server", None)
+        server = importlib.import_module("server")
+        monkeypatch.setattr(server, "load_plugins", lambda *a, **kw: None)
+        monkeypatch.setattr(server, "startup_scan", lambda: None)
+        monkeypatch.setattr(server, "SLOPPAK_CACHE_DIR", tmp_path / "cache")
+        return server
+
+    (tmp_path / "dlc").mkdir()
+    yield _make
+    server = sys.modules.get("server")
+    conn = getattr(getattr(server, "meta_db", None), "conn", None)
+    if conn is not None:
+        conn.close()
+
+
+def _arr_index(client, path):
+    with client.websocket_connect(path) as ws:
+        for _ in range(200):
+            msg = ws.receive_json()
+            if msg.get("error"):
+                raise AssertionError(f"WS error frame: {msg}")
+            if msg.get("type") == "song_info":
+                return msg["arrangement_index"]
+            if msg.get("type") == "ready":
+                break
+    raise AssertionError("no song_info frame received")
+
+
+def test_bass_instrument_routes_to_bass_arrangement(make_client):
+    server = make_client(instrument="bass")
+    _write_multi_arr_sloppak(server._get_dlc_dir())
+    with TestClient(server.app) as client:
+        # No explicit arrangement → route to Bass (index 1), not the default Lead.
+        idx = _arr_index(client, "/ws/highway/multi.sloppak?naming_mode=smart")
+    assert idx == 1
+
+
+def test_guitar_instrument_keeps_default(make_client):
+    server = make_client(instrument="guitar")
+    _write_multi_arr_sloppak(server._get_dlc_dir())
+    with TestClient(server.app) as client:
+        idx = _arr_index(client, "/ws/highway/multi.sloppak?naming_mode=smart")
+    assert idx == 0  # guitar falls through to the default → Lead
+
+
+def test_explicit_arrangement_overrides_instrument(make_client):
+    server = make_client(instrument="bass")
+    _write_multi_arr_sloppak(server._get_dlc_dir())
+    with TestClient(server.app) as client:
+        # An explicit arrangement request wins even for a bass player.
+        idx = _arr_index(client, "/ws/highway/multi.sloppak?arrangement=0")
+    assert idx == 0
+
+
+def test_bass_with_no_bass_part_falls_through_to_guitar(make_client):
+    server = make_client(instrument="bass")
+    # Lead + Rhythm, no bass part at all.
+    _write_sloppak(server._get_dlc_dir(), "gtr", [("lead", "Lead"), ("rhythm", "Rhythm")])
+    with TestClient(server.app) as client:
+        idx = _arr_index(client, "/ws/highway/gtr.sloppak")
+    assert idx == 0  # no bass candidate → existing default (a guitar part)
+
+
+def test_bass_no_pref_picks_the_primary_bass_not_an_alt(make_client):
+    server = make_client(instrument="bass")
+    # Lead + two bass parts; the canonical "Bass" should win over "Bass 2".
+    _write_sloppak(
+        server._get_dlc_dir(), "bb",
+        [("lead", "Lead"), ("bass", "Bass"), ("bass2", "Bass 2")],
+    )
+    with TestClient(server.app) as client:
+        idx = _arr_index(client, "/ws/highway/bb.sloppak")
+    assert idx == 1  # the primary Bass, not the first-in-order-if-it-were-an-alt
+
+
+def test_bass_honors_saved_pref_within_the_bass_parts(make_client):
+    # A bass player who saved "Bass 2" keeps it — instrument routing must not clobber
+    # the preference with the primary Bass.
+    server = make_client(instrument="bass", default_arrangement="Bass 2")
+    _write_sloppak(
+        server._get_dlc_dir(), "bb",
+        [("lead", "Lead"), ("bass", "Bass"), ("bass2", "Bass 2")],
+    )
+    with TestClient(server.app) as client:
+        idx = _arr_index(client, "/ws/highway/bb.sloppak")
+    assert idx == 2  # the preferred Bass 2, not the primary Bass (index 1)
+
+
+def test_guitar_still_honors_saved_pref(make_client):
+    # Guitar routing unchanged: a saved default_arrangement still applies.
+    server = make_client(instrument="guitar", default_arrangement="Rhythm")
+    _write_sloppak(
+        server._get_dlc_dir(), "gtr2",
+        [("lead", "Lead"), ("rhythm", "Rhythm"), ("bass", "Bass")],
+    )
+    with TestClient(server.app) as client:
+        idx = _arr_index(client, "/ws/highway/gtr2.sloppak")
+    assert idx == 1  # Rhythm, per preference

tests/test_library_keyset.py

@@ -73,7 +73,10 @@ def _walk_offset(client, sort, size, total):
     return seen
 
 
-@pytest.mark.parametrize("sort", ["artist", "artist-desc", "title", "title-desc", "recent"])
+# artist/artist-desc left out: their ORDER BY carries a title secondary
+# (grid cards read alphabetically within an artist, like the tree), which
+# the two-term cursor cannot seek — they page by OFFSET (covered below).
+@pytest.mark.parametrize("sort", ["title", "title-desc", "recent"])
 def test_keyset_matches_offset_exactly(client, server_mod, sort):
     _seed(server_mod, 25)
     offset_order = _walk_offset(client, sort, 7, 25)
@@ -87,15 +90,17 @@ def test_stable_tiebreak_on_equal_keys(client, server_mod):
     # 25 songs, all the SAME artist → the artist sort is decided entirely by the
     # filename tiebreak. Both pagers must still cover all 25 with no dupe.
     _seed(server_mod, 25, shared_artist=True)
-    keyset_order = _walk_keyset(client, "artist", 6, 25)
+    keyset_order = _walk_offset(client, "artist", 6, 25)
     assert len(keyset_order) == 25 and len(set(keyset_order)) == 25
     assert keyset_order == sorted(keyset_order)      # tiebreak is filename ASC
 
 
 def test_first_page_has_cursor_and_no_after_is_offset(client, server_mod):
     _seed(server_mod, 5)
+    body = client.get("/api/library", params={"sort": "title", "size": 2}).json()
+    assert body["next_cursor"]                       # keyset sort: cursor offered
     body = client.get("/api/library", params={"sort": "artist", "size": 2}).json()
-    assert body["next_cursor"]                       # cursor offered
+    assert body["next_cursor"] is None               # artist sorts page by OFFSET
     assert [s["filename"] for s in body["songs"]] == ["song00.archive", "song01.archive"]
 
 
@@ -111,7 +116,7 @@ def test_legacy_dir_desc_keysets_correctly(client, server_mod):
     _seed(server_mod, 20)
     offset_order, page = [], 0
     while True:
-        body = client.get("/api/library", params={"sort": "artist", "dir": "desc", "size": 6, "page": page}).json()
+        body = client.get("/api/library", params={"sort": "title", "dir": "desc", "size": 6, "page": page}).json()
         if not body["songs"]:
             break
         offset_order.extend(s["filename"] for s in body["songs"])
@@ -119,7 +124,7 @@ def test_legacy_dir_desc_keysets_correctly(client, server_mod):
     keyset, cursor, guard = [], "", 0
     while len(keyset) < 20 and guard < 25:
         guard += 1
-        params = {"sort": "artist", "dir": "desc", "size": 6}
+        params = {"sort": "title", "dir": "desc", "size": 6}
         if cursor:
             params["after"] = cursor
         body = client.get("/api/library", params=params).json()
@@ -131,7 +136,7 @@ def test_legacy_dir_desc_keysets_correctly(client, server_mod):
     assert len(set(keyset)) == 20
 
 
-@pytest.mark.parametrize("sort", ["artist", "artist-desc", "recent"])
+@pytest.mark.parametrize("sort", ["recent"])
 def test_keyset_handles_null_sort_keys(client, server_mod, sort):
     # NULL artist/mtime (corrupt/legacy rows past put()'s '' defaults) sort
     # first in ASC / last in DESC; keyset must cover them exactly like OFFSET.

tests/test_mb_enrichment.py

@@ -0,0 +1,526 @@
+"""Server-level tests for the P8 MusicBrainz matcher + Match-Review flow.
+
+The HTTP transport is a fake installed over `server._mb_http_get` — the ONE
+seam enrichment uses to reach the network — so nothing here ever opens a
+socket. The offline default is itself under test: without explicitly
+enabling the network flag, a pass must skip matching entirely (pytest can
+never hit MusicBrainz, whatever a test triggers).
+"""
+
+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 / "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:
+            conn.close()
+        sys.modules.pop("server", None)
+
+
+@pytest.fixture()
+def client(server):
+    return TestClient(server.app)
+
+
+class FakeMB:
+    """Canned MusicBrainz: records every call, serves per-path responses."""
+
+    def __init__(self):
+        self.calls = []
+        self.search_response = {"recordings": []}
+        self.recording_lookups = {}   # mbid → recording doc
+        self.isrc_lookups = {}        # isrc → {"recordings": [...]}
+        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 == "recording":
+            return self.search_response
+        if path.startswith("recording/"):
+            return self.recording_lookups.get(path.split("/", 1)[1])
+        if path.startswith("isrc/"):
+            return self.isrc_lookups.get(path.split("/", 1)[1])
+        raise AssertionError(f"unexpected MB path {path!r}")
+
+    @property
+    def search_calls(self):
+        return [c for c in self.calls if c[0] == "recording"]
+
+
+@pytest.fixture()
+def mb(server, monkeypatch):
+    """Install the fake transport AND enable the network flag (the test env
+    disables it by default — see test_offline_default_skips_matching)."""
+    fake = FakeMB()
+    fake._srv = server
+    monkeypatch.setattr(server, "_mb_http_get", fake)
+    monkeypatch.setattr(server, "_enrich_network_enabled", lambda: True)
+    return fake
+
+
+def _put(server, fn, title="Thunderstruck (v2)", artist="ACDC", album="",
+         duration=292, year="1990"):
+    server.meta_db.put(fn, 0, 0, {
+        "title": title, "artist": artist, "album": album, "year": year,
+        "duration": duration, "arrangements": [{"name": "Lead", "index": 0}],
+    })
+
+
+def mb_doc(rid="rec-1", title="Thunderstruck", artist="AC/DC", artist_id="art-1",
+           album="The Razors Edge", date="1990-09-24", length_ms=292000, score=100):
+    return {
+        "id": rid, "score": score, "title": title, "length": length_ms,
+        "isrcs": ["AUAP09000045"],
+        "artist-credit": [{"name": artist, "artist": {
+            "id": artist_id, "name": artist, "sort-name": artist}}],
+        "releases": [{"id": "rel-1", "title": album, "status": "Official",
+                      "date": date, "release-group": {"primary-type": "Album"}}],
+        "tags": [{"name": "hard rock", "count": 7}],
+    }
+
+
+# ── offline safety (the pytest-never-hits-network contract) ──────────────────
+
+def test_offline_default_skips_matching(server, monkeypatch):
+    """Under the test env (FEEDBACK_SKIP_STARTUP_TASKS) a pass stamps hashes
+    but never matches — even with a transport installed."""
+    fake = FakeMB()
+    fake._srv = server
+    monkeypatch.setattr(server, "_mb_http_get", fake)
+    _put(server, "a.sloppak")
+    server._background_enrich()
+    assert fake.calls == []
+    assert server.meta_db.get_enrichment("a.sloppak")["match_state"] == "unscanned"
+
+
+def test_real_transport_refuses_when_offline(server):
+    """_mb_http_get itself raises (before any socket) when the network is
+    disabled — defence in depth under pytest."""
+    with pytest.raises(server.EnrichTransportError):
+        server._mb_http_get("recording", {"query": "x"})
+
+
+def test_transport_error_pauses_pass_without_burning_attempts(server, mb):
+    _put(server, "a.sloppak")
+    _put(server, "b.sloppak", title="Other Song")
+    mb.raise_transport = True
+    server._background_enrich()
+    for fn in ("a.sloppak", "b.sloppak"):
+        row = server.meta_db.get_enrichment(fn)
+        assert row["match_state"] == "unscanned"
+        assert row["attempts"] == 0
+    # Network comes back → the next kick matches both.
+    mb.raise_transport = False
+    mb.search_response = {"recordings": [mb_doc()]}
+    server._background_enrich()
+    assert server.meta_db.get_enrichment("a.sloppak")["match_state"] == "matched"
+
+
+# ── text tiers ────────────────────────────────────────────────────────────────
+
+def test_high_confidence_auto_matches_and_settles(server, mb):
+    _put(server, "a.sloppak")
+    mb.search_response = {"recordings": [mb_doc()]}
+    server._background_enrich()
+    row = server.meta_db.get_enrichment("a.sloppak")
+    assert row["match_state"] == "matched"
+    assert row["match_source"] == "text"
+    assert row["match_score"] >= 0.95
+    assert row["mb_recording_id"] == "rec-1"
+    assert row["canon_artist"] == "AC/DC"
+    assert row["canon_title"] == "Thunderstruck"
+    assert row["canon_album"] == "The Razors Edge"
+    assert row["canon_year"] == "1990"
+    assert row["genres"] == ["hard rock"]
+    # Settled: another pass makes NO further network calls…
+    n = len(mb.calls)
+    server._background_enrich()
+    assert len(mb.calls) == n
+    # …until the identity changes, which re-matches.
+    _put(server, "a.sloppak", title="Back in Black")
+    mb.search_response = {"recordings": [mb_doc(rid="rec-2", title="Back in Black",
+                                                album="Back in Black", date="1980-07-25")]}
+    server._background_enrich()
+    row = server.meta_db.get_enrichment("a.sloppak")
+    assert row["mb_recording_id"] == "rec-2"
+
+
+def test_medium_confidence_goes_to_review_not_canonical(server, mb):
+    # Partial artist agreement → medium confidence.
+    _put(server, "a.sloppak", artist="AC/DC ft Nobody")
+    mb.search_response = {"recordings": [mb_doc()]}
+    server._background_enrich()
+    row = server.meta_db.get_enrichment("a.sloppak")
+    assert row["match_state"] == "review"
+    assert row["match_source"] == "text"
+    # Review before auto-canonicalize: NO canonical values written yet.
+    assert row["canon_artist"] is None
+    assert row["mb_recording_id"] is None
+    assert row["candidates"] and row["candidates"][0]["recording_id"] == "rec-1"
+    # A review row is settled while its identity is unchanged — no re-query.
+    n = len(mb.calls)
+    server._background_enrich()
+    assert len(mb.calls) == n
+
+
+def test_low_confidence_fails_with_backoff(server, mb):
+    _put(server, "a.sloppak")
+    mb.search_response = {"recordings": [mb_doc(rid="rec-x", title="Sunrise",
+                                                artist="Norah Jones")]}
+    server._background_enrich()
+    row = server.meta_db.get_enrichment("a.sloppak")
+    assert row["match_state"] == "failed"
+    assert row["attempts"] == 1
+    assert row["last_attempt_at"] is not None
+    # Immediately after, the backoff hasn't elapsed → no retry, no network.
+    n = len(mb.calls)
+    server._background_enrich()
+    assert len(mb.calls) == n
+    assert server.meta_db.get_enrichment("a.sloppak")["attempts"] == 1
+    # Rewind the clock two hours → eligible again, attempts increments.
+    with server.meta_db._lock:
+        server.meta_db.conn.execute(
+            "UPDATE song_enrichment SET last_attempt_at = last_attempt_at - 7200")
+        server.meta_db.conn.commit()
+    server._background_enrich()
+    assert len(mb.calls) == n + 1
+    assert server.meta_db.get_enrichment("a.sloppak")["attempts"] == 2
+
+
+def test_no_results_fails(server, mb):
+    _put(server, "a.sloppak")
+    mb.search_response = {"recordings": []}
+    server._background_enrich()
+    assert server.meta_db.get_enrichment("a.sloppak")["match_state"] == "failed"
+
+
+# ── the content-hash match cache ──────────────────────────────────────────────
+
+def test_cache_hit_copies_match_without_network(server, mb):
+    _put(server, "a.sloppak")
+    _put(server, "b.sloppak")   # identical identity → same content_hash
+    mb.search_response = {"recordings": [mb_doc()]}
+    server._background_enrich()
+    assert len(mb.search_calls) == 1          # ONE search covered both charts
+    a = server.meta_db.get_enrichment("a.sloppak")
+    b = server.meta_db.get_enrichment("b.sloppak")
+    assert a["match_state"] == b["match_state"] == "matched"
+    assert {a["match_source"], b["match_source"]} == {"text", "cache"}
+    assert a["mb_recording_id"] == b["mb_recording_id"] == "rec-1"
+
+
+# ── exact keys from the manifest (tier 0 / tier 1) ────────────────────────────
+
+def _write_sloppak_manifest(server, name, extra_yaml=""):
+    d = server.DLC_DIR / name
+    d.mkdir(parents=True)
+    (d / "manifest.yaml").write_text(
+        "title: Thunderstruck\nartist: AC/DC\nduration: 292\n"
+        "arrangements: []\nstems: []\n" + extra_yaml,
+        encoding="utf-8")
+
+
+def test_manifest_mbid_tier0(server, mb):
+    mbid = "12345678-abcd-4ef0-9876-0123456789ab"
+    _write_sloppak_manifest(server, "a.sloppak", f"mbid: {mbid}\n")
+    _put(server, "a.sloppak")
+    mb.recording_lookups[mbid] = mb_doc(rid=mbid)
+    server._background_enrich()
+    row = server.meta_db.get_enrichment("a.sloppak")
+    assert row["match_state"] == "matched"
+    assert row["match_source"] == "mbid"
+    assert row["match_score"] == 1.0
+    assert row["mb_recording_id"] == mbid
+    assert mb.search_calls == []              # trusted key — no text search
+
+
+def test_manifest_isrc_tier1(server, mb):
+    _write_sloppak_manifest(server, "a.sloppak", "isrc: AUAP09000045\n")
+    _put(server, "a.sloppak")
+    mb.isrc_lookups["AUAP09000045"] = {"recordings": [mb_doc()]}
+    server._background_enrich()
+    row = server.meta_db.get_enrichment("a.sloppak")
+    assert row["match_state"] == "matched"
+    assert row["match_source"] == "isrc"
+    assert mb.search_calls == []
+
+
+def test_manifest_isrc_display_hyphens_stripped(server, mb):
+    """Spec 1.14.0: the hyphenated display form (AU-AP0-90-00045) is
+    presentation only — the reader strips separators, so a hand-authored
+    manifest still hits the exact tier with the bare 12-char code."""
+    _write_sloppak_manifest(server, "a.sloppak", "isrc: AU-AP0-90-00045\n")
+    _put(server, "a.sloppak")
+    mb.isrc_lookups["AUAP09000045"] = {"recordings": [mb_doc()]}
+    server._background_enrich()
+    row = server.meta_db.get_enrichment("a.sloppak")
+    assert row["match_state"] == "matched"
+    assert row["match_source"] == "isrc"
+    assert mb.search_calls == []
+
+
+def test_bad_manifest_mbid_falls_through_to_text(server, mb):
+    mbid = "12345678-abcd-4ef0-9876-0123456789ab"
+    _write_sloppak_manifest(server, "a.sloppak", f"mbid: {mbid}\n")
+    _put(server, "a.sloppak")
+    mb.recording_lookups.clear()              # lookup 404s (typo'd manifest)
+    mb.search_response = {"recordings": [mb_doc()]}
+    server._background_enrich()
+    row = server.meta_db.get_enrichment("a.sloppak")
+    assert row["match_state"] == "matched"
+    assert row["match_source"] == "text"
+
+
+# ── manual is sacred ──────────────────────────────────────────────────────────
+
+def test_manual_never_overwritten_by_matcher(server, mb):
+    _put(server, "a.sloppak")
+    server.meta_db.set_enrichment_manual(
+        "a.sloppak", {"recording_id": "user-pick", "title": "Thunderstruck",
+                      "artist": "AC/DC"}, source="search")
+    mb.search_response = {"recordings": [mb_doc(rid="machine-pick")]}
+    server._background_enrich()
+    row = server.meta_db.get_enrichment("a.sloppak")
+    assert row["match_state"] == "manual"
+    assert row["mb_recording_id"] == "user-pick"
+    # The writer refuses machine writes onto manual outright.
+    ok = server.meta_db.apply_enrichment_match(
+        "a.sloppak", row["content_hash"], "matched", source="text", score=1.0,
+        cand={"recording_id": "machine-pick", "title": "X"})
+    assert ok is False
+
+
+# ── review routes ─────────────────────────────────────────────────────────────
+
+def _seed_review(server, mb, fn="a.sloppak", title="Thunderstruck (v2)"):
+    # Distinct raw titles give distinct content hashes (else the match cache
+    # legitimately copies an earlier row instead of running the text tiers).
+    _put(server, fn, title=title, artist="AC/DC ft Nobody")
+    mb.search_response = {"recordings": [mb_doc()]}
+    server._background_enrich()
+    assert server.meta_db.get_enrichment(fn)["match_state"] == "review"
+
+
+def test_review_queue_route(server, mb, client):
+    _seed_review(server, mb)
+    body = client.get("/api/enrichment/review").json()
+    assert body["total_review"] == 1
+    assert body["songs"][0]["filename"] == "a.sloppak"
+    assert body["songs"][0]["candidates"][0]["recording_id"] == "rec-1"
+
+
+def test_review_accept_route(server, mb, client):
+    _seed_review(server, mb)
+    r = client.post("/api/enrichment/review/a.sloppak/accept",
+                    json={"recording_id": "rec-1"})
+    assert r.status_code == 200
+    row = server.meta_db.get_enrichment("a.sloppak")
+    assert row["match_state"] == "manual"
+    assert row["match_source"] == "review"
+    assert row["canon_artist"] == "AC/DC"
+    assert client.get("/api/enrichment/review").json()["total_review"] == 0
+    # Accepting a candidate that isn't in the stored list → 404.
+    _seed_review(server, mb, fn="b.sloppak", title="Thunderstruck (Live)")
+    r = client.post("/api/enrichment/review/b.sloppak/accept",
+                    json={"recording_id": "nope"})
+    assert r.status_code == 404
+
+
+def test_review_reject_route_never_retries(server, mb, client):
+    _seed_review(server, mb)
+    r = client.post("/api/enrichment/review/a.sloppak/reject")
+    assert r.status_code == 200
+    row = server.meta_db.get_enrichment("a.sloppak")
+    assert row["match_state"] == "failed"
+    assert row["match_source"] == "rejected"
+    # Rejected rows are excluded from the retry backoff forever…
+    n = len(mb.calls)
+    server._background_enrich()
+    assert len(mb.calls) == n
+    # …but an identity edit re-queues (the user fixed the metadata).
+    _put(server, "a.sloppak", artist="AC/DC")
+    server._background_enrich()
+    assert server.meta_db.get_enrichment("a.sloppak")["match_state"] == "matched"
+    # Rejecting a manual row is refused.
+    r = client.post("/api/enrichment/review/a.sloppak/reject")
+    assert r.status_code == 200               # matched → rejectable
+    client.post("/api/enrichment/review/a.sloppak/pick",
+                json={"candidate": {"recording_id": "rec-9", "title": "T"}})
+    r = client.post("/api/enrichment/review/a.sloppak/reject")
+    assert r.status_code == 404
+
+
+def test_pick_route_fix_match(server, mb, client):
+    _put(server, "a.sloppak")
+    r = client.post("/api/enrichment/review/a.sloppak/pick", json={"candidate": {
+        "recording_id": "rec-77", "title": "Thunderstruck", "artist": "AC/DC",
+        "album": "The Razors Edge", "year": "1990", "genres": ["hard rock"],
+        "junk_key": "dropped"}})
+    assert r.status_code == 200
+    row = server.meta_db.get_enrichment("a.sloppak")
+    assert row["match_state"] == "manual"
+    assert row["match_source"] == "search"
+    assert row["mb_recording_id"] == "rec-77"
+    # Malformed candidate → 400; unknown song → 404.
+    assert client.post("/api/enrichment/review/a.sloppak/pick",
+                       json={"candidate": {"title": "no id"}}).status_code == 400
+    assert client.post("/api/enrichment/review/ghost.sloppak/pick",
+                       json={"candidate": {"recording_id": "x", "title": "t"}}
+                       ).status_code == 404
+
+
+def test_search_proxy(server, mb, client, monkeypatch):
+    _put(server, "a.sloppak")
+    mb.search_response = {"recordings": [mb_doc()]}
+    assert client.get("/api/enrichment/search").status_code == 400
+    body = client.get("/api/enrichment/search",
+                      params={"title": "Thunderstruck", "artist": "AC/DC",
+                              "filename": "a.sloppak"}).json()
+    assert body["candidates"][0]["recording_id"] == "rec-1"
+    assert body["candidates"][0]["score"] > 0.9
+    # Transport failure surfaces as 503, not a 500.
+    def _down(path, params):
+        raise server.EnrichTransportError("down")
+    monkeypatch.setattr(server, "_mb_http_get", _down)
+    r = client.get("/api/enrichment/search", params={"title": "x"})
+    assert r.status_code == 503
+
+
+# ── the match facet on /api/library + /api/library/stats ─────────────────────
+
+def test_match_facet_filters_grid_and_stats(server, mb, client, monkeypatch):
+    _put(server, "auto.sloppak")                                  # → matched
+    _put(server, "rev.sloppak", title="Revsong", artist="AC/DC ft Nobody")   # → review
+    _put(server, "fail.sloppak", title="Failsong", artist="Zzz")  # → failed
+    _put(server, "pend.sloppak", title="Pendsong", artist="Yyy")  # stays unscanned
+
+    def _routed(path, params):
+        q = params.get("query", "")
+        if "thunderstruck" in q:
+            return {"recordings": [mb_doc()]}
+        if "revsong" in q:
+            return {"recordings": [mb_doc(rid="rec-r", title="Revsong")]}
+        return {"recordings": []}
+    monkeypatch.setattr(server, "_mb_http_get", _routed)
+    server._background_enrich()
+    # Pendsong got failed by the pass (no results); reset it to unscanned to
+    # represent the not-yet-scanned band.
+    with server.meta_db._lock:
+        server.meta_db.conn.execute(
+            "UPDATE song_enrichment SET match_state='unscanned', attempts=0, "
+            "last_attempt_at=NULL WHERE filename='pend.sloppak'")
+        server.meta_db.conn.commit()
+
+    def names(match):
+        return sorted(s["filename"] for s in client.get(
+            "/api/library", params={"match": match, "size": 50}).json()["songs"])
+
+    assert names("review") == ["rev.sloppak"]
+    assert names("matched") == ["auto.sloppak"]
+    assert names("unmatched") == ["fail.sloppak"]
+    assert names("pending") == ["pend.sloppak"]
+    assert names("review,matched") == ["auto.sloppak", "rev.sloppak"]
+    # Stats agree with the grid (the rail's lockstep contract).
+    total = client.get("/api/library/stats",
+                       params={"match": "review"}).json()["total_songs"]
+    assert total == 1
+    # Unknown values are ignored → unfiltered.
+    assert len(names("bogus")) == 4
+
+
+def test_status_counts_by_state(server, mb, client):
+    _seed_review(server, mb)
+    states = client.get("/api/enrichment/status").json()["states"]
+    assert states.get("review") == 1
+
+
+# ── settings: enable toggle + auto-apply confidence ───────────────────────────
+
+def test_auto_threshold_setting_moves_the_auto_review_boundary(server, mb, client):
+    # artist exact (1.0) + title 4/5 token overlap (0.8) and NO year/duration
+    # corroboration → combined exactly 0.90.
+    mb.search_response = {"recordings": [
+        mb_doc(title="Highway Hell", artist="AC/DC", date="", length_ms=None)]}
+    client.post("/api/settings", json={"enrich_auto_threshold": 0.95})
+    _put(server, "a.sloppak", title="Highway to Hell", artist="AC/DC",
+         year="", duration=0)
+    server._background_enrich()
+    assert server.meta_db.get_enrichment("a.sloppak")["match_state"] == "review"
+    # Lower the bar to the default 0.90 → an identity edit re-queues, and the
+    # same 0.90-scored candidate now auto-applies.
+    client.post("/api/settings", json={"enrich_auto_threshold": 0.9})
+    _put(server, "a.sloppak", title="Highway to Hell", artist="AC/DC",
+         year="", duration=0, album="Different Album")
+    server._background_enrich()
+    row = server.meta_db.get_enrichment("a.sloppak")
+    assert row["match_state"] == "matched"
+    assert abs(row["match_score"] - 0.9) < 1e-6
+
+
+def test_enrich_enabled_setting_gates_background_matching(server, mb, client):
+    client.post("/api/settings", json={"enrich_enabled": False})
+    _put(server, "a.sloppak")
+    mb.search_response = {"recordings": [mb_doc()]}
+    server._background_enrich()
+    assert mb.calls == []
+    assert server.meta_db.get_enrichment("a.sloppak")["match_state"] == "unscanned"
+    # Manual search/fix stays available while the background matcher is off.
+    r = client.get("/api/enrichment/search", params={"title": "Thunderstruck"})
+    assert r.status_code == 200
+    # Re-enable → the next pass matches.
+    client.post("/api/settings", json={"enrich_enabled": True})
+    server._background_enrich()
+    assert server.meta_db.get_enrichment("a.sloppak")["match_state"] == "matched"
+
+
+def test_settings_validation(server, client):
+    assert "error" in client.post(
+        "/api/settings", json={"enrich_enabled": "yes"}).json()
+    assert "error" in client.post(
+        "/api/settings", json={"enrich_auto_threshold": "high"}).json()
+    assert "error" in client.post(
+        "/api/settings", json={"enrich_auto_threshold": 2.5}).json()
+    ok = client.post("/api/settings", json={"enrich_auto_threshold": 1.01}).json()
+    assert "error" not in ok
+    assert client.get("/api/settings").json()["enrich_auto_threshold"] == 1.01
+
+
+def test_kick_route(server, mb, client):
+    import time as _t
+    body = client.post("/api/enrichment/kick").json()
+    assert "started" in body
+    # Let the kicked pass settle so its daemon thread can't bleed into the
+    # fixture teardown (the DB connection closes there).
+    for _ in range(200):
+        if not client.get("/api/enrichment/status").json()["running"]:
+            break
+        _t.sleep(0.02)
+
+
+def test_review_queue_orders_missing_data_first(server, mb, client):
+    # Complete chart first alphabetically, incomplete second — the queue must
+    # surface the incomplete (missing album + year) one first anyway.
+    _seed_review(server, mb, fn="aa.sloppak", title="Thunderstruck (v2)")
+    _put(server, "zz.sloppak", title="Thunderstruck (Live)",
+         artist="AC/DC ft Nobody", album="", year="")
+    server._background_enrich()
+    assert server.meta_db.get_enrichment("zz.sloppak")["match_state"] == "review"
+    songs = client.get("/api/enrichment/review").json()["songs"]
+    assert [s["filename"] for s in songs] == ["zz.sloppak", "aa.sloppak"]

tests/test_mb_match.py

@@ -0,0 +1,227 @@
+"""Unit tests for lib/mb_match.py — the pure text-matching engine (P8).
+
+No network, no database, no server import: denoise/tokenize, similarity,
+scoring + tier classification, Lucene query building, and MusicBrainz
+response parsing are all exercised as plain functions.
+"""
+
+import mb_match as m
+
+
+# ── denoise / tokenize ────────────────────────────────────────────────────────
+
+def test_denoise_lowercases_and_strips_punct_and_diacritics():
+    assert m.denoise("Motörhead") == "motorhead"
+    assert m.denoise("Beyoncé!!") == "beyonce"
+    assert m.denoise("Guns N' Roses") == "guns n roses"
+    assert m.denoise("  Weird   spacing ") == "weird spacing"
+
+
+def test_denoise_strips_noise_parentheticals():
+    # The design's explicit list: author suffixes + (440Hz)/(Live)/(No Lead)/(v2).
+    assert m.denoise("Thunderstruck (440Hz)") == "thunderstruck"
+    assert m.denoise("Thunderstruck (Live)") == "thunderstruck"
+    assert m.denoise("Thunderstruck (No Lead)") == "thunderstruck"
+    assert m.denoise("Thunderstruck (v2)") == "thunderstruck"
+    assert m.denoise("Thunderstruck [Remastered 2012]") == "thunderstruck"
+    assert m.denoise("One (Live at Wembley)") == "one"
+
+
+def test_denoise_strips_author_credits():
+    assert m.denoise("Back in Black (by SomeCharter)") == "back in black"
+    assert m.denoise("Back in Black (charted by X99)") == "back in black"
+    assert m.denoise("Back in Black - by SomeCharter") == "back in black"
+
+
+def test_denoise_keeps_meaningful_parentheticals():
+    # A parenthetical with no noise term survives (both sides get the same
+    # treatment, so symmetric content still matches).
+    assert m.denoise("Doin' It (All for My Baby)") == "doin it all for my baby"
+
+
+def test_denoise_leading_the_is_artist_only():
+    assert m.denoise("The Beatles", strip_leading_the=True) == "beatles"
+    # Titles keep their "The" — never strip it there.
+    assert m.denoise("The Trooper") == "the trooper"
+
+
+def test_ampersand_folds_to_and():
+    assert m.similarity("Angus & Julia Stone", "Angus and Julia Stone", artist=True) == 1.0
+
+
+# ── similarity ────────────────────────────────────────────────────────────────
+
+def test_similarity_exact_and_empty():
+    assert m.similarity("Back in Black", "Back In Black!") == 1.0
+    assert m.similarity("", "Anything") == 0.0
+    assert m.similarity(None, None) == 0.0
+
+
+def test_similarity_folds_spelling_drift_via_compaction():
+    # The headline case: ACDC / AC DC / AC/DC all name the same artist.
+    assert m.similarity("ACDC", "AC/DC", artist=True) == 1.0
+    assert m.similarity("AC DC", "ACDC", artist=True) == 1.0
+    assert m.similarity("Greenday", "Green Day", artist=True) == 1.0
+
+
+def test_similarity_partial_overlap():
+    s = m.similarity("Highway to Hell", "Highway Hell")
+    assert 0.7 < s < 1.0
+    assert m.similarity("Back in Black", "Paint It Black") < 0.5
+
+
+# ── scoring + tiers ───────────────────────────────────────────────────────────
+
+SONG = {"artist": "ACDC", "title": "Thunderstruck (v2)", "album": "The Razors Edge",
+        "year": "1990", "duration": 292}
+
+
+def test_score_exact_match_is_high():
+    cand = {"artist": "AC/DC", "title": "Thunderstruck", "year": "1990", "duration": 292}
+    s = m.score_candidate(SONG, cand)
+    assert s == 1.0
+    assert m.classify(SONG, cand, s) == "auto"
+
+
+def test_score_cover_never_auto():
+    # Perfect title, wrong artist (a cover) — must not auto-match.
+    cand = {"artist": "Some Cover Band", "title": "Thunderstruck"}
+    s = m.score_candidate(SONG, cand)
+    assert m.classify(SONG, cand, s) != "auto"
+
+
+def test_missing_artist_caps_at_review():
+    song = {"artist": "", "title": "Thunderstruck", "duration": 292}
+    cand = {"artist": "AC/DC", "title": "Thunderstruck", "duration": 292}
+    s = m.score_candidate(song, cand)
+    # artist half scores 0 → combined ≤ 0.55 + bonuses → review at best.
+    assert m.classify(song, cand, s) != "auto"
+
+
+def test_year_and_duration_corroborate():
+    # Fuzzy title so the base sits below the 1.0 cap and bonuses are visible.
+    base = {"artist": "AC/DC", "title": "Thunderstruck Thunder"}
+    plain = m.score_candidate(SONG, base)
+    with_year = m.score_candidate(SONG, dict(base, year="1990"))
+    with_dur = m.score_candidate(SONG, dict(base, duration=290))
+    assert with_year > plain
+    assert with_dur > plain
+
+
+def test_fuzzy_title_with_corroboration_lands_review_or_auto():
+    cand = {"artist": "AC/DC", "title": "Thunderstruck Thunder"}
+    s = m.score_candidate(SONG, cand)
+    assert m.classify(SONG, cand, s) in ("review", "auto")
+
+
+def test_unrelated_is_none():
+    cand = {"artist": "Norah Jones", "title": "Sunrise"}
+    s = m.score_candidate(SONG, cand)
+    assert m.classify(SONG, cand, s) == "none"
+
+
+def test_classify_auto_min_override():
+    # The host's "auto-apply confidence" setting: a perfect match autos at
+    # any real threshold, and "Always review" (>1.0) sends even it to review.
+    cand = {"artist": "AC/DC", "title": "Thunderstruck", "year": "1990", "duration": 292}
+    s = m.score_candidate(SONG, cand)
+    assert s == 1.0
+    assert m.classify(SONG, cand, s, auto_min=0.9) == "auto"
+    assert m.classify(SONG, cand, s, auto_min=1.01) == "review"
+    # The per-field floors are independent of the threshold: a wrong-artist
+    # cover stays non-auto even at a permissive auto_min.
+    cover = {"artist": "Some Cover Band", "title": "Thunderstruck"}
+    cs = m.score_candidate(SONG, cover)
+    assert m.classify(SONG, cover, cs, auto_min=0.5) != "auto"
+
+
+def test_rank_candidates_orders_by_our_score():
+    cands = [
+        {"recording_id": "b", "artist": "Someone Else", "title": "Thunderstruck", "mb_score": 100},
+        {"recording_id": "a", "artist": "AC/DC", "title": "Thunderstruck", "mb_score": 90},
+    ]
+    ranked = m.rank_candidates(SONG, cands)
+    assert [c["recording_id"] for c in ranked] == ["a", "b"]
+    assert all("score" in c for c in ranked)
+
+
+# ── query building ────────────────────────────────────────────────────────────
+
+def test_build_recording_query_denoises_and_quotes():
+    q = m.build_recording_query("ACDC", 'Thunderstruck (v2)')
+    assert q == 'recording:"thunderstruck" AND artist:"acdc"'
+
+
+def test_build_recording_query_escapes_and_handles_missing_artist():
+    q = m.build_recording_query("", 'Say "Hello"')
+    # Quotes are punct-stripped by denoise, so nothing to escape here — but
+    # the artist clause must be absent entirely.
+    assert q.startswith('recording:"')
+    assert "artist:" not in q
+
+
+# ── MusicBrainz response parsing ──────────────────────────────────────────────
+
+MB_DOC = {
+    "id": "rec-123",
+    "score": 98,
+    "title": "Thunderstruck",
+    "length": 292773,
+    "isrcs": ["AUAP09000045"],
+    "artist-credit": [
+        {"name": "AC/DC", "joinphrase": "",
+         "artist": {"id": "art-1", "name": "AC/DC", "sort-name": "AC/DC"}},
+    ],
+    "releases": [
+        {"id": "rel-compilation", "title": "Greatest Hits", "status": "Official",
+         "date": "2005-01-01", "release-group": {"primary-type": "Compilation"}},
+        {"id": "rel-album", "title": "The Razors Edge", "status": "Official",
+         "date": "1990-09-24", "release-group": {"primary-type": "Album"}},
+        {"id": "rel-boot", "title": "Bootleg", "status": "Bootleg",
+         "date": "1989-01-01", "release-group": {"primary-type": "Album"}},
+    ],
+    "tags": [{"name": "hard rock", "count": 10}, {"name": "rock", "count": 4}],
+}
+
+
+def test_parse_recording_doc_normalizes():
+    c = m.parse_recording_doc(MB_DOC)
+    assert c["recording_id"] == "rec-123"
+    assert c["title"] == "Thunderstruck"
+    assert c["artist"] == "AC/DC"
+    assert c["artist_id"] == "art-1"
+    # Official Album beats the compilation and the bootleg.
+    assert c["album"] == "The Razors Edge"
+    assert c["release_id"] == "rel-album"
+    assert c["year"] == "1990"
+    assert c["duration"] == 293
+    assert c["isrc"] == "AUAP09000045"
+    assert c["genres"] == ["hard rock", "rock"]
+    assert c["mb_score"] == 98
+
+
+def test_parse_recording_doc_joined_artist_credit():
+    doc = dict(MB_DOC)
+    doc["artist-credit"] = [
+        {"name": "Queen", "joinphrase": " & ",
+         "artist": {"id": "q", "name": "Queen", "sort-name": "Queen"}},
+        {"name": "David Bowie",
+         "artist": {"id": "b", "name": "David Bowie", "sort-name": "Bowie, David"}},
+    ]
+    c = m.parse_recording_doc(doc)
+    assert c["artist"] == "Queen & David Bowie"
+    assert c["artist_id"] == "q"
+
+
+def test_parse_recording_doc_rejects_malformed():
+    assert m.parse_recording_doc({}) is None
+    assert m.parse_recording_doc({"id": "x"}) is None
+    assert m.parse_recording_doc(None) is None
+
+
+def test_parse_search_response():
+    body = {"recordings": [MB_DOC, {"bogus": True}]}
+    cands = m.parse_search_response(body)
+    assert len(cands) == 1
+    assert m.parse_search_response({}) == []
+    assert m.parse_search_response(None) == []

tests/test_notation_lift.py

@@ -85,6 +85,26 @@ def test_split_hands_narrow_group_goes_by_mean_vs_middle_c():
     assert "rh" in high and "lh" not in high  # mean ~65.5 ≥ 60
 
 
+def test_split_hands_straddling_middle_c_splits_at_middle_c():
+    # [G2, E3, C4] = [43, 52, 60]: largest gap is G2→E3 (9) but the musically
+    # correct split is E3|C4. Middle-C boundary → lh=[G2,E3], rh=[C4].
+    notes = [{"t": 0.0, "midi": m, "sus": 0} for m in (43, 52, 60)]
+    hands = nl.split_hands(notes)
+    assert sorted(n["midi"] for n in hands["lh"]) == [43, 52]
+    assert [n["midi"] for n in hands["rh"]] == [60]
+
+
+def test_split_hands_middle_c_split_falls_back_when_it_makes_unplayable_hand():
+    # Em7-shape RH voicing over a low bass note: [E2, B3, D4, G4] = [40,59,62,67].
+    # A hard middle-C split would put E2+B3 in the LH — a 19-semitone span that
+    # re-violates the 12-semitone threshold. Must fall back to the largest gap,
+    # isolating E2 in the LH and keeping the treble voicing in the RH.
+    notes = [{"t": 0.0, "midi": m, "sus": 0} for m in (40, 59, 62, 67)]
+    hands = nl.split_hands(notes)
+    assert [n["midi"] for n in hands["lh"]] == [40]
+    assert sorted(n["midi"] for n in hands["rh"]) == [59, 62, 67]
+
+
 # ── Timing ───────────────────────────────────────────────────────────────────
 
 def test_downbeat_times_filters_non_downbeats_and_sorts():

tests/test_pack_overwrite.py

@@ -0,0 +1,361 @@
+"""Tests for the R4b pack-field overwrite — the §7-AMENDMENT shape made
+executable: per-field confirmation with values only from a match the user
+EXPLICITLY confirmed (`manual` — an automatic match may gap-fill but never
+replace), a default-OFF Settings gate (allow_pack_overwrite), identity keys
+(mbid/isrc) never overwritable, receipts in write_log (old/new/source/score,
+pruned at 5000 rows), and .bak = the pristine author original with a working
+Revert that preserves the backup.
+
+Reuses the gap-fill fixtures/helpers (tests/test_gap_fill.py); no network
+anywhere — matches are seeded straight into the enrichment cache.
+"""
+
+import importlib
+import sys
+import zipfile
+
+import yaml
+from fastapi.testclient import TestClient
+
+from tests.test_gap_fill import (  # noqa: F401  (server/client fixtures)
+    BASE_MANIFEST,
+    client,
+    make_dir_sloppak,
+    make_zip_sloppak,
+    seed_match,
+    server,
+)
+
+# Author-set values that all DIFFER from the seeded match (artist/album/year/
+# genres), plus a title equal to the match (equal values are never offered).
+DIFF_MANIFEST = ("# my hand-made pack\n"
+                 "title: Thunderstruck\n"
+                 "artist: ACDC   # typo the match fixes\n"
+                 "album: Razors Edge\n"
+                 "year: 1991\n"
+                 "genres:\n"
+                 "- Rock\n"
+                 "duration: 292\n"
+                 "arrangements: []\n"
+                 "stems: []\n")
+
+
+def enable_overwrite(client):
+    r = client.post("/api/settings", json={"allow_pack_overwrite": True})
+    assert r.status_code == 200
+
+
+# ── differs (preview) ─────────────────────────────────────────────────────────
+
+def test_differs_only_for_manual_rows(server, client):
+    """The librarian rule: an automatic match may gap-fill absent keys but is
+    not authority to replace author bytes — differs is empty until the user
+    pins the match."""
+    make_dir_sloppak(server, "a.sloppak", DIFF_MANIFEST)
+    seed_match(server, "a.sloppak", state="matched")
+    d = client.get("/api/song/a.sloppak/gap-fill").json()
+    assert d["differs"] == []
+    # The same row, user-pinned → the differences surface.
+    seed_match(server, "a.sloppak", state="manual")
+    d = client.get("/api/song/a.sloppak/gap-fill").json()
+    got = {x["key"]: x for x in d["differs"]}
+    assert set(got) == {"artist", "album", "year", "genres"}
+    assert got["artist"]["current"] == "ACDC" and got["artist"]["proposed"] == "AC/DC"
+    assert got["album"]["current"] == "Razors Edge"
+    assert got["album"]["proposed"] == "The Razors Edge"
+    assert got["year"]["current"] == "1991" and got["year"]["proposed"] == 1990
+    assert got["genres"]["current"] == ["Rock"]
+    assert got["genres"]["proposed"] == ["hard rock", "rock"]
+
+
+def test_differs_excludes_identity_keys_and_equal_values(server, client):
+    """mbid/isrc present in the file AND different from the match are still
+    never offered (identity changes only via explicit re-match); a value equal
+    to the match isn't a difference; an ABSENT key is a gap (missing), not a
+    differ."""
+    make_dir_sloppak(server, "a.sloppak", BASE_MANIFEST +
+                     "mbid: 00000000-0000-4000-8000-000000000000\n"
+                     "isrc: USZZZ0000001\n")
+    seed_match(server, "a.sloppak", state="manual")
+    d = client.get("/api/song/a.sloppak/gap-fill").json()
+    assert d["differs"] == []           # title/artist equal; mbid/isrc barred
+    assert {m["key"] for m in d["missing"]} == {"album", "year", "genres"}
+
+
+def test_preview_reports_gate_state_and_backup(server, client):
+    make_dir_sloppak(server, "a.sloppak", DIFF_MANIFEST)
+    seed_match(server, "a.sloppak", state="manual")
+    d = client.get("/api/song/a.sloppak/gap-fill").json()
+    assert d["overwrite_allowed"] is False      # default OFF
+    assert d["has_backup"] is False             # nothing written yet
+    enable_overwrite(client)
+    assert client.get("/api/song/a.sloppak/gap-fill").json()["overwrite_allowed"] is True
+
+
+# ── refusals ──────────────────────────────────────────────────────────────────
+
+def test_overwrite_refused_when_setting_off(server, client):
+    """The gate refuses the WHOLE request before anything is written."""
+    d = make_dir_sloppak(server, "a.sloppak", DIFF_MANIFEST)
+    seed_match(server, "a.sloppak", state="manual")
+    before = (d / "manifest.yaml").read_text(encoding="utf-8")
+    r = client.post("/api/song/a.sloppak/gap-fill", json={"overwrite_keys": ["artist"]})
+    assert r.status_code == 409
+    assert (d / "manifest.yaml").read_text(encoding="utf-8") == before
+    assert not (d / "manifest.yaml.bak").exists()
+
+
+def test_overwrite_refused_when_not_manual(server, client):
+    d = make_dir_sloppak(server, "a.sloppak", DIFF_MANIFEST)
+    seed_match(server, "a.sloppak", state="matched")
+    enable_overwrite(client)
+    before = (d / "manifest.yaml").read_text(encoding="utf-8")
+    r = client.post("/api/song/a.sloppak/gap-fill", json={"overwrite_keys": ["artist"]})
+    assert r.status_code == 409
+    assert r.json()["skipped"] == ["artist"]
+    assert (d / "manifest.yaml").read_text(encoding="utf-8") == before
+
+
+def test_overwrite_validates_keys(server, client):
+    make_dir_sloppak(server, "a.sloppak", DIFF_MANIFEST)
+    seed_match(server, "a.sloppak", state="manual")
+    enable_overwrite(client)
+    # Identity keys and unknown keys are turned away wholesale (400).
+    for bad in (["mbid"], ["isrc"], ["nope"]):
+        r = client.post("/api/song/a.sloppak/gap-fill", json={"overwrite_keys": bad})
+        assert r.status_code == 400
+    # Both lists empty is still a 400.
+    assert client.post("/api/song/a.sloppak/gap-fill",
+                       json={"keys": [], "overwrite_keys": []}).status_code == 400
+
+
+def test_overwrite_equal_value_is_skipped(server, client):
+    """A requested key whose value already equals the match is not in differs
+    → skipped, and with nothing else to write the request 409s untouched."""
+    d = make_dir_sloppak(server, "a.sloppak", DIFF_MANIFEST)
+    seed_match(server, "a.sloppak", state="manual")
+    enable_overwrite(client)
+    r = client.post("/api/song/a.sloppak/gap-fill", json={"overwrite_keys": ["title"]})
+    assert r.status_code == 409
+    assert r.json()["skipped"] == ["title"]
+    assert (d / "manifest.yaml").read_text(encoding="utf-8") == DIFF_MANIFEST
+
+
+# ── happy path ────────────────────────────────────────────────────────────────
+
+def test_overwrite_dir_form_replaces_and_keeps_pristine_bak(server, client):
+    d = make_dir_sloppak(server, "a.sloppak", DIFF_MANIFEST)
+    seed_match(server, "a.sloppak", state="manual")
+    enable_overwrite(client)
+    r = client.post("/api/song/a.sloppak/gap-fill",
+                    json={"overwrite_keys": ["artist", "genres"]})
+    assert r.status_code == 200
+    body = r.json()
+    assert body["overwritten"] == {
+        "artist": {"old": "ACDC", "new": "AC/DC"},
+        "genres": {"old": ["Rock"], "new": ["hard rock", "rock"]},
+    }
+    assert body["written"] == {}
+    manifest = yaml.safe_load((d / "manifest.yaml").read_text(encoding="utf-8"))
+    assert manifest["artist"] == "AC/DC"
+    assert manifest["genres"] == ["hard rock", "rock"]
+    assert manifest["album"] == "Razors Edge"       # unrequested keys untouched
+    assert manifest["year"] == 1991
+    # The backup is the author's pristine original…
+    assert (d / "manifest.yaml.bak").read_text(encoding="utf-8") == DIFF_MANIFEST
+    # …and a SECOND write never clobbers it.
+    r = client.post("/api/song/a.sloppak/gap-fill", json={"overwrite_keys": ["album"]})
+    assert r.status_code == 200
+    assert (d / "manifest.yaml.bak").read_text(encoding="utf-8") == DIFF_MANIFEST
+    manifest = yaml.safe_load((d / "manifest.yaml").read_text(encoding="utf-8"))
+    assert manifest["album"] == "The Razors Edge"
+    assert manifest["artist"] == "AC/DC"            # the first write survives
+    # DB sync: the songs row reflects the replaced values.
+    row = client.get("/api/song/a.sloppak").json()
+    assert row["artist"] == "AC/DC"
+    assert row["album"] == "The Razors Edge"
+
+
+def test_gap_fill_and_overwrite_in_one_request(server, client):
+    """`keys` keeps working unchanged alongside `overwrite_keys`: absent keys
+    append (author bytes preserved into the one pristine backup), the differing
+    key is replaced."""
+    d = make_dir_sloppak(server, "a.sloppak", BASE_MANIFEST + "year: 1991\n")
+    seed_match(server, "a.sloppak", state="manual")
+    enable_overwrite(client)
+    r = client.post("/api/song/a.sloppak/gap-fill",
+                    json={"keys": ["album", "mbid"], "overwrite_keys": ["year"]})
+    assert r.status_code == 200
+    body = r.json()
+    assert body["written"] == {"album": "The Razors Edge",
+                               "mbid": "12345678-abcd-4ef0-9876-0123456789ab"}
+    assert body["overwritten"] == {"year": {"old": "1991", "new": 1990}}
+    manifest = yaml.safe_load((d / "manifest.yaml").read_text(encoding="utf-8"))
+    assert manifest["album"] == "The Razors Edge"
+    assert manifest["mbid"] == "12345678-abcd-4ef0-9876-0123456789ab"
+    assert manifest["year"] == 1990
+    # One request, one pristine backup: the pre-request original bytes.
+    assert ((d / "manifest.yaml.bak").read_text(encoding="utf-8")
+            == BASE_MANIFEST + "year: 1991\n")
+
+
+def test_zip_form_overwrite(server, client):
+    p = make_zip_sloppak(server, "a.sloppak", DIFF_MANIFEST)
+    seed_match(server, "a.sloppak", state="manual")
+    enable_overwrite(client)
+    r = client.post("/api/song/a.sloppak/gap-fill", json={"overwrite_keys": ["artist"]})
+    assert r.status_code == 200
+    with zipfile.ZipFile(p) as z:
+        manifest = yaml.safe_load(z.read("manifest.yaml"))
+        assert manifest["artist"] == "AC/DC"
+        assert z.read("stems/full.ogg") == b"OggS-fake"     # pack intact
+    bak = p.with_name(p.name + ".bak")
+    with zipfile.ZipFile(bak) as z:
+        assert z.read("manifest.yaml").decode("utf-8") == DIFF_MANIFEST
+
+
+# ── write_log (provenance receipts) ───────────────────────────────────────────
+
+def test_write_log_records_old_and_new(server, client):
+    make_dir_sloppak(server, "a.sloppak", DIFF_MANIFEST)
+    seed_match(server, "a.sloppak", state="manual")
+    enable_overwrite(client)
+    r = client.post("/api/song/a.sloppak/gap-fill",
+                    json={"overwrite_keys": ["artist", "year"]})
+    assert r.status_code == 200
+    rows = client.get("/api/song/a.sloppak/write-log").json()["rows"]
+    by_key = {x["key"]: x for x in rows}
+    assert by_key["artist"]["old_value"] == "ACDC"
+    assert by_key["artist"]["new_value"] == "AC/DC"
+    assert by_key["year"]["old_value"] == "1991"
+    assert by_key["year"]["new_value"] == "1990"
+    for x in rows:
+        assert x["source"] == "text" and x["score"] == 1.0 and x["ts"]
+
+
+def test_write_log_records_gap_fills_too(server, client):
+    make_dir_sloppak(server, "a.sloppak")
+    seed_match(server, "a.sloppak")
+    r = client.post("/api/song/a.sloppak/gap-fill", json={"keys": ["album", "genres"]})
+    assert r.status_code == 200
+    rows = client.get("/api/song/a.sloppak/write-log").json()["rows"]
+    by_key = {x["key"]: x for x in rows}
+    assert by_key["album"]["old_value"] is None         # was a gap — no old value
+    assert by_key["album"]["new_value"] == "The Razors Edge"
+    assert by_key["genres"]["new_value"] == '["hard rock", "rock"]'
+
+
+def test_write_log_endpoint_shape_and_order(server, client):
+    make_dir_sloppak(server, "a.sloppak", DIFF_MANIFEST)
+    seed_match(server, "a.sloppak", state="manual")
+    enable_overwrite(client)
+    assert client.post("/api/song/a.sloppak/gap-fill",
+                       json={"overwrite_keys": ["artist"]}).status_code == 200
+    assert client.post("/api/song/a.sloppak/gap-fill",
+                       json={"overwrite_keys": ["album"]}).status_code == 200
+    rows = client.get("/api/song/a.sloppak/write-log").json()["rows"]
+    assert [x["key"] for x in rows] == ["album", "artist"]      # newest first
+    assert set(rows[0]) == {"id", "key", "old_value", "new_value",
+                            "source", "score", "ts"}
+    # Another song's rows don't bleed in.
+    make_dir_sloppak(server, "b.sloppak")
+    assert client.get("/api/song/b.sloppak/write-log").json()["rows"] == []
+
+
+def test_write_log_prunes_beyond_cap(server):
+    """The receipts table stays bounded at 5000 rows — oldest pruned first."""
+    db = server.meta_db
+    db.add_write_log("bulk.sloppak",
+                     [("album", None, str(i)) for i in range(5100)],
+                     source="text", score=1.0)
+    n = db.conn.execute("SELECT COUNT(*) FROM write_log").fetchone()[0]
+    assert n == 5000
+    oldest = db.conn.execute(
+        "SELECT new_value FROM write_log ORDER BY id ASC LIMIT 1").fetchone()[0]
+    assert oldest == "100"      # rows 0..99 fell off the bottom
+
+
+# ── revert ────────────────────────────────────────────────────────────────────
+
+def test_revert_dir_form_restores_original_and_resyncs_db(server, client):
+    d = make_dir_sloppak(server, "a.sloppak", DIFF_MANIFEST)
+    seed_match(server, "a.sloppak", state="manual")
+    enable_overwrite(client)
+    assert client.post("/api/song/a.sloppak/gap-fill",
+                       json={"overwrite_keys": ["artist"]}).status_code == 200
+    assert client.get("/api/song/a.sloppak").json()["artist"] == "AC/DC"
+    r = client.post("/api/song/a.sloppak/revert-original")
+    assert r.status_code == 200
+    # Author bytes restored verbatim; the backup is PRESERVED (re-apply later).
+    assert (d / "manifest.yaml").read_text(encoding="utf-8") == DIFF_MANIFEST
+    assert (d / "manifest.yaml.bak").exists()
+    row = client.get("/api/song/a.sloppak").json()
+    assert row["artist"] == "ACDC"
+    assert str(row["year"]) == "1991"
+    # And the preview still offers the revert + the differences again.
+    d2 = client.get("/api/song/a.sloppak/gap-fill").json()
+    assert d2["has_backup"] is True
+    assert {x["key"] for x in d2["differs"]} >= {"artist"}
+
+
+def test_revert_zip_form(server, client):
+    p = make_zip_sloppak(server, "a.sloppak", DIFF_MANIFEST)
+    seed_match(server, "a.sloppak", state="manual")
+    enable_overwrite(client)
+    assert client.post("/api/song/a.sloppak/gap-fill",
+                       json={"overwrite_keys": ["artist"]}).status_code == 200
+    assert client.post("/api/song/a.sloppak/revert-original").status_code == 200
+    with zipfile.ZipFile(p) as z:
+        assert z.read("manifest.yaml").decode("utf-8") == DIFF_MANIFEST
+        assert z.read("stems/full.ogg") == b"OggS-fake"     # pack intact
+    assert p.with_name(p.name + ".bak").exists()            # backup preserved
+    assert client.get("/api/song/a.sloppak").json()["artist"] == "ACDC"
+
+
+def test_revert_without_backup_is_404(server, client):
+    make_dir_sloppak(server, "a.sloppak")
+    assert client.post("/api/song/a.sloppak/revert-original").status_code == 404
+
+
+def test_revert_refuses_non_package_target_with_sibling_bak(server, client):
+    """A non-package file under DLC_DIR with a sibling `.bak` must NOT be
+    reverted — revert mirrors the write path's is_sloppak guard, so it never
+    restores a stray backup over a file the feature was not meant to touch."""
+    target = server.DLC_DIR / "notes.txt"
+    target.write_bytes(b"user notes, not a pack")
+    (server.DLC_DIR / "notes.txt.bak").write_bytes(b"stray backup")
+    r = client.post("/api/song/notes.txt/revert-original")
+    assert r.status_code == 404
+    # The target is left byte-for-byte untouched.
+    assert target.read_bytes() == b"user notes, not a pack"
+
+
+def test_preview_reports_backup_after_gap_fill(server, client):
+    """Plain gap-fill (R4a) also leaves the one-time backup — the preview
+    surfaces it so the drawer can offer Revert."""
+    make_dir_sloppak(server, "a.sloppak")
+    seed_match(server, "a.sloppak")
+    assert client.post("/api/song/a.sloppak/gap-fill",
+                       json={"keys": ["album"]}).status_code == 200
+    assert client.get("/api/song/a.sloppak/gap-fill").json()["has_backup"] is True
+
+
+def test_demo_mode_blocks_revert(tmp_path, monkeypatch, isolate_logging):
+    """The middleware turns revert away before any handler runs — demo
+    visitors can never rewrite pack files."""
+    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")
+    monkeypatch.setenv("FEEDBACK_DEMO_MODE", "1")
+    sys.modules.pop("server", None)
+    srv = importlib.import_module("server")
+    try:
+        r = TestClient(srv.app).post("/api/song/a.sloppak/revert-original")
+        assert r.status_code == 403
+    finally:
+        conn = getattr(getattr(srv, "meta_db", None), "conn", None)
+        if conn is not None:
+            conn.close()
+        sys.modules.pop("server", None)

tests/test_practice_suggestions.py

@@ -0,0 +1,140 @@
+"""Tests for the P3 growth-edge 'practice next' recommender —
+GET /api/library/practice-suggestions + meta_db.growth_edge_suggestions().
+
+The score is difficulty-appropriateness (mid band wins) × mastery-proximity
+(closer to 0.9, not yet there). Read-only: it must never write difficulty.
+Personal difficulty is per-filename (P1); authored/derived seeding + true
+per-arrangement difficulty are deferred pending the feedpak difficulty spec."""
+
+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:
+            conn.close()
+        sys.modules.pop("server", None)
+
+
+@pytest.fixture()
+def client(server):
+    return TestClient(server.app)
+
+
+def _seed(server, fn, title=None):
+    server.meta_db.put(fn, 0, 0, {"title": title or fn.split(".")[0], "artist": "A"})
+
+
+def _play(server, fn, acc, arr=0):
+    """Record a scored attempt so the song has a best_accuracy."""
+    server.meta_db.record_session(fn, arr, score=int(acc * 1000), accuracy=acc)
+
+
+def _diff(client, fn, d):
+    client.put(f"/api/song/{fn}/user-meta", json={"user_difficulty": d})
+
+
+def _suggest(client, limit=8):
+    return client.get(f"/api/library/practice-suggestions?limit={limit}").json()
+
+
+SUG = "/api/library/practice-suggestions"
+
+
+# ── Gating: only attempted & not-yet-mastered ────────────────────────────────
+
+def test_excludes_mastered_and_unattempted(client, server):
+    _seed(server, "mastered.archive"); _play(server, "mastered.archive", 0.95)
+    _seed(server, "inprog.archive");   _play(server, "inprog.archive", 0.6)
+    _seed(server, "fresh.archive")     # never played
+    got = {r["filename"] for r in _suggest(client)}
+    assert got == {"inprog.archive"}
+
+
+def test_empty_when_nothing_attempted(client, server):
+    _seed(server, "a.archive")
+    assert _suggest(client) == []
+
+
+# ── Ordering: mid-difficulty preferred at equal accuracy ──────────────────────
+
+def test_mid_difficulty_ranks_above_extremes(client, server):
+    for fn in ("mid.archive", "easy.archive", "hard.archive"):
+        _seed(server, fn); _play(server, fn, 0.6)
+    _diff(client, "mid.archive", 3)
+    _diff(client, "easy.archive", 1)
+    _diff(client, "hard.archive", 5)
+    order = [r["filename"] for r in _suggest(client)]
+    assert order[0] == "mid.archive"
+    # 1 and 5 share the same weight, so both trail mid
+    assert set(order[1:]) == {"easy.archive", "hard.archive"}
+
+
+# ── Ordering: closer-to-mastery preferred at equal difficulty ─────────────────
+
+def test_closer_to_mastery_ranks_higher(client, server):
+    _seed(server, "almost.archive"); _play(server, "almost.archive", 0.85)
+    _seed(server, "early.archive");  _play(server, "early.archive", 0.4)
+    # both unrated (→ treated as mid), so accuracy proximity decides
+    order = [r["filename"] for r in _suggest(client)]
+    assert order == ["almost.archive", "early.archive"]
+
+
+def test_unrated_still_surfaces_as_mid(client, server):
+    """Before anything is rated the shelf must still work (degrades to
+    closest-to-mastery). An unrated song outranks a very-easy rated one at
+    similar accuracy."""
+    _seed(server, "unrated.archive"); _play(server, "unrated.archive", 0.7)
+    _seed(server, "veryeasy.archive"); _play(server, "veryeasy.archive", 0.72)
+    _diff(client, "veryeasy.archive", 1)
+    order = [r["filename"] for r in _suggest(client)]
+    # unrated (weight 1.0 × 0.70 = 0.70) beats very-easy (0.6 × 0.72 = 0.432)
+    assert order[0] == "unrated.archive"
+
+
+# ── Best arrangement = the one closest to mastery ────────────────────────────
+
+def test_suggested_arrangement_is_best(client, server):
+    _seed(server, "multi.archive")
+    _play(server, "multi.archive", 0.5, arr=0)
+    _play(server, "multi.archive", 0.8, arr=1)   # closer to mastery
+    r = _suggest(client)[0]
+    assert r["filename"] == "multi.archive"
+    assert r["arrangement"] == 1
+    assert r["best_accuracy"] == 0.8
+
+
+# ── Enrichment + limit ───────────────────────────────────────────────────────
+
+def test_rows_are_enriched(client, server):
+    _seed(server, "song.archive", title="My Song"); _play(server, "song.archive", 0.6)
+    r = _suggest(client)[0]
+    assert r["title"] == "My Song" and r["artist"] == "A"
+    assert r["art_url"].endswith("/art")
+    assert "growth_score" in r
+
+
+def test_limit_is_respected(client, server):
+    for i in range(5):
+        fn = f"s{i}.archive"; _seed(server, fn); _play(server, fn, 0.5 + i * 0.05)
+    assert len(_suggest(client, limit=3)) == 3
+
+
+# ── Read-only: never writes difficulty ───────────────────────────────────────
+
+def test_recommender_never_writes_difficulty(client, server):
+    _seed(server, "a.archive"); _play(server, "a.archive", 0.6)
+    _suggest(client)
+    assert client.get("/api/song/a.archive/user-meta").json()["user_difficulty"] is None

tests/test_scraper_options.py

@@ -0,0 +1,333 @@
+"""Tests for the R1 scraper options: per-source toggles (MusicBrainz /
+Cover Art Archive), per-field auto-apply toggles (names / year / genres /
+cover art), and the review-queue order preference.
+
+Same no-network contract as the P8/R3 suites: both transports are faked
+over their single seams (`_mb_http_get`, `_caa_http_get`) and the network
+flag is only force-enabled where a test needs the pipeline to run.
+"""
+
+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:
+            conn.close()
+        sys.modules.pop("server", None)
+
+
+@pytest.fixture()
+def client(server):
+    return TestClient(server.app)
+
+
+class FakeMB:
+    """Canned MusicBrainz over the `_mb_http_get` seam (the P8 fixture)."""
+
+    def __init__(self):
+        self.calls = []
+        self.search_response = {"recordings": []}
+
+    def __call__(self, path, params):
+        self.calls.append((path, dict(params)))
+        if path == "recording":
+            return self.search_response
+        raise AssertionError(f"unexpected MB path {path!r}")
+
+
+@pytest.fixture()
+def mb(server, monkeypatch):
+    fake = FakeMB()
+    monkeypatch.setattr(server, "_mb_http_get", fake)
+    monkeypatch.setattr(server, "_enrich_network_enabled", lambda: True)
+    return fake
+
+
+def _put(server, fn, title="Thunderstruck (v2)", artist="ACDC", album="",
+         duration=292, year="1990", mtime=0):
+    server.meta_db.put(fn, mtime, 0, {
+        "title": title, "artist": artist, "album": album, "year": year,
+        "duration": duration, "arrangements": [{"name": "Lead", "index": 0}],
+    })
+
+
+def mb_doc(rid="rec-1", title="Thunderstruck", artist="AC/DC", artist_id="art-1",
+           album="The Razors Edge", date="1990-09-24", length_ms=292000, score=100):
+    return {
+        "id": rid, "score": score, "title": title, "length": length_ms,
+        "isrcs": ["AUAP09000045"],
+        "artist-credit": [{"name": artist, "artist": {
+            "id": artist_id, "name": artist, "sort-name": artist}}],
+        "releases": [{"id": "rel-1", "title": album, "status": "Official",
+                      "date": date, "release-group": {"primary-type": "Album"}}],
+        "tags": [{"name": "hard rock", "count": 7}],
+    }
+
+
+# ── settings keys ─────────────────────────────────────────────────────────────
+
+BOOL_KEYS = ("enrich_src_musicbrainz", "enrich_src_caa", "enrich_apply_names",
+             "enrich_apply_year", "enrich_apply_genres", "enrich_apply_art")
+
+
+def test_scraper_option_keys_validate_and_persist(client):
+    for key in BOOL_KEYS:
+        bad = client.post("/api/settings", json={key: "yes"}).json()
+        assert "error" in bad
+        client.post("/api/settings", json={key: False})
+        assert client.get("/api/settings").json()[key] is False
+    assert "error" in client.post(
+        "/api/settings", json={"enrich_review_order": "random"}).json()
+    assert "error" in client.post(
+        "/api/settings", json={"enrich_review_order": 42}).json()
+    client.post("/api/settings", json={"enrich_review_order": "artist"})
+    assert client.get("/api/settings").json()["enrich_review_order"] == "artist"
+
+
+def test_defaults_present(server):
+    d = server._default_settings()
+    for key in BOOL_KEYS:
+        assert d[key] is True
+    assert d["enrich_review_order"] == "missing_first"
+
+
+# ── per-source: MusicBrainz ───────────────────────────────────────────────────
+
+def test_musicbrainz_source_off_stamps_without_matching(server, mb, client):
+    client.post("/api/settings", json={"enrich_src_musicbrainz": False})
+    _put(server, "a.sloppak")
+    mb.search_response = {"recordings": [mb_doc()]}
+    server._background_enrich()
+    assert mb.calls == []
+    row = server.meta_db.get_enrichment("a.sloppak")
+    assert row["match_state"] == "unscanned"       # hash stamped, no match
+    # Re-enabling picks the same row up on the next pass.
+    client.post("/api/settings", json={"enrich_src_musicbrainz": True})
+    server._background_enrich()
+    assert server.meta_db.get_enrichment("a.sloppak")["match_state"] == "matched"
+
+
+# ── per-field auto-apply ──────────────────────────────────────────────────────
+
+def test_field_toggles_strip_auto_applied_fields(server, mb, client):
+    client.post("/api/settings", json={"enrich_apply_year": False,
+                                       "enrich_apply_genres": False})
+    _put(server, "a.sloppak")
+    mb.search_response = {"recordings": [mb_doc()]}
+    server._background_enrich()
+    row = server.meta_db.get_enrichment("a.sloppak")
+    assert row["match_state"] == "matched"
+    assert row["canon_artist"] == "AC/DC"
+    assert row["canon_title"] == "Thunderstruck"
+    assert row["canon_album"] == "The Razors Edge"
+    assert row["canon_year"] is None               # toggled off
+    assert row["genres"] == []                     # toggled off
+    # Identity ids always stamp — the art fetch and re-matching need them.
+    assert row["mb_recording_id"] == "rec-1"
+    assert row["mb_release_id"] == "rel-1"
+
+
+def test_names_toggle_keeps_ids_and_other_fields(server, mb, client):
+    client.post("/api/settings", json={"enrich_apply_names": False})
+    _put(server, "a.sloppak")
+    mb.search_response = {"recordings": [mb_doc()]}
+    server._background_enrich()
+    row = server.meta_db.get_enrichment("a.sloppak")
+    assert row["match_state"] == "matched"
+    assert row["canon_artist"] is None
+    assert row["canon_title"] is None
+    assert row["canon_album"] is None
+    assert row["canon_year"] == "1990"
+    assert row["genres"] == ["hard rock"]
+    assert row["mb_recording_id"] == "rec-1"
+
+
+def test_review_accept_applies_all_fields_despite_toggles(server, mb, client):
+    """A match the USER confirms is their intent — the auto-apply toggles
+    gate only what happens without them."""
+    client.post("/api/settings", json={"enrich_apply_names": False,
+                                       "enrich_apply_year": False,
+                                       "enrich_apply_genres": False})
+    # Partial artist agreement → review tier (candidates stored unfiltered).
+    _put(server, "a.sloppak", artist="AC/DC ft Nobody")
+    mb.search_response = {"recordings": [mb_doc()]}
+    server._background_enrich()
+    assert server.meta_db.get_enrichment("a.sloppak")["match_state"] == "review"
+    r = client.post("/api/enrichment/review/a.sloppak/accept",
+                    json={"recording_id": "rec-1"})
+    assert r.status_code == 200
+    row = server.meta_db.get_enrichment("a.sloppak")
+    assert row["match_state"] == "manual"
+    assert row["canon_artist"] == "AC/DC"
+    assert row["canon_year"] == "1990"
+    assert row["genres"] == ["hard rock"]
+
+
+# ── per-field: nothing-forfeited (re-enable backfills, no partial seeding) ─────
+
+def test_reenabling_field_backfills_matched_row(server, mb, client):
+    """A field toggled OFF strips the value AND records it in apply_mask, so
+    turning the field back on re-queues the (unchanged-hash) matched row and
+    backfills — the same "nothing forfeited" contract the source/art toggles
+    keep."""
+    client.post("/api/settings", json={"enrich_apply_year": False})
+    _put(server, "a.sloppak")
+    mb.search_response = {"recordings": [mb_doc()]}
+    server._background_enrich()
+    row = server.meta_db.get_enrichment("a.sloppak")
+    assert row["match_state"] == "matched"
+    assert row["canon_year"] is None                    # suppressed
+    assert row["apply_mask"] == "enrich_apply_year"     # …and remembered
+    # Re-enable → next pass re-queues and backfills the year (hash unchanged).
+    client.post("/api/settings", json={"enrich_apply_year": True})
+    server._background_enrich()
+    row = server.meta_db.get_enrichment("a.sloppak")
+    assert row["match_state"] == "matched"
+    assert row["canon_year"] == "1990"                  # backfilled
+    assert row["apply_mask"] in (None, "")              # fully applied now
+    # Converged: a fully-applied row is not re-queued again.
+    assert server.meta_db.enrichment_pending(
+        allowed_keys=frozenset(server._ENRICH_APPLY_FIELDS)) == []
+
+
+def test_partial_match_is_not_a_cache_donor(server):
+    """A row that suppressed a display field must not seed a sibling chart of
+    the same recording with its blank — enrichment_cache_lookup skips it, so
+    the sibling falls through to its own (correctly-filtered) match. A fully-
+    applied row IS a donor."""
+    h = server.meta_db.enrichment_content_hash("ACDC", "Thunderstruck (v2)", "", 292)
+    # Partial donor: matched with the year suppressed (apply_mask set).
+    server.meta_db.apply_enrichment_match(
+        "a.sloppak", h, "matched", source="text", score=1.0,
+        cand={"recording_id": "rec-1", "artist": "AC/DC", "title": "Thunderstruck"},
+        apply_mask="enrich_apply_year")
+    assert server.meta_db.enrichment_cache_lookup(
+        h, exclude_filename="b.sloppak") is None
+    # Fully-applied donor (no apply_mask): offered, with its year intact.
+    server.meta_db.apply_enrichment_match(
+        "c.sloppak", h, "matched", source="text", score=1.0,
+        cand={"recording_id": "rec-1", "artist": "AC/DC",
+              "title": "Thunderstruck", "year": "1990"})
+    donor = server.meta_db.enrichment_cache_lookup(h, exclude_filename="b.sloppak")
+    assert donor is not None and donor["year"] == "1990"
+
+
+# ── per-source / per-field: cover art ─────────────────────────────────────────
+
+def png_bytes(color=(200, 30, 30)):
+    buf = _io.BytesIO()
+    Image.new("RGB", (4, 4), color).save(buf, "PNG")
+    return buf.getvalue()
+
+
+def make_sloppak(server, name, 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")
+    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"):
+    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, "matched", source="text", score=1.0,
+        cand={"recording_id": "rec-1", "release_id": release_id,
+              "title": song["title"], "artist": song["artist"]})
+
+
+@pytest.fixture()
+def caa(server, monkeypatch):
+    calls = []
+    art = {"rel-1": png_bytes((60, 60, 200))}
+
+    def fake(release_id):
+        calls.append(release_id)
+        return art.get(release_id)
+    fake.calls = calls
+    monkeypatch.setattr(server, "_caa_http_get", fake)
+    monkeypatch.setattr(server, "_enrich_network_enabled", lambda: True)
+    return fake
+
+
+def test_caa_source_toggle_gates_art_fetch(server, client, caa):
+    make_sloppak(server, "a.sloppak")
+    _match_row(server, "a.sloppak")
+    client.post("/api/settings", json={"enrich_src_caa": False})
+    server._background_enrich()
+    assert caa.calls == []
+    row = server.meta_db.get_enrichment("a.sloppak")
+    assert row["art_state"] is None                # not forfeited, just skipped
+    # Re-enable → the same row is picked up.
+    client.post("/api/settings", json={"enrich_src_caa": True})
+    server._background_enrich()
+    assert server.meta_db.get_enrichment("a.sloppak")["art_state"] == "caa"
+
+
+def test_apply_art_toggle_gates_art_fetch(server, client, caa):
+    make_sloppak(server, "a.sloppak")
+    _match_row(server, "a.sloppak")
+    client.post("/api/settings", json={"enrich_apply_art": False})
+    server._background_enrich()
+    assert caa.calls == []
+    assert server.meta_db.get_enrichment("a.sloppak")["art_state"] is None
+
+
+# ── review-queue order ────────────────────────────────────────────────────────
+
+def _review_row(server, fn):
+    server.meta_db.apply_enrichment_match(
+        fn, "h", "review", source="text", score=0.7,
+        candidates=[{"recording_id": "rec-1", "title": "T", "artist": "A"}])
+
+
+def _review_filenames(client):
+    return [s["filename"] for s in
+            client.get("/api/enrichment/review").json()["songs"]]
+
+
+def test_review_queue_order_setting(server, client):
+    # a: complete, artist Alpha, oldest; b: missing album+year, artist Zeta,
+    # middle; c: missing year, artist Mid, newest — the three orders differ.
+    _put(server, "a.sloppak", title="Song A", artist="Alpha",
+         album="Full", year="1990", mtime=100)
+    _put(server, "b.sloppak", title="Song B", artist="Zeta",
+         album="", year="", mtime=200)
+    _put(server, "c.sloppak", title="Song C", artist="Mid",
+         album="Full", year="", mtime=300)
+    for fn in ("a.sloppak", "b.sloppak", "c.sloppak"):
+        _review_row(server, fn)
+
+    # Default: missing-data-first.
+    assert _review_filenames(client) == ["b.sloppak", "c.sloppak", "a.sloppak"]
+    client.post("/api/settings", json={"enrich_review_order": "artist"})
+    assert _review_filenames(client) == ["a.sloppak", "c.sloppak", "b.sloppak"]
+    client.post("/api/settings", json={"enrich_review_order": "recent"})
+    assert _review_filenames(client) == ["c.sloppak", "b.sloppak", "a.sloppak"]
+    # An unknown stored value degrades to the default order, never an error.
+    assert server.meta_db.enrichment_review_queue(order="bogus")[0]["filename"] == "b.sloppak"

tests/test_sloppak_jsonc_load.py

@@ -0,0 +1,335 @@
+"""Tests for .jsonc support in the sloppak/feedpak loaders (feedpak-spec §8).
+
+When a manifest pointer resolves to a ``.jsonc`` file, the reader MUST strip
+C-style comments (``//`` line and ``/* */`` block) before parsing. These tests
+exercise every side-file reader in ``lib/sloppak.py`` (arrangement, notation,
+drum_tab, song_timeline, lyrics, keys) plus the arrangement/song_timeline
+reads in ``scripts/lift_keys_notation.py`` against ``.jsonc`` inputs, and pin
+the string-boundary rule (comment-like text inside a JSON string survives).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+import yaml
+
+import sloppak as sloppak_mod
+from jsonc import parse_jsonc
+from scripts.lift_keys_notation import _load_song_beats
+
+
+# ── jsonc.parse_jsonc unit tests ─────────────────────────────────────────────
+
+def test_parse_jsonc_strips_line_comment():
+    assert parse_jsonc('{"a": 1 // c\n}') == {"a": 1}
+
+
+def test_parse_jsonc_strips_block_comment():
+    assert parse_jsonc('{"a": /* x */ 2}') == {"a": 2}
+
+
+def test_parse_jsonc_strips_multiline_block_comment():
+    text = '{\n  /* multi\n     line */\n  "a": 1\n}'
+    assert parse_jsonc(text) == {"a": 1}
+
+
+def test_parse_jsonc_preserves_comment_like_text_in_strings():
+    # ``//`` and ``/*`` inside a JSON string literal must NOT be treated as
+    # comments — the string-aware regex keeps them verbatim.
+    text = '{"url": "https://x/y", "note": "// not a comment /* still not */"}'
+    out = parse_jsonc(text)
+    assert out["url"] == "https://x/y"
+    assert out["note"] == "// not a comment /* still not */"
+
+
+def test_parse_jsonc_rejects_malformed():
+    with pytest.raises(json.JSONDecodeError):
+        parse_jsonc('{"a": // comment breaks value\n}')
+
+
+def test_parse_jsonc_plain_json_passes_through():
+    assert parse_jsonc('{"a": 1}') == {"a": 1}
+
+
+# ── Fixture builder ──────────────────────────────────────────────────────────
+
+def _base_arrangement(*, beats=None) -> dict:
+    return {
+        "name": "Lead", "tuning": [0, 0, 0, 0, 0, 0], "capo": 0,
+        "notes": [], "chords": [], "anchors": [], "handshapes": [],
+        "templates": [], "beats": beats or [], "sections": [],
+    }
+
+
+def _write_sloppak(root: Path, *, manifest_extras: dict, side_files: dict) -> Path:
+    """Build a minimal directory-form sloppak.
+
+    ``side_files`` maps a pak-relative filename (e.g. ``"arrangements/lead.jsonc"``)
+    to the exact text to write — so the caller controls comments / extensions.
+    """
+    pak = root / f"{root.name}.sloppak"
+    pak.mkdir()
+    (pak / "arrangements").mkdir()
+    # A default lead arrangement file the manifest references; can be overridden
+    # via side_files if the caller wants a .jsonc arrangement.
+    if "arrangements/lead.json" not in side_files and "arrangements/lead.jsonc" not in side_files:
+        (pak / "arrangements" / "lead.json").write_text(
+            json.dumps(_base_arrangement())
+        )
+    for rel, text in side_files.items():
+        target = pak / rel
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(text, encoding="utf-8")
+    manifest = {
+        "title": "Test", "artist": "Tester", "album": "", "year": 2026,
+        "duration": 10.0,
+        "arrangements": [{"id": "lead", "name": "Lead", "file": "arrangements/lead.json"}],
+        "stems": [{"id": "full", "file": "stems/full.ogg", "default": True}],
+    }
+    manifest.update(manifest_extras)
+    (pak / "manifest.yaml").write_text(yaml.safe_dump(manifest, sort_keys=False))
+    return pak
+
+
+def _load(pak_path: Path, tmp_path: Path):
+    dlc_root = pak_path.parent
+    cache = tmp_path / "cache"
+    cache.mkdir()
+    return sloppak_mod.load_song(pak_path.name, dlc_root, cache)
+
+
+# ── Arrangement .jsonc ───────────────────────────────────────────────────────
+
+def test_load_arrangement_jsonc_with_comments(tmp_path: Path):
+    arr_text = (
+        '// lead chart\n'
+        '{\n'
+        '  "name": "Lead",\n'
+        '  "tuning": [0, 0, 0, 0, 0, 0],\n'
+        '  "capo": 0,\n'
+        '  /* no notes yet */\n'
+        '  "notes": [{"t": 0.5, "s": 0, "f": 5, "sus": 0}],\n'
+        '  "chords": [], "anchors": [], "handshapes": [], "templates": [],\n'
+        '  "beats": [], "sections": []\n'
+        '}'
+    )
+    pak = _write_sloppak(
+        tmp_path,
+        manifest_extras={
+            "arrangements": [{"id": "lead", "name": "Lead",
+                              "file": "arrangements/lead.jsonc"}]
+        },
+        side_files={"arrangements/lead.jsonc": arr_text},
+    )
+    loaded = _load(pak, tmp_path)
+    assert len(loaded.song.arrangements) == 1
+    arr = loaded.song.arrangements[0]
+    assert arr.name == "Lead"
+    assert len(arr.notes) == 1
+    assert arr.notes[0].fret == 5
+
+
+def test_load_arrangement_jsonc_malformed_is_skipped(tmp_path: Path):
+    # A .jsonc file that is still invalid after stripping comments must be
+    # skipped gracefully (the loader's existing permissive path), not crash.
+    pak = _write_sloppak(
+        tmp_path,
+        manifest_extras={
+            "arrangements": [{"id": "lead", "name": "Lead",
+                              "file": "arrangements/lead.jsonc"}]
+        },
+        side_files={"arrangements/lead.jsonc": '{"notes": // broken\n}'},
+    )
+    loaded = _load(pak, tmp_path)
+    # The malformed arrangement is skipped; load still returns a song shell.
+    assert len(loaded.song.arrangements) == 0
+
+
+# ── Notation .jsonc ──────────────────────────────────────────────────────────
+
+def test_load_notation_jsonc_with_comments(tmp_path: Path):
+    from tests.test_sloppak_notation_load import VALID_NOTATION
+    payload = VALID_NOTATION
+    text = (
+        '/* notation for keys */\n'
+        + json.dumps(payload)
+    )
+    pak = _write_sloppak(
+        tmp_path,
+        manifest_extras={
+            "arrangements": [{"id": "lead", "name": "Lead",
+                              "file": "arrangements/lead.json",
+                              "notation": "notation_lead.jsonc"}]
+        },
+        side_files={"notation_lead.jsonc": text},
+    )
+    loaded = _load(pak, tmp_path)
+    assert loaded.notation_by_id is not None
+    assert "lead" in loaded.notation_by_id
+
+
+# ── drum_tab .jsonc ──────────────────────────────────────────────────────────
+
+def test_load_drum_tab_jsonc_with_comments(tmp_path: Path):
+    payload = {
+        "version": 1, "name": "Drums",
+        "kit": [{"id": "kick", "name": "Kick"}],
+        "hits": [{"t": 0.5, "p": "kick", "v": 110}],
+    }
+    text = '// drum tab\n' + json.dumps(payload)
+    pak = _write_sloppak(
+        tmp_path,
+        manifest_extras={"drum_tab": "drum_tab.jsonc"},
+        side_files={"drum_tab.jsonc": text},
+    )
+    loaded = _load(pak, tmp_path)
+    assert loaded.drum_tab is not None
+    assert loaded.drum_tab["hits"][0]["p"] == "kick"
+
+
+# ── song_timeline .jsonc ─────────────────────────────────────────────────────
+
+def test_load_song_timeline_jsonc_with_comments(tmp_path: Path):
+    payload = {
+        "beats": [{"time": 0.0, "measure": 0}, {"time": 0.5, "measure": 0}],
+        "sections": [{"name": "intro", "number": 0, "time": 0.0}],
+    }
+    text = '/* timeline */\n' + json.dumps(payload)
+    pak = _write_sloppak(
+        tmp_path,
+        manifest_extras={"song_timeline": "song_timeline.jsonc"},
+        side_files={"song_timeline.jsonc": text},
+    )
+    loaded = _load(pak, tmp_path)
+    assert loaded.song_timeline is not None
+    assert len(loaded.song.beats) == 2
+    assert loaded.song.sections[0].name == "intro"
+
+
+# ── lyrics .jsonc ────────────────────────────────────────────────────────────
+
+def test_load_lyrics_jsonc_with_comments(tmp_path: Path):
+    payload = [
+        {"w": "Hel", "t": 0.0, "d": 0.2},
+        {"w": "lo", "t": 0.2, "d": 0.3},
+    ]
+    text = '// syllable lyrics\n' + json.dumps(payload)
+    pak = _write_sloppak(
+        tmp_path,
+        manifest_extras={"lyrics": "lyrics.jsonc"},
+        side_files={"lyrics.jsonc": text},
+    )
+    loaded = _load(pak, tmp_path)
+    assert len(loaded.song.lyrics) == 2
+    assert loaded.song.lyrics[0]["w"] == "Hel"
+
+
+# ── keys .jsonc ──────────────────────────────────────────────────────────────
+
+def test_load_keys_jsonc_with_comments(tmp_path: Path):
+    payload = {
+        "version": 1,
+        "events": [{"t": 0.0, "key": "Em", "scale": "natural_minor"}],
+    }
+    text = '/* key/scale track */\n' + json.dumps(payload)
+    pak = _write_sloppak(
+        tmp_path,
+        manifest_extras={"keys": "keys.jsonc"},
+        side_files={"keys.jsonc": text},
+    )
+    loaded = _load(pak, tmp_path)
+    assert loaded.keys is not None
+    assert loaded.keys["events"][0]["key"] == "Em"
+
+
+# ── Comment-like text inside strings is preserved end-to-end ─────────────────
+
+def test_load_arrangement_jsonc_preserves_comment_like_string_values(tmp_path: Path):
+    # A note whose fret label (if it had one) or a string field contains ``//``
+    # must survive the strip. We put a ``//`` inside the arrangement name and a
+    # ``/* */`` inside a beat section name to exercise both comment shapes.
+    arr_text = (
+        '{\n'
+        '  "name": "Lead // solo",\n'
+        '  "tuning": [0, 0, 0, 0, 0, 0], "capo": 0,\n'
+        '  "notes": [], "chords": [], "anchors": [], "handshapes": [], "templates": [],\n'
+        '  "beats": [],\n'
+        '  "sections": [{"name": "verse /* important */", "number": 0, "time": 0.0}]\n'
+        '}'
+    )
+    pak = _write_sloppak(
+        tmp_path,
+        manifest_extras={
+            "arrangements": [{"id": "lead", "name": "Lead",
+                              "file": "arrangements/lead.jsonc"}]
+        },
+        side_files={"arrangements/lead.jsonc": arr_text},
+    )
+    loaded = _load(pak, tmp_path)
+    arr = loaded.song.arrangements[0]
+    # The manifest's ``name: Lead`` overrides the arrangement JSON's name, so
+    # assert on the section name instead — it flows straight from the parsed
+    # .jsonc with no manifest override, proving the comment-like text inside
+    # the string survived the strip.
+    assert arr.name == "Lead"
+    assert loaded.song.sections[0].name == "verse /* important */"
+
+
+# ── lift_keys_notation reads .jsonc arrangements / song_timeline ─────────────
+
+def test_lift_keys_notation_loads_song_beats_from_jsonc_timeline(tmp_path: Path):
+    """``_load_song_beats`` (the helper the lifter uses to find downbeats) must
+    read a ``.jsonc`` song_timeline when the manifest points at one."""
+    timeline_text = (
+        '// timeline\n'
+        + json.dumps({
+            "beats": [{"time": 0.0, "measure": 0}, {"time": 0.5, "measure": 0},
+                      {"time": 1.0, "measure": 1}],
+            "sections": [],
+        })
+    )
+    pak = tmp_path / "song.sloppak"
+    pak.mkdir()
+    (pak / "arrangements").mkdir()
+    (pak / "arrangements" / "keys.json").write_text(json.dumps(_base_arrangement()))
+    (pak / "song_timeline.jsonc").write_text(timeline_text, encoding="utf-8")
+    manifest = {
+        "title": "T", "artist": "A", "duration": 4.0,
+        "arrangements": [{"id": "keys", "name": "Keys",
+                          "file": "arrangements/keys.json"}],
+        "song_timeline": "song_timeline.jsonc",
+        "stems": [{"id": "full", "file": "stems/full.ogg"}],
+    }
+    (pak / "manifest.yaml").write_text(yaml.safe_dump(manifest, sort_keys=False))
+    beats = _load_song_beats(pak, manifest)
+    assert len(beats) == 3
+    assert beats[2]["measure"] == 1
+
+
+def test_lift_keys_notation_falls_back_to_jsonc_arrangement_beats(tmp_path: Path):
+    """When no song_timeline is present, ``_load_song_beats`` falls back to the
+    first arrangement JSON carrying beats — and that arrangement may be ``.jsonc``."""
+    arr_text = (
+        '/* keys */\n'
+        + json.dumps({
+            **_base_arrangement(),
+            "beats": [{"time": 0.0, "measure": 0}, {"time": 1.0, "measure": 1}],
+        })
+    )
+    pak = tmp_path / "song.sloppak"
+    pak.mkdir()
+    (pak / "arrangements").mkdir()
+    (pak / "arrangements" / "keys.jsonc").write_text(arr_text, encoding="utf-8")
+    manifest = {
+        "title": "T", "artist": "A", "duration": 4.0,
+        "arrangements": [{"id": "keys", "name": "Keys",
+                          "file": "arrangements/keys.jsonc"}],
+        "stems": [{"id": "full", "file": "stems/full.ogg"}],
+    }
+    (pak / "manifest.yaml").write_text(yaml.safe_dump(manifest, sort_keys=False))
+    beats = _load_song_beats(pak, manifest)
+    assert len(beats) == 2
+    assert beats[1]["measure"] == 1