refactor(app): carve the player controls out of app.js (R3a)

static/js/player-controls.js (229) — the speed + mastery sliders and the four
playback-preference reads (autoplay-exit, up-next, countdown-before-song,
confirm-exit). Bodies VERBATIM. app.js 7,914 → 7,727.

The fourth slice out of the strongly-connected core, and by far the easiest: ONE
hook (handleSliderInput) and NO shared mutable state. The three groups are the same
surface — the controls under the highway — and the preference reads are the
one-line localStorage lookups 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.

Zero missed members on the first build (the no-undef pass was clean), which is the
first time that has happened in this phase.

TWO HARNESSES ARE SPLIT, and both taught something:

  * speed_reset spans BOTH files — playSong (app.js) resets the speed controls
    (module). Its presence GUARDS still read `src.includes('function setSpeed')`
    against app.js, so once the code moved they silently evaluated FALSE and the
    helpers were quietly dropped from the sandbox. A guard that disables itself is
    worse than no guard. Repointed at the file the code actually lives in.

  * Its `host.handleSliderInput` stub had to route at the sandbox's EXISTING spy,
    not a fresh `() => {}`. The test asserts the slider was actually refreshed
    (`deepEqual(__sliderInputs, ['speed-slider'])`); a fresh stub swallows the call
    and the assertion passes VACUOUSLY. Same failure mode as a no-op host default —
    the thing this whole seam design exists to prevent.

  * autoplay_exit is split too: _autoplayExitEnabled moved, but the auto-exit
    machinery around it (_clearAutoExit, holdAutoExit, _resolvePlayerOrigin) stayed.

VERIFIED. A/B against origin/main in two browsers, real song: setSpeed(0.75) ->
playbackRate 0.75; applySpeedPreset(100) -> 1; the speed slider; setMastery;
setAutoplayExit / setCountdownBeforeSong / setShowUpNext — IDENTICAL, zero page errors.

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

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

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/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,34 @@
+// 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,
+};

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/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;
@@ -89,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: {
@@ -97,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;
 }
@@ -129,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);
 
@@ -145,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);
@@ -162,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);
@@ -180,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);
 
@@ -191,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);
 
@@ -201,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);
 
@@ -210,7 +229,7 @@ test('setLoop rejects b <= a', async () => {
 });
 
 test('clearLoop resets loopA/loopB to null (and asks section-practice to drop its selection)', async () => {
-    const src = fs.readFileSync(APP_JS, 'utf8');
+    const src = fs.readFileSync(LOOPS_JS, 'utf8');
     const sandbox = buildSandbox();
     loadFunctions(sandbox, src);
 
@@ -231,7 +250,7 @@ test('clearLoop resets loopA/loopB to null (and asks section-practice to drop it
 });
 
 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);
 
@@ -269,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/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/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