refactor(app): carve count-in (and the song-credits overlay) out of app.js (R3a)

static/js/count-in.js (389) — bodies VERBATIM. app.js 8,223 → 7,913.
The third slice out of the strongly-connected core, and the first that WRITES
shared state rather than only reading it. #889's container is what makes it possible.

  imports: loops (setLoop/loopA/loopB — a count-in inside an A-B loop must begin at
           A), audio-el, player-state, host
  hooks  : _audioSeek, setPlayButtonState, _songEventPayload, togglePlay + a
           jucePlayer getter
  Nothing imports count-in back — app.js and section-practice both reach it through
  the seam — so the graph stays acyclic.

app.js's autoplay path used to reach IN and set this module's credits timers itself
(_creditsTimer, _creditsHideOnPlay) and read _countingIn. It cannot now, and should
not have to, so the module exports the OPERATIONS instead — armCreditsHideOnPlay(),
scheduleCreditsHide(), holdCreditsThen(start), isCountingIn() — and owns its own
timer invariants. Third time this has happened (section-practice's resetSelection,
loops' state) and each time the constraint produced better code than was there
before: the module keeps its own promises instead of trusting a caller 6,000 lines
away to zero the right fields.

THE no-undef GATE FOUND FIVE MISSED MEMBERS, one at a time: showSongCreditsOverlay
and startSongCountIn (my name regex matched startCountIn, not startSongCountIn),
then _creditLineLabel, _CREDITS_MAX_MS, and _CREDIT_ROLE_VERBS. A call-graph closure
does not see a const table; only the undefined-symbol pass does.

AND A REAL TRAP: I computed _CREDIT_ROLE_VERBS's span against the ALREADY-MODIFIED
app.js and applied it to the clean one — the line numbers had drifted, so the slice
would have cut somewhere else entirely. Recomputed every span from the clean file
with acorn. Never carry line numbers across an edit.

VERIFIED. A/B against origin/main in two browsers with a real song: playback state,
the public feedBack.isPlaying mirror, audio position, cancel-count-in — IDENTICAL,
zero page errors. Unit coverage moved with the code: loop_restart's count-in
cancellation-token test and the 5 song_credits_overlay tests now read count-in.js;
loop_restart's sandbox gains a `host` object routed at its EXISTING stubs, so every
assertion is unchanged.

HONEST LIMIT: I could not make the count-in OVERLAY actually render headlessly —
its autoplay path needs a fresh-load _pendingAutostart that a scripted playSong()
never arms. Behaviour is identical to main on every probe and the unit tests cover
the logic, but the on-screen 1-2-3-4 and the credits card want a human look.

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

@@ -143,7 +143,10 @@ function loadPlaySong(sandbox) {
         : '';
     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 };
         var currentFilename = null;
         var _playerOriginScreen = null;
         var _pendingAutostart = false;

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