refactor(app): carve resume-session out of app.js (R3a)

static/js/resume-session.js (157) — the snapshot taken when you leave a song and the
pill that offers it back. Bodies VERBATIM. app.js 7,727 → 7,601.
Fifth slice out of the strongly-connected core. ONE hook (playSong) + a
currentFilename getter.

S.pendingResume JOINS THE CONTAINER — on demand, exactly as intended. app.js WRITES
it (playSong({ resume }) arms it; the song:ready listener consumes it) while this
module reads it, so it cannot be a plain export: an imported binding is read-only.
Same reason isPlaying is there. The container grows one field per carve that needs
it, never speculatively.

THE CONTRACT TEST CAUGHT THE MISSING HOOK, again on a path nothing executes:
"playSong is read by a module but never wired by app.js — it would throw at runtime".
Second time it has caught a real wiring gap the moment it appeared.

A REAL TRAP, worth remembering: I first did the S.pendingResume rewrite by feeding
acorn's identifier RANGES from node into python, and it corrupted the file
(`_pS.pendingResume null;`). **Acorn's offsets are UTF-16 code units; Python's string
indices are code points.** static/app.js contains emoji, so every offset past one
drifts. Do an AST-driven rewrite in the SAME language that produced the offsets.
`node --check` caught it; a silent version of that bug is very easy to imagine.

VERIFIED. A/B against origin/main in two browsers, real song: the window API
(resumeLastSession / _snapshotResumeSession / _readResumeSession /
_clearResumeSession), snapshot, read-back, and clear — IDENTICAL, zero page errors.
HONEST LIMIT: my probe never got the snapshot to actually PERSIST (there is a guard
beyond the 3s minimum position that a scripted playSong does not satisfy), so that
path is verified only as identical-to-main, not as observed-working. The real
coverage is tests/browser/resume-session.spec.ts, which drives the flow properly.

Zero harnesses broke. pytest 2396, node 1040/1040, ESLint 0 (no-cycle clean),
tailwind clean, Codex 0.

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

static/js/audio-el.js

@@ -0,0 +1,17 @@
+// The one <audio> element the whole app plays through.
+//
+// This exists so that code carved out of app.js can reach the player without
+// importing app.js back — which would close a cycle and fail the import-x/no-cycle
+// gate. It is the same handle app.js has always held (`document.getElementById`
+// on the element in the shell), just given a home of its own.
+//
+// It is deliberately a `const`, and it is never reassigned anywhere in core — so a
+// read-only import binding is exactly right, and no state container is needed.
+// (Contrast the reassigned scalars — isPlaying, _avOffsetMs, … — which cannot be
+// shared this way, because an imported binding cannot be written to.)
+//
+// Module scripts evaluate after the HTML is parsed, so the element is already in
+// the document by the time this runs. app.js is loaded as <script type="module">,
+// and its imports evaluate before its body — the same point at which app.js used
+// to run this exact lookup itself.
+export const audio = document.getElementById('audio');

static/js/count-in.js

@@ -0,0 +1,389 @@
+// Count-in — the 1-2-3-4 click before playback, plus the song-credits overlay that
+// shares its lifecycle and timers.
+//
+// The third slice out of app.js's strongly-connected core, and the first that had to
+// WRITE shared state rather than just read it. It starts and stops playback, so it sets
+// `isPlaying` and `lastAudioTime`. An imported binding is read-only — `isPlaying = true`
+// throws — which is exactly why those two scalars were lifted onto the container in
+// ./player-state.js. Every earlier slice only READ what it shared, so a getter hook
+// sufficed; this one could not.
+//
+// It imports the loop module directly (setLoop / loopA / loopB — a count-in that starts
+// inside an A-B loop must begin at A). Nothing imports count-in back: app.js and
+// section-practice both reach it through the host seam, so the graph stays acyclic.
+//
+// app.js's autoplay path used to reach IN and set the credits timers itself. It cannot
+// now, and it should not have to — so the module exports the OPERATIONS instead
+// (armCreditsHideOnPlay, scheduleCreditsHide, holdCreditsThen, isCountingIn) and owns
+// its own timer invariants. Same reason section-practice grew resetSelection().
+//
+// See ./host.js: reading an unwired hook THROWS, and tests/js/host_contract.test.js
+// fails CI if the hooks used here and the hooks app.js wires ever drift apart.
+import { audio } from './audio-el.js';
+import { host } from './host.js';
+import { loopA, loopB, setLoop } from './loops.js';
+import { S } from './player-state.js';
+
+// ── Count-in click sound (Web Audio API) ────────────────────────────────
+let _audioCtx = null;
+export function playClick(high = false) {
+    if (!_audioCtx) _audioCtx = new (window.AudioContext || window.webkitAudioContext)();
+    const osc = _audioCtx.createOscillator();
+    const gain = _audioCtx.createGain();
+    osc.connect(gain);
+    gain.connect(_audioCtx.destination);
+    osc.frequency.value = high ? 1200 : 800;
+    osc.type = 'sine';
+    gain.gain.setValueAtTime(0.5, _audioCtx.currentTime);
+    gain.gain.exponentialRampToValueAtTime(0.001, _audioCtx.currentTime + 0.08);
+    osc.start(_audioCtx.currentTime);
+    osc.stop(_audioCtx.currentTime + 0.08);
+}
+
+let _countingIn = false;
+let _countOverlay = null;
+// Generation token so teardown can cancel an in-progress count-in. Each
+// startCountIn() captures the gen at entry; rewindStep, the loop-wrap
+// then-callback, and beginCount's tick all bail when their captured gen
+// no longer matches. Bumped by _cancelCountIn().
+let _countInGen = 0;
+let _countInTimer = null;
+let _countInRaf = 0;
+// Feedpak credits overlay (manifest `authors:`, spec §5.4): shown on the
+// highway when a song is loaded, alongside the count-in. Torn down together
+// with the count-in via _cancelCountIn().
+let _creditsOverlay = null;
+let _creditsTimer = null;
+let _creditsHideOnPlay = null;
+let _creditsMaxTimer = null;
+const _CREDITS_HOLD_MS = 3000;
+// Backstop: the overlay's primary dismiss is song:play, but playback can fail
+// to start without emitting it (HTML5 autoplay rejection, JUCE start failure,
+// a count-in handoff that never plays). This hard cap guarantees the credits
+// never linger over the highway. Generous enough to outlast a normal count-in.
+const _CREDITS_MAX_MS = 12000;
+export function _cancelCountIn() {
+    _countInGen++;
+    _countingIn = false;
+    hideCountOverlay();
+    // The credits overlay rides the count-in lifecycle (and its no-count-in
+    // hold timer), so a teardown — leaving the player, loading another song —
+    // must clear it too, or it lingers on the next screen.
+    hideSongCreditsOverlay();
+    if (_countInTimer) { clearTimeout(_countInTimer); _countInTimer = null; }
+    if (_countInRaf) { cancelAnimationFrame(_countInRaf); _countInRaf = 0; }
+}
+
+export function showCountOverlay(n) {
+    if (!_countOverlay) {
+        _countOverlay = document.createElement('div');
+        _countOverlay.className = 'fixed inset-0 z-[100] flex items-center justify-center pointer-events-none';
+        document.body.appendChild(_countOverlay);
+    }
+    _countOverlay.innerHTML = `<span class="text-9xl font-black text-white/30">${n}</span>`;
+}
+
+export function hideCountOverlay() {
+    if (_countOverlay) { _countOverlay.remove(); _countOverlay = null; }
+}
+
+// Map a feedpak author `role` to a friendly "<verb> by" credit line. The
+// recommended vocabulary is from feedpak spec §5.4; unknown roles are
+// title-cased ("foo" → "Foo by"); a missing role shows the bare name.
+const _CREDIT_ROLE_VERBS = {
+    charter: 'Charted by',
+    transcriber: 'Transcribed by',
+    arranger: 'Arranged by',
+    editor: 'Edited by',
+    mixer: 'Mixed by',
+    engineer: 'Engineered by',
+    proofreader: 'Proofread by',
+};
+
+function _creditLineLabel(role) {
+    if (!role) return '';
+    const key = String(role).trim().toLowerCase();
+    if (_CREDIT_ROLE_VERBS[key]) return _CREDIT_ROLE_VERBS[key];
+    return key.charAt(0).toUpperCase() + key.slice(1) + ' by';
+}
+
+// Show the feedpak contributor credits over the highway. `authors` is the
+// sanitized [{name, role}] list from window.feedBack.currentSong.authors.
+// Anchored to the lower third (bottom-center) so it never collides with the
+// vertically-centered count-in number, and pointer-events-none so it never
+// intercepts clicks. No-op when there are no contributors to show.
+export function showSongCreditsOverlay(authors) {
+    if (!Array.isArray(authors) || authors.length === 0) return;
+    if (!_creditsOverlay) {
+        _creditsOverlay = document.createElement('div');
+        _creditsOverlay.className = 'song-credits-overlay';
+        document.body.appendChild(_creditsOverlay);
+    }
+    // Build via DOM + textContent — author names are untrusted pack data and
+    // must never be interpolated as HTML.
+    _creditsOverlay.replaceChildren();
+    const card = document.createElement('div');
+    card.className = 'song-credits-card';
+
+    const eyebrow = document.createElement('div');
+    eyebrow.className = 'song-credits-eyebrow';
+    eyebrow.textContent = 'Credits';
+    card.appendChild(eyebrow);
+
+    const title = (window.feedBack && window.feedBack.currentSong
+        && window.feedBack.currentSong.title) || '';
+    if (title) {
+        const heading = document.createElement('div');
+        heading.className = 'song-credits-heading';
+        heading.textContent = title;
+        card.appendChild(heading);
+    }
+
+    for (const a of authors) {
+        if (!a || !a.name) continue;
+        const row = document.createElement('div');
+        row.className = 'song-credits-line';
+        const label = _creditLineLabel(a.role);
+        if (label) {
+            const lab = document.createElement('span');
+            lab.className = 'song-credits-role';
+            lab.textContent = label + ' ';
+            row.appendChild(lab);
+        }
+        const nm = document.createElement('span');
+        nm.className = 'song-credits-name';
+        nm.textContent = a.name;
+        row.appendChild(nm);
+        card.appendChild(row);
+    }
+    _creditsOverlay.appendChild(card);
+    // Arm the backstop so the overlay self-clears even if playback never starts
+    // / never emits song:play. song:play (or any teardown) clears it earlier.
+    if (_creditsMaxTimer) clearTimeout(_creditsMaxTimer);
+    _creditsMaxTimer = setTimeout(hideSongCreditsOverlay, _CREDITS_MAX_MS);
+}
+
+export function hideSongCreditsOverlay() {
+    if (_creditsTimer) { clearTimeout(_creditsTimer); _creditsTimer = null; }
+    if (_creditsMaxTimer) { clearTimeout(_creditsMaxTimer); _creditsMaxTimer = null; }
+    if (_creditsHideOnPlay) {
+        window.feedBack.off('song:play', _creditsHideOnPlay);
+        _creditsHideOnPlay = null;
+    }
+    if (_creditsOverlay) { _creditsOverlay.remove(); _creditsOverlay = null; }
+}
+
+export async function startCountIn(opts = {}) {
+    if (_countingIn) return;
+    _countingIn = true;
+    // Snapshot the current gen so every delayed callback (rewind frames,
+    // post-seek then, count-in ticks, post-count play) can bail if a
+    // teardown bumped the gen mid-flight via _cancelCountIn().
+    const gen = _countInGen;
+    const immediate = !!opts.immediate;
+    if (window._juceMode) {
+        await host.jucePlayer().pause().catch((err) => console.error('[app] host.jucePlayer().pause error in count-in:', err));
+    } else {
+        audio.pause();
+    }
+    if (gen !== _countInGen) return; // teardown during pause
+
+    // Section-practice entry: already at loop A after setLoop(); skip the
+    // B→A rewind animation used on loop wrap and go straight to clicks.
+    if (immediate) {
+        if (loopA === null || loopB === null) {
+            _countingIn = false;
+            return;
+        }
+        S.lastAudioTime = loopA;
+        highway.setTime(loopA);
+        if (window.feedBack) {
+            window.feedBack.emit('loop:restart', { loopA, loopB, time: loopA });
+        }
+        beginCount();
+        return;
+    }
+
+    // Rewind animation: sweep highway time from B to A
+    const rewindDuration = 400; // ms
+    const rewindStart = performance.now();
+    const fromTime = loopB;
+    const toTime = loopA;
+
+    function rewindStep(now) {
+        if (gen !== _countInGen) return; // teardown mid-rewind
+        const elapsed = now - rewindStart;
+        const t = Math.min(elapsed / rewindDuration, 1);
+        // Ease out quad
+        const eased = 1 - (1 - t) * (1 - t);
+        const currentT = fromTime + (toTime - fromTime) * eased;
+        highway.setTime(currentT);
+        if (t < 1) {
+            _countInRaf = requestAnimationFrame(rewindStep);
+        } else {
+            _countInRaf = 0;
+            // Rewind done — set final position and start count.
+            // Await the JUCE seek so the engine has repositioned before
+            // we start the click track (HTML5 path is synchronous).
+            host._audioSeek(loopA, 'loop-wrap').then((r) => {
+                if (gen !== _countInGen) return; // teardown during seek
+                // Abort the loop restart in two cases:
+                //   1. Cancelled (player torn down): don't beginCount on a
+                //      new session.
+                //   2. Off-target landing (JUCE rollback / clamp far from
+                //      loopA): proceeding would emit loop:restart and start
+                //      a count-in from the wrong position. Audio is at
+                //      r.from / r.to, which is not where the loop wants to
+                //      resume — better to drop this iteration than play out
+                //      of sync.
+                // 50 ms tolerance: well within JUCE's normal seek precision
+                // but tight enough to catch a real rollback or no-op.
+                if (!r.completed || Math.abs(r.to - loopA) > 0.05) {
+                    // startCountIn paused audio at entry but left isPlaying
+                    // alone — beginCount would have set it on resume. On
+                    // abort, sync the transport: audio is paused, so
+                    // isPlaying must reflect that and the button + plugin
+                    // host must agree.
+                    _countingIn = false;
+                    if (S.isPlaying) {
+                        S.isPlaying = false;
+                        host.setPlayButtonState(false);
+                        if (window.feedBack) {
+                            window.feedBack.isPlaying = false;
+                            window.feedBack.emit('song:pause', host._songEventPayload());
+                        }
+                    }
+                    return;
+                }
+                // Use the verified post-seek clock for the chart so audio
+                // and chart stay in sync if JUCE clamped to slightly
+                // before/after loopA. The loop:restart event keeps `time:
+                // loopA` because subscribers treat that as the semantic
+                // marker for "new iteration starts at A", not the actual
+                // audio position.
+                S.lastAudioTime = r.to;
+                highway.setTime(r.to);
+                window.feedBack.emit('loop:restart', { loopA, loopB, time: loopA });
+                beginCount();
+            });
+        }
+    }
+    _countInRaf = requestAnimationFrame(rewindStep);
+
+    function beginCount() {
+        const bpm = highway.getBPM(loopA);
+        const beatInterval = 60 / bpm;
+        let count = 0;
+
+        function tick() {
+            if (gen !== _countInGen) return; // teardown mid-count
+            count++;
+            if (count > 4) {
+                hideCountOverlay();
+                _countingIn = false;
+                if (window._juceMode) {
+                    host.jucePlayer().play().then((started) => {
+                        if (gen !== _countInGen) return; // teardown during play start
+                        if (!started) return;
+                        S.isPlaying = true;
+                        host.setPlayButtonState(true);
+                        window.feedBack.isPlaying = true;
+                        const payload = host._songEventPayload();
+                        window.feedBack.emit('song:play', payload);
+                        window.feedBack.emit('song:resume', payload);
+                    }).catch((err) => console.error('[app] host.jucePlayer().play error:', err));
+                } else {
+                    audio.play().then(() => {
+                        if (gen !== _countInGen) return;
+                        S.isPlaying = true;
+                        host.setPlayButtonState(true);
+                    }).catch((err) => {
+                        if (gen !== _countInGen) return;
+                        // An engine reroute's deliberate pause aborts this play()
+                        // while playback continues on JUCE — don't reset the
+                        // button (mirrors the togglePlay guard).
+                        if (window._juceRerouteInProgress) return;
+                        // Same rationale as togglePlay: don't claim playback
+                        // started if the Promise rejected.
+                        console.error('[app] audio.play() rejected after count-in:', err);
+                        S.isPlaying = false;
+                        host.setPlayButtonState(false);
+                    });
+                }
+                return;
+            }
+            showCountOverlay(count);
+            playClick(count === 1);
+            _countInTimer = setTimeout(tick, beatInterval * 1000);
+        }
+        _countInTimer = setTimeout(tick, 500);
+    }
+}
+
+// Start-of-song count-in: a 4-beat click before playback begins, gated by the
+// "Countdown before song" setting (Gameplay tab). Mirrors the loop count-in's
+// overlay + click + gen-token cancellation, but counts from the song's current
+// position (0 at song start) with no loop A/B rewind. startCountIn() is loop-
+// coupled (early-returns when loopA/loopB are null), so this is a sibling
+// rather than an overload. Hands off to togglePlay() once the count completes.
+export async function startSongCountIn() {
+    if (_countingIn) return;
+    _countingIn = true;
+    // Snapshot the gen so a teardown (showScreen/playSong calls _cancelCountIn)
+    // bumps it and every delayed callback below bails.
+    const gen = _countInGen;
+    if (window._juceMode) {
+        await host.jucePlayer().pause().catch((err) => console.error('[app] host.jucePlayer().pause error in song count-in:', err));
+    } else {
+        audio.pause();
+    }
+    if (gen !== _countInGen) return; // teardown during pause
+    const startT = S.lastAudioTime || 0;
+    let bpm = highway.getBPM(startT);
+    // Pre-chart / malformed-tempo fallback: 4 beats at 120 BPM (500 ms each).
+    if (!Number.isFinite(bpm) || bpm <= 0) bpm = 120;
+    const beatInterval = 60 / bpm;
+    let count = 0;
+    function tick() {
+        if (gen !== _countInGen) return; // teardown mid-count
+        count++;
+        if (count > 4) {
+            hideCountOverlay();
+            _countingIn = false;
+            // Hand off to the normal play path — togglePlay() flips isPlaying,
+            // updates the button, and emits song:play/resume for plugins.
+            Promise.resolve(host.togglePlay()).catch((err) => console.warn('[app] play after count-in failed:', err));
+            return;
+        }
+        showCountOverlay(count);
+        playClick(count === 1);
+        _countInTimer = setTimeout(tick, beatInterval * 1000);
+    }
+    // First beat after a short lead-in, matching the loop count-in's 500 ms.
+    _countInTimer = setTimeout(tick, 500);
+}
+
+// ── Operations app.js's autoplay path used to perform by reaching in ────────
+// It used to assign _creditsTimer / _creditsHideOnPlay directly. Imported bindings are
+// read-only, and the module should own its own timer invariants anyway.
+
+/** Is a count-in running? app.js's timeupdate handler suppresses highway sync during one. */
+export function isCountingIn() {
+    return _countingIn;
+}
+
+/** Dismiss the credits the moment real playback begins. Fires once. */
+export function armCreditsHideOnPlay() {
+    _creditsHideOnPlay = () => { _creditsHideOnPlay = null; hideSongCreditsOverlay(); };
+    window.feedBack.on('song:play', _creditsHideOnPlay, { once: true });
+}
+
+/** Let the credits dwell, then clear them. Used when autoplay-exit is disabled. */
+export function scheduleCreditsHide() {
+    _creditsTimer = setTimeout(hideSongCreditsOverlay, _CREDITS_HOLD_MS);
+}
+
+/** Let the credits dwell, then run `then` (the autoplay start). */
+export function holdCreditsThen(then) {
+    _creditsTimer = setTimeout(() => { _creditsTimer = null; then(); }, _CREDITS_HOLD_MS);
+}

static/js/diagnostics-export.js

