muzical-ui 0.1.1

package/lib/library/collect-tracks-for-meta.ts

@@ -0,0 +1,91 @@
+import type { LibraryRootMeta } from "@/types/library-root-meta";
+import type { ScanProgressTick } from "@/lib/library/scan-progress-tick";
+import { scanDirectoryForTracks } from "@/lib/library/scan-tree";
+import type { ScanTreeOptions } from "@/types/scan-tree-options";
+import type { Track } from "@/types/track";
+
+export type CollectTracksResult = {
+  tracks: Track[];
+  failedRootCount: number;
+  firstError: string | null;
+};
+
+function scanFailureMessage(e: unknown): string {
+  if (e instanceof DOMException) {
+    return `${e.name}: ${e.message}`;
+  }
+  if (e instanceof Error) {
+    return e.message;
+  }
+  return String(e);
+}
+
+/**
+ * Scans every configured library root and merges track rows in stable order.
+ */
+export async function collectTracksForMeta(
+  meta: readonly LibraryRootMeta[],
+  handles: ReadonlyMap<string, FileSystemDirectoryHandle>,
+  scanOptions: ScanTreeOptions,
+  onProgress?: (tick: ScanProgressTick) => void,
+): Promise<CollectTracksResult> {
+  const list: Track[] = [];
+  let failedRootCount = 0;
+  let firstError: string | null = null;
+  const roots = meta.filter((r) => handles.has(r.id));
+  const rootCount = roots.length;
+
+  for (let rootIndex = 0; rootIndex < roots.length; rootIndex++) {
+    const r = roots[rootIndex];
+    const h = handles.get(r.id);
+    if (!h) continue;
+    const emit = (
+      partial: Pick<ScanProgressTick, "phase" | "filesDone" | "filesTotal">,
+    ): void => {
+      onProgress?.({
+        rootIndex,
+        rootCount,
+        rootName: r.name,
+        phase: partial.phase,
+        filesDone: partial.filesDone,
+        filesTotal: partial.filesTotal,
+      });
+    };
+    emit({ phase: "walk" });
+    try {
+      const chunk = await scanDirectoryForTracks(
+        r.id,
+        r.name,
+        h,
+        scanOptions,
+        (inner) => {
+          if (inner.phase === "walk") {
+            emit({ phase: "walk" });
+          } else {
+            emit({
+              phase: "metadata",
+              filesDone: inner.filesDone,
+              filesTotal: inner.filesTotal,
+            });
+          }
+        },
+      );
+      list.push(...chunk);
+    } catch (e) {
+      failedRootCount += 1;
+      if (!firstError) firstError = scanFailureMessage(e);
+    }
+  }
+
+  list.sort((a, b) => {
+    const ra = a.library?.rootId ?? "";
+    const rb = b.library?.rootId ?? "";
+    const c = ra.localeCompare(rb, undefined, { sensitivity: "base" });
+    if (c !== 0) return c;
+    const pa = a.library?.relativePath ?? a.title;
+    const pb = b.library?.relativePath ?? b.title;
+    return pa.localeCompare(pb, undefined, { sensitivity: "base" });
+  });
+
+  return { tracks: list, failedRootCount, firstError };
+}

package/lib/library/compute-library-stats.ts

@@ -0,0 +1,37 @@
+import {
+  albumCompositeKey,
+  artistDisplayName,
+} from "@/lib/library/favorite-keys";
+import type { Track } from "@/types/track";
+
+export type LibraryStats = {
+  trackCount: number;
+  folderCount: number;
+  artistCount: number;
+  albumCount: number;
+  totalDurationSec: number;
+};
+
+/**
+ * Derives aggregate library counts from the scanned track catalog.
+ */
+export default function computeLibraryStats(
+  tracks: readonly Track[],
+  folderCount: number,
+): LibraryStats {
+  const artists = new Set<string>();
+  const albums = new Set<string>();
+  let totalDurationSec = 0;
+  for (const t of tracks) {
+    artists.add(artistDisplayName(t.artist));
+    albums.add(albumCompositeKey(t.album, t.artist));
+    if (t.durationSec > 0) totalDurationSec += t.durationSec;
+  }
+  return {
+    trackCount: tracks.length,
+    folderCount,
+    artistCount: artists.size,
+    albumCount: albums.size,
+    totalDurationSec,
+  };
+}

