Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 14 additions & 13 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -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.

Expand Down Expand Up @@ -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.

Expand Down
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
19 changes: 18 additions & 1 deletion src/app.svelte
Original file line number Diff line number Diff line change
Expand Up @@ -197,6 +197,15 @@

{#snippet navigation()}
<nav class="stack-sm" aria-label="Main navigation">
<button
class="menu-item"
commandfor="player-dialog"
command="show-modal"
onclick={() => navigationDrawer?.close()}
>
<Icon name="queue" />
Queue
</button>
<a
class="menu-item"
href="?/library"
Expand Down Expand Up @@ -328,7 +337,15 @@
/>
{/if}
</main>
<Player {cache} {covers} {playback} {trackEngine} {offlineMode} audio={player} />
<Player
{cache}
{covers}
{playback}
{trackEngine}
{offlineMode}
audio={player}
serverQueueExchange={!demo}
/>
{#if hasErrors}
<div id="error-popover" class="notification-popover" popover="auto" aria-label="Errors">
<div class="stack-sm">
Expand Down
Loading
Loading