From e32fc81ef756d6491424ded8f86df80722d7cd77 Mon Sep 17 00:00:00 2001 From: Bogdan Chadkin Date: Fri, 13 Nov 2026 20:13:26 +0100 Subject: [PATCH] Make device queue authoritative with explicit server exchange --- CONTRIBUTING.md | 27 +- README.md | 3 +- src/app.svelte | 19 +- src/playback.svelte.ts | 183 ++++---- src/session.svelte.ts | 10 +- src/ui/player.svelte | 220 +++++++--- tests/app-cache.test.ts | 14 +- tests/app-settings.test.ts | 12 +- tests/browser/queue.test.cjs | 248 +++++++++++ tests/playback-queue.test.ts | 771 +++++++++------------------------- tests/playback.test.ts | 28 +- tests/player-exchange.test.ts | 105 +++++ tests/session-library.test.ts | 2 +- tests/session-test-helpers.ts | 11 +- tests/session.test.ts | 19 +- 15 files changed, 858 insertions(+), 814 deletions(-) create mode 100644 tests/browser/queue.test.cjs create mode 100644 tests/player-exchange.test.ts diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9bae2c7..fde9b20 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,7 +36,7 @@ The workspace contains the root app (`src/`, `tests/`) and `@libras/website` (`w | `AuthStore` / `authenticate` | Credential persistence / token derivation and automatic HTTPS password fallback | | `Network` / `SubsonicClient` | Connection cancellation, normalized domain access / Subsonic protocol requests | | `Cache` | Account-scoped library, queue, images, downloads, playlists, and OPFS persistence | -| `Playback` | Queue commands, server synchronization, and playback orchestration | +| `Playback` | Local queue commands, explicit server exchange, and playback orchestration | | `AudioTransport` | Native audio lifetime, source acquisition, reactive transport state, and seeking | | `AudioPlayer` | Headless keyboard shortcuts and Media Session binding to the app-owned transport | | `Covers` / `TrackEngine` | Resource acquisition, download scheduling, and browser URL lifetimes | @@ -51,7 +51,7 @@ Routes use the bare query, for example `/webapp/?/library/artist/123#section`. E - Library, queue, playlist, and image memory updates checkpoint asynchronously. Downloads instead await explicit queued/failed/completed commits in one versioned store; failed jobs require explicit Retry or a bulk Download action. Interrupted queued jobs restart from scratch, never adopting unregistered bytes. Successful byte close wins cancellation while completed metadata commits; cancellation joins that work. Unknown queued/failed job fields, including old attempts, are ignored on load and omitted on subsequent writes; orphan-file reclamation after old attempts or abrupt termination is intentionally out of scope. Offline library limits browsing/listening, not requested downloads. Do not treat visible state as proof of persistence. Unreadable download documents are preserved, not reset; readable saved files remain usable. - Credentials use localStorage only, until disconnect. Token login stores username/token/salt; verified direct-password fallback stores the actual password. localStorage is not encrypted and is readable by same-origin scripts. Never log credentials or credential-bearing URLs. Legacy token records migrate without changing account keys; migration writeback is best-effort. - Disconnect retains local data for offline use. Same-account reconnects reuse the live cache to preserve edits. Account changes drain old writes and retire resources before committing the new workspace. Late results must not leak into a different account. -- Startup and manual refresh pull server state. Reconnecting must not upload an offline queue automatically, and refresh must not replace a playing or paused queue. +- Startup and manual refresh pull library/artwork/playlist state only. The device queue is authoritative: no automatic server queue reads or writes on startup, refresh, reconnect, progress, pause or visibility changes. Local resume checkpoints remain automatic. Queue in navigation opens Now Playing even when empty/stopped; only confirmed Load server queue and explicit Save queue to server exchange queues. Empty saves confirm clearing the server queue. One exchange runs at a time; local edits remain available. Loads discard stale account/connection/revision/playback results and never autoplay. Saves send a stable starting snapshot without changing local playback. Subsonic selects by track ID, not occurrence: retain a matching local occurrence when membership matches, otherwise select the first match. Preserve unknown IDs. Demo exchange controls are disabled. - Preserve queue IDs and occurrence indexes, including duplicates and unavailable tracks. Filtering the UI must not rewrite the saved queue. - Release browser resources explicitly. The service worker caches the app shell, not API responses or music; offline audio downloads are explicit user actions. @@ -95,17 +95,18 @@ NODE_PATH=/path/to/external/node_modules PREVIEW_URL=http://127.0.0.1:5173 \ Select suites for the behavior being changed: -| Suite in `tests/browser/` | Coverage | -| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `edgerunner.test.cjs` | Shared styles, fonts, native controls, overlays, and reduced motion | -| `navigation.test.cjs` | Document scrolling, shell, playback, query routes, anchors, and optional offline navigation | -| `startup.test.cjs` | Initial Settings route, reloads, and subsequent animated navigation | -| `pwa-updates.test.cjs` | Self-hosted production builds: real worker installation, per-tab consent, repeated discovery, offline application, failed precache, and optional old-plugin migration | -| `library.test.cjs`, `search.test.cjs` | Browsing, actions, responsive layouts, and native dismissal | -| `downloads.test.cjs`, `settings.test.cjs` | Actual app/OPFS behavior with intercepted Subsonic requests | -| `atmosphere.test.cjs` | Document/dialog scroll timelines; self-contained, no server required | -| `website-cascade.test.cjs` | Script-free landing layout, keyboard/FAQ behavior, and standalone demo journeys | -| `design-improvements.test.cjs` | Compact details, full-height player, queue anchors, confirmation, gradients, popover timing, titles, and demo guidance (website server) | +| Suite in `tests/browser/` | Coverage | +| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `edgerunner.test.cjs` | Shared styles, fonts, native controls, overlays, and reduced motion | +| `navigation.test.cjs` | Document scrolling, shell, playback, query routes, anchors, and optional offline navigation | +| `startup.test.cjs` | Initial Settings route, reloads, and subsequent animated navigation | +| `pwa-updates.test.cjs` | Self-hosted production builds: real worker installation, per-tab consent, repeated discovery, offline application, failed precache, and optional old-plugin migration | +| `library.test.cjs`, `search.test.cjs` | Browsing, actions, responsive layouts, and native dismissal | +| `queue.test.cjs` | Explicit load/save, zero automatic queue requests, empty navigation, native confirmation focus/Escape, sanitized failures, duplicates and 320px reflow (optional `ARTIFACT_DIR` for screenshots) | +| `downloads.test.cjs`, `settings.test.cjs` | Actual app/OPFS behavior with intercepted Subsonic requests | +| `atmosphere.test.cjs` | Document/dialog scroll timelines; self-contained, no server required | +| `website-cascade.test.cjs` | Script-free landing layout, keyboard/FAQ behavior, and standalone demo journeys | +| `design-improvements.test.cjs` | Compact details, full-height player, queue anchors, confirmation, gradients, popover timing, titles, and demo guidance (website server) | `cache-downloads.test.cjs` exercises native OPFS close/publication boundaries and restart-from-scratch behavior by importing the owning modules. Run it against the app **dev** server; Downloads, Settings, and navigation checks can run against production preview. diff --git a/README.md b/README.md index 01412ae..ccbf763 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,8 @@ Libras is a browser-based minimalistic music player that connects to your own mu - Browse artists, albums, and tracks. - Stream music from your own server. - Download music for offline playback and manage it in Settings → Downloads. -- Restore your playback queue and position between sessions. +- Restore this device’s playback queue and position between sessions, without autoplay. +- Explicitly Load server queue or Save queue to server from Queue in navigation. Startup, reconnect, library refresh and playback never exchange server queues. Loading confirms replacement and stops playback only after a valid result arrives; failed/stale loads leave local state intact. Saving an empty queue confirms clearing the server queue. Duplicate and unavailable IDs are retained; Subsonic selection uses a track ID, so duplicate occurrences are ambiguous (the local occurrence is retained when membership matches, otherwise the first match is selected). The demo has no server queue exchange. - Install as a standalone web app. ## Get started diff --git a/src/app.svelte b/src/app.svelte index fbf29cb..8100963 100644 --- a/src/app.svelte +++ b/src/app.svelte @@ -197,6 +197,15 @@ {#snippet navigation()}