package/lib/library/constants.ts

@@ -0,0 +1,27 @@
+/** IndexedDB database name for saved library folder handles */
+export const LIBRARY_DB_NAME = "muzical-library";
+
+/** Object store for configured roots (includes directory handles) */
+export const LIBRARY_STORE_NAME = "libraryRoots";
+
+/** Object store for last successful scan snapshot (metadata only, no handles) */
+export const LIBRARY_CATALOG_STORE_NAME = "libraryCatalog";
+
+/** DB schema version */
+export const LIBRARY_DB_VERSION = 3;
+
+/** Lowercase extensions including dot */
+export const LIBRARY_AUDIO_EXTENSIONS: readonly string[] = [
+  ".mp3",
+  ".flac",
+  ".m4a",
+  ".aac",
+  ".ogg",
+  ".opus",
+  ".wav",
+  ".webm",
+  ".aiff",
+  ".aif",
+  ".alac",
+  ".wma",
+];

package/lib/library/cover-bytes-cache.ts

@@ -0,0 +1,59 @@
+import type { ExtractedCoverBytes } from "@/lib/library/extract-cover-bytes-from-audio-file";
+import { extractCoverBytesFromAudioFile } from "@/lib/library/extract-cover-bytes-from-audio-file";
+
+const COVER_BYTES_CACHE_MAX = 48;
+
+type CacheEntry = {
+  bytes: ExtractedCoverBytes;
+  lastUsedAt: number;
+};
+
+const cache = new Map<string, CacheEntry>();
+const pendingByTrackId = new Map<string, Promise<ExtractedCoverBytes | null>>();
+
+function touchEntry(trackId: string, entry: CacheEntry): void {
+  cache.delete(trackId);
+  cache.set(trackId, entry);
+}
+
+function evictIfNeeded(): void {
+  while (cache.size > COVER_BYTES_CACHE_MAX) {
+    const oldestKey = cache.keys().next().value as string | undefined;
+    if (!oldestKey) return;
+    cache.delete(oldestKey);
+  }
+}
+
+/**
+ * Returns embedded cover bytes for a track, extracting on first use and caching in-memory.
+ */
+export async function getCoverBytesForTrack(
+  trackId: string,
+  file: File,
+): Promise<ExtractedCoverBytes | null> {
+  const cached = cache.get(trackId);
+  if (cached) {
+    touchEntry(trackId, { ...cached, lastUsedAt: Date.now() });
+    return cached.bytes;
+  }
+
+  const pending = pendingByTrackId.get(trackId);
+  if (pending) return pending;
+
+  const p = (async (): Promise<ExtractedCoverBytes | null> => {
+    const bytes = await extractCoverBytesFromAudioFile(file);
+    if (bytes) {
+      const entry: CacheEntry = { bytes, lastUsedAt: Date.now() };
+      cache.set(trackId, entry);
+      evictIfNeeded();
+    }
+    return bytes;
+  })();
+
+  pendingByTrackId.set(trackId, p);
+  try {
+    return await p;
+  } finally {
+    pendingByTrackId.delete(trackId);
+  }
+}

package/lib/library/default-library-scan-preferences.ts

@@ -0,0 +1,13 @@
+import { LIBRARY_AUDIO_EXTENSIONS } from "@/lib/library/constants";
+import type { LibraryScanPreferences } from "@/types/library-scan-preferences";
+
+/**
+ * Default scan preferences: all extensions, unlimited depth, no symlink follow.
+ */
+export default function defaultLibraryScanPreferences(): LibraryScanPreferences {
+  return {
+    maxScanDepth: 0,
+    followSymlinks: false,
+    enabledExtensions: [...LIBRARY_AUDIO_EXTENSIONS],
+  };
+}

package/lib/library/extract-cover-bytes-from-audio-file.ts

