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
11 changes: 6 additions & 5 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ Routes use the bare query, for example `/webapp/?/library/artist/123#section`. E

- Read Cache collections directly; change them through explicit methods. Session owns account details; Cache accepts an opaque account key and hashes it for storage. An undefined key creates an empty, non-persisting fallback. A defined key does not mean hydration succeeded.
- 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. Work offline disables all server domains and pauses queued downloads, retaining durable intent. One Network-owned connection serves every domain; reconnect resumes queued, never failed jobs. All music/Downloaded is a separate browsing preference and never filters or rewrites the queue. Cached playback may continue offline; remote playback stops. 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.
- New connections default to memory-only credentials. `Session.connect(input, remember)` persists verified credentials only after workspace acceptance when explicitly opted in; credential-free identity persists separately so reload opens local data offline. Existing persisted credentials remain recognized until disconnect/explicit opt-out; do not silently remove legacy records. Token persistence 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. Keep injected demo `AuthStore(new MemoryStorage())` supported. Remember is an app persistence choice, not browser autofill policy.
- Session acquires an exclusive Web Lock with `ifAvailable`, named from the same SHA-256 account identity as OPFS, before hydration or authenticated producers. Only one tab activates a persistent account; another is blocked, not a read-only replica. Retry is explicit after closing the owner; there is no polling/takeover. Missing Web Locks blocks activation honestly. Browser document termination releases its lock; it does not guarantee the last in-memory edit survived a crash.
- Disconnect retains local data and ownership for offline use. Same-account reconnects reuse the live cache and lease to preserve edits. Different-account preparation acquires its lease first; failures retain the original workspace. Account changes stop producers and drain old writes before releasing ownership. Disposal stops producers, checkpoints globally and cancels/drains disk operations before releasing. Deletion retains ownership even on failure. Late results must not leak into a different account.
- `Cache.flushQueue()` checkpoints only the queue document, independent of other domains’ pending/failing checkpoints. Playback progress, pause, visibility and explicit queue commands use it. Global `flush()` remains for workspace retirement/disposal. These guarantees apply to Session-owned persistent workspaces; direct Cache construction in focused storage fixtures does not acquire a lease.
Expand All @@ -75,8 +75,9 @@ Library normalization uses structured `artists`, `displayArtist`, and `genres`,
- Use semantic color/type roles and spacing/shape primitives. Containers own gaps and padding. Avoid global element resets and additional token aliases or configuration layers without a concrete consumer.
- `src/ui/` contains shared presentation. Artwork delegates acquisition and object-URL ownership to Covers. Atmosphere uses CSS scroll timelines with static fallbacks for unsupported browsers and reduced motion; don't add scroll handlers for decoration.
- The app scrolls the document with native page overscroll. Container queries adapt navigation and split layouts without remounting playback. Now Playing is a fullscreen native dialog with its own scrolling. Modal dialogs/backdrops suppress scroll chaining and boundary bounce without changing document overflow.
- Preserve offline filtering, ordered playback, and action scope. Library batches remain lazy. Downloads show real jobs and saved records, not invented progress. Queue rows use original occurrence indexes.
- Keep native validation, keyboard focus, actual error messages, and guarded busy actions. Never expose credentials. A completed connection must not redirect after the user leaves Settings. Update state is shared between sidebar and drawer.
- Library reuses the committed search implementation, including multi-select URL criteria and lazy batches; `/search` is an alias, not a second browse model. Routine Library arrival focuses its heading; explicit search anchors focus the input, and criteria updates preserve focus. Preserve independent downloaded filtering and ordered collection scope. Track Play now replaces with only that track; collection Play now replaces with its scope. Play next inserts after selection; Add to queue appends; neither autoplays inactive queues. Queue removal uses original occurrence indexes, stops selected removal without advancing, and focuses next/previous removal or the heading.
- Downloads show actual jobs and registered completed audio-byte totals (not origin usage). Completed-format removal commits the catalog before reclaiming bytes, preserves failures honestly, and stops/unloads an active cached source without changing queue membership. Bulk removal confirms account scope and excludes pending jobs; cancellation remains separate.
- Keep native validation, keyboard focus, actual error messages, and guarded busy actions. Never expose credentials. A completed connection must not redirect after the user leaves the focused Connect screen. Update state is shared between sidebar and drawer.
- Prefer native `commandfor`/`command` invokers for dialogs and popovers. Use imperative APIs only for behavior that cannot be expressed declaratively. Popovers already have implicit invoker anchors. Preserve long-press and swipe dismissal; don't dismiss overlays on resize.
- Store UI icons in `src/sprite.svg` and render through typed `Icon`; keep its name union synchronized. Use `currentColor` and accessible labels for icon-only controls. The build injects the sprite into HTML, not JavaScript.
- Self-hosted fonts and their license live in `src/fonts/`; preserve optional loading and system fallbacks. Keep font preloads aligned with the faces each entry point uses.
Expand All @@ -101,11 +102,11 @@ Select suites for the behavior being changed:
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `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 |
| `startup.test.cjs` | Initial Connect 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 |
| `downloads.test.cjs`, `settings.test.cjs` | Actual app/OPFS behavior with intercepted Subsonic requests; focused connection, memory/remembered reload, queue removal focus, saved-byte removal and confirmation |
| `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) |
Expand Down
12 changes: 8 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Libras is a browser-based minimalistic music player that connects to your own mu

