feat(v3): add "Add to playlist" to a song's ⋮ More menu (#625)

* feat(v3): add "Add to playlist" to a song's ⋮ More menu

You could only add a song to a playlist via select-mode (checkbox → batch bar).
Add an "Add to playlist" row to each song card's ⋮ overflow menu that targets
that one song, reusing the same picker (pick a listed number or type a new name
to create the playlist).

The select-mode batch flow and the single-song menu now share one extracted
`addFilenamesToPlaylist(filenames)` helper; the menu is `openCardMenu`, shared by
grid cards and tree rows, so both views get it. Tests:
tests/js/v3_add_to_playlist_menu.test.js.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QbexxfTt8q2tAn436MqGWF

* fix(v3): don't clear the batch selection when the playlist picker is cancelled

The extract-helper refactor made batchAddToPlaylist() call finishBatch()
unconditionally, so cancelling (or a failed create) cleared the multi-select
and reloaded the grid — a regression from the original early-return-on-cancel
behaviour. addFilenamesToPlaylist() already returns null on cancel/failure;
gate finishBatch() on a truthy playlist id so the selection is preserved for
a retry. Adds a regression assertion.

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

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: byrongamatos <xasiklas@gmail.com>

CHANGELOG.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- **v3 Songs: "Add to playlist" is now on each song's ⋮ "More" menu.** Previously a song could only be added to a playlist through select-mode (the checkbox → batch bar). The per-card overflow menu now has an **Add to playlist** row that targets that one song, reusing the same picker (choose a listed number or type a new name to create it). The select-mode batch flow and the single-song menu now share one extracted `addFilenamesToPlaylist(filenames)` helper in `static/v3/songs.js` (both grid and tree rows, since they share `openCardMenu`). Tests: `tests/js/v3_add_to_playlist_menu.test.js`.
 - **Resume where you left off — leaving a song now snapshots your place so an exit is recoverable, not a restart-from-zero.** Exiting the player (`showScreen()` teardown, before audio unload) writes `{song, arrangement, position, speed}` to `localStorage` (`feedBack.resumeSession`), and a non-blocking **"Resume practice"** pill offers it back on the next non-player screen (and on the next app launch). Clicking Resume re-enters the song, restores the arrangement + playback speed, and seeks to the saved position via the existing `_audioSeek` funnel; `playSong()` gains a `{ resume: {position, speed} }` option that arms a `song:ready`-consumed restore instead of the normal autostart, so the two never fight over playback. The snapshot is deliberately conservative — ignored for a song you barely started (< 3s) or had basically finished (within 5s of the end), cleared on natural song-end and once consumed, and expired after 24h. The pill is self-contained (inline-styled, body-appended, works identically in the classic and v3 shells with no Tailwind rebuild), never blocks, and a dismiss forgets the current snapshot for the session. This pairs with the Escape focus fix: now that Escape reliably leaves regardless of focus, an *accidental* exit is one tap to undo. Public surface: `window.resumeLastSession()` / `window.feedBack.resumeLastSession`. (The broader nav-state work — returning to a song after wandering into Settings → Tone Builder — is a separate, larger track; this lands the player-session slice.) Tests: `tests/browser/resume-session.spec.ts` (snapshot guards, staleness, pill show/hide/dismiss, resume consumption).
 - **Optional "Ask before leaving a song" confirm (Gameplay tab, default OFF).** A new client-only toggle (`confirmExitSong` in `localStorage`, in the v3 Gameplay settings + the Gameplay "Reset" set) for players who want a guard against an accidental exit. **Off by default — Escape leaves instantly, zero change for everyone else.** When on, a *user-initiated* exit (the player-scope Escape shortcut, or the player's ✕) opens a small true-modal confirm instead of leaving; auto-exit on song-end and a results screen's own Close are unaffected (they call `closeCurrentSong()` directly, which stays the unguarded actual-exit). The confirm honors the team's refined asks: **opening it pauses the song** (so it isn't running or being scored behind the prompt) and **Stay resumes exactly what was paused**; **Escape = Stay** — the dialog's capture-phase handler *dismisses* it (now consistent with every other modal and the generic `_confirmDialog`'s Esc=cancel), so a second Escape returns you to the (resumed) song rather than leaving; **Space/Enter (or click) Leave** by natively activating the default-focused "Leave" button ("just get me out"). Pause/resume run through the canonical `togglePlay()` path (HTML5 + `_juceMode`), guarded so a count-in, an already-paused song, or a teardown/seek/end behind the modal can't mis-resume. It's a real modal (`role="dialog" aria-modal="true"` / `.feedBack-modal`) with **Tab trapped inside it** and a **backdrop click that also Stays**, so the Escape/Space focus carve-outs treat it as a trap and don't fire player-back / play-pause behind it. The player Escape shortcut and the v3 ✕ route through a shared `window.requestExitSong()` gate (the ✕ also becomes origin-aware, matching Escape). Tests: `tests/browser/exit-confirm.spec.ts` (default-off instant exit, confirm-on opens + stays, second-Escape stays, backdrop stays, Stay/Leave, Enter-leaves); the audio pause/resume is verified manually on web + desktop (the mock song has no backing track).
 - **Folder Library — a bundled core plugin (`plugins/folder_library/`) that browses the DLC library by its on-disk folder tree.** Surfaces top-level folders → subfolders → songs (root-level songs land in `(Unsorted)`), with in-app folder management (create / rename / delete nested folders), song moves via dialog or drag-and-drop, and sort/filter that mirrors the host library's filter state. Wired into both the classic (v2) library toolbar and the v3 Songs page as a third **Folders** view alongside grid/tree; the plugin's `screen.js` is loaded once by the host and reused (idempotent IIFEs). Supersedes the former standalone "Folder Organizer" community plugin (removed from the README list). Backend (`routes.py`) registers `/api/plugins/folder_library/{tree,folder/create,folder/rename,folder/delete,song/move}`; **all filesystem mutations are confined to `DLC_DIR` and validated against path traversal** (per-segment name validation plus a resolved-containment check on `song/move`), and folder deletion relocates every song — de-duplicating colliding names — so a name clash never destroys a song. A two-level cache keeps re-opening folders fast. Tests: `tests/plugins/folder_library/test_routes.py` (path-safety helpers + move-traversal and delete-no-data-loss end-to-end).