@@ -0,0 +1,41 @@
+import { parseBlob } from "music-metadata";
+
+export type ExtractedCoverBytes = {
+  mime: string;
+  /** Image bytes (no object URL) for efficient reuse */
+  data: Uint8Array<ArrayBuffer>;
+};
+
+/**
+ * Extracts embedded cover art from an audio `File`.
+ * Returns raw image bytes; callers can create object URLs and should revoke them.
+ */
+export async function extractCoverBytesFromAudioFile(
+  file: File,
+): Promise<ExtractedCoverBytes | null> {
+  try {
+    const meta = await parseBlob(file, { duration: false });
+    const pictures = meta.common.picture;
+    if (!pictures?.length) return null;
+
+    const front = pictures.find((p) => {
+      const t = p.type?.toLowerCase() ?? "";
+      return t.includes("front") || t.includes("cover");
+    });
+    const chosen =
+      front ??
+      pictures.reduce((a, b) => (b.data.length > a.data.length ? b : a));
+    const mime =
+      chosen.format?.trim() ||
+      (chosen.name?.toLowerCase().endsWith(".png")
+        ? "image/png"
+        : "image/jpeg");
+
+    return {
+      mime,
+      data: Uint8Array.from(chosen.data),
+    };
+  } catch {
+    return null;
+  }
+}

package/lib/library/extract-cover-object-url-from-audio-file.ts

@@ -0,0 +1,31 @@
+import { parseBlob } from 'music-metadata'
+
+/**
+ * Parses embedded artwork from an audio file and returns an object URL for the best
+ * candidate image. The caller must `URL.revokeObjectURL` when the URL is no longer needed.
+ */
+export async function extractCoverObjectUrlFromAudioFile(
+  file: File,
+): Promise<string | null> {
+  try {
+    const meta = await parseBlob(file, { duration: false })
+    const pictures = meta.common.picture
+    if (!pictures?.length) return null
+
+    const front = pictures.find((p) => {
+      const t = p.type?.toLowerCase() ?? ''
+      return t.includes('front') || t.includes('cover')
+    })
+    const chosen = front ?? pictures.reduce((a, b) =>
+      b.data.length > a.data.length ? b : a,
+    )
+
+    const mime =
+      chosen.format?.trim() ||
+      (chosen.name?.toLowerCase().endsWith('.png') ? 'image/png' : 'image/jpeg')
+    const blob = new Blob([new Uint8Array(chosen.data)], { type: mime })
+    return URL.createObjectURL(blob)
+  } catch {
+    return null
+  }
+}

package/lib/library/favorite-keys.ts

@@ -0,0 +1,14 @@
+/**
+ * Stable artist label for favorites and grouping (matches library browser).
+ */
+export function artistDisplayName(artist: string | undefined): string {
+  const t = artist?.trim();
+  return t ? t : "Unknown artist";
+}
+
+/**
+ * Album + artist composite key (matches `groupByAlbum` in the library browser).
+ */
+export function albumCompositeKey(album: string, artist: string): string {
+  return `${album}\u0000${artist}`;
+}

package/lib/library/format-fs-access-error.ts

@@ -0,0 +1,29 @@
+/**
+ * Maps File System Access / Security errors to a short, actionable UI string.
+ */
+export function formatFsAccessErrorMessage(e: unknown): string {
+  if (e instanceof DOMException) {
+    if (e.name === "AbortError") {
+      return "";
+    }
+    if (
+      e.name === "SecurityError" ||
+      e.name === "NotAllowedError" ||
+      e.message.includes("not allowed by the user agent") ||
+      e.message.includes("The request is not allowed")
+    ) {
+      return "Folder access is blocked in this context. Open the app in Chrome or Edge in a normal window (not an embedded preview), and use https:// or http://localhost.";
+    }
+  }
+  if (e instanceof Error) {
+    const m = e.message;
+    if (
+      m.includes("not allowed by the user agent") ||
+      m.includes("The request is not allowed")
+    ) {
+      return "Folder access is blocked in this context. Open the app in Chrome or Edge in a normal window (not an embedded preview), and use https:// or http://localhost.";
+    }
+    return m;
+  }
+  return "Could not access the folder.";
+}

package/lib/library/idb.ts