@@ -0,0 +1,280 @@
+// The diagnostics-bundle export — the Settings "Export diagnostics" flow.
+//
+// Carved verbatim out of static/app.js (R3a). A LEAF module: imports nothing.
+// It snapshots the browser-only state (console ring buffer, hardware probe,
+// localStorage, ua) via window.feedBack.diagnostics, POSTs it to
+// /api/diagnostics/export with the user's include/redact toggles, and streams the
+// returned zip to disk. Bundle layout + schemas: docs/diagnostics-bundle-spec.md.
+//
+// Everything except the two entry points is module-private — the preview
+// renderer, the file-label table, and the byte/HTML formatters are used nowhere
+// else in core.
+
+//
+// Companion to Settings export but for troubleshooting bug reports.
+// Bundle layout + schemas: docs/diagnostics-bundle-spec.md.
+//
+// Frontend's job is to:
+//   1. Snapshot the browser-only state (console ring buffer, hardware
+//      probe, localStorage, ua) via window.feedBack.diagnostics.
+//   2. POST it to /api/diagnostics/export with the user's include /
+//      redact toggles.
+//   3. Stream the returned zip to disk.
+
+function _diagIncludeFromUI() {
+    const v = (id) => document.getElementById(id)?.checked !== false;
+    return {
+        system: v('diag-incl-system'),
+        hardware: v('diag-incl-hardware'),
+        logs: v('diag-incl-logs'),
+        console: v('diag-incl-console'),
+        plugins: v('diag-incl-plugins'),
+    };
+}
+
+function _diagRedactFromUI() {
+    const el = document.getElementById('diag-redact');
+    return el ? !!el.checked : true;
+}
+
+// Map raw file paths inside the bundle to plain-English labels +
+// descriptions for the preview UI. Only paths that show up in
+// previews need entries — unknown paths fall back to the path itself.
+const _DIAG_FILE_LABELS = {
+    'system/version.json':   { label: 'App version',    desc: 'FeedBack version, Python, OS' },
+    'system/env.json':       { label: 'Environment',    desc: 'Allowlisted env vars (LOG_LEVEL, etc.). No secrets.' },
+    'system/hardware.json':  { label: 'Hardware (server-side)', desc: 'CPU, RAM, GPU. In Docker this reflects the container, not the host.' },
+    'system/plugins.json':   { label: 'Plugins',        desc: 'Loaded plugins + git commit + orphan detection.' },
+    'logs/server.log':       { label: 'Server log',     desc: 'Tail of LOG_FILE (last ~5 MB).' },
+    'logs/server.log.meta.json': { label: 'Log metadata', desc: 'Log file path, size, rotation info.' },
+    'client/console.json':   { label: 'Browser console', desc: 'console.log/warn/error transcript + window errors.' },
+    'client/hardware.json':  { label: 'Hardware (browser)', desc: 'WebGL/WebGPU adapter, host OS via userAgent.' },
+    'client/local_storage.json': { label: 'Browser storage', desc: 'localStorage contents (preferences).' },
+    'client/ua.json':        { label: 'User agent',     desc: 'Browser, screen, page URL.' },
+};
+
+function _formatBytes(n) {
+    if (!n || n < 1024) return (n || 0) + ' B';
+    if (n < 1024 * 1024) return (n / 1024).toFixed(1) + ' KB';
+    return (n / (1024 * 1024)).toFixed(1) + ' MB';
+}
+
+function _escapeHtml(s) {
+    return String(s || '').replace(/[&<>"']/g, c => ({
+        '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+    }[c]));
+}
+
+function _renderDiagPreview(data) {
+    const m = data.manifest || {};
+    const files = m.files || [];
+    const groups = { system: [], logs: [], client: [], plugins: [], other: [] };
+    for (const f of files) {
+        const top = (f.path || '').split('/')[0];
+        (groups[top] || groups.other).push(f);
+    }
+    const totalBytes = files.reduce((s, f) => s + (f.size || 0), 0);
+    const include = _diagIncludeFromUI();
+    const redact = _diagRedactFromUI();
+
+    const sections = [];
+    // Per-file `summary` (server-derived) → human one-liner.
+    function _summaryLine(path, summary) {
+        if (!summary || typeof summary !== 'object') return '';
+        if (path === 'system/plugins.json') {
+            const loaded = summary.loaded_count || 0;
+            const orphans = summary.orphan_count || 0;
+            const orphPart = orphans ? ` · <span class="text-amber-400">${orphans} orphan${orphans === 1 ? '' : 's'}</span>` : '';
+            return `${loaded} plugin${loaded === 1 ? '' : 's'} loaded${orphPart}`;
+        }
+        if (path === 'client/console.json') {
+            const total = summary.entry_count || 0;
+            const lvl = summary.by_level || {};
+            const parts = [];
+            for (const k of ['error','warn','info','log','debug']) {
+                if (lvl[k]) parts.push(`${lvl[k]} ${k}`);
+            }
+            return `${total} entries${parts.length ? ' (' + parts.join(', ') + ')' : ''}`;
+        }
+        if (path === 'system/hardware.json') {
+            const bits = [];
+            if (summary.cpu_brand) bits.push(summary.cpu_brand);
+            if (summary.cores_logical) bits.push(`${summary.cores_logical} cores`);
+            if (summary.gpu_count) bits.push(`${summary.gpu_count} GPU`);
+            if (summary.runtime) bits.push(`runtime: ${summary.runtime}`);
+            return bits.join(' · ');
+        }
+        if (path === 'client/hardware.json') {
+            const bits = [];
+            if (summary.runtime) bits.push(summary.runtime);
+            if (summary.webgl_renderer) bits.push(summary.webgl_renderer);
+            return bits.join(' · ');
+        }
+        if (path === 'client/local_storage.json') {
+            return `${summary.key_count || 0} keys`;
+        }
+        if (path === 'system/version.json') {
+            const bits = [];
+            if (summary.feedBack) bits.push(`feedBack ${summary.feedBack}`);
+            if (summary.python) bits.push(`python ${summary.python}`);
+            if (summary.os) bits.push(summary.os);
+            return bits.join(' · ');
+        }
+        return '';
+    }
+
+    function pushSection(title, list, emptyHint) {
+        if (!list.length) {
+            if (emptyHint) {
+                sections.push(`<div class="mb-3"><div class="text-gray-300 font-semibold mb-1">${_escapeHtml(title)}</div><div class="text-gray-500">${_escapeHtml(emptyHint)}</div></div>`);
+            }
+            return;
+        }
+        const rows = list.map(f => {
+            const meta = _DIAG_FILE_LABELS[f.path] || { label: f.path, desc: '' };
+            const summary = _summaryLine(f.path, f.summary);
+            const summaryHtml = summary
+                ? `<div class="text-accent-light text-[10px] mt-0.5">${summary}</div>`
+                : '';
+            return `<div class="flex justify-between gap-4 py-1 border-b border-dark-600 last:border-0">
+                <div class="min-w-0">
+                    <div class="text-gray-200">${_escapeHtml(meta.label)}</div>
+                    <div class="text-gray-500 text-[10px]">${_escapeHtml(meta.desc)}</div>
+                    ${summaryHtml}
+                </div>
+                <div class="text-gray-400 text-right whitespace-nowrap">${_escapeHtml(_formatBytes(f.size))}</div>
+            </div>`;
+        }).join('');
+        sections.push(`<div class="mb-3"><div class="text-gray-300 font-semibold mb-1">${_escapeHtml(title)}</div>${rows}</div>`);
+    }
+
+    pushSection('System', groups.system, include.system ? '' : 'Skipped (toggle off)');
+    pushSection('Server logs', groups.logs, include.logs
+        ? 'No log file configured — set LOG_FILE env var to include server logs.'
+        : 'Skipped (toggle off)');
+    pushSection('Plugin diagnostics', groups.plugins, include.plugins
+        ? 'No plugins have opted in to diagnostics.'
+        : 'Skipped (toggle off)');
+
+    // Client section preview is a server-side estimate only — actual
+    // client/* payloads are added at Export time after the browser
+    // snapshots. Show what WILL be added, not file sizes.
+    const clientLines = [];
+    if (include.console) clientLines.push({ label: 'Browser console', desc: 'console.log/warn/error transcript + window errors.' });
+    if (include.hardware) clientLines.push({ label: 'Hardware (browser)', desc: 'WebGL/WebGPU adapter, host OS via userAgent.' });
+    clientLines.push({ label: 'Browser storage', desc: 'localStorage contents (preferences).' });
+    clientLines.push({ label: 'User agent', desc: 'Browser, screen, page URL.' });
+    const clientHtml = clientLines.map(c => `<div class="flex justify-between gap-4 py-1 border-b border-dark-600 last:border-0">
+        <div><div class="text-gray-200">${_escapeHtml(c.label)}</div><div class="text-gray-500 text-[10px]">${_escapeHtml(c.desc)}</div></div>
+        <div class="text-gray-500 text-right whitespace-nowrap">added on export</div>
+    </div>`).join('');
+    sections.push(`<div class="mb-3"><div class="text-gray-300 font-semibold mb-1">Browser data</div>${clientHtml}</div>`);
+
+    const notesHtml = (m.notes || []).length
+        ? `<div class="mb-3 bg-dark-600 border border-amber-500/30 rounded-lg p-2">
+              <div class="text-amber-400 text-[10px] font-semibold uppercase mb-1">Notes</div>
+              ${(m.notes).map(n => `<div class="text-gray-300 text-[11px]">• ${_escapeHtml(n)}</div>`).join('')}
+           </div>`
+        : '';
+
+    const privacyHtml = redact
+        ? `<div class="text-emerald-400 text-[11px]">🔒 Redaction enabled — paths, song names, IPs, and secrets will be replaced with stable hash tokens.</div>`
+        : `<div class="text-amber-400 text-[11px]">⚠ Redaction OFF — bundle will contain raw paths, song names, and IPs. Only share with people you trust.</div>`;
+
+    return `
+        <div class="text-[11px]">
+            <div class="flex justify-between items-baseline mb-2">
+                <div class="text-gray-200 font-semibold">${_escapeHtml(data.filename)}</div>
+                <div class="text-gray-400">${_escapeHtml(_formatBytes(totalBytes))}<span class="text-gray-600"> server-side</span></div>
+            </div>
+            <div class="text-gray-500 text-[10px] mb-3">runtime: ${_escapeHtml(m.runtime || 'unknown')} · exported_at: ${_escapeHtml(m.exported_at || '')}</div>
+            ${notesHtml}
+            ${sections.join('')}
+            ${privacyHtml}
+        </div>`;
+}
+
+export async function previewDiagnostics() {
+    const status = document.getElementById('diag-status');
+    const preview = document.getElementById('diag-preview');
+    if (!status || !preview) return;
+    status.textContent = 'Building preview…';
+    preview.classList.add('hidden');
+    const include = _diagIncludeFromUI();
+    const params = new URLSearchParams({
+        redact: String(_diagRedactFromUI()),
+        system: String(include.system),
+        hardware: String(include.hardware),
+        logs: String(include.logs),
+        console: String(include.console),
+        plugins: String(include.plugins),
+    });
+    try {
+        const resp = await fetch(`/api/diagnostics/preview?${params.toString()}`);
+        if (!resp.ok) {
+            status.textContent = `Preview failed (HTTP ${resp.status})`;
+            return;
+        }
+        const data = await resp.json();
+        preview.innerHTML = _renderDiagPreview(data);
+        preview.classList.remove('hidden');
+        status.textContent = 'Preview ready.';
+    } catch (e) {
+        status.textContent = `Preview failed: ${e.message}`;
+    }
+}
+
+export async function exportDiagnostics() {
+    const status = document.getElementById('diag-status');
+    if (!status) return;
+    status.textContent = 'Building bundle…';
+    const include = _diagIncludeFromUI();
+    const redact = _diagRedactFromUI();
+
+    const diag = window.feedBack && window.feedBack.diagnostics;
+    const body = {
+        redact,
+        include,
+        client_console: include.console && diag ? diag.snapshotConsole() : null,
+        client_hardware: include.hardware && diag ? await diag.snapshotHardware() : null,
+        client_ua: diag ? diag.snapshotUa() : null,
+        local_storage: diag ? diag.snapshotLocalStorage() : null,
+        client_contributions: diag ? diag.snapshotContributions() : null,
+    };
+
+    let resp;
+    try {
+        resp = await fetch('/api/diagnostics/export', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+    } catch (e) {
+        status.textContent = `Export failed: ${e.message}`;
+        return;
+    }
+    if (!resp.ok) {
+        status.textContent = `Export failed (HTTP ${resp.status})`;
+        return;
+    }
+    let filename = 'feedBack-diag.zip';
+    const disp = resp.headers.get('Content-Disposition');
+    if (disp) {
+        const m = /filename="([^"]+)"/.exec(disp);
+        if (m) filename = m[1];
+    }
+    try {
+        const blob = await resp.blob();
+        const url = URL.createObjectURL(blob);
+        const a = document.createElement('a');
+        a.href = url;
+        a.download = filename;
+        document.body.appendChild(a);
+        a.click();
+        document.body.removeChild(a);
+        URL.revokeObjectURL(url);
+        status.textContent = `Exported ${filename}`;
+    } catch (e) {
+        status.textContent = `Export failed during download: ${e.message}`;
+    }
+}

static/js/dom.js

@@ -0,0 +1,203 @@
+// DOM + HTML-escaping primitives, and the modal dialogs built on them.
+//
+// Carved verbatim out of static/app.js (R3a). A LEAF module: imports nothing.
+//
+// This one is a GATHER, not a slice — the six lived in six different places in
+// app.js. They belong together because they are the bottom of the UI stack:
+// `esc` / `_escAttr` alone have ~48 call sites, and every later carve that
+// renders HTML will need them. Giving them a home NOW means those carves can
+// import them instead of inventing a host seam to reach back into app.js —
+// which is exactly the trap the plugin-loader carve had to work around before
+// the viz layer became a module.
+
+export function _isElementVisible(el) {
+    // Walk ancestors looking for display:none. Handles collapsed
+    // `.album-body` / `.artist-body` subtrees (hidden via CSS class
+    // rules). Using a DOM walk rather than `offsetParent` avoids the
+    // false-negative for `position:fixed` elements whose offsetParent
+    // is null even when they are perfectly visible.
+    if (!el) return false;
+    let node = el;
+    while (node && node !== document.body) {
+        if (getComputedStyle(node).display === 'none') return false;
+        node = node.parentElement;
+    }
+    return true;
+}
+
+// Focus trap: keep Tab / Shift+Tab cycling inside `modal` so focus
+// can't escape to the content underneath while the overlay is open.
+// Call this once after the modal is in the DOM and initial focus is set.
+export function _trapFocusInModal(modal) {
+    const FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+    modal.addEventListener('keydown', (e) => {
+        if (e.key !== 'Tab') return;
+        const els = Array.from(modal.querySelectorAll(FOCUSABLE)).filter(el => {
+            if (!_isElementVisible(el)) return false;
+            if (getComputedStyle(el).visibility === 'hidden') return false;
+            if (el.disabled) return false;
+            return true;
+        });
+        if (!els.length) return;
+        const first = els[0];
+        const last = els[els.length - 1];
+        if (e.shiftKey) {
+            if (document.activeElement === first) { e.preventDefault(); last.focus(); }
+        } else {
+            if (document.activeElement === last) { e.preventDefault(); first.focus(); }
+        }
+    });
+}
+
+// Styled async confirm dialog. Returns a Promise<boolean>. For destructive
+// prompts pass `danger: true` — confirm button turns red and Cancel gets
+// initial focus so an accidental Enter won't fire the action. `body` is
+// inserted as HTML so callers can use formatting; callers are responsible
+// for escaping any user-supplied content in it (use _escAttr).
+export function _confirmDialog({ title, body = '', confirmText = 'Confirm', cancelText = 'Cancel', danger = false } = {}) {
+    return new Promise((resolve) => {
+        const previouslyFocused = document.activeElement;
+        const modal = document.createElement('div');
+        modal.className = 'feedBack-modal fixed inset-0 z-[250] flex items-center justify-center bg-black/70 backdrop-blur-sm';
+        modal.setAttribute('role', 'alertdialog');
+        modal.setAttribute('aria-modal', 'true');
+        modal.setAttribute('aria-label', title || 'Confirm');
+        const confirmClass = danger
+            ? 'flex-1 bg-red-600 hover:bg-red-500 px-4 py-2 rounded-xl text-sm font-semibold text-white transition focus:outline-none focus:ring-2 focus:ring-red-400/60'
+            : 'flex-1 bg-accent hover:bg-accent-light px-4 py-2 rounded-xl text-sm font-semibold text-white transition focus:outline-none focus:ring-2 focus:ring-accent/60';
+        modal.innerHTML = `
+            <div class="bg-dark-700 border border-gray-700 rounded-2xl p-6 w-full max-w-sm mx-4 shadow-2xl">
+                <h3 class="text-lg font-bold text-white mb-3">${_escAttr(title || '')}</h3>
+                <div class="mb-5">${body}</div>
+                <div class="flex gap-3">
+                    <button type="button" data-confirm class="${confirmClass}">${_escAttr(confirmText)}</button>
+                    <button type="button" data-cancel class="px-4 py-2 bg-dark-600 hover:bg-dark-500 rounded-xl text-sm text-gray-300 transition focus:outline-none focus:ring-2 focus:ring-gray-500/40">${_escAttr(cancelText)}</button>
+                </div>
+            </div>`;
+        document.body.appendChild(modal);
+
+        function finish(result) {
+            modal.remove();
+            document.removeEventListener('keydown', onKey, true);
+            if (previouslyFocused && document.body.contains(previouslyFocused)) {
+                try { previouslyFocused.focus({ preventScroll: true }); } catch {}
+            }
+            resolve(result);
+        }
+        function onKey(e) {
+            if (e.key === 'Escape') { e.preventDefault(); e.stopImmediatePropagation(); finish(false); }
+            else if (e.key === 'Enter' && document.activeElement === modal.querySelector('[data-confirm]')) {
+                e.preventDefault(); finish(true);
+            }
+        }
+        modal.addEventListener('click', (e) => {
+            if (e.target === modal) finish(false);
+            else if (e.target.closest('[data-confirm]')) finish(true);
+            else if (e.target.closest('[data-cancel]')) finish(false);
+        });
+        document.addEventListener('keydown', onKey, true);
+        _trapFocusInModal(modal);
+        // Focus Cancel by default for destructive prompts so an accidental
+        // Enter / Space won't fire the dangerous action; otherwise focus
+        // the confirm button so Enter accepts.
+        const focusTarget = modal.querySelector(danger ? '[data-cancel]' : '[data-confirm]');
+        if (focusTarget) focusTarget.focus({ preventScroll: true });
+    });
+}
+
+export function esc(s) {
+    const d = document.createElement('div');
+    d.textContent = s;
+    return d.innerHTML;
+}
+
+// `esc()` escapes the HTML-content metacharacters (<, >, &) but not
+// quotes — fine for text-node interpolation but unsafe when the
+// result is used as an attribute value, where a literal `"` ends the
+// attribute early. Use `_escAttr` for any `attr="${...}"` site.
+export function _escAttr(s) {
+    return esc(s == null ? '' : String(s))
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+
+// In-app text prompt — replaces window.prompt(), which Electron does NOT
+// implement (it logs "prompt() is and will not be supported" and returns null),
+// so any prompt()-based flow is a silent no-op on desktop. Returns the entered
+// string, or null if cancelled (Esc / Cancel / backdrop). Styled to match the
+// edit modal; role=dialog so the global keyboard shortcuts ignore typing here.
+// Injection-safe: all caller text is set via textContent / value, never innerHTML.
+export function uiPrompt({ title = '', label = '', value = '', okLabel = 'Save', placeholder = '' } = {}) {
+    return new Promise((resolve) => {
+        const modal = document.createElement('div');
+        modal.className = 'feedBack-modal fixed inset-0 z-[200] flex items-center justify-center bg-black/70 backdrop-blur-sm';
+        modal.setAttribute('role', 'dialog');
+        modal.setAttribute('aria-modal', 'true');
+        if (title) modal.setAttribute('aria-label', title);
+        modal.innerHTML = `
+            <form class="bg-dark-700 border border-gray-700 rounded-2xl p-6 w-full max-w-sm mx-4 shadow-2xl">
+                <h3 class="text-lg font-bold text-white mb-4" data-ui-prompt-title hidden></h3>
+                <label class="text-xs text-gray-400 mb-1 block" data-ui-prompt-label hidden></label>
+                <input type="text" data-ui-prompt-input autocomplete="off"
+                    class="w-full bg-dark-600 border border-gray-700 rounded-lg px-3 py-2 text-sm text-gray-200 outline-none focus:border-accent/50">
+                <div class="flex gap-3 mt-5">
+                    <button type="submit"
+                        class="flex-1 bg-accent hover:bg-accent-light px-4 py-2 rounded-xl text-sm font-semibold text-white transition" data-ui-prompt-ok></button>
+                    <button type="button" data-ui-prompt-cancel
+                        class="px-4 py-2 bg-dark-600 hover:bg-dark-500 rounded-xl text-sm text-gray-300 transition">Cancel</button>
+                </div>
+            </form>`;
+        const titleEl = modal.querySelector('[data-ui-prompt-title]');
+        const labelEl = modal.querySelector('[data-ui-prompt-label]');
+        const input = modal.querySelector('[data-ui-prompt-input]');
+        const okEl = modal.querySelector('[data-ui-prompt-ok]');
+        if (title) { titleEl.textContent = title; titleEl.hidden = false; }
+        if (label) { labelEl.textContent = label; labelEl.hidden = false; }
+        okEl.textContent = okLabel;
+        input.value = value;
+        if (placeholder) input.placeholder = placeholder;
+
+        // Restore focus to wherever it was when we're done (matches the edit
+        // modal's behavior so keyboard users aren't dumped at the page top).
+        const previousActiveElement = document.activeElement;
+        const focusables = () => Array.from(
+            modal.querySelectorAll('input, button, [tabindex]:not([tabindex="-1"])'),
+        ).filter((el) => !el.disabled && el.offsetParent !== null);
+
+        let settled = false;
+        const close = (result) => {
+            if (settled) return;
+            settled = true;
+            document.removeEventListener('keydown', onKey, true);
+            modal.remove();
+            if (previousActiveElement && typeof previousActiveElement.focus === 'function') {
+                previousActiveElement.focus();
+            }
+            resolve(result);
+        };
+        const onKey = (e) => {
+            if (e.key === 'Escape') { e.preventDefault(); e.stopPropagation(); close(null); return; }
+            // Trap Tab inside the modal so focus can't wander to the page behind it.
+            if (e.key === 'Tab') {
+                const items = focusables();
+                if (!items.length) return;
+                const first = items[0];
+                const last = items[items.length - 1];
+                const active = document.activeElement;
+                if (e.shiftKey && (active === first || !modal.contains(active))) {
+                    e.preventDefault(); last.focus();
+                } else if (!e.shiftKey && (active === last || !modal.contains(active))) {
+                    e.preventDefault(); first.focus();
+                }
+            }
+        };
+        modal.querySelector('form').addEventListener('submit', (e) => { e.preventDefault(); close(input.value); });
+        modal.querySelector('[data-ui-prompt-cancel]').addEventListener('click', () => close(null));
+        // Backdrop (overlay itself, not the panel) cancels.
+        modal.addEventListener('mousedown', (e) => { if (e.target === modal) close(null); });
+        document.addEventListener('keydown', onKey, true);
+        document.body.appendChild(modal);
+        input.focus();
+        input.select();
+    });
+}

static/js/highway-colors.js

@@ -0,0 +1,601 @@
+// Highway string colours — user theming for the 2D + bundled 3D highways.
+//
+// Carved verbatim out of static/app.js (R3a). A LEAF module: imports nothing.
+//
+// Slot→hex colours (per named string slot, so a 6-string map survives a 4-string
+// bass and a 7-string's Low B), named themes in localStorage, a copy/paste share
+// code, and the Settings-screen picker UI. The highways colour by raw string
+// INDEX, so a translation table maps named slots → per-index colours for the
+// current arrangement, recomputed whenever a song loads.
+//
+// Exports exactly two entry points; the other 43 symbols (the HWC_* tables, the
+// theme store, the picker handlers, the window.feedBack facade) are used nowhere
+// else in core and stay private. The Settings buttons are wired by
+// addEventListener inside hwcInitSettingsUI — there are no inline on*= handlers
+// here, so nothing needs re-exposing on window.
+//
+// It does import uiPrompt from ./dom.js (the "name this theme" prompt) — which is
+// precisely why dom.js was carved out first: without it this module would have
+// needed a host seam back into app.js.
+import { uiPrompt } from './dom.js';
+
+// Colors are assigned per NAMED string (Low E, A, D, G, B, High E, plus the
+// extended low strings of 7/8-string guitars), so a string keeps its color
+// when the string count changes (e.g. Low E stays the same from a 6-string
+// guitar to a 4-string bass, and on a 7-string the extra Low B takes the
+// 7-string slot rather than bumping every color over). The highways color by
+// raw string INDEX, so a small translation table maps named slots → per-index
+// colors for the current arrangement; this is recomputed whenever a song loads
+// (its string count / bass-vs-guitar may differ). Applies to BOTH the 2D and
+// bundled 3D highway; stored client-side; shared via a copy/paste code.
+const HWC_KEY_ACTIVE = 'highwayStringColors';    // JSON slot→hex map (active)
+const HWC_KEY_THEMES = 'highwayColorThemes';     // { "<name>": {slot:hex} }
+const HWC_KEY_NAME = 'highwayColorActiveName';   // selected saved theme name, or ''
+const HWC_HEX_RE = /^#[0-9a-fA-F]{6}$/;
+
+// Named color slots, in display order (high → low, then extended low strings).
+const HWC_SLOTS = [
+    { key: 'highE', label: 'High E', sub: '1st' },
+    { key: 'B', label: 'B', sub: '2nd' },
+    { key: 'G', label: 'G', sub: '3rd' },
+    { key: 'D', label: 'D', sub: '4th' },
+    { key: 'A', label: 'A', sub: '5th' },
+    { key: 'lowE', label: 'Low E', sub: '6th / lowest' },
+    { key: 'low7', label: 'Low B', sub: '7-string' },
+    { key: 'low8', label: 'Low F#', sub: '8-string' },
+];
+const HWC_SLOT_KEYS = HWC_SLOTS.map((s) => s.key);
+// Hardcoded fallback (matches the highway defaults) for before the 2D highway
+// is queryable.
+const HWC_DEFAULT_FALLBACK = { lowE: '#cc0000', A: '#cca800', D: '#0066cc', G: '#cc6600', B: '#00cc66', highE: '#9900cc', low7: '#cc00aa', low8: '#00cccc' };
+
+// One-click string-color presets. Each is a full named-slot → hex map (every
+// slot, so 7/8-string charts get a sensible color too) keyed by the same slot
+// names as HWC_SLOTS, so "Low E" always lands on the lowE slot regardless of
+// string count. Hues are chosen for the dark scene (~#080810): each color is
+// bright enough to read on black and distinct from its neighbours.
+//   - warmcool: an ordered low→high spectrum (warm reds at the bass end →
+//     cool blues/violet at the treble end) so pitch reads as color temperature.
+//   - vivid: punchier, higher-saturation take on the classic mapping for a
+//     stage-bright look.
+//   - colorblind: the Okabe–Ito accessible qualitative palette (vermillion,
+//     orange, yellow, bluish-green, sky-blue, blue, reddish-purple), the most
+//     distinguishable option for deuteranopia/protanopia.
+//   - colorblind_deuteranope: a deuteranope-tuned variant of the Okabe–Ito set
+//     above, contributed by a deuteranopic player who still found that set hard
+//     to separate. Retunes the six main strings (red / yellow-green / blue /
+//     orange / teal / deep-purple) and keeps its 7/8-string colors unchanged.
+//   - neon: electric, max-saturation hues whose LIGHTNESS deliberately zig-zags
+//     between neighbours (bright→bright→brightest→dark blue→bright green→dark
+//     violet) so adjacent strings separate harder than vivid — a stage/stream
+//     "pop" set, not a vivid duplicate.
+//   - accessible: a CVD-safe set ORDERED by ascending lightness low→high (deep
+//     blue → vermilion → azure → orange → yellow → cream). Unlike the unordered
+//     Okabe–Ito 'colorblind' set, the value ramp teaches pitch low→high AND
+//     survives grayscale/colorblindness; no red/green pair carries meaning.
+//   - ember: a warm, lower-intensity family for long sessions, luminance-stepped
+//     from rust/ember at the bass through warm gold to cream at the treble. The
+//     bass embers stay light enough to clear the near-black scene.
+//   - tapedeck: a vintage-print, slightly desaturated ochre-tinted family
+//     (rust-red → mustard → avocado → teal → faded denim → dusty plum). Muted
+//     hues collapse, so neighbour LIGHTNESS deliberately zig-zags to keep the
+//     dusty mid-strings (avocado/teal/denim) distinct on the dark board.
+//   - crtgreen / crtamber: monochrome CRT-phosphor families (green / amber)
+//     stepped by STRICT ASCENDING LIGHTNESS low→high. Mono sets collapse on hue,
+//     so lightness alone carries the ordering. Verified to stay legible even on
+//     the matching phosphor scene board (green-on-green / amber-on-amber).
+//   - pitchramp: a smooth low→high hue sweep (violet → blue → teal → green →
+//     yellow → warm-white) with rising lightness — memorable + teaches order.
+//   - sunrise: a soft dawn gradient (plum → rose → coral → amber → gold → cream),
+//     warm and lower-intensity, lightness-stepped low→high.
+const HWC_PRESETS = [
+    {
+        id: 'warmcool', label: 'Warm → Cool',
+        colors: { lowE: '#ff3b30', A: '#ff7a18', D: '#ffc400', G: '#36c46a', B: '#2196f3', highE: '#9b5cff', low7: '#ff2d78', low8: '#00c2c7' },
+    },
+    {
+        id: 'vivid', label: 'Vivid',
+        colors: { lowE: '#ff2222', A: '#ffd000', D: '#1e8bff', G: '#ff7a00', B: '#16d65a', highE: '#b24bff', low7: '#ff3cc0', low8: '#15d8d8' },
+    },
+    {
+        id: 'colorblind', label: 'Colorblind-friendly',
+        colors: { lowE: '#d55e00', A: '#e69f00', D: '#f0e442', G: '#009e73', B: '#56b4e9', highE: '#cc79a7', low7: '#0072b2', low8: '#999999' },
+    },
+    {
+        id: 'colorblind_deuteranope', label: 'Colorblind (deuteranope)',
+        colors: { lowE: '#aa1414', A: '#88de00', D: '#1889e3', G: '#c6601c', B: '#00f5b2', highE: '#4d2173', low7: '#0072b2', low8: '#999999' },
+    },
+    {
+        id: 'neon', label: 'Neon',
+        colors: { lowE: '#ff1f4e', A: '#ff9d00', D: '#e9ff00', G: '#1844ff', B: '#00ff84', highE: '#d000ff', low7: '#ff00aa', low8: '#00f0ff' },
+    },
+    {
+        id: 'accessible', label: 'Accessible (ordered)',
+        colors: { lowE: '#2453c0', A: '#c44a00', D: '#3f93cf', G: '#ec9a1e', B: '#f2d43c', highE: '#f5eecb', low7: '#173f96', low8: '#0f2c6b' },
+    },
+    {
+        id: 'ember', label: 'Warm Ember',
+        colors: { lowE: '#c0392b', A: '#e0552a', D: '#ef7d2e', G: '#f6a13a', B: '#f4c95d', highE: '#f7e3a8', low7: '#9e2f23', low8: '#7d2418' },
+    },
+    {
+        id: 'tapedeck', label: 'Tape Deck',
+        colors: { lowE: '#b04632', A: '#d8ad42', D: '#5f7a34', G: '#54b3a6', B: '#5e83ad', highE: '#b98abb', low7: '#8f3526', low8: '#6f2a1e' },
+    },
+    {
+        id: 'crtgreen', label: 'CRT Green',
+        colors: { lowE: '#0a5a23', A: '#108a30', D: '#1fb53f', G: '#3ad94f', B: '#74f06a', highE: '#c7ffb0', low7: '#08491c', low8: '#063514' },
+    },
+    {
+        id: 'crtamber', label: 'CRT Amber',
+        colors: { lowE: '#7a3a02', A: '#a85f06', D: '#cf8410', G: '#e8a82a', B: '#f4cf5e', highE: '#ffeeb8', low7: '#5f2d01', low8: '#471f00' },
+    },
+    {
+        id: 'pitchramp', label: 'Pitch Ramp',
+        colors: { lowE: '#7a2390', A: '#2f5ad8', D: '#1f9bc4', G: '#2fb84a', B: '#cfd22a', highE: '#f3e0c0', low7: '#5e1a78', low8: '#440f5e' },
+    },
+    {
+        id: 'sunrise', label: 'Sunrise',
+        colors: { lowE: '#8a3a6e', A: '#bf4a5e', D: '#e0664f', G: '#f29a55', B: '#f7c873', highE: '#fce8b8', low7: '#6e2c5c', low8: '#54214a' },
+    },
+];
+
+// Translation table: chart string index → named slot, for a given string count
+// and bass/guitar family. Mirrors the 3D highway's _baseOpenStringMidis: bass
+// shares the low strings (E A D G), 7/8-string guitars prepend lower strings,
+// and sub-6 guitars truncate from the high end. Index 0 is always the lowest.
+function _hwcSlotKeysForChart(sc, isBass) {
+    sc = Math.max(1, Math.min(8, (sc | 0) || 6));
+    if (isBass) {
+        if (sc <= 4) return ['lowE', 'A', 'D', 'G'].slice(0, sc);
+        if (sc === 5) return ['low7', 'lowE', 'A', 'D', 'G'];
+        return ['low8', 'low7', 'lowE', 'A', 'D', 'G'].slice(0, sc);
+    }
+    if (sc <= 6) return ['lowE', 'A', 'D', 'G', 'B', 'highE'].slice(0, sc);
+    if (sc === 7) return ['low7', 'lowE', 'A', 'D', 'G', 'B', 'highE'];
+    return ['low8', 'low7', 'lowE', 'A', 'D', 'G', 'B', 'highE'];
+}
+
+// Current arrangement shape (string count + bass-vs-guitar) from the 2D highway.
+function _hwcChartShape() {
+    let sc = 6, arr = '';
+    try { sc = window.highway?.getStringCount?.() || 6; } catch (_) {}
+    try { arr = window.highway?.getSongInfo?.()?.arrangement || window.feedBack?.currentSong?.arrangement || ''; } catch (_) {}
+    return { sc: Math.max(1, Math.min(8, sc)), isBass: /bass/i.test(String(arr)) };
+}
+
+// Normalize an arbitrary value to a slot→hex map of validated lowercase colors
+// (absent / invalid slots are omitted).
+function _hwcNormalize(slotMap) {
+    const out = {};
+    if (slotMap && typeof slotMap === 'object' && !Array.isArray(slotMap)) {
+        for (const k of HWC_SLOT_KEYS) {
+            const v = (typeof slotMap[k] === 'string') ? slotMap[k].trim().toLowerCase() : '';
+            if (HWC_HEX_RE.test(v)) out[k] = v;
+        }
+    }
+    return out;
+}
+
+// Canonical default color per named slot (the classic highway mapping).
+// Fixed, not read back from the highway (which may already be name-remapped for
+// a 7/8-string chart), so the pickers always preview the true per-name default.
+function getHighwayDefaultSlotColors() {
+    return { ...HWC_DEFAULT_FALLBACK };
+}
+
+// Active (user-customized) slot→hex map from storage ({} when none set).
+function getHighwayStringColors() {
+    try {
+        const raw = localStorage.getItem(HWC_KEY_ACTIVE);
+        if (raw) return _hwcNormalize(JSON.parse(raw));
+    } catch (_) { /* corrupt / blocked */ }
+    return {};
+}
+
+// Defaults overlaid with the user's custom slots (custom wins). Always a full
+// 8-slot map, so name-mapping has a color for every string of any arrangement.
+function _hwcMergedSlotColors() {
+    return { ...getHighwayDefaultSlotColors(), ...getHighwayStringColors() };
+}
+
+// True when the slot→index mapping is the identity (index 0 = lowest = Low E):
+// guitar ≤6 strings and 4-string bass. For these the name mapping equals the
+// stock index order, so we leave the highways on their hand-tuned defaults
+// (byte-identical) unless the user set custom colors. Extended-range charts —
+// 7/8-string guitar and 5/6-string bass — prepend lower strings (Low B/F#),
+// shifting Low E up an index, so their defaults must be name-remapped too.
+function _hwcMappingIsIdentity(sc, isBass) {
+    return isBass ? sc <= 4 : sc <= 6;
+}
+
+// Translate a full slot map into the index-keyed array the highways consume.
+function _hwcEffectiveIndexColors(slotMap, sc, isBass) {
+    const keys = _hwcSlotKeysForChart(sc, isBass);
+    return keys.map((k) => slotMap[k] || null);
+}
+
+// Persist the user's custom slot map (or clear it), then apply. Only slots that
+// actually DIFFER from the default are stored — so reverting every picker to its
+// stock color persists as empty and the identity/stock path is restored (rather
+// than pinning the highways on an all-default "custom" theme).
+function applyHighwayStringColors(slotMap, opts) {
+    const persist = !opts || opts.persist !== false;
+    const colors = _hwcNormalize(slotMap);
+    const defaults = getHighwayDefaultSlotColors();
+    const overrides = {};
+    for (const k of Object.keys(colors)) {
+        if (colors[k] !== defaults[k]) overrides[k] = colors[k];
+    }
+    if (persist) {
+        try {
+            if (Object.keys(overrides).length) localStorage.setItem(HWC_KEY_ACTIVE, JSON.stringify(overrides));
+            else localStorage.removeItem(HWC_KEY_ACTIVE);
+        } catch (_) {}
+    }
+    reapplyHighwayStringColors();
+}
+
+// Apply a named one-click string-color preset (see HWC_PRESETS) to all strings.
+// Persists + applies to both highways (via applyHighwayStringColors), then —
+// when the Settings UI is mounted — refreshes the per-string pickers so their
+// swatches show the preset's colors. Unknown id is a no-op.
+function applyHighwayStringPreset(id) {
+    const preset = HWC_PRESETS.find((p) => p.id === id);
+    if (!preset) return false;
+    applyHighwayStringColors(preset.colors);
+    try { if (typeof hwcRenderPickers === 'function') hwcRenderPickers(); } catch (_) {}
+    return true;
+}
+
+// Apply colors by NAMED string to both highways for the current arrangement.
+// Colors follow the string name regardless of count: Low E stays Low E's color
+// on a 6-, 7-, or 8-string. Defaults map identically to the stock order for
+// 6-string/bass (so those stay byte-identical); 7/8-string remaps the defaults
+// too so Low E keeps its color. The String Colors UI replaces the 3D highway's
+// old palette picker, so core always drives the 3D string colors here.
+function reapplyHighwayStringColors() {
+    const { sc, isBass } = _hwcChartShape();
+    const custom = getHighwayStringColors();
+    const hasCustom = Object.keys(custom).length > 0;
+
+    if (!hasCustom && _hwcMappingIsIdentity(sc, isBass)) {
+        // Pure stock defaults in natural order — leave the hand-tuned highway
+        // defaults intact, and make sure the 3D is on its plain default palette
+        // (clears any stale 'custom' / leftover palette selection).
+        try { window.highway?.setStringColors?.(null); } catch (_) {}
+        try {
+            if (localStorage.getItem('h3d_bg_palette') !== 'default') window.h3dBgSetPalette?.('default');
+        } catch (_) {}
+        try { window.feedBack?.emit?.('highway:stringColors', {}); } catch (_) {}
+        return;
+    }
+
+    const eff = _hwcEffectiveIndexColors(_hwcMergedSlotColors(), sc, isBass);
+    try { window.highway?.setStringColors?.(eff); } catch (_) {}
+    try { window.h3dBgSetStringColors?.(eff); } catch (_) {}
+    try { window.feedBack?.emit?.('highway:stringColors', custom); } catch (_) {}
+}
+
+function _hwcReadThemes() {
+    // Null-prototype store: theme names come from user input / share codes, so
+    // names like `constructor`/`toString`/`__proto__` must not collide with
+    // inherited Object properties or mutate the prototype.
+    try {
+        const parsed = JSON.parse(localStorage.getItem(HWC_KEY_THEMES) || '{}');
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return Object.create(null);
+        const out = Object.create(null);
+        for (const [name, colors] of Object.entries(parsed)) out[name] = _hwcNormalize(colors);
+        return out;
+    } catch (_) { return Object.create(null); }
+}
+function _hwcWriteThemes(o) { try { localStorage.setItem(HWC_KEY_THEMES, JSON.stringify(o)); } catch (_) {} }
+function listHighwayColorThemes() { return Object.keys(_hwcReadThemes()); }
+function getActiveHighwayColorThemeName() { try { return localStorage.getItem(HWC_KEY_NAME) || ''; } catch (_) { return ''; } }
+
+function saveHighwayColorTheme(name, slotMap) {
+    name = String(name || '').trim();
+    if (!name) return false;
+    const o = _hwcReadThemes();
+    o[name] = _hwcNormalize(slotMap);
+    _hwcWriteThemes(o);
+    try { localStorage.setItem(HWC_KEY_NAME, name); } catch (_) {}
+    return true;
+}
+function deleteHighwayColorTheme(name) {
+    const o = _hwcReadThemes();
+    if (Object.prototype.hasOwnProperty.call(o, name)) { delete o[name]; _hwcWriteThemes(o); }
+    if (getActiveHighwayColorThemeName() === name) { try { localStorage.removeItem(HWC_KEY_NAME); } catch (_) {} }
+}
+// Select a saved theme by name, or pass '' to revert to defaults.
+function selectHighwayColorTheme(name) {
+    if (!name) {
+        try { localStorage.removeItem(HWC_KEY_NAME); } catch (_) {}
+        applyHighwayStringColors(null);
+        return;
+    }
+    const o = _hwcReadThemes();
+    if (!Object.prototype.hasOwnProperty.call(o, name)) return;
+    try { localStorage.setItem(HWC_KEY_NAME, name); } catch (_) {}
+    applyHighwayStringColors(o[name]);
+}
+
+// Compact, paste-friendly share code: "SLOPHWY2." + base64url(JSON{n,c}) where
+// c is the named slot→hex map.
+function encodeHighwayColorShare(name, slotMap) {
+    const payload = { n: String(name || '').slice(0, 60), c: _hwcNormalize(slotMap) };
+    const json = JSON.stringify(payload);
+    let b64;
+    try { b64 = btoa(unescape(encodeURIComponent(json))); } catch (_) { b64 = btoa(json); }
+    return 'SLOPHWY2.' + b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function decodeHighwayColorShare(code) {
+    if (typeof code !== 'string') return null;
+    let s = code.trim();
+    // Require the exact versioned prefix. Anything else (a future/legacy
+    // SLOPHWY*, or unprefixed text) is rejected so the version boundary is real.
+    const PREFIX = 'SLOPHWY2.';
+    if (s.slice(0, PREFIX.length).toUpperCase() !== PREFIX) return null;
+    s = s.slice(PREFIX.length);
+    s = s.replace(/-/g, '+').replace(/_/g, '/');
+    while (s.length % 4) s += '=';
+    let json;
+    try { json = decodeURIComponent(escape(atob(s))); } catch (_) { try { json = atob(s); } catch (_) { return null; } }
+    let obj;
+    try { obj = JSON.parse(json); } catch (_) { return null; }
+    if (!obj || typeof obj.c !== 'object' || Array.isArray(obj.c)) return null;
+    return { name: String(obj.n || '').slice(0, 60), colors: _hwcNormalize(obj.c) };
+}
+// Import a share code: store it as a (uniquely named) saved theme and apply.
+function importHighwayColorShare(code) {
+    const parsed = decodeHighwayColorShare(code);
+    if (!parsed) return null;
+    let name = parsed.name || 'Imported';
+    const existing = _hwcReadThemes();
+    if (Object.prototype.hasOwnProperty.call(existing, name)) {
+        let i = 2;
+        while (Object.prototype.hasOwnProperty.call(existing, name + ' ' + i)) i++;
+        name = name + ' ' + i;
+    }
+    saveHighwayColorTheme(name, parsed.colors);
+    applyHighwayStringColors(parsed.colors);
+    return { name, colors: parsed.colors };
+}
+
+// Startup: apply persisted colors to the 2D highway immediately and re-apply on
+// every song load (string count / bass-vs-guitar can change the slot→index
+// mapping) and whenever a viz renderer (re)initializes (the 3D loads async +
+// rebuilds per song, so a one-shot apply could land before it exists).
+let _hwcWired = false;
+export function initHighwayColors() {
+    reapplyHighwayStringColors();
+    if (!_hwcWired && window.feedBack && typeof window.feedBack.on === 'function') {
+        _hwcWired = true;
+        window.feedBack.on('viz:renderer:ready', reapplyHighwayStringColors);
+        window.feedBack.on('song:loaded', reapplyHighwayStringColors);
+        window.feedBack.on('song:ready', reapplyHighwayStringColors);
+    }
+    _hwcInstallFacade();
+}
+
+// ── Public plugin API: window.feedBack.highwayColors ─────────────────────
+// A stable, documented facade over the (otherwise private) string-color
+// manager so plugins can read / react to / set the user's per-string colors
+// without reaching into internals. This is a synchronous data-plane API, not a
+// capability domain — consistent with the constitution keeping highway/viz
+// surfaces off the capability graph until a dedicated render-facade slice
+// lands. Colors are keyed by NAMED string slot (see `slots`); use
+// `keysForChart`/`toEffective` to map names → per-string-index for a given
+// arrangement. See docs/plugin-capability-inventory.md.
+const _hwcChangeWrappers = new WeakMap();
+function _hwcInstallFacade() {
+    if (!window.feedBack || window.feedBack.highwayColors) return;
+    const api = {
+        version: 1,
+        // Ordered named slots: [{ key, label, sub }]. `key` is the stable id.
+        slots: HWC_SLOTS.map((s) => ({ key: s.key, label: s.label, sub: s.sub })),
+        // User-set overrides only (named slot → hex); empty object = defaults.
+        get() { return getHighwayStringColors(); },
+        // Canonical default color per named slot.
+        getDefaults() { return getHighwayDefaultSlotColors(); },
+        // Defaults overlaid with overrides — the colors in effect, by name.
+        getResolved() { return _hwcMergedSlotColors(); },
+        // Which named slot each chart string index maps to, for an arrangement
+        // (index 0 = lowest string). e.g. (7,false) → ['low7','lowE','A',...].
+        keysForChart(stringCount, isBass) { return _hwcSlotKeysForChart(stringCount, !!isBass); },
+        // Per-string-INDEX hex array (resolved colors) for an arrangement.
+        // Omit args to use the currently-loaded chart's shape.
+        toEffective(stringCount, isBass) {
+            const shape = (typeof stringCount === 'number')
+                ? { sc: stringCount, isBass: !!isBass }
+                : _hwcChartShape();
+            return _hwcEffectiveIndexColors(_hwcMergedSlotColors(), shape.sc, shape.isBass);
+        },
+        // The per-index colors actually applied to the live 2D highway now.
+        getCurrent() {
+            try { return (window.highway && window.highway.getStringColors) ? window.highway.getStringColors() : []; }
+            catch (_) { return []; }
+        },
+        // Set colors programmatically (persists + applies to both highways).
+        // Pass a named slot map, or null/{} to revert to defaults.
+        apply(slotMap) { return applyHighwayStringColors(slotMap); },
+        // One-click presets: [{ id, label, colors }] (full named-slot maps).
+        presets: HWC_PRESETS.map((p) => ({ id: p.id, label: p.label, colors: { ...p.colors } })),
+        // Apply a preset by id (persists + applies to both highways).
+        applyPreset(id) { return applyHighwayStringPreset(id); },
+        // Share-code interop (the "SLOPHWY2." copy/paste format).
+        encodeShare(name, slotMap) { return encodeHighwayColorShare(name, slotMap); },
+        decodeShare(code) { return decodeHighwayColorShare(code); },
+        // Subscribe to color changes; handler receives the resolved slot map.
+        // Returns an unsubscribe fn that removes exactly THIS subscription;
+        // offChange(fn) removes every subscription registered with that fn.
+        // (Each fn maps to a Set of wrappers so repeated mount/init paths that
+        // subscribe the same handler don't clobber each other or leak.)
+        onChange(fn) {
+            if (typeof fn !== 'function' || !window.feedBack) return () => {};
+            const wrapper = () => {
+                try { fn(api.getResolved()); } catch (e) { console.error('[highwayColors] onChange handler threw', e); }
+            };
+            let set = _hwcChangeWrappers.get(fn);
+            if (!set) { set = new Set(); _hwcChangeWrappers.set(fn, set); }
+            set.add(wrapper);
+            window.feedBack.on('highway:stringColors', wrapper);
+            return () => {
+                if (window.feedBack) window.feedBack.off('highway:stringColors', wrapper);
+                const s = _hwcChangeWrappers.get(fn);
+                if (s) { s.delete(wrapper); if (!s.size) _hwcChangeWrappers.delete(fn); }
+            };
+        },
+        offChange(fn) {
+            const set = _hwcChangeWrappers.get(fn);
+            if (set && window.feedBack) {
+                for (const wrapper of set) window.feedBack.off('highway:stringColors', wrapper);
+                _hwcChangeWrappers.delete(fn);
+            }
+        },
+    };
+    window.feedBack.highwayColors = api;
+}
+
+// ── Highway String Colors — Settings UI wiring ───────────────────────────
+// Pickers are per NAMED string (see HWC_SLOTS). Assigning "Low E" a color
+// keeps Low E that color regardless of string count — the translation table
+// (_hwcSlotKeysForChart) handles the index remapping per arrangement.
+
+function _hwcStatus(msg) {
+    const el = document.getElementById('hwc-status');
+    if (!el) return;
+    el.textContent = msg || '';
+    if (msg) {
+        clearTimeout(_hwcStatus._t);
+        _hwcStatus._t = setTimeout(() => { if (el.textContent === msg) el.textContent = ''; }, 2500);
+    }
+}
+
+// Render one color input per named slot, seeded from active colors (falling
+// back to the highway defaults for that slot).
+function hwcRenderPickers() {
+    const host = document.getElementById('hwc-pickers');
+    if (!host) return;
+    const defaults = getHighwayDefaultSlotColors();
+    const active = getHighwayStringColors();
+    host.innerHTML = '';
+    for (const slot of HWC_SLOTS) {
+        const val = active[slot.key] || defaults[slot.key] || '#888888';
+        const wrap = document.createElement('label');
+        wrap.className = 'flex items-center gap-2 text-xs text-gray-400';
+        const input = document.createElement('input');
+        input.type = 'color';
+        input.id = 'hwc-color-' + slot.key;
+        input.dataset.slot = slot.key;
+        input.value = val;
+        input.style.width = '2.5rem';
+        input.style.height = '1.75rem';
+        input.style.padding = '2px';
+        input.style.cursor = 'pointer';
+        input.className = 'rounded border border-gray-800 bg-dark-700';
+        input.addEventListener('input', () => hwcOnColorInput());
+        wrap.appendChild(input);
+        const span = document.createElement('span');
+        span.textContent = slot.label;
+        wrap.appendChild(span);
+        const sub = document.createElement('span');
+        sub.className = 'text-gray-600';
+        sub.textContent = slot.sub;
+        wrap.appendChild(sub);
+        host.appendChild(wrap);
+    }
+}
+
+function hwcReadPickers() {
+    const out = {};
+    for (const slot of HWC_SLOTS) {
+        const el = document.getElementById('hwc-color-' + slot.key);
+        if (el) out[slot.key] = el.value;
+    }
+    return out;
+}
+
+// Live apply on any picker change. Leaves the saved-theme select alone so a
+// tweaked-but-unsaved state is allowed; "Save as…" captures it.
+function hwcOnColorInput() {
+    applyHighwayStringColors(hwcReadPickers());
+}
+
+function hwcPopulateThemeSelect() {
+    const sel = document.getElementById('hwc-theme-select');
+    if (!sel) return;
+    const names = listHighwayColorThemes().sort((a, b) => a.localeCompare(b));
+    const current = getActiveHighwayColorThemeName();
+    sel.innerHTML = '';
+    const def = document.createElement('option');
+    def.value = '';
+    def.textContent = 'Default colors';
+    sel.appendChild(def);
+    for (const n of names) {
+        const opt = document.createElement('option');
+        opt.value = n;
+        opt.textContent = n;
+        sel.appendChild(opt);
+    }
+    sel.value = (current && names.includes(current)) ? current : '';
+}
+
+function hwcOnSelectTheme(name) {
+    selectHighwayColorTheme(name);
+    hwcRenderPickers();
+}
+
+async function hwcSaveTheme() {
+    const name = await uiPrompt({ title: 'Save Highway Colors', label: 'Theme name', value: getActiveHighwayColorThemeName() || 'My Colors', okLabel: 'Save' });
+    if (!name) return;
+    saveHighwayColorTheme(name, hwcReadPickers());
+    hwcPopulateThemeSelect();
+    _hwcStatus('Saved “' + name + '”');
+}
+
+function hwcDeleteTheme() {
+    const name = getActiveHighwayColorThemeName();
+    if (!name) { _hwcStatus('No saved theme selected'); return; }
+    deleteHighwayColorTheme(name);
+    applyHighwayStringColors(null);
+    hwcPopulateThemeSelect();
+    hwcRenderPickers();
+    _hwcStatus('Deleted “' + name + '”');
+}
+
+function hwcReset() {
+    try { localStorage.removeItem(HWC_KEY_NAME); } catch (_) {}
+    applyHighwayStringColors(null);
+    hwcPopulateThemeSelect();
+    hwcRenderPickers();
+    _hwcStatus('Reset to defaults');
+}
+
+async function hwcCopyShare() {
+    const name = getActiveHighwayColorThemeName() || 'Highway Colors';
+    const code = encodeHighwayColorShare(name, hwcReadPickers());
+    let copied = false;
+    try { await navigator.clipboard.writeText(code); copied = true; } catch (_) {}
+    if (!copied) {
+        // Fallback: drop the code into the import field so it can be copied manually.
+        const inp = document.getElementById('hwc-import-code');
+        if (inp) { inp.value = code; inp.select(); }
+    }
+    _hwcStatus(copied ? 'Share code copied' : 'Copy failed — code shown below');
+}
+
+function hwcImport() {
+    const inp = document.getElementById('hwc-import-code');
+    const code = inp ? inp.value : '';
+    const res = importHighwayColorShare(code);
+    if (!res) { _hwcStatus('Invalid share code'); return; }
+    if (inp) inp.value = '';
+    hwcPopulateThemeSelect();
+    hwcRenderPickers();
+    _hwcStatus('Imported “' + res.name + '”');
+}
+
+export function hwcInitSettingsUI() {
+    hwcPopulateThemeSelect();
+    hwcRenderPickers();
+}

static/js/host.js

@@ -0,0 +1,99 @@
+// The host seam — how a carved-out module calls back into app.js.
+//
+// WHY THIS EXISTS. What is left in app.js is not a tree, it is a cycle: seeding a
+// dependency closure from count-in, from loops, from section-practice, or from the
+// JUCE seek shim all return the SAME 178-function set, and setLoop() and
+// practiceSection() call each other directly. So a module carved out of that
+// component will always need to call back into app.js — and it cannot `import`
+// app.js to do it, because app.js imports the module, and that closes a cycle the
+// import-x/no-cycle gate (rightly) rejects.
+//
+// So app.js hands its functions DOWN, once, at boot: `configureHost({ playSong, … })`.
+//
+// ─── THE FAILURE MODE THIS IS BUILT TO PREVENT ───────────────────────────────
+//
+// The obvious way to write this is a plain object with no-op defaults. That is a
+// TRAP, and we walked into it once already: the plugin loader's host seam defaulted
+// `populateVizPicker` to `() => {}`, which means that if the wiring call in app.js
+// is ever dropped, renamed, or drifts, the loader keeps running, the viz picker
+// silently stops refreshing, and NOTHING — no test, no boot check, no bot — says a
+// word. A feature just quietly stops existing.
+//
+// Two layers stop that here, and the second is the one that actually closes it:
+//
+//   1. RUNTIME — reading an unwired hook THROWS. There are no defaults and no
+//      stubs. `host.playSong` either is the real function or it is a loud error.
+//      An unwired hook cannot degrade into a no-op, because there is nothing for
+//      it to degrade INTO.
+//
+//   2. STATIC — tests/js/host_contract.test.js asserts that the set of hooks the
+//      modules USE is exactly the set app.js WIRES. This is the important one:
+//      layer 1 only fires if the broken path actually executes, and the whole
+//      danger of this seam is paths that don't run in a smoke test. The static
+//      check catches a drifted or misspelled hook in CI, on a path nobody ran.
+//
+// Consequence for anyone adding a hook: add it to the configureHost({…}) call in
+// app.js *and* use it as `host.<name>`. The contract test fails on either alone —
+// deliberately. A hook wired but never used is dead weight; a hook used but never
+// wired is a bug that would otherwise hide.
+
+const _hooks = Object.create(null);
+let _configured = false;
+
+/**
+ * Called ONCE by app.js at boot, before any carved module runs. Every value must
+ * be a function — a hook that is accidentally `undefined` (a typo, a renamed
+ * export, a dropped line) fails HERE, at startup, rather than silently much later.
+ */
+export function configureHost(hooks) {
+    if (_configured) {
+        throw new Error('[host] configureHost() called twice — it must be wired exactly once, at boot.');
+    }
+    const bad = Object.entries(hooks || {})
+        .filter(([, v]) => typeof v !== 'function')
+        .map(([k]) => k);
+    if (bad.length) {
+        throw new Error(
+            `[host] these hooks are not functions: ${bad.join(', ')}. `
+            + 'A hook is usually undefined because it was renamed or its line was dropped.',
+        );
+    }
+    Object.assign(_hooks, hooks);
+    _configured = true;
+}
+
+/**
+ * The seam itself. Reading a hook that was never wired THROWS — it never returns
+ * undefined and never returns a silent no-op. See the note at the top: a no-op
+ * default is precisely the bug this module exists to make impossible.
+ */
+export const host = new Proxy(Object.create(null), {
+    get(_target, name) {
+        if (typeof name === 'symbol') return undefined;   // let JS probe it freely
+        if (!_configured) {
+            throw new Error(
+                `[host] host.${name} was read before configureHost() ran. `
+                + 'app.js must call configureHost() at boot, before any carved module executes.',
+            );
+        }
+        const fn = _hooks[name];
+        if (typeof fn !== 'function') {
+            throw new Error(
+                `[host] host.${name} is not wired. Add it to the configureHost({ … }) `
+                + 'call in app.js. (tests/js/host_contract.test.js should have caught this in CI.)',
+            );
+        }
+        return fn;
+    },
+    // Keep the object honest for anything that introspects it.
+    has(_target, name) { return name in _hooks; },
+    ownKeys() { return Object.keys(_hooks); },
+    getOwnPropertyDescriptor(_target, name) {
+        return name in _hooks
+            ? { value: _hooks[name], enumerable: true, configurable: true, writable: false }
+            : undefined;
+    },
+    set(_target, name) {
+        throw new Error(`[host] host.${String(name)} is read-only — hooks are wired only via configureHost().`);
+    },
+});

static/js/loops.js

@@ -0,0 +1,261 @@
+// The A–B loop — set / clear / persist, and the saved-loops list.
+//
+// The second slice out of app.js's strongly-connected core, and it owns the loop
+// state: loopA, loopB, _loopMutationGen. Nothing outside this module writes them
+// (restartCurrentSong() looked like it did, but it declares its own local shadows).
+//
+// DIRECTION MATTERS HERE. loops and section-practice are mutually dependent — the
+// SCC in miniature. clearLoop() has to drop section-practice's selection, and
+// practiceSection() has to call setLoop(). Both directions cannot be imports or the
+// no-cycle gate (rightly) rejects it. So the edge is oriented:
+//
+//     section-practice  ->  reaches loops through the HOST SEAM (host.setLoop, …)
+//     loops             ->  imports section-practice DIRECTLY
+//
+// section-practice is the higher-level feature — it is a consumer of loops, not the
+// other way round — so it is the one that gets the indirection. app.js wires this
+// module's exports into the seam for it.
+//
+// See ./host.js: reading an unwired hook THROWS, and tests/js/host_contract.test.js
+// fails CI if the hooks used here and the hooks app.js wires ever drift apart.
+import { esc, uiPrompt } from './dom.js';
+import { host } from './host.js';
+import {
+    _setSectionPracticeMode,
+    _syncSectionPracticeFromLoop,
+    _updateSectionPracticeHighlight,
+    practiceSection,
+    resetSelection,
+} from './section-practice.js';
+
+// ── A-B Loop ────────────────────────────────────────────────────────────
+export let loopA = null;
+export let loopB = null;
+// Bumped on every NON-practiceSection loop mutation (direct setLoop from Saved
+// Loops / the plugin API, and clearLoop). practiceSection() captures it and bails
+// if it changes mid-retry, so a stale section retry can't overwrite a loop the
+// user just set/cleared by another path. practiceSection's own setLoop calls pass
+// skipSectionSync and do NOT bump it (they must not supersede themselves).
+export let _loopMutationGen = 0;
+
+export function setLoopStart() {
+    loopA = host._audioTime();
+    document.getElementById('btn-loop-a').className = 'px-3 py-1.5 bg-green-900/50 rounded-lg text-xs text-green-300 transition';
+    updateLoopUI();
+}
+
+export function setLoopEnd() {
+    if (loopA === null) return;
+    loopB = host._audioTime();
+    if (loopB <= loopA) { loopB = null; return; }
+    document.getElementById('btn-loop-b').className = 'px-3 py-1.5 bg-green-900/50 rounded-lg text-xs text-green-300 transition';
+    updateLoopUI();
+    // Manual A/B arming is a loop mutation like setLoop()'s — emit the same
+    // transport event so event-driven consumers (note_detect drill sync) see
+    // button-armed loops without having to poll getLoop().
+    window.feedBack?.playback?.transportEvent?.('loop-set', { requesterId: 'core.loop', loopA, loopB, loop: { startTime: loopA, endTime: loopB, enabled: true, state: 'active' } });
+}
+
+export function clearLoop(options) {
+    const { emitTransportEvent = true } = options || {};
+    // playSong() clears the loop on every song load, so only signal a
+    // loop-cleared transport event when a loop was actually active —
+    // otherwise every song switch emits a spurious playback:loop-cleared.
+    const hadLoop = loopA !== null || loopB !== null;
+    _setSectionPracticeMode(false, { skipClearLoop: true });
+    loopA = null;
+    loopB = null;
+    document.getElementById('btn-loop-a').className = 'px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs text-gray-300 transition';
+    document.getElementById('btn-loop-b').className = 'px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs text-gray-300 transition';
+    document.getElementById('btn-loop-clear').classList.add('hidden');
+    document.getElementById('btn-loop-save').classList.add('hidden');
+    document.getElementById('loop-label').textContent = '';
+    document.getElementById('saved-loops').value = '';
+    resetSelection();
+    _updateSectionPracticeHighlight(host._audioTime());
+    if (hadLoop && emitTransportEvent && typeof window !== 'undefined') {
+        window.feedBack?.playback?.transportEvent?.('loop-cleared', {
+            requesterId: 'core.loop',
+            reason: 'app loop cleared',
+            loop: { enabled: false, state: 'inactive' },
+        });
+    }
+}
+
+// Resync #saved-loops + #btn-loop-delete with the currently-active
+// loopA/loopB. Used by both setLoop's success path (so plugin-driven
+// loops show up correctly in the dropdown) and loadSavedLoop's
+// failure path (so a cancelled selection reverts to the still-active
+// loop). Without this sync, deleteSelectedLoop could target a stale
+// option that doesn't match the active loop.
+function _syncSavedLoopSelection() {
+    const sel = document.getElementById('saved-loops');
+    const delBtn = document.getElementById('btn-loop-delete');
+    if (!sel || !delBtn) return;
+    let selected = '';
+    if (loopA !== null && loopB !== null) {
+        for (const opt of sel.options) {
+            if (Number(opt.dataset.start) === loopA && Number(opt.dataset.end) === loopB) {
+                selected = opt.value;
+                break;
+            }
+        }
+    }
+    sel.value = selected;
+    delBtn.classList.toggle('hidden', !selected);
+}
+
+// Programmatically set both loop endpoints and seek to A. The dropdown
+// path (loadSavedLoop) and the plugin-API path (window.feedBack.setLoop)
+// both funnel through here so the UI state stays canonical regardless of
+// who triggered the loop.
+//
+// Returns true if the seek landed at A and the loop is now active;
+// returns false if the seek was cancelled by teardown or landed off-target
+// (JUCE clamp / HTML5 snap > 50ms from A). On false, loopA/loopB are NOT
+// committed and the UI is not painted — the prior loop (if any) stays
+// active. Throws on invalid inputs.
+export async function setLoop(a, b, options) {
+    const { emitTransportEvent = true, skipSectionSync = false, commitGuard = null } = options || {};
+    const aNum = Number(a);
+    const bNum = Number(b);
+    if (!Number.isFinite(aNum) || !Number.isFinite(bNum) || bNum <= aNum) {
+        throw new Error(`setLoop: requires finite a and b with b > a (got a=${a}, b=${b})`);
+    }
+    // Don't arm loopA/loopB before the seek lands — the 60Hz tick's wrap
+    // detector (`ct >= loopB`) would trigger startCountIn against
+    // half-applied state.
+    const r = await host._audioSeek(aNum, 'loop-set');
+    if (!r.completed || Math.abs(r.to - aNum) > 0.05) return false;
+    // Caller-owned staleness gate, re-checked after the awaited seek and before
+    // we commit loopA/loopB. practiceSection() passes this so a superseded retry
+    // (newer section click, mode turned off, or song/arrangement teardown that
+    // happened during the seek) does not arm a stale loop. Returning false here
+    // leaves the prior loop (if any) untouched, same as the off-target path.
+    if (typeof commitGuard === 'function' && !commitGuard()) return false;
+    loopA = aNum;
+    loopB = bNum;
+    // A direct (non-practice) loop set supersedes any in-flight practiceSection
+    // retry; practiceSection passes skipSectionSync and is exempt so it doesn't
+    // cancel itself.
+    if (!skipSectionSync) _loopMutationGen++;
+    document.getElementById('btn-loop-a').className = 'px-3 py-1.5 bg-green-900/50 rounded-lg text-xs text-green-300 transition';
+    document.getElementById('btn-loop-b').className = 'px-3 py-1.5 bg-green-900/50 rounded-lg text-xs text-green-300 transition';
+    updateLoopUI();
+    // Sync the saved-loops dropdown so a plugin-driven setLoop call
+    // surfaces the matching saved option (and Delete button) — otherwise
+    // the dropdown can stay on a stale selection and deleteSelectedLoop
+    // would target the wrong record.
+    _syncSavedLoopSelection();
+    // practiceSection() passes skipSectionSync: it sets its own section state
+    // under a request-gen guard, so the shared setLoop path must NOT re-sync
+    // here — otherwise a stale (superseded / mode-off) practiceSection retry
+    // that lands inside setLoop would re-arm the loop and flip the mode back on
+    // before the caller's gen check can bail. Direct callers (Saved Loops,
+    // window.feedBack.setLoop) still sync so their chip selection tracks.
+    if (!skipSectionSync && typeof _syncSectionPracticeFromLoop === 'function') {
+        _syncSectionPracticeFromLoop();
+    }
+    if (emitTransportEvent && typeof window !== 'undefined') {
+        window.feedBack?.playback?.transportEvent?.('loop-set', { requesterId: 'core.loop', loopA, loopB, loop: { startTime: loopA, endTime: loopB, enabled: true, state: 'active' } });
+    }
+    return true;
+}
+
+export function updateLoopUI() {
+    const label = document.getElementById('loop-label');
+    const hasLoop = loopA !== null && loopB !== null;
+    if (hasLoop) {
+        label.textContent = `${host.formatTime(loopA)} → ${host.formatTime(loopB)}`;
+        document.getElementById('btn-loop-clear').classList.remove('hidden');
+        document.getElementById('btn-loop-save').classList.remove('hidden');
+    } else if (loopA !== null) {
+        label.textContent = `${host.formatTime(loopA)} → ?`;
+        document.getElementById('btn-loop-clear').classList.add('hidden');
+        document.getElementById('btn-loop-save').classList.add('hidden');
+    } else {
+        label.textContent = '';
+    }
+    host._updateEditRegionBtn();
+}
+
+export async function loadSavedLoops() {
+    const sel = document.getElementById('saved-loops');
+    const delBtn = document.getElementById('btn-loop-delete');
+    if (!host.currentFilename()) { sel.classList.add('hidden'); delBtn.classList.add('hidden'); return; }
+
+    const resp = await fetch(`/api/loops?filename=${encodeURIComponent(decodeURIComponent(host.currentFilename()))}`);
+    const loops = await resp.json();
+
+    sel.innerHTML = '<option value="">Saved Loops</option>';
+    for (const l of loops) {
+        sel.innerHTML += `<option value="${l.id}" data-start="${l.start}" data-end="${l.end}">${esc(l.name)} (${host.formatTime(l.start)}→${host.formatTime(l.end)})</option>`;
+    }
+    if (loops.length > 0) {
+        sel.classList.remove('hidden');
+    } else {
+        sel.classList.add('hidden');
+    }
+    delBtn.classList.add('hidden');
+}
+
+export async function loadSavedLoop(loopId) {
+    const sel = document.getElementById('saved-loops');
+    const opt = sel.selectedOptions[0];
+    const delBtn = document.getElementById('btn-loop-delete');
+    if (!loopId || !opt?.dataset.start) {
+        delBtn.classList.add('hidden');
+        return;
+    }
+    let ok = false;
+    try {
+        // Pass raw strings — setLoop's Number() coercion is stricter than
+        // parseFloat (rejects "12abc") so malformed dataset values throw
+        // and fall into the catch instead of silently truncating.
+        ok = await setLoop(opt.dataset.start, opt.dataset.end);
+    } catch (err) {
+        // Malformed dataset (server returned bad data): treat the same as
+        // a failed seek so the dropdown resyncs and we don't propagate an
+        // uncaught rejection out of the onchange handler.
+        console.warn('[loadSavedLoop] setLoop threw:', err);
+        ok = false;
+    }
+    if (!ok) {
+        // Seek aborted, landed off-target, or input was malformed.
+        // Resync the dropdown with the still-active loop so the UI
+        // doesn't lie about which loop is loaded.
+        _syncSavedLoopSelection();
+        return;
+    }
+    // Success path: setLoop already called _syncSavedLoopSelection,
+    // which surfaces the delete button when the new loop matches a
+    // saved option (which the dropdown selection guarantees here).
+}
+
+export async function saveCurrentLoop() {
+    if (loopA === null || loopB === null || !host.currentFilename()) return;
+    const name = await uiPrompt({ title: 'Save Loop', label: 'Loop name', value: 'Loop', okLabel: 'Save' });
+    if (name === null) return;          // cancelled
+    const finalName = name.trim() || 'Loop';   // never persist an empty name
+    await fetch('/api/loops', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            filename: decodeURIComponent(host.currentFilename()),
+            name: finalName,
+            start: loopA,
+            end: loopB,
+        }),
+    });
+    await loadSavedLoops();
+    document.getElementById('btn-loop-save').classList.add('hidden');
+}
+
+export async function deleteSelectedLoop() {
+    const sel = document.getElementById('saved-loops');
+    const loopId = sel.value;
+    if (!loopId) return;
+    await fetch(`/api/loops/${loopId}`, { method: 'DELETE' });
+    clearLoop();
+    await loadSavedLoops();
+}

