Merge remote-tracking branch 'origin/main' into fix/gpx-bcfs-final-partial-sector

# Conflicts:
#	CHANGELOG.md

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

.github/workflows/nightly.yml

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

.github/workflows/rc.yml

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

.github/workflows/release.yml

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

.github/workflows/ship-ci.yml

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

.gitignore

@@ -21,9 +21,15 @@ plugins/*/
 # treats them identically to user-installed ones) but are bundled with
 # the default container image and marked `"bundled": true` in their
 # manifest. Add new core plugins as `!plugins/<id>/` exceptions.
+!plugins/achievements/
+!plugins/achievements/**
+plugins/achievements/__pycache__/
 !plugins/highway_3d/
 !plugins/highway_3d/**
 plugins/highway_3d/__pycache__/
+!plugins/folder_library/
+!plugins/folder_library/**
+plugins/folder_library/__pycache__/
 !plugins/app_tour_library/
 !plugins/app_tour_library/**
 !plugins/app_tour_settings/
@@ -38,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

@@ -8,6 +8,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- **Playlist shuffle.** The v3 playlist detail page gains a crossing-arrows shuffle toggle next to Play all / Play album. When on, `playQueue.start` Fisher-Yates-shuffles the queue once at start (on a copy — the stored playlist order is untouched), swapping any per-slot album arrangements in lockstep so each slot keeps its pinned arrangement. The preference is global and persists in `localStorage` (`v3PlaylistShuffle`). Tests: `tests/js/play_queue_shuffle.test.js`.
+
+### Changed
+- **Player frame-time hotspots removed (trace-backed) + weak-hardware hardening.** A Chrome performance trace of a 3D-highway session surfaced two core per-frame layout-thrash sources, now fixed: the highway's visibility check read `canvas.offsetParent` every rAF frame (forces style/layout recalc — now sampled every 10th frame with a cached value, force-refreshed on init/canvas-replace/resize/override-clear), and the v3 player chrome loop called `matches(':hover')` per frame and unconditionally rewrote the Up-Next pill's `textContent`/bar width at 6 Hz (now hover-tracked via mouseenter/mouseleave, DOM writes only on value change, progress bar moved from `width` to compositor-only `scaleX`). The 3D highway pre-warms shader programs (`ren.compile`) and deterministic label textures at init — and chart-dependent chord/section label textures on first draw — so first-appearance shader-compile/texture-upload frame spikes move into the load spinner. For weaker hardware: the per-frame renderer bundle is now a single reused object instead of a fresh ~35-field allocation per frame (object identity is stable and meaningless; array fields still swap reference on chart changes), custom viz get `bundle.lowerBoundT`/`bundle.lowerBoundTime` binary-search helpers for visible-window culling, the default 2D highway's beat lines no longer scan every beat in the song per frame, and the 3D highway stops reading `localStorage` per frame (1 Hz poll) and caches its lyrics text-measurement layout per displayed line instead of re-measuring every syllable every frame. A second, throttled-CPU trace pass additionally removed: shader-program re-resolution churn from label texture swaps (`material.needsUpdate` is now only set on a null↔texture transition — swapping between two cached label textures never changes the compiled program), the 3D highway's per-frame `getBoundingClientRect` layout read in its canvas-size self-check (now every 10th frame, still immediate on backing-store change), and the core 60 Hz HUD clock rewriting `textContent` on every tick (now write-on-change, ~1/s). The dominant residual — steady `getParameters` shader-program re-resolution (~4% of throttled main thread) — turned out to be Three r158+'s transparent-DoubleSide two-pass rendering, which sets `material.needsUpdate` twice per object per frame; all 18 of the 3D highway's transparent DoubleSide materials are flat unlit quads (labels, rails, chord frames, lanes), so they now declare `forceSinglePass: true`, eliminating the recompile churn and halving those objects' draw calls.
+
+### Fixed
+- **Guitar Pro 6 (`.gpx`) import no longer fails on every real file.** The GPX BCFS container reader (`lib/gp2rs_gpx.py`) rejected any file whose final sector wasn't a full `0x1000` block — but a real `.gpx`'s BCFZ-declared decompressed size isn't sector-aligned, so the last (small) container file always lands in a partial trailing sector. The bounds check *raised* `GPX BCFS sector pointer out of range (malformed file)` instead of clamping the tail read, so `_load_gpif` threw before `score.gpif` could be extracted and **no GP6 file could be imported into the song editor** (both real test files failed identically — this wasn't file-specific). GP7/GP8 `.gp` files were unaffected — they take the ZIP path, not BCFS, which is why prior GP-import work didn't surface it. The reader now **clamps the final sector read to the buffer end** (the per-file size field trims the padding anyway), matching canonical GPX readers (alphaTab / PyGuitarPro); a sector whose *start* is past the end still raises, preserving the malformed-file guard. Verified against two real GP6 files — both now unpack to valid GPIF with all tracks. Tests: `tests/test_gp2rs_gpx.py` (partial-final-sector round-trip, multi-file container, sector-aligned baseline, and the preserved out-of-range guard).
+- **v3 Songs grid: fixed the scroll stutter that "skips every so many scrolls," up or down.** The virtualized grid rebuilt its **entire** visible window (`grid.innerHTML = …` + a full `wireCards` pass) every time it slid by one row, so each row-boundary crossing was a heavy synchronous frame that stalled the main thread and buffered held-arrow key-repeats into a visible lurch (a tester's "super fast for a second then slowed down") at fixed scroll offsets — in **both directions and regardless of whether the page was already loaded** (the cost was DOM teardown, not fetching, which is why scrolling back up over cached songs hitched too). `renderWindow()` now **reconciles the window in place**: it reuses the card nodes that stay on-screen and builds only the row that enters/leaves (~6 nodes per slide instead of ~60), keyed by absolute index with a real-vs-skeleton + select-mode signature so hole-fills (after a page fetch) and select-mode toggles still rebuild exactly the nodes that changed. `wireCards`'s `data-wired` guard then wires only the freshly-built nodes, so per-slide listener churn drops with it. Follow-up to the stage-2 virtualized grid (got-feedback/feedBack#636 item 3). Frontend-only: `static/v3/songs.js`. Tests: `tests/js/v3_songs_window_recycle.test.js` (window stays `[start,end)` contiguous + in-window node identity reused across a down-then-up scroll; select-mode toggle and rail-seek jump rebuild correctly).
+- **Starter content seeds again (and now ships The Adicts' "Ode to Joy").** `_BUILTIN_STARTER_SOURCES` still listed `beethoven-ode_to_joy.feedpak` after that pack was deleted, and never wired up its replacement `the_adicts-ode-to-joy_vst_cover.feedpak` that landed on disk. The listed-but-missing file made the all-present gate never fire, so **no** starter songs seeded on first run. Synced the manifest to what's on disk (Für Elise, Star Spangled Banner, The Adicts' Ode to Joy). Tests: `tests/test_builtin_starter_seed.py` (the present/unlisted guards were red on `main`).
+- **Edit Metadata now writes into `.feedpak` files, not just legacy `.sloppak` ones.** `lib/songmeta.py`'s suffix gate predated the format rename — core reads both suffixes everywhere else (`sloppak.SONG_EXTS`), but the metadata writer only dispatched on `.sloppak`, so editing a zip-form `.feedpak`'s title/artist/album/year silently fell back to a DB-only update. That looked fine until the next **full library rescan** re-derived metadata from the file and reverted the edit (directory-form packages were unaffected — they dispatch on manifest presence, not suffix). The gate now accepts both package suffixes. Tests: `tests/test_songmeta.py` `TestWriteSongMetadata` (both zip suffixes, mixed-case suffix, directory form, unknown-suffix fallback).
+- **3D Drum & Keys highways now re-frame on fullscreen/layout drift under splitscreen.** The guitar/bass `highway_3d` self-detects when its panel canvas changes size and re-runs `applySize()` every frame, because the splitscreen host overrides `hw.resize` and never calls `renderer.resize()`. The drum and keys highways lacked that fallback — they only re-framed when the host explicitly called `resize(w, h)` — so their panels stayed framed for the pre-fullscreen size while the guitar/bass panels adapted (visible as a too-small, off-center highway after maximizing a split-screen session). Both draw loops now port `highway_3d`'s per-frame drift check: they re-apply on backing-store change (`canvas.width/height`) AND on CSS-box drift (`clientWidth/clientHeight` vs the last applied logical size, throttled to every 10th frame), and reset the tracking in `destroy()` so a reused instance re-frames on the next song. `plugins/drum_highway_3d` → 0.3.1, `plugins/keys_highway_3d` → 0.1.1. Tests: `tests/js/drum_keys_highway_3d_resize_reframe.test.js`.
+- **Tuner: finished the "remove unused settings" cleanup and fixed the sidebar panel position.** The Floating Button and Tuning Visibility settings sections were removed, but their config was still live: `disabledTunings` still filtered the tuner menu (with no UI left to re-enable a hidden tuning — a one-way trap) and `showFloatingButton` still gated the floating launcher. Both are now fully retired — the enforcement paths in `plugins/tuner/screen.js`/`utils/ui.js` and the persistence in `plugins/tuner/routes.py` are gone (and `routes.py` strips the retired keys on write, so stale values are purged). The tuner panel opened from the v3 sidebar Plugins rail popover now anchors beside it via the host's stable plugin-control slot API (falling back to the popover id), is **clamped to the viewport** so it can't open off the right/bottom edge on narrow/short windows, and re-anchors on window resize. `plugins/tuner` → 1.3.3.
+
+### Added
+- **Host theme read surface — `window.feedBack.theme` + always-present `--fbv-*` tokens — so a plugin feature can render correctly under any theme instead of binding to whichever one the developer happened to see.** The cosmetics applier (`static/v3/theme-core.js`) previously only *applied* themes and emitted `--fbv-*` vars **only while a theme was equipped** (nothing for a plugin to read in the default, un-themed state) with no read/capability API — so plugins reinvented their own theming and a new visual *device* (a glow, a gradient) silently bound to one look. It now: (1) emits the default `fb` palette as **always-present `--fbv-*` on `:root`** (additive — the un-themed look is unchanged; the `fb-*` utilities still use their compiled defaults; this only hands plugins a stable host token to read + derive surfaces from), plus two keystone ROLES the palette lacked — **`on-accent`** (a foreground legible *on* the accent fill — the missing piece behind white-on-accent contrast bugs) and **`focus-ring`**; (2) adds **`window.feedBack.theme`** — `get()` → `{id, isThemed, tokens}`, **`capabilities()`** → `{glow, gradients, motion}` (the device-affordance signal a feature reads to choose a glow vs. a solid device; recolor-only themes report defaults, a theme may opt out via a `capabilities` block in its payload, and `motion` is additionally reduced-motion-gated), and **`prefersReducedMotion()`** (one central matchMedia wrapper); and (3) emits a normalized **`theme:changed`** event (`{id, isThemed, tokens, capabilities}`) from the single `apply()` chokepoint. All additive + feature-detected (the apply side stays on `window.v3Theme`; the read surface is attached defensively so it survives the `feedBack` bus being (re)built by `capabilities.js` regardless of load order). First slice of the host theme contract (got-feedback/feedBack#644) — the framework fix so a plugin UI feature can't accidentally carve itself into a single theme; see `docs/host-theme-contract.md`. Verified by a headless render (apply/unequip intact, defaults present + restored, capability opt-out honored, event payload correct). Tests: `tests/js/v3_theme_read_api.test.js`.
+- **3D Keys Highway: audio-reactive background ambience + score effects (parity slice 4 — completes the keys side of the visual-parity epic).** The gradient sky behind the highway gains the guitar's **background ambience styles** — drifting **Particles**, pitch-class-colored pulsing **Stage lights**, wireframe **Geometric** shapes, or Off — driven by the shared audio-analyser bridge (stems-first on sloppaks, one-shot `#audio` fallback; bass/mid/treble bands, 5 ms cache) with an **Ambience intensity** slider and an **Audio-reactive** toggle. And the score talks back: a **score-FX overlay** canvas draws rising **“+1” pops** off each scored key, an **expanding ring every 10-combo tier**, **milestone bursts** at 25/50/100 streak, and a brief **red flicker** when a 3+ streak breaks (wrong notes and swept misses both count). All settings-gated and on by default (`keys3d_bg_*`), pooled, cleared when idle, torn down with the scene. Butterchurn/image/video remain out of scope. The `#audio` analyser tap is also **shared across visualizers** now (`window.__feedBackAudioTap` — whoever taps first publishes, everyone else adopts, `highway_3d` included), so switching between or splitting the guitar/drum/keys highways can't strand a permanently non-reactive backdrop, and the tap is never created before the page has user activation (a suspended AudioContext would silence live playback). Tests: bg-style id validation + FX defaults (30 total).
+- **3D Keys Highway: the anti-plastic pass — lacquered note gems, glossy piano-black keys, a studio environment, scene themes and a gradient sky (parity slice 3).** The note gems move to `MeshPhysicalMaterial` with a full **clearcoat** (roughness 0.32, clearcoat 1.0/0.18, envMapIntensity 0.9): a sharp lacquer highlight over the colored body instead of the old dead matte surface — glass, not plastic. What sells it is **image-based lighting**: the same procedural PMREM "studio" environment as the drum highway (dark room + cool overhead / warm+cool side light strips, no addon dependency) feeds `scene.environment`, so the **black keys finally read as glossy piano black** (roughness 0.55 → 0.22, envMapIntensity 1.3) with visible strip reflections, whites keep an ivory sheen (0.42/0.55), and the highway floor gets a stage sheen (roughness 0.9 → 0.55, metalness 0.15). The flat background becomes a **vertical gradient** (lighter above the horizon → theme color → darker toward the keyboard), and the guitar highway's **11 scene themes** arrive (same names/values — your look carries across instruments; `default` preserves the original keys palette; pitch-class note/key colors are never themed — themes own the scene, Synthesia colors own the notes). Plus **Cinematic lighting** (ambient 0.55/key 1.3, on by default) and a **Glow strength** slider multiplying the note glow, key approach-glow and the sustain consume-flash (0.5 = stock). All live-applying from the Graphics settings (`keys3d_bg_theme` + `keys3d_bg_*`); the PMREM target and gradient texture are disposed with the scene. Tests: theme-table id parity + default-look preservation + fallbacks (28 total).
+- **3D Drum Highway: audio-reactive background ambience + score effects (parity slice 4 — completes the drum side of the visual-parity epic).** The empty fog band behind the kit gains the guitar highway's **background ambience styles**: drifting **Particles**, palette-colored pulsing **Stage lights**, and slowly-tumbling wireframe **Geometric** shapes (plus Off) — driven by the same audio-analyser bridge the guitar uses (prefers the stems plugin's per-song analyser on sloppaks, falls back to a one-shot `#audio` tap; bass/mid/treble bands with a 5 ms cache), with an **Ambience intensity** slider and an **Audio-reactive** toggle (off = the styles animate on time only; a permanently-tapped `#audio` in a mixed split degrades the same way). The guitar's butterchurn/image/video styles are deliberately out of scope (vendored megabytes / upload plumbing; the style enum is extensible). And your combo finally talks back: a **score-FX overlay** (2D canvas over the WebGL scene, guitar `drawScoreFx` adapted to this plugin's internal scoring) draws rising **“+1” pops** off each scored lane, an **expanding ring pulse every 10-combo tier**, **milestone particle bursts** at 25/50/100 streak, and a brief **red flicker** when a 3+ streak breaks. Everything is settings-gated (Background ambience dropdown + intensity + reactive, Score effects toggle — all on by default, live-applying, `drum_h3d_bg_*` keys), pooled (zero per-frame allocation), and torn down with the scene across kit changes. Tests: bg-style id validation + FX defaults (15 total).
+- **3D Drum Highway: real materials + scene themes (parity slice 3).** The scene gets **image-based lighting**: a procedural PMREM "studio" environment (dark room + three emissive light strips — cool overhead key, warm/cool side fills; no vendored-addon dependency) feeds `scene.environment`, so the cymbals' metalness **finally reads as metal** (retuned to roughness 0.2 / metalness 0.85 / envMapIntensity 1.2 — the old 0.7-metalness look was matte because there was nothing to reflect), drumheads get a satin sheen, and the floor (roughness 0.95 → 0.7) catches the strips without turning into a mirror. **Scene themes arrive** — the same 11 theme names as the guitar highway (Midnight, Charcoal, Deep Purple, Forest, Warm Slate, Deep Focus, Deep Sea, Cathode, Cathode Green, Hearth) retint the background/fog, floor and lane stripes so your look carries across instruments; `default` preserves the original drum palette byte-for-byte, and piece colours stay with the existing Palette picker (themes own the scene, palettes own the kit). Plus **Cinematic lighting** (dimmer ambient / stronger key, on by default), a **Glow strength** slider (0–1, 0.5 = stock) multiplying every emissive base — notes, hit line, snare wires — and a **Lane vibrancy** slider driving stripe/halo/ghost-ring strength (the hit-FX approach highlight stacks on top). Everything applies live from the plugin settings (`drum_h3d_bg_theme` + `drum_h3d_bg_*` keys); the PMREM render target is rebuilt across kit-change renderer recreation and disposed in both teardown paths — and the floor/hit-bar geometry+materials that previously leaked on every kit change are now tracked and disposed too. Tests: theme-table parity with the guitar ids + default-look preservation + fallbacks (13 total).
+- **3D Drum Highway: hit FX — sparks, timing-colored lane flashes, kick camera pulse, approach glow, and open hi-hat notation (parity slice 2).** Striking a pad now *feels* struck: a pooled additive **spark burst** fires at the lane (ported from the guitar highway's Points-cloud system, pool 160), colored by **timing** — on-time green, early cyan, late amber (same `_timingHex` vocabulary as `highway_3d`, classified against the ±50 ms hit window with the inner 40% reading as on-time); with **Streak feedback** on, bursts grow with your combo. The **lane flash** feedback that was removed when note-recoloring landed is resurrected properly: pooled additive quads with a soft gaussian falloff light up the struck lane at the hit line (timing-colored; red for wrong-pad hits), and a **kick** hit fires triple amber bursts across the bar plus a subtle **camera dip + amber floor wash** that decays exponentially. Lanes also glow ahead of time: each stripe brightens as its next note approaches the hit line, so the eye is led to where the next hit lands. **Open hi-hat finally renders distinctly** — `hh_open` chart hits get a thin warm ring around the cymbal gem (standard notation's "o"), closing the long-standing TODO; the flag is orthogonal to accents/ghosts/flams so combined cues stack. All of it is settings-gated (Graphics → Hit sparks / Timing colours / Streak feedback / a 0–1 **Hit feedback intensity** slider driving flashes, approach glow and the kick pulse; everything on by default, `drum_h3d_bg_*` keys, live-applying) and GPU-frugal: every new visual is pooled or shares geometry/materials — zero per-note allocation on top of the per-frame notes rebuild, all registered in both dispose paths (kit-change renderer recreation included). Tests: timing-classifier boundaries + FX defaults added to `plugins/drum_highway_3d/tests/data_layer.test.js` (10 total).
+- **3D Keys Highway: hit FX — vibrant note gems, timing-colored sparks, and a hit-line that reacts to your playing (parity slice 2).** The washed-out note look is gone: gem opacity is now driven by a **Note vibrancy** slider (default 0.85 → opacity 0.92, up from a fixed 0.8; lane guides scale with it too, live-applying without a chart rebuild) and the resting emissive glow rises 0.08 → 0.22, so the falling notes finally read saturated against the dark floor. Scored key presses fire a pooled additive **spark burst** at the struck key (guitar-highway port, pool 96) **colored by timing** — on-time green, early cyan, late amber, classified against the ±100 ms window with the inner 40% reading as on-time (the timing delta is recovered from the matched note's key, so `judgeHit`'s tested contract is untouched); the per-pitch-class flame sprite keeps its identity color so pitch and timing stay separate signals. With **Streak feedback** on, bursts grow with the combo. The **hit line kicks brighter** for a beat on every scored press (exponential decay, scaled by a 0–1 **Hit feedback intensity** slider). All new controls live in the plugin's Graphics settings (on by default, `keys3d_bg_*` keys, live-applying), and the spark pool is disposed with the scene like every other GPU resource. Tests: timing-classifier boundaries, the noteKey time round-trip that the delta recovery relies on, and the new FX defaults (26 total).
+- **3D Drum Highway: bloom glow + adaptive-resolution support — the first slice of visual parity with the guitar highway.** The drum highway now renders through the same post-processing path as `highway_3d`: an `UnrealBloomPass` (strength 0.65, radius 0.5, threshold 0.82 — high, so only emissive/bright surfaces bleed) on a multisampled HalfFloat target with ACES filmic tone mapping, so the white hit-line bar and proximity-lit notes get a real glow instead of a flat emissive tint. **On by default**, with a new **Graphics → "Glow (bloom)"** toggle in the plugin settings (`drum_h3d_bg_bloom`, applies live, no reload); if the vendored postprocessing addons can't load (older self-hosted core), the plugin silently falls back to the direct render path. The plugin also now honors the host's **adaptive render scale** (`bundle.renderScale` — the Quality/"Min res" controls that the guitar highway already respected), multiplying it into the device pixel ratio, and caps DPR at 1.25 when more than one viz instance is live (splitscreen) so two panels don't double the GPU fill cost. Groundwork for the rest of the parity series: an FX-settings scaffold (`FX_DEFAULTS`/`readFxSettings`/`window.drumH3dSetFx`, `drum_h3d_bg_*` localStorage keys) that the sparks/themes/backgrounds PRs extend, plus a first node test suite for the plugin (`plugins/drum_highway_3d/tests/data_layer.test.js` — vm-loaded like the keys plugin's, covering the hit-variant precedence, the Auto-mode steal-guard predicate, and FX defaults; 8 tests, runs in CI via the `plugins/*/tests/*.test.js` glob).
+- **3D Keys Highway: sharp HiDPI rendering, bloom glow, a live combo HUD, and a graphics settings panel — the first slice of visual parity with the guitar highway.** The biggest single fix is resolution: the plugin never called `setPixelRatio`, so on HiDPI/retina displays (and Windows display scaling) it rendered at CSS resolution and was upscaled — soft and aliased. It now multiplies the device pixel ratio (capped at 2, or 1.25 when two viz panels are live in splitscreen) with the host's **adaptive render scale** (`bundle.renderScale`, the Quality/"Min res" controls), exactly like `highway_3d`. On top of that: the same **bloom** post-processing path as the guitar highway (UnrealBloomPass 0.65/0.5/0.82 on a multisampled HalfFloat target + ACES tone mapping — the cyan hit-line, hit flames and the sustain "consume" glow finally bleed light instead of reading flat), **on by default** with a graceful direct-render fallback when the vendored addons can't load. The plugin gains its first **settings panel** (`settings.html`, Settings → graphics category, `"settings"` block in plugin.json) with a live-applying "Glow (bloom)" toggle (`keys3d_bg_bloom`), plus the FX scaffold (`FX_DEFAULTS`/`readFxSettings`/`window.keys3dSetFx`, `keys3d_bg_*` keys) the later parity PRs extend. And the score state the plugin was already tracking is finally visible: a **combo / accuracy / best-streak HUD** overlay (drum-highway pattern), shown only while a MIDI keyboard session is wired so it never renders a frozen 0× combo. Tests: `plugins/keys_highway_3d/tests/fx_settings.test.js` (defaults, localStorage overrides + type coercion, setter persist/dispatch/unknown-key guard; 3 tests alongside the existing 20).
+- **The 3D Drum Highway and 3D Keys Highway are now bundled core plugins** (`plugins/drum_highway_3d/`, `plugins/keys_highway_3d/`), imported from their former standalone repos (`feedBack-plugin-drum-highway-3d`, `feedBack-plugin-keys-highway-3d`, now archived) via `git subtree` so their history is preserved. They join the other in-tree plugins-as-plugins: the loader treats them identically to user-installed ones, both are marked `"bundled": true` in their manifests, and `.gitignore` gains the matching `!plugins/<id>/` exceptions. This puts all three 3D highways (guitar, drums, keys) in one repo ahead of a visual-parity pass that ports the guitar highway's polish (bloom, sparks, themes, reactive backgrounds) to the other two — shared helper code and theme tables can now be reviewed and kept in sync in a single place. The keys plugin's existing node test suite is wired into CI (the JS test step gains a `plugins/*/tests/*.test.js` glob, +20 tests), and `static/tailwind.min.css` is regenerated since the core Tailwind build scans `plugins/**`. One deliberate behavior change ships with the bundling: the drum highway's Auto-mode predicate is **narrowed** (it used to claim any pack with `has_drum_tab` — a pack-level flag — which, now that the plugin ships to everyone and sorts before `highway_3d` in first-match-wins Auto order, would have stolen full-band packs from the guitar highway even on Lead/Bass arrangements; it now claims only drum arrangements, or packs nothing more specific can render). Picking the drum highway manually from the viz picker is unchanged.
+- **The tuner now tracks what tuning your instrument is *actually* in, so it prompts you to retune in BOTH directions — down to a song's tuning, and back up when the next song needs it.** The coverage check used to compare each song against your fixed instrument-profile tuning, so it only ever prompted you *away* from "home" (e.g. E → Drop C#) and stayed silent coming back (Drop C# → E), even though you'd physically retuned. It now reads the host's live **per-instrument working tuning** (`window.feedBack.workingTuning`) — what your selected instrument is currently in — so coverage is measured against your *actual* tuning and fires both ways. When you clear an auto-opened tuner, the tuner publishes that song's tuning as your instrument's live working tuning (`assumed` — an explicit "I tuned / Skip" refines it in a later PR), so the next song is judged against where you now are. **Per-instrument** — your guitar's and bass's tunings are tracked separately (keyed like the selector), so switching instruments uses the right one. Feature-detected: on a host without the working-tuning capability it falls back to the static `/api/settings` tuning (today's behavior). `plugins/tuner/screen.js` (`_playerTuning` reads `workingTuning` keyed by the selected instrument; `_publishWorkingTuning` writes on clear). Builds on the host `workingTuning` foundation (PR 1 of the series) + the instrument→chart routing (PR 2). Tests: `tests/js/tuner_auto_open.test.js` (both-directions coverage via a live Drop-D working tuning; publish-on-clear targets the right instrument slot) — 29 pass.
+- **`.jsonc` support for feedpak data files** (feedpak-spec §8, FEP #3 / PR #13). Hand-edited packs may now use the `.jsonc` extension (JSON with C-style `//` line and `/* */` block comments) for any data file the manifest points at — arrangements, notation sidecars, `drum_tab`, `song_timeline`, `lyrics`, and `keys`. New shared `lib/jsonc.py` provides `parse_jsonc(text)` + `load_json(path)` (auto-detects `.jsonc` by suffix, string-aware so comment-like text inside JSON string values is preserved) and is now used by every reader in `lib/sloppak.py` (six side-file sites) and `scripts/lift_keys_notation.py` (three arrangement / song_timeline read sites). The strip regex mirrors the reference validator in `feedpak-spec/tools/validate.py`. This is an additive (MINOR) change: `.jsonc` is opt-in, so any pack that keeps its data files as `.json` is unaffected and needs no regeneration. Note that a `.jsonc` file containing real comments only loads on a reader that implements §8 — a pre-this-change reader calls bare `json.loads` and fails on the comments rather than ignoring them, so don't hand out `.jsonc` packs to older hosts. Tests: `tests/test_sloppak_jsonc_load.py` (covers all six side-file types, the lift helper, and the string-boundary preservation rule end-to-end).
+- **The highway now loads the part that matches your selected instrument — a bass player gets the Bass arrangement, not the default Lead/guitar chart.** When you open a song without an explicit arrangement, the WebSocket handler (`server.py` `highway_ws`) reads your selected `instrument` from `config.json` (the same file it already reads for your default-arrangement preference) and routes to the matching part: **bass → the Bass arrangement**; guitar — and any unknown/future instrument (drums, keys) — falls through to the existing preference/most-notes default, which already lands on a guitar part. Previously the instrument selector only fed the tuner, so a bass player was handed a guitar chart (and a tune/coverage check then compared a 4-string bass against a 6-string part). An **explicit arrangement request always wins** (a manual arrangement switch is untouched), and a bass player's saved default-arrangement preference is still honored **within** the bass parts (so a preferred `Bass 2` / `Alt. Bass` wins over the canonical Bass), so this only changes the *default* part chosen on load. Server-only — every launch path already flows through the WS, so there's no client change. This is the instrument↔chart-routing piece the working-tuning series leans on (otherwise coverage compares across instruments). Tests: `tests/test_highway_ws_instrument_routing.py` (bass→Bass, bass-honors-pref, bass-no-bass-part→guitar, guitar→default, explicit-wins).
+- **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`.
+- **The settings backup now includes your library database + custom art — your scores, favorites, playlists, and play history are no longer the one thing a backup can't save.** `GET /api/settings/export` gains an additive `core_server_files` section carrying a **consistent snapshot of `web_library.db`** (taken via the SQLite online-backup API, so it's a complete single file even while the server is running) plus any custom **playlist covers** and **avatar** (`CONFIG_DIR/playlist_covers/`, `CONFIG_DIR/avatars/`). On `POST /api/settings/import` the database is **staged** to `web_library.db.restore` rather than written over the live, open DB; it's swapped in at the next startup (`_apply_pending_db_restore`, before the connection opens), which also clears the old WAL sidecars so a stale `-wal` can't be replayed onto the restored file — the import response sets `restart_required: true` and warns accordingly. Custom art is written immediately. The bundle stays backward-compatible (older servers ignore the new section). Came out of the library design charrette (dev-ops lens's top "protect irreplaceable data" pick, got-feedback/feedBack#636). _Known gap:_ custom uploaded **song** art is still commingled with the rebuildable thumbnail cache in `art_cache/`, so it isn't bundled yet (a tracked follow-up). Tests: `tests/test_settings_export_library_db.py` (snapshot consistency, staged-not-live restore, sidecar clearing, traversal rejection, full round-trip).
+- **A persisted wishlist — keep a list of songs you want but don't own yet.** New `wanted` table + `GET`/`POST`/`DELETE /api/wanted` give FeedBack the *arr-style "Wanted/Monitored" primitive it was missing: an entry is a *not-owned* song (artist/title/source/source_ref/note), so it lives in its own table rather than the playlist subsystem (which references owned local files). The API is idempotent on identity (case-insensitive artist+title, plus source+source_ref), so a producer — the `find_more` ownership-diff, or a manual add — can re-post without duplicating. Newest-first. Backend primitive for the charrette's wishlist finding (got-feedback/feedBack#636 item 4); the consuming UI lives in the producing plugin. Tests: `tests/test_wanted_api.py`.
+- **Practice-aware library home — a "Repertoire" meter + a "Keep practicing" shelf on the v3 Songs page.** The library opened cold into a flat sorted grid; now the unfiltered grid front door leads with two practice-aware surfaces built entirely from data already on hand (no new endpoints or stored state). A **Repertoire meter** shows how much of your library you can actually play — *"Repertoire: 12 of 80 songs · 7 in progress"* with a progress bar — counting songs at or above the same mastery threshold the green accuracy badge uses (≥ 90% best accuracy) over the unfiltered library total. A **"Keep practicing" shelf** is a horizontal row of your recently-played-but-not-yet-mastered songs (newest first, click to play) — the practice-accuracy-driven "continue" rail a media server can't do. Both reuse `/api/stats/best` (already loaded for the card badges) + `/api/stats/recent`; they show **only** on the grid view when you aren't searching/filtering/selecting, refresh after a song is scored, and collapse to nothing on an empty library. Soft-gamification only — descriptive encouragement (goal-gradient / endowed-progress), never content-gating, decay, or nagging. Frontend-only: `static/v3/songs.js` (`renderLibraryHome`/`_repertoireCounts`), `static/v3/v3.css`. Came out of the library design charrette (the UX + gamification lenses' top pick). Tests: `tests/js/v3_keep_practicing.test.js`.
+- **A–Z fast-scroll rail on the v3 Songs grid.** A vertical letter rail (Plex/Radarr/iOS-contacts pattern) pinned to the right edge next to the scrollbar lets you jump the library to a starting letter — tap a letter, drag to scrub with a live letter bubble, or arrow-key between letters. It shows **only** for the grid view + alphabetical (artist/title) sorts, and only offers letters actually present in the current sort **and filter set**, so a tap always lands on a real card (absent letters are dimmed + non-interactive). Because the grid is forward-only, server-paged infinite scroll, a jump pages through to the target card and scrolls to it (a newer jump supersedes an in-flight one); a keyset-seek + virtualized window is the noted scaling follow-up for very large libraries. Backend: `/api/library/stats` now accepts `sort` and returns an additive `sort_letters` map (songs-per-first-letter of the active sort column — artist or title), filter-synced; the legacy `letters` (distinct-artist) field is unchanged for the dashboard + classic tree. Frontend: `static/v3/songs.js` (`refreshRail`/`jumpToLetter`, cards tagged with `data-letter`), `static/v3/v3.css` (`.v3-azrail`). The classic (v2) tree already had letter selection; this brings the new grid to parity. Tests: `tests/test_library_filters.py` (sort_letters artist/title + song-vs-artist counting), `tests/test_library_providers.py` (sort forwarded to providers), `tests/js/v3_az_rail.test.js`.
+- **Playlists get content-dependent covers + custom art.** Playlist cards were a tiny `🎵` emoji on an empty square. Now a playlist's cover reflects its contents: **empty → the icon**, **a few songs → the first song's album art**, **4+ songs → a 2×2 art mosaic**. You can also **upload a custom cover** (a "Cover" button in the playlist detail view → image picker; "Remove cover" reverts to the content view). `MetadataDB.list_playlists()` now returns each playlist's first few song `art_urls`; `GET /api/playlists` and `GET /api/playlists/{id}` add `cover_url` when a custom cover exists. New routes `POST` / `GET` / `DELETE /api/playlists/{id}/cover` store a small PNG thumbnail under `CONFIG_DIR/playlist_covers/` (PIL-converted, like song-art upload); the cover is removed with the playlist. Frontend: `playlistCoverHtml(p)` in `static/v3/playlists.js`. Tests: `tests/test_playlists_api.py` (art_urls + cover roundtrip / reject-non-image / delete-cleanup), `tests/js/v3_playlist_cover.test.js`.
+- **v3 Songs: "Add to playlist" is now on each song's ⋮ "More" menu.** Previously a song could only be added to a playlist through select-mode (the checkbox → batch bar). The per-card overflow menu now has an **Add to playlist** row that targets that one song, reusing the same picker (choose a listed number or type a new name to create it). The select-mode batch flow and the single-song menu now share one extracted `addFilenamesToPlaylist(filenames)` helper in `static/v3/songs.js` (both grid and tree rows, since they share `openCardMenu`). Tests: `tests/js/v3_add_to_playlist_menu.test.js`.
+- **Resume where you left off — leaving a song now snapshots your place so an exit is recoverable, not a restart-from-zero.** Exiting the player (`showScreen()` teardown, before audio unload) writes `{song, arrangement, position, speed}` to `localStorage` (`feedBack.resumeSession`), and a non-blocking **"Resume practice"** pill offers it back on the next non-player screen (and on the next app launch). Clicking Resume re-enters the song, restores the arrangement + playback speed, and seeks to the saved position via the existing `_audioSeek` funnel; `playSong()` gains a `{ resume: {position, speed} }` option that arms a `song:ready`-consumed restore instead of the normal autostart, so the two never fight over playback. The snapshot is deliberately conservative — ignored for a song you barely started (< 3s) or had basically finished (within 5s of the end), cleared on natural song-end and once consumed, and expired after 24h. The pill is self-contained (inline-styled, body-appended, works identically in the classic and v3 shells with no Tailwind rebuild), never blocks, and a dismiss forgets the current snapshot for the session. This pairs with the Escape focus fix: now that Escape reliably leaves regardless of focus, an *accidental* exit is one tap to undo. Public surface: `window.resumeLastSession()` / `window.feedBack.resumeLastSession`. (The broader nav-state work — returning to a song after wandering into Settings → Tone Builder — is a separate, larger track; this lands the player-session slice.) Tests: `tests/browser/resume-session.spec.ts` (snapshot guards, staleness, pill show/hide/dismiss, resume consumption).
+- **Optional "Ask before leaving a song" confirm (Gameplay tab, default OFF).** A new client-only toggle (`confirmExitSong` in `localStorage`, in the v3 Gameplay settings + the Gameplay "Reset" set) for players who want a guard against an accidental exit. **Off by default — Escape leaves instantly, zero change for everyone else.** When on, a *user-initiated* exit (the player-scope Escape shortcut, or the player's ✕) opens a small true-modal confirm instead of leaving; auto-exit on song-end and a results screen's own Close are unaffected (they call `closeCurrentSong()` directly, which stays the unguarded actual-exit). The confirm honors the team's refined asks: **opening it pauses the song** (so it isn't running or being scored behind the prompt) and **Stay resumes exactly what was paused**; **Escape = Stay** — the dialog's capture-phase handler *dismisses* it (now consistent with every other modal and the generic `_confirmDialog`'s Esc=cancel), so a second Escape returns you to the (resumed) song rather than leaving; **Space/Enter (or click) Leave** by natively activating the default-focused "Leave" button ("just get me out"). Pause/resume run through the canonical `togglePlay()` path (HTML5 + `_juceMode`), guarded so a count-in, an already-paused song, or a teardown/seek/end behind the modal can't mis-resume. It's a real modal (`role="dialog" aria-modal="true"` / `.feedBack-modal`) with **Tab trapped inside it** and a **backdrop click that also Stays**, so the Escape/Space focus carve-outs treat it as a trap and don't fire player-back / play-pause behind it. The player Escape shortcut and the v3 ✕ route through a shared `window.requestExitSong()` gate (the ✕ also becomes origin-aware, matching Escape). Tests: `tests/browser/exit-confirm.spec.ts` (default-off instant exit, confirm-on opens + stays, second-Escape stays, backdrop stays, Stay/Leave, Enter-leaves); the audio pause/resume is verified manually on web + desktop (the mock song has no backing track).
+- **Folder Library — a bundled core plugin (`plugins/folder_library/`) that browses the DLC library by its on-disk folder tree.** Surfaces top-level folders → subfolders → songs (root-level songs land in `(Unsorted)`), with in-app folder management (create / rename / delete nested folders), song moves via dialog or drag-and-drop, and sort/filter that mirrors the host library's filter state. Wired into both the classic (v2) library toolbar and the v3 Songs page as a third **Folders** view alongside grid/tree; the plugin's `screen.js` is loaded once by the host and reused (idempotent IIFEs). Supersedes the former standalone "Folder Organizer" community plugin (removed from the README list). Backend (`routes.py`) registers `/api/plugins/folder_library/{tree,folder/create,folder/rename,folder/delete,song/move}`; **all filesystem mutations are confined to `DLC_DIR` and validated against path traversal** (per-segment name validation plus a resolved-containment check on `song/move`), and folder deletion relocates every song — de-duplicating colliding names — so a name clash never destroys a song. A two-level cache keeps re-opening folders fast. Tests: `tests/plugins/folder_library/test_routes.py` (path-safety helpers + move-traversal and delete-no-data-loss end-to-end).
+- **Full-screen (immersive) plugin screens — opt-in via `"fullscreen": true` in `plugin.json`.** DAW-style plugin UIs (e.g. a practice studio) need the whole viewport, not a scrolling content page below the topbar — embedded in the v3 shell they get cut off at the bottom with dead space up top. A plugin can now declare a top-level `"fullscreen": true`; `plugins/__init__.py` surfaces it as the `fullscreen` boolean on `/api/plugins` (mirroring the `settings_category` plumbing). When such a plugin's screen is active, `static/v3/shell.js` toggles `html.fb-immersive` from `syncActive()` (so it tracks every navigation incl. deep-link), and `static/v3/v3.css` hides the topbar, collapses the sidebar to a functional **icon rail** (kept reachable — Escape is bound only on player/settings scopes, so a fully-hidden sidebar would trap the user), and lets the active plugin screen fill `#v3-main`. Mirrors the existing `ss-follower-pre` chrome-hide pattern. Additive + opt-in: plugins without the flag are unaffected. Tests: `tests/test_plugins.py::test_fullscreen_flag_parsed_from_manifest`.
+- **Achievements wall sync — background drain worker (epic PR3, client side).** The bundled `achievements` plugin gains a dead-letter sync worker that POSTs queued Feat unlocks (and removals) to the hosted **feedback-achievements** wall service (separate repo). Idle unless a wall URL is configured (`FEEDBACK_ACHIEVEMENTS_WALL_URL`); uses `requests` with the baked-in client-token header, mirroring `lib/lyrics_transcribe`'s outbound pattern (explicit timeout, no raise on non-2xx). **Dead-letter, never drop** (pure `engine.drain_decision`): network error / `429` / `5xx` → keep `pending` (retry); other `4xx` → `dead_letter` (diagnosable, replayable); `2xx` → delete on server ack. A row leaves the queue only on ack or a user opt-out. `remove-me` now enqueues a wall removal keyed by the reused `player_hash`. Verified by an end-to-end staging round-trip (earn a Feat → drains onto the wall with name + short hash → `remove-me` → wall empties) with **no IP** in tables or access logs. Tests: `tests/plugins/achievements/test_sync.py` (decision table + ack/retry/dead-letter retention + four-field payload on the wire). The hosted service itself (FastAPI + SQLite-on-disk, Feats-only, hidden-until-first-global-unlock, profanity filter, in-memory rate limit, Render blueprint, migration tool) lives in the new `feedback-achievements` repo.
+- **Achievements wall — opt-in, privacy controls & data-minimization gate (epic PR2).** Sharing earned **Feats** on the (forthcoming) public wall is strictly opt-in. A new **onboarding step** (`static/v3/profile.js`, inserted after song-directory / before instrument paths — the wizard is now five steps) presents a plain-language card: it publishes only your display name and the Feats you earn, never songs/skills/scores, and is **off by default**. The bundled plugin's Settings panel (`plugins/achievements/settings.html`, mounted under the **System** tab via `settings.category`) carries the same toggle plus a **"Remove me from the wall"** button (`POST /api/plugins/achievements/remove-me` — wipes local synced state offline + enqueues a wall removal). Core adds `achievements_enabled` (bool, default `false`) to `_default_settings()` + the `/api/settings` validation block + `_RESETTABLE_SETTINGS_KEYS` in `server.py`, mirrored to `localStorage` in `app.js loadSettings()`. **Data-minimization contract (binding, code-enforced):** every outbound payload is built by a single explicit-dict serializer (`engine.build_wall_payload`, never `dict(row)`/`**model`) whose key-set is **exactly** `{display_name, player_hash, achievement_id, unlocked_at}` with `achievement_id` always a **Feat** id — a unit test asserts the four-field set and goes red on a fifth. Enqueue is doubly gated: it happens only when opted-in **and** a profile identity (name + the reused `player_hash`) exists; **competency unlocks never enqueue** (integration law). Tests: `tests/plugins/achievements/test_datamin.py` (key-set, opt-out/identity/competency gating) + `tests/test_settings_api.py` (flag persists/validates/resettable).
+- **Achievements & Feats of Power — local engine + tabbed Profile (epic PR1).** The Profile screen (`static/v3/profile.js`) becomes **tabbed** exactly like the v3 Settings page (`.fb-tabbar` / `.fb-tab[data-tab]` / `.fb-tabpanel[data-tab]`, active-tab persisted in `localStorage 'v3-profile-tab'`): a **Profile** (main) tab carrying the existing header + best-scores cards plus a new **Feats of Power** trophy shelf mount (`#v3-profile-feats-slot`, earned-only / hidden-until-earned), and an **Achievements** tab with a plugin mount (`#v3-profile-achievements-mount`) + `[data-empty-for]` empty note. Core dispatches a new **`v3:profile-rendered`** event after every render (mirrors `v3:settings-rendered`) so the plugin re-injects on each profile entry. A new bundled **`plugins/achievements/`** plugin owns the engine: SQLite under `<config_dir>/achievements/achievements.db` (`unlocks` / `counters` / `comp_ledger` / `sync_queue`), pure threshold/criterion math in the testable sibling `engine.py` (P-V), and routes under `/api/plugins/achievements/` (`activity`, `report-unlock`, `report-criterion`, `catalog`, `earned`, `feats`, `remove-me`). **Two surfaces, one engine, structurally separated (integration law):** **Feats** (activity/volume — Note Hunter, Marathon, Untouchable, Road Warrior, Time Served, Encore, two 🥚 secrets) read activity counters only, evaluated from a batched `song:ended` activity POST (notes only when **notedetect** is present — graceful degradation, no fake progress); **competency Achievements** (baseline: First Steps / Ascendant / Steady Hands / Renaissance + per-instrument Apprentice·Journeyman·Master / Personal Best / Challenger) are evaluated from **progression events only** and never re-derived from activity. The Achievements catalogue is always shown (locked = greyed), grouped by a secondary pill row over the **real progression paths** (Global / Guitar / Bass / Drums / Keys — auto-extends to new paths) with a per-category "X / Y earned" badge, defaulting to the player's primary path. Source plugins contribute their own competency defs and report unlocks through a versioned **`window.feedBack.achievements`** API (`register`/`registerAll`/`unlock`/`progress`), load-order-safe via the `window.__feedBackAchievementsPending` queue + an `achievements:ready` event (minigames pending-queue pattern); an absent source contributes nothing (no dead greyed rows). Opt-in publishing to a hosted Feats wall, the Settings privacy toggle, and the data-minimization gate land in epic PR2/PR3. Tests: `tests/plugins/achievements/test_engine.py` + `test_routes.py` (incl. the integration-law assertion that a competency unlock never reaches the Feats shelf).
+- **v3 settings page redesigned as a tabbed, card-row layout.** The single long scrolling settings screen becomes a horizontal tab bar (Gameplay / Audio / Graphics / Keybinds / Progression / Mic / Plugins / System) over card rows — each a leading icon + title + description with the control (toggle/dropdown/slider) on the right, plus a per-category "Reset" action. The markup lives in `static/v3/index.html` (so existing element ids keep hydrating through the unchanged `app.js` `loadSettings()`/`persistSetting()` path); a new `static/v3/settings.js` owns tab switching + active-tab persistence (`localStorage 'v3-settings-tab'`), the per-category reset, and a read-only **Keybinds** reference built from the live shortcut registry (`window.getAllShortcuts()`); styling is plain CSS in `static/v3/v3.css` (no Tailwind rebuild). **Plugins choose their settings tab** via a new optional `settings.category` field in `plugin.json` (`plugins/__init__.py` surfaces it as `settings_category`; `app.js` mounts each plugin's `<details>` panel into `#plugin-settings-<category>`, falling back to the generic Plugins tab) — `highway_3d` ships `category: "graphics"`; the out-of-repo notedetect/progression plugins should declare `"mic"` / `"progression"`. **New gameplay settings:** **Countdown before song** (a four-beat count-in before playback, wired end-to-end via the existing count-in engine + the song-start autostart path; key `countdown_before_song`, default off); **Miss penalty** (`miss_penalty`) and **Fail behavior** (`fail_behavior`) are persisted now but not yet consumed by scoring (shown with a "Not yet active" badge). "Note highway speed" surfaces the existing `master_difficulty` and stays in sync with the player-popover difficulty slider. New `POST /api/settings/reset` clears chosen keys back to defaults. Tests: `tests/test_settings_api.py` (new keys + reset), `tests/test_plugins.py::test_settings_category_parsed_from_manifest`, `tests/browser/settings-tabbed.spec.ts`.
+- **Full-mix audio exposed alongside stems for the stem mixer's auto-switch.** `lib/sloppak.py::load_song` now parses the optional manifest `original_audio:` key (the single pre-separation mixdown, e.g. `original/full.ogg`) into a new `LoadedSloppak.original_audio` field, with the same path-traversal guard and permissive "missing → disabled" posture as the `drum_tab` loader. The highway WS `song_info` frame additively carries three new fields next to `stems`: `original_audio_url` (served by the existing `/api/sloppak/{filename}/file/{rel_path}` endpoint, `None` when the pack ships stems only), `has_original_audio`, and `has_stems` (mirroring the `has_drum_tab`/`has_keys` flag convention). The stems plugin consumes `original_audio_url` to play the untouched single file while every stem slider is at unity and switch to the separate stems the moment one drops below 100%. **Migration notes:** the `song_info` message shape is a stable contract — these are purely additive; all existing fields are unchanged. `audio_url` still points at stem[0] when stems exist (it is only the degraded native fallback); the one behavioural change is that a stem-less, full-mix-only sloppak now sets `audio_url` to the full mix instead of emitting `audio_error`, so it plays natively.
 - **Autoplay & auto-exit — a global "click it, it plays; finish, you're back at the menu" option (default ON).** New single Settings toggle (`autoplayExit` in `localStorage`, surfaced in both the v3 and classic settings screens; absence of the key = enabled) that closes the friction at both ends of the play loop. **Autoplay:** `playSong()` previously loaded a chart paused, requiring a Play press; a one-shot flag armed per fresh load is now consumed by the next `song:ready` (highway.js) to auto-start via the existing `togglePlay()` path (HTML5 + `_juceMode` + count-in). Arrangement switches / seeks reuse the same `song:ready` event but never arm the flag, so they don't auto-restart. **Auto-exit:** on `song:ended`, core returns to the launching menu after a short grace delay — unless a visible full-screen results/dialog overlay is on top (detected via `[role=dialog][aria-modal]` / `.fixed.inset-0` with a `getClientRects()` visibility test that works for `position:fixed`), in which case the return is deferred so that score screen's own Close button (calling `window.closeCurrentSong()`) drives the exit. A plugin can also defer explicitly via the new `window.feedBack.holdAutoExit()` (called synchronously from its own `song:ended` handler — core's listener runs first). Both paths mean **no external plugin PR is required** for a results screen to be respected. **Context-aware destination:** the player's remembered origin (`_playerOriginScreen`) now honours any real launch screen instead of clamping to library/home/favorites, and a one-shot `window.feedBack.setReturnScreen(id)` override lets the lessons catalog (`static/v3/lessons.js`) send a finished lesson back to the lessons screen — not the song library — even though the external tutorials plugin owns the `playSong` call. Also exposes a read-only `window.feedBack.autoplayExit` getter for plugins. Songs and lessons share the same `playSong` → highway path, so both inherit the behaviour. Core-only (`static/app.js`, `static/v3/lessons.js`, both `index.html`s); the end-of-song score screen itself remains a plugin. Optional polish (not required — the overlay heuristic already covers it): external scoring/note-detection plugins (e.g. SlopScale) may call `holdAutoExit()` + `closeCurrentSong()` for an exact, heuristic-free handoff.
 - **"Song Editor" promoted to a first-class v3 sidebar item.** The editor
   plugin (`id: editor`) now gets its own dedicated sidebar entry — under the
@@ -29,6 +75,27 @@ 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.
+- **3D Highway FPS counter no longer hides behind the v3 "Up Next" pill.** The on-highway FPS readout (Settings → Graphics → 3D Highway → Show FPS counter) is pinned to the top-right of the highway overlay — the same corner the v3 player chrome stacks its persistent **Up Next** pill and live-performance HUD into, on a higher layer that paints over the canvas. So the readout sat *behind* that chrome and couldn't be read — precisely when a tester had turned it on to judge performance (it also made the separate "Up Next won't turn off" complaint worse, since the default-on pill covered the counter regardless). The counter now stays top-right but drops just **below** whichever of that chrome is showing: `highway_3d`'s `screen.js` measures the lowest visible top-right v3 HUD element (`#v3-upnext` / `#v3-live-performance-hud` / `#hud-time`) and floors the FPS box's Y beneath it. Element refs are resolved once and cached (no per-frame `querySelector`, per the plugin perf rules) and only consulted while the counter is actually drawn; gated on `window.feedBack.uiVersion === 'v3'` so the classic (v2) UI is byte-for-byte unaffected. `plugins/highway_3d/plugin.json` version → `3.30.1` (cache-buster). (For reading raw perf numbers unobstructed, the core perf HUD — `localStorage.highwayPerfHud='1'` — still renders above all chrome and additionally shows the adaptive render-scale.)
+- **3D Highway fret-number row no longer clips off the bottom edge when the camera zooms in on a centred span.** The heat-coloured fret-number row is drawn as a band *below* the board (`sY(lowest) − S_GAP*1.4`), but the camera's self-correcting framing only anchors the board **centre** to the lower third of the screen — it reserved no headroom for that row. So a tight zoom on a centred active span (worst around mid-neck; fine when the span sits at either end of the neck, which is why testers saw it "only when centered" and "not every song") dropped the numbers past the bottom edge. Tilt can't fix it there (it would only trade a bottom clip for a top clip), so `camUpdate()` now **dollies the camera back just enough to bring the row back into frame**: it projects the row band with the final camera and, when it falls below a safe NDC line (`FRET_ROW_FIT_NDC_MIN`), raises a capped, hysteretic `_fretRowFitBoost` applied to the `curDist` lerp target (the span-driven zoom still owns zooming *in*). The boost rises promptly (proportional to the deficit), relaxes lazily past a deadband, and is capped (`FRET_ROW_FIT_BOOST_MAX`, +60%) so the zoom can't pop or hunt; it cooperates with the tilt loop (pull-back shrinks the scene, tilt keeps the centre anchored) and yields entirely to the Camera Director free-cam. Surgical: passages where the row is already visible never trigger it, so framing is unchanged everywhere it already worked. `plugins/highway_3d/plugin.json` version → `3.30.2` (cache-buster). Tests: `tests/js/highway_3d_camera_framing.test.js` (guard constants, the boosted `curDist` lerp, the projected-row hysteresis, free-cam yield).
+- **v3 Songs grid now refreshes after a Settings rescan / DLC-folder change — no app restart needed.** On a fresh install, pointing at a DLC folder in Settings and running a scan left the Songs section empty until a restart (the scan *did* populate the library — `_background_scan` re-reads `config.json` fresh — but the v3 grid never reloaded). The Settings **Rescan / Full Rescan** handlers only refreshed the classic (v2) library via `loadLibrary()`; the v3 grid (`static/v3/songs.js`) had no listener for a scan it didn't start itself (only its own upload path self-refreshed via `watchUploadScan`), so its cached, pre-DLC (empty) DOM/snapshot survived a sidebar return until a full reload. The rescan handlers now emit a **`library:changed`** event (`static/app.js`); the v3 grid listens and **reloads if it's the active screen, else marks itself dirty** so the next entry does a full re-fetch instead of restoring the stale snapshot (a `_libraryDirty` short-circuit ahead of every cached-DOM fast-path in `onV3SongsScreenEnter`). Tests: `tests/js/v3_library_refresh.test.js` (the emit + the reload/dirty wiring).
+- **Edit Metadata modal: the Year is now editable.** You could set a year when authoring a pak but the Songs → Edit Metadata modal had no Year field, so it could never be changed afterward. The backend (`POST /api/song/<f>/meta`) already accepted and normalized `year` (writes it into the file via `songmeta`, survives a rescan) — only the UI omitted it. Added a **Year** input to `openEditModal()` (populated from the song's existing year) and included `year` in `saveEditModal()`'s POST body (`static/app.js`). Both the v3 card menu and the legacy edit button already pass the year through, so both surfaces get the field.
+- **Edit Metadata modal no longer closes when a click-drag is released on the backdrop.** Selecting text inside a field and releasing the mouse past the modal's edge dismissed the form without warning (the `click` event's target resolved to the backdrop), discarding the edit. Backdrop dismissal now requires the **mousedown to have started on the backdrop** too — tracked per-modal and decided by a new pure `_editModalShouldClose(clickTarget, modalEl, downOnBackdrop)` helper (`static/app.js`). Cancel / ✕ still close on a normal click. Tests: `tests/js/edit_metadata_modal.test.js` (year in the POST body + the backdrop-close decision table).
+- **Built-in diagnostic sloppak rebranded "Slopsmith" → "FeedBack" in the song name.** PR #586 renamed the file to `feedBack-diagnostic-basic-guitar.sloppak` but never regenerated the archive, so the manifest inside still carried `title: Slopsmith Diagnostic — Basic Guitar` / `artist: Slopsmith` (and the same heading in `DIAGNOSTIC.md`) — the stale name testers saw in the library/player and the onboarding calibration step, even though the build script, server, and docs all already say "FeedBack Diagnostic — Basic Guitar". Regenerated `docs/diagnostics/feedBack-diagnostic-basic-guitar.sloppak` from `docs/diagnostics/build_diagnostic_basic_guitar.py` so the committed artifact matches its source generator (title/artist/heading now "FeedBack"; chart, stem, and `diagnostic:` metadata unchanged). No code change — the rename in #586 just needed the rebuild.
+- **v3 song/lesson accuracy badges now refresh on the first return from a song — no restart needed.** PR #574 added a `stats:recorded` → in-place badge repaint, but the repaint never matched a card. The event (like `song:loading`) carries the filename **`encodeURIComponent`'d** — exactly as `playCard` hands it to `playSong` (the highway WS `decodeURIComponent`s it back) — whereas library cards key on the **decoded** `localFilename` (`data-fn`), and `/api/stats/best` is server-canonicalized to that same decoded key (`server.py` `_canonical_song_filename`). So `repaintAccuracy`'s `data-fn !== key` check rejected every card and `state.accuracy[encoded]` was `undefined`, leaving the just-earned badge stale until a full `render()` (app restart / search / re-enter the screen) — which is why it "came back after a restart." `static/v3/songs.js` now decodes the `stats:recorded` filename back into the card / `state.accuracy` key space via a small `decFn` helper before marking dirty and repainting (idempotent for already-decoded names; falls back to the original on malformed input so a real filename containing a literal `%` is never corrupted), so both the immediate repaint and the `onV3SongsScreenEnter` deferred path land on the right card. Tests: `tests/js/v3_songs_score_badge_refresh.test.js`.
+- **Escape now exits a song (and leaves Settings) even when a transport/rail control button holds keyboard focus.** Clicking a player control (Play / FF / RW / Restart) left that `<button>` focused, and `_shortcutDispatchBlocked()` in `static/app.js` treats any focused `INPUT/SELECT/TEXTAREA/BUTTON` as an "interactive control" and bails before the shortcut registry runs — so the player-scope `Escape → Back` shortcut never fired until the user clicked empty canvas to blur the control ("Escape in song not consistent"). Space already had a player-screen carve-out (#593) that let it fire through a focused control; Escape did not. Generalized that carve-out to Escape, scoped to the player **and** settings screens (both register an `Escape = Back` shortcut, and settings had the identical latent bug). The earlier guards are preserved and still win: text inputs are exempted first (Escape there clears/blurs the field), the Section Practice popover already claims Escape before the carve-out, and a true modal layered over the screen (`[role="dialog"][aria-modal="true"]` / `.feedBack-modal`) still traps Escape so it closes the modal rather than ejecting past it. Escape becomes a reliable, focus-independent "Back" — making it monotonic groundwork for an optional exit-confirm. Plugins that register a player-scope `Escape` shortcut benefit identically (they were broken the same way). Tests: `tests/browser/keyboard-shortcuts.spec.ts` (focused-button repro, text-input no-exit, no-escape-past-modal, Section Practice popover, settings twin-bug).
+- **The v3 "Up Next" pill can now be turned off — new "Show 'Up Next'" gameplay toggle (default ON).** The v0.3.0 player chrome's persistent upcoming-section pill (`#v3-upnext`, drawn by `static/v3/player-chrome.js`'s `updateUpNext()`) shipped with no off switch, so it always showed during playback whenever a section was upcoming — overlapping the top-right FPS HUD and ignoring the 3D-highway "Show 'Up Next' section card" checkbox (a *different*, in-canvas widget that was demoted to default-off precisely because this pill is the canonical readout). Users reading the pill as the same setting saw "disabled in settings but still there." Adds a real core toggle following the `autoplayExit` idiom: a client-only `showUpNext` `localStorage` pref (absence = enabled), a **Show "Up Next"** switch in the Gameplay settings tab (`static/v3/index.html`), reader/writer + `loadSettings()` hydration + a read-only `window.feedBack.showUpNext` getter in `static/app.js`, and a gate at the top of `updateUpNext()` that hides the pill when off. Disabling mid-playback hides it immediately; re-enabling re-shows it on the next chrome tick (~6 Hz). Added to `RESET_MAP.gameplay.local` in `static/v3/settings.js` so the Gameplay "Reset" restores the default-on state. Default ON = zero change for existing users. No Tailwind rebuild (plain markup + existing classes).
+- **v3 list/tree view brought to parity with the grid: select mode, parts chips, and song actions — plus a stale-CSS Docker fix.** Re-lands a previously-reverted change. **Frontend (`static/v3/songs.js`):** entering select mode no longer collapses the tree — `loadTree()` now captures the expanded artist groups (`details[open]` keyed by `data-artist`) before the "Loading…" wipe and restores them on rebuild, so toggling select mode (which re-renders via `reload()`) keeps groups open and selection usable; tree rows gain a display-only checkbox + selection ring, the same fav / save-for-later / overflow-menu cluster as the grid card (always shown, all bound by `wireCards()`), and a capture-phase select guard mirroring the grid so clicking a row or arrangement chip in select mode selects instead of playing (`<summary>` headers sit outside `[data-fn]`, so native expand/collapse is untouched). **Docker fix (`static/tailwind.min.css`):** the committed Tailwind stylesheet was stale — `.sm\:flex` (and the other utilities behind #582's `hidden sm:flex` arrangement chips and the new action cluster) were never compiled in, so they rendered `display:none` on the Docker build (which serves the committed CSS as-is; Desktop rebuilds from source so it looked fine). Regenerated with the pinned `tailwindcss@3.4.19` via `scripts/build-tailwind.sh` so Docker matches Desktop and #582's chips render on every Docker deploy. Regression tests: `tests/browser/v3-tree-select.spec.ts`.
+- **Space bar now plays/pauses on the player screen even when a sidebar nav link or rail button has focus.** When any `<button>` in the player rail (viz, audio, mixer, lyrics, plugins, advanced), a sidebar nav link, or a popover control held keyboard focus, pressing Space was swallowed by `_shortcutDispatchBlocked` → `_isInsideInteractiveControl` (which treats `BUTTON`/`A` as interactive), so the Space shortcut never reached the dispatcher and `togglePlay()` never ran. `_shortcutDispatchBlocked` (`static/app.js`) now extends the same carve-out already used for the Section Practice bar: while the player screen is active, Space is always routed through the shortcut system — the dispatcher calls `e.preventDefault()` before invoking the handler, so the focused element does not also activate. Text inputs (`_isTextInput`) remain exempted first, so typing space in a search/input field still works normally, and focus inside a true modal dialog (`role="dialog" aria-modal="true"` / `.feedBack-modal`) layered over the player is also exempted so Space reaches the modal's focused control (e.g. its Close button) instead of toggling playback behind it — non-modal player popovers/toasts (loop A/B, arrangement pin) stay covered. Regression tests in `tests/browser/keyboard-shortcuts.spec.ts` cover the focused-rail-button play/pause, the text-input exemption, and the modal-dialog exemption.
 - **A song's accuracy badge now updates on its library card right after you play it — no restart needed.** The v3 library (`static/v3/songs.js`) loaded the best-accuracy map (`/api/stats/best`) once into `state.accuracy` at render time and only ever refreshed it on a full re-render; the play→return flow takes the screen-entry fast-path that restores the cached grid DOM without re-fetching, so a just-earned score stayed invisible until the next restart re-ran `render()`. The `stats-recorder` now emits a `stats:recorded` event (carrying `filename`/`arrangement`) once the scored `POST /api/stats` resolves on the server — the correct moment, since `song:stop` fires before the POST completes. `songs.js` listens: if the library is the active screen it re-fetches `/api/stats/best` and patches the affected card/row badge in place; otherwise it marks the filename dirty and `onV3SongsScreenEnter` applies it on return (a failed fetch keeps the entry dirty to retry). Badge markup was factored into a shared `accuracyBadge(filename, variant)` (grid pill + tree-row percentage, both tagged `.fb-acc-badge`) so the in-place `repaintAccuracy` can find and replace them without a full list re-render (scroll/pagination preserved). The old empty `song:stop` "refresh lazily next render" placeholder is replaced.
 - **Changing Settings → 3D Highway → Fret spacing no longer ejects you to the home screen.** The `highway_3d` plugin's `h3dSetFretSpacing` was the lone 3D-highway setting that called `location.reload()` to apply — and since the SPA boots with `#home` as the active screen (`index.html` `.screen.active`), the reload dropped the user out of Settings onto the homescreen. It now applies live like every other 3D-highway setting: it rebinds the module-scope `_h3dFretUniform` flag (so panels mounted later this session pick up the new mode), recomputes the two `fretX`-derived scalars that were baked at init (`_fretLabelScaleRefW` for fret-label sprite scaling, `FRET_WIDTH_MID` for camera hysteresis), and broadcasts a `fretSpacing` change over the existing `_bgEmitChange` pub-sub so every mounted panel rebuilds its board via `buildBoard()`. Per-frame note geometry already reads `fretX` live and needs no rebuild. No page reload, so the Settings screen stays put. Source-level regression tests in `tests/js/highway_3d_fret_spacing.test.js` now pin the no-reload / live-rebuild behavior.
 - **v3 library scroll-restore no longer breaks the classic v2 UI or drops off-screen searches** (feedBack#857). Two regressions in the scroll-restore work above: (1) `playSong` remapped `home`-launched songs to return to the `#v3-songs` screen unconditionally, but `static/app.js` is shared with the v2 UI (served at `/v2` / `FEEDBACK_UI=v2`) where that screen does not exist — Esc-from-player then called `showScreen('v3-songs')`, which threw on the missing element and stranded the user on a blank screen with playback still running; the remap now applies only when `#v3-songs` is present. (2) The Songs screen-entry fast-path skips reloading to preserve scroll, but the global topbar search routed through it, so once Songs had been visited, searching from another screen navigated there without applying the new query; the screen now tracks the state hash each fetch reflects and refetches when it has drifted, keeping the scroll-preserving no-op only when nothing changed.
@@ -36,11 +103,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Screensaver no longer kicks in during windowed-mode playback** (#686). While a song is playing, `static/app.js` now holds a [Screen Wake Lock](https://developer.mozilla.org/en-US/docs/Web/API/Screen_Wake_Lock_API) (`navigator.wakeLock.request('screen')`) so the OS display/screensaver stays awake even though only audio + the highway animation are active and the keyboard/mouse are idle. The lock is acquired on `song:play`/`song:resume` and released on `song:pause`/`song:ended`/`song:stop` (kept only while actually playing), and re-acquired on `visibilitychange` when the tab refocuses (the API auto-releases a lock whenever the page is hidden). Both the HTML5 `<audio>` and JUCE desktop playback paths emit the same `song:*` events, so the fix covers both. In feedBack-desktop (Electron), where `navigator.wakeLock` is unreliable, it also drives a native `powerSaveBlocker` bridge via the optional `window.feedBackDesktop.power.setScreenAwake` hook when present; both calls degrade silently where unsupported. Note: the browser Wake Lock API is secure-context only, so in a plain browser this is active on `localhost` / HTTPS only — a session opened over plain HTTP to a LAN IP (e.g. `http://192.168.1.100:8000`) won't keep the screen awake; front it with HTTPS or use the desktop app (see README → reverse-proxy notes).
 
 ### Changed
-- **Practice plugin first-class sidebar slot now points at Virtuoso.** The bundled practice plugin was rebranded/re-homed from the SlopScale fork (`id: slopscale`) to `got-feedback/feedback-plugin-virtuoso` (`id: virtuoso`); the desktop bundle swap is feedBack-desktop#31. `static/v3/shell.js` still promoted `slopscale`, whose id no longer ships — so `renderPromotedNav()` (gated on the plugin appearing in `/api/plugins`) would have found no match and the dedicated sidebar slot would have gone dark, dropping Virtuoso to the generic Plugins gallery. Update the NAV entry + `PROMOTED_PLUGINS` slot `slopscale` → `virtuoso` (`screen: plugin-virtuoso`, label "Virtuoso - Practice", same FeedBarcade anchor + `target` icon) so the practice plugin keeps its first-class entry. Also clear the now-dead `slopscale` id from the Plugins-gallery curated category map (`static/v3/plugins-page.js`) and add `virtuoso: 'practice'` as a defensive fallback (the manifest's `category: "practice"` is authoritative, so it lands on the practice board regardless), and refresh the stale SlopScale references in `README.md` + `docs/plugin-capability-inventory.md`. Must land with the bundle swap or the practice plugin regresses in the UI.
+- **Practice plugin first-class sidebar slot now points at Virtuoso.** The bundled practice plugin was rebranded/re-homed from the SlopScale fork (`id: slopscale`) to `got-feedback/feedBack-plugin-virtuoso` (`id: virtuoso`); the desktop bundle swap is feedBack-desktop#31. `static/v3/shell.js` still promoted `slopscale`, whose id no longer ships — so `renderPromotedNav()` (gated on the plugin appearing in `/api/plugins`) would have found no match and the dedicated sidebar slot would have gone dark, dropping Virtuoso to the generic Plugins gallery. Update the NAV entry + `PROMOTED_PLUGINS` slot `slopscale` → `virtuoso` (`screen: plugin-virtuoso`, label "Virtuoso - Practice", same FeedBarcade anchor + `target` icon) so the practice plugin keeps its first-class entry. Also clear the now-dead `slopscale` id from the Plugins-gallery curated category map (`static/v3/plugins-page.js`) and add `virtuoso: 'practice'` as a defensive fallback (the manifest's `category: "practice"` is authoritative, so it lands on the practice board regardless), and refresh the stale SlopScale references in `README.md` + `docs/plugin-capability-inventory.md`. Must land with the bundle swap or the practice plugin regresses in the UI.
 - **3D highway: realistic curved metal frets.** The fret wires are now bowed `TubeGeometry` (the middle strings push away from the camera so the row of frets reads as wrapping a cylindrical neck — a depth cue) rendered with a lit `MeshStandardMaterial` instead of the old flat, straight `MeshBasicMaterial` boxes, so the scene's ambient + directional light glints across the rounded surface for a polished-steel look. The existing per-frame highlight is preserved unchanged: frets inside the active anchor still turn gold (`0xD8A636`), which under the metallic shading reads as brass. Metalness is kept moderate (0.4, not full-metal) because the scene has no envMap — a PBR full-metal surface would reflect black — with a dim emissive floor so frets stay legible down the fogged neck. Backported from the `highway_babylon` plugin's "hit-zone fret bars". All knobs (`FRET_BOW_DZ`, metalness/roughness/emissive) are tunable constants. `plugins/highway_3d` v3.25.0.
 - **3D highway: section + tone HUD cards now default OFF.** The v0.3.0 player chrome carries a persistent "Up Next" pill, making the in-canvas section card redundant by default (it doubled the readout, feedBack feedback); the tone HUD follows the same less-is-more default. Both remain available in Settings → 3D Highway (visibility/position/size unchanged); users who previously toggled either explicitly keep their stored preference — only the untouched default flips. `plugins/highway_3d` v3.24.1.
 - **Perf**: replace runtime Tailwind Play CDN with a prebuilt static stylesheet (`static/tailwind.min.css`). The Play CDN's runtime JIT scanned the DOM ~1.8x/sec on the main thread (~37 ms blocking spans), dropping ~26% of frames in long playback sessions with the 3D highway as default. Theme extensions (dark/accent/gold colors, Inter font) move to `tailwind.config.js`; regen via `bash scripts/build-tailwind.sh`. No runtime build step — the generated CSS is committed. Fixes feedBack-desktop#110.
 - **Perf**: reduce per-frame allocations in the 2D highway chord + lyric render paths. `_ensureChordRenderCache` now also caches `sortedNotes` / `nonZeroNotes` / `nonZeroFrets` / `allMuted` / `hasMultipleNotes` (computed once per chord, invalidated on `src` / `_inverted` / `chordTemplates` change — the third key catches a stale `isOpen`-derived classification when the WS `chord_templates` message lands after the final `chords` chunk), so `drawChords` no longer re-sorts / re-filters / spreads min-max per visible chord per frame. The in-chord unison bend classification is folded inline (no `chordPositions.filter` × 2 per frame). `drawLyrics` memoizes `ctx.measureText` results in a two-level `Map<fontSize, Map<text, width>>` so cache hits don't allocate a composite string key. Lit-sustain shimmer in `drawSustains` swaps the 4 per-note-per-frame `Math.random()` calls for a 64-entry precomputed jitter LUT (xorshift32-seeded — the LUT contents are reload-stable and test-reproducible; rendered shimmer is deterministic per `createHighway()` instance, since the seed includes that instance's `_frameIdx`) indexed by `(frameIdx + n.s + ⌊n.t·60⌋)`, visually indistinguishable and allocation-free.
+- **Perf**: the load-adaptive render scale (`_adaptRenderScale`, #654) no longer visibly hunts up/down on passages that hover near the frame budget (testers saw "quality going up and down" with the 3D highway). Downscaling stays prompt to protect the frame rate, but **upscaling is now lazy**: a smaller step (×1.06 vs ×1.1) on a longer cooldown (`_AUTO_UPSCALE_COOLDOWN_MS` 2500 ms vs the 600 ms adjust cooldown), reset on any downscale, and gated by a predictive guard — it only upscales when the projected cost *after* the step (≈ cost × step², since draw cost tracks the pixel count) still clears the high budget. The scale therefore settles just inside the 7–12 ms deadband instead of oscillating across it. No new public API; the `_autoScaleMin` "Min res" floor is unchanged.
+
+### Removed
+- **`c` library hotkey ("Convert to .sloppak") removed from core.** Core hardcoded a plugin-specific shortcut: a documentation-only `registerShortcut({ key: 'c', scope: 'library' })` no-op plus a `c → button.sloppak-convert-btn` entry in the library keydown handler that fired the Sloppak Converter plugin's button. Per the plugins-own-their-behavior principle, core no longer ships this hotkey — the convert button still works by click, and the Sloppak Converter plugin can register its own `c` shortcut via `window.registerShortcut()` if keyboard access is wanted. The `f` (favorite) and `e` (edit) library hotkeys, which drive core buttons, are unchanged. Help-modal/registry tests in `tests/browser/keyboard-shortcuts.spec.ts` updated to drop the `c` assertions.
 
 ### Added
 - **Player progression: Mastery Rank, instrument-path challenges, daily/weekly quests, Decibels currency, cosmetics shop (spec 010).** Onboarding gains two steps: pick one or more **instrument paths** (Guitar / Bass / Drums — data-driven, more can ship as content) and a **calibration challenge** offer (play the bundled FeedBack Diagnostic with note detection at 100% accuracy — or skip; either way you reach **Mastery Rank 1**, and a skipped calibration can still be completed later from the Progress screen). Each path levels by completing a content-defined number of **challenges** (any order) from that level's set; Mastery Rank = onboarding rank + the sum of path levels, starting at 0 on a fresh install. The existing unified XP backend is untouched but the frontend renames it to **Decibels (dB)** — a spendable currency earned ONLY by playing (songs, FeedBarcade rounds, quest rewards; no real-money path exists or may be added) — with spend tracked in a separate wallet so lifetime earnings stay monotonic. Rotating **daily/weekly quests** (deterministic per period, lazy instantiation, local-midnight / Monday resets) award dB and feed `quest_completed` challenges. A new **Progress** screen (rank hero, per-path checklists, quest countdowns, add-a-path) and **Shop** screen (themes via CSS-variable swaps under `html[data-fb-theme]`, avatar frames; atomic balance-checked purchases — 402 on insufficient dB, 409 on re-buy) join the v3 nav, and the topbar badge now shows Rank + challenge-set progress + dB balance. All definitions live in `data/progression/` JSON (paths/levels/challenges, quest pools, shop catalog) — adding a rank, challenge, quest, or cosmetic is a content edit + restart, never code; invalid content degrades to logged warnings. New tables (additive + idempotent): `progression_state`, `player_paths`, `challenge_progress`, `quest_state`, `wallet`, `shop_owned`, `shop_equipped`. New endpoints: `GET /api/progression`, `POST /api/progression/paths|onboarding|events` (events whitelists `minigame_run`; `song_completed` stays server-derived inside `POST /api/stats`, which now resolves the instrument server-side and reports an additive `progression` outcome key), `GET /api/shop`, `POST /api/shop/buy|equip`; equipped cosmetics ride along on `GET /api/profile`. A new **`progression` capability domain** (core-owned, kind: command, safety: safe — `inspect`, `record-event`, `list-shop`, `buy-item`/`equip-item` gated on user action) emits `challenge-completed`/`quest-completed`/`path-level-up`/`rank-changed`/`db-changed`/`calibration-completed`/`cosmetic-equipped`, mirrored as `progression:*` window events, with a redaction-safe diagnostics contributor; backend plugins get the symmetric `record_progression_event` context hook (the bundled minigames hub reports runs through it, guarded for standalone). Spec: `specs/010-progression-domain/`. Tests: `tests/test_progression.py`, `tests/test_progression_api.py`. **Migration notes:** existing XP totals carry over as lifetime dB (balance = lifetime − spent); resetting a per-source XP contribution (e.g. a minigames profile reset) after spending can clamp the spendable balance to 0 until new dB is earned; drums-path v1 content uses currently-satisfiable goals (arcade rounds, quests, any-instrument plays) until drums scoring lands.

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
@@ -530,7 +542,7 @@ cover.jpg              Album art (optional)
 lyrics.json            Syllable-level lyrics (optional)
 ```
 
-Sloppak is the preferred format for new features. The [Stems plugin](https://github.com/topkoa/feedBack-plugin-stems) provides live stem mixing for sloppak songs.
+Sloppak is the preferred format for new features. The [Stems plugin](https://github.com/topkoa/slopsmith-plugin-stems) provides live stem mixing for sloppak songs.
 
 **Full developer reference:** the authoritative format spec now lives in its own repo —
 [got-feedback/feedpak-spec](https://github.com/got-feedback/feedpak-spec)
@@ -552,6 +564,7 @@ a local pointer + code map.
 - **Storage** — `localStorage` for all user preferences
 - **Styling** — Tailwind CSS utility classes, dark theme (`bg-dark-600`, `text-gray-300`, accent `#4080e0`, gold `#e8c040`). Tailwind is served as a **prebuilt** stylesheet (`static/tailwind.min.css`, regenerated by `bash scripts/build-tailwind.sh`), **never** the runtime Play CDN — the CDN's on-the-fly JIT rescanned the DOM on the main thread and dropped ~26% of frames with the 3D highway (feedBack-desktop#110). The committed CSS only contains classes the build scanner saw, so CI (`tailwind-fresh`) rebuilds and diffs it; run the build script and commit when you add new classes. A plugin that uses classes not guaranteed in core (notably arbitrary values like `w-[37px]`) MUST ship its own compiled stylesheet via the `styles` manifest key, built with `corePlugins.preflight = false` (utilities only — core ships the one base reset). Plugins MUST NOT load the Tailwind Play CDN or any runtime CSS JIT. See constitution Principle II.
 - **Naming** — camelCase for JS functions, kebab-case for CSS classes, snake_case for plugin IDs
+- **Text selection (v3)** — the v3 UI defaults to `user-select: none` on `html` (in `static/v3/v3.css`) so accidental drag/double-click selection of chrome never looks broken. Form fields are always re-enabled, and a **plugin's mounted screen subtree (`.screen[id^="plugin-"]`) stays selectable by default**, so a plugin's copy-worthy text (lyrics, chord names, results, diagnostics) is unaffected — *unless your plugin renders copyable content OUTSIDE its `plugin-<id>` screen* (e.g. injected into the player chrome / a HUD overlay), which inherits the non-select default. Opt such content back in with the core-served **`.fb-selectable`** class (it sets `user-select: text` on the element + descendants; works for runtime-installed plugins since it's hand-authored in core CSS, not a scanned Tailwind utility). Never use a `* { user-select: none }` rule (breaks input carets/IME), and never use `user-select: none` to "lock" text — keep errors, IDs, paths, versions, and metadata selectable. (v2 is unchanged.)
 - **Player layout** — `#player` is `display:flex; flex-direction:column; position:fixed; inset:0`. `#highway` is `flex:1`. `#player-controls` sits at the bottom. Hiding the highway collapses the layout — use `margin-top: auto` on controls if you need to hide it.
 
 ## Backend Conventions

Dockerfile

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

README.md

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

TODO.md

@@ -22,5 +22,5 @@ too sharp / too flat / not played).
 - **[Implementation Plan](docs/NOTE_FAILURE_PLAN.md)** — 7 phases from
   detection foundation through section grading and polish
 - **Note Detection Plugin Plan** — see the
-  [feedBack-plugin-notedetect](https://github.com/topkoa/feedBack-plugin-notedetect)
+  [slopsmith-plugin-notedetect](https://github.com/topkoa/slopsmith-plugin-notedetect)
   repository (Phase 0 foundation)

VERSION

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

docs/diagnostics-bundle-spec.md

@@ -177,7 +177,7 @@ entry explaining why.
       "capability_validation_warnings": [],
       "capability_unsupported_versions": [],
       "compatibility_shims": [],
-      "git": { "sha": "abc123d", "remote": "https://github.com/topkoa/feedBack-plugin-stems.git" }
+      "git": { "sha": "abc123d", "remote": "https://github.com/topkoa/slopsmith-plugin-stems.git" }
     }
   ],
   "orphans": [

docs/host-theme-contract.md

@@ -0,0 +1,246 @@
+# Host Theme Contract — design proposal
+
+**Status:** proposal (charrette output, 2026-06-29) · **Owner area:** core v3 + plugin UI
+**Trigger:** a plugin UI feature accidentally "carved itself into a single theme."
+
+## 1. Problem
+
+A results-card feature in the `note_detect` plugin (a glow-ring hero button + a
+gradient-filled accuracy number) was built and visually verified against **only the
+default skin** ("neon"). On the other skins it broke: on "esports" — a deliberately
+glow-less, near-monochrome design language — the glow ring and the colour gradient
+simply **vanished**. The colours adapted (everything used CSS custom-property tokens),
+but the **visual devices themselves did not port**, because nothing in the system says
+"this theme does / doesn't do glow rings."
+
+### Root cause (three findings)
+
+1. **Themes are design *languages*, not palettes.** neon = glow + animation + gradients;
+   esports = no-glow, square, near-monochrome amber; metal = brushed steel + hard bevels +
+   drop-shadows. Tokens made *colour* portable; they never made a *device* portable.
+2. **Tokens are named by *device*, not *intent*.** e.g. `--nd-glow-*` holds a glow in neon
+   but a **hard drop-shadow** in metal — the metal skin is already repurposing a
+   device-named slot to express a different language. The cure is to finish that move:
+   name slots by intent, with "off" (`none`) a legal value.
+3. **No "text-legible-on-accent" role.** White-on-accent was hardcoded in several places;
+   on esports' amber accent that's a contrast failure. And `--nd-accent2` was
+   **double-booked** (gradient-end *and* S-grade colour), so the hero gradient resolved
+   amber→near-white and washed out.
+
+A process gap compounds it: **verification covered one skin**, so the regression was
+invisible until a user switched themes. And this recurs ecosystem-wide — other plugins
+ship their own independent skin systems too.
+
+## 2. Current state (two disconnected systems)
+
+| System | What it is | Limits |
+| --- | --- | --- |
+| **Host themes** (`static/v3/theme-core.js`, `html[data-fb-theme]`) | Cosmetic "shop" themes that recolour `fb-*` Tailwind tokens (surfaces/text/borders). | Apply-only & recolour-only. `--fbv-*` vars exist **only while a theme is equipped** (nothing to read in the default state). No read API, no capability signal, no normalized `theme:changed` event. Comment explicitly says it *leaves decorative accents (rings/shadows) at defaults* → **devices are an ownerless gap.** |
+| **Plugin skins** (e.g. `note_detect` `data-nd-skin`) | Full per-plugin design languages (neon/esports/metal) as CSS-var blocks. | Each plugin reinvents the wheel; disconnected from host themes; a feature can't see both. |
+
+## 3. Goals / non-goals
+
+- **Goal:** a feature, authored once, renders correctly in **any** theme — including ones not
+  yet invented — and degrades **intentionally** (neon ring → esports border), never accidentally.
+- **Goal:** the host owns a canonical contract so plugins consume instead of reinventing.
+- **Non-goal:** forcing every plugin skin to become a host theme. Skins stay plugin-local but
+  **implement** the contract.
+- **Non-goal:** backward-compat with pre-v3 hosts. Everything here is additive + feature-detected.
+
+## 4. The contract — three layers
+
+### Layer 1 — Semantic colour **roles** (always present)
+
+The host writes default `--fb-*` role tokens on `:root` **unconditionally** (not only under
+`[data-fb-theme]`), seeded from the canonical `fb` palette, so `var(--fb-accent, …)` always
+resolves — themed or not. Roles:
+
+**Namespace (normative).** The public contract lives under one prefix, **`--fb-*`**, written on
+`:root` by a host-owned *contract stylesheet* (see §6 / §8) so it is present **themed or not**.
+The existing `--fbv-*` vars stay **internal plumbing** — `theme-core.js` uses them only to
+recolour the Tailwind `.bg-fb-*/.text-fb-*/.border-fb-*` utilities under `html[data-fb-theme]`;
+they are **not** part of this contract and plugins must not read them. (Implementation may seed
+`--fb-*` from the same source the `--fbv-*` overrides use, so an equipped theme moves both.)
+
+**Value grammar (normative).** Colour roles are a **space-separated `r g b` triplet** (matching
+today's `--fbv-*` and the Tailwind utilities), consumed as `rgb(var(--fb-accent))` with optional
+alpha `rgb(var(--fb-accent) / .5)`. Recipe slots (Layer 2) hold **full CSS values** for their
+device (a `box-shadow`, a `border` shorthand, a length, a paint), with `none` legal **except**
+where noted.
+
+**Normative role tokens** (all `--fb-*`, all always present):
+
+| Role | Token | Notes |
+| --- | --- | --- |
+| surface / card / border | `--fb-surface` `--fb-card` `--fb-border` | structural |
+| text / dim | `--fb-text` `--fb-text-dim` | |
+| accent / second hue | `--fb-accent` `--fb-accent-2` | `accent-2` is **just a second hue** — never an assumed gradient end |
+| status | `--fb-good` `--fb-warn` `--fb-bad` | maps onto today's palette `good / mid / low` (mid→warn, low→bad) — implementation aliases both |
+| **on-fill (new)** | `--fb-on-accent` `--fb-on-good` `--fb-on-warn` `--fb-on-bad` | **Rule: every role used as a fill behind text gets a paired `--fb-on-*`** (fixes white-on-amber). Required + contrast-linted (§6). |
+| **focus (new)** | `--fb-focus-ring` | focus indicator independent of `accent`, so focus stays visible when `accent ≈ surface` |
+
+### Layer 2 — Capability **recipes** (intent-named slots; "off" is legal)
+
+A theme declares its design *language* by filling intent-named slots (all `--fb-*`-prefixed,
+same namespace as the roles). A feature applies the slot bundle **unconditionally**; it never
+branches on "is this theme glowy?". Atomic slots (renames-by-intent of today's tokens):
+`--fb-corner-radius`, `--fb-corner-clip`, `--fb-panel-shadow`, `--fb-text-emph-shadow`,
+`--fb-panel-texture`, `--fb-motion-decorative` (reduced-motion-gated). For these, `none` is legal.
+
+Two **composite recipes** carry the load:
+
+- **EMPHASIS** — how this theme makes a primary action special:
+  `--fb-emph-fill / --fb-emph-border / --fb-emph-halo / --fb-emph-on`.
+  neon → halo (glow ring); esports → border (solid accent); metal → fill + drop-shadow.
+  Any individual slot may be `none` — but a theme **must** emphasise *somehow* (at least one of
+  fill/border/halo non-`none`), so a primary action is never visually flat.
+- **ACCENT-TEXT** — how this theme fills a big accent number: `--fb-acc-text-fill`
+  (decoupled from `accent-2`). neon/metal → a gradient; esports → a solid accent.
+  **`--fb-acc-text-fill` is the one slot where `none` is illegal** — it is always a valid paint
+  (solid colour or gradient), defaulting to `rgb(var(--fb-accent))`. Reason: the number is
+  rendered with `background-clip: text` + transparent text-fill, so a `none` paint would make
+  the digits **invisible** (transparent fill, nothing to clip) — which would violate the DoD
+  "a device stays legible when its slot resolves to `none`". The feature also feature-detects
+  `background-clip: text` and keeps a solid `color` base (see §5), so the digits are legible
+  even where clip-text is unsupported.
+
+> These generalize the interim per-skin tokens already shipped in `note_detect`
+> (`--nd-hero-ring-idle/on`, `--nd-hero-border`, `--nd-acc-fill`).
+
+### Layer 3 — JS read API + reconciliation
+
+**The JS API is only for renderers that can't use CSS (canvas / WebGL), never for DOM/CSS
+consumers** — those use the tokens and slots directly (§5). Critically, it exposes *resolved
+token values*, **not** theme-style booleans: a `glow:false` flag can't tell a canvas whether to
+draw a border, a bevel, a drop-shadow, or flat text, so there is **no** `capabilities()` of
+booleans. On the existing `window.feedBack` bus:
+
+- `feedBack.theme.get()` → `{ id, isThemed, tokens }` where `tokens` is the **resolved** map of
+  every `--fb-*` role + recipe slot (the computed values, so a canvas reads the actual device,
+  e.g. the gradient stops for `--fb-acc-text-fill`, not a boolean).
+- `feedBack.theme.prefersReducedMotion()` → boolean (host wraps `matchMedia` once). **This is the
+  single approved JS reduced-motion gate going forward** — existing direct `matchMedia` callers
+  (`venue-mood-fx.js`, `pedal-cables.js`) migrate to it; `--fb-motion-decorative` covers the
+  CSS-authored decorative motion.
+- `theme:changed` event → `{ id, tokens }`.
+
+**Lifecycle (normative).** `get()` always returns the **current effective theme synchronously**
+and is valid at any time — before any theme is applied it returns the default/unthemed roles
+(which always exist on `:root`). Theme application is async (it follows a `/api/profile` refresh);
+`theme:changed` fires **only after** the DOM vars/classes are committed, and **once on initial
+hydration** so a late-mounting plugin isn't stuck on stale state. **Plugin rule:** read `get()`
+on mount, then subscribe to `theme:changed` — never assume an order between your mount and the
+first theme apply.
+
+**Reconciliation rule (ends the two-disconnected-systems problem):** a plugin skin
+**derives surface/text/border from host tokens** (`--nd-bg: rgb(var(--fb-card))`, etc.) and
+**owns only its accent + its devices**, selecting the device via the recipe. A host theme then
+pulls plugin chrome along (one truth for surfaces), while the plugin layers identity on top and
+never imposes a device the active theme neutralizes.
+
+**Propagation scope (normative).** The contract is **same-document light-DOM**: `:root` `--fb-*`
+inheritance and the central focus/motion rules (§6) reach any normal plugin screen. A plugin that
+renders into a **shadow root or iframe** is responsible for bridging — copy the resolved
+`get().tokens` into its sub-root and re-subscribe to `theme:changed` (host `:root` vars don't
+cross those boundaries).
+
+## 5. Consumption pattern (the rule for feature authors)
+
+> **A feature may reference a colour *role* or a recipe *slot*. It may never write a raw
+> device — no literal glow `box-shadow`, no literal `linear-gradient`, no hex.** Devices live
+> in slots; the theme owns the slots.
+
+```css
+.hero-cta {
+  background: var(--fb-emph-fill);
+  border:     var(--fb-emph-border);
+  box-shadow: var(--fb-emph-halo);   /* neon→ring · esports→none · metal→drop-shadow */
+  color:      var(--fb-emph-on);     /* never hardcoded #fff again */
+  border-radius: var(--fb-corner-radius);
+}
+.accuracy-number {
+  /* Always-legible solid base; survives no-clip-text support too. */
+  color: rgb(var(--fb-accent));
+}
+/* Apply the clipped paint ONLY where supported — and --fb-acc-text-fill is
+   guaranteed a real paint (never `none`, per Layer 2), so the digits can't go
+   invisible. */
+@supports ((background-clip: text) or (-webkit-background-clip: text)) {
+  .accuracy-number {
+    background: var(--fb-acc-text-fill);
+    -webkit-background-clip: text; background-clip: text;
+    -webkit-text-fill-color: transparent;
+  }
+}
+```
+
+**Where the contract physically lives.** A **host-owned static contract stylesheet** (e.g.
+`static/v3/theme-contract.css`, hand-authored, linked from `static/v3/index.html`) holds the
+always-present `:root --fb-*` defaults **plus** the two central a11y rules below. It is **not** a
+Tailwind file, so it never touches the prebuilt `static/tailwind.min.css` artifact the
+`tailwind-fresh` CI check diffs (and it's independent of `theme-core.js`, which keeps
+runtime-injecting only the `--fbv-*` utility overrides under `[data-fb-theme]`).
+
+- **Reduced motion:** `--fb-motion-decorative` is the *only* place CSS decorative animation is
+  named; one central rule in the contract sheet sets it to `none` under
+  `@media (prefers-reduced-motion: reduce)`, so no theme can forget the gate. (JS-driven motion
+  uses `feedBack.theme.prefersReducedMotion()` — §4.3.)
+- **Focus parity:** one contract-level `:focus-visible { outline: 2px solid rgb(var(--fb-focus-ring)) }`
+  for contract consumers; themes recolour `--fb-focus-ring` but may not author their own focus
+  styling. *Migration:* v3 already ships component-specific focus + reduced-motion rules in
+  `v3.css`; those are reconciled onto the contract token (not magically replaced) as a tracked
+  cleanup — "one rule" describes the end state, not day one.
+- **On-fill contrast:** every `--fb-on-*` is required and **lintable**
+  (`contrast(on-X, X) ≥ 4.5:1`, 3:1 large) for each fill role (`accent / good / warn / bad`).
+  Contrast is the theme's job, computed once — not re-judged per feature.
+
+## 7. Verification gate (prevent recurrence)
+
+- A committed **render-matrix** tool, driven off the runtime skin list, that renders the key
+  surfaces (hero CTA, accent number, **and the canvas share-image card**) across **every skin ×
+  key states** (rest / hover / focus / reduced-motion).
+- The gate is **computed-style invariant assertions** (deterministic, CI-safe) — e.g. "emphasis
+  present and text legible in each theme" — **not** pixel-snapshot diffing (the animated ring +
+  fonts + AA make snapshots flaky); a contact-sheet montage is the human backstop.
+- Triggered on the version bump that CSS changes already require; skins enumerated at runtime +
+  a guard test so the matrix can't silently go stale.
+
+**Definition-of-done for any theme-touching UI change** (the few items that would have caught this):
+expressed via tokens not hardcoded values · rendered across all skins · **a new visual *device*
+stays legible when its slot resolves to `none`** · reduced-motion + focus parity · on-accent contrast.
+
+## 8. Back-compat & rollout
+
+All additive: the new always-present `--fb-*` tokens (in the contract sheet, §6) + a new
+`feedBack.theme` namespace + a new event with no current listeners. Existing plugins (those
+reading `fb-*` Tailwind utility classes, or shipping their own skins) are untouched unless they
+opt in. On a host too old to ship the contract sheet, a consumer still degrades cleanly: the
+two-arg fallback `rgb(var(--fb-accent, 224 128 32))` resolves to the literal, and
+`window.feedBack?.theme?.get?.()` is feature-detected — so older hosts behave exactly as today.
+
+**Workstream (sub-tasks):**
+1. **Host minimal surface** — the contract stylesheet's always-present default `--fb-*` tokens + `feedBack.theme.{get, prefersReducedMotion}` (`get().tokens` = resolved values; no boolean `capabilities()`) + `theme:changed`. *(the smallest thing that would have prevented the incident)*
+2. **note_detect refactor** — rename device tokens by intent (EMPHASIS + ACCENT-TEXT recipes), add `on-accent` + `focus-ring`, derive surfaces from host tokens.
+3. **Verification gate** — commit the render-matrix + DoD checklist; add the canvas share-card surface.
+4. **Ecosystem migration guide** — document the contract + the consumption rule for community plugin authors.
+
+## 9. Cross-apply status (already done)
+
+- `note_detect` results-card hero + accuracy number — fixed via per-skin device tokens
+  (the Layer-2 prototype) and verified across neon/esports/metal.
+- The **canvas share-image card** — re-checked across all three skins: **theme-robust**
+  (reads per-skin colour tokens via computed style, draws skin-neutral solid devices). Minor
+  fidelity gap only: it uses flat `--nd-bg` and skips metal's brushed-steel *texture*.
+
+## 10. Open questions
+
+- Should plugin skins eventually become *selectable host themes* (one picker), or stay
+  plugin-local forever? (This proposal assumes plugin-local + contract-implementing.)
+- Component-recipe **bundles** (per named component) are the richer end-state; intent-named
+  slots are the right seed. When/whether to graduate.
+
+*(Resolved during review and folded into the sections above: the token namespace + value grammar
+and normative role table (§4.1); the `none`-is-illegal carve-out for `--fb-acc-text-fill` (§4.2);
+JS exposes resolved tokens, not booleans (§4.3); `theme:changed` lifecycle + shadow/iframe
+propagation (§4.3); the physical home of the role tokens + central focus/motion rules — a
+host-owned contract stylesheet outside Tailwind (§6).)*

docs/sloppak-hand-editing.md

@@ -73,7 +73,7 @@ The use case: the converted rhythm guitar sounds muddy (Demucs has a tough time
 2. Open `manifest.yaml` in any text editor (Notepad++, VS Code, BBEdit, gedit — all fine; just **don't use Word**).
 3. Find the `stems:` block. Two things matter here:
    - **Order:** FeedBack's base `<audio>` element always plays the **first** stem listed in `stems[]`, regardless of `default:` flags. So if you want your custom stem to be what the player plays out-of-the-box (and what users without the Stems plugin will hear), put it **first**.
-   - **`default:` flags:** consulted by the [Stems plugin](https://github.com/topkoa/feedBack-plugin-stems) to decide which faders start un-muted. They do **not** affect what the base `<audio>` element plays — that's purely the first-stem rule above.
+   - **`default:` flags:** consulted by the [Stems plugin](https://github.com/topkoa/slopsmith-plugin-stems) to decide which faders start un-muted. They do **not** affect what the base `<audio>` element plays — that's purely the first-stem rule above.
 
    Example for a Demucs-split sloppak where you re-recorded the rhythm guitar:
 
@@ -110,7 +110,7 @@ The use case: the converted rhythm guitar sounds muddy (Demucs has a tough time
 
 ### Step 5 — Reload and verify
 
-Reload the song in FeedBack. The [Stems plugin](https://github.com/topkoa/feedBack-plugin-stems) will show a fader for `rhythm_custom` next to the others. If you don't see it, check the cache notes in §1.
+Reload the song in FeedBack. The [Stems plugin](https://github.com/topkoa/slopsmith-plugin-stems) will show a fader for `rhythm_custom` next to the others. If you don't see it, check the cache notes in §1.
 
 ### Common gotchas
 

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

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

lib/diagnostics_redact.py

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

lib/gp2rs.py

@@ -1124,7 +1124,17 @@ def _build_xml(
     # for compatibility, and emit additional string6+ attributes (up to
     # `len(tuning)-1`) for 7+ string arrangements. FeedBack parses
     # them; the format ignores them.
+    #
+    # `stringCount` records the AUTHORITATIVE string count (== len(tuning)),
+    # because the 6-slot padding above erases the 4-vs-5-vs-6-string
+    # distinction for standard tunings (a 4-string bass, 5-string bass and
+    # 6-string guitar are otherwise byte-identical, all string0..5 = 0).
+    # parse_arrangement trims `tuning` back to this on read so downstream
+    # string-count derivation (song.arrangement_string_count, the editor's
+    # _stringCountFor) sees the real width instead of guessing. RS2014 and
+    # any other consumer simply ignore the unknown attribute.
     tuning_el = ET.SubElement(root, "tuning")
+    tuning_el.set("stringCount", str(len(tuning)))
     for i in range(max(6, len(tuning))):
         tuning_el.set(f"string{i}", str(tuning[i] if i < len(tuning) else 0))
     ET.SubElement(root, "capo").text = "0"

lib/gp2rs_gpx.py

@@ -121,10 +121,18 @@ def _parse_bcfs(bcfs: bytes) -> dict:
             while sc <= max_sectors:
                 s = _gi(po + 4 * sc); sc += 1
                 if s == 0: break
-                so = s * SECTOR
-                if HDR + so + SECTOR > len(data):
+                start = HDR + s * SECTOR
+                # Real .gpx files' final sector is a few bytes short of a full
+                # 0x1000 block: the BCFZ-declared decompressed size isn't
+                # sector-aligned, so the last (small) container file lands in a
+                # partial trailing sector. Clamp the read to the buffer end —
+                # the per-file size field (`fs`, applied below) trims any
+                # padding — matching canonical GPX readers (alphaTab /
+                # PyGuitarPro slice-and-clamp). Only a sector whose *start* is
+                # past the end is genuinely malformed.
+                if start < 0 or start >= len(data):
                     raise ValueError("GPX BCFS sector pointer out of range (malformed file)")
-                fb.extend(data[HDR + so: HDR + so + SECTOR])
+                fb.extend(data[start: min(start + SECTOR, len(data))])
             else:
                 raise ValueError("GPX BCFS sector chain too long (malformed file)")
             files[fn] = bytes(fb[:fs])
@@ -229,22 +237,47 @@ 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 [])}
     _beats_by_id = {b.get('id'): b for b in (root.find('Beats') or [])}
+    _notes_by_id = {n.get('id'): n for n in (root.find('Notes') or [])}
 
     def _note_count_for_raw(raw_idx: int) -> int:
-        # Total note count for the track (sum of notes across all its beats).
-        # This is the single source of truth: list_tracks surfaces it as the
-        # 'notes' field, and _auto_select_gpx uses (count == 0) to skip empty
-        # tracks — so the graph is walked once here, not again in list_tracks.
+        # Count of notes that ACTUALLY become RS notes for the track. This is
+        # the single source of truth: list_tracks surfaces it as the 'notes'
+        # field (the importer's per-track preview count) and _auto_select_gpx
+        # uses (count == 0) to skip empty tracks — so the graph is walked once
+        # here, not again in list_tracks.
+        #
+        # Tie-DESTINATION notes are excluded: a tied note is folded into the
+        # previous note as extended sustain (see the `_note_is_tie` skips in
+        # convert_file), so it never becomes a separate RS note. Counting them
+        # made the preview overstate the result (e.g. 260 shown, 241 imported);
+        # excluding them makes the preview match what the user actually gets.
         n = 0
         for mb in _masterbars:
             bar_ids = mb.findtext('Bars', '').split()
@@ -263,16 +296,25 @@ def _gpif_tracks(root: ET.Element) -> list[dict]:
                     beat = _beats_by_id.get(bid)
                     if beat is None:
                         continue
-                    notes_text = beat.findtext('Notes', '').strip()
-                    if notes_text:
-                        n += len(notes_text.split())
+                    for nid in beat.findtext('Notes', '').split():
+                        note_el = _notes_by_id.get(nid)
+                        if note_el is not None and _note_is_tie(note_el):
+                            continue
+                        n += 1
         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
@@ -309,27 +351,37 @@ def _gpif_tracks(root: ET.Element) -> list[dict]:
                 except (ValueError, TypeError):
                     pass
 
-        # String tuning
-        string_pitches: list[int] = []
-        for prop in t.findall('.//Property'):
-            if prop.get('name') == 'Tuning':
-                pe = prop.find('Pitches')
-                if pe is not None and pe.text:
-                    try:
-                        string_pitches = [int(p) for p in pe.text.split()]
-                    except ValueError:
-                        pass
+        # String tuning — one list per stave, in stave order.  Reading all
+        # `.//Property` descendants across every stave meant the last stave's
+        # tuning overwrote the first; for a GP8 piano (treble 6-string +
+        # bass 5-string) that caused stave-0 notes with String=5 to be
+        # out-of-range against the 5-entry bass tuning and silently dropped.
+        # A staff with no Tuning of its own falls back to the track-level
+        # property (never to []) — an empty list silently drops every fretted
+        # note on that stave in `_note_midi`.  The list stays parallel to
+        # `stave_columns` so a per-stave column always has a matching tuning.
+        _track_tuning = _parse_tuning(t)
+        _staff_els = list(t.findall('Staves/Staff'))
+        if _staff_els:
+            stave_pitches = [(_parse_tuning(s) or _track_tuning) for s in _staff_els]
+        else:
+            # No <Staves> (GP3/4/5 or old GPX): single track-level tuning.
+            stave_pitches = [_track_tuning]
 
         result.append({
             '_el': t,
             'id': t.get('id', ''),
             'name': name,
-            'string_pitches': string_pitches,
+            'string_pitches': stave_pitches[0],   # primary stave (existing key)
+            'num_staves': num_staves,
+            'stave_columns': stave_columns,
+            'stave_pitches': stave_pitches,
             'is_drums': is_drums,
             'midi_program': midi_program,
             'midi_channel': midi_channel,
-            'note_count': _note_count_for_raw(raw_idx),
+            'note_count': sum(_note_count_for_raw(c) for c in stave_columns),
         })
+        bar_column += num_staves
     return result
 
 
@@ -357,6 +409,121 @@ def _beat_dur_secs(beat_el: ET.Element, rhythms_dict: dict, tempo_bpm: float) ->
     return dur_qn * (60.0 / tempo_bpm)
 
 
+def _collect_column_notes(
+    col: int,
+    string_pitches: list[int],
+    *,
+    masterbars: list,
+    bars_by_id: dict,
+    voices_dict: dict,
+    beats_dict: dict,
+    notes_dict: dict,
+    rhythms_dict: dict,
+    tempo_map: list,
+    tempo_bpm: float,
+    audio_offset: float,
+) -> list['RsNote']:
+    """Walk one ``MasterBar/Bars`` column (a single stave / hand) and return its
+    notes as keys-encoded ``RsNote`` (``string = midi // 24``, ``fret = midi %
+    24``). Tie destinations extend the matching prior note's sustain (keyed by
+    pitch, so polyphonic parts are handled) rather than emitting a new note —
+    mirroring the main ``convert_file`` builder, including its full-precision
+    timing and the 0.2s sustain threshold.
+
+    Shared by the GPX LH/RH pair merge and the GP8 multi-stave (grand-staff)
+    fold so the two code paths can never drift in tie / timing / dedup handling.
+    """
+    from gp2rs import RsNote  # lazy: gp2rs<->gpx circular import (see convert_file)
+
+    notes: list[RsNote] = []
+    last_per_key: dict[int, RsNote] = {}
+    tempo_iter = iter(tempo_map)
+    next_bar, next_bpm = next(tempo_iter, (999999, tempo_bpm))
+    cur_tempo = tempo_bpm
+    t_cursor = 0.0
+
+    for mb_idx, mb in enumerate(masterbars):
+        while mb_idx >= next_bar:
+            cur_tempo = next_bpm
+            next_bar, next_bpm = next(tempo_iter, (999999, cur_tempo))
+        ts = mb.findtext('Time', '4/4')
+        try:
+            nb, db = [int(x) for x in ts.split('/')]
+        except ValueError:
+            nb, db = 4, 4
+        bar_dur = nb * (4.0 / db) * (60.0 / cur_tempo)
+        bar_ids = mb.findtext('Bars', '').split()
+        bid = bar_ids[col] if col < len(bar_ids) else '-1'
+        if bid != '-1' and bid:
+            bar = bars_by_id.get(bid)
+            if bar is not None:
+                for vid in bar.findtext('Voices', '').split():
+                    if vid == '-1':
+                        continue
+                    voice = voices_dict.get(vid)
+                    if voice is None:
+                        continue
+                    vt = t_cursor
+                    for beat_id in voice.findtext('Beats', '').split():
+                        beat = beats_dict.get(beat_id)
+                        if beat is None:
+                            continue
+                        dur = _beat_dur_secs(beat, rhythms_dict, cur_tempo)
+                        for nid in beat.findtext('Notes', '').strip().split():
+                            note_el = notes_dict.get(nid)
+                            if note_el is None:
+                                continue
+                            if _note_is_tie(note_el):
+                                tie_midi = _note_midi(note_el, string_pitches)
+                                if tie_midi is not None:
+                                    prev = last_per_key.get(tie_midi)
+                                    tie_t = vt + audio_offset
+                                    if prev is not None and prev.time < tie_t:
+                                        prev.sustain = max(
+                                            prev.sustain, (tie_t + dur) - prev.time)
+                                continue
+                            midi = _note_midi(note_el, string_pitches)
+                            if midi is None:
+                                continue
+                            rn = RsNote(
+                                time=vt + audio_offset,
+                                string=midi // 24,
+                                fret=midi % 24,
+                                sustain=dur if dur > 0.2 else 0.0,
+                            )
+                            notes.append(rn)
+                            last_per_key[midi] = rn
+                        vt += dur
+        t_cursor += bar_dur
+    return notes
+
+
+def _merge_lh_notes(rs_notes: list, rs_chords: list, lh_notes: list) -> None:
+    """Fold ``lh_notes`` (a second stave / left hand) into ``rs_notes`` in
+    place, de-duplicating simultaneous same-pitch notes and keeping the LONGER
+    sustain when both hands strike the same key at the same instant. Seeds the
+    dedup set from chord notes too (polyphonic RH beats live in
+    ``rs_chords[*].notes``). No-op for an empty ``lh_notes``."""
+    if not lh_notes:
+        return
+    seen: dict[tuple, RsNote] = {}
+    for n in rs_notes:
+        seen.setdefault((round(n.time, 3), n.string, n.fret), n)
+    for c in rs_chords:
+        for cn in c.notes:
+            seen.setdefault((round(cn.time, 3), cn.string, cn.fret), cn)
+    for rn in lh_notes:
+        k = (round(rn.time, 3), rn.string, rn.fret)
+        existing = seen.get(k)
+        if existing is None:
+            rs_notes.append(rn)
+            seen[k] = rn
+        elif rn.sustain > existing.sustain:
+            # Mutating the RsNote also updates it in place inside any RH chord.
+            existing.sustain = rn.sustain
+    rs_notes.sort(key=lambda n: (n.time, n.string))
+
+
 # ---------------------------------------------------------------------------
 # Drum encoding tables — ported from alphaTab PercussionMapper (MIT licensed)
 # ---------------------------------------------------------------------------
@@ -1356,25 +1523,84 @@ 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)
 
     output_files = []
-    # Counts of auto-named guitar/bass arrangements so far, so multiple guitars
-    # get distinct RS roles (Lead, Rhythm, Combo, …) instead of all "Lead".
-    _role_counts: dict[str, int] = {}
+    # All auto-assigned arrangement names handed out so far, so multiple
+    # arrangements get distinct labels (Lead, Rhythm, Combo, Bass, Bass 2, …)
+    # and the name-aware and positional guitar paths never collide.
+    _used_arr_names: set[str] = set()
+
+    def _unique_arr_name(base: str) -> str:
+        """Return `base`, or `base 2`/`base 3`/… if it's already been used."""
+        if base not in _used_arr_names:
+            _used_arr_names.add(base)
+            return base
+        k = 2
+        while f"{base} {k}" in _used_arr_names:
+            k += 1
+        name = f"{base} {k}"
+        _used_arr_names.add(name)
+        return name
+
+    _KEYS_PROGS = set(range(0, 8)) | set(range(16, 24)) | {80, 81, 82, 83}
+
+    def _auto_guitar_hint(track_idx: int):
+        """For a track that auto-resolves to a guitar arrangement, return its
+        role hint: 'lead', 'rhythm', or '' (unhinted). None when the track is
+        NOT an auto-named guitar (explicitly named, bass, drum, vocal, keys).
+        Mirrors the per-track classification in the conversion loop below."""
+        if track_idx >= len(tracks) or names.get(track_idx):
+            return None
+        t = tracks[track_idx]
+        if t['is_drums'] or _is_vocal_track(t):
+            return None
+        low = t['name'].lower()
+        sp = t['string_pitches']
+        prog = t['midi_program']
+        if (isinstance(prog, int) and 32 <= prog <= 39) or (bool(sp) and max(sp) <= 48) or 'bass' in low:
+            return None  # bass
+        if (not sp and prog in _KEYS_PROGS) or any(kw in low for kw in ('piano', 'keys', 'keyboard', 'organ')):
+            return None  # keys
+        if 'lead' in low and 'rhythm' not in low:
+            return 'lead'
+        if 'rhythm' in low and 'lead' not in low:
+            return 'rhythm'
+        return ''  # guitar, no role hint
+
+    # Two-pass guitar role naming, resolved up front so the per-track loop just
+    # looks names up. Reserve every name-hinted Lead/Rhythm first, THEN fill
+    # unhinted guitars into the remaining canonical roles. A single pass would
+    # let an unhinted guitar that appears BEFORE a hinted one steal its role,
+    # pushing the real Lead/Rhythm to a non-canonical "Rhythm 2" that the
+    # downstream name-based path classification doesn't recognise.
+    _guitar_name_by_idx: dict[int, str] = {}
+    _unhinted_guitars: list[int] = []
+    for _ti in track_indices:
+        hint = _auto_guitar_hint(_ti)
+        if hint is None:
+            continue
+        if hint == 'lead':
+            _guitar_name_by_idx[_ti] = _unique_arr_name('Lead')
+        elif hint == 'rhythm':
+            _guitar_name_by_idx[_ti] = _unique_arr_name('Rhythm')
+        else:
+            _unhinted_guitars.append(_ti)
+    for _ti in _unhinted_guitars:
+        base = next((r for r in ('Lead', 'Rhythm', 'Combo') if r not in _used_arr_names), 'Combo')
+        _guitar_name_by_idx[_ti] = _unique_arr_name(base)
 
     for track_idx in track_indices:
         if track_idx >= len(tracks):
@@ -1398,7 +1624,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']
@@ -1422,16 +1657,12 @@ def convert_file(
             )
             low = track['name'].lower()
             if is_bass or 'bass' in low:
-                _bc = _role_counts.get('bass', 0)
-                _role_counts['bass'] = _bc + 1
-                arr_name = 'Bass' if _bc == 0 else f'Bass {_bc + 1}'
+                arr_name = _unique_arr_name('Bass')
             else:
-                # Distinct guitar roles by appearance order so two guitars
-                # don't both become "Lead": Lead, Rhythm, Combo, then Combo N.
-                _gc = _role_counts.get('guitar', 0)
-                _role_counts['guitar'] = _gc + 1
-                _roles = ('Lead', 'Rhythm', 'Combo')
-                arr_name = _roles[_gc] if _gc < len(_roles) else f'Combo {_gc - 1}'
+                # Guitar role was resolved up front (two-pass, honoring
+                # "lead"/"rhythm" in the GP track name so a Rhythm-before-Lead
+                # file isn't swapped by positional assignment).
+                arr_name = _guitar_name_by_idx.get(track_idx) or _unique_arr_name('Lead')
 
         # Vocal tracks get their own converter — outputs vocals XML, not notes XML
         if is_vocal:
@@ -1468,7 +1699,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)
@@ -1800,112 +2030,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")
@@ -1913,6 +2051,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).
@@ -1966,19 +2116,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:
@@ -2317,7 +2472,15 @@ def _auto_select_gpx(tracks: list[dict]) -> tuple[list[int], dict[int, str]]:
         if is_bass:
             selected.append((i, 'bass'))
         elif is_guitar:
-            selected.append((i, 'guitar'))
+            # Honor "lead"/"rhythm" in the GP track name so two guitars keep
+            # the author's roles instead of being labelled by appearance order
+            # (which swaps a Rhythm-before-Lead file). Unhinted → positional.
+            if 'lead' in name_l and 'rhythm' not in name_l:
+                selected.append((i, 'guitar_lead'))
+            elif 'rhythm' in name_l and 'lead' not in name_l:
+                selected.append((i, 'guitar_rhythm'))
+            else:
+                selected.append((i, 'guitar'))
         elif is_keys:
             selected.append((i, 'keys'))
 
@@ -2326,19 +2489,48 @@ def _auto_select_gpx(tracks: list[dict]) -> tuple[list[int], dict[int, str]]:
             if not t['is_drums'] and t.get('note_count', 1) > 0:
                 selected.append((i, 'guitar'))
 
-    indices = []
     name_map = {}
     counts: dict[str, int] = {}
-    RS_NAMES = {'guitar': ('Lead', 'Rhythm', 'Combo'), 'bass': ('Bass',), 'keys': ('Keys',), 'drums': ('Drums',), 'vocal': ('Vocals',)}
+    RS_NAMES = {'bass': ('Bass',), 'keys': ('Keys',),
+                'drums': ('Drums',), 'vocal': ('Vocals',)}
+    used: set[str] = set()
+
+    def _unique(base: str) -> str:
+        if base not in used:
+            used.add(base)
+            return base
+        k = 2
+        while f"{base} {k}" in used:
+            k += 1
+        used.add(f"{base} {k}")
+        return f"{base} {k}"
+
+    # Two passes so name-hinted Lead/Rhythm guitars reserve their canonical role
+    # BEFORE unhinted guitars are filled in — otherwise an unhinted guitar that
+    # appears before a hinted one steals its role (real Rhythm → "Rhythm 2").
+    # Non-guitar roles are handled in pass 1. `name_map` keys by track index so
+    # this does not affect arrangement (selection) order, computed separately.
+    for idx, role in selected:
+        if role == 'guitar':
+            continue
+        if role == 'guitar_lead':
+            base = 'Lead'
+        elif role == 'guitar_rhythm':
+            base = 'Rhythm'
+        else:
+            counts[role] = counts.get(role, 0) + 1
+            c = counts[role]
+            names_for_role = RS_NAMES.get(role, (role.title(),))
+            base = names_for_role[min(c - 1, len(names_for_role) - 1)]
+            if c > len(names_for_role):
+                base = f"{names_for_role[-1]} {c}"
+        name_map[idx] = _unique(base)
 
     for idx, role in selected:
-        counts[role] = counts.get(role, 0) + 1
-        c = counts[role]
-        names_for_role = RS_NAMES.get(role, (role.title(),))
-        arr_name = names_for_role[min(c - 1, len(names_for_role) - 1)]
-        if c > len(names_for_role):
-            arr_name = f"{names_for_role[-1]} {c}"
-        indices.append(idx)
-        name_map[idx] = arr_name
+        if role != 'guitar':
+            continue
+        base = next((r for r in ('Lead', 'Rhythm', 'Combo') if r not in used), 'Combo')
+        name_map[idx] = _unique(base)
 
+    indices = [idx for idx, _role in selected]
     return indices, name_map

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

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

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

lib/scan_worker.py

@@ -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,
@@ -367,6 +367,14 @@ class LoadedSloppak:
     # song.arrangements (not to manifest["arrangements"]) — skipped entries are
     # absent so indexing by song.arrangements index is safe.
     arrangement_ids: list[str | None] = field(default_factory=list)
+    # Manifest-relative path to the single full-mix audio file, taken from the
+    # manifest `original_audio:` key (e.g. "original/full.ogg"). This is the
+    # pre-separation mixdown that exists alongside the per-instrument `stems`.
+    # None when the key is absent, points outside source_dir, or the file is
+    # missing on disk. Served to the front-end via the highway WS as
+    # `original_audio_url`; the stems plugin uses it to play the untouched mix
+    # when every stem slider is at unity (and the separate stems otherwise).
+    original_audio: str | None = None
 
 
 def load_song(
@@ -415,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
@@ -481,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:
@@ -520,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
@@ -580,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
@@ -678,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
@@ -765,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
@@ -808,6 +816,29 @@ def load_song(
                     }
 
     _fpv = manifest.get("feedpak_version")
+    # Optional full-mix audio — manifest `original_audio:` key. The single
+    # pre-separation mixdown that ships alongside the per-instrument stems.
+    # Same permissive, path-traversal-guarded posture as drum_tab above: a
+    # missing/escaping/absent file simply leaves the full mix unavailable (the
+    # player falls back to the separate stems) rather than aborting the load.
+    # We store the manifest-relative string so server.py can build its URL the
+    # same way it builds stem URLs (via the /api/sloppak/.../file/ endpoint).
+    original_audio_data: str | None = None
+    original_audio_rel = manifest.get("original_audio")
+    if isinstance(original_audio_rel, str) and original_audio_rel.strip():
+        rel = original_audio_rel.strip()
+        try:
+            oa_path = (source_dir / rel).resolve()
+            oa_path.relative_to(source_dir.resolve())
+        except ValueError:
+            log.warning("sloppak: original_audio path %r escapes source_dir — skipped", rel)
+            oa_path = None
+        except OSError as e:
+            log.warning("sloppak: original_audio path resolution failed (%s) — skipped", e)
+            oa_path = None
+        if oa_path is not None and oa_path.is_file():
+            original_audio_data = rel
+
     return LoadedSloppak(
         song=song,
         stems=stems,
@@ -821,6 +852,7 @@ def load_song(
         keys=keys_data,
         notation_by_id=notation_by_id_data,
         arrangement_ids=arrangement_ids_acc,
+        original_audio=original_audio_data,
     )
 
 
@@ -887,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/song.py

@@ -1090,6 +1090,20 @@ def parse_arrangement(xml_path: str) -> Arrangement:
         while el.get(f"string{i}") is not None:
             tuning.append(_int(el, f"string{i}"))
             i += 1
+        # Authoritative string count, written by the GP/RS serializer
+        # (gp2rs._build_xml). The schema pads `<tuning>` to 6 slots, which
+        # erases the 4-vs-5-vs-6-string distinction for standard tunings;
+        # when the real count was recorded, trim the padded tail so
+        # arrangement_string_count / the editor see 4 or 5 instead of 6.
+        # Absent (archive / legacy sources) → leave the 6-slot tuning as-is.
+        sc = el.get("stringCount")
+        if sc is not None:
+            try:
+                n = int(sc)
+            except (TypeError, ValueError):
+                n = 0
+            if 1 <= n <= len(tuning):
+                tuning = tuning[:n]
 
     # Capo
     capo = 0

lib/songmeta.py

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

lib/tunings.py

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

plugins/__init__.py

@@ -1330,6 +1330,18 @@ def load_plugins(app: FastAPI, context: dict, progress_cb=None, route_setup_fn=N
         _category = manifest.get("category")
         if not isinstance(_category, str) or not _category:
             _category = None
+        # Settings-tab placement (tabbed settings page). When `settings` is a
+        # dict, an optional `category` field names which settings tab the
+        # plugin's panel mounts under (e.g. "graphics", "mic", "progression").
+        # Distinct from the top-level `category` above (which drives Pedalboard
+        # grouping) so the two don't collide. Absent/blank → None → the
+        # frontend falls back to the generic "Plugins" tab.
+        _settings_manifest = manifest.get("settings")
+        _settings_category = None
+        if isinstance(_settings_manifest, dict):
+            _sc = _settings_manifest.get("category")
+            if isinstance(_sc, str) and _sc:
+                _settings_category = _sc
         _icon = manifest.get("icon")
         if not isinstance(_icon, str) or not _icon:
             _icon = None
@@ -1338,6 +1350,13 @@ def load_plugins(app: FastAPI, context: dict, progress_cb=None, route_setup_fn=N
                     _icon = "assets/thumb.png"
             except OSError:
                 _icon = None
+        # Immersive (full-screen) screen opt-in. A plugin that declares a
+        # top-level `"fullscreen": true` gets the whole content area when its
+        # screen is active: the v3 shell hides the topbar and collapses the
+        # sidebar to an icon rail (see static/v3/shell.js + v3.css). For
+        # DAW-style plugin UIs that need the viewport, not a scrolling content
+        # page. Strict `is True` so a stray truthy value can't silently opt in.
+        _fullscreen = manifest.get("fullscreen") is True
         return {
             "id": plugin_id,
             "name": manifest.get("name", plugin_id),
@@ -1355,6 +1374,10 @@ def load_plugins(app: FastAPI, context: dict, progress_cb=None, route_setup_fn=N
             "has_screen": bool(manifest.get("screen")),
             "has_script": bool(manifest.get("script")),
             "has_settings": bool(manifest.get("settings")),
+            "settings_category": _settings_category,
+            # Drives the v3 shell's immersive (full-screen) mode for this
+            # plugin's screen. False unless the manifest declares it explicitly.
+            "fullscreen": _fullscreen,
             "has_tour": _is_valid_tour_manifest(manifest.get("tour")),
             # `styles` is an optional relpath (under the plugin's assets/) to a
             # compiled, preflight-off stylesheet the frontend injects as a
@@ -2067,6 +2090,11 @@ def register_plugin_api(app: FastAPI):
                 "has_screen": p["has_screen"],
                 "has_script": p["has_script"],
                 "has_settings": p["has_settings"],
+                # v3 immersive screen opt-in (full-screen plugin UI).
+                "fullscreen": p.get("fullscreen", False),
+                # Settings-tab placement; None when the manifest's `settings`
+                # is absent, a bare string, or omits `category`.
+                "settings_category": p.get("settings_category"),
                 "has_tour": p.get("has_tour", False),
                 # `.get()` fallbacks keep stubbed test entries (built without
                 # _nav_entry) working — styles is None when unset.
@@ -2115,6 +2143,8 @@ def register_plugin_api(app: FastAPI):
                 "has_screen": e.get("has_screen", False),
                 "has_script": e.get("has_script", False),
                 "has_settings": e.get("has_settings", False),
+                "settings_category": e.get("settings_category"),
+                "fullscreen": e.get("fullscreen", False),
                 "has_tour": e.get("has_tour", False),
                 "has_styles": e.get("has_styles", False),
                 "styles": e.get("styles"),

plugins/achievements/achievements.json

@@ -0,0 +1,68 @@
+{
+  "version": 1,
+  "global": [
+    {
+      "id": "first_steps",
+      "title": "First Steps",
+      "description": "Reach Mastery Rank 1 — finish onboarding.",
+      "category": "global",
+      "sourceId": "achievements",
+      "criterion": { "type": "mastery_rank", "tiers": [1] },
+      "tiers": [1]
+    },
+    {
+      "id": "ascendant",
+      "title": "Ascendant",
+      "description": "Climb the Mastery Rank ladder.",
+      "category": "global",
+      "sourceId": "achievements",
+      "criterion": { "type": "mastery_rank", "tiers": [10, 25, 50] },
+      "tiers": [10, 25, 50],
+      "tier_titles": ["Ascendant I", "Ascendant II", "Ascendant III"]
+    },
+    {
+      "id": "steady_hands",
+      "title": "Steady Hands",
+      "description": "Make a real advance on many separate days.",
+      "category": "global",
+      "sourceId": "achievements",
+      "criterion": { "type": "growth_streak_days", "tiers": [7, 30, 100] },
+      "tiers": [7, 30, 100],
+      "tier_titles": ["Steady Hands (7)", "Steady Hands (30)", "Steady Hands (100)"]
+    },
+    {
+      "id": "renaissance",
+      "title": "Renaissance",
+      "description": "Reach Level 10 across several distinct instrument paths.",
+      "category": "global",
+      "sourceId": "achievements",
+      "criterion": { "type": "paths_at_level", "level": 10, "tiers": [2, 3, 5] },
+      "tiers": [2, 3, 5],
+      "tier_titles": ["Renaissance (2)", "Renaissance (3)", "Renaissance (5)"]
+    }
+  ],
+  "per_instrument": [
+    {
+      "id": "path_rank",
+      "title": "{Inst} Mastery",
+      "description": "Climb the {Inst} path: Apprentice, Journeyman, Master.",
+      "sourceId": "achievements",
+      "criterion": { "type": "path_level", "tiers": [10, 25, "max"] },
+      "tier_titles": ["{Inst} Apprentice", "{Inst} Journeyman", "{Inst} Master"]
+    },
+    {
+      "id": "personal_best",
+      "title": "Personal Best ({Inst})",
+      "description": "Beat your own best accuracy on any {Inst} chart.",
+      "sourceId": "achievements",
+      "criterion": { "type": "personal_best" }
+    },
+    {
+      "id": "challenger",
+      "title": "Challenger ({Inst})",
+      "description": "Clear a full level-up challenge set on the {Inst} path.",
+      "sourceId": "achievements",
+      "criterion": { "type": "challenge_set_cleared" }
+    }
+  ]
+}

plugins/achievements/assets/achievements.css

@@ -0,0 +1,84 @@
+/* Achievements & Feats of Power — plugin styles (plain CSS, no Tailwind build;
+ * P-II: plugins ship their own stylesheet for non-core classes). Mirrors the v3
+ * dark surface tokens used across the Profile page. */
+
+/* Secondary category pill row inside the Achievements tab (lighter .fb-tab). */
+.fb-ach-pillrow {
+    display: flex;
+    flex-wrap: wrap;
+    gap: .4rem;
+    margin-bottom: 1rem;
+}
+.fb-ach-pill {
+    appearance: none;
+    background: rgba(30, 41, 59, .5);
+    border: 1px solid rgba(51, 65, 85, .6);
+    color: #94a3b8;
+    border-radius: 9999px;
+    padding: .35rem .75rem;
+    font-size: .8rem;
+    font-weight: 600;
+    cursor: pointer;
+    transition: color .15s, border-color .15s, background .15s;
+}
+.fb-ach-pill:hover { color: #e2e8f0; border-color: rgba(14, 165, 233, .4); }
+.fb-ach-pill.active { color: #f8fafc; background: rgba(14, 165, 233, .15); border-color: #0ea5e9; }
+.fb-ach-pill-badge {
+    font-size: .7rem;
+    font-weight: 700;
+    color: #64748b;
+    margin-left: .15rem;
+}
+.fb-ach-pill.active .fb-ach-pill-badge { color: #7dd3fc; }
+
+/* Catalogue list. */
+.fb-ach-list { display: flex; flex-direction: column; gap: .5rem; }
+.fb-ach-item {
+    display: flex;
+    align-items: flex-start;
+    gap: .85rem;
+    padding: .75rem .9rem;
+    border-radius: .6rem;
+    border: 1px solid rgba(51, 65, 85, .5);
+    background: rgba(30, 41, 59, .35);
+}
+.fb-ach-item.locked { opacity: .45; filter: grayscale(.6); }
+.fb-ach-item.earned { border-color: rgba(14, 165, 233, .35); background: rgba(14, 165, 233, .06); }
+.fb-ach-item-icon { font-size: 1.4rem; line-height: 1.6rem; flex: 0 0 auto; }
+.fb-ach-item-body { min-width: 0; }
+.fb-ach-item-title {
+    font-size: .9rem;
+    font-weight: 700;
+    color: #f1f5f9;
+    display: flex;
+    align-items: center;
+    gap: .4rem;
+}
+.fb-ach-tier {
+    font-size: .65rem;
+    text-transform: uppercase;
+    letter-spacing: .04em;
+    font-weight: 700;
+    color: #7dd3fc;
+    border: 1px solid rgba(125, 211, 252, .35);
+    border-radius: 9999px;
+    padding: .05rem .4rem;
+}
+.fb-ach-item-desc { font-size: .78rem; color: #94a3b8; margin-top: .15rem; }
+
+/* Feats of Power trophy shelf (profile main page). */
+.fb-feat-shelf {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(150px, 1fr));
+    gap: .75rem;
+}
+.fb-feat-card {
+    text-align: center;
+    padding: 1rem .75rem;
+    border-radius: .7rem;
+    border: 1px solid rgba(234, 179, 8, .35);
+    background: linear-gradient(180deg, rgba(234, 179, 8, .1), rgba(30, 41, 59, .3));
+}
+.fb-feat-icon { font-size: 1.9rem; }
+.fb-feat-title { font-size: .85rem; font-weight: 800; color: #fde68a; margin-top: .3rem; }
+.fb-feat-desc { font-size: .72rem; color: #cbd5e1; margin-top: .25rem; }

plugins/achievements/engine.py

@@ -0,0 +1,191 @@
+"""Achievements & Feats of Power — pure evaluation helpers.
+
+This module holds the side-effect-free core of the engine so it is unit
+testable (constitution P-V): no IO, no SQLite, no clock. `routes.py` owns the
+storage/HTTP shell and calls into these functions.
+
+**Integration law (structural):** Feats are evaluated from *activity counters*
+only (`evaluate_feats` / `apply_activity`); competency Achievements are recorded
+from *competency events* the source reports (`report-unlock`). Nothing here ever
+converts an activity count into a competency unlock or vice versa.
+"""
+
+from __future__ import annotations
+
+# Counter keys the activity model owns. `*_max` keys take the running maximum;
+# everything else is a cumulative running total. Kept here (not in routes) so a
+# test can assert the contract without standing up a DB.
+MAX_COUNTERS = frozenset({"notes_session_max", "streak_insong_max", "chart_encore_max"})
+
+
+def tier_index_for(tiers, value):
+    """Highest 0-based tier index whose threshold is met by ``value``.
+
+    Returns -1 when no tier is reached. Tiers are assumed ascending; we scan
+    all of them rather than short-circuit so an out-of-order catalogue still
+    resolves to the largest satisfied tier.
+    """
+    idx = -1
+    for i, threshold in enumerate(tiers or []):
+        try:
+            if value >= threshold:
+                idx = i
+        except TypeError:
+            continue
+    return idx
+
+
+def feat_counter_value(feat, counters):
+    """Activity-counter value backing a Feat definition (0 when absent)."""
+    key = feat.get("counter")
+    if not key:
+        return 0
+    try:
+        return int(counters.get(key, 0) or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
+def evaluate_feats(feat_defs, counters):
+    """Map ``feat_id -> highest reached tier index`` for all satisfied Feats.
+
+    A Feat with no tiers, or whose counter hasn't reached tier 0, is omitted.
+    Pure: takes the current counters snapshot, returns a plain dict.
+    """
+    out = {}
+    for feat in feat_defs or []:
+        fid = feat.get("id")
+        if not fid:
+            continue
+        tiers = feat.get("tiers") or []
+        if not tiers:
+            continue
+        ti = tier_index_for(tiers, feat_counter_value(feat, counters))
+        if ti >= 0:
+            out[fid] = ti
+    return out
+
+
+def apply_activity(counters, delta):
+    """Return a NEW counters dict after folding in one activity ``delta``.
+
+    Cumulative keys add; ``*_max`` keys keep the running maximum. The caller
+    (routes.py) is responsible for the only stateful bit — the per-chart play
+    count — and passes the post-increment value as ``delta['chart_play_count']``
+    so this function stays pure.
+
+    Recognised delta fields (all optional, default 0):
+      notes            -> notes_total            (+=)
+      song_done        -> songs_done             (+=)
+      seconds          -> time_total_seconds     (+=)
+      session_notes    -> notes_session_max      (max)
+      in_song_streak   -> streak_insong_max      (max)
+      chart_play_count -> chart_encore_max       (max)
+    """
+    out = dict(counters or {})
+
+    def _cur(key):
+        try:
+            return int(out.get(key, 0) or 0)
+        except (TypeError, ValueError):
+            return 0
+
+    def _int(v):
+        try:
+            return int(v or 0)
+        except (TypeError, ValueError):
+            return 0
+
+    out["notes_total"] = _cur("notes_total") + _int(delta.get("notes"))
+    out["songs_done"] = _cur("songs_done") + _int(delta.get("song_done"))
+    out["time_total_seconds"] = _cur("time_total_seconds") + _int(delta.get("seconds"))
+    out["notes_session_max"] = max(_cur("notes_session_max"), _int(delta.get("session_notes")))
+    out["streak_insong_max"] = max(_cur("streak_insong_max"), _int(delta.get("in_song_streak")))
+    if delta.get("chart_play_count") is not None:
+        out["chart_encore_max"] = max(_cur("chart_encore_max"), _int(delta.get("chart_play_count")))
+    return out
+
+
+def consecutive_run_length(dates):
+    """Longest run of consecutive calendar dates in ``dates`` (ISO 'YYYY-MM-DD').
+
+    Used by the `secret_witching` Feat (practise in the 2–5am window on N
+    consecutive nights). Pure date arithmetic so it's unit-testable; routes.py
+    feeds it the distinct night-dates recorded in `comp_ledger`.
+    """
+    from datetime import date
+
+    parsed = []
+    for d in dates or []:
+        try:
+            y, m, dd = (int(x) for x in str(d).split("-"))
+            parsed.append(date(y, m, dd))
+        except (ValueError, TypeError):
+            continue
+    if not parsed:
+        return 0
+    parsed = sorted(set(parsed))
+    best = run = 1
+    for prev, cur in zip(parsed, parsed[1:]):
+        if (cur - prev).days == 1:
+            run += 1
+            best = max(best, run)
+        else:
+            run = 1
+    return best
+
+
+# ── Data-minimization contract (binding, code-enforced) ──────────────────────
+# The wall payload key-set is frozen here and asserted by a unit test. The
+# serializer below is the ONLY way outbound data is built — never dict(row) or
+# **model — so a stray field cannot leak. Adding a key makes the test go red.
+WALL_PAYLOAD_KEYS = ("display_name", "player_hash", "achievement_id", "unlocked_at")
+
+
+def build_wall_payload(display_name, player_hash, achievement_id, unlocked_at):
+    """Build the EXACT four-field wall payload. ``achievement_id`` must always be
+    a Feat id (the caller only ever invokes this for Feat unlocks — competency
+    never syncs). Explicit literal dict on purpose; do not refactor into a
+    row/model splat."""
+    return {
+        "display_name": display_name,
+        "player_hash": player_hash,
+        "achievement_id": achievement_id,
+        "unlocked_at": unlocked_at,
+    }
+
+
+def drain_decision(status):
+    """Dead-letter state machine for one wall-sync attempt (pure).
+
+    ``status`` is the HTTP status code, or ``None`` for a network error.
+    Returns one of:
+      'ack'   → server accepted; delete the row.
+      'retry' → keep it pending (network error, 429 backoff, or 5xx).
+      'dead'  → any other 4xx; move to dead_letter (diagnosable/replayable).
+    A row is NEVER silently dropped — it leaves the queue only on 'ack' (or a
+    user opt-out wiping it).
+    """
+    if status is None:
+        return "retry"
+    if 200 <= status < 300:
+        return "ack"
+    if status == 429:
+        return "retry"
+    if 400 <= status < 500:
+        return "dead"
+    return "retry"  # 5xx — transient server-side, try again later
+
+
+def diff_unlocks(prev_tiers, new_tiers):
+    """Feat ids whose tier advanced (incl. first unlock).
+
+    ``prev_tiers`` / ``new_tiers`` are ``feat_id -> tier_index`` maps as
+    returned by :func:`evaluate_feats`. Returns the ids that are newly present
+    or moved to a higher tier — i.e. the Feats to record + announce this round.
+    """
+    out = []
+    for fid, tier in (new_tiers or {}).items():
+        if tier > prev_tiers.get(fid, -1):
+            out.append(fid)
+    return out

plugins/achievements/feats.json

@@ -0,0 +1,101 @@
+{
+  "version": 1,
+  "feats": [
+    {
+      "id": "notes_total",
+      "title": "Note Hunter",
+      "description": "Hit a colossal number of notes across all your practice.",
+      "category": "global",
+      "sourceId": "achievements",
+      "secret": false,
+      "needs_notedetect": true,
+      "counter": "notes_total",
+      "tiers": [100000, 1000000, 10000000],
+      "tier_titles": ["Note Hunter", "Million-Note Maestro", "Ten-Million-Note Titan"]
+    },
+    {
+      "id": "notes_session",
+      "title": "Marathon",
+      "description": "Hit 25,000 notes in a single sitting.",
+      "category": "global",
+      "sourceId": "achievements",
+      "secret": false,
+      "needs_notedetect": true,
+      "counter": "notes_session_max",
+      "tiers": [25000],
+      "tier_titles": ["Marathon"]
+    },
+    {
+      "id": "streak_insong",
+      "title": "Untouchable",
+      "description": "Land a huge run of consecutive in-song hits with no miss.",
+      "category": "global",
+      "sourceId": "achievements",
+      "secret": false,
+      "needs_notedetect": true,
+      "counter": "streak_insong_max",
+      "tiers": [1000, 5000],
+      "tier_titles": ["Untouchable", "Truly Untouchable"]
+    },
+    {
+      "id": "songs_done",
+      "title": "Road Warrior",
+      "description": "Finish a mountain of songs.",
+      "category": "global",
+      "sourceId": "achievements",
+      "secret": false,
+      "needs_notedetect": false,
+      "counter": "songs_done",
+      "tiers": [1000, 5000],
+      "tier_titles": ["Road Warrior", "Road Legend"]
+    },
+    {
+      "id": "time_total",
+      "title": "Time Served",
+      "description": "Pour hundreds of hours into practice.",
+      "category": "global",
+      "sourceId": "achievements",
+      "secret": false,
+      "needs_notedetect": false,
+      "counter": "time_total_seconds",
+      "tiers": [1800000, 7200000],
+      "tier_titles": ["Time Served (500h)", "Time Served (2,000h)"]
+    },
+    {
+      "id": "chart_encore",
+      "title": "Encore",
+      "description": "Play the same chart again and again and again.",
+      "category": "global",
+      "sourceId": "achievements",
+      "secret": false,
+      "needs_notedetect": false,
+      "counter": "chart_encore_max",
+      "tiers": [100, 500],
+      "tier_titles": ["Encore", "Standing Ovation"]
+    },
+    {
+      "id": "secret_witching",
+      "title": "The Witching Hour",
+      "description": "Practise in the dead of night, seven nights running.",
+      "category": "global",
+      "sourceId": "achievements",
+      "secret": true,
+      "needs_notedetect": false,
+      "counter": "witching_nights_run",
+      "tiers": [7],
+      "tier_titles": ["The Witching Hour"]
+    },
+    {
+      "id": "secret_combo",
+      "title": "Hidden Track",
+      "description": "You found the hidden track.",
+      "category": "global",
+      "sourceId": "achievements",
+      "secret": true,
+      "needs_notedetect": false,
+      "counter": null,
+      "tiers": [],
+      "tier_titles": ["Hidden Track"]
+    }
+  ]
+}

plugins/achievements/plugin.json

@@ -0,0 +1,18 @@
+{
+  "id": "achievements",
+  "name": "Achievements",
+  "version": "0.1.0",
+  "bundled": true,
+  "private": false,
+  "description": "Achievements & Feats of Power — skill milestones on your Profile, plus rare activity Feats.",
+  "script": "screen.js",
+  "styles": "assets/achievements.css",
+  "settings": {
+    "html": "settings.html",
+    "category": "system",
+    "server_files": [
+      "achievements/"
+    ]
+  },
+  "routes": "routes.py"
+}

plugins/achievements/routes.py

@@ -0,0 +1,585 @@
+"""Achievements & Feats of Power — local engine (offline).
+
+State lives under ``<config_dir>/achievements/``:
+  - ``achievements.db``  SQLite — unlocks, activity counters, derived ledger,
+                         and the (PR3) wall sync queue.
+
+Two surfaces, one engine, kept structurally apart (the **integration law**):
+  * **Feats of Power** — activity/volume. The engine OWNS raw activity counters
+    (`counters`), evaluates Feat thresholds, and records Feat unlocks. Feats are
+    the only thing that ever syncs to the public wall.
+  * **Achievements** — demonstrated competency. The engine RECORDS unlocks the
+    source reports (`report-unlock`); it never re-derives them from activity.
+    A baseline catalogue ships here and is driven by the built-in progression
+    system; richer items are contributed by source plugins at runtime.
+
+Endpoints (all under /api/plugins/achievements/):
+  POST /activity        bump activity counters, eval Feats, return newly-unlocked
+  POST /report-unlock   idempotent upsert of a competency/feat unlock
+  POST /report-criterion record a (criterion_id, token) pair → distinct count
+  GET  /catalog         baseline competency defs + earned state
+  GET  /earned          all earned items (id, cls, category, tier, at)
+  GET  /feats           earned Feats (for the profile trophy shelf)
+  POST /remove-me       wipe synced state (full wall-removal lands in PR2/PR3)
+
+Pure threshold/criterion math lives in the sibling ``engine.py`` (P-V testable);
+this module is the SQLite + HTTP shell.
+"""
+
+import hashlib
+import json
+import logging
+import os
+import sqlite3
+import threading
+import time
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+_lock = threading.Lock()
+_state = {
+    "db_path": None,
+    "dir": None,            # plugin directory (for catalog JSON)
+    "config_dir": None,     # CONFIG_DIR (for reading the opt-in setting)
+    "meta_db": None,        # MetadataDB (for the profile identity: name + hash)
+    "log": logging.getLogger("feedBack.plugin.achievements"),
+    "engine": None,         # sibling engine.py module (pure helpers)
+    "feat_defs": [],        # parsed feats.json -> list of feat defs
+    "baseline": {},         # parsed achievements.json
+}
+
+
+# ── SQLite ──────────────────────────────────────────────────────────────────
+
+def _conn():
+    conn = sqlite3.connect(_state["db_path"], timeout=5)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    return conn
+
+
+def _init_db():
+    conn = _conn()
+    try:
+        conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS unlocks (
+                achievement_id TEXT PRIMARY KEY,
+                cls            TEXT NOT NULL,          -- 'competency' | 'feat'
+                disp_category  TEXT,                   -- global/guitar/bass/...
+                source_id      TEXT,
+                tier           INTEGER NOT NULL DEFAULT 0,
+                unlocked_at    TEXT,
+                synced         INTEGER NOT NULL DEFAULT 0
+            )
+            """
+        )
+        conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS counters (
+                key   TEXT PRIMARY KEY,
+                value INTEGER NOT NULL DEFAULT 0
+            )
+            """
+        )
+        conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS comp_ledger (
+                criterion_id TEXT NOT NULL,
+                token        TEXT NOT NULL,
+                PRIMARY KEY (criterion_id, token)
+            )
+            """
+        )
+        conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS sync_queue (
+                id      INTEGER PRIMARY KEY AUTOINCREMENT,
+                kind    TEXT NOT NULL,                 -- 'unlock' | 'remove'
+                payload TEXT NOT NULL,
+                state   TEXT NOT NULL DEFAULT 'pending' -- 'pending' | 'dead_letter'
+            )
+            """
+        )
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def _now_iso():
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def _opted_in():
+    """True only when the user has opted in (core setting ``achievements_enabled``).
+
+    Read straight from CONFIG_DIR/config.json — the single source of truth the
+    /api/settings endpoint persists. Default OFF on any read failure: nothing
+    leaves the device unless explicitly enabled.
+    """
+    try:
+        cfg_path = Path(_state["config_dir"]) / "config.json"
+        cfg = json.loads(cfg_path.read_text(encoding="utf-8"))
+        return bool(cfg.get("achievements_enabled") is True)
+    except (OSError, ValueError, TypeError):
+        return False
+
+
+def _identity():
+    """(display_name, player_hash) from the profile, or (None, None).
+
+    Reused as the wall identity (server.py's documented player_hash). Sync is
+    skipped entirely when either is missing.
+    """
+    db = _state["meta_db"]
+    if db is None or not hasattr(db, "get_profile"):
+        return None, None
+    try:
+        prof = db.get_profile() or {}
+        return (prof.get("display_name") or None), (prof.get("player_hash") or None)
+    except Exception:  # noqa: BLE001 — identity is best-effort; never break a request
+        return None, None
+
+
+def _enqueue_feat_sync(conn, feat_id, unlocked_at):
+    """Enqueue a wall-sync POST for a Feat unlock — opt-in gated, identity gated.
+
+    Builds the outbound payload through the SINGLE code-gated serializer
+    (engine.build_wall_payload, exactly four fields). Competency unlocks never
+    reach this path (integration law + data-minimization contract). The drain
+    worker (PR3) POSTs the queued rows; here we only persist intent.
+    """
+    if not _opted_in():
+        return False
+    display_name, player_hash = _identity()
+    if not display_name or not player_hash:
+        return False
+    payload = _state["engine"].build_wall_payload(display_name, player_hash, feat_id, unlocked_at)
+    conn.execute(
+        "INSERT INTO sync_queue(kind, payload, state) VALUES ('unlock', ?, 'pending')",
+        (json.dumps(payload),),
+    )
+    return True
+
+
+# ── Wall sync — background drain worker (dead-letter, never drop) ─────────────
+# Idle unless a wall URL is configured. POSTs pending rows to the hosted
+# feedback-achievements service; the decision state machine
+# (engine.drain_decision) is pure + tested. A row leaves the queue only on a
+# server ack (or a user opt-out wiping it) — never silently dropped.
+
+# Canonical hosted Feats wall (the got-feedback service). Used by default so the
+# drain worker targets it out of the box; override via env for self-hosting or a
+# staging wall. Nothing is ever sent unless the user opted in AND has an identity
+# (see _enqueue_feat_sync), so a default URL does not publish anything on its own.
+_DEFAULT_WALL_URL = "https://feedback-achievements.onrender.com"
+_WALL_URL = (os.environ.get("FEEDBACK_ACHIEVEMENTS_WALL_URL")
+             or os.environ.get("SLOPSMITH_ACHIEVEMENTS_WALL_URL")
+             or _DEFAULT_WALL_URL).rstrip("/")
+_WALL_TOKEN = os.environ.get("FEEDBACK_ACHIEVEMENTS_CLIENT_TOKEN", "fb-wall-v1")
+_DRAIN_INTERVAL_S = int(os.environ.get("FEEDBACK_ACHIEVEMENTS_DRAIN_INTERVAL", "30"))
+_drain_started = False
+
+
+def _post_to_wall(kind, payload):
+    """POST one queued item; return the HTTP status code, or None on a network
+    error. Mirrors the lib/lyrics_transcribe outbound pattern (explicit timeout,
+    no raise on non-2xx — the caller's state machine decides)."""
+    import requests  # local import: only needed when a wall is configured
+
+    path = "/api/unlock" if kind == "unlock" else "/api/remove"
+    try:
+        resp = requests.post(
+            _WALL_URL + path, json=payload,
+            headers={"X-Client-Token": _WALL_TOKEN, "Content-Type": "application/json"},
+            timeout=10,
+        )
+        return resp.status_code
+    except requests.RequestException:
+        return None
+
+
+def _drain_once(post_fn=None):
+    """Process all pending queue rows once. ``post_fn(kind, payload) -> status``
+    is injectable for tests; defaults to the real wall POST."""
+    post_fn = post_fn or _post_to_wall
+    engine = _state["engine"]
+    with _lock:
+        conn = _conn()
+        try:
+            rows = conn.execute(
+                "SELECT id, kind, payload FROM sync_queue WHERE state='pending'").fetchall()
+        finally:
+            conn.close()
+    for row in rows:
+        try:
+            payload = json.loads(row["payload"]) if row["payload"] else {}
+        except ValueError:
+            payload = {}
+        status = post_fn(row["kind"], payload)
+        action = engine.drain_decision(status)
+        with _lock:
+            conn = _conn()
+            try:
+                if action == "ack":
+                    conn.execute("DELETE FROM sync_queue WHERE id=?", (row["id"],))
+                elif action == "dead":
+                    conn.execute("UPDATE sync_queue SET state='dead_letter' WHERE id=?", (row["id"],))
+                # 'retry' → leave it pending for the next pass
+                conn.commit()
+            finally:
+                conn.close()
+
+
+def _drain_loop():
+    while True:
+        try:
+            _drain_once()
+        except Exception as e:  # noqa: BLE001 — a worker crash must not kill the thread
+            _state["log"].warning("achievements wall drain error: %s", e)
+        time.sleep(_DRAIN_INTERVAL_S)
+
+
+def _maybe_start_drain():
+    global _drain_started
+    if _drain_started or not _WALL_URL:
+        return
+    _drain_started = True
+    threading.Thread(target=_drain_loop, name="ach-wall-drain", daemon=True).start()
+    _state["log"].info("achievements wall drain worker started → %s", _WALL_URL)
+
+
+def _chart_key(chart):
+    """Stable per-chart counter key — a sha1 digest of the chart id. NOT the
+    builtin hash(), whose str hashing is salted per process (PYTHONHASHSEED), so
+    the same chart would land on a different counter after every restart and the
+    Encore Feat could never accumulate across sessions."""
+    return "chart_plays:" + hashlib.sha1(str(chart).encode("utf-8")).hexdigest()[:16]
+
+
+def _read_counters(conn):
+    # Excludes the per-chart `chart_plays:*` rows: they are bumped + read
+    # individually via _bump_counter and would otherwise make this aggregate
+    # round-trip O(distinct charts played) on every activity POST.
+    return {
+        row["key"]: int(row["value"])
+        for row in conn.execute("SELECT key, value FROM counters WHERE key NOT LIKE 'chart_plays:%'")
+    }
+
+
+def _write_counters(conn, counters):
+    for key, value in counters.items():
+        conn.execute(
+            "INSERT INTO counters(key, value) VALUES (?, ?) "
+            "ON CONFLICT(key) DO UPDATE SET value=excluded.value",
+            (key, int(value)),
+        )
+
+
+def _bump_counter(conn, key, delta):
+    """Increment a counter and return the new value (used for per-chart plays)."""
+    conn.execute(
+        "INSERT INTO counters(key, value) VALUES (?, ?) "
+        "ON CONFLICT(key) DO UPDATE SET value=value+excluded.value",
+        (key, int(delta)),
+    )
+    row = conn.execute("SELECT value FROM counters WHERE key=?", (key,)).fetchone()
+    return int(row["value"]) if row else int(delta)
+
+
+def _earned_feat_tiers(conn):
+    return {
+        row["achievement_id"]: int(row["tier"])
+        for row in conn.execute("SELECT achievement_id, tier FROM unlocks WHERE cls='feat'")
+    }
+
+
+def _record_unlock(conn, ach_id, cls, disp_category, source_id, tier, at):
+    """Idempotent upsert; only advances the tier upward. Returns True if changed."""
+    row = conn.execute("SELECT tier FROM unlocks WHERE achievement_id=?", (ach_id,)).fetchone()
+    if row is not None and int(row["tier"]) >= int(tier):
+        return False
+    conn.execute(
+        """
+        INSERT INTO unlocks(achievement_id, cls, disp_category, source_id, tier, unlocked_at, synced)
+        VALUES (?, ?, ?, ?, ?, ?, 0)
+        ON CONFLICT(achievement_id) DO UPDATE SET
+            tier=excluded.tier,
+            cls=excluded.cls,
+            disp_category=COALESCE(excluded.disp_category, unlocks.disp_category),
+            source_id=COALESCE(excluded.source_id, unlocks.source_id)
+        """,
+        (ach_id, cls, disp_category, source_id, int(tier), at or _now_iso()),
+    )
+    return True
+
+
+# ── Catalog loading ─────────────────────────────────────────────────────────
+
+def _feat_by_id(fid):
+    for f in _state["feat_defs"]:
+        if f.get("id") == fid:
+            return f
+    return None
+
+
+def _load_catalogs():
+    base = Path(_state["dir"])
+    try:
+        feats = json.loads((base / "feats.json").read_text(encoding="utf-8"))
+        _state["feat_defs"] = feats.get("feats", []) if isinstance(feats, dict) else []
+    except (OSError, ValueError) as e:
+        _state["log"].warning("achievements: could not load feats.json: %s", e)
+        _state["feat_defs"] = []
+    try:
+        _state["baseline"] = json.loads((base / "achievements.json").read_text(encoding="utf-8"))
+    except (OSError, ValueError) as e:
+        _state["log"].warning("achievements: could not load achievements.json: %s", e)
+        _state["baseline"] = {}
+
+
+# ── Request models ──────────────────────────────────────────────────────────
+
+class ActivityIn(BaseModel):
+    notes:          int = Field(ge=0, default=0)
+    session_notes:  int = Field(ge=0, default=0)
+    in_song_streak: int = Field(ge=0, default=0)
+    song_done:      int = Field(ge=0, default=0)
+    seconds:        int = Field(ge=0, default=0)
+    chart:          str | None = None
+    night_session:  bool = False
+    night_date:     str | None = None     # 'YYYY-MM-DD', frontend supplies (no server clock)
+
+
+class UnlockIn(BaseModel):
+    id:        str
+    kind:      str = "achievement"        # 'achievement' | 'feat'
+    category:  str | None = None          # display category (global/guitar/...)
+    sourceId:  str | None = None
+    tier:      int = Field(ge=0, default=0)
+    at:        str | None = None
+
+
+class CriterionIn(BaseModel):
+    criterion_id: str
+    token:        str
+
+
+# ── FastAPI wiring ──────────────────────────────────────────────────────────
+
+def setup(app, context):
+    config_dir = context["config_dir"]
+    base = Path(config_dir) / "achievements"
+    base.mkdir(parents=True, exist_ok=True)
+    _state["db_path"] = str(base / "achievements.db")
+    _state["dir"] = str(Path(__file__).resolve().parent)
+    _state["config_dir"] = str(config_dir)
+    _state["meta_db"] = context.get("meta_db")
+    _state["log"] = context.get("log") or _state["log"]
+    # Pure helpers via the per-plugin sibling loader (constitution P-III), with a
+    # plain-import fallback for pytest / standalone use.
+    load_sibling = context.get("load_sibling")
+    try:
+        _state["engine"] = load_sibling("engine") if load_sibling else __import__("engine")
+    except Exception:  # noqa: BLE001 — last-ditch, keep the plugin alive
+        import importlib.util
+        spec = importlib.util.spec_from_file_location(
+            "achievements_engine", str(Path(__file__).resolve().parent / "engine.py"))
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+        _state["engine"] = mod
+    _init_db()
+    _load_catalogs()
+    log = _state["log"]
+
+    @app.post("/api/plugins/achievements/activity")
+    def post_activity(body: ActivityIn):
+        engine = _state["engine"]
+        with _lock:
+            conn = _conn()
+            try:
+                # Per-chart play count is the only directly-stateful bit; bump it
+                # first (stable key) so apply_activity() just takes the new max.
+                chart_play_count = None
+                if body.song_done and body.chart:
+                    chart_play_count = _bump_counter(conn, _chart_key(body.chart), 1)
+                # Night-window ledger → consecutive-night run. Computed here but
+                # NOT written before the prev snapshot: it is folded into the delta
+                # below so prev_tiers reflects the OLD run and new_tiers the new one
+                # (the same asymmetry chart_encore relies on). Pre-writing it would
+                # make prev already satisfy the Feat, so diff_unlocks would never
+                # see the freshly-earned witching unlock.
+                witching_run = None
+                if body.night_session and body.night_date:
+                    conn.execute(
+                        "INSERT OR IGNORE INTO comp_ledger(criterion_id, token) VALUES ('witching', ?)",
+                        (body.night_date,),
+                    )
+                    nights = [r["token"] for r in conn.execute(
+                        "SELECT token FROM comp_ledger WHERE criterion_id='witching'")]
+                    witching_run = engine.consecutive_run_length(nights)
+
+                counters = _read_counters(conn)
+                prev_tiers = engine.evaluate_feats(_state["feat_defs"], counters)
+                new_counters = engine.apply_activity(counters, {
+                    "notes": body.notes,
+                    "session_notes": body.session_notes,
+                    "in_song_streak": body.in_song_streak,
+                    "song_done": body.song_done,
+                    "seconds": body.seconds,
+                    "chart_play_count": chart_play_count,
+                })
+                if witching_run is not None:
+                    new_counters["witching_nights_run"] = max(
+                        int(new_counters.get("witching_nights_run", 0) or 0), witching_run)
+                _write_counters(conn, new_counters)
+                new_tiers = engine.evaluate_feats(_state["feat_defs"], new_counters)
+                fresh = engine.diff_unlocks(prev_tiers, new_tiers)
+                unlocked = []
+                for fid in fresh:
+                    f = _feat_by_id(fid) or {}
+                    tier = new_tiers[fid]
+                    at = _now_iso()
+                    if _record_unlock(conn, fid, "feat", f.get("category"), f.get("sourceId"), tier, at):
+                        _enqueue_feat_sync(conn, fid, at)
+                        unlocked.append(_feat_payload(fid, f, tier))
+                conn.commit()
+                return {"ok": True, "unlocked": unlocked, "counters": new_counters}
+            finally:
+                conn.close()
+
+    @app.post("/api/plugins/achievements/report-unlock")
+    def post_report_unlock(body: UnlockIn):
+        cls = "feat" if body.kind == "feat" else "competency"
+        at = body.at or _now_iso()
+        with _lock:
+            conn = _conn()
+            try:
+                changed = _record_unlock(
+                    conn, body.id, cls, body.category, body.sourceId, body.tier, at)
+                # Only Feats sync; competency never enqueues (integration law +
+                # data-minimization contract).
+                if changed and cls == "feat":
+                    _enqueue_feat_sync(conn, body.id, at)
+                conn.commit()
+                return {"ok": True, "changed": changed, "id": body.id, "tier": body.tier}
+            finally:
+                conn.close()
+
+    @app.post("/api/plugins/achievements/report-criterion")
+    def post_report_criterion(body: CriterionIn):
+        """Record a distinct (criterion_id, token); return the distinct count.
+
+        Lets a baseline subscriber aggregate multi-event criteria (e.g. the set
+        of distinct days with a real advance → `steady_hands`) without us
+        re-deriving competency from activity. Bookkeeping over events only.
+        """
+        with _lock:
+            conn = _conn()
+            try:
+                conn.execute(
+                    "INSERT OR IGNORE INTO comp_ledger(criterion_id, token) VALUES (?, ?)",
+                    (body.criterion_id, body.token),
+                )
+                row = conn.execute(
+                    "SELECT COUNT(*) AS n FROM comp_ledger WHERE criterion_id=?",
+                    (body.criterion_id,),
+                ).fetchone()
+                conn.commit()
+                return {"ok": True, "count": int(row["n"]) if row else 0}
+            finally:
+                conn.close()
+
+    @app.get("/api/plugins/achievements/catalog")
+    def get_catalog():
+        with _lock:
+            conn = _conn()
+            try:
+                earned = _earned_map(conn)
+            finally:
+                conn.close()
+        return {"baseline": _state["baseline"], "earned": earned}
+
+    @app.get("/api/plugins/achievements/earned")
+    def get_earned():
+        with _lock:
+            conn = _conn()
+            try:
+                return {"earned": list(_earned_map(conn).values())}
+            finally:
+                conn.close()
+
+    @app.get("/api/plugins/achievements/feats")
+    def get_feats():
+        with _lock:
+            conn = _conn()
+            try:
+                rows = conn.execute(
+                    "SELECT achievement_id, tier, unlocked_at FROM unlocks WHERE cls='feat'"
+                ).fetchall()
+            finally:
+                conn.close()
+        out = []
+        for row in rows:
+            fid = row["achievement_id"]
+            f = _feat_by_id(fid) or {}
+            payload = _feat_payload(fid, f, int(row["tier"]))
+            payload["unlocked_at"] = row["unlocked_at"]
+            out.append(payload)
+        return {"feats": out}
+
+    @app.post("/api/plugins/achievements/remove-me")
+    def post_remove_me():
+        # Local removal works offline: drop the synced flag so nothing re-syncs,
+        # and enqueue a wall removal (drained in PR3). The wall identity
+        # (player_hash) is resolved server-side at drain time, not stored here.
+        _, player_hash = _identity()
+        with _lock:
+            conn = _conn()
+            try:
+                conn.execute("UPDATE unlocks SET synced=0 WHERE cls='feat'")
+                # Enqueue a wall removal only when we have an identity to key it
+                # by; the drain worker (below) POSTs it. Idempotent server-side.
+                if player_hash:
+                    conn.execute(
+                        "INSERT INTO sync_queue(kind, payload, state) VALUES ('remove', ?, 'pending')",
+                        (json.dumps({"player_hash": player_hash}),),
+                    )
+                conn.commit()
+                return {"ok": True}
+            finally:
+                conn.close()
+
+    _maybe_start_drain()
+    log.info("achievements engine ready (%d feats, baseline v%s)",
+             len(_state["feat_defs"]), str(_state["baseline"].get("version", "?")))
+
+
+def _feat_payload(fid, feat, tier):
+    titles = feat.get("tier_titles") or []
+    title = titles[tier] if 0 <= tier < len(titles) else feat.get("title", fid)
+    return {
+        "id": fid,
+        "cls": "feat",
+        "tier": tier,
+        "title": title,
+        "description": feat.get("description", ""),
+        "category": feat.get("category", "global"),
+        "secret": bool(feat.get("secret", False)),
+    }
+
+
+def _earned_map(conn):
+    out = {}
+    for row in conn.execute(
+        "SELECT achievement_id, cls, disp_category, tier, unlocked_at FROM unlocks"
+    ):
+        out[row["achievement_id"]] = {
+            "id": row["achievement_id"],
+            "cls": row["cls"],
+            "category": row["disp_category"],
+            "tier": int(row["tier"]),
+            "unlocked_at": row["unlocked_at"],
+        }
+    return out

plugins/achievements/screen.js

@@ -0,0 +1,395 @@
+/*
+ * Achievements & Feats of Power — frontend engine (vanilla, constitution P-II).
+ *
+ * Renders into the two core Profile mount points (achievements epic):
+ *   #v3-profile-feats-slot        → earned Feats trophy shelf (hidden-until-earned)
+ *   #v3-profile-achievements-mount → full competency catalogue (locked = greyed),
+ *                                    grouped by instrument via a secondary pill row.
+ * Re-injects on every `v3:profile-rendered` (core wipes the mounts each render).
+ *
+ * Also exposes the cross-plugin registration API `window.feedBack.achievements`
+ * (v1) so source plugins (Virtuoso, notedetect, …) contribute competency defs +
+ * report unlocks without us hardcoding their vocabulary. Load-order safe via the
+ * `window.__feedBackAchievementsPending` queue + `achievements:ready` event.
+ *
+ * INTEGRATION LAW: Feats read activity counters only (we POST batched activity on
+ * song:ended); competency Achievements are evaluated from progression EVENTS only.
+ * The two paths never cross.
+ */
+(function () {
+    'use strict';
+
+    var API = '/api/plugins/achievements';
+    var bus = window.feedBack;
+    if (!bus) return;  // bus must exist (capabilities.js); nothing to attach to.
+
+    var esc = function (s) {
+        return String(s == null ? '' : s).replace(/[&<>"']/g, function (c) {
+            return { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c];
+        });
+    };
+
+    // ── State ────────────────────────────────────────────────────────────────
+    var registered = {};   // id -> def (contributed + expanded baseline defs)
+    var earned = {};       // id -> { tier, cls, category }
+    var baseline = null;   // /catalog baseline blob
+    var CAT_KEY = 'achievements:profile-cat';  // P-III: plugin localStorage keys prefixed with plugin id
+    var INSTRUMENTS = ['guitar', 'bass', 'drums', 'keys'];
+
+    function progState() {
+        return (window.v3Progression && window.v3Progression.get()) || null;
+    }
+    function notedetectPresent() {
+        return typeof window.createNoteDetector === 'function';
+    }
+
+    // ── Backend I/O ──────────────────────────────────────────────────────────
+    function fetchJSON(path, opts) {
+        return fetch(API + path, opts).then(function (r) { return r.ok ? r.json() : null; }).catch(function () { return null; });
+    }
+    function postUnlock(def, tier) {
+        return fetch(API + '/report-unlock', {
+            method: 'POST', headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                id: def.id, kind: def.kind || 'achievement',
+                category: def.category || 'global', sourceId: def.sourceId || 'achievements',
+                tier: tier || 0,
+            }),
+        }).then(function (r) { return r.ok ? r.json() : null; }).catch(function () { return null; });
+    }
+    function refreshEarned() {
+        return fetchJSON('/earned').then(function (data) {
+            earned = {};
+            ((data && data.earned) || []).forEach(function (e) { earned[e.id] = e; });
+        });
+    }
+
+    // ── Tier math (mirrors engine.tier_index_for) ────────────────────────────
+    function tierIndexFor(tiers, value) {
+        var idx = -1;
+        (tiers || []).forEach(function (t, i) { if (value >= t) idx = i; });
+        return idx;
+    }
+    function alreadyEarnedAtLeast(id, tier) {
+        var e = earned[id];
+        return e && e.tier >= tier;
+    }
+
+    // ── Registration API (v1) ────────────────────────────────────────────────
+    function register(def) {
+        if (!def || !def.id) return;
+        registered[def.id] = {
+            id: def.id, kind: def.kind || 'achievement', category: def.category || 'global',
+            title: def.title || def.id, description: def.description || '',
+            secret: !!def.secret, sourceId: def.sourceId || 'unknown',
+        };
+        scheduleRender();
+    }
+    function registerAll(defs) { (defs || []).forEach(register); }
+    function unlock(id, opts) {
+        var def = registered[id] || { id: id, kind: 'achievement', category: 'global', sourceId: 'unknown' };
+        var tier = (opts && opts.tier) || 0;
+        if (alreadyEarnedAtLeast(id, tier)) return Promise.resolve();
+        return postUnlock(def, tier).then(function () {
+            return refreshEarned().then(function () {
+                // A contributed Feat unlock would enqueue a wall sync here when
+                // opted-in (PR2/PR3); competency never syncs (integration law).
+                scheduleRender();
+            });
+        });
+    }
+    function progress() { /* accepted, optional — display is greyed/earned, not bars */ }
+
+    var api = { version: 1, register: register, registerAll: registerAll, unlock: unlock, progress: progress };
+    bus.achievements = api;
+    // Drain sources that loaded before us (minigames pending-queue pattern).
+    try { (window.__feedBackAchievementsPending || []).forEach(function (fn) {
+        try { typeof fn === 'function' ? fn(api) : register(fn); } catch (_) { /* noop */ }
+    }); } catch (_) { /* noop */ }
+    window.__feedBackAchievementsPending = null;
+    try { bus.emit && bus.emit('achievements:ready', { version: 1 }); } catch (_) { /* noop */ }
+
+    // ── Baseline competency: evaluate from progression EVENTS only ────────────
+    function expandBaseline() {
+        // Register baseline defs (always present — built-in progression is always
+        // present) so they render greyed even before they're earned. Per-instrument
+        // templates expand across the REAL paths that exist (auto-extends).
+        if (!baseline) return;
+        (baseline.global || []).forEach(function (d) {
+            register({ id: d.id, kind: 'achievement', category: 'global', title: d.title,
+                description: d.description, sourceId: 'achievements' });
+        });
+        var paths = (progState() && progState().paths) || [];
+        var pathIds = paths.length ? paths.map(function (p) { return { id: p.id, name: p.name }; })
+            : INSTRUMENTS.map(function (i) { return { id: i, name: i.charAt(0).toUpperCase() + i.slice(1) }; });
+        (baseline.per_instrument || []).forEach(function (tpl) {
+            pathIds.forEach(function (pi) {
+                var inst = pi.name;
+                register({
+                    id: tpl.id + ':' + pi.id, kind: 'achievement', category: pi.id,
+                    title: (tpl.title || '').replace(/\{Inst\}/g, inst),
+                    description: (tpl.description || '').replace(/\{Inst\}/g, inst),
+                    sourceId: 'achievements',
+                });
+            });
+        });
+    }
+
+    function evaluateBaseline() {
+        var prog = progState();
+        if (!prog || !baseline) return;
+        var defById = {};
+        (baseline.global || []).forEach(function (d) { defById[d.id] = d; });
+
+        // mastery_rank → first_steps / ascendant
+        (baseline.global || []).forEach(function (d) {
+            var crit = d.criterion || {};
+            if (crit.type === 'mastery_rank') {
+                var ti = tierIndexFor(crit.tiers || d.tiers, prog.mastery_rank || 0);
+                if (ti >= 0) baselineUnlock(d.id, 'global', ti);
+            } else if (crit.type === 'paths_at_level') {
+                var n = ((prog.paths) || []).filter(function (p) { return (p.level || 0) >= (crit.level || 10); }).length;
+                var ti2 = tierIndexFor(crit.tiers || d.tiers, n);
+                if (ti2 >= 0) baselineUnlock(d.id, 'global', ti2);
+            }
+        });
+
+        // per-instrument path_rank → reach Lv 10/25/max in that path
+        var tpl = (baseline.per_instrument || []).filter(function (t) { return t.id === 'path_rank'; })[0];
+        if (tpl) {
+            ((prog.paths) || []).forEach(function (p) {
+                var thresholds = (tpl.criterion && tpl.criterion.tiers) || [10, 25, 'max'];
+                var resolved = thresholds.map(function (t) { return t === 'max' ? (p.max_level || 9999) : t; });
+                var ti = tierIndexFor(resolved, p.level || 0);
+                if (ti >= 0) baselineUnlock('path_rank:' + p.id, p.id, ti);
+            });
+        }
+    }
+
+    function baselineUnlock(id, category, tier) {
+        if (alreadyEarnedAtLeast(id, tier)) return;
+        var def = registered[id] || { id: id, kind: 'achievement', category: category, sourceId: 'achievements' };
+        postUnlock(def, tier).then(function () { refreshEarned().then(scheduleRender); });
+    }
+
+    // Local calendar date 'YYYY-MM-DD' (one source of truth for both the
+    // steady-hands day ledger and the witching-night date below).
+    function localISODate(d) {
+        d = d || new Date();
+        return d.getFullYear() + '-' + String(d.getMonth() + 1).padStart(2, '0') + '-' + String(d.getDate()).padStart(2, '0');
+    }
+
+    // growth-streak + challenger record on real competency events (date ledger /
+    // distinct challenge sets) — kept as bookkeeping over EVENTS, never activity.
+    function recordGrowthDay() {
+        var iso = localISODate();
+        fetchJSON('/report-criterion', {
+            method: 'POST', headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ criterion_id: 'steady_hands_days', token: iso }),
+        }).then(function (res) {
+            if (!res) return;
+            var d = ((baseline && baseline.global) || []).filter(function (x) { return x.id === 'steady_hands'; })[0];
+            var ti = tierIndexFor((d && d.tiers) || [7, 30, 100], res.count || 0);
+            if (ti >= 0) baselineUnlock('steady_hands', 'global', ti);
+        });
+    }
+
+    // ── Activity (Feats): in-memory session counters, flushed on song:ended ───
+    var session = { notesTotal: 0 };           // cumulative across this sitting
+    // `active` gates note counting to an actual song in progress — without it,
+    // note:hit/miss from the tuner or input-calibration would inflate Feats from
+    // non-song input and flush a phantom streak with chart:null.
+    var song = { hits: 0, streak: 0, maxStreak: 0, chart: null, active: false };
+    function resetSong(chart) { song = { hits: 0, streak: 0, maxStreak: 0, chart: chart || null, active: true }; }
+
+    function flushActivity(seconds) {
+        if (!song.active) return;   // no active song → nothing to flush (ignore stray events)
+        song.active = false;
+        // No notedetect → song.hits stays 0; notes-based Feats simply don't move
+        // (graceful degradation). song_done / seconds / chart still flow so the
+        // notedetect-free Feats (Road Warrior, Time Served, Encore) progress.
+        var hour = new Date().getHours();
+        var isNight = hour >= 2 && hour < 5;
+        var iso = localISODate();
+        var body = {
+            notes: song.hits,
+            session_notes: session.notesTotal,
+            in_song_streak: song.maxStreak,
+            song_done: 1,
+            seconds: Math.max(0, Math.round(seconds || 0)),
+            chart: song.chart,
+            night_session: isNight,
+            night_date: isNight ? iso : null,
+        };
+        fetchJSON('/activity', {
+            method: 'POST', headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        }).then(function (res) {
+            if (res && res.unlocked && res.unlocked.length) {
+                // A Feat just unlocked — refresh the shelf + toast via the bus.
+                fetchFeatsAndRender();
+                res.unlocked.forEach(function (f) {
+                    try { bus.emit && bus.emit('achievements:feat-unlocked', f); } catch (_) { /* noop */ }
+                });
+            }
+        });
+    }
+
+    // ── Rendering ────────────────────────────────────────────────────────────
+    var _renderQueued = false;
+    function scheduleRender() {
+        if (_renderQueued) return;
+        _renderQueued = true;
+        (window.requestAnimationFrame || window.setTimeout)(function () { _renderQueued = false; renderAll(); }, 0);
+    }
+
+    function renderAll() {
+        renderCatalog();
+        fetchFeatsAndRender();
+    }
+
+    function categoriesForDisplay() {
+        var cats = [{ id: 'global', name: 'Global' }];
+        var paths = (progState() && progState().paths) || [];
+        if (paths.length) {
+            paths.forEach(function (p) { cats.push({ id: p.id, name: p.name }); });
+        } else {
+            // Fallback before progression loads: show the known instrument cats
+            // that actually have registered items.
+            INSTRUMENTS.forEach(function (i) {
+                if (Object.keys(registered).some(function (id) { return registered[id].category === i; })) {
+                    cats.push({ id: i, name: i.charAt(0).toUpperCase() + i.slice(1) });
+                }
+            });
+        }
+        return cats;
+    }
+
+    function itemsForCategory(catId) {
+        return Object.keys(registered).map(function (id) { return registered[id]; })
+            .filter(function (d) { return (d.category || 'global') === catId; })
+            // Hide un-earned secret items (revealed only once earned).
+            .filter(function (d) { return !d.secret || earned[d.id]; });
+    }
+
+    function renderCatalog() {
+        var mount = document.getElementById('v3-profile-achievements-mount');
+        if (!mount) return;
+        // Hide the core empty-state note now that we own this mount.
+        var emptyNote = document.querySelector('[data-empty-for="v3-profile-achievements-mount"]');
+        if (emptyNote) emptyNote.style.display = 'none';
+
+        var cats = categoriesForDisplay();
+        var saved = null;
+        try { saved = localStorage.getItem(CAT_KEY); } catch (_) { /* noop */ }
+        // Default to the player's primary path (first path), fallback Global.
+        var primary = (progState() && progState().paths && progState().paths[0] && progState().paths[0].id) || 'global';
+        var active = cats.some(function (c) { return c.id === saved; }) ? saved
+            : (cats.some(function (c) { return c.id === primary; }) ? primary : 'global');
+
+        var pills = cats.map(function (c) {
+            var items = itemsForCategory(c.id);
+            var got = items.filter(function (d) { return earned[d.id]; }).length;
+            return '<button type="button" class="fb-ach-pill' + (c.id === active ? ' active' : '') +
+                '" data-cat="' + esc(c.id) + '">' + esc(c.name) +
+                ' <span class="fb-ach-pill-badge">' + got + '/' + items.length + '</span></button>';
+        }).join('');
+
+        var items = itemsForCategory(active);
+        var list = items.length ? items.map(function (d) {
+            var got = !!earned[d.id];
+            var tier = got ? (earned[d.id].tier || 0) : -1;
+            return '<div class="fb-ach-item' + (got ? ' earned' : ' locked') + '">' +
+                '<div class="fb-ach-item-icon">' + (got ? '🏅' : '🔒') + '</div>' +
+                '<div class="fb-ach-item-body">' +
+                '<div class="fb-ach-item-title">' + esc(d.title) +
+                (got && tier > 0 ? ' <span class="fb-ach-tier">tier ' + (tier + 1) + '</span>' : '') + '</div>' +
+                '<div class="fb-ach-item-desc">' + esc(d.description) + '</div>' +
+                '</div></div>';
+        }).join('') : '<p class="fb-tabpanel-empty">No achievements in this category yet.</p>';
+
+        mount.innerHTML =
+            '<div class="fb-ach-pillrow">' + pills + '</div>' +
+            '<div class="fb-ach-list">' + list + '</div>';
+        mount.querySelectorAll('[data-cat]').forEach(function (b) {
+            b.addEventListener('click', function () {
+                try { localStorage.setItem(CAT_KEY, b.dataset.cat); } catch (_) { /* noop */ }
+                renderCatalog();
+            });
+        });
+    }
+
+    function fetchFeatsAndRender() {
+        return fetchJSON('/feats').then(function (data) { renderFeats((data && data.feats) || []); });
+    }
+
+    function renderFeats(feats) {
+        var slot = document.getElementById('v3-profile-feats-slot');
+        if (!slot) return;
+        if (!feats.length) { slot.innerHTML = ''; return; }  // hidden-until-earned
+        var cards = feats.map(function (f) {
+            return '<div class="fb-feat-card" title="' + esc(f.description) + '">' +
+                '<div class="fb-feat-icon">🏆</div>' +
+                '<div class="fb-feat-title">' + esc(f.title) + '</div>' +
+                '<div class="fb-feat-desc">' + esc(f.description) + '</div>' +
+                '</div>';
+        }).join('');
+        // Opt-out users get a subtle wall hint linking to Settings (PR2 wires it).
+        var hint = '';
+        slot.innerHTML =
+            '<div class="bg-fb-card/80 backdrop-blur rounded-xl p-6 border border-fb-border/50">' +
+            '<h3 class="text-lg font-bold text-fb-text mb-3">Feats of Power</h3>' +
+            '<div class="fb-feat-shelf">' + cards + '</div>' + hint +
+            '</div>';
+    }
+
+    // ── Boot ─────────────────────────────────────────────────────────────────
+    function init() {
+        fetchJSON('/catalog').then(function (data) {
+            baseline = (data && data.baseline) || {};
+            ((data && data.earned) && (earned = {}, Object.keys(data.earned).forEach(function (id) { earned[id] = data.earned[id]; })));
+            expandBaseline();
+            evaluateBaseline();
+            scheduleRender();
+        });
+        // Re-inject on every profile entry (core wipes the mounts each render).
+        document.addEventListener('v3:profile-rendered', function () { renderAll(); });
+
+        // Competency events → re-expand (paths may have appeared) + re-evaluate.
+        ['progression:updated', 'progression:rank-changed', 'progression:path-level-up'].forEach(function (ev) {
+            bus.on && bus.on(ev, function () { expandBaseline(); evaluateBaseline(); });
+        });
+        // A real competency advance ticks the growth-streak day ledger.
+        ['progression:rank-changed', 'progression:path-level-up', 'progression:challenge-completed'].forEach(function (ev) {
+            bus.on && bus.on(ev, function () { recordGrowthDay(); });
+        });
+        // challenger:<inst> — clearing a full level-up set for a path.
+        bus.on && bus.on('progression:path-level-up', function (e) {
+            var pid = e && e.detail && (e.detail.path_id || e.detail.id);
+            if (pid) baselineUnlock('challenger:' + pid, pid, 0);
+        });
+
+        // Activity (Feats) — in-memory counters, flushed once per song.
+        bus.on && bus.on('song:loading', function (e) {
+            resetSong(e && e.detail && e.detail.filename);
+        });
+        bus.on && bus.on('note:hit', function () {
+            if (!song.active) return;   // ignore tuner/calibration note events
+            song.hits++; song.streak++; session.notesTotal++;
+            if (song.streak > song.maxStreak) song.maxStreak = song.streak;
+        });
+        bus.on && bus.on('note:miss', function () { if (song.active) song.streak = 0; });
+        bus.on && bus.on('song:ended', function (e) {
+            flushActivity(e && e.detail && (e.detail.time || e.detail.audioT));
+        });
+        // Song stopped/abandoned without a natural end → mark inactive so stray
+        // note events after it don't accrue against a phantom (chart:null) song.
+        bus.on && bus.on('song:stop', function () { song.active = false; });
+    }
+
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', init, { once: true });
+    } else {
+        init();
+    }
+})();

plugins/achievements/settings.html

@@ -0,0 +1,68 @@
+<!-- Achievements plugin — Privacy panel (mounts under the Settings "System" tab
+     via settings.category). Owns the wall opt-in toggle (bound to the core
+     `achievements_enabled` setting) + the self-serve "Remove me from the wall"
+     action. Default OFF — nothing publishes until the user opts in. -->
+<div class="text-sm text-gray-300 space-y-4" data-ach-privacy>
+  <div>
+    <p>Your <strong>Achievements</strong> and <strong>Feats of Power</strong> live on your
+       <em>Profile</em> page and are local &amp; private by default.</p>
+  </div>
+
+  <label class="flex items-start gap-3 cursor-pointer">
+    <input type="checkbox" id="setting-achievements-enabled"
+           class="mt-1 h-4 w-4 rounded border-gray-600 bg-gray-800 text-sky-500 focus:ring-sky-500">
+    <span>
+      <span class="font-medium text-gray-200">Share my Feats of Power on the public wall</span>
+      <span class="block text-gray-400">Publishes only your display name and the rare
+        <strong>Feats</strong> you earn (activity milestones) — never songs, skills, or scores.
+        You can turn this off and remove yourself at any time.</span>
+    </span>
+  </label>
+
+  <div>
+    <button type="button" id="ach-remove-me"
+            class="px-3 py-1.5 rounded-md text-sm border border-red-500/40 text-red-300 hover:bg-red-500/10 transition">
+      Remove me from the wall
+    </button>
+    <span id="ach-remove-status" class="ml-2 text-xs text-gray-400"></span>
+  </div>
+</div>
+
+<script>
+(function () {
+    var root = document.currentScript && document.currentScript.previousElementSibling;
+    // The panel re-injects on each Settings entry; bind once per element.
+    var toggle = document.getElementById('setting-achievements-enabled');
+    if (!toggle || toggle.dataset.wired === '1') return;
+    toggle.dataset.wired = '1';
+
+    // Hydrate from the authoritative server setting.
+    fetch('/api/settings').then(function (r) { return r.ok ? r.json() : {}; }).then(function (d) {
+        toggle.checked = d && d.achievements_enabled === true;
+    }).catch(function () { /* offline — leave unchecked */ });
+
+    toggle.addEventListener('change', function () {
+        var on = !!toggle.checked;
+        try { localStorage.setItem('achievementsEnabled', on ? '1' : '0'); } catch (_) {}
+        fetch('/api/settings', {
+            method: 'POST', headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ achievements_enabled: on }),
+        }).catch(function () { /* best-effort; revert on failure */ });
+    });
+
+    var removeBtn = document.getElementById('ach-remove-me');
+    var status = document.getElementById('ach-remove-status');
+    if (removeBtn) {
+        removeBtn.addEventListener('click', function () {
+            removeBtn.disabled = true;
+            if (status) status.textContent = 'Removing…';
+            fetch('/api/plugins/achievements/remove-me', { method: 'POST' })
+                .then(function (r) {
+                    if (status) status.textContent = r.ok ? 'Removed. Your Feats stay on your Profile.' : 'Could not reach the server — try again.';
+                })
+                .catch(function () { if (status) status.textContent = 'Offline — queued; it will sync when you reconnect.'; })
+                .finally(function () { removeBtn.disabled = false; });
+        });
+    }
+})();
+</script>

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/folder_library/CLAUDE.md

@@ -0,0 +1,345 @@
+# Folder Library — AI Agent Guide
+
+A FeedBack (fee[dB]ack) plugin that adds a **Folders** nav screen showing your `.sloppak` / `.feedpak` DLC songs grouped by the folder tree on disk. Create, rename, and delete folders (including **nested subfolders**) directly in the UI, move songs by drag-and-drop, and browse with sort and metadata filters.
+
+> The host app is **FeedBack** (formerly "Slopsmith"). The frontend talks to the host through `window.feedBack`; `window.slopsmith` is a back-compat alias the host still exposes (`window.slopsmith = window.feedBack` in `static/app.js`). New code should prefer `window.feedBack`.
+
+> ⚠️ **Status — bundled core plugin.** This plugin began as a standalone plugin and is now a bundled core plugin. `screen.js` has been unified into a **single surface factory** driving two entry points: the v3 library Folder view (host chrome — host search `#v3-search`/`#lib-filter`, host filter params, renders into `#lib-folder-tree`) and the classic v2 standalone Folders nav-tab (its own `#fb-search` + toolbar, renders into `#fb-tree`). **Folder search works on both surfaces** — typing in the relevant search box re-renders the tree. **Loose-folder songs** (directories with audio + an arrangement XML) are recognised as songs via the host `loosefolder.is_loose_song` predicate, so they appear in the tree alongside `.sloppak`/`.feedpak` bundles. Folder management, nested subfolders, collapsible folders + expand/collapse-all, drag-and-drop, move-song, sort, filters, and the hover metadata badges are wired on both surfaces; verify against a running build before relying on any of it.
+
+## File Structure
+
+```
+plugin.json     Plugin manifest — id, name, nav entry, file declarations ("bundled": true core plugin)
+routes.py       FastAPI backend — recursive DLC scan, folder tree + filters, folder/song mutations, two-level cache
+screen.html     Plugin screen content — injected by the host into the plugin div automatically
+screen.js       Frontend logic — recursive folder tree, search, sort, filters, drag-and-drop, modals
+README.md       User-facing docs
+```
+
+## Architecture
+
+This plugin follows the standard FeedBack plugin pattern (see the repo-root `CLAUDE.md` for the full plugin system reference).
+
+- **Backend** (`routes.py`) — registers routes under `GET/POST /api/plugins/folder_library/`. Uses `context["get_dlc_dir"]()`, `context["extract_meta"]()`, and `context["log"]`. Scans `<dlc>/sloppak/` if it exists, otherwise `<dlc>/`. Recursively walks the tree and handles create/rename/delete folder and move-song operations on slash-separated folder paths.
+- **Frontend** (`screen.js`) — plain vanilla JS in an IIFE. Fetches the tree from the backend on screen load, recursively renders collapsible folder sections (any depth) and song rows or cards (grid view). Uses `window.feedBack.on('screen:changed', ...)` (via the `window.slopsmith` alias) to trigger load when the user navigates here. Calls `window.playSong(filename)` on song click with the full relative path from the DLC root.
+- **No dependencies** — no npm, no build step. Tailwind utility classes available globally from the host; the plugin uses only core-guaranteed utilities and inline styles, so it ships **no** `styles` manifest key.
+
+## Critical Layout Lessons (Hard-Won)
+
+These are non-obvious behaviours of the FeedBack desktop app (Electron) that took significant debugging to discover. They still apply unchanged.
+
+### 1. Do NOT put an outer wrapper div in screen.html
+The host automatically creates `<div id="plugin-folder_library" class="screen">` and injects `screen.html` content inside it. If you add your own outer div with `class="screen"`, you get a nested screen element which gets `display:none` applied, hiding all content.
+
+**Wrong:**
+```html
+<div id="plugin-folder_library" class="screen">
+  <div>toolbar</div>
+  <div>content</div>
+</div>
+```
+
+**Correct:**
+```html
+<!-- no outer wrapper — the host provides it -->
+<div>toolbar</div>
+<div>content</div>
+```
+
+### 2. The .screen CSS class sets display:none by default
+`.screen { display: none }` and `.screen.active { display: block }`. There is no height set. The screen div gets its height purely from its content. Do not try to set height via CSS classes — use inline styles or JS if needed.
+
+### 3. The host navbar is position:fixed with z-index:50
+The navbar sits at `top:0, z-index:50`. Plugin toolbars must use `position:fixed; top:64px; z-index:40` to sit below the navbar. Use a solid `background-color` (not Tailwind bg classes — those may not apply correctly) to prevent content showing through.
+
+### 4. Content must have padding-top to clear the fixed toolbar
+Since the toolbar is `position:fixed`, it floats above the content. The content container needs enough `padding-top` (~120px) to ensure the first item isn't hidden behind the toolbar — the host navbar (64px) plus the plugin toolbar height (~56px). Adding more toolbar buttons increases this height, so if content is clipped, increase the padding further.
+
+### 5. Electron blocks window.prompt() and window.confirm()
+The desktop app is built on Electron, which throws `Error: prompt() is not supported`. Use a custom inline modal instead. See `_showModal()` in `screen.js` — it returns a Promise and supports both text input and confirm modes.
+
+### 6. The nav plugin dropdown has z-index:50 and blocks clicks
+When navigating to a plugin screen via the Plugins dropdown, the dropdown stays open and sits on top of the screen. Call `_closeDropdown()` on screen load to dismiss it. The dropdown element id is `plugin-dropdown`.
+
+### 7. playSong() expects a relative path from the DLC root
+`window.playSong()` expects the path relative to the DLC root with forward slashes, e.g. `sloppak/CH/Artist - Title.sloppak`. Not just the filename. The backend builds this in `_meta()` via `"/".join(p.relative_to(dlc).parts)` and returns it as each song's `filename`.
+
+### 8. FastAPI POST routes need `from fastapi import Request`
+Routes that receive a JSON body must import `Request` from fastapi explicitly and use `async def route(request: Request)` with `body = await request.json()`. Missing this import crashes the server on plugin load.
+
+### 9. Plugin id must be consistent everywhere
+The plugin id (`folder_library`) must match in:
+- `plugin.json` → `"id"` and `"nav.screen"`
+- `screen.js` → `PLUGIN_ID` constant and `API` constant (`/api/plugins/folder_library`)
+- `routes.py` → `APIRouter(prefix="/api/plugins/folder_library")`
+
+A mismatch in any of these causes silent failures (blank screen, 404 API calls).
+
+### 10. Use inline styles for grid layout, not Tailwind
+Tailwind's `grid` and `grid-cols-*` classes may not apply reliably inside the plugin div. Use `element.style.cssText` with explicit `display:grid; grid-template-columns:...` for the grid container.
+
+## Key Conventions
+
+- **IIFE + `'use strict'`** — all frontend code wrapped in `(function(){ 'use strict'; ... })();`
+- **localStorage prefixes** — plugin keys are prefixed `fo:` (e.g. `fo:view`, `fo:sort`, `fo:filters`); host-library-synced filter state uses `fo:lib:`. Open-folder state is tracked by **folder path** (so nested folders each remember their own state).
+- **Safe storage access** — all `localStorage` reads/writes wrapped in try/catch
+- **Logging** — backend uses `context["log"]`, never `print()`
+- **Sibling imports** — use `context["load_sibling"]("name")` not bare `import name` (none needed today; keep this in mind if you add helper modules)
+
+## Song Formats
+
+The plugin treats both `.sloppak` and `.feedpak` as songs (`_is_song()` in `routes.py`). `feedpak` is the published name for the same on-disk format the codebase still calls `sloppak` internally — see the repo-root `CLAUDE.md`. Both file form (`.sloppak`/`.feedpak` zip) and directory form (`*.sloppak/` folder) are recognized.
+
+## Backend Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/plugins/folder_library/tree` | Returns the folder tree. Accepts optional filter query params (below) applied server-side. |
+| POST | `/api/plugins/folder_library/folder/create` | Body: `{name, parent?}` — creates a subfolder; `parent` (slash path) nests it inside an existing folder, omit/empty for top level |
+| POST | `/api/plugins/folder_library/folder/rename` | Body: `{old, new}` — `old` is a slash path, `new` is a bare name; renames within the same parent |
+| POST | `/api/plugins/folder_library/folder/delete` | Body: `{name}` (slash path) — moves all songs at any depth to the scan root, then removes the folder |
+| POST | `/api/plugins/folder_library/song/move` | Body: `{filename, folder}` — moves a song to `folder` (slash path; empty = scan root / "Unsorted") |
+
+### `/tree` filter query params
+
+All optional, applied server-side over the cached full tree by `_apply_tree_filters()`. Comma-separated, case-insensitive:
+
+- `arrangements_has`, `arrangements_lacks` — include/exclude by arrangement name
+- `stems_has`, `stems_lacks` — include/exclude by stem name
+- `has_lyrics` — `""` (any), `"1"`, or `"0"`
+- `tunings` — comma-separated tuning names to include
+
+The frontend forwards the host library's active filter params here (via `window.feedBackLibFilterParams()` when present, with `window.slopsmithLibFilterParams()` as a legacy fallback) so the Folders view can stay in sync with the main library filters, falling back to its own filter panel state otherwise.
+
+### Path safety
+
+`_safe_name()` rejects empty names, leading/trailing whitespace, the characters `\ / : * ? " < > |`, and `.`/`..`. `_safe_path()` applies `_safe_name()` to every slash-separated segment, so traversal (`..`) and absolute paths are rejected before any filesystem op. Always validate user-supplied folder paths through these before touching disk.
+
+## Tree Shape
+
+`/tree` returns:
+
+```json
+{
+  "folders": [
+    {
+      "name": "CH",
+      "path": "CH",
+      "songs": [ /* song objects */ ],
+      "children": [
+        { "name": "Live", "path": "CH/Live", "songs": [], "children": [] }
+      ]
+    }
+  ],
+  "root_songs": [ /* songs sitting directly in the scan root — shown as "Unsorted" */ ]
+}
+```
+
+Folder nodes are **recursive**: each has `name`, `path` (slash-separated, relative to the scan root), `songs`, and `children`. The frontend renders any depth — `_findFolderByPath()`, `_countDeep()`, and `_countFoldersDeep()` walk the `children` arrays.
+
+## Song Metadata Format
+
+Each song object (built by `_meta()`):
+
+```json
+{
+  "filename": "sloppak/CH/Artist - Title.sloppak",
+  "title": "Title",
+  "artist": "Artist",
+  "album": "Album Name",
+  "duration": 213.5,
+  "year": 1993,
+  "tuning": "E Standard",
+  "added": 1748132400.0,
+  "arrangements": ["Lead", "Rhythm", "Bass"],
+  "stems": ["Drums", "Bass", "Vocals"],
+  "lyrics": true
+}
+```
+
+- `filename` is the full relative path from the DLC root — pass it directly to `window.playSong()`.
+- `added` is a Unix timestamp (float, seconds) from `stat().st_mtime` — convert with `new Date(added * 1000)`. Always recomputed fresh (it changes when a file moves), even on a metadata-cache hit.
+- `arrangements` / `stems` are flat lists of **strings**, even though `extract_meta()` returns them as objects.
+
+### extract_meta returns arrangements/stems as objects, not strings
+
+`context["extract_meta"]()` returns arrangements as a list of objects `{index, name, notes}`, not plain strings; stems similarly. `_meta()` normalizes to `.name`:
+
+```python
+raw_arr = raw.get("arrangements") or []
+m["arrangements"] = [
+    a["name"] if isinstance(a, dict) else str(a)
+    for a in raw_arr
+    if (isinstance(a, dict) and "name" in a) or isinstance(a, str)
+]
+```
+
+`lyrics` is coerced to a bool from several possible keys (`lyrics`, `hasLyrics`, `has_lyrics`, …). If you add new metadata fields from `extract_meta`, check the raw shape before assuming it's a plain value.
+
+## Two-Level Cache
+
+`routes.py` keeps two caches inside `setup()`:
+
+- **`_meta_cache`** — expensive `extract_meta()` results keyed by absolute POSIX path. **Never cleared.** When files move (rename/delete/move), the keys are rewritten in-place so the warm data survives the operation.
+- **`_cache`** — the assembled tree structure (`folders` / `root_songs`). Cleared by `_invalidate()` on **every** mutation so the next `/tree` rebuilds it — but the rebuild is fast because `_meta_cache` is still warm.
+
+`filename` and `added` are deliberately **not** stored in `_meta_cache` (they depend on the file's current location) — they're recomputed on every `_meta()` call and merged onto the cached copy. When you add a mutation route, mirror the existing key-rewrite logic (see `rename_folder`, `delete_folder`, `move_song`) so the metadata cache stays valid.
+
+## Folder Scan Logic
+
+`routes.py` scans recursively starting at `<dlc>/sloppak/` (or `<dlc>/` if no `sloppak` subdir exists):
+- Files/dirs matching `.sloppak` or `.feedpak` → song entries (root-level ones go to `root_songs`, shown as "Unsorted")
+- Subdirectories → recursive folder nodes with their own `songs` + `children`
+- Dot-prefixed entries are skipped; empty folders are still included (shown with a 0 count)
+
+To add more grouping options (by artist, album, etc.), build an alternative projection over the scanned songs rather than the on-disk tree.
+
+## Library provider (future, not implemented)
+
+This plugin surfaces folders as a dedicated **view** over the existing library;
+it does not (yet) register itself as a selectable library **source/provider**.
+If you want a "Folders" entry to appear in the host's main library-source
+picker (mapping top-level folder → "artist", subfolder → "album"), implement a
+provider exposing the source-aware contract (`query_page`, `query_artists`,
+`query_stats`, `tuning_names`) and register it in `setup()` via
+`context["register_library_provider"](...)`, unregistering on teardown. (An
+earlier inert `FolderLibraryProvider` scaffold was removed — it was never wired
+and only duplicated the scan logic; re-add it only alongside real registration
+and tests.)
+
+## View Modes (List / Grid)
+
+The toolbar has a list/grid toggle. Current view is stored in `localStorage` under `fo:view` (`'list'` or `'grid'`).
+
+- **List view** — `_songRow()`, rendered inside a `ml-5 space-y-0` div
+- **Grid view** — `_songCard()`, rendered inside a CSS grid div (`auto-fill, minmax(150px,1fr)`)
+- Both the folder and unsorted section renderers branch on `_view` to pick the right renderer and container
+- Album art is fetched via `/api/song/<encoded-path>/art` where each path segment is individually `encodeURIComponent`-encoded. On error the `<img>` is hidden and a placeholder SVG is shown
+- The collapse/expand toggle restores `display:grid` (not just `display:''`) when reopening a folder in grid mode — always check this when changing toggle logic
+
+### Lazy folder rendering
+
+Folders do **not** render their song list on initial load. The folder renderer sets a `_listPopulated` flag and only populates the list the first time a folder is opened, keeping the initial render fast with large libraries. When search is active all folders are forced open and populated immediately (search overrides lazy loading).
+
+## Sort System
+
+The toolbar has a sort select (`#fb-sort`) and a direction toggle (`#fb-sort-dir`). State is stored under `fo:sort` and `fo:sortDir`.
+
+- `_sort` — `'default' | 'title' | 'artist' | 'duration' | 'year' | 'tuning' | 'added'`
+- `_sortDir` — `'asc' | 'desc'`
+- `_sortSongs(songs)` returns a sorted copy; direction is applied by reversing after sort. Returns the array unchanged when `_sort === 'default'`.
+- The sort direction button is dimmed (`opacity: 0.35`) and non-interactive when sort is `'default'`.
+
+## Filter System
+
+Client-side filters are stored under `fo:filters` as a JSON object. (The server `/tree` endpoint can also filter — see Backend Routes — used to sync with the host library.)
+
+### Filter state shape
+
+```js
+_filters = {
+    arrangements: { Lead: 'on', Bass: 'exclude', Rhythm: 'off' },
+    stems:        { Drums: 'off' },
+    lyrics:       'off',   // 'off' | 'on' | 'exclude'
+    tunings:      ['E Standard', 'Eb Standard'],
+}
+```
+
+Each arrangement/stem value is `'off' | 'on' | 'exclude'`.
+
+### Include vs exclude logic
+
+`_matchFilters(song)` uses **OR logic for includes, AND logic for excludes**:
+
+- **Include (`'on'`)** — song passes if it has *at least one* selected arrangement/stem. More includes widens the result set.
+- **Exclude (`'exclude'`)** — each excluded tag independently removes songs that have it. More excludes narrows the result set.
+
+This matches standard multi-select filter UX (Spotify/library style).
+
+### Data-driven filter panel
+
+All filter sections are built from the actual library data — nothing is hardcoded:
+
+- `_getArrangements()` — unique arrangement names sorted by frequency (most common first), then alphabetically
+- `_getStems()` — same pattern for stem names
+- `_getAvailableFilters()` — returns `{ arrangements, stems, lyrics, tuning }` booleans gating the lyrics/tuning sections
+
+Non-standard arrangement names (e.g. `"Bonus"`) appear as pills automatically — no constants to update. The stems section only appears if at least one song has stems data.
+
+### Split pill UI
+
+`_makeSplitPill(label, state, onChange)` renders a two-zone pill:
+- Left zone (label) — toggles `'off' ↔ 'on'` (include, blue)
+- Right zone (`✕`) — toggles `'off' ↔ 'exclude'` (exclude, red)
+
+The filter badge (`#fb-filter-badge`) shows the active filter count via `_activeFilterCount()`.
+
+## Hover Badges
+
+Each song row/card has two hidden hover-reveal layers, built once and toggled via CSS `max-height` + `opacity` transitions.
+
+### `_badge(text, active, type)`
+
+Renders a single metadata badge. Type controls the inactive colour:
+
+| type | inactive border | inactive text |
+|---|---|---|
+| `'arrangement'` | amber `#92400e` | amber `#fcd34d` |
+| `'stem'` | violet `#5b21b6` | violet `#c4b5fd` |
+| `'lyrics'` | rose `#9f1239` | rose `#fda4af` |
+| `'tuning'` | teal `#0f766e` | teal `#5eead4` |
+
+Active state is always blue (`#1d4ed8` fill, `#3b82f6` border, white text) regardless of type.
+
+### `_buildSongBadges(song)`
+
+Builds the badge row (arrangements, stems, lyrics, tuning), deduplicating within each category. Clicking a badge toggles that filter on/off and re-renders. Returns `null` if the song has no filterable metadata.
+
+### `_buildSongDateInfo(song)`
+
+Builds a separate plain-text hover line showing `year · date added` (e.g. `1993  ·  24 May 2026`), `#cbd5e1` text. Always shown on hover regardless of filter state.
+
+### Reveal / hide
+
+```js
+_revealBadges(el)  // max-height:120px, opacity:1, margin-top:4px
+_hideBadges(el)    // max-height:0, opacity:0, margin-top:0
+```
+
+Both badge layers (badges + date-info) are wired to the same `mouseenter`/`mouseleave` events on the row or card element.
+
+## Drag-and-Drop
+
+Drag-and-drop uses **pointer events** (mousedown/mousemove/mouseup), not the HTML5 DnD API. HTML5 DnD blocks wheel events and gives unreliable edge positions inside Electron — pointer events give full control.
+
+- `_makeDraggable(el, song, folderName)` — attaches a `mousedown` listener. A drag goes "live" only after the pointer moves more than `_DRAG_THRESH` (5 px), preventing accidental drags on clicks.
+- Once live, a ghost `div` follows the cursor. Auto-scroll activates when the pointer is within `_DRAG_ZONE` (150 px) of the viewport top/bottom.
+- `_makeDropTarget(el, targetFolder)` — sets `data-dropFolder` so an element can receive drops. Both folder headers and song-list containers are drop targets — including **nested** folders (drop onto a subfolder header moves the song there).
+- `_dragFindTarget(x, y)` — uses `document.elementsFromPoint` to find the topmost element with `data-dropFolder` under the cursor.
+- **Esc to cancel** — `_onDragKeyDown` calls `_endPointerDrag()` on `Escape`, removing the ghost and clearing state without dropping.
+- On a successful drop, `_executeDrop()` does an **optimistic UI update** (moves the song in the in-memory tree and re-renders) then calls `/song/move`. On API failure it reloads the full tree.
+- A one-time `click` capture listener after mouseup suppresses the post-drag click so it doesn't trigger playback.
+
+## Modal Behaviour
+
+`_showModal(msg, withInput, defaultVal)` is the custom modal used for all prompts and confirms (Electron blocks `window.prompt()` / `window.confirm()`). It returns a Promise.
+
+- `_confirm(msg)` — resolves `true` on OK, `null` on cancel
+- `_prompt(msg, default)` — resolves the trimmed input string on OK, `null` on cancel
+- **Esc cancels** — resolves with `null`, same as Cancel (applies to rename, delete, create folder/subfolder, move song)
+- **Enter confirms** — submits, equivalent to OK
+
+## Roadmap
+
+Implemented since the original release: **nested subfolders** (recursive tree + create-inside-folder), drag-and-drop, sort, advanced filtering, server-side tree filtering synced to the host library, and the warm metadata cache.
+
+Not yet implemented, in rough priority order:
+
+- **Auto-play on hover** — with an on/off toggle saved to localStorage.
+- **Bulk move** — multi-select songs and move them all at once.
+- **Thumbnail performance** — faster loading and smoother scrolling with large libraries.
+- **Adjustable thumbnail/row sizes** — user-resizable song cards and list rows.
+- **Custom themes** — switchable colour schemes.
+- **Favoriting songs** — likely a new backend route plus a `fo:favorites` localStorage key.
+- **Editing song metadata** — edit title, artist, album etc. in-plugin; needs new backend write routes.
+- **Folders as a library source** — register a library provider so a "Folders" entry appears in the host's main library-source picker (see "Library provider (future)" above).

plugins/folder_library/README.md

@@ -0,0 +1,100 @@
+# Folder Library — FeedBack Plugin
+
+![Core plugin](https://img.shields.io/badge/fee%5BdB%5Dack-core%20plugin-blue)
+![Platform](https://img.shields.io/badge/platform-fee%5BdB%5Dack-darkblue)
+
+A FeedBack (fee[dB]ack) plugin that organizes your `.sloppak` / `.feedpak` DLC songs into a folder tree, grouped by the folders on disk. Browse your whole library visually with album art, nest folders as deep as you like, switch between list and grid layouts, and manage folders without ever leaving the app.
+
+---
+
+## Screenshots
+
+![Grid view](assets/grid-view.webp)
+*Grid view — album art cards with title and artist*
+
+![Grid search](assets/grid-search.png)
+*Live search filters instantly across all folders*
+
+![List view](assets/list-view.png)
+*List view — compact rows with album art thumbnails and duration*
+
+![New folder](assets/new-folder.png)
+*Create and manage folders directly in the UI*
+
+---
+
+> **Status — migrating to core.** Folder Library is being reworked from a standalone plugin into a bundled core plugin, and several previously-shipped features are not currently wired up in core (see the Roadmap). The list below reflects what works today; if something here is wrong, it's because this rework is still in progress.
+
+## Features
+
+- **List & Grid views** — toggle between a compact list with thumbnails or a full album art card grid
+- **Album art** — pulls art automatically for every song in both views
+- **One-click playback** — click any song to start playing immediately
+- **Sort options** — sort songs by title, artist, duration, year, tuning, or recently added with an asc/desc toggle
+- **Advanced filters** — filter by arrangements, stems, lyrics, and tuning with include and exclude support
+- **Folder management** — create, rename, and delete folders without leaving the plugin
+- **Nested subfolders** — organize as deep as you want; create a subfolder inside any folder, expand/collapse a whole branch in one click
+- **Collapsible folders** — expand/collapse individual folders, plus Expand All / Collapse All
+- **Move songs** — reassign any song to a different folder on the fly; press `Esc` to cancel
+- **Drag-and-drop** — drag songs between folders (including into nested folders) with smooth auto-scroll; press `Esc` to cancel
+- **Fast with big libraries** — folder song lists render lazily and metadata is cached so reopening folders is instant
+
+---
+
+## Installation
+
+Folder Library ships bundled with FeedBack as a core plugin (`"bundled": true`), so there's nothing to install — the **Folders** screen appears in the navbar under **Plugins** automatically.
+
+---
+
+## Usage
+
+| Action | How |
+|--------|-----|
+| Switch to grid view | Click the grid icon in the toolbar |
+| Switch to list view | Click the list icon in the toolbar |
+| Play a song | Click any song row or card |
+| Sort songs | Use the sort dropdown in the toolbar |
+| Toggle sort direction | Click the arrow button next to the sort dropdown |
+| Open filters | Click the filter icon in the toolbar |
+| Filter by arrangement/stem | Open filters → click a pill to include; click `✕` to exclude |
+| Clear all filters | Open filters → click "Clear all" |
+| Create a folder | Click the folder+ icon in the toolbar |
+| Create a subfolder | Hover a folder header → click the new-subfolder icon |
+| Rename a folder | Hover the folder header → click the pencil icon |
+| Delete a folder | Hover the folder header → click the trash icon (songs move up to Unsorted) |
+| Move a song | Hover the song row → click the folder icon |
+| Drag a song to a folder | Click and hold a song → drag to a folder header or body (nested folders work too) |
+| Cancel a drag | Press `Esc` while holding a song |
+| Cancel a move dialog | Press `Esc` in the move prompt |
+| Expand / collapse a folder | Click the folder header |
+| Expand / collapse all subfolders | Use the expand/collapse-children buttons on a folder with subfolders |
+
+---
+
+## Changelog
+
+Folder Library started life as a standalone plugin with its own version line, but it's now a **bundled core plugin** that ships with FeedBack. Its changes are tracked alongside the app in the repo-root [CHANGELOG.md](../../CHANGELOG.md), and it versions with the app rather than on its own. The **Features** section above reflects what's in the current build.
+
+---
+
+## Roadmap
+
+- [ ] Auto play song on hover (with an on/off toggle)
+- [ ] Bulk move — select multiple songs and move them at once
+- [ ] Thumbnail performance — faster loading and smoother scrolling with large song libraries
+- [ ] Adjustable thumbnail and row sizes — resize song cards and list rows to suit your preference
+- [ ] Custom themes — switch between colour schemes to match your style
+- [ ] Favoriting songs
+- [ ] Editing song metadata
+
+---
+
+## Contributing
+
+Pull requests are welcome. For major changes please open an issue first to discuss what you'd like to change.
+
+1. Fork the repo
+2. Create a feature branch (`git checkout -b feature/your-feature`)
+3. Commit your changes
+4. Push to the branch and open a pull request

plugins/folder_library/plugin.json

@@ -0,0 +1,10 @@
+{
+  "id": "folder_library",
+  "name": "Folder Library",
+  "version": "1.8.0",
+  "bundled": true,
+  "nav": { "label": "Folders", "screen": "plugin-folder_library" },
+  "screen": "screen.html",
+  "script": "screen.js",
+  "routes": "routes.py"
+}

plugins/folder_library/routes.py

@@ -0,0 +1,440 @@
+"""
+Folder Library plugin — routes.py
+
+Surfaces the DLC folder structure as a navigable tree and provides in-app
+folder management (create / rename / delete) and song moves. Every filesystem
+mutation is confined to DLC_DIR and validated against path traversal.
+"""
+
+from pathlib import Path
+from fastapi import APIRouter, Request
+from fastapi.responses import JSONResponse
+import shutil
+import re
+
+
+# ── Pure, testable helpers ─────────────────────────────────────────────────
+
+_UNSAFE_NAME_RE = re.compile(r'[\\/:*?"<>|]')
+
+
+def _safe_name(name: str) -> bool:
+    """A single path segment is safe: no separators, no traversal dot-names,
+    no surrounding whitespace, no characters illegal across filesystems."""
+    if not name or name.strip() != name:
+        return False
+    if _UNSAFE_NAME_RE.search(name):
+        return False
+    if name in (".", ".."):
+        return False
+    return True
+
+
+def _safe_path(path_str: str) -> bool:
+    """A slash-separated path is safe iff every segment is a safe name."""
+    if not path_str:
+        return False
+    return all(_safe_name(p) for p in path_str.split("/"))
+
+
+def _is_within(root: Path, candidate: Path) -> bool:
+    """True iff ``candidate`` resolves to a location inside ``root`` (after
+    normalising ``..`` and symlinks). Containment backstop for file moves so a
+    crafted filename can't escape DLC_DIR even past the segment validator."""
+    try:
+        candidate.resolve().relative_to(root.resolve())
+        return True
+    except (ValueError, OSError):
+        return False
+
+
+def _path_to_dir(root: Path, folder_path: str) -> Path:
+    """Resolve a slash-separated folder path relative to ``root``."""
+    result = root
+    for part in folder_path.split("/"):
+        result = result / part
+    return result
+
+
+def _load_is_loose_song():
+    """The host's authoritative loose-folder predicate (lib/loosefolder.py),
+    imported lazily so the plugin still loads if it's ever unavailable. A
+    loose-folder song is a directory carrying audio + an arrangement XML rather
+    than a ``.sloppak`` bundle, so the plain suffix check below misses it."""
+    try:
+        from loosefolder import is_loose_song
+        return is_loose_song
+    except Exception:
+        return None
+
+
+_IS_LOOSE_SONG = _load_is_loose_song()
+
+
+def _is_song(p: Path) -> bool:
+    """A song carrier is a ``.sloppak`` / ``.feedpak`` file or directory-form
+    bundle (extension on the leaf name), or a host-recognised loose-folder song
+    directory — so loose-folder charts surface in the tree like any other song
+    instead of being walked into as if they were ordinary folders."""
+    if p.suffix.lower() in (".sloppak", ".feedpak"):
+        return True
+    if _IS_LOOSE_SONG is not None and p.is_dir():
+        try:
+            return bool(_IS_LOOSE_SONG(p))
+        except Exception:
+            return False
+    return False
+
+
+def setup(app, context):
+    log = context["log"]
+    router = APIRouter(prefix="/api/plugins/folder_library")
+
+    # ── Two-level cache ────────────────────────────────────────────────
+    # _meta_cache  — expensive extract_meta() results keyed by abs path
+    #                (as_posix() string).  Never cleared; keys are updated
+    #                in-place when files are moved so the data stays valid.
+    # _cache       — tree structure ("folders" / "root_songs").  Cleared on
+    #                every mutation so the next /tree request rebuilds it —
+    #                but that rebuild is now fast because _meta_cache is warm.
+    _cache      = {}   # "tree" → JSONResponse-ready dict
+    _meta_cache = {}   # abs_posix_path → extracted meta (no filename/added)
+
+    def _invalidate():
+        """Clear the tree structure cache only.  _meta_cache is preserved."""
+        _cache.clear()
+
+    def _dlc_root() -> Path | None:
+        try:
+            return Path(context["get_dlc_dir"]())
+        except Exception:
+            return None
+
+    def _scan_root(dlc: Path) -> Path:
+        sloppak = dlc / "sloppak"
+        return sloppak if sloppak.exists() else dlc
+
+    def _meta(p: Path, dlc: Path) -> dict:
+        # filename and added are always computed fresh — they change when files move.
+        try:
+            filename = "/".join(p.relative_to(dlc).parts)
+        except ValueError:
+            filename = p.name
+        added = None
+        try:
+            added = p.stat().st_mtime
+        except Exception:
+            pass
+
+        # Return cached extracted metadata if available.
+        cache_key = p.as_posix()
+        if cache_key in _meta_cache:
+            m = dict(_meta_cache[cache_key])   # shallow copy
+            m["filename"] = filename
+            m["added"]    = added
+            return m
+
+        # Cache miss — run the expensive extract.
+        m = {"title": None, "artist": None, "album": None, "duration": None,
+             "year": None, "tuning": None, "arrangements": [], "stems": [], "lyrics": False}
+        try:
+            raw = context["extract_meta"](p)
+            if raw:
+                m["title"]    = raw.get("title")    or raw.get("name")
+                m["artist"]   = raw.get("artist")   or raw.get("artistName")
+                m["album"]    = raw.get("album")     or raw.get("albumName")
+                m["duration"] = raw.get("duration")
+                m["year"]     = raw.get("year")
+                m["tuning"]   = raw.get("tuning")
+
+                # arrangements — objects with a "name" key e.g. [{name:"Lead",...}, ...]
+                raw_arr = raw.get("arrangements") or []
+                if isinstance(raw_arr, (list, tuple)):
+                    m["arrangements"] = [
+                        a["name"] if isinstance(a, dict) else str(a)
+                        for a in raw_arr
+                        if (isinstance(a, dict) and "name" in a) or isinstance(a, str)
+                    ]
+
+                # stems — may also be objects with a "name" key, same as arrangements
+                raw_stems = raw.get("stems") or []
+                for _key in ("stems", "stem_types", "available_stems", "stemTypes"):
+                    _v = raw.get(_key)
+                    if _v:
+                        raw_stems = _v
+                        break
+                if isinstance(raw_stems, (list, tuple)):
+                    m["stems"] = [
+                        a["name"] if isinstance(a, dict) else str(a)
+                        for a in raw_stems
+                        if (isinstance(a, dict) and "name" in a) or isinstance(a, str)
+                    ]
+
+                # lyrics — try common key variants
+                for _key in ("lyrics", "hasLyrics", "has_lyrics", "lyric", "hasLyric"):
+                    _val = raw.get(_key)
+                    if _val is not None:
+                        if isinstance(_val, str):
+                            m["lyrics"] = _val.lower() not in ("", "false", "no", "0")
+                        else:
+                            m["lyrics"] = bool(_val)
+                        break
+        except Exception as exc:
+            log.debug("meta failed for %s: %s", p.name, exc)
+        if not m["title"]:
+            m["title"] = p.stem
+
+        _meta_cache[cache_key] = m      # store without filename/added
+        result = dict(m)
+        result["filename"] = filename
+        result["added"]    = added
+        return result
+
+    def _scan_dir(path: Path, root: Path, dlc: Path) -> dict:
+        """Recursively scan a directory and return a folder node."""
+        songs = []
+        children = []
+        try:
+            for entry in sorted(path.iterdir(), key=lambda p: p.name.lower()):
+                if entry.name.startswith("."):
+                    continue
+                if _is_song(entry):
+                    songs.append(_meta(entry, dlc))
+                elif entry.is_dir():
+                    children.append(_scan_dir(entry, root, dlc))
+        except PermissionError:
+            log.warning("permission denied: %s", path)
+        try:
+            rel = path.relative_to(root)
+            folder_path = "/".join(rel.parts)
+        except ValueError:
+            folder_path = path.name
+        return {
+            "name": path.name,
+            "path": folder_path,
+            "songs": songs,
+            "children": children,
+        }
+
+    def _apply_tree_filters(tree, arrangements_has="", arrangements_lacks="",
+                            stems_has="", stems_lacks="", has_lyrics="", tunings=""):
+        """Filter a cached tree dict by arrangement/stem/lyrics/tuning params.
+        The cache always holds the full unfiltered tree; this is applied per-request."""
+        def _split(s):
+            return [x.strip().lower() for x in s.split(",") if x.strip()] if s else []
+
+        arr_has   = _split(arrangements_has)
+        arr_lacks = _split(arrangements_lacks)
+        st_has    = _split(stems_has)
+        st_lacks  = _split(stems_lacks)
+        tun_set   = set(_split(tunings))
+        lyr       = None if has_lyrics == "" else (has_lyrics == "1")
+
+        if not any([arr_has, arr_lacks, st_has, st_lacks, tun_set, lyr is not None]):
+            return tree  # no filters active — return as-is
+
+        def _song_ok(s):
+            arrs = [a.lower() for a in (s.get("arrangements") or [])]
+            stms = [x.lower() for x in (s.get("stems") or [])]
+            if arr_has   and not any(a in arrs for a in arr_has):   return False
+            if arr_lacks and     any(a in arrs for a in arr_lacks): return False
+            if st_has    and not any(x in stms for x in st_has):    return False
+            if st_lacks  and     any(x in stms for x in st_lacks):  return False
+            if lyr is not None and bool(s.get("lyrics")) != lyr:    return False
+            if tun_set and (s.get("tuning") or "").lower() not in tun_set: return False
+            return True
+
+        def _filter_node(node):
+            return {
+                "name": node["name"],
+                "path": node["path"],
+                "songs": [s for s in node["songs"] if _song_ok(s)],
+                "children": [_filter_node(c) for c in node.get("children", [])],
+            }
+
+        return {
+            "folders": [_filter_node(f) for f in tree["folders"]],
+            "root_songs": [s for s in tree["root_songs"] if _song_ok(s)],
+        }
+
+    @router.get("/tree")
+    def get_tree(
+        arrangements_has:   str = "",
+        arrangements_lacks: str = "",
+        stems_has:          str = "",
+        stems_lacks:        str = "",
+        has_lyrics:         str = "",
+        tunings:            str = "",
+    ):
+        if "tree" not in _cache:
+            dlc = _dlc_root()
+            if not dlc or not dlc.exists():
+                return JSONResponse({"folders": [], "root_songs": [],
+                                     "error": "DLC directory not found"})
+            root = _scan_root(dlc)
+            log.info("folder_library: scanning %s", root)
+            folders = []
+            root_songs = []
+            try:
+                for entry in sorted(root.iterdir(), key=lambda p: p.name.lower()):
+                    if entry.name.startswith("."):
+                        continue
+                    if _is_song(entry):
+                        root_songs.append(_meta(entry, dlc))
+                    elif entry.is_dir():
+                        folders.append(_scan_dir(entry, root, dlc))
+            except PermissionError:
+                return JSONResponse({"folders": [], "root_songs": [],
+                                     "error": "Permission denied"})
+            _cache["tree"] = {"folders": folders, "root_songs": root_songs}
+
+        result = _apply_tree_filters(
+            _cache["tree"], arrangements_has, arrangements_lacks,
+            stems_has, stems_lacks, has_lyrics, tunings,
+        )
+        return JSONResponse(result)
+
+    @router.post("/folder/create")
+    async def create_folder(request: Request):
+        body = await request.json()
+        name = (body.get("name") or "").strip()
+        parent = (body.get("parent") or "").strip()
+        if not _safe_name(name):
+            return JSONResponse({"error": "Invalid folder name"}, status_code=400)
+        if parent and not _safe_path(parent):
+            return JSONResponse({"error": "Invalid parent path"}, status_code=400)
+        dlc = _dlc_root()
+        if not dlc:
+            return JSONResponse({"error": "DLC dir not found"}, status_code=500)
+        root = _scan_root(dlc)
+        parent_dir = _path_to_dir(root, parent) if parent else root
+        if parent and not parent_dir.exists():
+            return JSONResponse({"error": "Parent folder not found"}, status_code=404)
+        target = parent_dir / name
+        if target.exists():
+            return JSONResponse({"error": "Folder already exists"}, status_code=400)
+        try:
+            target.mkdir(parents=False)
+            _invalidate()
+            return JSONResponse({"ok": True})
+        except Exception as e:
+            return JSONResponse({"error": str(e)}, status_code=500)
+
+    @router.post("/folder/rename")
+    async def rename_folder(request: Request):
+        body = await request.json()
+        old = (body.get("old") or "").strip()
+        new = (body.get("new") or "").strip()
+        if not _safe_path(old) or not _safe_name(new):
+            return JSONResponse({"error": "Invalid folder name"}, status_code=400)
+        dlc = _dlc_root()
+        if not dlc:
+            return JSONResponse({"error": "DLC dir not found"}, status_code=500)
+        root = _scan_root(dlc)
+        src = _path_to_dir(root, old)
+        dst = src.parent / new  # rename within the same parent
+        if not src.exists():
+            return JSONResponse({"error": "Folder not found"}, status_code=404)
+        if dst.exists():
+            return JSONResponse({"error": "Name already taken"}, status_code=400)
+        try:
+            # Pre-compute meta cache key updates (keys change because the
+            # folder path changes — all files under src get a new prefix).
+            old_prefix = src.as_posix() + "/"
+            new_prefix = dst.as_posix() + "/"
+            meta_updates = {
+                key: new_prefix + key[len(old_prefix):]
+                for key in list(_meta_cache)
+                if key.startswith(old_prefix)
+            }
+            src.rename(dst)
+            _invalidate()
+            for old_key, new_key in meta_updates.items():
+                if old_key in _meta_cache:
+                    _meta_cache[new_key] = _meta_cache.pop(old_key)
+            return JSONResponse({"ok": True})
+        except Exception as e:
+            return JSONResponse({"error": str(e)}, status_code=500)
+
+    @router.post("/folder/delete")
+    async def delete_folder(request: Request):
+        body = await request.json()
+        name = (body.get("name") or "").strip()
+        if not _safe_path(name):
+            return JSONResponse({"error": "Invalid folder path"}, status_code=400)
+        dlc = _dlc_root()
+        if not dlc:
+            return JSONResponse({"error": "DLC dir not found"}, status_code=500)
+        root = _scan_root(dlc)
+        target = _path_to_dir(root, name)
+        if not target.exists():
+            return JSONResponse({"error": "Folder not found"}, status_code=404)
+        try:
+            # Relocate every song (at any depth) up to the scan root BEFORE
+            # removing the folder. Colliding filenames are de-duplicated so a
+            # name clash never leaves a song behind to be destroyed by rmtree
+            # (the folder is advertised as "moves its songs to Unsorted").
+            for song_path in sorted(target.rglob("*")):
+                if not song_path.exists():
+                    continue  # a parent song-dir was already relocated
+                if not _is_song(song_path):
+                    continue
+                old_key = song_path.as_posix()
+                dest = root / song_path.name
+                if dest.exists():
+                    stem, suffix = song_path.stem, song_path.suffix
+                    n = 1
+                    while dest.exists():
+                        dest = root / f"{stem} ({n}){suffix}"
+                        n += 1
+                song_path.rename(dest)
+                if old_key in _meta_cache:
+                    _meta_cache[dest.as_posix()] = _meta_cache.pop(old_key)
+            shutil.rmtree(target)
+            _invalidate()
+            return JSONResponse({"ok": True})
+        except Exception as e:
+            return JSONResponse({"error": str(e)}, status_code=500)
+
+    @router.post("/song/move")
+    async def move_song(request: Request):
+        body = await request.json()
+        filename = (body.get("filename") or "").strip()
+        dest_folder = (body.get("folder") or "").strip()
+        # Validate the source path like the folder ops, AND confirm it resolves
+        # inside DLC_DIR — without this a filename such as "../../etc/passwd"
+        # would be renamed (moved) into the served library and become readable.
+        if not filename or not _safe_path(filename):
+            return JSONResponse({"error": "Invalid filename"}, status_code=400)
+        dlc = _dlc_root()
+        if not dlc:
+            return JSONResponse({"error": "DLC dir not found"}, status_code=500)
+        src = dlc / Path(*filename.split("/"))
+        if not _is_within(dlc, src):
+            return JSONResponse({"error": "Invalid filename"}, status_code=400)
+        if not src.exists():
+            return JSONResponse({"error": "Song not found"}, status_code=404)
+        root = _scan_root(dlc)
+        if dest_folder:
+            if not _safe_path(dest_folder):
+                return JSONResponse({"error": "Invalid folder path"}, status_code=400)
+            dst_dir = _path_to_dir(root, dest_folder)
+            if not dst_dir.exists():
+                return JSONResponse({"error": "Destination folder not found"}, status_code=404)
+        else:
+            dst_dir = root
+        dst = dst_dir / src.name
+        if dst.exists():
+            return JSONResponse({"error": "File already exists at destination"}, status_code=400)
+        try:
+            old_key = src.as_posix()
+            src.rename(dst)
+            if old_key in _meta_cache:
+                _meta_cache[dst.as_posix()] = _meta_cache.pop(old_key)
+            _invalidate()
+            return JSONResponse({"ok": True})
+        except Exception as e:
+            return JSONResponse({"error": str(e)}, status_code=500)
+
+    app.include_router(router)
+    log.info("folder_library routes registered")

plugins/folder_library/screen.html

@@ -0,0 +1,159 @@
+<!-- Folder Browser — screen.html
+     Slopsmith injects this into a div#plugin-folder_library.screen automatically.
+     Do NOT add an outer wrapper div with class="screen". -->
+
+<!-- ── toolbar ──────────────────────────────────────────────────────── -->
+<div class="flex items-center gap-2 px-4 py-3 border-b border-dark-400 flex-wrap"
+     style="position:fixed; top:64px; left:0; right:0; z-index:40; background-color:#0f1117; border-bottom: 1px solid #1f2937;">
+
+  <h2 class="text-base font-semibold text-white mr-1">Folders</h2>
+
+  <!-- search -->
+  <div class="relative flex-1 min-w-40 max-w-xs">
+    <svg class="absolute left-2.5 top-1/2 -translate-y-1/2 w-3.5 h-3.5 text-gray-500 pointer-events-none"
+         viewBox="0 0 20 20" fill="currentColor">
+      <path fill-rule="evenodd"
+            d="M8 4a4 4 0 100 8 4 4 0 000-8zM2 8a6 6 0 1110.89 3.476l4.817 4.817a1 1 0 01-1.414 1.414l-4.816-4.816A6 6 0 012 8z"
+            clip-rule="evenodd"/>
+    </svg>
+    <input id="fb-search" type="text" placeholder="Search songs…"
+           class="w-full pl-8 pr-3 py-1.5 rounded bg-dark-500 border border-dark-400
+                  text-sm text-gray-200 placeholder-gray-500
+                  focus:outline-none focus:border-blue-500 focus:ring-1 focus:ring-blue-500"/>
+  </div>
+
+  <!-- new folder -->
+  <button id="fb-new-folder" title="New parent folder"
+          class="p-1.5 rounded text-gray-400 hover:text-white hover:bg-dark-400 transition-colors">
+    <svg viewBox="0 0 20 20" fill="currentColor" class="w-4 h-4">
+      <path d="M2 6a2 2 0 012-2h5l2 2h5a2 2 0 012 2v6a2 2 0 01-2 2H4a2 2 0 01-2-2V6z"/>
+      <path fill-rule="evenodd" d="M10 9a1 1 0 011 1v1h1a1 1 0 110 2h-1v1a1 1 0 11-2 0v-1H8a1 1 0 110-2h1v-1a1 1 0 011-1z" clip-rule="evenodd"/>
+    </svg>
+  </button>
+
+  <!-- expand all -->
+  <button id="fb-expand-all" title="Expand all"
+          class="p-1.5 rounded text-gray-400 hover:text-white hover:bg-dark-400 transition-colors">
+    <svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.8"
+         stroke-linecap="round" class="w-4 h-4">
+      <path d="M5 8l5 5 5-5"/>
+      <path d="M5 4l5 5 5-5" opacity=".4"/>
+    </svg>
+  </button>
+
+  <!-- collapse all -->
+  <button id="fb-collapse-all" title="Collapse all"
+          class="p-1.5 rounded text-gray-400 hover:text-white hover:bg-dark-400 transition-colors">
+    <svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.8"
+         stroke-linecap="round" class="w-4 h-4">
+      <path d="M5 12l5-5 5 5"/>
+      <path d="M5 16l5-5 5 5" opacity=".4"/>
+    </svg>
+  </button>
+
+  <!-- sort -->
+  <select id="fb-sort" title="Sort songs within folders"
+          style="padding:4px 8px; border-radius:6px; border:1px solid #374151;
+                 background:#1f2937; color:#d1d5db; font-size:12px; cursor:pointer; outline:none;">
+    <option value="default">Default</option>
+    <option value="title">Title</option>
+    <option value="artist">Artist</option>
+    <option value="duration">Duration</option>
+    <option value="year">Year</option>
+    <option value="tuning">Tuning</option>
+    <option value="added">Recently Added</option>
+  </select>
+
+  <!-- sort direction -->
+  <button id="fb-sort-dir" title="Ascending"
+          class="p-1.5 rounded text-gray-400 hover:text-white hover:bg-dark-400 transition-colors">
+    <svg id="fb-sort-dir-icon" viewBox="0 0 20 20" fill="none" stroke="currentColor"
+         stroke-width="1.8" stroke-linecap="round" class="w-4 h-4">
+      <path d="M5 12l5-5 5 5"/>
+    </svg>
+  </button>
+
+  <!-- view toggle -->
+  <button id="fb-view-list" title="List view"
+          class="p-1.5 rounded text-gray-400 hover:text-white hover:bg-dark-400 transition-colors">
+    <svg viewBox="0 0 20 20" fill="currentColor" class="w-4 h-4">
+      <path fill-rule="evenodd"
+            d="M3 4a1 1 0 000 2h14a1 1 0 100-2H3zm0 4a1 1 0 000 2h14a1 1 0 100-2H3zm0 4a1 1 0 000 2h14a1 1 0 100-2H3z"
+            clip-rule="evenodd"/>
+    </svg>
+  </button>
+  <button id="fb-view-grid" title="Grid view"
+          class="p-1.5 rounded text-gray-400 hover:text-white hover:bg-dark-400 transition-colors">
+    <svg viewBox="0 0 20 20" fill="currentColor" class="w-4 h-4">
+      <path d="M5 3a2 2 0 00-2 2v2a2 2 0 002 2h2a2 2 0 002-2V5a2 2 0 00-2-2H5zM5 11a2 2 0 00-2 2v2a2 2 0 002 2h2a2 2 0 002-2v-2a2 2 0 00-2-2H5zM11 5a2 2 0 012-2h2a2 2 0 012 2v2a2 2 0 01-2 2h-2a2 2 0 01-2-2V5zM11 13a2 2 0 012-2h2a2 2 0 012 2v2a2 2 0 01-2 2h-2a2 2 0 01-2-2v-2z"/>
+    </svg>
+  </button>
+
+  <!-- filters -->
+  <button id="fb-filter" title="Filters"
+          class="p-1.5 rounded text-gray-400 hover:text-white hover:bg-dark-400 transition-colors"
+          style="position:relative;">
+    <svg viewBox="0 0 20 20" fill="currentColor" class="w-4 h-4">
+      <path fill-rule="evenodd"
+            d="M3 3a1 1 0 011-1h12a1 1 0 011 1v3a1 1 0 01-.293.707L12 11.414V15a1 1 0 01-.293.707l-2 2A1 1 0 018 17v-5.586L3.293 6.707A1 1 0 013 6V3z"
+            clip-rule="evenodd"/>
+    </svg>
+    <span id="fb-filter-badge"
+          style="display:none; position:absolute; top:-2px; right:-2px; min-width:14px; height:14px;
+                 padding:0 3px; border-radius:7px; background:#3b82f6; color:#fff;
+                 font-size:9px; font-weight:700; line-height:14px; text-align:center;
+                 box-sizing:border-box;"></span>
+  </button>
+
+  <!-- reload -->
+  <button id="fb-reload" title="Reload"
+          class="p-1.5 rounded text-gray-400 hover:text-white hover:bg-dark-400 transition-colors">
+    <svg viewBox="0 0 20 20" fill="currentColor" class="w-4 h-4">
+      <path fill-rule="evenodd"
+            d="M4 2a1 1 0 011 1v2.101a7.002 7.002 0 0111.601 2.566 1 1 0 11-1.885.666A5.002 5.002 0 005.999 7H9a1 1 0 010 2H4a1 1 0 01-1-1V3a1 1 0 011-1zm.008 9.057a1 1 0 011.276.61A5.002 5.002 0 0014.001 13H11a1 1 0 110-2h5a1 1 0 011 1v5a1 1 0 11-2 0v-2.101a7.002 7.002 0 01-11.601-2.566 1 1 0 01.61-1.276z"
+            clip-rule="evenodd"/>
+    </svg>
+  </button>
+
+  <span id="fb-status" class="text-xs text-gray-500 ml-1"></span>
+</div>
+
+<!-- ── tree ─────────────────────────────────────────────────────────── -->
+<div id="fb-tree" class="px-2 py-2" style="padding-top: 120px;"></div>
+
+<!-- ── filter backdrop ───────────────────────────────────────────────── -->
+<div id="fb-filter-backdrop"
+     style="display:none; position:fixed; inset:0; z-index:44;"></div>
+
+<!-- ── filter panel ──────────────────────────────────────────────────── -->
+<div id="fb-filter-panel"
+     style="display:none; position:fixed; top:64px; right:0; bottom:0; width:300px;
+            z-index:45; background:#0f1117; border-left:1px solid #1f2937;
+            flex-direction:column; overflow:hidden;"></div>
+
+<!-- ── custom modal ──────────────────────────────────────────────────── -->
+<div id="fb-modal" style="display:none; position:fixed; inset:0; z-index:9999;
+     background:rgba(0,0,0,0.6); align-items:center; justify-content:center;">
+  <div style="background:#1e2130; border:1px solid #374151; border-radius:8px;
+              padding:24px; width:360px; max-width:90vw; box-shadow:0 20px 60px rgba(0,0,0,0.5);">
+    <p id="fb-modal-msg" style="color:#e5e7eb; font-size:14px; margin:0 0 16px 0;
+       white-space:pre-wrap; line-height:1.5;"></p>
+    <input id="fb-modal-input" type="text"
+           style="display:none; width:100%; box-sizing:border-box; padding:8px 12px;
+                  background:#111827; border:1px solid #374151; border-radius:6px;
+                  color:#e5e7eb; font-size:14px; outline:none; margin-bottom:16px;"
+           placeholder=""/>
+    <div style="display:flex; gap:8px; justify-content:flex-end;">
+      <button id="fb-modal-cancel"
+              style="padding:6px 16px; border-radius:6px; border:1px solid #374151;
+                     background:transparent; color:#9ca3af; font-size:13px; cursor:pointer;">
+        Cancel
+      </button>
+      <button id="fb-modal-ok"
+              style="padding:6px 16px; border-radius:6px; border:none;
+                     background:#3b82f6; color:#fff; font-size:13px; cursor:pointer; font-weight:500;">
+        OK
+      </button>
+    </div>
+  </div>
+</div>

plugins/highway_3d/CLAUDE.md

@@ -108,9 +108,19 @@ Each entry names the function or banner you should grep for, plus key sub-blocks
 - **Beat lines** (downbeats highlighted) → `update()`, `// ── Beat lines ──` block. `mBeatM` (full opacity 0.25) for measure starts, `mBeatQ` (0.07) for other beats.
 - **Section labels** → `update()`, `// ── Section labels ──` block. Cyan (`#00cccc`) sprite at fret 12, above the highest string.
 
+### Scene colors (two independent axes: Background + Highway)
+- **Scene-color themes** → `BG_THEMES` table near the top of `createFactory()`. One combined table is the single source of truth, but it drives **two independent axes that share the same id-set**:
+  - **Background axis** — setting key `bgTheme`, setter `window.h3dBgSetBgTheme`, state `bgThemeId`. Owns `clear` (WebGL clear color) + `fog`.
+  - **Highway axis** — setting key `hwTheme`, setter `window.h3dBgSetHwTheme`, state `hwThemeId`. Owns `board` (fretboard/highway-surface plane) + optional `lane`/`laneDim` (the lit lane strip).
+  Any background id can mix with any highway id; picking the same id in both gives the original "matched" look. Per-axis accessors are `_bgBackgroundColors(id)` / `_bgHighwayColors(id)` (both alias `_bgThemeColors`). Both axes default to `'default'` (byte-identical to the original look).
+- **Applying a theme** → `_applyBgTheme()`. Background half sets clear+fog from `bgThemeId` (skipped under the venue scene); highway half sets the board plane + lane materials (`mLaneOdd`/`mLaneEven`) from `hwThemeId`. Re-run on init, `buildBoard()`, and the settings listener (which fires for **both** `bgTheme` and `hwTheme`), so changing either dropdown retints only its half live.
+- **Backward-compat migration** → `_bgLoadSettings()`: the first time it loads with no stored `hwTheme` (`_bgHasStored` false), it seeds `hwThemeId` from `bgThemeId` **and persists `hwTheme` once** (a one-time backfill, written without `_bgEmitChange`). So a pre-split single-`bgTheme` pick is byte-identical right after the upgrade, and from then on the two axes are fully independent — changing the Background dropdown never drags the Highway surface, and the settings UI's Highway value can't disagree with what's rendered. settings.html shows the same first-load value via `storedHwTheme == null ? bgTheme : coerceHwTheme(...)`.
+- **Adding/removing a theme** → edit `BG_THEMES` (the colors) AND `settings.html`'s `SCENE_THEMES` array (the `{id,label}` list — the single source the two dropdowns' `<option>`s and the `VALID_BG_THEMES` validator are both generated from). Keep the two id-sets aligned.
+
 ### Highway lane (the highlighted strip under active frets)
 - **Lane drawing** → `update()`, `// ── Dynamic highway lane ──` block. `pLane` is a single quad on the fretboard plane; `pLaneDivider` is thin vertical lines at each fret inside the lane. Width keys off the active-fret range; min width ≈ 4 frets.
-- **Lane intensity** → `highwayIntensity` accumulated from upcoming notes (further notes dim it, near notes light it). `_laneTargetColor = 0x4488ff` (set in `initScene()`) is the "lit" color, blended toward from `0x112233`.
+- **Lane intensity** → `highwayIntensity` accumulated from upcoming notes (further notes dim it, near notes light it).
+- **Lane color** → the lit quad color is `mLaneOdd.color` (stock `HWY_LANE_STRIPE_ODD_HEX = 0x103B5C`), the dimmer alternating row `mLaneEven.color` (`HWY_LANE_STRIPE_EVEN_HEX = 0x08283C`). These are now **theme-aware**: `_applyBgTheme()` recolors them from the active HIGHWAY theme's optional `lane`/`laneDim` fields, falling back to the stock hexes when a highway theme omits them. (`_laneTargetColor`, set in `initScene()`, is kept in sync with the lit color but has no live consumer today.)
 
 ### Lyrics & overlays
 - **Lyrics overlay** → `drawLyrics()`. 2D canvas, top centre, semi-transparent rounded background, syllable-level highlighting (current syllable in white, played in muted, upcoming in dim).
@@ -147,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.
@@ -201,7 +213,7 @@ The eight-color palette `S_COL` is the single source of truth for per-string col
 
 If a planned color-palette feature lands (issue #10), expect it to swap the palette source array but keep this single-array indirection. Anything that hardcodes color today will break that swap; flag it during review.
 
-Non-string colors (lane target `0x4488ff`, fret-row label colors `#ffe84d` / `#9ab8cc`, fret-dot color `0x556677`, lyrics box rgba, chord-name gold `#e8d080`, etc.) are scattered as literals — that's intentional for now, since they're scene-wide accents rather than per-string. Pulling them into named constants is fine if you're already in that area.
+Non-string colors (the stock lane hexes `HWY_LANE_STRIPE_ODD_HEX`/`_EVEN_HEX` — now overridable per Highway theme, see "Scene colors" above; fret-row label colors `#ffe84d` / `#9ab8cc`, fret-dot color `0x556677`, lyrics box rgba, chord-name gold `#e8d080`, etc.) are scattered as literals — that's intentional for now, since they're scene-wide accents rather than per-string. Pulling them into named constants is fine if you're already in that area.
 
 ## Tweaking text-sprite styling
 

plugins/highway_3d/NOTICE

@@ -0,0 +1,30 @@
+3D Highway plugin — third-party notices
+=======================================
+
+The "Butterchurn (visualizer)" background style (the 'butterchurn' option in
+the plugin's Background-style setting) bundles the third-party components below
+under plugins/highway_3d/assets/vendor/. They are lazy-loaded only when a user
+selects that background style.
+
+The 3D Highway plugin and the feedBack project are licensed under the GNU Affero
+General Public License v3.0 (AGPL-3.0-only). The components below are under their
+own permissive (MIT) licenses, which are compatible with AGPL-3.0.
+
+- Butterchurn — a WebGL implementation of the MilkDrop visualizer.
+  https://github.com/jberg/butterchurn
+  Copyright (c) Jordan Berg. MIT License.
+  Vendored at: plugins/highway_3d/assets/vendor/butterchurn.min.js
+
+- butterchurn-presets — MilkDrop preset pack.
+  https://github.com/jberg/butterchurn-presets
+  Presets authored by the MilkDrop community (Geiss, Flexi, Martin, Rovastar,
+  Zylot, Aderrasi, Cope, Eo.S., Unchained, and many others); refer to each
+  preset's embedded attribution.
+  Vendored at: plugins/highway_3d/assets/vendor/butterchurnPresets.min.js
+
+- Three.js (r170) — loaded at runtime from feedBack core's vendored copy
+  (/static/vendor/three/three.module.min.js). https://threejs.org  MIT License.
+
+Provenance: the Butterchurn background integration originated as the standalone
+"3D Highway + Butterchurn" plugin and was merged into the bundled 3D Highway
+renderer as the opt-in 'butterchurn' background style.

plugins/highway_3d/assets/viz-worklet.js

@@ -0,0 +1,47 @@
+/*
+ * Slopsmith visualizer — audio feed AudioWorkletProcessor.
+ * Generates Butterchurn's drive signal off the main thread (replaces the
+ * deprecated ScriptProcessor): guitar PCM (gained) + a bass-band song-energy
+ * pulse + a mid-band chart-accent pulse. The main thread pushes the latest
+ * guitar frame and the song/chart/gain scalars via port messages.
+ */
+class VizFeedProcessor extends AudioWorkletProcessor {
+    constructor() {
+        super();
+        this.frame = null;   // latest guitar PCM (Float32Array)
+        this.readIdx = 0;
+        this.song = 0;
+        this.chart = 0;
+        this.gain = 6;
+        this.phase = 0;
+        this.phase2 = 0;
+        this.osc = (2 * Math.PI * 90) / sampleRate;   // ~90 Hz  → bass band (song)
+        this.osc2 = (2 * Math.PI * 520) / sampleRate; // ~520 Hz → mid band (chart)
+        this.port.onmessage = (e) => {
+            const d = e.data;
+            if (!d) return;
+            if (d.frame) { this.frame = d.frame; this.readIdx = 0; }
+            if (typeof d.song === 'number') this.song = d.song;
+            if (typeof d.chart === 'number') this.chart = d.chart;
+            if (typeof d.gain === 'number') this.gain = d.gain;
+        };
+    }
+    process(inputs, outputs) {
+        const out = outputs[0] && outputs[0][0];
+        if (!out) return true;
+        const f = this.frame, fl = f ? f.length : 0;
+        const TWO_PI = 2 * Math.PI;
+        for (let i = 0; i < out.length; i++) {
+            const g = (fl ? f[this.readIdx % fl] : 0) * this.gain;
+            this.readIdx++;
+            const song = this.song * (0.7 * Math.sin(this.phase) + 0.3 * (Math.random() * 2 - 1)) * 1.4;
+            const chart = this.chart * (0.5 * Math.sin(this.phase2) + 0.5 * (Math.random() * 2 - 1)) * 1.5;
+            this.phase += this.osc; if (this.phase > TWO_PI) this.phase -= TWO_PI;
+            this.phase2 += this.osc2; if (this.phase2 > TWO_PI) this.phase2 -= TWO_PI;
+            const v = g + song + chart;
+            out[i] = v > 1 ? 1 : (v < -1 ? -1 : v);
+        }
+        return true;
+    }
+}
+registerProcessor('viz-feed', VizFeedProcessor);

plugins/highway_3d/plugin.json

@@ -1,12 +1,12 @@
 {
     "id": "highway_3d",
     "name": "3D Highway",
-    "version": "3.26.0",
+    "version": "3.31.2",
     "type": "visualization",
     "bundled": true,
     "script": "screen.js",
     "styles": "assets/plugin.css",
-    "settings": { "html": "settings.html", "server_files": ["plugin_uploads/highway_3d/current.mp4", "plugin_uploads/highway_3d/current.webm"] },
+    "settings": { "html": "settings.html", "category": "graphics", "server_files": ["plugin_uploads/highway_3d/current.mp4", "plugin_uploads/highway_3d/current.webm"] },
     "routes": "routes.py",
     "tour": "tour.json"
 }

plugins/highway_3d/settings.html

@@ -14,6 +14,15 @@
         <button type="button" onclick="window.hwcSaveTheme?.()" class="bg-dark-700 border border-gray-800 rounded-lg px-3 py-2 text-xs text-gray-300">Save as…</button>
         <button type="button" onclick="window.hwcDeleteTheme?.()" class="bg-dark-700 border border-gray-800 rounded-lg px-3 py-2 text-xs text-gray-400">Delete</button>
     </div>
+    <!-- One-click presets: apply a whole named palette to every string at once.
+         Buttons are generated from window.feedBack.highwayColors.presets so the
+         list stays in sync with core (app.js HWC_PRESETS). Each calls
+         applyPreset(id), which persists + applies to both highways and refreshes
+         the pickers below. Older core without the presets API leaves this empty. -->
+    <div class="mb-3">
+        <span class="text-xs text-gray-500 mb-1 block">Quick presets</span>
+        <div id="hwc-presets" class="flex flex-wrap gap-2"></div>
+    </div>
     <div id="hwc-pickers" class="mb-3" style="display:grid;grid-template-columns:1fr 1fr;gap:0.5rem;"></div>
     <div class="flex items-center gap-2 mb-2">
         <button type="button" onclick="window.hwcReset?.()" class="bg-dark-700 border border-gray-800 rounded-lg px-3 py-2 text-xs text-gray-300">Reset to defaults</button>
@@ -36,6 +45,33 @@
             if (typeof window.hwcInitSettingsUI === 'function') {
                 try { window.hwcInitSettingsUI(); } catch (e) { console.warn('[3D-Hwy] hwcInitSettingsUI failed', e); }
             }
+            // Render the one-click preset buttons from core's preset list.
+            try {
+                const api = window.feedBack && window.feedBack.highwayColors;
+                const host = document.getElementById('hwc-presets');
+                if (api && Array.isArray(api.presets) && host) {
+                    host.innerHTML = '';
+                    // Slot order low → high for the preview swatch (bass-side first).
+                    const order = ['lowE', 'A', 'D', 'G', 'B', 'highE'];
+                    for (const p of api.presets) {
+                        const btn = document.createElement('button');
+                        btn.type = 'button';
+                        btn.className = 'flex items-center gap-2 bg-dark-700 border border-gray-800 rounded-lg px-2 py-1 text-xs text-gray-300';
+                        const sw = document.createElement('span');
+                        const stops = order.map((k) => p.colors[k]).filter(Boolean).join(',');
+                        sw.style.cssText = 'width:2.5rem;height:0.85rem;border-radius:3px;border:1px solid #0006;'
+                            + 'background:linear-gradient(90deg,' + stops + ');';
+                        btn.appendChild(sw);
+                        const txt = document.createElement('span');
+                        txt.textContent = p.label;
+                        btn.appendChild(txt);
+                        btn.addEventListener('click', function () {
+                            try { api.applyPreset(p.id); } catch (e) { console.warn('[3D-Hwy] applyPreset failed', e); }
+                        });
+                        host.appendChild(btn);
+                    }
+                }
+            } catch (e) { console.warn('[3D-Hwy] preset render failed', e); }
         })();
     </script>
 </div>
@@ -88,11 +124,145 @@
             <option value="silhouettes">Silhouettes (parallax)</option>
             <option value="lights">Lights (stage glows)</option>
             <option value="geometric">Geometric (rotating shapes)</option>
+            <option value="butterchurn">Butterchurn (visualizer)</option>
             <option value="image" disabled>Custom image (none uploaded)</option>
             <option value="video" disabled>Custom video (none uploaded)</option>
         </select>
     </div>
 
+    <!-- Scene colors — TWO independent axes sharing one palette family:
+         Background (clear + fog) and Highway (board surface + lit lane). Same
+         id-set in both, so any background can mix with any highway; picking the
+         same in both gives the original "matched" look. "Default" is the
+         original look on both. -->
+    <div class="mt-3">
+        <label for="h3d-bg-theme" class="text-xs font-medium text-gray-400 mb-1 block">Background</label>
+        <!-- Options are populated from SCENE_THEMES (the single id+label source)
+             in the hydration script below, so the two dropdowns can't drift. -->
+        <select id="h3d-bg-theme"
+            onchange="window.h3dBgSetBgTheme && window.h3dBgSetBgTheme(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">
+        </select>
+        <p class="text-[10px] text-gray-500 mt-1">
+            Tints the background + distance fog. Applies to the 3D highway immediately.
+        </p>
+    </div>
+    <div class="mt-3">
+        <label for="h3d-hw-theme" class="text-xs font-medium text-gray-400 mb-1 block">Highway (surface + lane)</label>
+        <!-- Options populated from SCENE_THEMES (see below), same source as the
+             Background dropdown so the two stay in lockstep. -->
+        <select id="h3d-hw-theme"
+            onchange="window.h3dBgSetHwTheme && window.h3dBgSetHwTheme(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">
+        </select>
+        <p class="text-[10px] text-gray-500 mt-1">
+            Tints the fretboard surface + the lit lane. Applies to the 3D highway immediately.
+        </p>
+    </div>
+
+    <!-- Butterchurn (visualizer) options. These drive the 'butterchurn'
+         Background style. They used to live in a floating in-canvas panel; the
+         on/off + slider controls now live here in the standard settings UI.
+         The live preset browser (pick / favorite / ban / cycle) stays in-canvas.
+         Persisted in the 'viz3d_settings' localStorage blob (shared with the
+         in-canvas preset controls); window.h3dBcApplySettings() pushes changes
+         to a mounted highway live. -->
+    <div id="h3d-bc-section" class="mt-4">
+        <h3 class="text-sm font-medium text-gray-400 mb-2">Butterchurn (visualizer)</h3>
+        <p class="text-xs text-gray-500 mb-2">Active when Background style is set to <em>Butterchurn (visualizer)</em>.</p>
+        <div class="flex items-center gap-3 mt-3">
+            <label class="flex items-center gap-2 text-sm text-gray-300">
+                <input type="checkbox" id="h3d-bc-enabled" class="accent-accent"> Background on
+            </label>
+        </div>
+        <div class="mt-3">
+            <label for="h3d-bc-opacity" class="text-xs font-medium text-gray-400 mb-1 block">Opacity: <span id="h3d-bc-opacity-label">100%</span></label>
+            <input type="range" id="h3d-bc-opacity" min="0" max="100" class="w-full accent-accent">
+        </div>
+        <div class="flex items-center gap-3 mt-3">
+            <label class="flex items-center gap-2 text-sm text-gray-300">
+                <input type="checkbox" id="h3d-bc-laneDim" class="accent-accent"> Dim behind lane
+            </label>
+        </div>
+        <div class="mt-3">
+            <label for="h3d-bc-laneDimStrength" class="text-xs font-medium text-gray-400 mb-1 block">Dim strength</label>
+            <input type="range" id="h3d-bc-laneDimStrength" min="0" max="100" class="w-full accent-accent">
+        </div>
+        <div class="flex items-center gap-3 mt-3">
+            <label class="flex items-center gap-2 text-sm text-gray-300">
+                <input type="checkbox" id="h3d-bc-chartAccents" class="accent-accent"> Chart accents
+            </label>
+        </div>
+        <div class="mt-3">
+            <label for="h3d-bc-chartStrength" class="text-xs font-medium text-gray-400 mb-1 block">Chart strength</label>
+            <input type="range" id="h3d-bc-chartStrength" min="0" max="200" class="w-full accent-accent">
+        </div>
+        <div class="flex items-center gap-3 mt-3">
+            <label class="flex items-center gap-2 text-sm text-gray-300">
+                <input type="checkbox" id="h3d-bc-colorTint" class="accent-accent"> Color tint
+            </label>
+        </div>
+        <div class="mt-3">
+            <label for="h3d-bc-tintStrength" class="text-xs font-medium text-gray-400 mb-1 block">Tint strength</label>
+            <input type="range" id="h3d-bc-tintStrength" min="0" max="100" class="w-full accent-accent">
+        </div>
+        <div class="mt-3">
+            <label for="h3d-bc-guitarGain" class="text-xs font-medium text-gray-400 mb-1 block">Guitar gain: <span id="h3d-bc-guitarGain-label">×6</span></label>
+            <input type="range" id="h3d-bc-guitarGain" min="1" max="12" step="0.5" class="w-full accent-accent">
+        </div>
+        <div class="mt-3">
+            <label for="h3d-bc-songGain" class="text-xs font-medium text-gray-400 mb-1 block">Song gain: <span id="h3d-bc-songGain-label">×1.8</span></label>
+            <input type="range" id="h3d-bc-songGain" min="0" max="5" step="0.1" class="w-full accent-accent">
+        </div>
+    </div>
+    <script>
+        // Self-contained Butterchurn settings wiring. Reads/writes the same
+        // 'viz3d_settings' blob the in-canvas preset controls use (read-modify-
+        // write preserves cyclePool/hold and the favorites/bans lists), then
+        // calls window.h3dBcApplySettings() so a mounted highway applies the
+        // change live. Guarded so it no-ops if the section isn't present.
+        (function () {
+            const BC_LS = 'viz3d_settings';
+            const BC_DEFAULTS = { enabled: true, opacity: 1.0, laneDim: true, laneDimStrength: 0.45, chartAccents: true, colorTint: true, chartStrength: 1.0, tintStrength: 0.65, guitarGain: 6, songGain: 1.8 };
+            function readBlob() { let s = {}; try { s = JSON.parse(localStorage.getItem(BC_LS) || '{}') || {}; } catch (e) {} return s; }
+            function patch(p) {
+                const s = readBlob();
+                Object.assign(s, p);
+                try { localStorage.setItem(BC_LS, JSON.stringify(s)); } catch (e) {}
+                try { if (typeof window.h3dBcApplySettings === 'function') window.h3dBcApplySettings(); } catch (e) {}
+            }
+            const s = Object.assign({}, BC_DEFAULTS, readBlob());
+            const $ = (id) => document.getElementById(id);
+            const en = $('h3d-bc-enabled');
+            if (!en) return;
+            const op = $('h3d-bc-opacity'), opv = $('h3d-bc-opacity-label');
+            const ld = $('h3d-bc-laneDim'), lds = $('h3d-bc-laneDimStrength');
+            const ca = $('h3d-bc-chartAccents'), cs = $('h3d-bc-chartStrength');
+            const ct = $('h3d-bc-colorTint'), ts = $('h3d-bc-tintStrength');
+            const gg = $('h3d-bc-guitarGain'), ggv = $('h3d-bc-guitarGain-label');
+            const sg = $('h3d-bc-songGain'), sgv = $('h3d-bc-songGain-label');
+            // Hydrate from saved settings.
+            en.checked = !!s.enabled;
+            op.value = Math.round((s.opacity != null ? s.opacity : 1) * 100); if (opv) opv.textContent = op.value + '%';
+            ld.checked = !!s.laneDim; lds.value = Math.round((s.laneDimStrength != null ? s.laneDimStrength : 0.45) * 100);
+            ca.checked = !!s.chartAccents; cs.value = Math.round((s.chartStrength != null ? s.chartStrength : 1) * 100);
+            ct.checked = !!s.colorTint; ts.value = Math.round((s.tintStrength != null ? s.tintStrength : 0.65) * 100);
+            gg.value = s.guitarGain != null ? s.guitarGain : 6; if (ggv) ggv.textContent = '×' + gg.value;
+            sg.value = s.songGain != null ? s.songGain : 1.8; if (sgv) sgv.textContent = '×' + sg.value;
+            // Wire changes (read-modify-write + live apply).
+            en.addEventListener('change', () => patch({ enabled: en.checked }));
+            op.addEventListener('input', () => { if (opv) opv.textContent = op.value + '%'; patch({ opacity: op.value / 100 }); });
+            ld.addEventListener('change', () => patch({ laneDim: ld.checked }));
+            lds.addEventListener('input', () => patch({ laneDimStrength: lds.value / 100 }));
+            ca.addEventListener('change', () => patch({ chartAccents: ca.checked }));
+            cs.addEventListener('input', () => patch({ chartStrength: cs.value / 100 }));
+            ct.addEventListener('change', () => patch({ colorTint: ct.checked }));
+            ts.addEventListener('input', () => patch({ tintStrength: ts.value / 100 }));
+            gg.addEventListener('input', () => { if (ggv) ggv.textContent = '×' + gg.value; patch({ guitarGain: parseFloat(gg.value) }); });
+            sg.addEventListener('input', () => { if (sgv) sgv.textContent = '×' + sg.value; patch({ songGain: parseFloat(sg.value) }); });
+        })();
+    </script>
+
     <!-- Intensity -->
     <div class="mt-3">
         <label for="h3d-bg-intensity" class="text-xs font-medium text-gray-400 mb-1 block">
@@ -407,6 +577,80 @@
                     <span>Glowy</span>
                 </div>
             </div>
+
+            <div class="mt-4">
+                <label for="h3d-hitfx" class="text-xs font-medium text-gray-400 mb-1 block">
+                    Hit feedback intensity: <span id="h3d-hitfx-label">0.70</span>
+                </label>
+                <input type="range" id="h3d-hitfx" min="0" max="1" step="0.05" value="0.70"
+                    oninput="document.getElementById('h3d-hitfx-label').textContent = parseFloat(this.value).toFixed(2); window.h3dBgSetHitFx && window.h3dBgSetHitFx(this.value)"
+                    onchange="window.h3dBgSetHitFx && window.h3dBgSetHitFx(this.value)"
+                    class="w-full accent-accent">
+                <p class="text-[10px] text-gray-500 mt-1">
+                    How much "juice" a nailed note gets — the strike-line flash and the
+                    spark burst at the hit line. <em>0</em> = colour verdict only (no sparks).
+                </p>
+            </div>
+
+            <div class="mt-3 flex items-start justify-between gap-3">
+                <label for="h3d-sparks" class="text-xs font-medium text-gray-400">
+                    Hit sparks
+                    <span class="block text-[10px] text-gray-500 font-normal">The particle burst that pops off a note the instant it's detected as a hit. Turn off for a calmer highway — the strike-line flash and colour verdict stay.</span>
+                </label>
+                <input type="checkbox" id="h3d-sparks" checked
+                    onchange="window.h3dBgSetSparks && window.h3dBgSetSparks(this.checked)"
+                    class="accent-accent mt-0.5">
+            </div>
+
+            <div class="mt-3 flex items-start justify-between gap-3">
+                <label for="h3d-cinematic" class="text-xs font-medium text-gray-400">
+                    Cinematic lighting
+                    <span class="block text-[10px] text-gray-500 font-normal">Darker stage so the glowing notes pop against it. Turn off for the brighter, flatter look.</span>
+                </label>
+                <input type="checkbox" id="h3d-cinematic" checked
+                    onchange="window.h3dBgSetCinematic && window.h3dBgSetCinematic(this.checked)"
+                    class="accent-accent mt-0.5">
+            </div>
+
+            <div class="mt-3 flex items-start justify-between gap-3">
+                <label for="h3d-streakfx" class="text-xs font-medium text-gray-400">
+                    Streak feedback
+                    <span class="block text-[10px] text-gray-500 font-normal">A clean run quietly "heats up" — bigger sparks the longer you stay accurate. Eases back on a miss.</span>
+                </label>
+                <input type="checkbox" id="h3d-streakfx" checked
+                    onchange="window.h3dBgSetStreakFx && window.h3dBgSetStreakFx(this.checked)"
+                    class="accent-accent mt-0.5">
+            </div>
+
+            <div class="mt-3 flex items-start justify-between gap-3">
+                <label for="h3d-verdictmarks" class="text-xs font-medium text-gray-400">
+                    Accessible verdict marks (✓ / ✗)
+                    <span class="block text-[10px] text-gray-500 font-normal">Adds a shape mark to each hit/miss so the result doesn't rely on the green/red colour pair alone.</span>
+                </label>
+                <input type="checkbox" id="h3d-verdictmarks" checked
+                    onchange="window.h3dBgSetVerdictMarks && window.h3dBgSetVerdictMarks(this.checked)"
+                    class="accent-accent mt-0.5">
+            </div>
+
+            <div class="mt-3 flex items-start justify-between gap-3">
+                <label for="h3d-bloom" class="text-xs font-medium text-gray-400">
+                    Glow bloom
+                    <span class="block text-[10px] text-gray-500 font-normal">Real light-bleed around the glowing notes and hit flash (higher fidelity). Turns itself off in split-screen. If your machine struggles, turn this off first.</span>
+                </label>
+                <input type="checkbox" id="h3d-bloom" checked
+                    onchange="window.h3dBgSetBloom && window.h3dBgSetBloom(this.checked)"
+                    class="accent-accent mt-0.5">
+            </div>
+
+            <div class="mt-3 flex items-start justify-between gap-3">
+                <label for="h3d-timingfx" class="text-xs font-medium text-gray-400">
+                    Timing feedback
+                    <span class="block text-[10px] text-gray-500 font-normal">Colours a hit by your timing — on-time green, a touch <span style="color:#35d6ff">early (cyan)</span> or <span style="color:#ffb84d">late (amber)</span> — so you can feel where you sit in the beat.</span>
+                </label>
+                <input type="checkbox" id="h3d-timingfx" checked
+                    onchange="window.h3dBgSetTimingFx && window.h3dBgSetTimingFx(this.checked)"
+                    class="accent-accent mt-0.5">
+            </div>
         </div>
     </details>
 </div>
@@ -712,8 +956,27 @@
          no-selection / NaN state. -->
     <script>
         (function () {
-            const DEFAULTS = { style: 'particles', intensity: 0.5, reactive: true, palette: 'default', showFretOnNote: true, fretNumberGhostScope: 'chords', cameraSmoothing: 0.5, zoomSmoothing: 0.5, tiltSmoothing: 0.5, cameraLockLow: false, cameraLockZoom: 0.5, cameraMode: 'lookahead', nutHeadstockVisible: true, tuningLabelsVisible: true, nutColor: '#f5f3f0', headstockColor: '#d4b48a', textSize: 0.5, vibrancy: 0.85, glow: 0.25, customImageDataUrl: '', customImageName: '', customVideoName: '', chordDiagramVisible: true, chordDiagramSize: 0.5, chordDiagramPosition: 'tl', fretColumnMarkerCadence: 1, projectionVisible: true, inlayLabelsVisible: false, sectionLabelsOnHighway: false, sectionHudVisible: false, sectionHudPosition: 'tr', sectionHudSize: 0.5, toneHudVisible: false, toneHudPosition: 'tl', toneHudSize: 0.5, fpsVisible: false, fretDividersVisible: true, slideArrowApproachVisible: true, slideArrowNeckVisible: true, slideArrowChainPreviewVisible: true };
-            const VALID_STYLES = new Set(['off', 'particles', 'silhouettes', 'lights', 'geometric', 'image', 'video']);
+            const DEFAULTS = { style: 'particles', intensity: 0.5, reactive: true, palette: 'default', bgTheme: 'default', hwTheme: 'default', showFretOnNote: true, fretNumberGhostScope: 'chords', cameraSmoothing: 0.5, zoomSmoothing: 0.5, tiltSmoothing: 0.5, cameraLockLow: false, cameraLockZoom: 0.5, cameraMode: 'lookahead', nutHeadstockVisible: true, tuningLabelsVisible: true, nutColor: '#f5f3f0', headstockColor: '#d4b48a', textSize: 0.5, vibrancy: 0.85, glow: 0.25, customImageDataUrl: '', customImageName: '', customVideoName: '', chordDiagramVisible: true, chordDiagramSize: 0.5, chordDiagramPosition: 'tl', fretColumnMarkerCadence: 1, projectionVisible: true, inlayLabelsVisible: false, sectionLabelsOnHighway: false, sectionHudVisible: false, sectionHudPosition: 'tr', sectionHudSize: 0.5, toneHudVisible: false, toneHudPosition: 'tl', toneHudSize: 0.5, fpsVisible: false, fretDividersVisible: true, slideArrowApproachVisible: true, slideArrowNeckVisible: true, slideArrowChainPreviewVisible: true };
+            const VALID_STYLES = new Set(['off', 'particles', 'silhouettes', 'lights', 'geometric', 'butterchurn', 'image', 'video']);
+            // Scene color themes — the single id+label source for BOTH the
+            // Background and Highway dropdowns AND the validator below. The
+            // <option>s are generated from this list (see hydration), so the two
+            // dropdowns can't drift from each other or from VALID_BG_THEMES.
+            // Mirror these ids with screen.js BG_THEMES (the color table).
+            const SCENE_THEMES = [
+                { id: 'default',      label: 'Default (blue-black)' },
+                { id: 'midnight',     label: 'Midnight (deep blue)' },
+                { id: 'charcoal',     label: 'Charcoal (neutral gray)' },
+                { id: 'deeppurple',   label: 'Deep purple' },
+                { id: 'forest',       label: 'Forest (dark green)' },
+                { id: 'warmslate',    label: 'Warm Slate (espresso)' },
+                { id: 'deepfocus',    label: 'Deep Focus (near-black)' },
+                { id: 'deepsea',      label: 'Deep Sea (dark teal)' },
+                { id: 'cathode',      label: 'Cathode (amber CRT)' },
+                { id: 'cathodegreen', label: 'Cathode Green (green CRT)' },
+                { id: 'hearth',       label: 'Hearth (warm red)' },
+            ];
+            const VALID_BG_THEMES = new Set(SCENE_THEMES.map((t) => t.id));
             const VALID_CAMERA_MODES = new Set(['steady', 'lookahead']);
             // Chord diagram is top-only (bl/br removed).
             const VALID_CHORD_DIAG_POSITIONS = new Set(['tl', 'tr']);
@@ -771,6 +1034,9 @@
             const VIDEO_UPLOAD_URL = '/api/plugins/highway_3d/files';
 
             function coerceStyle(v) { return VALID_STYLES.has(v) ? v : DEFAULTS.style; }
+            function coerceBgTheme(v) { return VALID_BG_THEMES.has(v) ? v : DEFAULTS.bgTheme; }
+            // Highway axis shares the same valid id-set as the background axis.
+            function coerceHwTheme(v) { return VALID_BG_THEMES.has(v) ? v : DEFAULTS.hwTheme; }
             function coerceCameraMode(v) {
                 if (v === 'classic') v = 'steady';
                 return VALID_CAMERA_MODES.has(v) ? v : DEFAULTS.cameraMode;
@@ -812,7 +1078,7 @@
                 return fallback;
             }
 
-            let storedStyle = null, storedI = null, storedR = null, storedFretOnNote = null, storedFretNumberGhostScope = null;
+            let storedStyle = null, storedBgTheme = null, storedHwTheme = null, storedI = null, storedR = null, storedFretOnNote = null, storedFretNumberGhostScope = null;
             let storedCameraSmoothing = null;
             let storedCameraMode = null;
             let storedCustomImageDataUrl = null, storedCustomImageName = null;
@@ -848,6 +1114,8 @@
             let storedSlideArrowChainPreviewVisible = null;
             try {
                 storedStyle = localStorage.getItem('h3d_bg_style');
+                storedBgTheme = localStorage.getItem('h3d_bg_bgTheme');
+                storedHwTheme = localStorage.getItem('h3d_bg_hwTheme');
                 storedI = localStorage.getItem('h3d_bg_intensity');
                 storedR = localStorage.getItem('h3d_bg_reactive');
                 storedFretOnNote = localStorage.getItem('h3d_bg_showFretOnNote');
@@ -889,6 +1157,15 @@
             } catch (_) { /* storage blocked */ }
 
             const style = coerceStyle(storedStyle);
+            const bgTheme = coerceBgTheme(storedBgTheme);
+            // Highway axis. BACKWARD-COMPAT: when hwTheme was never written
+            // (pre-split installs, or the panel opened before the highway has
+            // mounted and run its one-time backfill), show the background pick —
+            // exactly the value screen.js will persist on first load — so the
+            // dropdown matches what's rendered. Once hwTheme is stored (which the
+            // renderer's backfill or any explicit pick does) it reads
+            // independently and the two axes no longer track each other.
+            const hwTheme = (storedHwTheme == null) ? bgTheme : coerceHwTheme(storedHwTheme);
             const intensity = coerceIntensity(storedI);
             const reactive = coerceBool(storedR, DEFAULTS.reactive);
             const showFretOnNote = coerceBool(storedFretOnNote, DEFAULTS.showFretOnNote);
@@ -959,6 +1236,20 @@
             const customVideoName    = (typeof storedCustomVideoName === 'string')    ? storedCustomVideoName    : DEFAULTS.customVideoName;
 
             const sel = document.getElementById('h3d-bg-style');
+            const bgThemeSel = document.getElementById('h3d-bg-theme');
+            const hwThemeSel = document.getElementById('h3d-hw-theme');
+            // Populate both scene-theme dropdowns from the single SCENE_THEMES
+            // source so they can't drift. (Values are selected further below.)
+            for (const selEl of [bgThemeSel, hwThemeSel]) {
+                if (!selEl) continue;
+                selEl.innerHTML = '';
+                for (const t of SCENE_THEMES) {
+                    const opt = document.createElement('option');
+                    opt.value = t.id;
+                    opt.textContent = t.label;
+                    selEl.appendChild(opt);
+                }
+            }
             const sli = document.getElementById('h3d-bg-intensity');
             const lbl = document.getElementById('h3d-bg-intensity-label');
             const rea = document.getElementById('h3d-bg-reactive');
@@ -1082,6 +1373,35 @@
             if (thsi)  thsi.value   = String(toneHudSize);
             if (thslbl) thslbl.textContent = toneHudSize.toFixed(2);
 
+            // Hit-feedback "juice" controls — hydrate from saved state so the
+            // panel reflects persistence on reopen (the renderer already reads
+            // these via _bgReadSetting; without this the controls always showed
+            // their default markup, misrepresenting a saved non-default). Reads
+            // h3d_bg_* directly; defaults mirror BG_DEFAULTS (all bools on,
+            // hitFx 0.70) and the _bgCoerceBool 'true'/'1' vs 'false'/'0' rules.
+            try {
+                const _bgBool = (k, def) => {
+                    const v = localStorage.getItem('h3d_bg_' + k);
+                    return v == null ? def : !(v === 'false' || v === '0');
+                };
+                const _setChk = (id, on) => { const el = document.getElementById(id); if (el) el.checked = on; };
+                _setChk('h3d-sparks',       _bgBool('sparks', true));
+                _setChk('h3d-cinematic',    _bgBool('cinematic', true));
+                _setChk('h3d-streakfx',     _bgBool('streakFx', true));
+                _setChk('h3d-verdictmarks', _bgBool('verdictMarks', true));
+                _setChk('h3d-bloom',        _bgBool('bloom', true));
+                _setChk('h3d-timingfx',     _bgBool('timingFx', true));
+                const _hf = document.getElementById('h3d-hitfx');
+                if (_hf) {
+                    let v = parseFloat(localStorage.getItem('h3d_bg_hitFx'));
+                    if (!isFinite(v)) v = 0.70;
+                    v = Math.max(0, Math.min(1, v));
+                    _hf.value = String(v);
+                    const _hfl = document.getElementById('h3d-hitfx-label');
+                    if (_hfl) _hfl.textContent = v.toFixed(2);
+                }
+            } catch (_) { /* storage blocked — controls keep their default markup */ }
+
             // (3D Highway palette picker removed — string colors are now set
             // via the core "Highway String Colors" UI above, which drives both
             // the 2D and 3D highways. The bg-settings 'palette' key still exists
@@ -1200,6 +1520,8 @@
                     sel.value = style;
                 }
             }
+            if (bgThemeSel) bgThemeSel.value = bgTheme;
+            if (hwThemeSel) hwThemeSel.value = hwTheme;
 
             if (fileInput) {
                 fileInput.addEventListener('change', function () {

plugins/input_setup/screen.js

@@ -51,15 +51,16 @@
             sources = sources.filter((s) => s
                 && !/midi/i.test(String(s.providerId || ''))
                 && !/^midi-input/i.test(String(s.label || '')));
-            // De-dupe by display label — the desktop engine enumerates the same
-            // device under several driver types, so the same name can repeat.
-            const seen = new Set();
-            sources = sources.filter((s) => {
-                const key = String(s.label || '').toLowerCase();
-                if (seen.has(key)) return false;
-                seen.add(key);
-                return true;
-            });
+            // No label de-dupe here. The audio-input capability already
+            // collapses exact duplicates by logicalSourceKey
+            // (_visibleInputSources), so nothing it returns shares a key. A
+            // device that enumerates under several driver types (ASIO / Windows
+            // Audio / DirectSound) has a DISTINCT key per type and is now
+            // labelled with its driver type (e.g. "Focusrite (ASIO)") — each is
+            // a real, separately-selectable input the user must be able to see.
+            // The old bare-label collapse also kept whichever variant sorted
+            // first, which could silently drop the one that was actually
+            // `selected` below.
             const selected = sources.find((s) => s && s.selected) || null;
             return { sources, selected };
         } catch (_) { return { sources: [], selected: null }; }
@@ -163,10 +164,25 @@
 
                 host.querySelector('[data-is-cal]').addEventListener('click', () => {
                     if (hasDetector) {
+                        // Hide our own full-screen overlay while note_detect's
+                        // Calibration Wizard runs on top. That wizard goes
+                        // transparent (pointer-events:none) when it minimizes to
+                        // expose the Tuner; if our overlay stayed up it would show
+                        // through — covering the tuner with the still-mounted
+                        // "select your input" card and looking like a second
+                        // wizard at the input step. Restore it on done/cancel
+                        // (one of which always fires when that wizard closes).
+                        const ov = document.getElementById('input-setup-overlay');
+                        const prevDisplay = ov ? ov.style.display : '';
+                        if (ov) ov.style.display = 'none';
+                        const restore = () => {
+                            const o = document.getElementById('input-setup-overlay');
+                            if (o) o.style.display = prevDisplay;
+                        };
                         window.noteDetect.launchCalibration({
                             instrument: inst,
-                            onDone: () => advance(inst, true),
-                            onCancel: () => { /* stay on this panel; user can skip or retry */ },
+                            onDone: () => { restore(); advance(inst, true); },
+                            onCancel: () => { restore(); /* stay on this panel; user can skip or retry */ },
                         });
                     } else {
                         advance(inst, true);

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

@@ -1,7 +1,7 @@
 {
   "id": "minigames",
   "name": "Minigames",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "bundled": true,
   "private": false,
   "screen": "screen.html",

plugins/minigames/screen.js

@@ -961,7 +961,25 @@
   // Drain queue of plugins that loaded before us.
   (window.__feedBackMinigamesPending || []).forEach(register);
   window.__feedBackMinigamesPending = null;
+
+  // ── Back-compat for pre-rename minigame plugins ───────────────────────
+  // Minigame plugins published before the slopsmith→feedBack rename (#537)
+  // register against `window.slopsmithMinigames` and, when the SDK isn't up
+  // yet, queue to `window.__slopsmithMinigamesPending`. The rename moved the
+  // SDK to `window.feedBackMinigames` and only drains the feedBack queue, so
+  // those plugins' specs — including community ones we don't control — get
+  // stranded in the legacy queue and never register. Their FeedBarcade tiles
+  // then render as dead "Loading…" placeholders that do nothing on click.
+  // Alias the SDK under the old name and drain the legacy pending queue too.
+  // register() is keyed on spec.id, so a plugin that queued under both names
+  // still registers exactly once.
+  window.slopsmithMinigames = sdk;
+  (window.__slopsmithMinigamesPending || []).forEach(register);
+  window.__slopsmithMinigamesPending = null;
+
   window.dispatchEvent(new CustomEvent('feedBack-minigames-ready'));
+  // Legacy event name for any pre-rename listener still bound to it.
+  window.dispatchEvent(new CustomEvent('slopsmith-minigames-ready'));
 
   // ── Wire hub render to screen lifecycle ───────────────────────────────
   // FeedBack mounts plugin screens with id "plugin-<plugin_id>" and

plugins/tuner/README.md

@@ -34,17 +34,17 @@ This plugin adds a floating "Tuner" button to the FeedBack interface, providing
 ## Installation
 
 ### Download a Release
-1. Download one of the [Releases](https://github.com/OmikronApex/feedBack-plugin-tuner/releases)
+1. Download one of the [Releases](https://github.com/OmikronApex/slopsmith-plugin-tuner/releases)
 2. Extract it to your plugins folder
 3. Restart FeedBack
 
 ### Update Manager
-The plugin is listed in the official plugin repository, so it can also be installed directly via the [Update Manager](https://github.com/masc0t/feedBack-update-manager)
+The plugin is listed in the official plugin repository, so it can also be installed directly via the [Update Manager](https://github.com/masc0t/slopsmith-update-manager)
 
 ### Git
 ```bash
 cd /path/to/feedBack/plugins
-git clone https://github.com/OmikronApex/feedBack-plugin-tuner.git tuner
+git clone https://github.com/OmikronApex/slopsmith-plugin-tuner.git tuner
 # Restart FeedBack (or restart your docker container)
 docker compose restart
 ```

plugins/tuner/plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "tuner",
   "name": "Guitar/Bass Tuner",
-  "version": "1.3.1",
+  "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,

plugins/tuner/visualization/analogue-gauge.js

@@ -18,6 +18,8 @@
     // ── Constants ─────────────────────────────────────────────────────
     var _TUNER_LABEL_H = 12;           // px height of each drum label
     var _TUNER_NEEDLE_HALF_SWEEP = 90; // degrees — ±50 cents = horizontal (180° apart)
+    var _SETTLE_A = 0.05;              // deg — needle "settled" threshold (sub-visible)
+    var _SETTLE_Y = 0.1;               // px — drum-strip "settled" threshold
     var _TUNER_IN_TUNE_THRESHOLD = 2;
     var _TUNER_STRIP_START_MIDI = 14;  // ~18 Hz — covers 20 Hz minimum
     var _TUNER_STRIP_END_MIDI = 84;    // ~1047 Hz C6
@@ -321,9 +323,34 @@
             currentAngle += (targetAngle - currentAngle) * lf;
             _setNeedle(currentAngle);
 
+            // Stop once the needle has settled on its target — a static needle
+            // needs no repaint. update() re-kicks the loop when a new reading
+            // moves the target, so this idles the always-on tuner (no signal /
+            // steady pitch) instead of pinning a core at 60 fps forever.
+            if (Math.abs(targetDrumY - currentDrumY) <= _SETTLE_Y
+                    && Math.abs(targetAngle - currentAngle) <= _SETTLE_A) {
+                currentDrumY = targetDrumY; currentAngle = targetAngle;
+                freqStrip.style.transform = 'translateY(' + currentDrumY + 'px)';
+                noteStrip.style.transform = 'translateY(' + currentDrumY + 'px)';
+                _setNeedle(currentAngle);
+                rafId = null;
+                return;
+            }
             rafId = requestAnimationFrame(_animate);
         }
 
+        // Restart the loop only when there's actually something to animate toward
+        // (a new target). Reset lastTime so the first frame after an idle gap
+        // doesn't take one big easing step.
+        function _kick() {
+            if (rafId === null
+                    && (Math.abs(targetDrumY - currentDrumY) > _SETTLE_Y
+                        || Math.abs(targetAngle - currentAngle) > _SETTLE_A)) {
+                lastTime = performance.now();
+                rafId = requestAnimationFrame(_animate);
+            }
+        }
+
         rafId = requestAnimationFrame(_animate);
 
         // ── Public API ────────────────────────────────────────────────
@@ -360,6 +387,7 @@
                 bulbEl.style.backgroundColor = '#2a1010';
                 bulbEl.style.border = '2px solid #4a2020';
                 bulbEl.style.boxShadow = 'none';
+                _kick();   // animate back to rest, then the loop self-stops
                 return;
             }
 
@@ -376,6 +404,7 @@
                 bulbEl.style.border = '2px solid #4a2020';
                 bulbEl.style.boxShadow = 'none';
             }
+            _kick();   // a new reading moved the target → run until it settles
         }
 
         function destroy() {

plugins/tuner/visualization/chef-mt3.js

@@ -620,8 +620,20 @@
             if (_mt3Mode === 'strobe') { _computeStrobeStates(); }
 
             _applyTickStates();
+
+            // No signal and both the glow and strobe drift have fully settled →
+            // idle the loop. update() re-kicks it on the next note.
+            if (!_mt3HasSignal && _mt3GlowOpacity < 0.004
+                    && Math.abs(_mt3SmoothedCents) <= 0.1) {
+                _mt3RafId = null;
+                _mt3LastTime = null;
+                return;
+            }
             _mt3RafId = requestAnimationFrame(_animateStrobe);
         }
+        function _kick() {
+            if (_mt3RafId === null) { _mt3LastTime = null; _mt3RafId = requestAnimationFrame(_animateStrobe); }
+        }
         _mt3RafId = requestAnimationFrame(_animateStrobe);
 
         // ── MODE button ───────────────────────────────────────────────
@@ -677,6 +689,7 @@
                 _renderNote(' ');
                 _applyAccidental();
             }
+            if (hasNote) { _kick(); }   // new signal → restart the strobe loop if idled
         }
 
         // ── Public: destroy ───────────────────────────────────────────

plugins/tuner/visualization/mace-fx-iii.js

@@ -354,10 +354,19 @@
                 if (_smoothedCents > 0) { speed = -speed; }
                 _strobeOffset = ((_strobeOffset + speed * dt) % _totalDash + _totalDash) % _totalDash;
                 arcPath.setAttribute('stroke-dashoffset', String(_strobeOffset));
+            } else if (_currentCents === 0) {
+                // Fully decelerated and no live signal → idle the loop instead of
+                // rescheduling forever. update() re-kicks it on the next note.
+                _rafId = null;
+                _lastTime = null;
+                return;
             }
 
             _rafId = requestAnimationFrame(_animateStrobe);
         }
+        function _kick() {
+            if (_rafId === null) { _lastTime = null; _rafId = requestAnimationFrame(_animateStrobe); }
+        }
         _rafId = requestAnimationFrame(_animateStrobe);
 
         // ── Helper: derive octave number from frequency ───────────────
@@ -439,6 +448,7 @@
 
             // Strobe state — smoothed animation decelerates naturally when _currentCents → 0
             _currentCents = hasNote ? cents : 0;
+            if (hasNote) { _kick(); }   // new signal → restart the decel loop if idled
         }
 
         // ── Public: destroy ───────────────────────────────────────────

plugins/tuner/visualization/strobe.js

@@ -142,9 +142,20 @@ window._tunerViz_strobe = function (container) {
             strobeEl.style.opacity = '0';
         }
 
+        // Idle the loop when there's no live signal — the strobe only needs to
+        // paint while a note is sounding. update() re-kicks it on the next note,
+        // so a silent tuner stops repainting instead of spinning at 60 fps.
+        if (!strobeActive) { rafId = null; return; }
         rafId = requestAnimationFrame(_animate);
     }
 
+    function _kick() {
+        if (rafId === null) {
+            lastAnimateTime = performance.now();
+            rafId = requestAnimationFrame(_animate);
+        }
+    }
+
     rafId = requestAnimationFrame(_animate);
 
     // ── Public API ────────────────────────────────────────────────────
@@ -188,6 +199,7 @@ window._tunerViz_strobe = function (container) {
         const inTune = Math.abs(cents) < 5;
         strobeEl.style.opacity = inTune ? '1' : '0.6';
         strobeEl.style.filter = inTune ? _STROBE_GLOW_IN_TUNE : _STROBE_GLOW_OUT;
+        _kick();
     }
 
     function destroy() {

plugins/tuner/visualization/toilet-tuner.js

@@ -122,6 +122,26 @@
             plungerEl.style.left = _leftPct.toFixed(2) + '%';
             plungerEl.style.top  = _topPct.toFixed(2)  + '%';
 
+            // No live signal and the plunger has eased back to its resting centre
+            // → idle the loop. update() re-kicks it on the next note.
+            if (_currentNote === null && !_plungerDipped
+                    && Math.abs(targetLeft - _leftPct) < 0.05) {
+                _leftPct = targetLeft;
+                plungerEl.style.left = _leftPct.toFixed(2) + '%';
+                _rafId = null;
+                _lastTime = null;
+                return;
+            }
+
+            _rafId = requestAnimationFrame(_animate);
+        }
+
+        function _kick() {
+            if (_rafId !== null) return;
+            // Already parked at rest with no signal → nothing to animate, stay idle.
+            if (_currentNote === null && !_plungerDipped
+                    && Math.abs(_TUNER_TT_CENTRE_PCT - _leftPct) < 0.05) return;
+            _lastTime = null;
             _rafId = requestAnimationFrame(_animate);
         }
 
@@ -130,6 +150,7 @@
             _currentNote  = note;
             _currentCents = note === null ? 0 : cents;
             if (!_plungerDipped) { noteEl.textContent = note || '–'; }
+            _kick();   // a new reading may move the plunger → ensure the loop runs
         }
 
         function destroy() {

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/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.tunings && t.tunings[key]) || 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
@@ -248,6 +266,7 @@ function createHighway() {
     let _frameMsEMA = 0;            // smoothed frame interval (for the HUD)
     let _lastFramePerf = 0;
     let _lastAutoAdjustAt = 0;
+    let _lastUpscaleAt = 0;          // separate, longer clock for UPscaling (lazy)
     let _perfHud = null;
     let _hudOn = false;       // cached highwayPerfHud flag (re-read ~2x/sec, not per-frame)
     let _hudFlagAt = 0;
@@ -266,6 +285,11 @@ function createHighway() {
         return Number.isFinite(v) ? Math.max(_AUTO_SCALE_MIN, Math.min(1, v)) : _AUTO_SCALE_MIN;
     })();
     const _AUTO_ADJUST_COOLDOWN_MS = 600;
+    // Upscaling is deliberately LAZY (longer cooldown than the downscale path) so
+    // the resolution doesn't visibly hunt up/down on passages that hover near the
+    // budget — testers saw "quality going up and down" as parts got busier (#618
+    // charrette). Downscale stays prompt to protect the frame rate.
+    const _AUTO_UPSCALE_COOLDOWN_MS = 2500;
     let _inverted = localStorage.getItem('invertHighway') === 'true';
     let _lefty = localStorage.getItem('lefty') === '1';
     let _lastChordOnFretLine = null;  // chord object currently shown on fret line
@@ -727,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 = {
@@ -1041,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
@@ -1240,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
@@ -1291,9 +1341,22 @@ function createHighway() {
         const eff = _effectiveRenderScale();
         let next = _autoScale;
         if (_drawMsEMA > _DRAW_BUDGET_HI_MS && eff > _autoScaleMin) {
+            // Over budget — downscale promptly to protect the frame rate, and reset
+            // the upscale clock so we don't immediately bounce back up.
             next = _autoScale * 0.85;
-        } else if (_drawMsEMA < _DRAW_BUDGET_LO_MS && eff < 1) {
-            next = _autoScale * 1.1;
+            _lastUpscaleAt = nowP;
+        } else if (_drawMsEMA < _DRAW_BUDGET_LO_MS && eff < 1
+                   && nowP - _lastUpscaleAt >= _AUTO_UPSCALE_COOLDOWN_MS) {
+            // Headroom — upscale LAZILY: a smaller step on a longer cooldown, and
+            // only when the projected cost AFTER the step (cost scales ~with the
+            // pixel count, i.e. step²) still clears the high budget. That predictive
+            // guard is what stops the up→over-budget→down ping-pong testers saw: the
+            // scale settles just inside the deadband instead of oscillating across it.
+            const step = 1.06;
+            if (_drawMsEMA * step * step < _DRAW_BUDGET_HI_MS) {
+                next = _autoScale * step;
+                _lastUpscaleAt = nowP;
+            }
         }
         // Clamp so _renderScale * _autoScale stays within [_autoScaleMin, 1].
         // Cap `lo` at 1: when the floor exceeds the manual ceiling (e.g. quality
@@ -1494,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;
@@ -2605,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) ──
     //
@@ -2937,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
@@ -2978,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();
@@ -3511,6 +3597,13 @@ function createHighway() {
                                     // matchesArrangement on this rather than the
                                     // arrangement name.
                                     hasNotation: Boolean(msg.has_notation),
+                                    // Feedpak contributor credits (manifest
+                                    // `authors:`, spec §5.4): [{name, role}].
+                                    // Only real feedpak plays carry these; loose/
+                                    // archive sources and synthetic highway uses
+                                    // (minigames) get []. app.js shows a credits
+                                    // overlay on song load when this is non-empty.
+                                    authors: Array.isArray(msg.authors) ? msg.authors : [],
                                 };
                                 window.feedBack.emit('song:loaded', window.feedBack.currentSong);
                             }
@@ -3745,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
@@ -3753,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">
@@ -103,10 +104,13 @@
                         <button id="view-tree-btn" onclick="setLibView('tree')" class="px-3 py-2.5 text-sm transition" title="Artist/Album view">
                             <svg class="w-4 h-4" fill="currentColor" viewBox="0 0 16 16"><rect x="1" y="1" width="14" height="3" rx="1"/><rect x="3" y="6" width="12" height="3" rx="1"/><rect x="3" y="11" width="12" height="3" rx="1"/></svg>
                         </button>
+                            <button id="view-folder-btn" onclick="setLibView('folder')" class="px-3 py-2.5 text-sm transition" title="Folder view">
+                                <svg class="w-4 h-4" fill="currentColor" viewBox="0 0 16 16"><path d="M1 3.5A1.5 1.5 0 012.5 2h3.086a1.5 1.5 0 011.06.44l.915.914H13.5A1.5 1.5 0 0115 4.914V12.5a1.5 1.5 0 01-1.5 1.5h-11A1.5 1.5 0 011 12.5v-9z"/></svg>
+                            </button>
                     </div>
                     <!-- Grid controls -->
                     <select id="lib-sort" onchange="sortLibrary()"
-                        class="lib-grid-ctrl bg-dark-700 border border-gray-800 rounded-xl px-3 py-2.5 text-sm text-gray-300 outline-none">
+                        class="lib-nontree-ctrl bg-dark-700 border border-gray-800 rounded-xl px-3 py-2.5 text-sm text-gray-300 outline-none">
                         <option value="artist">Artist A-Z</option>
                         <option value="artist-desc">Artist Z-A</option>
                         <option value="title">Title A-Z</option>
@@ -147,6 +151,9 @@
             <div id="lib-tree" class="space-y-2 hidden">
                 <!-- Tree populated by JS -->
             </div>
+            <div id="lib-folder-tree" class="space-y-1 hidden">
+                <!-- Folder tree populated by JS when Folders source is active -->
+            </div>
         </section>
 
         <!-- ══ Filters drawer (feedBack#129/#69/#22) ═════════════════════ -->
@@ -578,6 +585,13 @@
                 <option value="">Saved Loops</option>
             </select>
             <button onclick="deleteSelectedLoop()" id="btn-loop-delete" class="px-2 py-1.5 bg-dark-600 hover:bg-red-900/50 rounded-lg text-xs text-gray-500 hover:text-red-400 transition hidden" title="Delete selected loop">✕</button>
+            <!-- Editor ⇄ 3D Highway round-trip. "Edit region" opens the Song Editor
+                 scrolled to the active loop (or the section at the playhead).
+                 "↩ Editor" returns to the editing position you came from; it only
+                 appears after a Loop-in-3D handoff. Both are hidden when the editor
+                 plugin isn't loaded (state managed by _updateEditRegionBtn). -->
+            <button onclick="editRegionInEditor()" id="btn-edit-region" class="px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs text-gray-300 transition hidden" title="Edit this region in the Song Editor">✎ Edit region</button>
+            <button onclick="returnToEditorFromHighway()" id="btn-return-editor" class="px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs text-gray-300 transition hidden" title="Return to the editor where you left off">↩ Editor</button>
             <button onclick="showScreen('home')" class="ml-auto px-3 py-1.5 bg-dark-600 hover:bg-red-900/50 rounded-lg text-xs text-gray-400 hover:text-red-400 transition">✕ Close</button>
         </div>
         </div>

static/style.css

@@ -863,3 +863,93 @@ html { scroll-behavior: smooth; }
   box-shadow: 0 0 0 2px rgba(64, 128, 224, 0.7);
   border-radius: 0.25rem;
 }
+
+/* Feedpak contributor credits shown over the highway when a song loads
+   (manifest `authors:`, spec §5.4). Anchored to the upper third so it sits
+   ABOVE the vertically-centered count-in number; click-through. */
+.song-credits-overlay {
+  position: fixed;
+  left: 0;
+  right: 0;
+  top: 15%;
+  /* Above the modal layer (z-[200], incl. the "Loading audio" backdrop) and
+     the count-in number (z-[100]) so the credits stay prominent through the
+     whole load → count-in → play window. */
+  z-index: 205;
+  display: flex;
+  justify-content: center;
+  pointer-events: none;
+  animation: song-credits-fade-in 0.45s cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+.song-credits-card {
+  position: relative;
+  min-width: 16rem;
+  max-width: min(90vw, 34rem);
+  padding: 1.4rem 2.5rem 1.5rem;
+  text-align: center;
+  background:
+    radial-gradient(120% 140% at 50% 0%, rgb(56 78 130 / 0.45) 0%, transparent 60%),
+    linear-gradient(165deg, rgb(23 30 48 / 0.92) 0%, rgb(11 15 26 / 0.94) 100%);
+  border: 1px solid rgb(129 140 248 / 0.28);
+  border-radius: 1rem;
+  box-shadow:
+    0 18px 50px rgb(0 0 0 / 0.55),
+    0 0 0 1px rgb(0 0 0 / 0.35),
+    inset 0 1px 0 rgb(255 255 255 / 0.07);
+  backdrop-filter: blur(10px);
+  -webkit-backdrop-filter: blur(10px);
+}
+
+/* Accent bar across the top edge of the card. */
+.song-credits-card::before {
+  content: "";
+  position: absolute;
+  top: 0;
+  left: 50%;
+  transform: translateX(-50%);
+  width: 3.25rem;
+  height: 3px;
+  border-radius: 0 0 3px 3px;
+  background: linear-gradient(90deg, #38bdf8, #818cf8);
+  box-shadow: 0 0 12px rgb(99 102 241 / 0.7);
+}
+
+.song-credits-eyebrow {
+  font-size: 0.68rem;
+  font-weight: 700;
+  letter-spacing: 0.22em;
+  text-transform: uppercase;
+  color: rgb(165 180 252 / 0.9);
+  margin-bottom: 0.4rem;
+}
+
+.song-credits-heading {
+  font-size: 1.3rem;
+  font-weight: 800;
+  color: #f8fafc;
+  margin-bottom: 0.7rem;
+  letter-spacing: 0.01em;
+  text-shadow: 0 1px 8px rgb(0 0 0 / 0.5);
+}
+
+.song-credits-line {
+  font-size: 1.1rem;
+  line-height: 1.55;
+  color: #e2e8f0;
+}
+
+.song-credits-role {
+  color: rgb(148 163 184 / 0.95);
+  font-weight: 500;
+}
+
+.song-credits-name {
+  font-weight: 700;
+  color: #ffffff;
+}
+
+@keyframes song-credits-fade-in {
+  from { opacity: 0; transform: translateY(-12px) scale(0.97); }
+  to   { opacity: 1; transform: translateY(0) scale(1); }
+}

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>' +