@@ -0,0 +1,270 @@
+import {
+  LIBRARY_CATALOG_STORE_NAME,
+  LIBRARY_DB_NAME,
+  LIBRARY_DB_VERSION,
+  LIBRARY_STORE_NAME,
+} from "@/lib/library/constants";
+import type { Track } from "@/types/track";
+
+export type StoredLibraryRoot = {
+  id: string;
+  name: string;
+  addedAt: number;
+  handle: FileSystemDirectoryHandle;
+};
+
+const CATALOG_KEY = "catalog" as const;
+const FAVORITES_KEY = "favorites" as const;
+
+export type StoredLibraryCatalog = {
+  key: typeof CATALOG_KEY;
+  /** Sorted root ids — must match configured folders for this snapshot to apply */
+  rootIds: string[];
+  tracks: Track[];
+  savedAt: number;
+};
+
+export type StoredFavorites = {
+  key: typeof FAVORITES_KEY;
+  songIds: string[];
+  artistNames: string[];
+  albumKeys: string[];
+};
+
+/**
+ * Opens the library IndexedDB, creating the object store on upgrade.
+ */
+export function openLibraryDb(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(LIBRARY_DB_NAME, LIBRARY_DB_VERSION);
+    req.onerror = (): void => {
+      reject(req.error ?? new Error("IndexedDB open failed"));
+    };
+    req.onsuccess = (): void => {
+      resolve(req.result);
+    };
+    req.onupgradeneeded = (): void => {
+      const db = req.result;
+      if (!db.objectStoreNames.contains(LIBRARY_STORE_NAME)) {
+        db.createObjectStore(LIBRARY_STORE_NAME, { keyPath: "id" });
+      }
+      if (!db.objectStoreNames.contains(LIBRARY_CATALOG_STORE_NAME)) {
+        db.createObjectStore(LIBRARY_CATALOG_STORE_NAME, { keyPath: "key" });
+      }
+    };
+  });
+}
+
+/**
+ * Persists a library root (directory handle is stored via structured clone).
+ */
+export function idbPutRoot(
+  db: IDBDatabase,
+  root: StoredLibraryRoot,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(LIBRARY_STORE_NAME, "readwrite");
+    const store = tx.objectStore(LIBRARY_STORE_NAME);
+    const putReq = store.put(root);
+    putReq.onerror = (): void => {
+      reject(putReq.error ?? new Error("IndexedDB put failed"));
+    };
+    tx.oncomplete = (): void => {
+      resolve();
+    };
+    tx.onerror = (): void => {
+      reject(tx.error ?? new Error("IndexedDB transaction failed"));
+    };
+  });
+}
+
+/**
+ * Deletes a library root by id.
+ */
+export function idbDeleteRoot(db: IDBDatabase, id: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(LIBRARY_STORE_NAME, "readwrite");
+    const store = tx.objectStore(LIBRARY_STORE_NAME);
+    const delReq = store.delete(id);
+    delReq.onerror = (): void => {
+      reject(delReq.error ?? new Error("IndexedDB delete failed"));
+    };
+    tx.oncomplete = (): void => {
+      resolve();
+    };
+    tx.onerror = (): void => {
+      reject(tx.error ?? new Error("IndexedDB transaction failed"));
+    };
+  });
+}
+
+/**
+ * Loads all configured library roots from IndexedDB.
+ */
+export function idbGetAllRoots(db: IDBDatabase): Promise<StoredLibraryRoot[]> {
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(LIBRARY_STORE_NAME, "readonly");
+    const store = tx.objectStore(LIBRARY_STORE_NAME);
+    const getReq = store.getAll();
+    getReq.onerror = (): void => {
+      reject(getReq.error ?? new Error("IndexedDB getAll failed"));
+    };
+    getReq.onsuccess = (): void => {
+      resolve(getReq.result as StoredLibraryRoot[]);
+    };
+  });
+}
+
+function sortedRootIds(ids: readonly string[]): string[] {
+  return [...ids].sort((a, b) =>
+    a.localeCompare(b, undefined, { sensitivity: "base" }),
+  );
+}
+
+/**
+ * Saves the last library scan snapshot (track metadata + paths) for faster reload.
+ */
+export function idbPutCatalog(
+  db: IDBDatabase,
+  rootIds: readonly string[],
+  tracks: readonly Track[],
+): Promise<void> {
+  if (!db.objectStoreNames.contains(LIBRARY_CATALOG_STORE_NAME)) {
+    return Promise.reject(
+      new Error(`Missing object store ${LIBRARY_CATALOG_STORE_NAME}`),
+    );
+  }
+  const row: StoredLibraryCatalog = {
+    key: CATALOG_KEY,
+    rootIds: sortedRootIds(rootIds),
+    tracks: [...tracks],
+    savedAt: Date.now(),
+  };
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(LIBRARY_CATALOG_STORE_NAME, "readwrite");
+    const store = tx.objectStore(LIBRARY_CATALOG_STORE_NAME);
+    const putReq = store.put(row);
+    putReq.onerror = (): void => {
+      reject(putReq.error ?? new Error("IndexedDB catalog put failed"));
+    };
+    tx.oncomplete = (): void => {
+      resolve();
+    };
+    tx.onerror = (): void => {
+      reject(tx.error ?? new Error("IndexedDB catalog transaction failed"));
+    };
+  });
+}
+
+/**
+ * Loads the persisted catalog snapshot, if any.
+ */
+export function idbGetCatalog(
+  db: IDBDatabase,
+): Promise<StoredLibraryCatalog | null> {
+  if (!db.objectStoreNames.contains(LIBRARY_CATALOG_STORE_NAME)) {
+    return Promise.resolve(null);
+  }
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(LIBRARY_CATALOG_STORE_NAME, "readonly");
+    const store = tx.objectStore(LIBRARY_CATALOG_STORE_NAME);
+    const getReq = store.get(CATALOG_KEY);
+    getReq.onerror = (): void => {
+      reject(getReq.error ?? new Error("IndexedDB catalog get failed"));
+    };
+    getReq.onsuccess = (): void => {
+      const raw = getReq.result as StoredLibraryCatalog | undefined;
+      if (
+        !raw ||
+        raw.key !== CATALOG_KEY ||
+        !Array.isArray(raw.rootIds) ||
+        !Array.isArray(raw.tracks)
+      ) {
+        resolve(null);
+        return;
+      }
+      resolve(raw);
+    };
+  });
+}
+
+const defaultFavorites = (): StoredFavorites => ({
+  key: FAVORITES_KEY,
+  songIds: [],
+  artistNames: [],
+  albumKeys: [],
+});
+
+/**
+ * Loads saved favorites (songs by track id, artists by display name, albums by composite key).
+ */
+export function idbGetFavorites(db: IDBDatabase): Promise<StoredFavorites> {
+  if (!db.objectStoreNames.contains(LIBRARY_CATALOG_STORE_NAME)) {
+    return Promise.resolve(defaultFavorites());
+  }
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(LIBRARY_CATALOG_STORE_NAME, "readonly");
+    const store = tx.objectStore(LIBRARY_CATALOG_STORE_NAME);
+    const getReq = store.get(FAVORITES_KEY);
+    getReq.onerror = (): void => {
+      reject(getReq.error ?? new Error("IndexedDB favorites get failed"));
+    };
+    getReq.onsuccess = (): void => {
+      const raw = getReq.result as StoredFavorites | undefined;
+      if (
+        !raw ||
+        raw.key !== FAVORITES_KEY ||
+        !Array.isArray(raw.songIds) ||
+        !Array.isArray(raw.artistNames) ||
+        !Array.isArray(raw.albumKeys)
+      ) {
+        resolve(defaultFavorites());
+        return;
+      }
+      resolve({
+        key: FAVORITES_KEY,
+        songIds: [...raw.songIds],
+        artistNames: [...raw.artistNames],
+        albumKeys: [...raw.albumKeys],
+      });
+    };
+  });
+}
+
+/**
+ * Persists favorites in the same object store as the catalog (separate key).
+ */
+export function idbPutFavorites(
+  db: IDBDatabase,
+  data: {
+    songIds: readonly string[];
+    artistNames: readonly string[];
+    albumKeys: readonly string[];
+  },
+): Promise<void> {
+  if (!db.objectStoreNames.contains(LIBRARY_CATALOG_STORE_NAME)) {
+    return Promise.reject(
+      new Error(`Missing object store ${LIBRARY_CATALOG_STORE_NAME}`),
+    );
+  }
+  const payload: StoredFavorites = {
+    key: FAVORITES_KEY,
+    songIds: [...data.songIds],
+    artistNames: [...data.artistNames],
+    albumKeys: [...data.albumKeys],
+  };
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(LIBRARY_CATALOG_STORE_NAME, "readwrite");
+    const store = tx.objectStore(LIBRARY_CATALOG_STORE_NAME);
+    const putReq = store.put(payload);
+    putReq.onerror = (): void => {
+      reject(putReq.error ?? new Error("IndexedDB favorites put failed"));
+    };
+    tx.oncomplete = (): void => {
+      resolve();
+    };
+    tx.onerror = (): void => {
+      reject(tx.error ?? new Error("IndexedDB favorites transaction failed"));
+    };
+  });
+}