static/v3/songs.js

@@ -495,6 +495,7 @@
         menu.className = 'v3-card-menu absolute top-10 right-2 z-30 min-w-[10rem] bg-fb-card border border-fb-border/60 rounded-lg shadow-xl py-1 text-sm';
         const rows = [
             { id: '__play', label: 'Play', run: () => { _saveLibraryScrollSnapshot(); window.playSong && window.playSong(enc(song.filename)); } },
+            { id: '__playlist', label: 'Add to playlist' },
             ...items.map((a) => ({ id: a.id, label: a.label, destructive: a.destructive, enabled: a.enabled, plugin: a.pluginId })),
         ];
         menu.innerHTML = rows.map((r) =>
@@ -514,6 +515,7 @@
             const id = b.getAttribute('data-act');
             closeMenu();
             if (id === '__play') { playCard(song); return; }
+            if (id === '__playlist') { await addFilenamesToPlaylist([song.filename]); return; }
             if (reg) await reg.run(id, song, { source: 'v3-songs' });
         }));
         setTimeout(() => document.addEventListener('click', closer), 0);
@@ -612,26 +614,42 @@
         finishBatch();
     }
 
-    async function batchAddToPlaylist() {
+    // Prompt for a target playlist (pick a listed number, or type a new name to
+    // create it) and add the given song filenames to it. Shared by the
+    // select-mode batch bar and the per-card ⋮ menu's single-song add. Returns
+    // the playlist id (or null if cancelled).
+    async function addFilenamesToPlaylist(filenames) {
+        const fns = Array.from(filenames || []);
+        if (!fns.length) return null;
         const lists = (await jget('/api/playlists')) || [];
         const choices = lists.filter((p) => !p.system_key);
         const labels = choices.map((p, i) => (i + 1) + '. ' + p.name).join('   ');
         const ans = ((await window.uiPrompt({
-            title: 'Add ' + state.selected.size + ' song(s) to a playlist',
+            title: 'Add ' + fns.length + ' song' + (fns.length === 1 ? '' : 's') + ' to a playlist',
             label: (labels ? labels + ' ' : '') + 'Type a number above, or a new playlist name:',
             okLabel: 'Add',
             placeholder: 'Number or new playlist name',
         })) || '').trim();
-        if (!ans) return;
+        if (!ans) return null;
         let pid = null;
         const num = parseInt(ans, 10);
         if (!isNaN(num) && choices[num - 1]) pid = choices[num - 1].id;
         else { const created = await jsend('POST', '/api/playlists', { name: ans }); pid = created && created.id; }
-        if (!pid) return;
-        for (const fn of state.selected) {
+        if (!pid) return null;
+        for (const fn of fns) {
             try { await fetch('/api/playlists/' + pid + '/songs', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ filename: fn }) }); } catch (e) { /* */ }
         }