## Features

- Browse artists, albums, and tracks.
- Browse and search artists, albums, and tracks together in Library, with shareable multi-select type filters. Older Search links keep their criteria.
- Stream music from your own server.
- Download music for offline playback and manage it in Settings → Downloads.
- Restore this device’s playback queue and position between sessions, without autoplay.
Expand All @@ -23,7 +23,9 @@ Libras is a browser-based minimalistic music player that connects to your own mu

1. Open [Libras](https://libras-music.app/webapp/).
2. Connect to your music server with your server address, username, and password.
3. Browse your library and start listening.
3. Browse or search Library and start listening. Settings links back to the focused connection screen for sign-in.

**Play now** replaces the queue with that track only, or the chosen collection in its current scope. **Play next** inserts after the selected occurrence; **Add to queue** appends. Neither starts an inactive queue. Queue removal preserves other occurrences (including duplicates and unavailable tracks); removing the selected occurrence stops playback without choosing a replacement.

Just trying it out? Connect to the [Navidrome demo server](https://demo.navidrome.org/) using `https://demo.navidrome.org` as the server address and `demo` as both the username and password.

Expand All @@ -37,7 +39,9 @@ Safari 26.0 or newer is required; older Safari versions are not supported. The a

Libras tries salted token authentication first; your password stays in the browser for that attempt. Only a structured server rejection of token authentication (Subsonic code 41 or 42) automatically retries the same username and password over HTTPS, including on localhost. Invalid credentials, connection failures, and other errors never trigger a password retry.

Credentials persist in **localStorage** until you disconnect. Token login saves the username, token, and salt, not your password. Successfully verified direct-password login saves the actual password and sends it with subsequent requests, including artwork and streaming URLs. HTTPS encrypts transport, not localStorage; scripts running on the app's origin and anyone with access to your browser profile can read saved credentials. Use a trusted device and server, and disconnect on shared devices. Disconnect removes credentials but retains your offline account, music, and queue.
New connections keep credentials **in memory only** by default. Reloading retains your credential-free offline identity, music, and queue, but requires signing in again for server access. Select **Remember this device** only on a trusted device to save verified credentials in localStorage after the account workspace is accepted. Existing remembered credentials remain recognized until you disconnect or explicitly opt out; they are not silently deleted on startup. This choice controls Libras storage, not your browser’s password manager.

Remembered token login saves username/token/salt, not your password. Verified direct-password fallback saves the actual password and sends it with subsequent requests, including artwork and streaming URLs. HTTPS encrypts transport, not localStorage; same-origin scripts and anyone with access to your browser profile can read saved credentials. Disconnect removes credentials but retains offline identity/data unless you also choose local deletion.

## Install

Expand All @@ -55,7 +59,7 @@ Download music while connected, then choose **Work offline** in navigation or Se

**Library scope → All music / Downloaded** is independent of the connection. Downloaded filters browsing and search without disconnecting or changing your queue, position or active audio. All music can browse saved metadata offline; uncached tracks remain visible as unavailable.

- **Manage downloads:** Settings → Downloads.
- **Manage downloads:** Downloads in navigation (also linked from Settings). Totals count registered completed audio bytes, not total browser storage. Remove individual formats, or confirm **Remove all downloaded music** for this account. Queue membership and server files stay unchanged; pending jobs use the separate Cancel downloads action. Removing an active cached source stops/unloads it. Catalog deletion must succeed before bytes are reclaimed; failures remain visible for retry.
- **Refresh library:** Automatic when opening online, or via Settings → Refresh library.
- **Disconnect:** Clears credentials and optionally deletes this account’s local cache and downloads. Remembered identity, preferences, other accounts and server data are unchanged. Only one tab can open an account’s local data at a time, including while deleting it. A second tab is blocked: close the owning tab, then select **Retry**. There is no automatic takeover or live cross-tab queue replication.
- **Storage:** Each server/account has its own offline library, saved only in this browser on this device. **Clearing site data deletes it.**
Expand Down
29 changes: 13 additions & 16 deletions src/_album.svelte
Original file line number Diff line number Diff line change
Expand Up @@ -44,9 +44,6 @@
const albumPlaybackState = $derived(
album && currentTrack?.albumId === album.id ? playbackState : undefined,
);
const albumCanPause = $derived(
albumPlaybackState === "playing" || albumPlaybackState === "loading",
);
const artist = $derived(album ? cache.artists.get(album.artistIds[0]) : undefined);
const atmosphere = $derived(album?.artworkId ? covers.ensureCover(album.artworkId) : undefined);
const visibleTracks = $derived(
Expand All @@ -61,7 +58,7 @@
const visibleTrackIds = $derived(visibleTracks.map((track) => track.id));

function playTrack(track: Immutable<Track>) {
void playback.replaceQueueAndPlay(visibleTrackIds, visibleTrackIds.indexOf(track.id));
void playback.replaceQueueAndPlay([track.id]);
}

let menuTrackId = $state<string>();
Expand All @@ -88,6 +85,7 @@

<Atmosphere src={libraryAvailable && artist && album ? atmosphere?.source : undefined} />
<LibraryScope {session} />
{#if playback.queueMessage}<p class="caption" role="status">{playback.queueMessage}</p>{/if}
<section class="split-layout" aria-label="Album details">
{#if libraryAvailable && artist && album}
<div class="detail-panel view-slide-up">
Expand All @@ -104,18 +102,16 @@
<button
class="button"
data-variant="primary"
aria-label={`${albumCanPause ? "Pause" : "Play"} ${album.title}`}
aria-label={`Play now ${album.title}`}
aria-busy={albumPlaybackState === "loading"}
disabled={!albumPlaybackState && !visibleTrackIds.length}
onclick={() => {
if (albumPlaybackState) void playback.toggle();
else void playback.replaceQueueAndPlay(visibleTrackIds);
}}
disabled={!visibleTrackIds.length ||
(session.offlineMode && !trackEngine.isDownloaded(visibleTrackIds[0]))}
onclick={() => void playback.replaceQueueAndPlay(visibleTrackIds)}
>
{#if albumPlaybackState === "loading"}
<Loader />
{:else}
<Icon name={albumCanPause ? "pause" : "play"} />
<Icon name="play" />
{/if}
</button>
<button
Expand Down Expand Up @@ -201,12 +197,12 @@
</div>
<button
class="button-quiet link-target"
aria-label={`${currentTrack?.id === track.id && playbackState !== "paused" ? "Pause" : "Play"} ${track.title}`}
aria-label={`Play now ${track.title}`}
disabled={session.offlineMode && !trackEngine.isDownloaded(track.id)}
aria-describedby={session.offlineMode && !trackEngine.isDownloaded(track.id)
? `unavailable-${index}`
: undefined}
onclick={() => playback.toggleTrack(track.id, visibleTrackIds)}
onclick={() => playTrack(track)}
data-longpressfor="album-detail-menu"
data-longpress="show-modal"
onfocus={() => (menuTrackId = track.id)}
Expand Down Expand Up @@ -302,15 +298,16 @@
<div class="stack-sm">
<button
class="menu-item"
disabled={!menuTrackIds.length}
disabled={!menuTrackIds.length ||
(session.offlineMode && !trackEngine.isDownloaded(menuTrackIds[0]))}
onclick={() => {
if (menuTrack) playTrack(menuTrack);
else void playback.replaceQueueAndPlay(menuTrackIds);
dismissActions();
}}
>
<Icon name="play" />
<span>Play</span>
<span>Play now</span>
</button>
<button
class="menu-item"
Expand All @@ -332,7 +329,7 @@
}}
>
<Icon name="plus" />
<span>Play last</span>
<span>Add to queue</span>
</button>
<button
class="menu-item"
Expand Down
Loading
Loading