package/lib/library/read-audio-metadata.ts

@@ -0,0 +1,34 @@
+import { parseBlob } from "music-metadata";
+
+/** Normalized tags used to build `Track` rows for the library. */
+export type ExtractedAudioTags = {
+  title: string;
+  artist: string;
+  album: string;
+  durationSec: number;
+};
+
+/**
+ * Reads ID3/Vorbis/etc. tags and duration from an audio `File` (browser-safe `parseBlob`).
+ */
+export async function extractTagsFromAudioFile(
+  file: File,
+): Promise<ExtractedAudioTags | null> {
+  try {
+    const meta = await parseBlob(file, { duration: true });
+    const title = meta.common.title?.trim() ?? "";
+    const artist =
+      meta.common.artist?.trim() ||
+      meta.common.artists?.[0]?.trim() ||
+      meta.common.albumartist?.trim() ||
+      meta.common.albumartists?.[0]?.trim() ||
+      "";
+    const album = meta.common.album?.trim() ?? "";
+    const d = meta.format.duration;
+    const durationSec =
+      typeof d === "number" && Number.isFinite(d) ? Math.round(d) : 0;
+    return { title, artist, album, durationSec };
+  } catch {
+    return null;
+  }
+}

package/lib/library/read-stored-library-scan-preferences.ts