static/js/player-controls.js

@@ -0,0 +1,229 @@
+// Player controls — the speed and mastery sliders, and the four playback preference
+// reads (autoplay-exit, up-next, countdown-before-song, confirm-exit).
+//
+// The fourth slice out of app.js's strongly-connected core, and by far the easiest:
+// ONE hook and NO shared mutable state. It is here because these three groups are the
+// same surface (the controls under the highway) and all three reach the same helper.
+//
+// The preference reads are one-line localStorage lookups that half of app.js consults
+// before deciding whether to auto-start, show the Up Next pill, run a count-in, or
+// confirm on exit. They travel with the controls that set them.
+//
+// See ./host.js: reading an unwired hook THROWS, and tests/js/host_contract.test.js
+// fails CI if the hooks used here and the hooks app.js wires ever drift apart.
+import { audio } from './audio-el.js';
+import { host } from './host.js';
+
+// ── Autoplay & auto-exit (global option, default ON) ──────────────────
+// One toggle (`autoplayExit` in localStorage) that (a) auto-starts a song
+// once it's ready and (b) returns to the launching menu when the song
+// ends. Absence of the key means enabled. The behaviour lives in core
+// (app.js, shared by the v3 + classic UIs); the end-of-song *score*
+// screen, when present, is a plugin and hooks the contract below.
+export function _autoplayExitEnabled() {
+    try { return localStorage.getItem('autoplayExit') !== '0'; } catch (_) { return true; }
+}
+
+// ── "Up Next" pill (global option, default ON) ────────────────────────
+// Gates the v3 player chrome's persistent upcoming-section pill
+// (#v3-upnext, driven by player-chrome.js's updateUpNext). Client-only
+// localStorage pref (`showUpNext`); absence of the key means enabled.
+// player-chrome.js reads window.feedBack.showUpNext each tick and hides
+// the pill when off.
+export function _showUpNextEnabled() {
+    try { return localStorage.getItem('showUpNext') !== '0'; } catch (_) { return true; }
+}
+
+// "Countdown before song" (Gameplay tab). Mirrored to localStorage by
+// loadSettings so the song-start path can read it synchronously here — no
+// async /api/settings fetch on the play hot path. Defaults off.
+export function _countdownBeforeSongEnabled() {
+    try { return localStorage.getItem('countdownBeforeSong') === '1'; } catch (_) { return false; }
+}
+
+export function _curPlaybackSpeed() {
+    try {
+        return window._juceMode
+            ? ((window.jucePlayer && window.jucePlayer._speed) || 1)
+            : (document.getElementById('audio')?.playbackRate || 1);
+    } catch (_) { return 1; }
+}
+
+// ── "Ask before leaving a song" (Gameplay tab, default OFF) ────────────────
+// Client-only localStorage pref (`confirmExitSong`); absence = OFF. When ON, a
+// *user-initiated* exit (Escape, or the player ✕) opens a small confirm instead
+// of leaving immediately. Auto-exit on song-end and a results screen's own
+// Close never prompt — they call closeCurrentSong() directly, which stays the
+// unguarded actual-exit.
+export function _exitConfirmEnabled() {
+    try { return localStorage.getItem('confirmExitSong') === '1'; } catch (_) { return false; }
+}
+
+const SPEED_PRESET_PCTS = [100, 90, 80, 75, 70, 60, 50];
+const SPEED_SNAP_THRESHOLD = 0.02;
+let _speedPresetsWired = false;
+
+function _speedPresetPctFromActive(activePctOrRate) {
+    if (!Number.isFinite(activePctOrRate)) return null;
+    const rate = activePctOrRate <= 1.5 ? activePctOrRate : activePctOrRate / 100;
+    for (const pct of SPEED_PRESET_PCTS) {
+        if (Math.abs(rate - pct / 100) <= SPEED_SNAP_THRESHOLD) return pct;
+    }
+    return null;
+}
+
+function _updateSpeedPresetButtons(activePctOrRate) {
+    const wrap = document.getElementById('speed-presets');
+    if (!wrap) return;
+    const target = _speedPresetPctFromActive(activePctOrRate);
+    for (const btn of wrap.querySelectorAll('[data-speed-preset]')) {
+        const pct = Number(btn.dataset.speedPreset);
+        btn.classList.toggle('v3-speed-preset-active', target !== null && pct === target);
+    }
+}
+
+export function applySpeedPreset(percent) {
+    const slider = document.getElementById('speed-slider');
+    if (!slider) return;
+    const pct = Math.max(
+        Number(slider.min) || 15,
+        Math.min(Number(slider.max) || 150, Number(percent)),
+    );
+    if (!Number.isFinite(pct)) return;
+    slider.value = String(pct);
+    host.handleSliderInput(slider);
+    slider.dispatchEvent(new Event('input', { bubbles: true }));
+}
+
+export function _wireSpeedPresetsOnce() {
+    if (_speedPresetsWired) return;
+    const presets = document.getElementById('speed-presets');
+    if (!presets) return;
+    _speedPresetsWired = true;
+    presets.addEventListener('click', (e) => {
+        const btn = e.target.closest('[data-speed-preset]');
+        if (!btn) return;
+        applySpeedPreset(Number(btn.dataset.speedPreset));
+    });
+}
+
+export function setSpeed(v) {
+    const speedSlider = document.getElementById('speed-slider');
+    const rate = Number(v);
+    if (!Number.isFinite(rate)) {
+        return;
+    }
+    if (window._juceMode) {
+        window.jucePlayer?.setRate(rate);
+        const juceAudio = window.feedBackDesktop?.audio;
+        Promise.resolve()
+            .then(() => juceAudio?.setBackingSpeed(rate))
+            // Match the HTML5 path: preserve pitch on the JUCE backing track too.
+            // Optional-chained call is a no-op on desktop builds that predate
+            // setBackingPreservePitch, so this is safe to ship unconditionally.
+            .then(() => juceAudio?.setBackingPreservePitch?.(true))
+            .catch(err => console.warn('[setSpeed] backing speed/preserve-pitch failed:', err));
+    } else {
+        audio.playbackRate = rate;
+    }
+    const speedLabel = document.getElementById('speed-label');
+    if (speedLabel) speedLabel.textContent = rate.toFixed(2) + 'x';
+    host.handleSliderInput(speedSlider);
+    _updateSpeedPresetButtons(rate);
+}
+
+export function _resetPlaybackSpeedForNewSong() {
+    // Reset the *actual* playback rate to 1x, not just the visible slider/label
+    // (feedBack#615). The HTML5 <audio> element and the desktop JUCE/backing
+    // engine each retain their own rate, and which one drives the next song
+    // isn't decided until later in the load, so reset all paths unconditionally.
+    // Every setter is idempotent and optional-chained, so this is safe in web
+    // and desktop builds alike — no need to branch on window._juceMode.
+    const speedSlider = document.getElementById('speed-slider');
+    if (speedSlider) speedSlider.value = 100;
+    audio.playbackRate = 1;
+    window.jucePlayer?.setRate?.(1);
+    const juceAudio = window.feedBackDesktop?.audio;
+    Promise.resolve()
+        .then(() => juceAudio?.setBackingSpeed?.(1))
+        .then(() => juceAudio?.setBackingPreservePitch?.(true))
+        .catch(err => console.warn('[resetSpeed] backing speed/preserve-pitch failed:', err));
+    // Mirror setSpeed's UI side-effects (label text + slider fill styling).
+    const speedLabel = document.getElementById('speed-label');
+    if (speedLabel) speedLabel.textContent = (1).toFixed(2) + 'x';
+    host.handleSliderInput(speedSlider);
+    _updateSpeedPresetButtons(100);
+}
+// Master-difficulty slider (feedBack#48). Persists partial via
+// /api/settings — the POST handler merges only the keys present, so
+// this fire-and-forget call doesn't clobber dlc_dir or other settings.
+//
+// Debounced trailing-edge (300ms) so dragging the slider — which fires
+// oninput per pixel — doesn't flood the server with concurrent writes
+// to config.json. highway.setMastery() still fires every oninput so
+// the chart re-filters in real time; only disk persistence waits.
+let _masteryPersistTimer = null;
+function _persistMastery(pct) {
+    if (_masteryPersistTimer) clearTimeout(_masteryPersistTimer);
+    _masteryPersistTimer = setTimeout(() => {
+        _masteryPersistTimer = null;
+        fetch('/api/settings', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ master_difficulty: pct }),
+        }).catch(() => { /* best-effort — next setMastery() will retry */ });
+    }, 300);
+}
+export function setMastery(v) {
+    _applyMastery(v);
+}
+// Shared mastery applier. Master difficulty has two controls that write the
+// same master_difficulty key: the player-popover slider (#mastery-slider) and
+// the Gameplay-tab "Note highway speed" slider (#setting-highway-speed). Route
+// both — and loadSettings' hydration — through here so their positions,
+// labels, and track fills stay in sync regardless of which the user touches,
+// plus the live highway re-filter and the debounced persist. All element reads
+// are null-guarded since either control may be absent (follower window, or the
+// settings markup not yet rendered).
+export function _applyMastery(v, opts = {}) {
+    // Guard + clamp: v might be a slider string, a programmatic call from a
+    // plugin, or a restored settings value with a bad shape. Don't let NaN
+    // reach a label (would show "NaN%") or the POST.
+    const parsed = parseInt(v, 10);
+    if (!Number.isFinite(parsed)) return;
+    const pct = Math.max(0, Math.min(100, parsed));
+    const popLabel = document.getElementById('mastery-label');
+    if (popLabel) popLabel.textContent = pct + '%';
+    const popSlider = document.getElementById('mastery-slider');
+    if (popSlider) {
+        if (String(popSlider.value) !== String(pct)) popSlider.value = pct;
+        host.handleSliderInput(popSlider);
+    }
+    const setSlider = document.getElementById('setting-highway-speed');
+    if (setSlider) {
+        if (String(setSlider.value) !== String(pct)) setSlider.value = pct;
+        host.handleSliderInput(setSlider);
+    }
+    // The Gameplay-tab label markup appends a literal "%" after this span
+    // (matching the av-offset "ms" pattern), so write the number alone here —
+    // unlike #mastery-label above, whose markup carries no trailing unit.
+    const setLabel = document.getElementById('setting-highway-speed-val');
+    if (setLabel) setLabel.textContent = pct;
+    highway.setMastery(pct / 100);
+    if (!opts.skipPersist) _persistMastery(pct);
+}
+// Reflect phrase-data availability on the slider after every `ready`.
+// The server omits the `phrases` message entirely for single-level
+// sources (GP imports, legacy sloppak), so hasPhraseData() is the
+// right signal to enable/disable the slider.
+export function _applyMasteryAvailability(hasPhraseData) {
+    const slider = document.getElementById('mastery-slider');
+    if (!slider) return;
+    if (hasPhraseData) {
+        slider.disabled = false;
+        slider.title = 'Master difficulty — low = simpler chart, high = full';
+    } else {
+        slider.disabled = true;
+        slider.title = 'Source chart has a single difficulty level — slider disabled';
+    }
+}

