From 8d0e27034567792395b1cd2e2b8fbf187bb0bd71 Mon Sep 17 00:00:00 2001
From: Byron Gamatos <xasiklas@gmail.com>
Date: Sat, 11 Jul 2026 22:44:03 +0200
Subject: [PATCH] refactor(app): carve the JUCE/desktop audio shims out of
 app.js (R3a) (#893)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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

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

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

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

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

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

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

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

* refactor(app): carve the JUCE/desktop audio shims out of app.js (R3a)

static/js/juce-audio.js (994) — bodies VERBATIM. app.js 7,603 → 6,643.
THE LARGEST SINGLE SLICE of the whole carve phase: 960 lines, ~13% of what was left.

Three self-installing IIFEs:
  _installJuceEngineRoutingWatcher (444)  routes a song to the JUCE engine or HTML5 as
                                          the desktop output enters/leaves exclusive/ASIO
  _installRendererBusFeeder        (337)  feeds the highway renderer bus from whichever
                                          transport is actually running
  _installJuceAudioElementShim     (156)  patches audio.play/pause so the rest of the app
                                          keeps talking to the <audio> element while JUCE
                                          owns the transport

They EXPORT NOTHING — all three publish through `window.*` (_juceMode,
_reevaluateJuceRouting, _reevaluateRendererBus, …). So app.js needs only a
side-effect import plus the one binding it actually uses
(_resetJuceAudioShimChain, which the shim IIFE assigns).

THE ORDERING QUESTION, CHECKED RATHER THAN ASSUMED. Importing this module runs the
IIFEs EARLIER than before: imports evaluate ahead of app.js's body, and therefore
ahead of configureHost(). A hook read at IIFE-execution time would THROW. So I walked
the AST at IIFE-body depth to see what they actually touch when they run: nothing but
listener registration, and `audio.play`/`audio.pause` patching — and `audio` is itself
an imported module now. Verified in the browser: both are patched on the carved build
exactly as on main, which proves the shim installs correctly at its new, earlier point.
(Had I got this wrong, host.js throws loudly rather than silently misbehaving — which
is the whole reason it has no no-op defaults.)

VERIFIED. A/B against origin/main in two browsers: the entire window.* surface the
IIFEs publish (_juceMode, _juceOutputIsExclusive, _reevaluateJuceRouting,
_reevaluateRendererBus, _clearJuceRerouteMemo), audio.play/pause patched, a real song
loading and togglePlay driving the public mirror — IDENTICAL, zero page errors.

Harnesses: juce_engine_reroute (19 tests) + renderer_bus_feeder (13) slice the IIFEs by
signature — retargeted, and each sandbox gains a `host` object routed at its EXISTING
stubs so every assertion holds unchanged. test_plugin_runtime_idempotence is SPLIT: 3 of
its 4 source-asserts stayed in app.js, the sm.emit('song:resume') one moved.

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>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 static/app.js                            | 1118 +---------------------
 static/js/juce-audio.js                  |  994 +++++++++++++++++++
 static/js/player-state.js                |    8 +
 static/js/resume-session.js              |  157 +++
 tests/js/juce_engine_reroute.test.js     |   18 +-
 tests/js/renderer_bus_feeder.test.js     |   18 +-
 tests/test_plugin_runtime_idempotence.py |    6 +-
 7 files changed, 1211 insertions(+), 1108 deletions(-)
 create mode 100644 static/js/juce-audio.js
 create mode 100644 static/js/resume-session.js

diff --git a/static/app.js b/static/app.js
index 16f77f4..2cbecba 100644
--- a/static/app.js
+++ b/static/app.js
@@ -41,6 +41,18 @@ import {
 } from './js/settings-io.js';
 import { audio } from './js/audio-el.js';
 import { S } from './js/player-state.js';
+// Side-effect import: the three JUCE shims are IIFEs that install themselves and
+// publish through window.*. _resetJuceAudioShimChain is the one binding app.js needs.
+import { _resetJuceAudioShimChain } from './js/juce-audio.js';
+import {
+    _clearResumeSession,
+    _hideResumePill,
+    _maybeShowResumePill,
+    _readResumeSession,
+    _snapshotResumeSession,
+    resumeLastSession,
+} from './js/resume-session.js';
+
 import {
     _applyMastery,
     _applyMasteryAvailability,
@@ -3635,970 +3647,8 @@ window.addEventListener('unhandledrejection', (e) => {
         (r && (r.name + ': ' + r.message)) || String(r));
 });
 
-(function _installJuceEngineRoutingWatcher() {
-    const juceApi = window.feedBackDesktop?.audio;
-    if (!juceApi || typeof juceApi.isAudioRunning !== 'function') {
-        // Desktop bridge present but audio API incomplete — the whole
-        // exclusive reroute chain is dead and this line is the only witness.
-        // (Docker sphere has no bridge at all: stay silent, nothing to
-        // diagnose there and no debug flag to gate on.)
-        if (window.feedBackDesktop) {
-            console.log('[asio-diag] routing watcher NOT installed (audio api incomplete)');
-        }
-        return;
-    }
-
-    let _rerouteInFlight = false;
-    // URL that JUCE's loadBackingTrack *explicitly rejected* (ok === false —
-    // e.g. a codec it can't read). The poll below would otherwise retry the
-    // same doomed track every 350 ms; remember it and skip until the song
-    // changes. Only a hard JUCE reject is memoised here — transient failures
-    // (a network blip on /api/audio-local-path, an isAudioRunning() race
-    // during a device restart) are deliberately NOT memoised so they retry.
-    let _rerouteRejectedUrl = null;
-    // Exclusive-style output backends silence every other client on the
-    // endpoint — including our own <audio> element. The share mode IS the
-    // JUCE output device type: "Windows Audio (Exclusive Mode)" is a
-    // hardcoded, unlocalised JUCE type name; ASIO drivers typically hold
-    // the endpoint exclusively too. "Windows Audio (Low Latency Mode)" is
-    // shared and must NOT match.
-    function _isExclusiveOutputType(t) {
-        return t === 'Windows Audio (Exclusive Mode)' || t === 'ASIO';
-    }
-    // [feedpak-route] diagnostics: log the raw outputType string once per
-    // value change (this runs on a 350ms poll — logging every tick would
-    // flood the diagnostics buffer).
-    let _loggedOutputType;
-    // [asio-diag] verbose diagnostics, gated on --debug (preload exposes
-    // audio.debugEnabled). Resolved once at install; until it resolves the
-    // flag stays false and verbose lines are skipped. Shared with the
-    // renderer-bus feeder below via window._asioDiagEnabled.
-    let _asioDiag = false;
-    if (typeof juceApi.debugEnabled === 'function') {
-        juceApi.debugEnabled().then((v) => {
-            _asioDiag = !!v;
-            // Deferred install line: the flag resolves async, so logging at
-            // IIFE entry would race it. Change-detection isn't needed — this
-            // runs once per page load.
-            if (_asioDiag) console.log('[asio-diag] routing watcher installed');
-        }).catch(() => {});
-    }
-    window._asioDiagEnabled = () => _asioDiag;
-    async function _outputIsExclusive() {
-        if (typeof juceApi.getCurrentDevice !== 'function') {
-            if (_loggedOutputType !== '<no-getCurrentDevice>') {
-                _loggedOutputType = '<no-getCurrentDevice>';
-                console.warn('[feedpak-route] juceApi.getCurrentDevice missing — cannot detect exclusive output');
-            }
-            return false;
-        }
-        try {
-            const dev = await juceApi.getCurrentDevice();
-            const t = dev?.outputType || dev?.type || '';
-            const excl = _isExclusiveOutputType(t);
-            if (t !== _loggedOutputType) {
-                _loggedOutputType = t;
-                console.log('[feedpak-route] outputType=', JSON.stringify(t), '→ exclusive=', excl);
-                // [asio-diag] full device object on every type change — shows
-                // the exact strings the predicate saw (inputType vs outputType,
-                // device names, duplex), so a driver reporting a non-'ASIO'
-                // type name is visible in tester logs.
-                if (_asioDiag) {
-                    try {
-                        console.log('[asio-diag] getCurrentDevice=', JSON.stringify(dev));
-                    } catch (_) { /* circular/hostile object — skip */ }
-                }
-            }
-            return excl;
-        } catch (e) {
-            if (_loggedOutputType !== '<getCurrentDevice-failed>') {
-                _loggedOutputType = '<getCurrentDevice-failed>';
-                console.warn('[feedpak-route] getCurrentDevice failed:', e);
-            }
-            return false;
-        }
-    }
-    // highway.js's initial song-load routing consults this for the same
-    // feedpak-under-exclusive decision the watcher makes below.
-    window._juceOutputIsExclusive = _outputIsExclusive;
-    // Returns true when window._currentSongAudio no longer references the exact
-    // snapshot object captured at reroute entry — i.e. the song was swapped (or
-    // cleared) mid-flight. Staleness is detected by object-reference identity,
-    // not by URL value.
-    function _isStale(songAudio) {
-        return window._currentSongAudio !== songAudio;
-    }
-
-    // Migrates the loaded song from the HTML5 element onto the JUCE backing
-    // transport. Throws only on transient/unexpected failures.
-    // `songAudio` is the snapshot captured at reroute entry; if it stops being
-    // the current song mid-flight we abort without mutating global routing.
-    // Returns a distinct string outcome — the caller must NOT conflate them:
-    //   'switched' — song now plays via JUCE.
-    //   'rejected' — JUCE hard-rejected the track (codec). Caller memoises it.
-    //   'stale'    — the loaded song changed mid-flight; aborted, NOT memoised.
-    // (a transient transport-start failure throws instead — also not memoised.)
-    async function _switchHtml5ToJuce(songAudio) {
-        const url = songAudio.url;
-        const wasPlaying = S.isPlaying;
-        const pos = audio.currentTime || 0;
-        window.feedBack?.playback?.recordRouteChange?.({
-            routeKind: 'desktop-native',
-            state: 'switching',
-            preservedTime: true,
-            safeReason: 'desktop audio engine became active',
-            requesterId: 'core.juce-route',
-        });
-        // Mark a reroute in progress so the <audio> 'play'/'pause' listeners
-        // suppress their song:play / song:pause emissions: the migration is
-        // transparent — playback genuinely continues — so plugin state and
-        // window.feedBack.isPlaying must NOT flip. This also silences the
-        // "Audio paused unexpectedly" diagnostic. A REFCOUNT (not a boolean)
-        // lets an overlapping reroute's deferred release coexist: each switch
-        // increments on entry and decrements after its own timeout; listeners
-        // treat any count > 0 as "reroute active".
-        window._juceRerouteInProgress = (window._juceRerouteInProgress || 0) + 1;
-        audio.pause();
-        try {
-            const res = await fetch(`/api/audio-local-path?url=${encodeURIComponent(url)}`);
-            if (!res.ok) {
-                console.warn('[feedpak-route] audio-local-path HTTP', res.status, 'for', url);
-                throw new Error('HTTP ' + res.status);
-            }
-            const { path } = await res.json();
-            console.log('[feedpak-route] audio-local-path resolved:', (typeof path === 'string' && path.split(/[\\/]/).pop()) || '<missing>');
-            if (_isStale(songAudio)) return 'stale';   // song changed mid-fetch
-            const ok = await juceApi.loadBackingTrack(path);
-            if (ok === false) {
-                // JUCE rejected the track — stay on HTML5, resume if needed.
-                console.warn('[juce-reroute] loadBackingTrack rejected; staying on HTML5');
-                // Only resume if the element still has a source. In the normal
-                // flow audio.src is intact here, but a prior HTML5→JUCE switch
-                // clears it — re-point + load before resuming so a bounced
-                // reroute doesn't try to play() an empty element.
-                if (S.isPlaying && !_isStale(songAudio)) {
-                    if (!audio.src) { audio.src = url; audio.load(); }
-                    try { await audio.play(); } catch (_) { /* ignore */ }
-                }
-                window.feedBack?.playback?.recordRouteChange?.({
-                    routeKind: 'browser-media',
-                    state: 'degraded',
-                    preservedTime: true,
-                    safeReason: 'desktop audio route rejected track; kept browser media route',
-                    requesterId: 'core.juce-route',
-                });
-                return 'rejected';
-            }
-            if (_isStale(songAudio)) return 'stale';
-            const dur = await juceApi.getBackingDuration();
-            await juceApi.seekBacking(pos);
-            // Start the new transport BEFORE committing global routing state, so
-            // a play() failure can't leave us in "JUCE mode, nothing playing"
-            // (the silent-song state this watcher exists to prevent).
-            // jucePlayer.play() RETURNS false (it does not throw) when
-            // startBacking fails — check the result, don't just await it.
-            // A play() failure is a TRANSIENT transport-start issue, not a hard
-            // codec reject: throw (rather than returning 'rejected') so the
-            // caller's catch path handles it WITHOUT memoising the URL, leaving
-            // it free to retry on the next poll. Only 'rejected' is memoised.
-            // Re-read isPlaying as late as possible: the user can press Pause
-            // during the multi-await fetch/IPC chain above. Starting the JUCE
-            // transport off a stale `wasPlaying` snapshot would resume a song
-            // the user just paused. Only start it if playback is still wanted.
-            if (S.isPlaying) {
-                const started = await jucePlayer.play();
-                if (started === false) {
-                    if (!_isStale(songAudio) && S.isPlaying) {
-                        try { await audio.play(); } catch (_) { /* ignore */ }
-                    }
-                    throw new Error('jucePlayer.play() failed (transient transport start)');
-                }
-            }
-            if (_isStale(songAudio)) {
-                // Song changed while JUCE was spinning up — undo and bail.
-                await jucePlayer.pause().catch(() => {});
-                return 'stale';
-            }
-            if (window.jucePlayer) {
-                jucePlayer._dur = dur;
-                jucePlayer._pos = pos;
-                jucePlayer._pollAt = performance.now();
-            }
-            window._juceMode = true;
-            window._juceAudioUrl = url;
-            const _spSlider = document.getElementById?.('speed-slider');
-            if (_spSlider) setSpeed(_spSlider.value / 100);
-            audio.src = '';
-            try {
-                const apply = window.feedBack?.audio?.applySongVolume;
-                if (typeof apply === 'function') await apply();
-            } catch (_) { /* best-effort */ }
-            console.log('[juce-reroute] HTML5 → JUCE @', pos.toFixed(2), 's playing=', wasPlaying);
-            window.feedBack?.playback?.recordRouteChange?.({
-                routeKind: 'desktop-native',
-                state: 'active',
-                preservedTime: true,
-                safeReason: 'desktop audio route active',
-                requesterId: 'core.juce-route',
-            });
-            return 'switched';
-        } catch (err) {
-            // Path lookup, JSON parse, or a JUCE IPC call threw partway through.
-            // audio.pause() already ran above; restore HTML5 playback so a
-            // previously playing song isn't left silently paused, then re-throw
-            // so the caller logs it. The caller does NOT memoise this URL —
-            // transient failures must retry on the next poll.
-            if (S.isPlaying && !window._juceMode && !_isStale(songAudio)) {
-                if (!audio.src) { audio.src = url; audio.load(); }
-                try { await audio.play(); } catch (_) { /* ignore */ }
-            }
-            window.feedBack?.playback?.recordRouteChange?.({
-                routeKind: 'browser-media',
-                state: 'degraded',
-                preservedTime: true,
-                safeReason: 'desktop audio route failed; kept browser media route',
-                requesterId: 'core.juce-route',
-            });
-            throw err;
-        } finally {
-            // Clearing audio.src above dispatches a 'pause' event in a later
-            // task, after this synchronous finally. Defer the refcount
-            // decrement so that trailing event is still suppressed; a 0ms
-            // timeout lands after the pending pause-event task. Decrementing
-            // (rather than zeroing) leaves any overlapping reroute's own
-            // suppression intact.
-            setTimeout(() => {
-                window._juceRerouteInProgress = Math.max(
-                    0, (window._juceRerouteInProgress || 1) - 1);
-            }, 0);
-        }
-    }
-
-    async function _switchJuceToHtml5(songAudio) {
-        const url = songAudio.url;
-        const wasPlaying = S.isPlaying;
-        const pos = (window.jucePlayer ? jucePlayer.currentTime : 0) || 0;
-        window.feedBack?.playback?.recordRouteChange?.({
-            routeKind: 'browser-media',
-            state: 'switching',
-            preservedTime: true,
-            safeReason: 'desktop audio engine stopped',
-            requesterId: 'core.juce-route',
-        });
-        // Mark a reroute in progress (refcount) so the <audio> 'play' listener
-        // suppresses its song:play emission — the migration is transparent and
-        // playback genuinely continues, so plugin state must not flip. Held
-        // until after the (possibly deferred) audio.play() event has fired.
-        window._juceRerouteInProgress = (window._juceRerouteInProgress || 0) + 1;
-        let _suppressionReleased = false;
-        const _releaseSuppression = () => {
-            if (_suppressionReleased) return;
-            _suppressionReleased = true;
-            // Defer so the 'play' (or 'pause') event task fires while still
-            // suppressed; a 0ms timeout lands after it.
-            setTimeout(() => {
-                window._juceRerouteInProgress = Math.max(
-                    0, (window._juceRerouteInProgress || 1) - 1);
-            }, 0);
-        };
-        let _resumeScheduled = false;
-        try {
-            await jucePlayer.pause().catch(() => {});
-            if (_isStale(songAudio)) return;           // song changed mid-pause
-            window._juceMode = false;
-            window._juceAudioUrl = null;
-            audio.src = url;
-            audio.load();
-            const _spSlider = document.getElementById?.('speed-slider');
-            if (_spSlider) setSpeed(_spSlider.value / 100);
-            // Resume only AFTER the seek so playback starts at `pos`, not at 0
-            // with an audible jump once metadata arrives.
-            const resumeAtPos = () => {
-                try {
-                    // The metadata event can land after a fast song switch —
-                    // bail before touching currentTime so a stale callback
-                    // doesn't seek the newly loaded song to the old position.
-                    if (_isStale(songAudio)) return;
-                    try { audio.currentTime = pos; } catch (_) { /* ignore */ }
-                    // Re-read isPlaying (not the entry snapshot): the user may
-                    // have pressed Pause during jucePlayer.pause()/metadata
-                    // load — don't resume a song they just paused.
-                    if (S.isPlaying) {
-                        audio.play().catch(() => { /* ignore */ });
-                    }
-                } finally {
-                    _releaseSuppression();
-                }
-            };
-            _resumeScheduled = true;
-            if (audio.readyState >= 1) {
-                resumeAtPos();
-            } else {
-                // Wait for metadata to resume at `pos`. But metadata may never
-                // arrive (bad URL, network error) — that would leak the
-                // suppression refcount and permanently silence song:play /
-                // song:pause. Guard with the element's 'error' event AND a
-                // backstop timeout; whichever fires first wins, the others are
-                // detached. _releaseSuppression is idempotent regardless.
-                let _settled = false;
-                const _onMeta = () => { finish(true); };
-                const _onErr = () => { finish(false); };
-                let _backstop;
-                function finish(reachedMetadata) {
-                    if (_settled) return;
-                    _settled = true;
-                    clearTimeout(_backstop);
-                    audio.removeEventListener('loadedmetadata', _onMeta);
-                    audio.removeEventListener('error', _onErr);
-                    if (reachedMetadata) {
-                        resumeAtPos();             // resumeAtPos releases suppression
-                    } else {
-                        _releaseSuppression();     // no resume — just release
-                    }
-                }
-                audio.addEventListener('loadedmetadata', _onMeta, { once: true });
-                audio.addEventListener('error', _onErr, { once: true });
-                // 10s is well beyond a normal local-file metadata load.
-                _backstop = setTimeout(() => { finish(false); }, 10000);
-            }
-        } finally {
-            // resumeAtPos owns the release once scheduled; if we returned
-            // early (stale, before scheduling) release here instead.
-            // _releaseSuppression is idempotent so an overlap is harmless.
-            if (!_resumeScheduled) _releaseSuppression();
-        }
-        try {
-            const apply = window.feedBack?.audio?.applySongVolume;
-            if (typeof apply === 'function') await apply();
-        } catch (_) { /* best-effort */ }
-        console.log('[juce-reroute] JUCE → HTML5 @', pos.toFixed(2), 's playing=', wasPlaying);
-        window.feedBack?.playback?.recordRouteChange?.({
-            routeKind: 'browser-media',
-            state: 'active',
-            preservedTime: true,
-            safeReason: 'browser media route active',
-            requesterId: 'core.juce-route',
-        });
-    }
-
-    async function _reevaluateJuceRouting() {
-        if (_rerouteInFlight) return;
-        const songAudio = window._currentSongAudio;
-        // /audio/ songs are always JUCE-routable. A feedpak full-mix
-        // (single-mix pack, no stems) is routable ONLY under an
-        // exclusive-style output — in shared mode it must stay on HTML5 so
-        // the stem mixer / WebAudio path keeps working. Sloppak stem URLs
-        // are never routable (per-stem mix can't ride a single transport).
-        if (!songAudio || (!songAudio.juceEligible && !songAudio.feedpakFullMix)) return;
-        // Don't race highway.js's own initial song-load routing: it owns
-        // _juceMode until _juceRoutingPromise settles. Re-running our switch
-        // concurrently would double-call loadBackingTrack for the same URL.
-        if (window._highwayJuceRoutingPending) return;
-
-        // Claim the in-flight guard SYNCHRONOUSLY, before the first await. The
-        // watcher is driven by a 350ms setInterval; if isAudioRunning() (or any
-        // later await) stalls past the poll period, a second tick would
-        // otherwise pass the `if (_rerouteInFlight) return` check above and run
-        // a concurrent switch — duplicate loadBackingTrack IPCs racing on
-        // _juceMode / audio.src. Setting it here closes that window.
-        _rerouteInFlight = true;
-        try {
-            let running;
-            try { running = await juceApi.isAudioRunning(); }
-            catch (_) { return; }
-            if (_isStale(songAudio)) return;               // song changed during IPC
-            // Eligibility is evaluated per tick, not snapshotted at song load:
-            // the output share mode can change mid-song (device switch in the
-            // Audio Engine panel), and a feedpak full-mix must follow it —
-            // exclusive → ride the engine; back to shared → return to HTML5.
-            let eligible = !!songAudio.juceEligible;
-            if (!eligible && songAudio.feedpakFullMix && running) {
-                eligible = await _outputIsExclusive();
-                if (_isStale(songAudio)) return;           // song changed during IPC
-            }
-            const wantJuce = !!(running && eligible);
-            // [feedpak-route] diagnostics: one line per decision change (the
-            // watcher polls at 350ms; steady state must not spam the buffer).
-            const _decision = 'running=' + running + ' eligible=' + eligible
-                + ' feedpakFullMix=' + !!songAudio.feedpakFullMix
-                + ' juceMode=' + !!window._juceMode + ' url=' + songAudio.url;
-            if (_decision !== window._lastFeedpakRouteDecision) {
-                window._lastFeedpakRouteDecision = _decision;
-                console.log('[feedpak-route] watcher:', _decision);
-            }
-            if (wantJuce === !!window._juceMode) return;   // routing already consistent
-            // Don't keep retrying a track JUCE explicitly rejected.
-            if (wantJuce && songAudio.url === _rerouteRejectedUrl) return;
-
-            if (wantJuce) {
-                const outcome = await _switchHtml5ToJuce(songAudio);
-                // Memoise ONLY an explicit hard JUCE reject. A successful
-                // switch clears the memo; a 'stale' abort (song changed
-                // mid-flight) leaves it untouched — it must never be
-                // misclassified as a reject, even if the song object was
-                // swapped and then restored before this point.
-                if (outcome === 'rejected') {
-                    _rerouteRejectedUrl = songAudio.url;
-                } else if (outcome === 'switched') {
-                    _rerouteRejectedUrl = null;
-                }
-                // outcome === 'stale': leave _rerouteRejectedUrl as-is.
-            } else {
-                await _switchJuceToHtml5(songAudio);
-                // The engine stopped (or a feedpak's output left exclusive
-                // mode). Clear any hard-reject memo so a later engine restart
-                // or mode change re-evaluates the track at least once — the
-                // rejection may have been a transient device/decoder state.
-                _rerouteRejectedUrl = null;
-            }
-        } catch (e) {
-            // Transient failure — log but do NOT memoise, so the next poll retries.
-            console.warn('[juce-reroute] re-route failed (will retry):', e);
-        } finally {
-            _rerouteInFlight = false;
-        }
-    }
-    window._reevaluateJuceRouting = _reevaluateJuceRouting;
-
-    // Clears the hard-reject memo. Called from the song-teardown sites that
-    // null window._currentSongAudio (showScreen, playSong) so that reloading
-    // the same file later gets a fresh routing attempt — a prior reject may
-    // have been a transient JUCE/device state, not a permanent codec issue.
-    window._clearJuceRerouteMemo = function () { _rerouteRejectedUrl = null; };
-
-    // The engine can be started/stopped from several places (the desktop Audio
-    // Engine panel, the audio_engine plugin, note_detect) and via setDevice
-    // restarts — and the contextBridge api object is frozen, so its methods
-    // can't be wrapped. Poll isAudioRunning() while a song is loaded; the check
-    // is a cheap IPC boolean and no-ops once routing is already consistent.
-    // Skip the poll while the document is hidden (background tab / minimised
-    // window) — engine toggles there will be reconciled on the first poll
-    // after the tab is visible again.
-    setInterval(() => {
-        if (document.hidden) return;
-        if (window._currentSongAudio) void _reevaluateJuceRouting();
-    }, 350);
-})();
-
-// Renderer-audio bus feeder (desktop Phase 2): when the engine holds the
-// output endpoint in an exclusive-style mode, Chromium cannot reach the
-// device, so any song audio still played by the renderer goes silent. The
-// Phase 1 watcher above already migrates what a single-file transport can
-// carry (loose /audio/ songs, feedpak full-mixes) onto the native backing
-// transport. This feeder covers the rest — the stems plugin's multi-stem
-// WebAudio graph, plus <audio>-element songs the native transport could not
-// take (e.g. a codec loadBackingTrack rejected).
-//
-// Mechanism: capture the renderer-side master with an AudioWorklet tap,
-// re-point the owning AudioContext at a null sink so it keeps rendering
-// without a device, and push ~10 ms chunks over IPC into the engine's
-// renderer bus, where they are mixed into the exclusive output like a
-// backing track (~10-20 ms added latency on song audio only; the guitar
-// monitoring path is untouched). Validated by the fix12 tester spike:
-// null-sink rendering works, clocks hold (drift → 0), no overflow.
-//
-// Docker sphere: window.feedBackDesktop is undefined → this whole block is
-// inert. Shared-mode desktop: the bus stays disabled (no double audio) and
-// captured contexts keep/regain their default sink.
-(function _installRendererBusFeeder() {
-    const api = window.feedBackDesktop?.audio;
-    if (!api || typeof api.setRendererBus !== 'function'
-             || typeof api.pushRendererAudio !== 'function') {
-        // Silent in the Docker sphere (no bridge, no debug flag); a desktop
-        // bridge missing the bus API is the diagnostic case.
-        if (window.feedBackDesktop) {
-            console.log('[asio-diag] renderer-bus feeder NOT installed (api=' + !!api
-                + ' setRendererBus=' + typeof api?.setRendererBus
-                + ' pushRendererAudio=' + typeof api?.pushRendererAudio + ')');
-        }
-        return;
-    }
-    // Deferred like the watcher's install line: gate on the async debug flag.
-    if (typeof api.debugEnabled === 'function') {
-        api.debugEnabled().then((v) => {
-            if (v) console.log('[asio-diag] renderer-bus feeder installed (loopback-capable='
-                + (typeof window.navigator?.mediaDevices?.getDisplayMedia === 'function') + ')');
-        }).catch(() => {});
-    }
-
-    const TAP_WORKLET = `
-        class FeedbackBusTap extends AudioWorkletProcessor {
-            process(inputs) {
-                const inp = inputs[0];
-                if (inp && inp[0]) {
-                    const L = inp[0], R = inp[1] || inp[0];
-                    const out = new Float32Array(L.length * 2);
-                    for (let i = 0; i < L.length; i++) { out[i*2] = L[i]; out[i*2+1] = R[i]; }
-                    this.port.postMessage(out, [out.buffer]);
-                }
-                return true;
-            }
-        }
-        registerProcessor('feedback-bus-tap', FeedbackBusTap);
-    `;
-    const _tapModuleUrl = URL.createObjectURL(new Blob([TAP_WORKLET], { type: 'application/javascript' }));
-    const _tapModuleLoaded = new WeakSet();   // AudioContexts with the module added
-
-    // One tap per captured graph. `active` gates the push (the worklet keeps
-    // running when inactive — it's silent bookkeeping, not audio).
-    function _makeTap(ctx) {
-        const state = { node: null, active: false, batch: [], batchFrames: 0 };
-        state.attach = async (sourceNode) => {
-            if (!_tapModuleLoaded.has(ctx)) {
-                await ctx.audioWorklet.addModule(_tapModuleUrl);
-                _tapModuleLoaded.add(ctx);
-            }
-            if (!state.node) {
-                state.node = new AudioWorkletNode(ctx, 'feedback-bus-tap', { numberOfInputs: 1, channelCount: 2 });
-                const BATCH = Math.round(ctx.sampleRate / 100);   // ~10 ms
-                state.node.port.onmessage = (e) => {
-                    if (!state.active) { state.batch = []; state.batchFrames = 0; return; }
-                    state.batch.push(e.data);
-                    state.batchFrames += e.data.length / 2;
-                    if (state.batchFrames >= BATCH) {
-                        const merged = new Float32Array(state.batchFrames * 2);
-                        let o = 0;
-                        for (const c of state.batch) { merged.set(c, o); o += c.length; }
-                        api.pushRendererAudio(merged, ctx.sampleRate);
-                        state.batch = []; state.batchFrames = 0;
-                    }
-                };
-            }
-            sourceNode.connect(state.node);
-            // No onward connection: the tap is a sink-side observer; audibility
-            // in shared mode comes from the graph's own destination path.
-        };
-        state.detach = (sourceNode) => {
-            state.active = false;
-            state.batch = []; state.batchFrames = 0;
-            if (state.node && sourceNode) {
-                try { sourceNode.disconnect(state.node); } catch (_) { /* already gone */ }
-            }
-        };
-        return state;
-    }
-
-    // ── Core <audio> element capture ─────────────────────────────────────────
-    // createMediaElementSource permanently reroutes the element into its
-    // context, so it is created lazily — only the first time an exclusive
-    // device actually needs it — and never torn down. From then on the element
-    // always plays through _elCtx; sink toggling routes it to the speakers
-    // (shared mode) or the null sink + bus (exclusive mode).
-    let _elCtx = null, _elSource = null, _elTap = null;
-    async function _ensureElementCapture() {
-        if (_elCtx) return;
-        const el = document.getElementById('audio');
-        if (!el) throw new Error('no core audio element');
-        // Assign the module state ONLY after the whole chain succeeded.
-        // createMediaElementSource throws InvalidStateError when another
-        // consumer (highway_3d's analyser tap) already owns the element's
-        // one-shot source — assigning _elCtx before that throw poisoned every
-        // later tick into `_elTap.active` TypeErrors (tester log 2026-07-11)
-        // while the song kept playing on the default device.
-        const ctx = new AudioContext();
-        let source, tap;
-        try {
-            source = ctx.createMediaElementSource(el);
-            source.connect(ctx.destination);
-            tap = _makeTap(ctx);
-            await tap.attach(source);
-        } catch (e) {
-            try { await ctx.close(); } catch (_) { /* already closed */ }
-            throw e;
-        }
-        _elCtx = ctx; _elSource = source; _elTap = tap;
-    }
-
-    // ── Whole-app loopback capture ───────────────────────────────────────────
-    // Preferred mode: one getDisplayMedia frame-audio capture covers EVERY
-    // sound the app makes (song, previews, UI) — no per-surface taps, so
-    // plugin-private AudioContexts (song-preview, future plugins) survive
-    // exclusive/ASIO output too. The desktop main process answers the request
-    // with this window's own frame (frame-scoped — no other apps' audio).
-    // Local playback is silenced via the suppressLocalAudioPlayback track
-    // constraint, with a page-mute IPC fallback (capture taps frame audio
-    // before the output mute, so a muted page still feeds the stream).
-    let _lbStream = null, _lbCtx = null, _lbTap = null, _lbPageMuted = false;
-    let _loopbackUnavailable = false;   // sticky: probe once, then fall back
-    async function _engageLoopback() {
-        const stream = await navigator.mediaDevices.getDisplayMedia({
-            video: true,
-            audio: { suppressLocalAudioPlayback: true },
-        });
-        for (const t of stream.getVideoTracks()) t.stop();   // required, unused
-        const track = stream.getAudioTracks()[0];
-        if (!track) {
-            for (const t of stream.getTracks()) t.stop();
-            throw new Error('no loopback audio track');
-        }
-        try {
-            // Fresh context per session (not reused) so teardown's close()
-            // fully releases the tap worklet node — see _teardownLoopback.
-            _lbCtx = new AudioContext();
-            if (_lbCtx.state !== 'running') await _lbCtx.resume().catch(() => {});
-            const source = _lbCtx.createMediaStreamSource(stream);
-            const tap = _makeTap(_lbCtx);
-            await tap.attach(source);
-            const suppressed = track.getSettings?.().suppressLocalAudioPlayback === true;
-            if (!suppressed && typeof api.setPageMuted === 'function') {
-                _lbPageMuted = (await api.setPageMuted(true)) === true;
-            }
-            if (window._asioDiagEnabled?.()) {
-                console.log('[asio-diag] loopback: suppressed=', suppressed,
-                    'pageMuted=', _lbPageMuted, 'rate=', _lbCtx.sampleRate);
-            }
-            await api.setRendererBus(true, 1.0);
-            tap.active = true;
-            _lbStream = stream; _lbTap = tap;
-            _mode = 'loopback';
-            console.log('[renderer-bus] engaged: app loopback → engine bus');
-        } catch (e) {
-            for (const t of stream.getTracks()) t.stop();
-            throw e;
-        }
-    }
-    async function _teardownLoopback() {
-        if (_lbTap) _lbTap.active = false;
-        if (_lbStream) for (const t of _lbStream.getTracks()) t.stop();
-        _lbStream = null; _lbTap = null;
-        // Close the capture context so its tap worklet node is released. The
-        // context is per-session (not reused): without this, each exclusive⇄
-        // shared switch orphaned a live worklet on a long-lived context.
-        if (_lbCtx) {
-            try { await _lbCtx.close(); } catch (_) { /* already closed */ }
-            _lbCtx = null;
-        }
-        if (_lbPageMuted && typeof api.setPageMuted === 'function') {
-            try { await api.setPageMuted(false); } catch (_) { /* engine gone */ }
-        }
-        _lbPageMuted = false;
-    }
-
-    // ── Engagement state machine ─────────────────────────────────────────────
-    // 'off' | 'loopback' | 'element' | 'stems' (element/stems = fallback when
-    // loopback capture is unavailable: old desktop main, denied capture)
-    let _mode = 'off';
-    let _stemsGraph = null;   // { context, masterNode } snapshot while engaged
-    let _stemsTap = null;
-    const _stemsTaps = new WeakMap();  // context → tap (stems ctx is reused across songs)
-    let _busy = false;
-
-    async function _setSink(ctx, exclusive) {
-        if (typeof ctx.setSinkId !== 'function') throw new Error('setSinkId unsupported');
-        await ctx.setSinkId(exclusive ? { type: 'none' } : '');
-        if (ctx.state !== 'running') await ctx.resume().catch(() => {});
-        // [asio-diag] a context left on the default sink while the bus is
-        // engaged is exactly the "song on the wrong device" symptom — record
-        // every successful sink flip (failures throw and are logged upstream).
-        if (window._asioDiagEnabled?.()) {
-            console.log('[asio-diag] setSink:', exclusive ? 'null-sink' : 'default',
-                'state=', ctx.state, 'rate=', ctx.sampleRate);
-        }
-    }
-
-    async function _disengage() {
-        if (_mode === 'off') return;
-        const prev = _mode;
-        _mode = 'off';
-        try { await api.setRendererBus(false, 0); } catch (_) { /* engine gone */ }
-        if (prev === 'loopback') {
-            await _teardownLoopback();
-        } else if (prev === 'element' && _elCtx) {
-            _elTap.active = false;
-            await _setSink(_elCtx, false).catch(() => {});
-        } else if (prev === 'stems' && _stemsGraph) {
-            if (_stemsTap) _stemsTap.detach(_stemsGraph.masterNode);
-            await _setSink(_stemsGraph.context, false).catch(() => {});
-            _stemsGraph = null; _stemsTap = null;
-        }
-        console.log('[renderer-bus] disengaged (' + prev + ')');
-    }
-
-    async function _engageStems(graph) {
-        await _setSink(graph.context, true);
-        let tap = _stemsTaps.get(graph.context);
-        if (!tap) { tap = _makeTap(graph.context); _stemsTaps.set(graph.context, tap); }
-        await tap.attach(graph.masterNode);
-        await api.setRendererBus(true, 1.0);
-        tap.active = true;
-        _stemsGraph = graph; _stemsTap = tap;
-        _mode = 'stems';
-        console.log('[renderer-bus] engaged: stems graph → engine bus');
-    }
-
-    async function _engageElement() {
-        await _ensureElementCapture();
-        await _setSink(_elCtx, true);
-        await api.setRendererBus(true, 1.0);
-        _elTap.active = true;
-        _mode = 'element';
-        console.log('[renderer-bus] engaged: <audio> element → engine bus');
-    }
-
-    async function _reevaluate() {
-        if (_busy) return;
-        _busy = true;
-        try {
-            let running = false, exclusive = false;
-            try {
-                running = await api.isAudioRunning();
-            } catch (_) { /* engine unreachable → treat as not running */ }
-            if (running) {
-                // Reuse the Phase 1 predicate installed by the routing watcher
-                // (getCurrentDevice + exclusive-type check with change-logged
-                // diagnostics). Fail closed if it is somehow absent.
-                exclusive = !!(await window._juceOutputIsExclusive?.());
-            }
-
-            // The stems plugin publishes its live graph while a multi-stem
-            // song is loaded (and removes it on teardown).
-            const stems = (window.feedBack || window.slopsmith)?.stems?.audioGraph || null;
-            // Element songs: a song is loaded, it is NOT riding the native
-            // transport (Phase 1 owns those), and the stems graph is not the
-            // player. Covers native-transport rejects (codec) in exclusive
-            // mode — without this they would be silent.
-            const songAudio = window._currentSongAudio;
-            const elementSong = !!songAudio && !window._juceMode && !stems;
-
-            let want = 'off';
-            if (running && exclusive) {
-                // Loopback covers ALL app audio (song, previews, UI), so it
-                // engages for the whole exclusive session — not just while a
-                // song is loaded. Per-surface modes remain as fallback when
-                // loopback capture is unavailable (old desktop main without
-                // the display-media handler, capture denied).
-                if (!_loopbackUnavailable) want = 'loopback';
-                else if (stems) want = 'stems';
-                else if (elementSong) want = 'element';
-            }
-            // Song audio riding the native transport must not ALSO ride the
-            // loopback (double-carry into the same engine output). The native
-            // transport plays from the engine, not the page, so page loopback
-            // never hears it — no conflict; loopback stays engaged for
-            // previews/UI while the transport owns the song.
-
-            // [asio-diag] full decision vector, change-gated (500ms poll —
-            // steady state must not flood the buffer). This is the feeder-side
-            // counterpart of the watcher's [feedpak-route] decision line: it
-            // shows WHY the bus did or didn't engage (exclusive predicate,
-            // stems graph presence, native transport ownership, element song).
-            if (window._asioDiagEnabled?.()) {
-                const d = 'running=' + running + ' exclusive=' + exclusive
-                    + ' stems=' + !!stems + ' songAudio=' + !!songAudio
-                    + ' juceMode=' + !!window._juceMode
-                    + ' elementSong=' + elementSong
-                    + ' loopbackUnavailable=' + _loopbackUnavailable
-                    + ' want=' + want + ' mode=' + _mode;
-                if (d !== window._lastRendererBusDecision) {
-                    window._lastRendererBusDecision = d;
-                    console.log('[asio-diag] renderer-bus:', d);
-                }
-            }
 
 
-            const stemsGraphChanged = _mode === 'stems' && stems !== _stemsGraph;
-            if (want !== _mode || stemsGraphChanged) {
-                await _disengage();
-                try {
-                    if (want === 'loopback') await _engageLoopback();
-                    else if (want === 'stems') await _engageStems(stems);
-                    else if (want === 'element') await _engageElement();
-                } catch (e) {
-                    if (want === 'loopback') {
-                        // Capture unavailable (no handler in an old desktop
-                        // main, permission denied) — remember and fall back to
-                        // the per-surface modes on the next tick.
-                        _loopbackUnavailable = true;
-                        console.warn('[renderer-bus] loopback capture unavailable — falling back to surface taps:', e);
-                    }
-                    throw e;
-                }
-            }
-        } catch (e) {
-            // Explicit name/message/stack head — the console-message forward
-            // stringifies a DOMException to the useless "[object DOMException]".
-            console.warn('[renderer-bus] reevaluate failed (will retry):',
-                (e && e.name ? e.name + ': ' + e.message : String(e)),
-                (e && e.stack ? '| ' + String(e.stack).split('\n')[1] : ''));
-            _mode = 'off';
-            // A partial engage may have left the bus enabled with no producer
-            // and the page muted — undo both so a failed tick can't strand
-            // audio in silence until the next successful engage.
-            try { await api.setRendererBus(false, 0); } catch (_) { /* engine gone */ }
-            await _teardownLoopback().catch(() => {});
-        } finally {
-            _busy = false;
-        }
-    }
-
-    // Same cadence/rationale as the routing watcher above. Also re-check on
-    // visibility return so a device switch made while hidden is reconciled.
-    setInterval(() => { if (!document.hidden) void _reevaluate(); }, 500);
-    document.addEventListener('visibilitychange', () => { if (!document.hidden) void _reevaluate(); });
-    window._reevaluateRendererBus = _reevaluate;
-})();
-
-// Desktop JUCE backing uses an empty <audio> element; plugins such as Section Map
-// still seek via audio.currentTime / pause / play. Mirror those onto jucePlayer
-// while _juceMode is active. Same-tick pause+seek coalesce into a single seek
-// (no stopBacking before seek — HTML5 needed that for buffering; JUCE does not).
-let _resetJuceAudioShimChain = function () {};
-(function _installJuceAudioElementShim() {
-    if (!window.feedBackDesktop?.audio) return;
-
-    const mediaProto = HTMLMediaElement.prototype;
-    const ctDesc = Object.getOwnPropertyDescriptor(mediaProto, 'currentTime');
-    const pausedDesc = Object.getOwnPropertyDescriptor(mediaProto, 'paused');
-    if (!ctDesc?.get || !ctDesc?.set || !pausedDesc?.get) return;
-
-    const nativePlay = mediaProto.play;
-    const nativePause = mediaProto.pause;
-
-    let chain = Promise.resolve();
-    /** Same-tick pause + seek (Section Map): coalesce to one seek — no stopBacking before seek. */
-    let _juceShimBatch = null;
-    let _juceShimBatchFlushScheduled = false;
-    let _juceShimGen = 0;
-    function enqueue(fn) {
-        const gen = _juceShimGen;
-        const p = chain.then(async () => {
-            if (gen !== _juceShimGen) return;
-            return fn(gen);
-        });
-        chain = p.catch((e) => {
-            console.warn('[juce-audio-shim]', e);
-        });
-        return p;
-    }
-    // forUpcomingPlay: caller will enqueue a play() right after, so don't
-    // emit pause-state side effects for a wantsPause batch — play() will
-    // overwrite them anyway.
-    function flushJuceShimBatchNow({ forUpcomingPlay = false } = {}) {
-        _juceShimBatchFlushScheduled = false;
-        const batch = _juceShimBatch;
-        _juceShimBatch = null;
-        if (!batch || !window._juceMode) return;
-        const wantsPause = !!batch.wantsPause;
-        const seekTime = batch.seekTime;
-        if (wantsPause && seekTime !== undefined) {
-            enqueue(async (gen) => {
-                const r = await _audioSeek(seekTime, 'audio-element-shim');
-                if (!r.completed) return; // seek cancelled by teardown
-                if (gen !== _juceShimGen) return;
-                if (!forUpcomingPlay) {
-                    await jucePlayer.pause();
-                    if (gen !== _juceShimGen) return;
-                    S.isPlaying = false;
-                    setPlayButtonState(false);
-                    const sm = window.feedBack;
-                    if (sm) {
-                        sm.isPlaying = false;
-                        sm.emit('song:pause', _songEventPayload());
-                    }
-                }
-                audio.dispatchEvent(new Event('seeked'));
-            });
-            return;
-        }
-        if (wantsPause) {
-            enqueue(async (gen) => {
-                await jucePlayer.pause();
-                if (gen !== _juceShimGen) return;
-                S.isPlaying = false;
-                setPlayButtonState(false);
-                const sm = window.feedBack;
-                if (sm) {
-                    sm.isPlaying = false;
-                    sm.emit('song:pause', _songEventPayload());
-                }
-            });
-            return;
-        }
-        if (seekTime !== undefined) {
-            enqueue(async (gen) => {
-                const r = await _audioSeek(seekTime, 'audio-element-shim');
-                if (!r.completed) return; // seek cancelled by teardown
-                if (gen !== _juceShimGen) return;
-                audio.dispatchEvent(new Event('seeked'));
-            });
-        }
-    }
-    function scheduleJuceShimBatchFlush() {
-        if (_juceShimBatchFlushScheduled) return;
-        _juceShimBatchFlushScheduled = true;
-        const flushGen = _juceShimGen;
-        queueMicrotask(() => {
-            if (flushGen !== _juceShimGen) {
-                _juceShimBatchFlushScheduled = false;
-                return;
-            }
-            flushJuceShimBatchNow();
-        });
-    }
-    _resetJuceAudioShimChain = function () {
-        chain = Promise.resolve();
-        _juceShimBatch = null;
-        _juceShimBatchFlushScheduled = false;
-        _juceShimGen++;
-    };
-
-    Object.defineProperty(audio, 'currentTime', {
-        get() {
-            if (window._juceMode) return jucePlayer.currentTime;
-            return ctDesc.get.call(this);
-        },
-        set(v) {
-            if (window._juceMode) {
-                const t = Math.max(0, Number(v) || 0);
-                _juceShimBatch = _juceShimBatch || {};
-                _juceShimBatch.seekTime = t;
-                scheduleJuceShimBatchFlush();
-                return;
-            }
-            ctDesc.set.call(this, v);
-        },
-        configurable: true,
-    });
-
-    Object.defineProperty(audio, 'paused', {
-        get() {
-            if (window._juceMode) return !S.isPlaying;
-            return pausedDesc.get.call(this);
-        },
-        configurable: true,
-    });
-
-    audio.pause = function () {
-        if (window._juceMode) {
-            _juceShimBatch = _juceShimBatch || {};
-            _juceShimBatch.wantsPause = true;
-            scheduleJuceShimBatchFlush();
-            return;
-        }
-        nativePause.call(audio);
-    };
-
-    audio.play = function () {
-        if (window._juceMode) {
-            if (_juceShimBatch != null) flushJuceShimBatchNow({ forUpcomingPlay: true });
-            const p = enqueue(async (gen) => {
-                const started = await jucePlayer.play();
-                if (gen !== _juceShimGen || !started) return;
-                S.isPlaying = true;
-                setPlayButtonState(true);
-                const sm = window.feedBack;
-                if (sm) {
-                    sm.isPlaying = true;
-                    const payload = _songEventPayload();
-                    sm.emit('song:play', payload);
-                    sm.emit('song:resume', payload);
-                }
-            });
-            return p.then(() => undefined);
-        }
-        return nativePlay.call(audio);
-    };
-})();
 
 function _audioTime() { return window._juceMode ? jucePlayer.currentTime : audio.currentTime; }
 function _audioDuration() { return window._juceMode ? jucePlayer.duration : audio.duration; }
@@ -5353,87 +4403,11 @@ window.feedBack.on('song:ready', () => {
     else holdCreditsThen(start);
 });
 
-// ── Resume last session ────────────────────────────────────────────────────
-// Leaving a song snapshots where you were — song, arrangement, position, and
-// speed — so an exit (especially an accidental one, now that Escape reliably
-// leaves regardless of focus) is recoverable instead of restarting from bar 1.
-// The snapshot is offered back through a non-blocking "Resume" pill; it never
-// gates, blocks, or auto-acts. Cleared on natural song-end and once consumed.
-// (This is the player-session slice; the broader nav/state-resume work — e.g.
-// returning to a song after wandering into Settings → Tone Builder — is a
-// separate, larger track.)
-const _RESUME_KEY = 'feedBack.resumeSession';
-const _RESUME_MAX_AGE_MS = 24 * 60 * 60 * 1000;   // a day-old snapshot is stale
-const _RESUME_MIN_POSITION_S = 3;                  // ignore barely-started songs
-const _RESUME_END_GUARD_S = 5;                      // ignore basically-finished songs
-let _pendingResume = null;                          // {position, speed}, consumed at song:ready
-let _resumePillDismissed = false;                   // per-session: user waved off the current snapshot
 
 
-// Snapshot the live session. Called from showScreen()'s teardown before
-// highway.stop()/audio unload, while getSongInfo() + position are still valid.
-function _snapshotResumeSession(position) {
-    try {
-        if (!currentFilename) return;
-        const si = (window.highway && typeof highway.getSongInfo === 'function')
-            ? (highway.getSongInfo() || {}) : {};
-        const dur = Number(si.duration) || 0;
-        const pos = Number(position) || 0;
-        // Only worth resuming a song you were genuinely mid-way through — not a
-        // glance at the first seconds, and not one that already basically ended.
-        if (pos < _RESUME_MIN_POSITION_S) { _clearResumeSession(); return; }
-        if (dur && pos > dur - _RESUME_END_GUARD_S) { _clearResumeSession(); return; }
-        const snap = {
-            f: currentFilename,
-            a: (typeof si.arrangement_index === 'number' && si.arrangement_index >= 0)
-                ? si.arrangement_index : undefined,
-            t: pos,
-            sp: _curPlaybackSpeed(),
-            title: si.title || '',
-            artist: si.artist || '',
-            ts: Date.now(),
-        };
-        localStorage.setItem(_RESUME_KEY, JSON.stringify(snap));
-        // A fresh snapshot earns one offer — undo any earlier dismissal.
-        _resumePillDismissed = false;
-    } catch (_) { /* storage unavailable — resume is best-effort */ }
-}
 
-function _readResumeSession() {
-    try {
-        const raw = localStorage.getItem(_RESUME_KEY);
-        if (!raw) return null;
-        const snap = JSON.parse(raw);
-        if (!snap || !snap.f || !(Number(snap.t) > 0)) return null;
-        if (!snap.ts || Date.now() - snap.ts > _RESUME_MAX_AGE_MS) { _clearResumeSession(); return null; }
-        return snap;
-    } catch (_) { return null; }
-}
 
-function _clearResumeSession() {
-    try { localStorage.removeItem(_RESUME_KEY); } catch (_) {}
-}
 
-// Re-enter the snapshotted song and restore arrangement + position + speed.
-async function resumeLastSession() {
-    const snap = _readResumeSession();
-    if (!snap) { _hideResumePill(); return false; }
-    _hideResumePill();
-    try {
-        await playSong(snap.f, snap.a, {
-            resume: { position: Number(snap.t) || 0, speed: Number(snap.sp) || 1 },
-        });
-    } catch (err) {
-        // A transient load/connect failure must not strand the user: keep the
-        // snapshot so the pill can re-offer it on the next non-player screen,
-        // rather than consuming the only copy before the song actually loaded.
-        console.warn('[app] resume failed to load; keeping snapshot:', err);
-        _pendingResume = null;
-        return false;
-    }
-    _clearResumeSession();   // consumed only after a successful load
-    return true;
-}
 window.resumeLastSession = resumeLastSession;
 if (window.feedBack) window.feedBack.resumeLastSession = resumeLastSession;
 
@@ -5441,9 +4415,9 @@ if (window.feedBack) window.feedBack.resumeLastSession = resumeLastSession;
 // saved position, then (if autoplay is on) start from there. playSong() does
 // NOT arm autostart for a resume load, so the two never fight over playback.
 window.feedBack.on('song:ready', () => {
-    const pend = _pendingResume;
+    const pend = S.pendingResume;
     if (!pend) return;
-    _pendingResume = null;
+    S.pendingResume = null;
     try {
         if (pend.speed && pend.speed > 0) {
             const slider = document.getElementById('speed-slider');
@@ -5460,66 +4434,7 @@ window.feedBack.on('song:ready', () => {
 // offer "resume" for a song the user just completed.
 window.feedBack.on('song:ended', _clearResumeSession);
 
-// ── Resume pill (non-blocking "continue where you left off") ────────────────
-// Self-contained, inline-styled, body-appended so it works identically in the
-// classic (v2) and v3 shells with no Tailwind rebuild. It only ever appears off
-// the player screen, never blocks, and a dismiss forgets the current snapshot
-// for the session.
-function _hideResumePill() {
-    const el = document.getElementById('fb-resume-pill');
-    if (el) el.remove();
-}
 
-function _maybeShowResumePill() {
-    const active = document.querySelector('.screen.active');
-    if (active && active.id === 'player') { _hideResumePill(); return; }
-    if (_resumePillDismissed) return;
-    const snap = _readResumeSession();
-    if (!snap) { _hideResumePill(); return; }
-    if (document.getElementById('fb-resume-pill')) return;   // already shown
-
-    const label = (snap.title || decodeURIComponent(snap.f || 'your last song')).toString();
-    const pill = document.createElement('div');
-    pill.id = 'fb-resume-pill';
-    pill.setAttribute('role', 'status');
-    pill.style.cssText = [
-        'position:fixed', 'left:16px', 'bottom:16px', 'z-index:120',
-        'display:flex', 'align-items:center', 'gap:10px',
-        'max-width:min(90vw,360px)', 'padding:10px 12px',
-        'background:rgba(17,24,39,0.96)', 'color:#e5e7eb',
-        'border:1px solid rgba(148,163,184,0.25)', 'border-radius:10px',
-        'box-shadow:0 6px 24px rgba(0,0,0,0.4)',
-        'font:13px/1.3 system-ui,-apple-system,"Segoe UI",Roboto,sans-serif',
-    ].join(';');
-
-    const text = document.createElement('div');
-    text.style.cssText = 'flex:1;min-width:0';
-    const t1 = document.createElement('div');
-    t1.textContent = 'Resume practice';
-    t1.style.cssText = 'font-weight:600;color:#fff';
-    const t2 = document.createElement('div');
-    t2.textContent = label;
-    t2.style.cssText = 'opacity:0.7;white-space:nowrap;overflow:hidden;text-overflow:ellipsis';
-    text.appendChild(t1); text.appendChild(t2);
-
-    const resumeBtn = document.createElement('button');
-    resumeBtn.type = 'button';
-    resumeBtn.textContent = 'Resume ▸';
-    resumeBtn.style.cssText = 'flex:none;padding:6px 10px;border:0;border-radius:7px;background:#4080e0;color:#fff;font-weight:600;cursor:pointer';
-    resumeBtn.addEventListener('click', () => { resumeLastSession(); });
-
-    const dismissBtn = document.createElement('button');
-    dismissBtn.type = 'button';
-    dismissBtn.setAttribute('aria-label', 'Dismiss');
-    dismissBtn.textContent = '✕';
-    dismissBtn.style.cssText = 'flex:none;padding:4px 6px;border:0;border-radius:7px;background:transparent;color:#9ca3af;cursor:pointer;font-size:14px';
-    dismissBtn.addEventListener('click', () => { _resumePillDismissed = true; _hideResumePill(); });
-
-    pill.appendChild(text);
-    pill.appendChild(resumeBtn);
-    pill.appendChild(dismissBtn);
-    (document.body || document.documentElement).appendChild(pill);
-}
 if (window.feedBack) window.feedBack._maybeShowResumePill = _maybeShowResumePill;
 
 // Exposed for tests/debugging (mirrors window._panels / _getCurrentContext).
@@ -5709,10 +4624,10 @@ async function playSong(filename, arrangement, options) {
     // the saved position, then start — so autostart and resume don't both try
     // to begin playback from different positions.
     if (options && options.resume && Number(options.resume.position) > 0) {
-        _pendingResume = options.resume;
+        S.pendingResume = options.resume;
         _pendingAutostart = false;
     } else {
-        _pendingResume = null;
+        S.pendingResume = null;
         _pendingAutostart = true;
     }
     _clearAutoExit();
@@ -7674,6 +6589,7 @@ configureHost({
     _songEventPayload,
     togglePlay,
     handleSliderInput,
+    playSong,
     // count-in is a module now, so section-practice reaches it through the seam too —
     // these are simply count-in's own exports, handed across.
     startCountIn,
diff --git a/static/js/juce-audio.js b/static/js/juce-audio.js
new file mode 100644
index 0000000..e4b0495
--- /dev/null
+++ b/static/js/juce-audio.js
@@ -0,0 +1,994 @@
+// The desktop (JUCE) audio integration — three self-installing shims.
+//
+// The largest single slice out of app.js's core: 938 lines, ~12% of what was left.
+//
+//   _installJuceEngineRoutingWatcher  routes a song to the JUCE engine or HTML5 as the
+//                                     desktop output device enters/leaves exclusive/ASIO
+//   _installRendererBusFeeder         feeds the highway renderer bus from whichever
+//                                     transport is actually running
+//   _installJuceAudioElementShim      patches audio.play/pause so the rest of the app
+//                                     can keep talking to the <audio> element while JUCE
+//                                     owns the transport
+//
+// They EXPORT NOTHING. All three are IIFEs that publish through `window.*`
+// (_juceMode, _reevaluateJuceRouting, _reevaluateRendererBus, …) — which is why app.js
+// only needs a side-effect import for two of them, plus _resetJuceAudioShimChain.
+//
+// ORDERING, CHECKED: importing this module runs the IIFEs EARLIER than before —
+// imports evaluate ahead of app.js's body, and therefore ahead of configureHost().
+// That is safe because none of them touches a hook at execution depth: they only
+// register listeners and patch audio.play/pause (and `audio` is itself an imported
+// module now). Verified by walking the AST at IIFE-body depth. If a hook were ever
+// read there it would THROW loudly — see ./host.js — rather than silently misbehave.
+//
+// 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 { setSpeed } from './player-controls.js';
+import { S } from './player-state.js';
+
+(function _installJuceEngineRoutingWatcher() {
+    const juceApi = window.feedBackDesktop?.audio;
+    if (!juceApi || typeof juceApi.isAudioRunning !== 'function') {
+        // Desktop bridge present but audio API incomplete — the whole
+        // exclusive reroute chain is dead and this line is the only witness.
+        // (Docker sphere has no bridge at all: stay silent, nothing to
+        // diagnose there and no debug flag to gate on.)
+        if (window.feedBackDesktop) {
+            console.log('[asio-diag] routing watcher NOT installed (audio api incomplete)');
+        }
+        return;
+    }
+
+    let _rerouteInFlight = false;
+    // URL that JUCE's loadBackingTrack *explicitly rejected* (ok === false —
+    // e.g. a codec it can't read). The poll below would otherwise retry the
+    // same doomed track every 350 ms; remember it and skip until the song
+    // changes. Only a hard JUCE reject is memoised here — transient failures
+    // (a network blip on /api/audio-local-path, an isAudioRunning() race
+    // during a device restart) are deliberately NOT memoised so they retry.
+    let _rerouteRejectedUrl = null;
+    // Exclusive-style output backends silence every other client on the
+    // endpoint — including our own <audio> element. The share mode IS the
+    // JUCE output device type: "Windows Audio (Exclusive Mode)" is a
+    // hardcoded, unlocalised JUCE type name; ASIO drivers typically hold
+    // the endpoint exclusively too. "Windows Audio (Low Latency Mode)" is
+    // shared and must NOT match.
+    function _isExclusiveOutputType(t) {
+        return t === 'Windows Audio (Exclusive Mode)' || t === 'ASIO';
+    }
+    // [feedpak-route] diagnostics: log the raw outputType string once per
+    // value change (this runs on a 350ms poll — logging every tick would
+    // flood the diagnostics buffer).
+    let _loggedOutputType;
+    // [asio-diag] verbose diagnostics, gated on --debug (preload exposes
+    // audio.debugEnabled). Resolved once at install; until it resolves the
+    // flag stays false and verbose lines are skipped. Shared with the
+    // renderer-bus feeder below via window._asioDiagEnabled.
+    let _asioDiag = false;
+    if (typeof juceApi.debugEnabled === 'function') {
+        juceApi.debugEnabled().then((v) => {
+            _asioDiag = !!v;
+            // Deferred install line: the flag resolves async, so logging at
+            // IIFE entry would race it. Change-detection isn't needed — this
+            // runs once per page load.
+            if (_asioDiag) console.log('[asio-diag] routing watcher installed');
+        }).catch(() => {});
+    }
+    window._asioDiagEnabled = () => _asioDiag;
+    async function _outputIsExclusive() {
+        if (typeof juceApi.getCurrentDevice !== 'function') {
+            if (_loggedOutputType !== '<no-getCurrentDevice>') {
+                _loggedOutputType = '<no-getCurrentDevice>';
+                console.warn('[feedpak-route] juceApi.getCurrentDevice missing — cannot detect exclusive output');
+            }
+            return false;
+        }
+        try {
+            const dev = await juceApi.getCurrentDevice();
+            const t = dev?.outputType || dev?.type || '';
+            const excl = _isExclusiveOutputType(t);
+            if (t !== _loggedOutputType) {
+                _loggedOutputType = t;
+                console.log('[feedpak-route] outputType=', JSON.stringify(t), '→ exclusive=', excl);
+                // [asio-diag] full device object on every type change — shows
+                // the exact strings the predicate saw (inputType vs outputType,
+                // device names, duplex), so a driver reporting a non-'ASIO'
+                // type name is visible in tester logs.
+                if (_asioDiag) {
+                    try {
+                        console.log('[asio-diag] getCurrentDevice=', JSON.stringify(dev));
+                    } catch (_) { /* circular/hostile object — skip */ }
+                }
+            }
+            return excl;
+        } catch (e) {
+            if (_loggedOutputType !== '<getCurrentDevice-failed>') {
+                _loggedOutputType = '<getCurrentDevice-failed>';
+                console.warn('[feedpak-route] getCurrentDevice failed:', e);
+            }
+            return false;
+        }
+    }
+    // highway.js's initial song-load routing consults this for the same
+    // feedpak-under-exclusive decision the watcher makes below.
+    window._juceOutputIsExclusive = _outputIsExclusive;
+    // Returns true when window._currentSongAudio no longer references the exact
+    // snapshot object captured at reroute entry — i.e. the song was swapped (or
+    // cleared) mid-flight. Staleness is detected by object-reference identity,
+    // not by URL value.
+    function _isStale(songAudio) {
+        return window._currentSongAudio !== songAudio;
+    }
+
+    // Migrates the loaded song from the HTML5 element onto the JUCE backing
+    // transport. Throws only on transient/unexpected failures.
+    // `songAudio` is the snapshot captured at reroute entry; if it stops being
+    // the current song mid-flight we abort without mutating global routing.
+    // Returns a distinct string outcome — the caller must NOT conflate them:
+    //   'switched' — song now plays via JUCE.
+    //   'rejected' — JUCE hard-rejected the track (codec). Caller memoises it.
+    //   'stale'    — the loaded song changed mid-flight; aborted, NOT memoised.
+    // (a transient transport-start failure throws instead — also not memoised.)
+    async function _switchHtml5ToJuce(songAudio) {
+        const url = songAudio.url;
+        const wasPlaying = S.isPlaying;
+        const pos = audio.currentTime || 0;
+        window.feedBack?.playback?.recordRouteChange?.({
+            routeKind: 'desktop-native',
+            state: 'switching',
+            preservedTime: true,
+            safeReason: 'desktop audio engine became active',
+            requesterId: 'core.juce-route',
+        });
+        // Mark a reroute in progress so the <audio> 'play'/'pause' listeners
+        // suppress their song:play / song:pause emissions: the migration is
+        // transparent — playback genuinely continues — so plugin state and
+        // window.feedBack.isPlaying must NOT flip. This also silences the
+        // "Audio paused unexpectedly" diagnostic. A REFCOUNT (not a boolean)
+        // lets an overlapping reroute's deferred release coexist: each switch
+        // increments on entry and decrements after its own timeout; listeners
+        // treat any count > 0 as "reroute active".
+        window._juceRerouteInProgress = (window._juceRerouteInProgress || 0) + 1;
+        audio.pause();
+        try {
+            const res = await fetch(`/api/audio-local-path?url=${encodeURIComponent(url)}`);
+            if (!res.ok) {
+                console.warn('[feedpak-route] audio-local-path HTTP', res.status, 'for', url);
+                throw new Error('HTTP ' + res.status);
+            }
+            const { path } = await res.json();
+            console.log('[feedpak-route] audio-local-path resolved:', (typeof path === 'string' && path.split(/[\\/]/).pop()) || '<missing>');
+            if (_isStale(songAudio)) return 'stale';   // song changed mid-fetch
+            const ok = await juceApi.loadBackingTrack(path);
+            if (ok === false) {
+                // JUCE rejected the track — stay on HTML5, resume if needed.
+                console.warn('[juce-reroute] loadBackingTrack rejected; staying on HTML5');
+                // Only resume if the element still has a source. In the normal
+                // flow audio.src is intact here, but a prior HTML5→JUCE switch
+                // clears it — re-point + load before resuming so a bounced
+                // reroute doesn't try to play() an empty element.
+                if (S.isPlaying && !_isStale(songAudio)) {
+                    if (!audio.src) { audio.src = url; audio.load(); }
+                    try { await audio.play(); } catch (_) { /* ignore */ }
+                }
+                window.feedBack?.playback?.recordRouteChange?.({
+                    routeKind: 'browser-media',
+                    state: 'degraded',
+                    preservedTime: true,
+                    safeReason: 'desktop audio route rejected track; kept browser media route',
+                    requesterId: 'core.juce-route',
+                });
+                return 'rejected';
+            }
+            if (_isStale(songAudio)) return 'stale';
+            const dur = await juceApi.getBackingDuration();
+            await juceApi.seekBacking(pos);
+            // Start the new transport BEFORE committing global routing state, so
+            // a play() failure can't leave us in "JUCE mode, nothing playing"
+            // (the silent-song state this watcher exists to prevent).
+            // jucePlayer.play() RETURNS false (it does not throw) when
+            // startBacking fails — check the result, don't just await it.
+            // A play() failure is a TRANSIENT transport-start issue, not a hard
+            // codec reject: throw (rather than returning 'rejected') so the
+            // caller's catch path handles it WITHOUT memoising the URL, leaving
+            // it free to retry on the next poll. Only 'rejected' is memoised.
+            // Re-read isPlaying as late as possible: the user can press Pause
+            // during the multi-await fetch/IPC chain above. Starting the JUCE
+            // transport off a stale `wasPlaying` snapshot would resume a song
+            // the user just paused. Only start it if playback is still wanted.
+            if (S.isPlaying) {
+                const started = await host.jucePlayer().play();
+                if (started === false) {
+                    if (!_isStale(songAudio) && S.isPlaying) {
+                        try { await audio.play(); } catch (_) { /* ignore */ }
+                    }
+                    throw new Error('host.jucePlayer().play() failed (transient transport start)');
+                }
+            }
+            if (_isStale(songAudio)) {
+                // Song changed while JUCE was spinning up — undo and bail.
+                await host.jucePlayer().pause().catch(() => {});
+                return 'stale';
+            }
+            if (window.jucePlayer) {
+                host.jucePlayer()._dur = dur;
+                host.jucePlayer()._pos = pos;
+                host.jucePlayer()._pollAt = performance.now();
+            }
+            window._juceMode = true;
+            window._juceAudioUrl = url;
+            const _spSlider = document.getElementById?.('speed-slider');
+            if (_spSlider) setSpeed(_spSlider.value / 100);
+            audio.src = '';
+            try {
+                const apply = window.feedBack?.audio?.applySongVolume;
+                if (typeof apply === 'function') await apply();
+            } catch (_) { /* best-effort */ }
+            console.log('[juce-reroute] HTML5 → JUCE @', pos.toFixed(2), 's playing=', wasPlaying);
+            window.feedBack?.playback?.recordRouteChange?.({
+                routeKind: 'desktop-native',
+                state: 'active',
+                preservedTime: true,
+                safeReason: 'desktop audio route active',
+                requesterId: 'core.juce-route',
+            });
+            return 'switched';
+        } catch (err) {
+            // Path lookup, JSON parse, or a JUCE IPC call threw partway through.
+            // audio.pause() already ran above; restore HTML5 playback so a
+            // previously playing song isn't left silently paused, then re-throw
+            // so the caller logs it. The caller does NOT memoise this URL —
+            // transient failures must retry on the next poll.
+            if (S.isPlaying && !window._juceMode && !_isStale(songAudio)) {
+                if (!audio.src) { audio.src = url; audio.load(); }
+                try { await audio.play(); } catch (_) { /* ignore */ }
+            }
+            window.feedBack?.playback?.recordRouteChange?.({
+                routeKind: 'browser-media',
+                state: 'degraded',
+                preservedTime: true,
+                safeReason: 'desktop audio route failed; kept browser media route',
+                requesterId: 'core.juce-route',
+            });
+            throw err;
+        } finally {
+            // Clearing audio.src above dispatches a 'pause' event in a later
+            // task, after this synchronous finally. Defer the refcount
+            // decrement so that trailing event is still suppressed; a 0ms
+            // timeout lands after the pending pause-event task. Decrementing
+            // (rather than zeroing) leaves any overlapping reroute's own
+            // suppression intact.
+            setTimeout(() => {
+                window._juceRerouteInProgress = Math.max(
+                    0, (window._juceRerouteInProgress || 1) - 1);
+            }, 0);
+        }
+    }
+
+    async function _switchJuceToHtml5(songAudio) {
+        const url = songAudio.url;
+        const wasPlaying = S.isPlaying;
+        const pos = (window.jucePlayer ? host.jucePlayer().currentTime : 0) || 0;
+        window.feedBack?.playback?.recordRouteChange?.({
+            routeKind: 'browser-media',
+            state: 'switching',
+            preservedTime: true,
+            safeReason: 'desktop audio engine stopped',
+            requesterId: 'core.juce-route',
+        });
+        // Mark a reroute in progress (refcount) so the <audio> 'play' listener
+        // suppresses its song:play emission — the migration is transparent and
+        // playback genuinely continues, so plugin state must not flip. Held
+        // until after the (possibly deferred) audio.play() event has fired.
+        window._juceRerouteInProgress = (window._juceRerouteInProgress || 0) + 1;
+        let _suppressionReleased = false;
+        const _releaseSuppression = () => {
+            if (_suppressionReleased) return;
+            _suppressionReleased = true;
+            // Defer so the 'play' (or 'pause') event task fires while still
+            // suppressed; a 0ms timeout lands after it.
+            setTimeout(() => {
+                window._juceRerouteInProgress = Math.max(
+                    0, (window._juceRerouteInProgress || 1) - 1);
+            }, 0);
+        };
+        let _resumeScheduled = false;
+        try {
+            await host.jucePlayer().pause().catch(() => {});
+            if (_isStale(songAudio)) return;           // song changed mid-pause
+            window._juceMode = false;
+            window._juceAudioUrl = null;
+            audio.src = url;
+            audio.load();
+            const _spSlider = document.getElementById?.('speed-slider');
+            if (_spSlider) setSpeed(_spSlider.value / 100);
+            // Resume only AFTER the seek so playback starts at `pos`, not at 0
+            // with an audible jump once metadata arrives.
+            const resumeAtPos = () => {
+                try {
+                    // The metadata event can land after a fast song switch —
+                    // bail before touching currentTime so a stale callback
+                    // doesn't seek the newly loaded song to the old position.
+                    if (_isStale(songAudio)) return;
+                    try { audio.currentTime = pos; } catch (_) { /* ignore */ }
+                    // Re-read isPlaying (not the entry snapshot): the user may
+                    // have pressed Pause during jucePlayer.pause()/metadata
+                    // load — don't resume a song they just paused.
+                    if (S.isPlaying) {
+                        audio.play().catch(() => { /* ignore */ });
+                    }
+                } finally {
+                    _releaseSuppression();
+                }
+            };
+            _resumeScheduled = true;
+            if (audio.readyState >= 1) {
+                resumeAtPos();
+            } else {
+                // Wait for metadata to resume at `pos`. But metadata may never
+                // arrive (bad URL, network error) — that would leak the
+                // suppression refcount and permanently silence song:play /
+                // song:pause. Guard with the element's 'error' event AND a
+                // backstop timeout; whichever fires first wins, the others are
+                // detached. _releaseSuppression is idempotent regardless.
+                let _settled = false;
+                const _onMeta = () => { finish(true); };
+                const _onErr = () => { finish(false); };
+                let _backstop;
+                function finish(reachedMetadata) {
+                    if (_settled) return;
+                    _settled = true;
+                    clearTimeout(_backstop);
+                    audio.removeEventListener('loadedmetadata', _onMeta);
+                    audio.removeEventListener('error', _onErr);
+                    if (reachedMetadata) {
+                        resumeAtPos();             // resumeAtPos releases suppression
+                    } else {
+                        _releaseSuppression();     // no resume — just release
+                    }
+                }
+                audio.addEventListener('loadedmetadata', _onMeta, { once: true });
+                audio.addEventListener('error', _onErr, { once: true });
+                // 10s is well beyond a normal local-file metadata load.
+                _backstop = setTimeout(() => { finish(false); }, 10000);
+            }
+        } finally {
+            // resumeAtPos owns the release once scheduled; if we returned
+            // early (stale, before scheduling) release here instead.
+            // _releaseSuppression is idempotent so an overlap is harmless.
+            if (!_resumeScheduled) _releaseSuppression();
+        }
+        try {
+            const apply = window.feedBack?.audio?.applySongVolume;
+            if (typeof apply === 'function') await apply();
+        } catch (_) { /* best-effort */ }
+        console.log('[juce-reroute] JUCE → HTML5 @', pos.toFixed(2), 's playing=', wasPlaying);
+        window.feedBack?.playback?.recordRouteChange?.({
+            routeKind: 'browser-media',
+            state: 'active',
+            preservedTime: true,
+            safeReason: 'browser media route active',
+            requesterId: 'core.juce-route',
+        });
+    }
+
+    async function _reevaluateJuceRouting() {
+        if (_rerouteInFlight) return;
+        const songAudio = window._currentSongAudio;
+        // /audio/ songs are always JUCE-routable. A feedpak full-mix
+        // (single-mix pack, no stems) is routable ONLY under an
+        // exclusive-style output — in shared mode it must stay on HTML5 so
+        // the stem mixer / WebAudio path keeps working. Sloppak stem URLs
+        // are never routable (per-stem mix can't ride a single transport).
+        if (!songAudio || (!songAudio.juceEligible && !songAudio.feedpakFullMix)) return;
+        // Don't race highway.js's own initial song-load routing: it owns
+        // _juceMode until _juceRoutingPromise settles. Re-running our switch
+        // concurrently would double-call loadBackingTrack for the same URL.
+        if (window._highwayJuceRoutingPending) return;
+
+        // Claim the in-flight guard SYNCHRONOUSLY, before the first await. The
+        // watcher is driven by a 350ms setInterval; if isAudioRunning() (or any
+        // later await) stalls past the poll period, a second tick would
+        // otherwise pass the `if (_rerouteInFlight) return` check above and run
+        // a concurrent switch — duplicate loadBackingTrack IPCs racing on
+        // _juceMode / audio.src. Setting it here closes that window.
+        _rerouteInFlight = true;
+        try {
+            let running;
+            try { running = await juceApi.isAudioRunning(); }
+            catch (_) { return; }
+            if (_isStale(songAudio)) return;               // song changed during IPC
+            // Eligibility is evaluated per tick, not snapshotted at song load:
+            // the output share mode can change mid-song (device switch in the
+            // Audio Engine panel), and a feedpak full-mix must follow it —
+            // exclusive → ride the engine; back to shared → return to HTML5.
+            let eligible = !!songAudio.juceEligible;
+            if (!eligible && songAudio.feedpakFullMix && running) {
+                eligible = await _outputIsExclusive();
+                if (_isStale(songAudio)) return;           // song changed during IPC
+            }
+            const wantJuce = !!(running && eligible);
+            // [feedpak-route] diagnostics: one line per decision change (the
+            // watcher polls at 350ms; steady state must not spam the buffer).
+            const _decision = 'running=' + running + ' eligible=' + eligible
+                + ' feedpakFullMix=' + !!songAudio.feedpakFullMix
+                + ' juceMode=' + !!window._juceMode + ' url=' + songAudio.url;
+            if (_decision !== window._lastFeedpakRouteDecision) {
+                window._lastFeedpakRouteDecision = _decision;
+                console.log('[feedpak-route] watcher:', _decision);
+            }
+            if (wantJuce === !!window._juceMode) return;   // routing already consistent
+            // Don't keep retrying a track JUCE explicitly rejected.
+            if (wantJuce && songAudio.url === _rerouteRejectedUrl) return;
+
+            if (wantJuce) {
+                const outcome = await _switchHtml5ToJuce(songAudio);
+                // Memoise ONLY an explicit hard JUCE reject. A successful
+                // switch clears the memo; a 'stale' abort (song changed
+                // mid-flight) leaves it untouched — it must never be
+                // misclassified as a reject, even if the song object was
+                // swapped and then restored before this point.
+                if (outcome === 'rejected') {
+                    _rerouteRejectedUrl = songAudio.url;
+                } else if (outcome === 'switched') {
+                    _rerouteRejectedUrl = null;
+                }
+                // outcome === 'stale': leave _rerouteRejectedUrl as-is.
+            } else {
+                await _switchJuceToHtml5(songAudio);
+                // The engine stopped (or a feedpak's output left exclusive
+                // mode). Clear any hard-reject memo so a later engine restart
+                // or mode change re-evaluates the track at least once — the
+                // rejection may have been a transient device/decoder state.
+                _rerouteRejectedUrl = null;
+            }
+        } catch (e) {
+            // Transient failure — log but do NOT memoise, so the next poll retries.
+            console.warn('[juce-reroute] re-route failed (will retry):', e);
+        } finally {
+            _rerouteInFlight = false;
+        }
+    }
+    window._reevaluateJuceRouting = _reevaluateJuceRouting;
+
+    // Clears the hard-reject memo. Called from the song-teardown sites that
+    // null window._currentSongAudio (showScreen, playSong) so that reloading
+    // the same file later gets a fresh routing attempt — a prior reject may
+    // have been a transient JUCE/device state, not a permanent codec issue.
+    window._clearJuceRerouteMemo = function () { _rerouteRejectedUrl = null; };
+
+    // The engine can be started/stopped from several places (the desktop Audio
+    // Engine panel, the audio_engine plugin, note_detect) and via setDevice
+    // restarts — and the contextBridge api object is frozen, so its methods
+    // can't be wrapped. Poll isAudioRunning() while a song is loaded; the check
+    // is a cheap IPC boolean and no-ops once routing is already consistent.
+    // Skip the poll while the document is hidden (background tab / minimised
+    // window) — engine toggles there will be reconciled on the first poll
+    // after the tab is visible again.
+    setInterval(() => {
+        if (document.hidden) return;
+        if (window._currentSongAudio) void _reevaluateJuceRouting();
+    }, 350);
+})();
+
+// Renderer-audio bus feeder (desktop Phase 2): when the engine holds the
+// output endpoint in an exclusive-style mode, Chromium cannot reach the
+// device, so any song audio still played by the renderer goes silent. The
+// Phase 1 watcher above already migrates what a single-file transport can
+// carry (loose /audio/ songs, feedpak full-mixes) onto the native backing
+// transport. This feeder covers the rest — the stems plugin's multi-stem
+// WebAudio graph, plus <audio>-element songs the native transport could not
+// take (e.g. a codec loadBackingTrack rejected).
+//
+// Mechanism: capture the renderer-side master with an AudioWorklet tap,
+// re-point the owning AudioContext at a null sink so it keeps rendering
+// without a device, and push ~10 ms chunks over IPC into the engine's
+// renderer bus, where they are mixed into the exclusive output like a
+// backing track (~10-20 ms added latency on song audio only; the guitar
+// monitoring path is untouched). Validated by the fix12 tester spike:
+// null-sink rendering works, clocks hold (drift → 0), no overflow.
+//
+// Docker sphere: window.feedBackDesktop is undefined → this whole block is
+// inert. Shared-mode desktop: the bus stays disabled (no double audio) and
+// captured contexts keep/regain their default sink.
+(function _installRendererBusFeeder() {
+    const api = window.feedBackDesktop?.audio;
+    if (!api || typeof api.setRendererBus !== 'function'
+             || typeof api.pushRendererAudio !== 'function') {
+        // Silent in the Docker sphere (no bridge, no debug flag); a desktop
+        // bridge missing the bus API is the diagnostic case.
+        if (window.feedBackDesktop) {
+            console.log('[asio-diag] renderer-bus feeder NOT installed (api=' + !!api
+                + ' setRendererBus=' + typeof api?.setRendererBus
+                + ' pushRendererAudio=' + typeof api?.pushRendererAudio + ')');
+        }
+        return;
+    }
+    // Deferred like the watcher's install line: gate on the async debug flag.
+    if (typeof api.debugEnabled === 'function') {
+        api.debugEnabled().then((v) => {
+            if (v) console.log('[asio-diag] renderer-bus feeder installed (loopback-capable='
+                + (typeof window.navigator?.mediaDevices?.getDisplayMedia === 'function') + ')');
+        }).catch(() => {});
+    }
+
+    const TAP_WORKLET = `
+        class FeedbackBusTap extends AudioWorkletProcessor {
+            process(inputs) {
+                const inp = inputs[0];
+                if (inp && inp[0]) {
+                    const L = inp[0], R = inp[1] || inp[0];
+                    const out = new Float32Array(L.length * 2);
+                    for (let i = 0; i < L.length; i++) { out[i*2] = L[i]; out[i*2+1] = R[i]; }
+                    this.port.postMessage(out, [out.buffer]);
+                }
+                return true;
+            }
+        }
+        registerProcessor('feedback-bus-tap', FeedbackBusTap);
+    `;
+    const _tapModuleUrl = URL.createObjectURL(new Blob([TAP_WORKLET], { type: 'application/javascript' }));
+    const _tapModuleLoaded = new WeakSet();   // AudioContexts with the module added
+
+    // One tap per captured graph. `active` gates the push (the worklet keeps
+    // running when inactive — it's silent bookkeeping, not audio).
+    function _makeTap(ctx) {
+        const state = { node: null, active: false, batch: [], batchFrames: 0 };
+        state.attach = async (sourceNode) => {
+            if (!_tapModuleLoaded.has(ctx)) {
+                await ctx.audioWorklet.addModule(_tapModuleUrl);
+                _tapModuleLoaded.add(ctx);
+            }
+            if (!state.node) {
+                state.node = new AudioWorkletNode(ctx, 'feedback-bus-tap', { numberOfInputs: 1, channelCount: 2 });
+                const BATCH = Math.round(ctx.sampleRate / 100);   // ~10 ms
+                state.node.port.onmessage = (e) => {
+                    if (!state.active) { state.batch = []; state.batchFrames = 0; return; }
+                    state.batch.push(e.data);
+                    state.batchFrames += e.data.length / 2;
+                    if (state.batchFrames >= BATCH) {
+                        const merged = new Float32Array(state.batchFrames * 2);
+                        let o = 0;
+                        for (const c of state.batch) { merged.set(c, o); o += c.length; }
+                        api.pushRendererAudio(merged, ctx.sampleRate);
+                        state.batch = []; state.batchFrames = 0;
+                    }
+                };
+            }
+            sourceNode.connect(state.node);
+            // No onward connection: the tap is a sink-side observer; audibility
+            // in shared mode comes from the graph's own destination path.
+        };
+        state.detach = (sourceNode) => {
+            state.active = false;
+            state.batch = []; state.batchFrames = 0;
+            if (state.node && sourceNode) {
+                try { sourceNode.disconnect(state.node); } catch (_) { /* already gone */ }
+            }
+        };
+        return state;
+    }
+
+    // ── Core <audio> element capture ─────────────────────────────────────────
+    // createMediaElementSource permanently reroutes the element into its
+    // context, so it is created lazily — only the first time an exclusive
+    // device actually needs it — and never torn down. From then on the element
+    // always plays through _elCtx; sink toggling routes it to the speakers
+    // (shared mode) or the null sink + bus (exclusive mode).
+    let _elCtx = null, _elSource = null, _elTap = null;
+    async function _ensureElementCapture() {
+        if (_elCtx) return;
+        const el = document.getElementById('audio');
+        if (!el) throw new Error('no core audio element');
+        // Assign the module state ONLY after the whole chain succeeded.
+        // createMediaElementSource throws InvalidStateError when another
+        // consumer (highway_3d's analyser tap) already owns the element's
+        // one-shot source — assigning _elCtx before that throw poisoned every
+        // later tick into `_elTap.active` TypeErrors (tester log 2026-07-11)
+        // while the song kept playing on the default device.
+        const ctx = new AudioContext();
+        let source, tap;
+        try {
+            source = ctx.createMediaElementSource(el);
+            source.connect(ctx.destination);
+            tap = _makeTap(ctx);
+            await tap.attach(source);
+        } catch (e) {
+            try { await ctx.close(); } catch (_) { /* already closed */ }
+            throw e;
+        }
+        _elCtx = ctx; _elSource = source; _elTap = tap;
+    }
+
+    // ── Whole-app loopback capture ───────────────────────────────────────────
+    // Preferred mode: one getDisplayMedia frame-audio capture covers EVERY
+    // sound the app makes (song, previews, UI) — no per-surface taps, so
+    // plugin-private AudioContexts (song-preview, future plugins) survive
+    // exclusive/ASIO output too. The desktop main process answers the request
+    // with this window's own frame (frame-scoped — no other apps' audio).
+    // Local playback is silenced via the suppressLocalAudioPlayback track
+    // constraint, with a page-mute IPC fallback (capture taps frame audio
+    // before the output mute, so a muted page still feeds the stream).
+    let _lbStream = null, _lbCtx = null, _lbTap = null, _lbPageMuted = false;
+    let _loopbackUnavailable = false;   // sticky: probe once, then fall back
+    async function _engageLoopback() {
+        const stream = await navigator.mediaDevices.getDisplayMedia({
+            video: true,
+            audio: { suppressLocalAudioPlayback: true },
+        });
+        for (const t of stream.getVideoTracks()) t.stop();   // required, unused
+        const track = stream.getAudioTracks()[0];
+        if (!track) {
+            for (const t of stream.getTracks()) t.stop();
+            throw new Error('no loopback audio track');
+        }
+        try {
+            // Fresh context per session (not reused) so teardown's close()
+            // fully releases the tap worklet node — see _teardownLoopback.
+            _lbCtx = new AudioContext();
+            if (_lbCtx.state !== 'running') await _lbCtx.resume().catch(() => {});
+            const source = _lbCtx.createMediaStreamSource(stream);
+            const tap = _makeTap(_lbCtx);
+            await tap.attach(source);
+            const suppressed = track.getSettings?.().suppressLocalAudioPlayback === true;
+            if (!suppressed && typeof api.setPageMuted === 'function') {
+                _lbPageMuted = (await api.setPageMuted(true)) === true;
+            }
+            if (window._asioDiagEnabled?.()) {
+                console.log('[asio-diag] loopback: suppressed=', suppressed,
+                    'pageMuted=', _lbPageMuted, 'rate=', _lbCtx.sampleRate);
+            }
+            await api.setRendererBus(true, 1.0);
+            tap.active = true;
+            _lbStream = stream; _lbTap = tap;
+            _mode = 'loopback';
+            console.log('[renderer-bus] engaged: app loopback → engine bus');
+        } catch (e) {
+            for (const t of stream.getTracks()) t.stop();
+            throw e;
+        }
+    }
+    async function _teardownLoopback() {
+        if (_lbTap) _lbTap.active = false;
+        if (_lbStream) for (const t of _lbStream.getTracks()) t.stop();
+        _lbStream = null; _lbTap = null;
+        // Close the capture context so its tap worklet node is released. The
+        // context is per-session (not reused): without this, each exclusive⇄
+        // shared switch orphaned a live worklet on a long-lived context.
+        if (_lbCtx) {
+            try { await _lbCtx.close(); } catch (_) { /* already closed */ }
+            _lbCtx = null;
+        }
+        if (_lbPageMuted && typeof api.setPageMuted === 'function') {
+            try { await api.setPageMuted(false); } catch (_) { /* engine gone */ }
+        }
+        _lbPageMuted = false;
+    }
+
+    // ── Engagement state machine ─────────────────────────────────────────────
+    // 'off' | 'loopback' | 'element' | 'stems' (element/stems = fallback when
+    // loopback capture is unavailable: old desktop main, denied capture)
+    let _mode = 'off';
+    let _stemsGraph = null;   // { context, masterNode } snapshot while engaged
+    let _stemsTap = null;
+    const _stemsTaps = new WeakMap();  // context → tap (stems ctx is reused across songs)
+    let _busy = false;
+
+    async function _setSink(ctx, exclusive) {
+        if (typeof ctx.setSinkId !== 'function') throw new Error('setSinkId unsupported');
+        await ctx.setSinkId(exclusive ? { type: 'none' } : '');
+        if (ctx.state !== 'running') await ctx.resume().catch(() => {});
+        // [asio-diag] a context left on the default sink while the bus is
+        // engaged is exactly the "song on the wrong device" symptom — record
+        // every successful sink flip (failures throw and are logged upstream).
+        if (window._asioDiagEnabled?.()) {
+            console.log('[asio-diag] setSink:', exclusive ? 'null-sink' : 'default',
+                'state=', ctx.state, 'rate=', ctx.sampleRate);
+        }
+    }
+
+    async function _disengage() {
+        if (_mode === 'off') return;
+        const prev = _mode;
+        _mode = 'off';
+        try { await api.setRendererBus(false, 0); } catch (_) { /* engine gone */ }
+        if (prev === 'loopback') {
+            await _teardownLoopback();
+        } else if (prev === 'element' && _elCtx) {
+            _elTap.active = false;
+            await _setSink(_elCtx, false).catch(() => {});
+        } else if (prev === 'stems' && _stemsGraph) {
+            if (_stemsTap) _stemsTap.detach(_stemsGraph.masterNode);
+            await _setSink(_stemsGraph.context, false).catch(() => {});
+            _stemsGraph = null; _stemsTap = null;
+        }
+        console.log('[renderer-bus] disengaged (' + prev + ')');
+    }
+
+    async function _engageStems(graph) {
+        await _setSink(graph.context, true);
+        let tap = _stemsTaps.get(graph.context);
+        if (!tap) { tap = _makeTap(graph.context); _stemsTaps.set(graph.context, tap); }
+        await tap.attach(graph.masterNode);
+        await api.setRendererBus(true, 1.0);
+        tap.active = true;
+        _stemsGraph = graph; _stemsTap = tap;
+        _mode = 'stems';
+        console.log('[renderer-bus] engaged: stems graph → engine bus');
+    }
+
+    async function _engageElement() {
+        await _ensureElementCapture();
+        await _setSink(_elCtx, true);
+        await api.setRendererBus(true, 1.0);
+        _elTap.active = true;
+        _mode = 'element';
+        console.log('[renderer-bus] engaged: <audio> element → engine bus');
+    }
+
+    async function _reevaluate() {
+        if (_busy) return;
+        _busy = true;
+        try {
+            let running = false, exclusive = false;
+            try {
+                running = await api.isAudioRunning();
+            } catch (_) { /* engine unreachable → treat as not running */ }
+            if (running) {
+                // Reuse the Phase 1 predicate installed by the routing watcher
+                // (getCurrentDevice + exclusive-type check with change-logged
+                // diagnostics). Fail closed if it is somehow absent.
+                exclusive = !!(await window._juceOutputIsExclusive?.());
+            }
+
+            // The stems plugin publishes its live graph while a multi-stem
+            // song is loaded (and removes it on teardown).
+            const stems = (window.feedBack || window.slopsmith)?.stems?.audioGraph || null;
+            // Element songs: a song is loaded, it is NOT riding the native
+            // transport (Phase 1 owns those), and the stems graph is not the
+            // player. Covers native-transport rejects (codec) in exclusive
+            // mode — without this they would be silent.
+            const songAudio = window._currentSongAudio;
+            const elementSong = !!songAudio && !window._juceMode && !stems;
+
+            let want = 'off';
+            if (running && exclusive) {
+                // Loopback covers ALL app audio (song, previews, UI), so it
+                // engages for the whole exclusive session — not just while a
+                // song is loaded. Per-surface modes remain as fallback when
+                // loopback capture is unavailable (old desktop main without
+                // the display-media handler, capture denied).
+                if (!_loopbackUnavailable) want = 'loopback';
+                else if (stems) want = 'stems';
+                else if (elementSong) want = 'element';
+            }
+            // Song audio riding the native transport must not ALSO ride the
+            // loopback (double-carry into the same engine output). The native
+            // transport plays from the engine, not the page, so page loopback
+            // never hears it — no conflict; loopback stays engaged for
+            // previews/UI while the transport owns the song.
+
+            // [asio-diag] full decision vector, change-gated (500ms poll —
+            // steady state must not flood the buffer). This is the feeder-side
+            // counterpart of the watcher's [feedpak-route] decision line: it
+            // shows WHY the bus did or didn't engage (exclusive predicate,
+            // stems graph presence, native transport ownership, element song).
+            if (window._asioDiagEnabled?.()) {
+                const d = 'running=' + running + ' exclusive=' + exclusive
+                    + ' stems=' + !!stems + ' songAudio=' + !!songAudio
+                    + ' juceMode=' + !!window._juceMode
+                    + ' elementSong=' + elementSong
+                    + ' loopbackUnavailable=' + _loopbackUnavailable
+                    + ' want=' + want + ' mode=' + _mode;
+                if (d !== window._lastRendererBusDecision) {
+                    window._lastRendererBusDecision = d;
+                    console.log('[asio-diag] renderer-bus:', d);
+                }
+            }
+
+
+            const stemsGraphChanged = _mode === 'stems' && stems !== _stemsGraph;
+            if (want !== _mode || stemsGraphChanged) {
+                await _disengage();
+                try {
+                    if (want === 'loopback') await _engageLoopback();
+                    else if (want === 'stems') await _engageStems(stems);
+                    else if (want === 'element') await _engageElement();
+                } catch (e) {
+                    if (want === 'loopback') {
+                        // Capture unavailable (no handler in an old desktop
+                        // main, permission denied) — remember and fall back to
+                        // the per-surface modes on the next tick.
+                        _loopbackUnavailable = true;
+                        console.warn('[renderer-bus] loopback capture unavailable — falling back to surface taps:', e);
+                    }
+                    throw e;
+                }
+            }
+        } catch (e) {
+            // Explicit name/message/stack head — the console-message forward
+            // stringifies a DOMException to the useless "[object DOMException]".
+            console.warn('[renderer-bus] reevaluate failed (will retry):',
+                (e && e.name ? e.name + ': ' + e.message : String(e)),
+                (e && e.stack ? '| ' + String(e.stack).split('\n')[1] : ''));
+            _mode = 'off';
+            // A partial engage may have left the bus enabled with no producer
+            // and the page muted — undo both so a failed tick can't strand
+            // audio in silence until the next successful engage.
+            try { await api.setRendererBus(false, 0); } catch (_) { /* engine gone */ }
+            await _teardownLoopback().catch(() => {});
+        } finally {
+            _busy = false;
+        }
+    }
+
+    // Same cadence/rationale as the routing watcher above. Also re-check on
+    // visibility return so a device switch made while hidden is reconciled.
+    setInterval(() => { if (!document.hidden) void _reevaluate(); }, 500);
+    document.addEventListener('visibilitychange', () => { if (!document.hidden) void _reevaluate(); });
+    window._reevaluateRendererBus = _reevaluate;
+})();
+
+// Desktop JUCE backing uses an empty <audio> element; plugins such as Section Map
+// still seek via audio.currentTime / pause / play. Mirror those onto jucePlayer
+// while _juceMode is active. Same-tick pause+seek coalesce into a single seek
+// (no stopBacking before seek — HTML5 needed that for buffering; JUCE does not).
+export let _resetJuceAudioShimChain = function () {};
+(function _installJuceAudioElementShim() {
+    if (!window.feedBackDesktop?.audio) return;
+
+    const mediaProto = HTMLMediaElement.prototype;
+    const ctDesc = Object.getOwnPropertyDescriptor(mediaProto, 'currentTime');
+    const pausedDesc = Object.getOwnPropertyDescriptor(mediaProto, 'paused');
+    if (!ctDesc?.get || !ctDesc?.set || !pausedDesc?.get) return;
+
+    const nativePlay = mediaProto.play;
+    const nativePause = mediaProto.pause;
+
+    let chain = Promise.resolve();
+    /** Same-tick pause + seek (Section Map): coalesce to one seek — no stopBacking before seek. */
+    let _juceShimBatch = null;
+    let _juceShimBatchFlushScheduled = false;
+    let _juceShimGen = 0;
+    function enqueue(fn) {
+        const gen = _juceShimGen;
+        const p = chain.then(async () => {
+            if (gen !== _juceShimGen) return;
+            return fn(gen);
+        });
+        chain = p.catch((e) => {
+            console.warn('[juce-audio-shim]', e);
+        });
+        return p;
+    }
+    // forUpcomingPlay: caller will enqueue a play() right after, so don't
+    // emit pause-state side effects for a wantsPause batch — play() will
+    // overwrite them anyway.
+    function flushJuceShimBatchNow({ forUpcomingPlay = false } = {}) {
+        _juceShimBatchFlushScheduled = false;
+        const batch = _juceShimBatch;
+        _juceShimBatch = null;
+        if (!batch || !window._juceMode) return;
+        const wantsPause = !!batch.wantsPause;
+        const seekTime = batch.seekTime;
+        if (wantsPause && seekTime !== undefined) {
+            enqueue(async (gen) => {
+                const r = await host._audioSeek(seekTime, 'audio-element-shim');
+                if (!r.completed) return; // seek cancelled by teardown
+                if (gen !== _juceShimGen) return;
+                if (!forUpcomingPlay) {
+                    await host.jucePlayer().pause();
+                    if (gen !== _juceShimGen) return;
+                    S.isPlaying = false;
+                    host.setPlayButtonState(false);
+                    const sm = window.feedBack;
+                    if (sm) {
+                        sm.isPlaying = false;
+                        sm.emit('song:pause', host._songEventPayload());
+                    }
+                }
+                audio.dispatchEvent(new Event('seeked'));
+            });
+            return;
+        }
+        if (wantsPause) {
+            enqueue(async (gen) => {
+                await host.jucePlayer().pause();
+                if (gen !== _juceShimGen) return;
+                S.isPlaying = false;
+                host.setPlayButtonState(false);
+                const sm = window.feedBack;
+                if (sm) {
+                    sm.isPlaying = false;
+                    sm.emit('song:pause', host._songEventPayload());
+                }
+            });
+            return;
+        }
+        if (seekTime !== undefined) {
+            enqueue(async (gen) => {
+                const r = await host._audioSeek(seekTime, 'audio-element-shim');
+                if (!r.completed) return; // seek cancelled by teardown
+                if (gen !== _juceShimGen) return;
+                audio.dispatchEvent(new Event('seeked'));
+            });
+        }
+    }
+    function scheduleJuceShimBatchFlush() {
+        if (_juceShimBatchFlushScheduled) return;
+        _juceShimBatchFlushScheduled = true;
+        const flushGen = _juceShimGen;
+        queueMicrotask(() => {
+            if (flushGen !== _juceShimGen) {
+                _juceShimBatchFlushScheduled = false;
+                return;
+            }
+            flushJuceShimBatchNow();
+        });
+    }
+    _resetJuceAudioShimChain = function () {
+        chain = Promise.resolve();
+        _juceShimBatch = null;
+        _juceShimBatchFlushScheduled = false;
+        _juceShimGen++;
+    };
+
+    Object.defineProperty(audio, 'currentTime', {
+        get() {
+            if (window._juceMode) return host.jucePlayer().currentTime;
+            return ctDesc.get.call(this);
+        },
+        set(v) {
+            if (window._juceMode) {
+                const t = Math.max(0, Number(v) || 0);
+                _juceShimBatch = _juceShimBatch || {};
+                _juceShimBatch.seekTime = t;
+                scheduleJuceShimBatchFlush();
+                return;
+            }
+            ctDesc.set.call(this, v);
+        },
+        configurable: true,
+    });
+
+    Object.defineProperty(audio, 'paused', {
+        get() {
+            if (window._juceMode) return !S.isPlaying;
+            return pausedDesc.get.call(this);
+        },
+        configurable: true,
+    });
+
+    audio.pause = function () {
+        if (window._juceMode) {
+            _juceShimBatch = _juceShimBatch || {};
+            _juceShimBatch.wantsPause = true;
+            scheduleJuceShimBatchFlush();
+            return;
+        }
+        nativePause.call(audio);
+    };
+
+    audio.play = function () {
+        if (window._juceMode) {
+            if (_juceShimBatch != null) flushJuceShimBatchNow({ forUpcomingPlay: true });
+            const p = enqueue(async (gen) => {
+                const started = await host.jucePlayer().play();
+                if (gen !== _juceShimGen || !started) return;
+                S.isPlaying = true;
+                host.setPlayButtonState(true);
+                const sm = window.feedBack;
+                if (sm) {
+                    sm.isPlaying = true;
+                    const payload = host._songEventPayload();
+                    sm.emit('song:play', payload);
+                    sm.emit('song:resume', payload);
+                }
+            });
+            return p.then(() => undefined);
+        }
+        return nativePlay.call(audio);
+    };
+})();
diff --git a/static/js/player-state.js b/static/js/player-state.js
index c708e02..793c042 100644
--- a/static/js/player-state.js
+++ b/static/js/player-state.js
@@ -31,4 +31,12 @@ export const S = {
      * land where it was asked to (JUCE can clamp; HTML5 can round).
      */
     lastAudioTime: 0,
+
+    /**
+     * A resume request armed by playSong({ resume }) and consumed on song:ready.
+     * Written by app.js (playSong, and the song:ready listener that consumes it) and
+     * read by the resume-session module — so, like the two above, it cannot be a plain
+     * export.
+     */
+    pendingResume: null,
 };
diff --git a/static/js/resume-session.js b/static/js/resume-session.js
new file mode 100644
index 0000000..5e15d37
--- /dev/null
+++ b/static/js/resume-session.js
@@ -0,0 +1,157 @@
+// Resume last session — the snapshot taken when you leave a song, and the pill that
+// offers it back.
+//
+// The fifth slice out of app.js's strongly-connected core. Small and self-contained:
+// ONE hook (playSong) plus a currentFilename getter.
+//
+// The armed resume request itself lives on the shared container as S.pendingResume,
+// not here, because app.js WRITES it — playSong({ resume }) arms it and the song:ready
+// listener consumes it — while this module reads it. An imported binding is read-only,
+// so shared mutable state has to live on the container. Same reason isPlaying does.
+//
+// See ./host.js: reading an unwired hook THROWS, and tests/js/host_contract.test.js
+// fails CI if the hooks used here and the hooks app.js wires ever drift apart.
+import { host } from './host.js';
+import { _curPlaybackSpeed } from './player-controls.js';
+import { S } from './player-state.js';
+
+// ── Resume last session ────────────────────────────────────────────────────
+// Leaving a song snapshots where you were — song, arrangement, position, and
+// speed — so an exit (especially an accidental one, now that Escape reliably
+// leaves regardless of focus) is recoverable instead of restarting from bar 1.
+// The snapshot is offered back through a non-blocking "Resume" pill; it never
+// gates, blocks, or auto-acts. Cleared on natural song-end and once consumed.
+// (This is the player-session slice; the broader nav/state-resume work — e.g.
+// returning to a song after wandering into Settings → Tone Builder — is a
+// separate, larger track.)
+const _RESUME_KEY = 'feedBack.resumeSession';
+const _RESUME_MAX_AGE_MS = 24 * 60 * 60 * 1000;   // a day-old snapshot is stale
+const _RESUME_MIN_POSITION_S = 3;                  // ignore barely-started songs
+const _RESUME_END_GUARD_S = 5;                      // ignore basically-finished songs
+let _resumePillDismissed = false;                   // per-session: user waved off the current snapshot
+
+// Snapshot the live session. Called from showScreen()'s teardown before
+// highway.stop()/audio unload, while getSongInfo() + position are still valid.
+export function _snapshotResumeSession(position) {
+    try {
+        if (!host.currentFilename()) return;
+        const si = (window.highway && typeof highway.getSongInfo === 'function')
+            ? (highway.getSongInfo() || {}) : {};
+        const dur = Number(si.duration) || 0;
+        const pos = Number(position) || 0;
+        // Only worth resuming a song you were genuinely mid-way through — not a
+        // glance at the first seconds, and not one that already basically ended.
+        if (pos < _RESUME_MIN_POSITION_S) { _clearResumeSession(); return; }
+        if (dur && pos > dur - _RESUME_END_GUARD_S) { _clearResumeSession(); return; }
+        const snap = {
+            f: host.currentFilename(),
+            a: (typeof si.arrangement_index === 'number' && si.arrangement_index >= 0)
+                ? si.arrangement_index : undefined,
+            t: pos,
+            sp: _curPlaybackSpeed(),
+            title: si.title || '',
+            artist: si.artist || '',
+            ts: Date.now(),
+        };
+        localStorage.setItem(_RESUME_KEY, JSON.stringify(snap));
+        // A fresh snapshot earns one offer — undo any earlier dismissal.
+        _resumePillDismissed = false;
+    } catch (_) { /* storage unavailable — resume is best-effort */ }
+}
+
+export function _readResumeSession() {
+    try {
+        const raw = localStorage.getItem(_RESUME_KEY);
+        if (!raw) return null;
+        const snap = JSON.parse(raw);
+        if (!snap || !snap.f || !(Number(snap.t) > 0)) return null;
+        if (!snap.ts || Date.now() - snap.ts > _RESUME_MAX_AGE_MS) { _clearResumeSession(); return null; }
+        return snap;
+    } catch (_) { return null; }
+}
+
+export function _clearResumeSession() {
+    try { localStorage.removeItem(_RESUME_KEY); } catch (_) {}
+}
+
+// Re-enter the snapshotted song and restore arrangement + position + speed.
+export async function resumeLastSession() {
+    const snap = _readResumeSession();
+    if (!snap) { _hideResumePill(); return false; }
+    _hideResumePill();
+    try {
+        await host.playSong(snap.f, snap.a, {
+            resume: { position: Number(snap.t) || 0, speed: Number(snap.sp) || 1 },
+        });
+    } catch (err) {
+        // A transient load/connect failure must not strand the user: keep the
+        // snapshot so the pill can re-offer it on the next non-player screen,
+        // rather than consuming the only copy before the song actually loaded.
+        console.warn('[app] resume failed to load; keeping snapshot:', err);
+        S.pendingResume = null;
+        return false;
+    }
+    _clearResumeSession();   // consumed only after a successful load
+    return true;
+}
+
+// ── Resume pill (non-blocking "continue where you left off") ────────────────
+// Self-contained, inline-styled, body-appended so it works identically in the
+// classic (v2) and v3 shells with no Tailwind rebuild. It only ever appears off
+// the player screen, never blocks, and a dismiss forgets the current snapshot
+// for the session.
+export function _hideResumePill() {
+    const el = document.getElementById('fb-resume-pill');
+    if (el) el.remove();
+}
+
+export function _maybeShowResumePill() {
+    const active = document.querySelector('.screen.active');
+    if (active && active.id === 'player') { _hideResumePill(); return; }
+    if (_resumePillDismissed) return;
+    const snap = _readResumeSession();
+    if (!snap) { _hideResumePill(); return; }
+    if (document.getElementById('fb-resume-pill')) return;   // already shown
+
+    const label = (snap.title || decodeURIComponent(snap.f || 'your last song')).toString();
+    const pill = document.createElement('div');
+    pill.id = 'fb-resume-pill';
+    pill.setAttribute('role', 'status');
+    pill.style.cssText = [
+        'position:fixed', 'left:16px', 'bottom:16px', 'z-index:120',
+        'display:flex', 'align-items:center', 'gap:10px',
+        'max-width:min(90vw,360px)', 'padding:10px 12px',
+        'background:rgba(17,24,39,0.96)', 'color:#e5e7eb',
+        'border:1px solid rgba(148,163,184,0.25)', 'border-radius:10px',
+        'box-shadow:0 6px 24px rgba(0,0,0,0.4)',
+        'font:13px/1.3 system-ui,-apple-system,"Segoe UI",Roboto,sans-serif',
+    ].join(';');
+
+    const text = document.createElement('div');
+    text.style.cssText = 'flex:1;min-width:0';
+    const t1 = document.createElement('div');
+    t1.textContent = 'Resume practice';
+    t1.style.cssText = 'font-weight:600;color:#fff';
+    const t2 = document.createElement('div');
+    t2.textContent = label;
+    t2.style.cssText = 'opacity:0.7;white-space:nowrap;overflow:hidden;text-overflow:ellipsis';
+    text.appendChild(t1); text.appendChild(t2);
+
+    const resumeBtn = document.createElement('button');
+    resumeBtn.type = 'button';
+    resumeBtn.textContent = 'Resume ▸';
+    resumeBtn.style.cssText = 'flex:none;padding:6px 10px;border:0;border-radius:7px;background:#4080e0;color:#fff;font-weight:600;cursor:pointer';
+    resumeBtn.addEventListener('click', () => { resumeLastSession(); });
+
+    const dismissBtn = document.createElement('button');
+    dismissBtn.type = 'button';
+    dismissBtn.setAttribute('aria-label', 'Dismiss');
+    dismissBtn.textContent = '✕';
+    dismissBtn.style.cssText = 'flex:none;padding:4px 6px;border:0;border-radius:7px;background:transparent;color:#9ca3af;cursor:pointer;font-size:14px';
+    dismissBtn.addEventListener('click', () => { _resumePillDismissed = true; _hideResumePill(); });
+
+    pill.appendChild(text);
+    pill.appendChild(resumeBtn);
+    pill.appendChild(dismissBtn);
+    (document.body || document.documentElement).appendChild(pill);
+}
diff --git a/tests/js/juce_engine_reroute.test.js b/tests/js/juce_engine_reroute.test.js
index 7c1b2b5..51a55ea 100644
--- a/tests/js/juce_engine_reroute.test.js
+++ b/tests/js/juce_engine_reroute.test.js
@@ -1,4 +1,4 @@
-// Behavioral tests for the JUCE engine-reroute watcher in static/app.js.
+// Behavioral tests for the JUCE engine-reroute watcher in static/js/juce-audio.js.
 //
 // The watcher (an IIFE, `_installJuceEngineRoutingWatcher`) migrates a loaded
 // song between the HTML5 <audio> element and the native JUCE backing transport
@@ -14,14 +14,15 @@ const fs = require('node:fs');
 const path = require('node:path');
 const vm = require('node:vm');
 
-const APP_JS = path.join(__dirname, '..', '..', 'static', 'app.js');
+// The JUCE audio shims were carved out of app.js into their own module (R3a).
+const APP_JS = path.join(__dirname, '..', '..', 'static', 'js', 'juce-audio.js');
 
 // Brace-balanced extraction of the watcher IIFE, starting at its `(function`
 // and ending after the matching `})();`.
 function extractWatcherIIFE(src) {
     const marker = '(function _installJuceEngineRoutingWatcher() {';
     const start = src.indexOf(marker);
-    assert.ok(start !== -1, 'watcher IIFE not found in app.js');
+    assert.ok(start !== -1, 'watcher IIFE not found in static/js/juce-audio.js');
     const openBrace = src.indexOf('{', start);
     let depth = 1;
     let i = openBrace + 1;
@@ -100,6 +101,17 @@ function makeSandbox({ isAudioRunning, loadBackingTrack, outputType = 'Windows A
 
     const src = fs.readFileSync(APP_JS, 'utf8');
     const iife = extractWatcherIIFE(src);
+    // The shims reach back into app.js through the host seam (static/js/host.js).
+    // Route it at the SAME stubs this sandbox already had — a fresh `() => {}` would
+    // swallow the calls and the assertions below would pass vacuously.
+    sandbox.host = {
+        jucePlayer: () => sandbox.jucePlayer,
+        playSong: (...a) => (sandbox.playSong ? sandbox.playSong(...a) : undefined),
+        _audioSeek: (...a) => (sandbox._audioSeek ? sandbox._audioSeek(...a) : Promise.resolve({ completed: true })),
+        setPlayButtonState: (...a) => (sandbox.setPlayButtonState ? sandbox.setPlayButtonState(...a) : undefined),
+        _songEventPayload: (...a) => (sandbox._songEventPayload ? sandbox._songEventPayload(...a) : ({})),
+        showScreen: (...a) => (sandbox.showScreen ? sandbox.showScreen(...a) : undefined),
+    };
     vm.createContext(sandbox);
     vm.runInContext(iife, sandbox);
     return sandbox;
diff --git a/tests/js/renderer_bus_feeder.test.js b/tests/js/renderer_bus_feeder.test.js
index 1500816..d582510 100644
--- a/tests/js/renderer_bus_feeder.test.js
+++ b/tests/js/renderer_bus_feeder.test.js
@@ -1,4 +1,4 @@
-// Behavioral tests for the renderer-audio bus feeder in static/app.js.
+// Behavioral tests for the renderer-audio bus feeder in static/js/juce-audio.js.
 //
 // The feeder (an IIFE, `_installRendererBusFeeder`) captures renderer-side
 // song audio (stems-plugin WebAudio master, or the core <audio> element) and
@@ -16,12 +16,13 @@ const fs = require('node:fs');
 const path = require('node:path');
 const vm = require('node:vm');
 
-const APP_JS = path.join(__dirname, '..', '..', 'static', 'app.js');
+// The JUCE audio shims were carved out of app.js into their own module (R3a).
+const APP_JS = path.join(__dirname, '..', '..', 'static', 'js', 'juce-audio.js');
 
 function extractFeederIIFE(src) {
     const marker = '(function _installRendererBusFeeder() {';
     const start = src.indexOf(marker);
-    assert.ok(start !== -1, 'feeder IIFE not found in app.js');
+    assert.ok(start !== -1, 'feeder IIFE not found in static/js/juce-audio.js');
     const openBrace = src.indexOf('{', start);
     let depth = 1;
     let i = openBrace + 1;
@@ -123,6 +124,17 @@ function makeSandbox({ isAudioRunning = () => true, exclusive = () => true, disp
     sandbox.globalThis = sandbox;
 
     const src = fs.readFileSync(APP_JS, 'utf8');
+    // The shims reach back into app.js through the host seam (static/js/host.js).
+    // Route it at the SAME stubs this sandbox already had — a fresh `() => {}` would
+    // swallow the calls and the assertions below would pass vacuously.
+    sandbox.host = {
+        jucePlayer: () => sandbox.jucePlayer,
+        playSong: (...a) => (sandbox.playSong ? sandbox.playSong(...a) : undefined),
+        _audioSeek: (...a) => (sandbox._audioSeek ? sandbox._audioSeek(...a) : Promise.resolve({ completed: true })),
+        setPlayButtonState: (...a) => (sandbox.setPlayButtonState ? sandbox.setPlayButtonState(...a) : undefined),
+        _songEventPayload: (...a) => (sandbox._songEventPayload ? sandbox._songEventPayload(...a) : ({})),
+        showScreen: (...a) => (sandbox.showScreen ? sandbox.showScreen(...a) : undefined),
+    };
     vm.createContext(sandbox);
     vm.runInContext(extractFeederIIFE(src), sandbox);
     assert.equal(typeof sandbox.window._reevaluateRendererBus, 'function',
diff --git a/tests/test_plugin_runtime_idempotence.py b/tests/test_plugin_runtime_idempotence.py
index e72aca3..8d6dc9e 100644
--- a/tests/test_plugin_runtime_idempotence.py
+++ b/tests/test_plugin_runtime_idempotence.py
@@ -189,9 +189,13 @@ def test_app_event_bus_dispatches_locally_and_preserves_juce_stop_state():
     # `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
 
+    # The JUCE audio-element shim — which re-emits song:resume through the session
+    # manager when JUCE owns the transport — was carved out into its own module (R3a).
+    juce = (ROOT / "static" / "js" / "juce-audio.js").read_text(encoding="utf-8")
+    assert "sm.emit('song:resume', payload)" in juce
+
 
 def test_nam_and_stems_use_owner_claim_dispatch_semantics():
     nam_source = _sibling_text("feedBack-plugin-nam-tone", "screen.js", "NAM_STEM_CLAIM_ID = 'nam.amp-active'")