@@ -0,0 +1,43 @@
+import { LIBRARY_AUDIO_EXTENSIONS } from "@/lib/library/constants";
+import defaultLibraryScanPreferences from "@/lib/library/default-library-scan-preferences";
+import type { LibraryScanPreferences } from "@/types/library-scan-preferences";
+
+const STORAGE_KEY = "muzical.libraryScanPreferences";
+
+const allowedExt = new Set<string>(LIBRARY_AUDIO_EXTENSIONS);
+
+/**
+ * Loads library scan preferences from localStorage with validation.
+ */
+export default function readStoredLibraryScanPreferences(): LibraryScanPreferences {
+  const defaults = defaultLibraryScanPreferences();
+  if (typeof window === "undefined") return defaults;
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY);
+    if (!raw) return defaults;
+    const parsed: unknown = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") return defaults;
+    const o = parsed as Record<string, unknown>;
+    const maxScanDepth =
+      typeof o.maxScanDepth === "number" &&
+      Number.isFinite(o.maxScanDepth) &&
+      o.maxScanDepth >= 0
+        ? Math.floor(o.maxScanDepth)
+        : defaults.maxScanDepth;
+    const followSymlinks = o.followSymlinks === true;
+    let enabledExtensions = defaults.enabledExtensions;
+    if (Array.isArray(o.enabledExtensions)) {
+      const filtered = o.enabledExtensions.filter(
+        (x): x is string =>
+          typeof x === "string" && allowedExt.has(x.toLowerCase()),
+      );
+      if (filtered.length > 0)
+        enabledExtensions = [...new Set(filtered.map((x) => x.toLowerCase()))];
+    }
+    return { maxScanDepth, followSymlinks, enabledExtensions };
+  } catch {
+    return defaults;
+  }
+}
+
+export { STORAGE_KEY as LIBRARY_SCAN_PREFERENCES_STORAGE_KEY };