static/js/player-state.js

@@ -0,0 +1,42 @@
+// Shared, MUTABLE player state.
+//
+// WHY A CONTAINER AND NOT PLAIN EXPORTS. An imported binding is read-only. Every
+// slice carved out of app.js so far has only ever READ the state it shares
+// (loopA/loopB, _audioSeekGen, currentFilename), so a getter hook was enough and no
+// container was needed. That runs out here: count-in genuinely WRITES `isPlaying`
+// (it starts and stops playback) and `lastAudioTime`. `import { isPlaying }` then
+// `isPlaying = true` throws — the binding cannot be assigned to.
+//
+// So the state moves onto an object. `S.isPlaying = true` is a property write, which
+// works from any module holding the same `S`. This is the same shape the stems,
+// studio, and editor migrations converged on.
+//
+// It is deliberately SMALL. app.js has ~104 top-level `let` scalars; lifting all of
+// them would be a ~977-site rewrite for no benefit, since most are private to one
+// cluster and travel with it. Only the ones a carved module must WRITE belong here.
+// Add to it when a carve actually needs it, not before.
+//
+// NB app.js's own 71 reference sites were rewritten mechanically — but from the AST,
+// not by text substitution. Of 100 textual occurrences of these two names, only 71
+// resolve to the module binding: 22 are member accesses (`someObj.isPlaying`), 4 are
+// the local parameter of setPlayButtonState(isPlaying), one is an object key, and two
+// are shorthand properties (`{ isPlaying }`) that must become `{ isPlaying: S.isPlaying }`.
+// A blind find-and-replace corrupts all 29.
+export const S = {
+    /** Is the transport running? Written by playback, count-in, and the JUCE shims. */
+    isPlaying: false,
+
+    /**
+     * The last audio position we saw, in seconds. Used to detect a seek that did not
+     * land where it was asked to (JUCE can clamp; HTML5 can round).
+     */
+    lastAudioTime: 0,
+
+    /**
+     * A resume request armed by playSong({ resume }) and consumed on song:ready.
+     * Written by app.js (playSong, and the song:ready listener that consumes it) and
+     * read by the resume-session module — so, like the two above, it cannot be a plain
+     * export.
+     */
+    pendingResume: null,
+};

