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

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

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

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

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

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

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

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

static/app.js

@@ -41,6 +41,30 @@ import {
 } from './js/settings-io.js';
 import { audio } from './js/audio-el.js';
 import { S } from './js/player-state.js';
+import {
+    _clearResumeSession,
+    _hideResumePill,
+    _maybeShowResumePill,
+    _readResumeSession,
+    _snapshotResumeSession,
+    resumeLastSession,
+} from './js/resume-session.js';
+
+import {
+    _applyMastery,
+    _applyMasteryAvailability,
+    _autoplayExitEnabled,
+    _countdownBeforeSongEnabled,
+    _curPlaybackSpeed,
+    _exitConfirmEnabled,
+    _resetPlaybackSpeedForNewSong,
+    _showUpNextEnabled,
+    _wireSpeedPresetsOnce,
+    applySpeedPreset,
+    setMastery,
+    setSpeed,
+} from './js/player-controls.js';
+
 import {
     _cancelCountIn,
     armCreditsHideOnPlay,
@@ -5170,15 +5194,6 @@ document.addEventListener('visibilitychange', () => {
     }
 });
 
-// ── Autoplay & auto-exit (global option, default ON) ──────────────────
-// One toggle (`autoplayExit` in localStorage) that (a) auto-starts a song
-// once it's ready and (b) returns to the launching menu when the song
-// ends. Absence of the key means enabled. The behaviour lives in core
-// (app.js, shared by the v3 + classic UIs); the end-of-song *score*
-// screen, when present, is a plugin and hooks the contract below.
-function _autoplayExitEnabled() {
-    try { return localStorage.getItem('autoplayExit') !== '0'; } catch (_) { return true; }
-}
 // Settings checkbox setter (onchange="setAutoplayExit(this.checked)").
 window.setAutoplayExit = function (on) {
     try { localStorage.setItem('autoplayExit', on ? '1' : '0'); } catch (_) { /* private mode */ }
@@ -5191,15 +5206,6 @@ Object.defineProperty(window.feedBack, 'autoplayExit', {
     get: _autoplayExitEnabled, configurable: true,
 });
 
-// ── "Up Next" pill (global option, default ON) ────────────────────────
-// Gates the v3 player chrome's persistent upcoming-section pill
-// (#v3-upnext, driven by player-chrome.js's updateUpNext). Client-only
-// localStorage pref (`showUpNext`); absence of the key means enabled.
-// player-chrome.js reads window.feedBack.showUpNext each tick and hides
-// the pill when off.
-function _showUpNextEnabled() {
-    try { return localStorage.getItem('showUpNext') !== '0'; } catch (_) { return true; }
-}
 // Settings checkbox setter (onchange="setShowUpNext(this.checked)").
 window.setShowUpNext = function (on) {
     try { localStorage.setItem('showUpNext', on ? '1' : '0'); } catch (_) { /* private mode */ }
@@ -5217,12 +5223,6 @@ Object.defineProperty(window.feedBack, 'showUpNext', {
     get: _showUpNextEnabled, configurable: true,
 });
 
-// "Countdown before song" (Gameplay tab). Mirrored to localStorage by
-// loadSettings so the song-start path can read it synchronously here — no
-// async /api/settings fetch on the play hot path. Defaults off.
-function _countdownBeforeSongEnabled() {
-    try { return localStorage.getItem('countdownBeforeSong') === '1'; } catch (_) { return false; }
-}
 // Settings checkbox setter (onchange="setCountdownBeforeSong(this.checked)").
 // Writes localStorage for the synchronous read above AND persists to the
 // server so it survives a reload / rides along in the settings export bundle.
@@ -5362,94 +5362,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
 
-function _curPlaybackSpeed() {
-    try {
-        return window._juceMode
-            ? ((window.jucePlayer && window.jucePlayer._speed) || 1)
-            : (document.getElementById('audio')?.playbackRate || 1);
-    } catch (_) { return 1; }
-}
 
-// 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;
 
@@ -5457,9 +5374,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');
@@ -5476,66 +5393,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).
@@ -5725,10 +5583,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();
@@ -6088,15 +5946,6 @@ window.feedBack.playQueue = (function () {
     if (window.feedBack) window.feedBack.closeCurrentSong = queueAwareClose;
 })();
 
-// ── "Ask before leaving a song" (Gameplay tab, default OFF) ────────────────
-// Client-only localStorage pref (`confirmExitSong`); absence = OFF. When ON, a
-// *user-initiated* exit (Escape, or the player ✕) opens a small confirm instead
-// of leaving immediately. Auto-exit on song-end and a results screen's own
-// Close never prompt — they call closeCurrentSong() directly, which stays the
-// unguarded actual-exit.
-function _exitConfirmEnabled() {
-    try { return localStorage.getItem('confirmExitSong') === '1'; } catch (_) { return false; }
-}
 // Settings checkbox setter (onchange="setConfirmExitSong(this.checked)").
 window.setConfirmExitSong = function (on) {
     try { localStorage.setItem('confirmExitSong', on ? '1' : '0'); } catch (_) { /* private mode */ }
@@ -6217,175 +6066,13 @@ function _openExitConfirm() {
 }
 window._openExitConfirm = _openExitConfirm;   // exposed for tests/debugging
 
-const SPEED_PRESET_PCTS = [100, 90, 80, 75, 70, 60, 50];
-const SPEED_SNAP_THRESHOLD = 0.02;
-let _speedPresetsWired = false;
 
-function _speedPresetPctFromActive(activePctOrRate) {
-    if (!Number.isFinite(activePctOrRate)) return null;
-    const rate = activePctOrRate <= 1.5 ? activePctOrRate : activePctOrRate / 100;
-    for (const pct of SPEED_PRESET_PCTS) {
-        if (Math.abs(rate - pct / 100) <= SPEED_SNAP_THRESHOLD) return pct;
-    }
-    return null;
-}
 
-function _updateSpeedPresetButtons(activePctOrRate) {
-    const wrap = document.getElementById('speed-presets');
-    if (!wrap) return;
-    const target = _speedPresetPctFromActive(activePctOrRate);
-    for (const btn of wrap.querySelectorAll('[data-speed-preset]')) {
-        const pct = Number(btn.dataset.speedPreset);
-        btn.classList.toggle('v3-speed-preset-active', target !== null && pct === target);
-    }
-}
 
-function applySpeedPreset(percent) {
-    const slider = document.getElementById('speed-slider');
-    if (!slider) return;
-    const pct = Math.max(
-        Number(slider.min) || 15,
-        Math.min(Number(slider.max) || 150, Number(percent)),
-    );
-    if (!Number.isFinite(pct)) return;
-    slider.value = String(pct);
-    handleSliderInput(slider);
-    slider.dispatchEvent(new Event('input', { bubbles: true }));
-}
 window.applySpeedPreset = applySpeedPreset;
 
-function _wireSpeedPresetsOnce() {
-    if (_speedPresetsWired) return;
-    const presets = document.getElementById('speed-presets');
-    if (!presets) return;
-    _speedPresetsWired = true;
-    presets.addEventListener('click', (e) => {
-        const btn = e.target.closest('[data-speed-preset]');
-        if (!btn) return;
-        applySpeedPreset(Number(btn.dataset.speedPreset));
-    });
-}
 
-function setSpeed(v) {
-    const speedSlider = document.getElementById('speed-slider');
-    const rate = Number(v);
-    if (!Number.isFinite(rate)) {
-        return;
-    }
-    if (window._juceMode) {
-        window.jucePlayer?.setRate(rate);
-        const juceAudio = window.feedBackDesktop?.audio;
-        Promise.resolve()
-            .then(() => juceAudio?.setBackingSpeed(rate))
-            // Match the HTML5 path: preserve pitch on the JUCE backing track too.
-            // Optional-chained call is a no-op on desktop builds that predate
-            // setBackingPreservePitch, so this is safe to ship unconditionally.
-            .then(() => juceAudio?.setBackingPreservePitch?.(true))
-            .catch(err => console.warn('[setSpeed] backing speed/preserve-pitch failed:', err));
-    } else {
-        audio.playbackRate = rate;
-    }
-    const speedLabel = document.getElementById('speed-label');
-    if (speedLabel) speedLabel.textContent = rate.toFixed(2) + 'x';
-    handleSliderInput(speedSlider);
-    _updateSpeedPresetButtons(rate);
-}
 
-function _resetPlaybackSpeedForNewSong() {
-    // Reset the *actual* playback rate to 1x, not just the visible slider/label
-    // (feedBack#615). The HTML5 <audio> element and the desktop JUCE/backing
-    // engine each retain their own rate, and which one drives the next song
-    // isn't decided until later in the load, so reset all paths unconditionally.
-    // Every setter is idempotent and optional-chained, so this is safe in web
-    // and desktop builds alike — no need to branch on window._juceMode.
-    const speedSlider = document.getElementById('speed-slider');
-    if (speedSlider) speedSlider.value = 100;
-    audio.playbackRate = 1;
-    window.jucePlayer?.setRate?.(1);
-    const juceAudio = window.feedBackDesktop?.audio;
-    Promise.resolve()
-        .then(() => juceAudio?.setBackingSpeed?.(1))
-        .then(() => juceAudio?.setBackingPreservePitch?.(true))
-        .catch(err => console.warn('[resetSpeed] backing speed/preserve-pitch failed:', err));
-    // Mirror setSpeed's UI side-effects (label text + slider fill styling).
-    const speedLabel = document.getElementById('speed-label');
-    if (speedLabel) speedLabel.textContent = (1).toFixed(2) + 'x';
-    handleSliderInput(speedSlider);
-    _updateSpeedPresetButtons(100);
-}
-// Master-difficulty slider (feedBack#48). Persists partial via
-// /api/settings — the POST handler merges only the keys present, so
-// this fire-and-forget call doesn't clobber dlc_dir or other settings.
-//
-// Debounced trailing-edge (300ms) so dragging the slider — which fires
-// oninput per pixel — doesn't flood the server with concurrent writes
-// to config.json. highway.setMastery() still fires every oninput so
-// the chart re-filters in real time; only disk persistence waits.
-let _masteryPersistTimer = null;
-function _persistMastery(pct) {
-    if (_masteryPersistTimer) clearTimeout(_masteryPersistTimer);
-    _masteryPersistTimer = setTimeout(() => {
-        _masteryPersistTimer = null;
-        fetch('/api/settings', {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ master_difficulty: pct }),
-        }).catch(() => { /* best-effort — next setMastery() will retry */ });
-    }, 300);
-}
-function setMastery(v) {
-    _applyMastery(v);
-}
-// Shared mastery applier. Master difficulty has two controls that write the
-// same master_difficulty key: the player-popover slider (#mastery-slider) and
-// the Gameplay-tab "Note highway speed" slider (#setting-highway-speed). Route
-// both — and loadSettings' hydration — through here so their positions,
-// labels, and track fills stay in sync regardless of which the user touches,
-// plus the live highway re-filter and the debounced persist. All element reads
-// are null-guarded since either control may be absent (follower window, or the
-// settings markup not yet rendered).
-function _applyMastery(v, opts = {}) {
-    // Guard + clamp: v might be a slider string, a programmatic call from a
-    // plugin, or a restored settings value with a bad shape. Don't let NaN
-    // reach a label (would show "NaN%") or the POST.
-    const parsed = parseInt(v, 10);
-    if (!Number.isFinite(parsed)) return;
-    const pct = Math.max(0, Math.min(100, parsed));
-    const popLabel = document.getElementById('mastery-label');
-    if (popLabel) popLabel.textContent = pct + '%';
-    const popSlider = document.getElementById('mastery-slider');
-    if (popSlider) {
-        if (String(popSlider.value) !== String(pct)) popSlider.value = pct;
-        handleSliderInput(popSlider);
-    }
-    const setSlider = document.getElementById('setting-highway-speed');
-    if (setSlider) {
-        if (String(setSlider.value) !== String(pct)) setSlider.value = pct;
-        handleSliderInput(setSlider);
-    }
-    // The Gameplay-tab label markup appends a literal "%" after this span
-    // (matching the av-offset "ms" pattern), so write the number alone here —
-    // unlike #mastery-label above, whose markup carries no trailing unit.
-    const setLabel = document.getElementById('setting-highway-speed-val');
-    if (setLabel) setLabel.textContent = pct;
-    highway.setMastery(pct / 100);
-    if (!opts.skipPersist) _persistMastery(pct);
-}
-// Reflect phrase-data availability on the slider after every `ready`.
-// The server omits the `phrases` message entirely for single-level
-// sources (GP imports, legacy sloppak), so hasPhraseData() is the
-// right signal to enable/disable the slider.
-function _applyMasteryAvailability(hasPhraseData) {
-    const slider = document.getElementById('mastery-slider');
-    if (!slider) return;
-    if (hasPhraseData) {
-        slider.disabled = false;
-        slider.title = 'Master difficulty — low = simpler chart, high = full';
-    } else {
-        slider.disabled = true;
-        slider.title = 'Source chart has a single difficulty level — slider disabled';
-    }
-}
 if (window.feedBack) {
     window.feedBack.on('song:loaded', syncDefaultArrangementPin);
     window.feedBack.on('arrangement:changed', syncDefaultArrangementPin);
@@ -7860,6 +7547,8 @@ configureHost({
     setPlayButtonState,
     _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,

static/js/player-controls.js

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

static/js/player-state.js

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

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);
+}

tests/js/autoplay_exit.test.js

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

tests/js/speed_reset.test.js

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