-        finishBatch();
+        if (window.v3Playlists) { try { window.v3Playlists.refresh(); } catch (e) { /* */ } }
+        return pid;
+    }
+
+    async function batchAddToPlaylist() {
+        const pid = await addFilenamesToPlaylist(state.selected);
+        // Only tear down the multi-select when the add actually happened. A
+        // cancelled or failed picker returns null — preserve the selection (and
+        // skip the reload) so the user can retry, matching the pre-refactor
+        // behaviour where !ans / !pid returned early before finishBatch().
+        if (pid) finishBatch();
     }
 
     function finishBatch() {

tests/js/v3_add_to_playlist_menu.test.js

@@ -0,0 +1,37 @@
+// Guard: a song's ⋮ "More" menu offers "Add to playlist" for a single song —
+// not only the select-mode checkbox + batch-bar flow. Both paths share the
+// extracted addFilenamesToPlaylist() helper. (Menu/DOM wiring isn't headlessly
+// unit-testable, so these are source-level guards.)
+
+'use strict';
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SONGS = fs.readFileSync(
+    path.join(__dirname, '..', '..', 'static', 'v3', 'songs.js'), 'utf8');
+
+test('the ⋮ card menu lists an "Add to playlist" row', () => {
+    assert.match(SONGS, /id:\s*'__playlist',\s*label:\s*'Add to playlist'/);
+});
+
+test('the menu row adds the single song via the shared helper', () => {
+    assert.match(SONGS, /id === '__playlist'[\s\S]{0,100}addFilenamesToPlaylist\(\[song\.filename\]\)/);
+});
+
+test('batch and single-song add share addFilenamesToPlaylist()', () => {
+    assert.match(SONGS, /async function addFilenamesToPlaylist\(filenames\)/);
+    assert.match(SONGS, /async function batchAddToPlaylist\(\)[\s\S]{0,120}addFilenamesToPlaylist\(state\.selected\)/);
+});
+
+test('batch only finishes (clears selection) when the add succeeded, not on cancel', () => {
+    // addFilenamesToPlaylist returns null on a cancelled/failed picker; the
+    // batch caller must capture it and gate finishBatch() on a truthy pid, so
+    // cancelling preserves the multi-select (regression guard for the
+    // extract-helper refactor — previously finishBatch ran unconditionally).
+    assert.match(SONGS, /const pid = await addFilenamesToPlaylist\(state\.selected\)/,
+        'batch must capture the returned playlist id');
+    assert.match(SONGS, /if \(pid\) finishBatch\(\)/,
+        'finishBatch must be gated on a successful add (truthy pid)');
+});