feat(player): global autoplay & auto-exit option (songs + lessons) (#558)

* fix(v3): pedal click opens the plugin's screen, not its settings The v3 Pedalboard's settingsTarget() resolved settings-first, so a plugin that ships both a screen and a settings panel (notably the bundled Audio Engine) could only ever reach its settings from the pedalboard — its actual page was unreachable. Flip to screen-first (stompbox metaphor: step on the pedal, see the pedal), falling back to settings when there is no screen. Keep a settings fallback in openPluginSettings() when a declared screen isn't mounted yet (installing/failed) so settings-bearing plugins are never stranded on a toast. Drive the pedal aria-label off the same target so it never promises the wrong surface. Update the unit test contract to screen > settings > none. Fixes #555 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(player): global autoplay & auto-exit option (songs + lessons) Single Settings toggle (autoplayExit, default ON) that auto-starts a song once it's ready and returns to the launching menu when it ends. Auto-exit defers while a results/score overlay is on top (heuristic + holdAutoExit() contract) so a scoring plugin's screen drives the exit. Player origin is now context-aware (lessons return to the lessons screen via setReturnScreen()), fixing lesson completion bouncing to the library. Core-only; songs and lessons share the playSong -> highway path. Adds a read-only window.slopsmith.autoplayExit getter + holdAutoExit()/setReturnScreen() for plugins. Unit tests for the pure helpers (_autoplayExitEnabled, _resolvePlayerOrigin, _resultsOverlayVisible). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-08-11 03:09:57 +00:00 · 2026-06-22 11:04:03 +02:00
parent f79efe2516
commit 4dc5936712
7 changed files with 369 additions and 14 deletions
@@ -0,0 +1,186 @@
+// Verify the autoplay & auto-exit option's pure decision helpers in app.js:
+//   - _autoplayExitEnabled()  (localStorage; absence = enabled)
+//   - _resolvePlayerOrigin()  (one-shot override → launch screen → 'home')
+//
+// Same isolation strategy as song_close.test.js — extract the function from
+// app.js by brace-matching and run it in a vm sandbox with stubbed deps.
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+
+const { extractFunction } = require('./test_utils');
+
+const APP_JS = path.join(__dirname, '..', '..', 'static', 'app.js');
+const SRC = fs.readFileSync(APP_JS, 'utf8');
+
+function runEnabled(stored) {
+    const fnSrc = extractFunction(SRC, 'function _autoplayExitEnabled(');
+    const sandbox = {
+        localStorage: {
+            getItem: () => {
+                if (stored === '__throw__') throw new Error('private mode');
+                return stored;
+            },
+        },
+    };
+    vm.createContext(sandbox);
+    vm.runInContext(fnSrc + '\nglobalThis.__r = _autoplayExitEnabled();', sandbox);
+    return sandbox.__r;
+}
+
+// Fake element honoring the bits _resultsOverlayVisible() inspects.
+function el({ id = '', hidden = false, visible = true } = {}) {
+    return {
+        id,
+        classList: { contains: (c) => c === 'hidden' && hidden },
+        getClientRects: () => (visible ? [{}] : []),
+    };
+}
+
+function runOverlay(nodes) {
+    const fnSrc = extractFunction(SRC, 'function _resultsOverlayVisible(');
+    const sandbox = { document: { querySelectorAll: () => nodes } };
+    vm.createContext(sandbox);
+    vm.runInContext(fnSrc + '\nglobalThis.__r = _resultsOverlayVisible();', sandbox);
+    return sandbox.__r;
+}
+
+function runResolve({ override = null, screens = [], active = null } = {}) {
+    const fnSrc = extractFunction(SRC, 'function _resolvePlayerOrigin(');
+    const sandbox = {
+        window: { slopsmith: { _nextReturnScreen: override } },
+        document: {
+            getElementById: (id) => (screens.includes(id) ? { id } : null),
+            querySelector: () => (active ? { id: active } : null),
+        },
+    };
+    vm.createContext(sandbox);
+    vm.runInContext(fnSrc + '\nglobalThis.__r = _resolvePlayerOrigin();', sandbox);
+    return { result: sandbox.__r, override: sandbox.window.slopsmith._nextReturnScreen };
+}
+
+// holdAutoExit() + _clearAutoExit() share module state; assemble them in one
+// sandbox to exercise the generation guard on the returned release handle.
+function buildHoldSandbox() {
+    const clearSrc = extractFunction(SRC, 'function _clearAutoExit(');
+    const holdSrc = extractFunction(SRC, 'window.slopsmith.holdAutoExit = function ()');
+    const sandbox = { __closeCount: 0 };
+    sandbox.window = { slopsmith: {}, closeCurrentSong: () => { sandbox.__closeCount++; } };
+    vm.createContext(sandbox);
+    vm.runInContext(`
+        var _autoExitTimer = null;
+        var _autoExitHeld = false;
+        var _autoExitGen = 0;
+        function clearTimeout() {}
+        ${clearSrc}
+        ${holdSrc}
+        globalThis.__clearAutoExit = _clearAutoExit;
+        globalThis.__hold = window.slopsmith.holdAutoExit;
+    `, sandbox);
+    return sandbox;
+}
+
+test('hold release navigates once while the generation is current', () => {
+    const sb = buildHoldSandbox();
+    const release = sb.__hold();
+    release();
+    assert.equal(sb.__closeCount, 1);
+    release(); // idempotent
+    assert.equal(sb.__closeCount, 1);
+});
+
+test('a stale hold release no-ops after the session moves on', () => {
+    const sb = buildHoldSandbox();
+    const release = sb.__hold();
+    sb.__clearAutoExit(); // new playSong / song:ended bumps the generation
+    release();
+    assert.equal(sb.__closeCount, 0, 'stale release must not navigate');
+});
+
+// ── _autoplayExitEnabled ──────────────────────────────────────────────
+test('autoplayExit defaults ON when the key is absent', () => {
+    assert.equal(runEnabled(null), true);
+});
+
+test('autoplayExit is OFF only for the explicit "0"', () => {
+    assert.equal(runEnabled('0'), false);
+    assert.equal(runEnabled('1'), true);
+    assert.equal(runEnabled('anything'), true);
+});
+
+test('autoplayExit falls back to ON when localStorage throws', () => {
+    assert.equal(runEnabled('__throw__'), true);
+});
+
+// ── _resultsOverlayVisible ────────────────────────────────────────────
+test('no overlays → not visible', () => {
+    assert.equal(runOverlay([]), false);
+});
+
+test('a visible modal overlay defers auto-exit', () => {
+    assert.equal(runOverlay([el({ id: 'mg-summary' })]), true);
+});
+
+test('a hidden (.hidden) overlay does not defer', () => {
+    assert.equal(runOverlay([el({ id: 'mg-summary', hidden: true })]), false);
+});
+
+test('a display:none overlay (no client rects) does not defer', () => {
+    assert.equal(runOverlay([el({ id: 'mg-summary', visible: false })]), false);
+});
+
+test('the player screen itself never counts as a results overlay', () => {
+    assert.equal(runOverlay([el({ id: 'player' })]), false);
+});
+
+test('mixed: ignores player + hidden, honors a visible results overlay', () => {
+    assert.equal(runOverlay([
+        el({ id: 'player' }),
+        el({ id: 'stale', hidden: true }),
+        el({ id: 'score-card' }),
+    ]), true);
+});
+
+// ── _resolvePlayerOrigin ──────────────────────────────────────────────
+test('one-shot override wins and is consumed when its screen exists', () => {
+    const { result, override } = runResolve({
+        override: 'v3-lessons', screens: ['v3-lessons', 'plugin-tutorials'], active: 'plugin-tutorials',
+    });
+    assert.equal(result, 'v3-lessons');
+    assert.equal(override, null); // consumed, even though it won
+});
+
+test('override is ignored (and still consumed) when its screen is missing', () => {
+    const { result, override } = runResolve({
+        override: 'ghost-screen', screens: ['favorites'], active: 'favorites',
+    });
+    assert.equal(result, 'favorites');
+    assert.equal(override, null);
+});
+
+test('remembers the real launch screen', () => {
+    assert.equal(runResolve({ screens: ['v3-lessons'], active: 'v3-lessons' }).result, 'v3-lessons');
+    assert.equal(runResolve({ screens: ['favorites'], active: 'favorites' }).result, 'favorites');
+});
+
+test('dashboard launches (classic home + v3-home) return to the Songs list', () => {
+    assert.equal(runResolve({ screens: ['home', 'v3-songs'], active: 'home' }).result, 'v3-songs');
+    assert.equal(runResolve({ screens: ['v3-home', 'v3-songs'], active: 'v3-home' }).result, 'v3-songs');
+});
+
+test('v3-home falls back to itself when there is no Songs list (defensive)', () => {
+    assert.equal(runResolve({ screens: ['v3-home'], active: 'v3-home' }).result, 'v3-home');
+});
+
+test('classic v2 (no #v3-songs) keeps home', () => {
+    assert.equal(runResolve({ screens: ['home'], active: 'home' }).result, 'home');
+});
+
+test('player / unknown / no active screen fall back to home', () => {
+    assert.equal(runResolve({ screens: ['player'], active: 'player' }).result, 'home');
+    assert.equal(runResolve({ screens: [], active: 'plugin-x' }).result, 'home');
+    assert.equal(runResolve({ screens: [], active: null }).result, 'home');
+});