static/js/plugin-loader.js

@@ -802,3 +802,62 @@ export async function bootstrapPluginsAndUi() {
     _streamPluginStartup();
     return plugins;
 }
+
+
+// ── Plugin updates ──────────────────────────────────────────────────────
+// The Settings-screen "Check for updates" / "Update" buttons. Carved out of
+// app.js (R3a) into the loader rather than a module of their own: this is plugin
+// MANAGEMENT, it belongs with the code that loads them. Both are inline handlers,
+// so app.js re-exposes them on window.
+
+export async function checkPluginUpdates() {
+    const btn = document.getElementById('btn-check-updates');
+    const status = document.getElementById('updates-status');
+    const list = document.getElementById('plugin-updates-list');
+    btn.disabled = true;
+    btn.textContent = 'Checking...';
+    status.textContent = '';
+    list.innerHTML = '';
+    try {
+        const resp = await fetch('/api/plugins/updates');
+        const data = await resp.json();
+        const updates = data.updates || {};
+        const keys = Object.keys(updates);
+        if (keys.length === 0) {
+            status.textContent = 'All plugins are up to date.';
+        } else {
+            status.textContent = `${keys.length} update${keys.length > 1 ? 's' : ''} available`;
+            for (const id of keys) {
+                const u = updates[id];
+                const row = document.createElement('div');
+                row.className = 'flex items-center gap-3 bg-dark-700 rounded-lg px-4 py-2';
+                row.innerHTML = `
+                    <span class="text-sm text-gray-300 flex-1">${u.name} <span class="text-xs text-gray-500">(${u.behind} commit${u.behind > 1 ? 's' : ''} behind — ${u.local} → ${u.remote})</span></span>
+                    <button onclick="updatePlugin('${id}', this)" class="bg-accent/20 hover:bg-accent/30 text-accent-light px-3 py-1 rounded-lg text-xs transition">Update</button>`;
+                list.appendChild(row);
+            }
+        }
+    } catch (e) {
+        status.textContent = 'Failed to check for updates.';
+    }
+    btn.disabled = false;
+    btn.textContent = 'Check for Updates';
+}
+
+export async function updatePlugin(pluginId, btn) {
+    btn.disabled = true;
+    btn.textContent = 'Updating...';
+    try {
+        const resp = await fetch(`/api/plugins/${pluginId}/update`, { method: 'POST' });
+        const data = await resp.json();
+        if (data.ok) {
+            btn.textContent = 'Updated — restart to apply';
+            btn.className = 'bg-green-900/30 text-green-400 px-3 py-1 rounded-lg text-xs';
+        } else {
+            btn.textContent = 'Failed';
+            btn.title = data.error || '';
+        }
+    } catch (e) {
+        btn.textContent = 'Error';
+    }
+}

