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
26 changes: 14 additions & 12 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,16 +40,18 @@ The workspace contains the root app (`src/`, `tests/`) and `@libras/website` (`w
| `AudioPlayer` | Audio transport, seeking, keyboard shortcuts, and Media Session |
| `Covers` / `TrackEngine` | Resource acquisition, download scheduling, and browser URL lifetimes |
| `Playlists` | Server-confirmed playlist operations and conflict detection; no offline outbox |
| `Favourites` | Serialized server-confirmed stars and reconciliation; independent account checkpoint, no outbox |
| `Router` | Query routes, native fragment anchors, active navigation metadata, and optional view transitions |

Routes use the bare query, for example `/webapp/?/library/artist/123#section`. Encode each dynamic path segment with `encodeURIComponent`; fragments remain native in-page anchors. The service worker serves one cached app shell for root/index navigation requests, including their route queries; assets and API requests are excluded.

### Persistence and account safety

- 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.
- Favourites use an independent `favourites.json` checkpoint. Server confirmation publishes before device checkpointing; cache failures never repeat a server write. Unreadable favourites documents are preserved, even after a server refresh restores visible memory, and are excluded from drainable retirement writes. Downloaded-only filtering does not disconnect authenticated favourites access. An unknown write outcome blocks further edits until an authoritative refresh succeeds.
- 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.
- Disconnect retains local data for offline use unless optional account-local cleanup is explicitly selected; that cleanup also removes the favourites checkpoint. 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.
- 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 @@ -94,17 +96,17 @@ 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`, `favourites.test.cjs` | Browsing, actions, responsive layouts, native dismissal, server stars, and URL-controlled Search criteria |
| `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
41 changes: 36 additions & 5 deletions src/_album.svelte
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
<script lang="ts">
import Icon from "./icon.svelte";
import FavouriteButton from "./ui/favourite-button.svelte";
import type { Favourites } from "./favourites.svelte";
import type { Cache, Immutable } from "./cache.svelte";
import type { Covers } from "./covers.svelte";
import Artwork from "./ui/artwork.svelte";
Expand All @@ -21,6 +23,7 @@
session: Session;
playbackState: "loading" | "playing" | "paused";
playback: Playback;
favourites: Favourites;
appName?: string;
}

Expand All @@ -32,6 +35,7 @@
session,
playbackState,
playback,
favourites,
appName = "Libras",
}: Props = $props();

Expand Down Expand Up @@ -64,14 +68,20 @@
}

let menuTrackId = $state<string>();
const menuTrack = $derived(menuTrackId ? cache.tracks.get(menuTrackId) : undefined);
const menuTrack = $derived(visibleTracks.find((track) => track.id === menuTrackId));
const albumTracks = $derived(album ? (cache.albumTracks.get(album.id) ?? []) : []);
const totalDuration = $derived(
visibleTracks.reduce((sum, track) => sum + (track.duration ?? 0), 0),
);
const menuTrackIds = $derived(menuTrack ? [menuTrack.id] : visibleTrackIds);
const menuTrackIds = $derived(
menuTrackId !== undefined ? (menuTrack ? [menuTrack.id] : []) : visibleTrackIds,
);
const menuDownloadIds = $derived(
menuTrack ? [menuTrack.id] : albumTracks.map((track) => track.id),
menuTrackId !== undefined
? menuTrack
? [menuTrack.id]
: []
: albumTracks.map((track) => track.id),
);
const menuDownloadStatus = $derived(menuTrack ? trackEngine.getStatus(menuTrack.id) : undefined);

Expand All @@ -81,6 +91,12 @@
sheet.close();
popover.hidePopover?.();
}
$effect(() => {
if (album && (menuTrackId === undefined || menuTrack)) return;
const wasOpen = sheet?.open || popover?.matches(":popover-open");
if (wasOpen) dismissActions();
menuTrackId = undefined;
});
</script>

<svelte:head><title>{album?.title ?? "Album"} | {appName}</title></svelte:head>
Expand Down Expand Up @@ -276,8 +292,14 @@
<div class="container-md stack-lg">
<header class="row-md row-justify">
<div class="row-md">
<Artwork {covers} id={menuTrack?.artworkId ?? album?.artworkId} size="lg" />
<h2 id={`${target}-title`} class="heading-md">{menuTrack?.title ?? album?.title}</h2>
<Artwork
{covers}
id={menuTrackId !== undefined ? menuTrack?.artworkId : album?.artworkId}
size="lg"
/>
<h2 id={`${target}-title`} class="heading-md">
{menuTrackId !== undefined ? menuTrack?.title : album?.title}
</h2>
</div>
<button
class="button"
Expand Down Expand Up @@ -353,6 +375,15 @@
: "Download"}
</span>
</button>
<FavouriteButton
{favourites}
{cache}
target={menuTrack
? { kind: "tracks", id: menuTrack.id }
: menuTrackId === undefined && album
? { kind: "albums", id: album.id }
: undefined}
/>
</div>
</div>
{/snippet}
39 changes: 34 additions & 5 deletions src/_artist.svelte
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
<script lang="ts">
import Icon from "./icon.svelte";
import FavouriteButton from "./ui/favourite-button.svelte";
import type { Favourites } from "./favourites.svelte";
import type { Cache, Immutable } from "./cache.svelte";
import type { Covers } from "./covers.svelte";
import Artwork from "./ui/artwork.svelte";
Expand All @@ -19,6 +21,7 @@
session: Session;
playbackState: "loading" | "playing" | "paused";
playback: Playback;
favourites: Favourites;
appName?: string;
}