static/js/resume-session.js

@@ -0,0 +1,157 @@
+// Resume last session — the snapshot taken when you leave a song, and the pill that
+// offers it back.
+//
+// The fifth slice out of app.js's strongly-connected core. Small and self-contained:
+// ONE hook (playSong) plus a currentFilename getter.
+//
+// The armed resume request itself lives on the shared container as S.pendingResume,
+// not here, because app.js WRITES it — playSong({ resume }) arms it and the song:ready
+// listener consumes it — while this module reads it. An imported binding is read-only,
+// so shared mutable state has to live on the container. Same reason isPlaying does.
+//
+// See ./host.js: reading an unwired hook THROWS, and tests/js/host_contract.test.js
+// fails CI if the hooks used here and the hooks app.js wires ever drift apart.
+import { host } from './host.js';
+import { _curPlaybackSpeed } from './player-controls.js';
+import { S } from './player-state.js';
+
+// ── Resume last session ────────────────────────────────────────────────────
+// Leaving a song snapshots where you were — song, arrangement, position, and
+// speed — so an exit (especially an accidental one, now that Escape reliably
+// leaves regardless of focus) is recoverable instead of restarting from bar 1.
+// The snapshot is offered back through a non-blocking "Resume" pill; it never
+// gates, blocks, or auto-acts. Cleared on natural song-end and once consumed.
+// (This is the player-session slice; the broader nav/state-resume work — e.g.
+// returning to a song after wandering into Settings → Tone Builder — is a
+// separate, larger track.)
+const _RESUME_KEY = 'feedBack.resumeSession';
+const _RESUME_MAX_AGE_MS = 24 * 60 * 60 * 1000;   // a day-old snapshot is stale
+const _RESUME_MIN_POSITION_S = 3;                  // ignore barely-started songs
+const _RESUME_END_GUARD_S = 5;                      // ignore basically-finished songs
+let _resumePillDismissed = false;                   // per-session: user waved off the current snapshot
+
+// Snapshot the live session. Called from showScreen()'s teardown before
+// highway.stop()/audio unload, while getSongInfo() + position are still valid.
+export function _snapshotResumeSession(position) {
+    try {
+        if (!host.currentFilename()) return;
+        const si = (window.highway && typeof highway.getSongInfo === 'function')
+            ? (highway.getSongInfo() || {}) : {};
+        const dur = Number(si.duration) || 0;
+        const pos = Number(position) || 0;
+        // Only worth resuming a song you were genuinely mid-way through — not a
+        // glance at the first seconds, and not one that already basically ended.
+        if (pos < _RESUME_MIN_POSITION_S) { _clearResumeSession(); return; }
+        if (dur && pos > dur - _RESUME_END_GUARD_S) { _clearResumeSession(); return; }
+        const snap = {
+            f: host.currentFilename(),
+            a: (typeof si.arrangement_index === 'number' && si.arrangement_index >= 0)
+                ? si.arrangement_index : undefined,
+            t: pos,
+            sp: _curPlaybackSpeed(),
+            title: si.title || '',
+            artist: si.artist || '',
+            ts: Date.now(),
+        };
+        localStorage.setItem(_RESUME_KEY, JSON.stringify(snap));
+        // A fresh snapshot earns one offer — undo any earlier dismissal.
+        _resumePillDismissed = false;
+    } catch (_) { /* storage unavailable — resume is best-effort */ }
+}
+
+export function _readResumeSession() {
+    try {
+        const raw = localStorage.getItem(_RESUME_KEY);
+        if (!raw) return null;
+        const snap = JSON.parse(raw);
+        if (!snap || !snap.f || !(Number(snap.t) > 0)) return null;
+        if (!snap.ts || Date.now() - snap.ts > _RESUME_MAX_AGE_MS) { _clearResumeSession(); return null; }
+        return snap;
+    } catch (_) { return null; }
+}
+
+export function _clearResumeSession() {
+    try { localStorage.removeItem(_RESUME_KEY); } catch (_) {}
+}
+
+// Re-enter the snapshotted song and restore arrangement + position + speed.
+export async function resumeLastSession() {
+    const snap = _readResumeSession();
+    if (!snap) { _hideResumePill(); return false; }
+    _hideResumePill();
+    try {
+        await host.playSong(snap.f, snap.a, {
+            resume: { position: Number(snap.t) || 0, speed: Number(snap.sp) || 1 },
+        });
+    } catch (err) {
+        // A transient load/connect failure must not strand the user: keep the
+        // snapshot so the pill can re-offer it on the next non-player screen,
+        // rather than consuming the only copy before the song actually loaded.
+        console.warn('[app] resume failed to load; keeping snapshot:', err);
+        S.pendingResume = null;
+        return false;
+    }
+    _clearResumeSession();   // consumed only after a successful load
+    return true;
+}
+
+// ── Resume pill (non-blocking "continue where you left off") ────────────────
+// Self-contained, inline-styled, body-appended so it works identically in the
+// classic (v2) and v3 shells with no Tailwind rebuild. It only ever appears off
+// the player screen, never blocks, and a dismiss forgets the current snapshot
+// for the session.
+export function _hideResumePill() {
+    const el = document.getElementById('fb-resume-pill');
+    if (el) el.remove();
+}
+
+export function _maybeShowResumePill() {
+    const active = document.querySelector('.screen.active');
+    if (active && active.id === 'player') { _hideResumePill(); return; }
+    if (_resumePillDismissed) return;
+    const snap = _readResumeSession();
+    if (!snap) { _hideResumePill(); return; }
+    if (document.getElementById('fb-resume-pill')) return;   // already shown
+
+    const label = (snap.title || decodeURIComponent(snap.f || 'your last song')).toString();
+    const pill = document.createElement('div');
+    pill.id = 'fb-resume-pill';
+    pill.setAttribute('role', 'status');
+    pill.style.cssText = [
+        'position:fixed', 'left:16px', 'bottom:16px', 'z-index:120',
+        'display:flex', 'align-items:center', 'gap:10px',
+        'max-width:min(90vw,360px)', 'padding:10px 12px',
+        'background:rgba(17,24,39,0.96)', 'color:#e5e7eb',
+        'border:1px solid rgba(148,163,184,0.25)', 'border-radius:10px',
+        'box-shadow:0 6px 24px rgba(0,0,0,0.4)',
+        'font:13px/1.3 system-ui,-apple-system,"Segoe UI",Roboto,sans-serif',
+    ].join(';');
+
+    const text = document.createElement('div');
+    text.style.cssText = 'flex:1;min-width:0';
+    const t1 = document.createElement('div');
+    t1.textContent = 'Resume practice';
+    t1.style.cssText = 'font-weight:600;color:#fff';
+    const t2 = document.createElement('div');
+    t2.textContent = label;
+    t2.style.cssText = 'opacity:0.7;white-space:nowrap;overflow:hidden;text-overflow:ellipsis';
+    text.appendChild(t1); text.appendChild(t2);
+
+    const resumeBtn = document.createElement('button');
+    resumeBtn.type = 'button';
+    resumeBtn.textContent = 'Resume ▸';
+    resumeBtn.style.cssText = 'flex:none;padding:6px 10px;border:0;border-radius:7px;background:#4080e0;color:#fff;font-weight:600;cursor:pointer';
+    resumeBtn.addEventListener('click', () => { resumeLastSession(); });
+
+    const dismissBtn = document.createElement('button');
+    dismissBtn.type = 'button';
+    dismissBtn.setAttribute('aria-label', 'Dismiss');
+    dismissBtn.textContent = '✕';
+    dismissBtn.style.cssText = 'flex:none;padding:4px 6px;border:0;border-radius:7px;background:transparent;color:#9ca3af;cursor:pointer;font-size:14px';
+    dismissBtn.addEventListener('click', () => { _resumePillDismissed = true; _hideResumePill(); });
+
+    pill.appendChild(text);
+    pill.appendChild(resumeBtn);
+    pill.appendChild(dismissBtn);
+    (document.body || document.documentElement).appendChild(pill);
+}

static/js/settings-io.js

@@ -0,0 +1,155 @@
+// Settings backup — the export / import bundle.
+//
+// Carved verbatim out of static/app.js (R3a). A LEAF module: imports nothing.
+//
+// Two entry points, both inline handlers on the Settings screen, so app.js keeps
+// re-exposing them on window. The import is two-phase (server first, atomic; then
+// a best-effort localStorage merge) — the rationale comment below is the contract
+// and moved with the code.
+
+//
+// Bundles server config + every localStorage key + opted-in plugin server
+// files into a single JSON file.
+//
+// Apply semantics — phased, NOT all-or-nothing across the two stores:
+//   1. Server first (/api/settings/import). Phase-1 validation guards
+//      the whole bundle; phase-2 disk commit is per-file but ordered
+//      so a mid-apply failure surfaces a `partial` field. A server
+//      failure short-circuits before any localStorage write, so the
+//      browser side stays untouched on validation refusals.
+//   2. localStorage second, only after the server returns ok. Applied
+//      as a MERGE (no clear): bundled keys overwrite, locally-present
+//      keys absent from the bundle are preserved (so a plugin
+//      installed after the export keeps its first-run defaults).
+//      A localStorage exception here (quota / private mode) is
+//      surfaced verbatim — server state is already committed and we
+//      don't pretend the import was clean.
+//
+// In short: the server side is atomic in phase 1 and surface-partial in
+// phase 2; the localStorage side is best-effort merge after server
+// success. Failures are reported, never silenced.
+
+export async function exportSettings() {
+    const status = document.getElementById('backup-status');
+    status.textContent = 'Exporting...';
+    try {
+        const resp = await fetch('/api/settings/export');
+        if (!resp.ok) {
+            status.textContent = `Export failed (HTTP ${resp.status})`;
+            return;
+        }
+        const bundle = await resp.json();
+        // Layer in the browser's localStorage. Use the standard Storage
+        // iteration API (length + key(i)) rather than Object.keys —
+        // Object.keys on a Storage instance is not deterministic across
+        // browsers and can both miss entries and include non-entry
+        // properties depending on the implementation. Keys are preserved
+        // verbatim as strings; that's how localStorage stores them, and
+        // round-trip fidelity matters more than re-typing values that
+        // were never typed in the first place.
+        const localStorageData = {};
+        for (let i = 0; i < localStorage.length; i++) {
+            const key = localStorage.key(i);
+            if (key === null) continue;
+            const value = localStorage.getItem(key);
+            if (value !== null) localStorageData[key] = value;
+        }
+        bundle.local_storage = localStorageData;
+
+        // Trigger download via blob + temporary <a download>. We honor the
+        // server's Content-Disposition filename when present, otherwise
+        // fall back to a date-stamped default.
+        let filename = 'feedBack-settings.json';
+        const disposition = resp.headers.get('Content-Disposition');
+        if (disposition) {
+            const match = /filename="([^"]+)"/.exec(disposition);
+            if (match) filename = match[1];
+        }
+        const blob = new Blob([JSON.stringify(bundle, null, 2)], { type: 'application/json' });
+        const url = URL.createObjectURL(blob);
+        const a = document.createElement('a');
+        a.href = url;
+        a.download = filename;
+        document.body.appendChild(a);
+        a.click();
+        document.body.removeChild(a);
+        URL.revokeObjectURL(url);
+        status.textContent = `Exported ${filename}`;
+    } catch (e) {
+        status.textContent = `Export failed: ${e.message}`;
+    }
+}
+
+export async function importSettings(file) {
+    if (!file) return;
+    const status = document.getElementById('backup-status');
+    if (!confirm('Import will overwrite settings present in the bundle (server config, browser preferences, and opted-in plugin data) and reload the page. Settings not in the bundle (e.g. from plugins installed after the export) are preserved. Continue?')) {
+        status.textContent = 'Import cancelled';
+        return;
+    }
+    let bundle;
+    try {
+        bundle = JSON.parse(await file.text());
+    } catch (e) {
+        status.textContent = `Import failed: not valid JSON (${e.message})`;
+        return;
+    }
+
+    status.textContent = 'Importing...';
+    let resp, data;
+    try {
+        resp = await fetch('/api/settings/import', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(bundle),
+        });
+        data = await resp.json();
+    } catch (e) {
+        status.textContent = `Import failed: ${e.message}`;
+        return;
+    }
+    // Two failure shapes to surface: our own validation handler
+    // returns `{ok: false, error: "..."}`, but if the body fails
+    // FastAPI's request-level validation (e.g. top-level value is
+    // an array, not an object), the response is the framework's
+    // `{detail: ...}` shape with no `ok` key. `resp.ok` distinguishes
+    // both from success without depending on which path produced
+    // the failure.
+    if (!resp.ok || data.ok === false) {
+        let msg = data.error;
+        if (!msg && data.detail) {
+            msg = typeof data.detail === 'string'
+                ? data.detail
+                : JSON.stringify(data.detail);
+        }
+        status.textContent = `Import failed: ${msg || `HTTP ${resp.status}`}`;
+        return;
+    }
+
+    // Server applied successfully. Now apply the localStorage portion as
+    // a MERGE (not clear+restore): keys in the bundle overwrite, keys
+    // present locally but absent from the bundle are preserved. This
+    // matters when a plugin was installed *after* the export — wiping
+    // its localStorage would erase first-run defaults the plugin set on
+    // load, leaving it in a worse state than before the import. The
+    // tradeoff is that orphan keys from removed plugins or renamed key
+    // schemes also linger; cleaning those up is the user's job.
+    const ls = bundle.local_storage;
+    if (ls && typeof ls === 'object') {
+        try {
+            for (const [key, value] of Object.entries(ls)) {
+                if (typeof value === 'string') localStorage.setItem(key, value);
+            }
+        } catch (e) {
+            // Quota exceeded / private mode etc. Server side already
+            // committed, so we surface the partial state rather than
+            // pretending it succeeded.
+            status.textContent = `Server applied, but localStorage write failed: ${e.message}`;
+            return;
+        }
+    }
+
+    const warnings = (data.warnings || []).join('; ');
+    status.textContent = warnings ? `Imported with warnings: ${warnings}. Reloading...` : 'Imported. Reloading...';
+    setTimeout(() => location.reload(), 800);
+}

static/js/tuning-display.js

@@ -0,0 +1,228 @@
+// Tuning display — naming, string counts, and target frequencies.
+//
+// Carved verbatim out of static/app.js (R3a). A LEAF module: imports nothing.
+//
+// Turns raw per-string semitone offsets into things a human reads: a tuning NAME
+// ("Drop D", "Eb Standard", or a raw-offsets fallback), whether an arrangement is
+// bass, its effective string count, and the target FREQUENCIES + note names the
+// tuner checks against. Pure functions over a small MIDI/note-name table.
+//
+// The window / window.feedBack assignments for these stay in app.js — they are the
+// public contract (constitution II names window.feedBack), and app.js re-exposes
+// the imported bindings from exactly where it always did, so nothing about the
+// surface or its ordering changes.
+
+// Display-only tuning label helpers — never mutate offsets or affect playback.
+function _looksLikeRawTuningOffsets(str) {
+    if (!str || typeof str !== 'string') return false;
+    const s = str.trim();
+    if (!s) return false;
+    if (/^-?\d+$/.test(s)) return true;
+    if (/^-?\d+(?: -?\d+)+$/.test(s)) return true;
+    if (/^-?\d+(?:,-?\d+)+$/.test(s)) return true;
+    if (/^-?\d+(-?\d+){2,}$/.test(s)) return true;
+    return false;
+}
+
+function _tuningNameFromOffsets(offsets) {
+    if (!offsets || !offsets.length) return '';
+    const standard = {
+        0: 'E Standard', '-1': 'Eb Standard', '-2': 'D Standard',
+        '-3': 'C# Standard', '-4': 'C Standard', '-5': 'B Standard',
+        '-6': 'Bb Standard', '-7': 'A Standard',
+        1: 'F Standard', 2: 'F# Standard',
+    };
+    // Uniform offsets across 4 (bass) / 5 / 6 strings name the same Standard;
+    // a 4-string bass [0,0,0,0] must read "E Standard", not "Custom Tuning".
+    if (offsets.length >= 4 && offsets.every((o) => o === offsets[0])) {
+        const name = standard[offsets[0]];
+        if (name) return name;
+    }
+    if (offsets.length >= 4 && offsets[0] === offsets[1] - 2
+            && offsets.slice(1).every((o) => o === offsets[1])) {
+        const noteNames = ['E', 'F', 'F#', 'G', 'Ab', 'A', 'Bb', 'B', 'C', 'C#', 'D', 'Eb'];
+        return 'Drop ' + noteNames[((offsets[0] % 12) + 12) % 12];
+    }
+    const named = {
+        '-2,0,0,0,0,0': 'Drop D',
+        '-4,-2,-2,-2,-2,-2': 'Drop C',
+        '-2,-2,0,0,0,0': 'Double Drop D',
+        '0,0,0,-1,0,0': 'Open G',
+        '-2,-2,0,0,-2,-2': 'Open D',
+        '-2,0,0,0,-2,0': 'DADGAD',
+        '0,2,2,1,0,0': 'Open E',
+        '-2,0,0,2,3,2': 'Open D (alt)',
+    };
+    if (offsets.length === 6) {
+        const key = offsets.join(',');
+        if (named[key]) return named[key];
+    }
+    return 'Custom Tuning';
+}
+
+export function displayTuningName(value, offsets) {
+    // Explicit offsets win — always name them.
+    if (Array.isArray(offsets) && offsets.length > 0) {
+        return _tuningNameFromOffsets(offsets);
+    }
+    if (value && typeof value === 'string') {
+        const trimmed = value.trim();
+        if (!trimmed || trimmed === 'Unknown') return '';
+        if (!_looksLikeRawTuningOffsets(trimmed)) {
+            return trimmed;
+        }
+        // A raw offset string (now served by the API) — parse and name it so a
+        // known tuning like "-1 -1 -1 -1 -1 -1" reads "Eb Standard" rather than
+        // collapsing to "Custom Tuning".
+        const parsed = (typeof parseRawTuningOffsets === 'function')
+            ? parseRawTuningOffsets(trimmed) : null;
+        if (parsed && parsed.length) return _tuningNameFromOffsets(parsed);
+        return 'Custom Tuning';
+    }
+    return '';
+}
+
+export function isBassArrangement(context) {
+    const ctx = context && typeof context === 'object' ? context : {};
+    if (typeof ctx.isBass === 'boolean') return ctx.isBass;
+    const label = ((ctx.arrangement || '') + ' ' + (ctx.arrangement_smart_name || '')).toLowerCase();
+    if (/\bbass\b/.test(label)) return true;
+    if (/\b(lead|rhythm|combo|guitar)\b/.test(label)) return false;
+    return false;
+}
+
+export function effectiveStringCount(offsets, context) {
+    if (!Array.isArray(offsets) || !offsets.length) return 0;
+    const ctx = context && typeof context === 'object' ? context : {};
+    const isBass = isBassArrangement(ctx);
+    let sc = ctx.stringCount > 0 ? Number(ctx.stringCount) : 0;
+    if (!isBass) {
+        if (sc > 0 && sc <= 5 && offsets.length >= 6) sc = 6;
+        if (!sc) sc = offsets.length >= 6 ? offsets.length : 6;
+    } else if (!sc) {
+        sc = offsets.length >= 5 ? offsets.length : 4;
+    }
+    return Math.min(sc, offsets.length);
+}
+
+export function songTuningContext(songInfo) {
+    if (!songInfo || typeof songInfo !== 'object') return {};
+    return {
+        stringCount: songInfo.stringCount,
+        arrangement: songInfo.arrangement,
+        arrangement_smart_name: songInfo.arrangement_smart_name,
+    };
+}
+
+// Open-string target notes (display only) — mirrors plugins/tuner/utils/tuning-utils.js.
+const _TUNING_BASE_MIDI = {
+    4: [28, 33, 38, 43],
+    5: [23, 28, 33, 38, 43],
+    6: [40, 45, 50, 55, 59, 64],
+    7: [35, 40, 45, 50, 55, 59, 64],
+    8: [30, 35, 40, 45, 50, 55, 59, 64],
+};
+
+const _TUNING_NOTE_SHARP = ['C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B'];
+
+const _TUNING_NOTE_FLAT = ['C', 'Db', 'D', 'Eb', 'E', 'F', 'Gb', 'G', 'Ab', 'A', 'Bb', 'B'];
+
+function _tuningMidiToFreq(m) {
+    return Math.pow(2, (m - 69) / 12) * 440;
+}
+
+function _tuningOffsetsToFreqs(offsets, isBass) {
+    const len = offsets.length;
+    let base;
+    if (len === 4 || len === 5) {
+        base = isBass ? _TUNING_BASE_MIDI[len] : _TUNING_BASE_MIDI[6];
+    } else {
+        base = _TUNING_BASE_MIDI[len] || _TUNING_BASE_MIDI[6];
+    }
+    return offsets.map((offset, i) => {
+        const root = i < base.length ? base[i] : base[base.length - 1];
+        return _tuningMidiToFreq(root + offset);
+    });
+}
+
+function _noteNameFromFreq(freq, useFlats) {
+    const midi = 69 + 12 * Math.log2(freq / 440);
+    const rounded = Math.round(midi);
+    const names = useFlats ? _TUNING_NOTE_FLAT : _TUNING_NOTE_SHARP;
+    return names[((rounded % 12) + 12) % 12];
+}
+
+function _octaveNoteFromFreq(freq, useFlats) {
+    const midi = 69 + 12 * Math.log2(freq / 440);
+    const rounded = Math.round(midi);
+    const octave = Math.floor(rounded / 12) - 1;
+    return _noteNameFromFreq(freq, useFlats) + octave;
+}
+
+function _stringOrdinalLabel(n) {
+    const v = n % 100;
+    if (v >= 11 && v <= 13) return n + 'th';
+    const suffix = { 1: 'st', 2: 'nd', 3: 'rd' }[n % 10] || 'th';
+    return n + suffix;
+}
+
+function _tuningTargetFreqs(offsets, context) {
+    if (!Array.isArray(offsets) || !offsets.length) return [];
+    const ctx = context && typeof context === 'object' ? context : {};
+    const stringCount = effectiveStringCount(offsets, ctx);
+    const trimmed = offsets.slice(0, stringCount);
+    if (!trimmed.length) return [];
+    const isBass = isBassArrangement(ctx);
+    try {
+        return _tuningOffsetsToFreqs(trimmed, isBass);
+    } catch (_) {
+        return [];
+    }
+}
+
+// Flat vs sharp spelling. A caller that knows the preference can pass
+// ctx.useFlats; otherwise we infer from a flat-keyed tuning name. The v3
+// card/HUD pass "Custom Tuning" (raw offsets carry no key), so those default
+// to sharps unless an explicit useFlats is supplied.
+function _resolveTargetUseFlats(ctx) {
+    if (typeof ctx.useFlats === 'boolean') return ctx.useFlats;
+    return typeof ctx.tuningName === 'string' && /\b[A-G]b\b/.test(ctx.tuningName);
+}
+
+export function displayTuningTargetDetails(offsets, context) {
+    const ctx = context && typeof context === 'object' ? context : {};
+    const useFlats = _resolveTargetUseFlats(ctx);
+    const freqs = _tuningTargetFreqs(offsets, ctx);
+    return freqs.map((f, i) => {
+        const stringNumber = freqs.length - i;
+        const note = _noteNameFromFreq(f, useFlats);
+        const octaveNote = _octaveNoteFromFreq(f, useFlats);
+        return {
+            stringNumber,
+            note,
+            octaveNote,
+            title: _stringOrdinalLabel(stringNumber) + ' string: ' + octaveNote,
+        };
+    });
+}
+
+export function displayTuningTargets(offsets, context) {
+    const ctx = context && typeof context === 'object' ? context : {};
+    const useFlats = _resolveTargetUseFlats(ctx);
+    const freqs = _tuningTargetFreqs(offsets, ctx);
+    if (!freqs.length) return '';
+    return freqs.map((f) => _noteNameFromFreq(f, useFlats)).join(' ');
+}
+
+export function parseRawTuningOffsets(value) {
+    if (Array.isArray(value) && value.length) return value;
+    if (!value || typeof value !== 'string') return null;
+    const s = value.trim();
+    if (/^-?\d+(?: -?\d+)+$/.test(s)) {
+        return s.split(/\s+/).map((n) => Number(n));
+    }
+    if (/^-?\d+(?:,-?\d+)+$/.test(s)) {
+        return s.split(',').map((n) => Number(n));
+    }
+    return null;
+}

tests/js/autoplay_exit.test.js

@@ -14,10 +14,16 @@ const vm = require('node:vm');
 const { extractFunction } = require('./test_utils');
 
 const APP_JS = path.join(__dirname, '..', '..', 'static', 'app.js');
+// _autoplayExitEnabled was carved out into static/js/player-controls.js (R3a); the
+// auto-exit machinery around it (_clearAutoExit, holdAutoExit, _resolvePlayerOrigin)
+// stayed in app.js.
+const CONTROLS_JS = path.join(__dirname, '..', '..', 'static', 'js', 'player-controls.js');
 const SRC = fs.readFileSync(APP_JS, 'utf8');
+// the module is ESM; these sandboxes evaluate plain script text
+const CONTROLS_SRC = fs.readFileSync(CONTROLS_JS, 'utf8').replace(/^export /gm, '');
 
 function runEnabled(stored) {
-    const fnSrc = extractFunction(SRC, 'function _autoplayExitEnabled(');
+    const fnSrc = extractFunction(CONTROLS_SRC, 'function _autoplayExitEnabled(');
     const sandbox = {
         localStorage: {
             getItem: () => {

tests/js/highway_colors_facade.test.js

@@ -8,7 +8,9 @@ const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const path = require('node:path');
 
-const appJs = path.join(__dirname, '..', '..', 'static', 'app.js');
+// The highway string-colour manager was carved out of app.js into its own
+// module (R3a).
+const appJs = path.join(__dirname, '..', '..', 'static', 'js', 'highway-colors.js');
 
 function extractBlock(src, signature) {
     const start = src.indexOf(signature);

tests/js/highway_string_colors.test.js

@@ -13,7 +13,9 @@ const path = require('node:path');
 
 const highwayJs = path.join(__dirname, '..', '..', 'static', 'highway.js');
 const highway3dJs = path.join(__dirname, '..', '..', 'plugins', 'highway_3d', 'screen.js');
-const appJs = path.join(__dirname, '..', '..', 'static', 'app.js');
+// The highway string-colour manager was carved out of app.js into its own
+// module (R3a).
+const appJs = path.join(__dirname, '..', '..', 'static', 'js', 'highway-colors.js');
 
 // Brace-balanced extraction (same helper shape as highway_note_state.test.js).
 function extractBlock(src, signature) {
@@ -86,7 +88,7 @@ test('3D gem-body gradients follow the active palette (not hardcoded)', () => {
     assert.match(apply, /_recolorGemGradients\(\)/, '_applyPaletteToMaterials must recolor gems on palette change');
 });
 
-// ── Core color manager (static/app.js) ────────────────────────────────────
+// ── Core color manager (static/js/highway-colors.js) ──────────────────────
 
 test('app.js color manager name-maps to both highways, with identity no-op + builtin guard', () => {
     const src = fs.readFileSync(appJs, 'utf8');

tests/js/host_contract.test.js

@@ -0,0 +1,113 @@
+// The host-seam contract: the hooks the modules USE must be exactly the hooks
+// app.js WIRES.
+//
+// This is the test that makes the seam safe. static/js/host.js already throws at
+// runtime when an unwired hook is read — but a runtime throw only fires if the
+// broken path actually executes, and the entire danger of a host seam is the paths
+// that DON'T run in a smoke test. That is not hypothetical: the plugin loader's
+// seam defaulted a hook to `() => {}`, and a dropped wiring line would have left
+// the viz picker silently not refreshing with no test, boot check, or bot noticing.
+//
+// So this closes it statically. Rename a hook in app.js, drop a line from the
+// configureHost({…}) call, or typo a `host.foo` in a module, and CI fails — on a
+// path nobody ever ran.
+//
+// It is deliberately symmetric:
+//   * used but not wired  -> a latent crash (host.js would throw at runtime)
+//   * wired but not used  -> dead weight, and usually the fossil of a rename
+// Both fail.
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ROOT = path.join(__dirname, '..', '..');
+const APP_JS = path.join(ROOT, 'static', 'app.js');
+const JS_DIR = path.join(ROOT, 'static', 'js');
+
+// Strip comments, so prose about `host.foo` in a header block is not read as a call
+// site.
+//
+// NOTHING ELSE. An earlier version also tried to strip import statements (to stop
+// `from './host.js'` reading as a hook called `js`) and its `[\s\S]*?` spanned lines
+// and silently ate 14,000 characters of the file — including, in the bite test, the
+// very drift it was supposed to catch. A guard with a hole in it is worse than no
+// guard, because you trust it. The `host.js` path is excluded far more cheaply,
+// below, by refusing a match followed by a quote.
+function scrub(src) {
+    return src
+        .replace(/\/\*[\s\S]*?\*\//g, '')
+        .replace(/^\s*\/\/[^\n]*$/gm, '');
+}
+
+// `host.<name>` — but not `host.js'` from the `from './host.js'` import path, which is
+// the one string in these files that looks like a hook and isn't.
+//
+// The trailing class must forbid a WORD character as well as a quote. With only
+// `(?!['"])`, `host.js'` fails on `js` (a quote follows), then BACKTRACKS to `j` —
+// where the next char is `s`, not a quote — and happily reports a hook called `j`.
+// Forbidding `[\w$]` too leaves it nowhere to backtrack to.
+const HOOK_RE = /(?<![\w$.])host\.([A-Za-z_$][\w$]*)(?![\w$'"])/g;
+
+/** Every `host.<name>` referenced by a carved module. */
+function hooksUsed() {
+    const used = new Map();   // name -> [files]
+    for (const file of fs.readdirSync(JS_DIR)) {
+        if (!file.endsWith('.js') || file === 'host.js') continue;
+        const raw = fs.readFileSync(path.join(JS_DIR, file), 'utf8');
+        if (!/from\s+'\.\/host\.js'/.test(raw)) continue;
+        for (const m of scrub(raw).matchAll(HOOK_RE)) {
+            if (!used.has(m[1])) used.set(m[1], []);
+            used.get(m[1]).push(file);
+        }
+    }
+    return used;
+}
+
+/** Every hook app.js passes to configureHost({ … }). */
+function hooksWired() {
+    const src = scrub(fs.readFileSync(APP_JS, 'utf8'));
+    // NB the closing brace is INDENTED (the call sits inside the boot function), so
+    // anchoring on `\n});` at column 0 runs straight past it and swallows the next
+    // object literal in the file — which is how this first read 77 "hooks", most of
+    // them app.js's window contract.
+    const call = src.match(/configureHost\(\{([\s\S]*?)\n\s*\}\);/);
+    if (!call) return null;   // no seam wired yet — fine until there is one
+    const wired = new Set();
+    for (const m of call[1].matchAll(/(?:^|,)\s*([A-Za-z_$][\w$]*)\s*(?=[,:}]|$)/gm)) {
+        wired.add(m[1]);
+    }
+    return wired;
+}
+
+test('every host.<hook> a module uses is wired by app.js', () => {
+    const used = hooksUsed();
+    if (used.size === 0) return;                      // no consumers yet
+    const wired = hooksWired();
+    assert.ok(wired, 'modules import ./host.js but app.js never calls configureHost({ … })');
+
+    const missing = [...used.keys()]
+        .filter((h) => !wired.has(h))
+        .map((h) => `${h} (used in ${used.get(h).join(', ')})`);
+
+    assert.deepEqual(
+        missing, [],
+        'these hooks are read by a module but never wired by app.js — they would throw at runtime, '
+        + 'on whatever path happens to reach them',
+    );
+});
+
+test('every hook app.js wires is actually used by a module', () => {
+    const wired = hooksWired();
+    if (!wired || wired.size === 0) return;
+    const used = hooksUsed();
+
+    const unused = [...wired].filter((h) => !used.has(h));
+
+    assert.deepEqual(
+        unused, [],
+        'these hooks are wired by app.js but no module reads them — dead weight, and usually '
+        + 'the fossil of a rename that left the other half behind',
+    );
+});

tests/js/juce_engine_reroute.test.js

@@ -84,7 +84,11 @@ function makeSandbox({ isAudioRunning, loadBackingTrack, outputType = 'Windows A
             json: () => Promise.resolve({ path: '/local/song.ogg' }),
         }),
         document: { hidden: false },
-        isPlaying: true,
+        // `isPlaying` moved onto the shared player-state container so a carved module
+        // can WRITE it (an imported binding is read-only). The sliced code now reads and
+        // writes S.isPlaying, so the sandbox provides the same container — the
+        // assertions below are unchanged.
+        S: { isPlaying: true, lastAudioTime: 0 },
         audio,
         jucePlayer,
         __calls: calls,

tests/js/loop_api.test.js

@@ -11,11 +11,16 @@ const fs = require('node:fs');
 const path = require('node:path');
 const vm = require('node:vm');
 
+// The A-B loop was carved out of app.js into its own module (R3a). The
+// window.feedBack API surface it is published through stayed in app.js.
+const LOOPS_JS = path.join(__dirname, '..', '..', 'static', 'js', 'loops.js');
 const APP_JS = path.join(__dirname, '..', '..', 'static', 'app.js');
 
-function extractFunction(src, signature) {
+function extractFunction(rawSrc, signature) {
+    // loops.js is an ES module; the vm sandbox evaluates plain script text.
+    const src = rawSrc.replace(/^export /gm, '');
     const start = src.indexOf(signature);
-    if (start === -1) throw new Error(`extractFunction: '${signature}' not found in app.js`);
+    if (start === -1) throw new Error(`extractFunction: '${signature}' not found in static/js/loops.js`);
     let scan = start + signature.length;
     if (src[scan] === '(') {
         let parenDepth = 1;
@@ -44,10 +49,18 @@ function buildSandbox() {
     const seekCalls = [];
     const sectionPracticeModeCalls = [];
     const transportEvents = [];
+    // clearLoop() used to zero section-practice's three selection scalars by hand.
+    // They now live in static/js/section-practice.js, which owns them, so clearLoop
+    // calls its exported resetSelection() instead. This is a SPY, not a stub — the
+    // test below still asserts the reset happens, it just asserts it through the
+    // seam rather than by reaching into someone else's state.
+    const resetSelectionCalls = [];
     const sandbox = {
         seekCalls,
         sectionPracticeModeCalls,
         transportEvents,
+        resetSelectionCalls,
+        resetSelection: () => resetSelectionCalls.push(true),
         // Mutable state (declared as `var` in eval prelude so it lives on
         // the sandbox global and the extracted functions can read/write).
         // The actual values are set below.
@@ -81,6 +94,7 @@ function buildSandbox() {
         // updateLoopUI references formatTime for the label; we don't
         // assert on the label text in these tests, so a stub is enough.
         formatTime: (s) => String(s),
+        _updateEditRegionBtn: () => {},
         window: {
             feedBack: {
                 playback: {
@@ -89,6 +103,19 @@ function buildSandbox() {
             },
         },
     };
+    // The loop module reaches back into app.js through the host seam
+    // (static/js/host.js), so the extracted bodies call host._audioSeek(),
+    // host._audioTime(), and so on. Point the seam at the SAME spies the sandbox
+    // already had: the assertions below are unchanged, they just travel through the
+    // indirection the real code now uses.
+    sandbox.host = {
+        _audioSeek: (...a) => sandbox._audioSeek(...a),
+        _audioTime: () => sandbox._audioTime(),
+        formatTime: (...a) => sandbox.formatTime(...a),
+        _updateEditRegionBtn: () => sandbox._updateEditRegionBtn(),
+        currentFilename: () => 'test-song.sloppak',
+        startCountIn: () => {},
+    };
     vm.createContext(sandbox);
     return sandbox;
 }
@@ -121,7 +148,7 @@ function loadFunctions(sandbox, src) {
 }
 
 test('setLoop mutates loopA/loopB and seeks to A', async () => {
-    const src = fs.readFileSync(APP_JS, 'utf8');
+    const src = fs.readFileSync(LOOPS_JS, 'utf8');
     const sandbox = buildSandbox();
     loadFunctions(sandbox, src);
 
@@ -137,7 +164,7 @@ test('setLoop mutates loopA/loopB and seeks to A', async () => {
 test('setLoop returns false and leaves loopA/loopB untouched on cancelled seek', async () => {
     // Plugin-facing contract: cancelled seek (teardown gen bump) returns
     // false; the loop is NOT armed.
-    const src = fs.readFileSync(APP_JS, 'utf8');
+    const src = fs.readFileSync(LOOPS_JS, 'utf8');
     const sandbox = buildSandbox();
     sandbox._audioSeek = () => Promise.resolve({ completed: false, from: NaN, to: NaN });
     loadFunctions(sandbox, src);
@@ -154,7 +181,7 @@ test('setLoop returns false and leaves loopA/loopB untouched on cancelled seek',
 test('setLoop returns false and leaves loopA/loopB untouched on off-target landing', async () => {
     // JUCE rollback / HTML5 clamp: completed:true but to drifts > 50ms
     // from the requested a. The loop is NOT armed.
-    const src = fs.readFileSync(APP_JS, 'utf8');
+    const src = fs.readFileSync(LOOPS_JS, 'utf8');
     const sandbox = buildSandbox();
     sandbox._audioSeek = (s) => Promise.resolve({ completed: true, from: 0, to: s + 0.5 });
     loadFunctions(sandbox, src);
@@ -172,7 +199,7 @@ test('setLoop coerces string inputs (parseFloat-style)', async () => {
     // loadSavedLoop passes parseFloat(dataset.start) — but the dataset
     // values may already be strings. Number() coercion in setLoop must
     // accept finite numeric strings.
-    const src = fs.readFileSync(APP_JS, 'utf8');
+    const src = fs.readFileSync(LOOPS_JS, 'utf8');
     const sandbox = buildSandbox();
     loadFunctions(sandbox, src);
 
@@ -183,7 +210,7 @@ test('setLoop coerces string inputs (parseFloat-style)', async () => {
 });
 
 test('setLoop rejects non-finite inputs', async () => {
-    const src = fs.readFileSync(APP_JS, 'utf8');
+    const src = fs.readFileSync(LOOPS_JS, 'utf8');
     const sandbox = buildSandbox();
     loadFunctions(sandbox, src);
 
@@ -193,7 +220,7 @@ test('setLoop rejects non-finite inputs', async () => {
 });
 
 test('setLoop rejects b <= a', async () => {
-    const src = fs.readFileSync(APP_JS, 'utf8');
+    const src = fs.readFileSync(LOOPS_JS, 'utf8');
     const sandbox = buildSandbox();
     loadFunctions(sandbox, src);
 
@@ -201,8 +228,8 @@ test('setLoop rejects b <= a', async () => {
     await assert.rejects(() => sandbox.__setLoop(10, 5), /b > a/);
 });
 
-test('clearLoop resets loopA/loopB to null', async () => {
-    const src = fs.readFileSync(APP_JS, 'utf8');
+test('clearLoop resets loopA/loopB to null (and asks section-practice to drop its selection)', async () => {
+    const src = fs.readFileSync(LOOPS_JS, 'utf8');
     const sandbox = buildSandbox();
     loadFunctions(sandbox, src);
 
@@ -211,6 +238,11 @@ test('clearLoop resets loopA/loopB to null', async () => {
     const { loopA, loopB } = sandbox.__getLoop();
     assert.equal(loopA, null);
     assert.equal(loopB, null);
+    assert.equal(
+        sandbox.resetSelectionCalls.length, 1,
+        'clearLoop must ask section-practice to drop its selection (it used to zero the '
+        + 'scalars by hand; the module owns them now)',
+    );
     assert.equal(sandbox.sectionPracticeModeCalls.length, 1);
     assert.equal(sandbox.sectionPracticeModeCalls[0].on, false);
     // Field-wise: vm-context objects break deepStrictEqual across realms.
@@ -218,7 +250,7 @@ test('clearLoop resets loopA/loopB to null', async () => {
 });
 
 test('loop helpers emit transport snapshots by default and can suppress adapter echoes', async () => {
-    const src = fs.readFileSync(APP_JS, 'utf8');
+    const src = fs.readFileSync(LOOPS_JS, 'utf8');
     const sandbox = buildSandbox();
     loadFunctions(sandbox, src);
 
@@ -256,7 +288,7 @@ test('loadSavedLoop funnels through setLoop (no duplicated UI mutation)', () =>
     // re-implementing the loopA/loopB assignment. Catches a future drift
     // where someone "fixes" loadSavedLoop and forgets to keep setLoop in
     // sync.
-    const src = fs.readFileSync(APP_JS, 'utf8');
+    const src = fs.readFileSync(LOOPS_JS, 'utf8');
     const fn = extractFunction(src, 'async function loadSavedLoop(');
     assert.match(fn, /await\s+setLoop\(/, 'loadSavedLoop must call setLoop');
     // The pre-refactor body assigned loopA = parseFloat(...) directly;

tests/js/loop_restart.test.js

@@ -14,7 +14,8 @@ const fs = require('node:fs');
 const path = require('node:path');
 const vm = require('node:vm');
 
-const APP_JS = path.join(__dirname, '..', '..', 'static', 'app.js');
+// startCountIn was carved out of app.js into its own module (R3a).
+const APP_JS = path.join(__dirname, '..', '..', 'static', 'js', 'count-in.js');
 
 // Pull a function body by declaration prefix (e.g. `async function startCountIn`)
 // and brace-matching to the closing brace. Skips an optional `( ... )` param
@@ -55,8 +56,10 @@ function buildSandbox() {
         loopA: 10,
         loopB: 20,
         _countingIn: false,
-        isPlaying: false,
-        lastAudioTime: 0,
+        // isPlaying / lastAudioTime moved onto the shared player-state container
+        // (static/js/player-state.js) so a carved module can WRITE them — an imported
+        // binding is read-only. Same values, same assertions, one indirection.
+        S: { isPlaying: false, lastAudioTime: 0 },
 
         // Browser-ish globals.
         performance: { now: () => Date.now() },
@@ -109,12 +112,23 @@ function buildSandbox() {
         __emitCalls: emitCalls,
         queueMicrotask,
     };
+    // startCountIn was carved into static/js/count-in.js and now reaches back into
+    // app.js through the host seam (static/js/host.js). Point the seam at the SAME
+    // stubs the sandbox already had: the assertions below are unchanged, they just
+    // travel through the indirection the real code now uses.
+    sandbox.host = {
+        _audioSeek: (...a) => sandbox._audioSeek(...a),
+        setPlayButtonState: () => {},
+        _songEventPayload: () => ({}),
+        togglePlay: () => {},
+        jucePlayer: () => sandbox.jucePlayer,
+    };
     vm.createContext(sandbox);
     return sandbox;
 }
 
 test('loop:restart fires once when wrap path runs', async () => {
-    const src = fs.readFileSync(APP_JS, 'utf8');
+    const src = fs.readFileSync(APP_JS, 'utf8').replace(/^export /gm, '');
     const startCountInSrc = extractFunction(src, 'async function startCountIn');
 
     // Sanity check: the change under test is present at all. Catches
@@ -135,8 +149,7 @@ test('loop:restart fires once when wrap path runs', async () => {
         var _countInGen = 0;
         var _countInTimer = null;
         var _countInRaf = 0;
-        var isPlaying = false;
-        var lastAudioTime = 0;
+        var S = { isPlaying: false, lastAudioTime: 0 };
         ${startCountInSrc}
         globalThis.__startCountIn = startCountIn;
     `;
@@ -166,7 +179,7 @@ test('loop:restart aborts when seek lands far from loopA (JUCE rollback)', async
     // _audioSeek resolves with completed:true but r.to !== loopA. The
     // wrap handler must abort instead of running beginCount on the wrong
     // position and emitting a misleading loop:restart.
-    const src = fs.readFileSync(APP_JS, 'utf8');
+    const src = fs.readFileSync(APP_JS, 'utf8').replace(/^export /gm, '');
     const startCountInSrc = extractFunction(src, 'async function startCountIn');
 
     const sandbox = buildSandbox();
@@ -180,8 +193,7 @@ test('loop:restart aborts when seek lands far from loopA (JUCE rollback)', async
         var _countInGen = 0;
         var _countInTimer = null;
         var _countInRaf = 0;
-        var isPlaying = false;
-        var lastAudioTime = 0;
+        var S = { isPlaying: false, lastAudioTime: 0 };
         ${startCountInSrc}
         globalThis.__startCountIn = startCountIn;
         globalThis.__getCountingIn = () => _countingIn;
@@ -202,7 +214,7 @@ test('count-in cancellation token bails delayed callbacks (rewindStep + tick)',
     // teardown can interrupt an in-flight count-in. Behavioral simulation
     // of timer cancellation is out of scope for the static extractor; this
     // verifies the contract is wired into the source.
-    const src = fs.readFileSync(APP_JS, 'utf8');
+    const src = fs.readFileSync(APP_JS, 'utf8').replace(/^export /gm, '');
     const fn = extractFunction(src, 'async function startCountIn');
     // Captures gen at entry
     assert.match(fn, /const gen = _countInGen/, 'startCountIn must capture _countInGen at entry');
@@ -218,7 +230,7 @@ test('loop:restart fires after highway.setTime, before beginCount', () => {
     // Source-order assertion on the A-B wrap path only. Section-practice
     // `opts.immediate` also emits loop:restart but is a separate entry path;
     // the wrap handler lives inside the `_audioSeek(loopA, 'loop-wrap')` then.
-    const src = fs.readFileSync(APP_JS, 'utf8');
+    const src = fs.readFileSync(APP_JS, 'utf8').replace(/^export /gm, '');
     const fn = extractFunction(src, 'async function startCountIn');
     const wrapMarker = "_audioSeek(loopA, 'loop-wrap')";
     const wrapStart = fn.indexOf(wrapMarker);

tests/js/play_button_reroute_guard.test.js

@@ -29,8 +29,11 @@ async function runTogglePlayRejecting({ rerouteInProgress }) {
     const buttonStates = [];
     const sandbox = {
         console: { log() {}, warn() {}, error() {} },
-        // not-playing -> togglePlay takes the HTML5 play branch
-        isPlaying: false,
+        // not-playing -> togglePlay takes the HTML5 play branch.
+        // isPlaying / lastAudioTime moved onto the shared player-state container
+        // (static/js/player-state.js) so a carved module can WRITE them — an imported
+        // binding is read-only. Same values, same assertions, one indirection.
+        S: { isPlaying: false, lastAudioTime: 0 },
         _audioSeekGen: 0,
         _playAttemptGen: 0,
         setPlayButtonState(v) { buttonStates.push(v); },
@@ -51,7 +54,7 @@ async function runTogglePlayRejecting({ rerouteInProgress }) {
     vm.createContext(sandbox);
     vm.runInContext(TOGGLE_PLAY_SRC, sandbox, { filename: 'app.js#togglePlay' });
     await vm.runInContext('togglePlay()', sandbox);
-    return { buttonStates, isPlaying: sandbox.isPlaying };
+    return { buttonStates, isPlaying: sandbox.S.isPlaying };
 }
 
 test('reroute-aborted play() leaves the button on Pause (isPlaying stays true)', async () => {

tests/js/playback_app_adapter.test.js

@@ -84,5 +84,8 @@ test('playback adapter suppresses duplicate HTML5 pause events before emitting c
     const src = fs.readFileSync(APP_JS, 'utf8');
     const fn = extractFunction(src, 'function _installPlaybackTransportAdapter()');
 
-    assert.match(fn, /if \(!window\._juceMode && wasPlaying\) \{\s*isPlaying = false;\s*window\.feedBack\.isPlaying = false;\s*audio\.pause\(\);\s*_markPlaybackPaused\(\);\s*\}/);
+    // isPlaying moved onto the shared player-state container so a carved module can
+    // WRITE it (an imported binding is read-only). window.feedBack.isPlaying — the
+    // public mirror — is unchanged.
+    assert.match(fn, /if \(!window\._juceMode && wasPlaying\) \{\s*S\.isPlaying = false;\s*window\.feedBack\.isPlaying = false;\s*audio\.pause\(\);\s*_markPlaybackPaused\(\);\s*\}/);
 });

tests/js/section_practice_dismiss.test.js

@@ -15,9 +15,10 @@ const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const path = require('node:path');
 
-const src = fs.readFileSync(path.join(__dirname, '..', '..', 'static', 'app.js'), 'utf8');
+// _installSectionPracticeDismiss was carved out of app.js into its own module (R3a).
+const src = fs.readFileSync(path.join(__dirname, '..', '..', 'static', 'js', 'section-practice.js'), 'utf8');
 const m = src.match(/function _installSectionPracticeDismiss\s*\(\)\s*\{[\s\S]*?\n\}/);
-assert.ok(m, '_installSectionPracticeDismiss() not found in static/app.js');
+assert.ok(m, '_installSectionPracticeDismiss() not found in static/js/section-practice.js');
 const body = m[0];
 
 test('the outside-click dismiss binds in the CAPTURE phase', () => {

tests/js/song_credits_overlay.test.js

@@ -14,8 +14,9 @@ const vm = require('node:vm');
 
 const { extractFunction } = require('./test_utils');
 
-const APP_JS = path.join(__dirname, '..', '..', 'static', 'app.js');
-const SRC = fs.readFileSync(APP_JS, 'utf8');
+// the song-credits overlay was carved out of app.js into its own module (R3a).
+const APP_JS = path.join(__dirname, '..', '..', 'static', 'js', 'count-in.js');
+const SRC = fs.readFileSync(APP_JS, 'utf8').replace(/^export /gm, '');
 
 // Minimal fake DOM element: records className, children, and textContent.
 // Setting textContent clears children (matching real DOM) so we can assert

tests/js/song_restart.test.js

@@ -19,7 +19,9 @@ function buildSandbox({ loopA = null, loopB = null, isPlaying = false } = {}) {
     const sandbox = {
         loopA,
         loopB,
-        isPlaying,
+        // isPlaying moved onto the shared player-state container so a carved module can
+        // WRITE it (an imported binding is read-only). Same value, same assertions.
+        S: { isPlaying, lastAudioTime: 0 },
         __cancelCountInCalls: 0,
         __seekCalls: [],
         __startCountInCalls: [],
@@ -42,7 +44,7 @@ function buildSandbox({ loopA = null, loopB = null, isPlaying = false } = {}) {
         },
         __togglePlay() {
             sandbox.__togglePlayCalls++;
-            sandbox.isPlaying = true;
+            sandbox.S.isPlaying = true;
             return Promise.resolve();
         },
     };
@@ -53,7 +55,7 @@ function buildSandbox({ loopA = null, loopB = null, isPlaying = false } = {}) {
 function loadRestart(sandbox, src, { audioSeekImpl } = {}) {
     const restartSrc = extractFunction(src, 'async function restartCurrentSong(');
     const code = `
-        var isPlaying = ${sandbox.isPlaying};
+        var S = { isPlaying: ${sandbox.S.isPlaying}, lastAudioTime: 0 };
         function _cancelCountIn() { __cancelCountInCalls++; }
         async function _audioSeek(s, reason) {
             return (${audioSeekImpl || '__audioSeek'})(s, reason);

tests/js/song_seek.test.js

@@ -77,7 +77,10 @@ function loadFunctions(sandbox, src) {
         // _audioSeek now syncs the jump-fix tracker so far seeks don't
         // trigger an immediate revert; declare it here so the sandbox
         // assignment lands on a real binding rather than an implicit global.
-        let lastAudioTime = 0;
+        // lastAudioTime moved onto the shared player-state container
+        // (static/js/player-state.js) so a carved module can WRITE it — an imported
+        // binding is read-only. The sliced code writes S.lastAudioTime now.
+        let S = { isPlaying: false, lastAudioTime: 0 };
         // _audioSeek wraps jucePlayer.seek in a timeout race; pull in the
         // helper + constant. Tests can override jucePlayer.seek to vary
         // behavior; the timeout (2 s) is well above any test setTimeout.

tests/js/speed_reset.test.js

@@ -5,6 +5,9 @@ const path = require('node:path');
 const vm = require('node:vm');
 
 const APP_JS = path.join(__dirname, '..', '..', 'static', 'app.js');
+// The speed controls were carved out into static/js/player-controls.js (R3a); playSong,
+// which resets them on a new song, stayed in app.js. This test spans both.
+const CONTROLS_JS = path.join(__dirname, '..', '..', 'static', 'js', 'player-controls.js');
 
 function extractFunction(src, signature) {
     const start = src.indexOf(signature);
@@ -130,20 +133,30 @@ function extractConstLine(src, name) {
 
 function loadPlaySong(sandbox) {
     const src = fs.readFileSync(APP_JS, 'utf8');
-    const resetHelper = src.includes('function _resetPlaybackSpeedForNewSong')
-        ? extractFunction(src, 'function _resetPlaybackSpeedForNewSong')
+    // the module is ESM; the vm sandbox evaluates plain script text
+    const controls = fs.readFileSync(CONTROLS_JS, 'utf8').replace(/^export /gm, '');
+    const resetHelper = controls.includes('function _resetPlaybackSpeedForNewSong')
+        ? extractFunction(controls, 'function _resetPlaybackSpeedForNewSong')
         : '';
-    const speedPresetHelpers = src.includes('function _updateSpeedPresetButtons')
+    const speedPresetHelpers = controls.includes('function _updateSpeedPresetButtons')
         ? `
-        ${extractConstLine(src, 'SPEED_PRESET_PCTS')}
-        ${extractConstLine(src, 'SPEED_SNAP_THRESHOLD')}
-        ${extractFunction(src, 'function _speedPresetPctFromActive')}
-        ${extractFunction(src, 'function _updateSpeedPresetButtons')}
+        ${extractConstLine(controls, 'SPEED_PRESET_PCTS')}
+        ${extractConstLine(controls, 'SPEED_SNAP_THRESHOLD')}
+        ${extractFunction(controls, 'function _speedPresetPctFromActive')}
+        ${extractFunction(controls, 'function _updateSpeedPresetButtons')}
         `
         : '';
     const code = `
         var artAbortController = null;
-        var isPlaying = true;
+        // isPlaying moved onto the shared player-state container so a carved module can
+        // WRITE it (an imported binding is read-only). NB window.feedBack.isPlaying — the
+        // public mirror stubbed above — is a different thing and is unchanged.
+        var S = { isPlaying: true, lastAudioTime: 0 };
+        // The speed controls reach app.js through the host seam (static/js/host.js).
+        // Route it at the sandbox's EXISTING handleSliderInput spy — a fresh stub would
+        // swallow the call and the assertion below (which checks the slider was actually
+        // refreshed) would pass vacuously.
+        var host = { handleSliderInput: (el) => handleSliderInput(el) };
         var currentFilename = null;
         var _playerOriginScreen = null;
         var _pendingAutostart = false;
@@ -163,7 +176,7 @@ function loadPlaySong(sandbox) {
         function _scheduleSectionPracticeRetries() {}
         function loadSavedLoops() {}
         function _songEventPayload() { return { time: 7, audioT: 7, chartT: 7, perfNow: 7 }; }
-        ${extractFunction(src, 'function setSpeed')}
+        ${extractFunction(controls, 'function setSpeed')}
         ${speedPresetHelpers}
         ${resetHelper}
         ${extractFunction(src, 'async function playSong')}

tests/js/tuner_auto_open.test.js

@@ -7,20 +7,23 @@ const path = require('node:path');
 const vm = require('node:vm');
 
 const APP_JS = path.join(__dirname, '..', '..', 'static', 'app.js');
+// The tuning-display helpers were carved out of app.js into their own module (R3a);
+// the autoplay-gate test below still reads app.js.
+const TUNING_JS = path.join(__dirname, '..', '..', 'static', 'js', 'tuning-display.js');
 const TUNER_SCREEN_JS = path.join(__dirname, '..', '..', 'plugins', 'tuner', 'screen.js');
 const TUNING_UTILS_JS = path.join(__dirname, '..', '..', 'plugins', 'tuner', 'utils', 'tuning-utils.js');
 const TUNER_UI_JS = path.join(__dirname, '..', '..', 'plugins', 'tuner', 'utils', 'ui.js');
 
 function loadTuningHelpers() {
-    const src = fs.readFileSync(APP_JS, 'utf8');
-    const start = src.indexOf('function isBassArrangement(');
-    const endMarker = 'window.feedBack.parseRawTuningOffsets = parseRawTuningOffsets;';
-    const end = src.indexOf(endMarker);
-    if (start === -1 || end === -1) throw new Error('tuning helper block not found in app.js');
+    const src = fs.readFileSync(TUNING_JS, 'utf8');
+    // The module is nothing BUT the tuning helpers now, so there is no block to
+    // slice out — take it whole. `export` is stripped so the vm sandbox can still
+    // evaluate it as a plain script (the window.* contract lives in app.js).
+    const body = src.replace(/^export /gm, '');
     const sandbox = { window: { feedBack: {} }, exports: {} };
     vm.createContext(sandbox);
     vm.runInContext(
-        src.slice(start, end + endMarker.length),
+        body,
         sandbox
     );
     return sandbox.window.feedBack;

tests/js/tuning_display.test.js

@@ -6,7 +6,8 @@ const fs = require('node:fs');
 const path = require('node:path');
 const vm = require('node:vm');
 
-const APP_JS = path.join(__dirname, '..', '..', 'static', 'app.js');
+// The tuning-display helpers were carved out of app.js into their own module (R3a).
+const APP_JS = path.join(__dirname, '..', '..', 'static', 'js', 'tuning-display.js');
 const HIGHWAY_JS = path.join(__dirname, '..', '..', 'static', 'highway.js');
 const V3_HTML = path.join(__dirname, '..', '..', 'static', 'v3', 'index.html');
 

tests/js/tuning_targets.test.js

@@ -6,7 +6,8 @@ const fs = require('node:fs');
 const path = require('node:path');
 const vm = require('node:vm');
 
-const APP_JS = path.join(__dirname, '..', '..', 'static', 'app.js');
+// The tuning-display helpers were carved out of app.js into their own module (R3a).
+const APP_JS = path.join(__dirname, '..', '..', 'static', 'js', 'tuning-display.js');
 const HIGHWAY_JS = path.join(__dirname, '..', '..', 'static', 'highway.js');
 const TUNER_UI_JS = path.join(__dirname, '..', '..', 'plugins', 'tuner', 'utils', 'ui.js');
 const TUNER_SCREEN_JS = path.join(__dirname, '..', '..', 'plugins', 'tuner', 'screen.js');
@@ -14,14 +15,14 @@ const V3_HTML = path.join(__dirname, '..', '..', 'static', 'v3', 'index.html');
 
 function loadTuningHelpers() {
     const src = fs.readFileSync(APP_JS, 'utf8');
-    const start = src.indexOf('function isBassArrangement(');
-    const endMarker = 'window.feedBack.parseRawTuningOffsets = parseRawTuningOffsets;';
-    const end = src.indexOf(endMarker);
-    if (start === -1 || end === -1) throw new Error('tuning helper block not found in app.js');
+    // The module is nothing BUT the tuning helpers now, so there is no block to
+    // slice out — take it whole. `export` is stripped so the vm sandbox can still
+    // evaluate it as a plain script (the window.* contract lives in app.js).
+    const body = src.replace(/^export /gm, '');
     const sandbox = { window: { feedBack: {} }, exports: {} };
     vm.createContext(sandbox);
     vm.runInContext(
-        src.slice(start, end + endMarker.length) + '\n'
+        body + '\n'
         + 'exports.displayTuningTargets = displayTuningTargets;\n'
         + 'exports.displayTuningTargetDetails = displayTuningTargetDetails;\n'
         + 'exports.isBassArrangement = isBassArrangement;\n'

tests/js/v3_songs_tuning.test.js

@@ -7,7 +7,8 @@ const path = require('node:path');
 const vm = require('node:vm');
 
 const SONGS_JS = path.join(__dirname, '..', '..', 'static', 'v3', 'songs.js');
-const APP_JS = path.join(__dirname, '..', '..', 'static', 'app.js');
+// The tuning-display helpers were carved out of app.js into their own module (R3a).
+const APP_JS = path.join(__dirname, '..', '..', 'static', 'js', 'tuning-display.js');
 
 function extractBlock(src, startMarker) {
     const start = src.indexOf(startMarker);
@@ -27,14 +28,14 @@ function extractBlock(src, startMarker) {
 
 function loadTuningHelpers() {
     const src = fs.readFileSync(APP_JS, 'utf8');
-    const start = src.indexOf('function _looksLikeRawTuningOffsets(');
-    const endMarker = 'window.feedBack.parseRawTuningOffsets = parseRawTuningOffsets;';
-    const end = src.indexOf(endMarker);
-    if (start === -1 || end === -1) throw new Error('tuning helpers not found');
+    // The module is nothing BUT the tuning helpers now, so there is no block to
+    // slice out — take it whole. `export` is stripped so the vm sandbox can still
+    // evaluate it as a plain script (the window.* contract lives in app.js).
+    const body = src.replace(/^export /gm, '');
     const sandbox = { window: { feedBack: {} }, exports: {} };
     vm.createContext(sandbox);
     vm.runInContext(
-        src.slice(start, end + endMarker.length) + '\n'
+        body + '\n'
         + 'exports.displayTuningName = displayTuningName;\n'
         + 'exports.displayTuningTargets = displayTuningTargets;\n'
         + 'exports.parseRawTuningOffsets = parseRawTuningOffsets;',

tests/test_plugin_runtime_idempotence.py

@@ -186,7 +186,9 @@ def test_app_event_bus_dispatches_locally_and_preserves_juce_stop_state():
     source = (ROOT / "static" / "app.js").read_text(encoding="utf-8")
 
     assert "this.dispatchEvent(new CustomEvent(event, { detail }))" in source
-    assert "const hadPlayableSong = !!audio.src || !!window._juceAudioUrl || isPlaying" in source
+    # `isPlaying` moved onto the shared player-state container (static/js/player-state.js)
+    # so a carved module can WRITE it — an imported binding is read-only.
+    assert "const hadPlayableSong = !!audio.src || !!window._juceAudioUrl || S.isPlaying" in source
     assert "sm.emit('song:resume', payload)" in source
     assert "window.feedBack.emit('song:resume', payload)" in source