Expand All @@ -30,6 +33,7 @@
session,
playbackState,
playback,
favourites,
appName = "Libras",
}: Props = $props();

Expand Down Expand Up @@ -68,10 +72,18 @@
}

let menuAlbumId = $state<string>();
const menuAlbum = $derived(menuAlbumId ? cache.albums.get(menuAlbumId) : undefined);
const menuTracks = $derived(menuAlbum ? (cache.albumTracks.get(menuAlbum.id) ?? []) : tracks);
const menuTitle = $derived(menuAlbum?.title ?? artist?.name);
const menuArtwork = $derived(menuAlbum ? menuAlbum.artworkId : artist?.artworkId);
const menuAlbum = $derived(visibleAlbums.find((album) => album.id === menuAlbumId));
const menuTracks = $derived(
menuAlbumId !== undefined
? menuAlbum
? (cache.albumTracks.get(menuAlbum.id) ?? [])
: []
: tracks,
);
const menuTitle = $derived(menuAlbumId !== undefined ? menuAlbum?.title : artist?.name);
const menuArtwork = $derived(
menuAlbumId !== undefined ? menuAlbum?.artworkId : artist?.artworkId,
);
const menuTrackIds = $derived(availableTrackIds(menuTracks));

let sheet: HTMLDialogElement;
Expand All @@ -80,6 +92,12 @@
sheet.close();
popover.hidePopover?.();
}
$effect(() => {
if (artist && (menuAlbumId === undefined || menuAlbum)) return;
const wasOpen = sheet?.open || popover?.matches(":popover-open");
if (wasOpen) dismissActions();
menuAlbumId = undefined;
});
</script>

<svelte:head><title>{artist?.name ?? "Artist"} | {appName}</title></svelte:head>
Expand All @@ -97,7 +115,9 @@
/>
<div class="stack-sm">
<div class="row-md row-justify">
<div class="stack-xs"><h1 class="heading-lg uppercase">{artist.name}</h1></div>
<div class="stack-xs">
<h1 class="heading-lg uppercase">{artist.name}</h1>
</div>
<div class="row-sm">
<button
class="button"
Expand Down Expand Up @@ -308,6 +328,15 @@
<Icon name="download" />
<span>Download</span>
</button>
<FavouriteButton
{favourites}
{cache}
target={menuAlbum
? { kind: "albums", id: menuAlbum.id }
: menuAlbumId === undefined && artist
? { kind: "artists", id: artist.id }
: undefined}
/>
</div>
</div>
{/snippet}
28 changes: 26 additions & 2 deletions src/_library.svelte
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
<script lang="ts">
import Icon from "./icon.svelte";
import FavouriteButton from "./ui/favourite-button.svelte";
import type { Favourites } from "./favourites.svelte";
import type { Cache, Immutable } from "./cache.svelte";
import type { Covers } from "./covers.svelte";
import Artwork from "./ui/artwork.svelte";
Expand All @@ -16,14 +18,23 @@
trackEngine: TrackEngine;
session: Session;
playback: Playback;
favourites: Favourites;
appName?: string;
}

let { cache, covers, trackEngine, session, playback, appName = "Libras" }: Props = $props();
let {
cache,
covers,
trackEngine,
session,
playback,
favourites,
appName = "Libras",
}: Props = $props();

// Long-press focuses the primary target before opening the shared dialog.
let menuArtistId = $state<string>();
const menuArtist = $derived(menuArtistId ? cache.artists.get(menuArtistId) : undefined);
const menuArtist = $derived.by(() => visibleArtists.find((artist) => artist.id === menuArtistId));

function artistTracks(artist: Immutable<Artist>) {
return (cache.artistAlbums.get(artist.id) ?? []).flatMap(
Expand Down Expand Up @@ -65,6 +76,14 @@
(document.getElementById("artist-menu") as HTMLDialogElement)?.close();
document.getElementById("artist-popover")?.hidePopover?.();
}
$effect(() => {
if (menuArtistId === undefined || menuArtist) return;
const sheet = document.getElementById("artist-menu") as HTMLDialogElement | null;
const popover = document.getElementById("artist-popover");
const wasOpen = sheet?.open || popover?.matches(":popover-open");
if (wasOpen) dismissActions();
menuArtistId = undefined;
});
</script>

<svelte:head><title>Your library | {appName}</title></svelte:head>
Expand Down Expand Up @@ -278,6 +297,11 @@
<Icon name="download" />
<span>Download</span>
</button>
<FavouriteButton
{favourites}
{cache}
target={menuArtist ? { kind: "artists", id: menuArtist.id } : undefined}
/>
</div>
</div>
{/snippet}
Expand Down
Loading
Loading