muzical-ui 0.1.1

package/lib/library/resolve-track-file.ts

@@ -0,0 +1,26 @@
+import type { Track } from "@/types/track";
+
+/**
+ * Opens a `File` for a library track using the saved directory handle map.
+ */
+export async function resolveTrackToFile(
+  track: Track,
+  rootHandles: ReadonlyMap<string, FileSystemDirectoryHandle>,
+): Promise<File | null> {
+  const lib = track.library;
+  if (!lib) return null;
+  const root = rootHandles.get(lib.rootId);
+  if (!root) return null;
+  const segments = lib.relativePath.split("/").filter(Boolean);
+  if (segments.length === 0) return null;
+  let dir = root;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const seg = segments[i];
+    if (!seg) return null;
+    dir = await dir.getDirectoryHandle(seg);
+  }
+  const fileName = segments[segments.length - 1];
+  if (!fileName) return null;
+  const fh = await dir.getFileHandle(fileName);
+  return fh.getFile();
+}

package/lib/library/scan-preferences-to-tree-options.ts

@@ -0,0 +1,15 @@
+import type { LibraryScanPreferences } from "@/types/library-scan-preferences";
+import type { ScanTreeOptions } from "@/types/scan-tree-options";
+
+/**
+ * Converts stored scan preferences into options for the directory walk.
+ */
+export default function scanPreferencesToTreeOptions(
+  prefs: LibraryScanPreferences,
+): ScanTreeOptions {
+  return {
+    maxScanDepth: prefs.maxScanDepth,
+    followSymlinks: prefs.followSymlinks,
+    enabledExtensions: new Set(prefs.enabledExtensions),
+  };
+}

package/lib/library/scan-progress-label.ts

@@ -0,0 +1,18 @@
+import type { ScanProgressTick } from "@/lib/library/scan-progress-tick";
+
+/**
+ * Human-readable status line for the library scan notification.
+ */
+export function scanProgressLabel(tick: ScanProgressTick): string {
+  const prefix =
+    tick.rootCount > 1 ? `[${tick.rootIndex + 1}/${tick.rootCount}] ` : "";
+  if (tick.phase === "walk") {
+    return `${prefix}Listing files in ${tick.rootName}…`;
+  }
+  const total = tick.filesTotal ?? 0;
+  const done = tick.filesDone ?? 0;
+  if (total > 0) {
+    return `${prefix}Reading tags (${done}/${total}) · ${tick.rootName}`;
+  }
+  return `${prefix}Reading tags · ${tick.rootName}`;
+}

package/lib/library/scan-progress-percent.ts

@@ -0,0 +1,19 @@
+import type { ScanProgressTick } from "@/lib/library/scan-progress-tick";
+
+/**
+ * Maps scan phase + per-root position to an overall 0–100 percentage.
+ */
+export function scanProgressPercent(tick: ScanProgressTick): number {
+  if (tick.rootCount <= 0) return 0;
+  const perRoot = 100 / tick.rootCount;
+  let value = tick.rootIndex * perRoot;
+  if (tick.phase === "walk") {
+    value += perRoot * 0.12;
+  } else {
+    const total = tick.filesTotal ?? 0;
+    const done = tick.filesDone ?? 0;
+    const metaRatio = total > 0 ? Math.min(1, done / total) : 0;
+    value += perRoot * (0.12 + 0.88 * metaRatio);
+  }
+  return Math.min(100, Math.round(value));
+}

package/lib/library/scan-progress-tick.ts

@@ -0,0 +1,9 @@
+/** Internal progress event emitted while scanning one or more library roots. */
+export type ScanProgressTick = {
+  rootIndex: number;
+  rootCount: number;
+  rootName: string;
+  phase: "walk" | "metadata";
+  filesDone?: number;
+  filesTotal?: number;
+};

package/lib/library/scan-tree.ts

@@ -0,0 +1,191 @@
+import {
+  isAudioFilename,
+  stripAudioExtension,
+} from "@/lib/library/audio-filename";
+import { extractTagsFromAudioFile } from "@/lib/library/read-audio-metadata";
+import type { ScanTreeOptions } from "@/types/scan-tree-options";
+import type { Track } from "@/types/track";
+
+const METADATA_PARSE_CONCURRENCY = 6;
+
+export type PendingAudioFile = {
+  rootId: string;
+  rootDisplayName: string;
+  relativePath: string;
+  handle: FileSystemFileHandle;
+};
+
+/**
+ * Walks a directory tree and collects audio file handles (no I/O on file bodies yet).
+ */
+export async function collectPendingAudioFiles(
+  rootId: string,
+  rootDisplayName: string,
+  dir: FileSystemDirectoryHandle,
+  pathPrefix: string,
+  depth: number,
+  options: ScanTreeOptions,
+  visitedDirs: Set<string>,
+  out: PendingAudioFile[],
+): Promise<void> {
+  if (options.maxScanDepth > 0 && depth >= options.maxScanDepth) return;
+
+  for await (const [name, entry] of dir.entries()) {
+    const rel = pathPrefix ? `${pathPrefix}/${name}` : name;
+    if (entry.kind === "directory") {
+      if (options.followSymlinks && visitedDirs.has(rel)) continue;
+      const nextVisited = options.followSymlinks
+        ? new Set(visitedDirs)
+        : visitedDirs;
+      if (options.followSymlinks) nextVisited.add(rel);
+      await collectPendingAudioFiles(
+        rootId,
+        rootDisplayName,
+        entry as FileSystemDirectoryHandle,
+        rel,
+        depth + 1,
+        options,
+        nextVisited,
+        out,
+      );
+    } else if (
+      entry.kind === "file" &&
+      isAudioFilename(name, options.enabledExtensions)
+    ) {
+      out.push({
+        rootId,
+        rootDisplayName,
+        relativePath: rel,
+        handle: entry as FileSystemFileHandle,
+      });
+    }
+  }
+}
+
+function basenameFromRelativePath(relativePath: string): string {
+  const i = relativePath.lastIndexOf("/");
+  return i >= 0 ? relativePath.slice(i + 1) : relativePath;
+}
+
+function folderAlbumFallback(
+  relativePath: string,
+  rootDisplayName: string,
+): string {
+  const segments = relativePath.split("/").filter(Boolean);
+  if (segments.length > 1) {
+    return segments[segments.length - 2] ?? rootDisplayName;
+  }
+  return rootDisplayName;
+}
+
+async function pendingFileToTrack(
+  p: PendingAudioFile,
+  enabledExtensions: ReadonlySet<string>,
+): Promise<Track> {
+  const fileName = basenameFromRelativePath(p.relativePath);
+  const fallbackTitle = stripAudioExtension(fileName, enabledExtensions);
+  const albumFolder = folderAlbumFallback(p.relativePath, p.rootDisplayName);
+  try {
+    const file = await p.handle.getFile();
+    const tags = await extractTagsFromAudioFile(file);
+    return {
+      id: `lib:${p.rootId}:${p.relativePath}`,
+      title: tags?.title ? tags.title : fallbackTitle,
+      artist: tags?.artist ? tags.artist : "Unknown artist",
+      album: tags?.album ? tags.album : albumFolder,
+      durationSec:
+        tags?.durationSec && tags.durationSec > 0 ? tags.durationSec : 0,
+      audioUrl: null,
+      library: { rootId: p.rootId, relativePath: p.relativePath },
+    };
+  } catch {
+    return {
+      id: `lib:${p.rootId}:${p.relativePath}`,
+      title: fallbackTitle,
+      artist: "Unknown artist",
+      album: albumFolder,
+      durationSec: 0,
+      audioUrl: null,
+      library: { rootId: p.rootId, relativePath: p.relativePath },
+    };
+  }
+}
+
+export type MetadataScanProgress = {
+  filesDone: number;
+  filesTotal: number;
+};
+
+export type DirectoryScanProgress =
+  | { phase: "walk" }
+  | { phase: "metadata"; filesDone: number; filesTotal: number };
+
+/**
+ * Opens files in bounded parallel, parses tags, and returns `Track` rows sorted by path.
+ */
+export async function buildTracksFromPending(
+  pending: readonly PendingAudioFile[],
+  enabledExtensions: ReadonlySet<string>,
+  onProgress?: (progress: MetadataScanProgress) => void,
+): Promise<Track[]> {
+  if (pending.length === 0) return [];
+  const tracks: Track[] = new Array(pending.length);
+  let nextIndex = 0;
+  let filesDone = 0;
+  const filesTotal = pending.length;
+
+  const report = (): void => {
+    onProgress?.({ filesDone, filesTotal });
+  };
+
+  report();
+
+  const worker = async (): Promise<void> => {
+    for (;;) {
+      const i = nextIndex++;
+      if (i >= pending.length) break;
+      tracks[i] = await pendingFileToTrack(
+        pending[i] as PendingAudioFile,
+        enabledExtensions,
+      );
+      filesDone += 1;
+      report();
+    }
+  };
+
+  const n = Math.min(METADATA_PARSE_CONCURRENCY, pending.length);
+  await Promise.all(Array.from({ length: n }, () => worker()));
+  return tracks;
+}
+
+/**
+ * Scans one library root: walk tree, read metadata per audio file, return tracks.
+ */
+export async function scanDirectoryForTracks(
+  rootId: string,
+  rootDisplayName: string,
+  dir: FileSystemDirectoryHandle,
+  options: ScanTreeOptions,
+  onProgress?: (progress: DirectoryScanProgress) => void,
+): Promise<Track[]> {
+  onProgress?.({ phase: "walk" });
+  const pending: PendingAudioFile[] = [];
+  await collectPendingAudioFiles(
+    rootId,
+    rootDisplayName,
+    dir,
+    "",
+    0,
+    options,
+    new Set<string>(),
+    pending,
+  );
+  onProgress?.({ phase: "metadata", filesDone: 0, filesTotal: pending.length });
+  return buildTracksFromPending(
+    pending,
+    options.enabledExtensions,
+    (metadata) => {
+      onProgress?.({ phase: "metadata", ...metadata });
+    },
+  );
+}

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

@@ -0,0 +1,19 @@
+import { LIBRARY_SCAN_PREFERENCES_STORAGE_KEY } from "@/lib/library/read-stored-library-scan-preferences";
+import type { LibraryScanPreferences } from "@/types/library-scan-preferences";
+
+/**
+ * Persists library scan preferences to localStorage.
+ */
+export default function writeStoredLibraryScanPreferences(
+  prefs: LibraryScanPreferences,
+): void {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(
+      LIBRARY_SCAN_PREFERENCES_STORAGE_KEY,
+      JSON.stringify(prefs),
+    );
+  } catch {
+    /* ignore */
+  }
+}

package/lib/mock-playlist.ts

@@ -0,0 +1,47 @@
+import type { Track } from "@/types/track";
+
+/**
+ * Stand-in data until `GET /api/...` (or your route) returns real rows.
+ */
+export const MOCK_PLAYLIST: readonly Track[] = [
+  {
+    id: "1",
+    title: "Northern Lights",
+    artist: "Aurora Fields",
+    album: "Polar Patterns",
+    durationSec: 214,
+    audioUrl: null,
+  },
+  {
+    id: "2",
+    title: "Basement Echo",
+    artist: "Mono City",
+    album: "Concrete Hymns",
+    durationSec: 189,
+    audioUrl: null,
+  },
+  {
+    id: "3",
+    title: "Paper Boats",
+    artist: "June & Tide",
+    album: "Harbor Demos",
+    durationSec: 241,
+    audioUrl: null,
+  },
+  {
+    id: "4",
+    title: "Static Bloom",
+    artist: "Velvet Wire",
+    album: "Lo-Fi Bloom",
+    durationSec: 198,
+    audioUrl: null,
+  },
+  {
+    id: "5",
+    title: "Slow Commute",
+    artist: "Transit Choir",
+    album: "Rush Hour B-Sides",
+    durationSec: 267,
+    audioUrl: null,
+  },
+];

package/lib/musicbrainz/build-musicbrainz-lucene-queries.ts

@@ -0,0 +1,46 @@
+import { escapeLuceneTerm } from "@/lib/musicbrainz/escape-lucene-term";
+
+export type MusicBrainzSearchHints = {
+  artist?: string;
+  album?: string;
+};
+
+/**
+ * Build prioritized Lucene queries for a free-text MusicBrainz search.
+ */
+export function buildMusicBrainzLuceneQueries(raw: string): {
+  queries: string[];
+  hints: MusicBrainzSearchHints;
+} {
+  const trimmed = raw.trim();
+  if (!trimmed) return { queries: [], hints: {} };
+
+  const tokens = trimmed.split(/\s+/).filter(Boolean);
+  const hints: MusicBrainzSearchHints = {};
+
+  if (tokens.length >= 2) {
+    const artist = escapeLuceneTerm(tokens[0]);
+    const albumPhrase = escapeLuceneTerm(tokens.slice(1).join(" "));
+    hints.artist = tokens[0];
+    hints.album = tokens.slice(1).join(" ");
+
+    const second = escapeLuceneTerm(tokens[1]);
+    const queries = [
+      `artist:${artist} AND release:${albumPhrase}`,
+      `artist:${artist} AND release-group:${albumPhrase}`,
+      `artist:${artist} AND releasegroup:${albumPhrase}`,
+    ];
+    if (tokens.length === 2) {
+      queries.push(`artist:${second} AND release:${artist}`);
+    }
+    queries.push(`"${escapeLuceneTerm(trimmed)}"`, trimmed);
+
+    return { hints, queries };
+  }
+
+  const single = escapeLuceneTerm(tokens[0]);
+  return {
+    hints: { artist: tokens[0] },
+    queries: [`artist:${single}`, trimmed],
+  };
+}

package/lib/musicbrainz/escape-lucene-term.ts

@@ -0,0 +1,6 @@
+/**
+ * Escape a user term for MusicBrainz Lucene query syntax.
+ */
+export function escapeLuceneTerm(term: string): string {
+  return term.replace(/([+\-!(){}[\]^"~*?:\\/])/g, "\\$1");
+}

package/lib/musicbrainz/fetch-musicbrainz-json.ts

@@ -0,0 +1,55 @@
+const MUSICBRAINZ_USER_AGENT =
+  "MuzicalUI/1.0 (https://github.com/f3rnox/muzical-ui)";
+
+/**
+ * GET a MusicBrainz JSON API URL.
+ */
+export async function fetchMusicBrainzJson<T>(
+  url: URL,
+  signal?: AbortSignal,
+): Promise<T> {
+  const urlString = url.toString();
+  let response: Response;
+  try {
+    response = await fetch(urlString, {
+      method: "GET",
+      headers: {
+        Accept: "application/json",
+        "User-Agent": MUSICBRAINZ_USER_AGENT,
+      },
+      signal,
+    });
+  } catch (error: unknown) {
+    if (
+      signal?.aborted ||
+      (error instanceof Error && error.name === "AbortError") ||
+      (typeof error === "object" &&
+        error !== null &&
+        "name" in error &&
+        error.name === "AbortError")
+    ) {
+      throw error;
+    }
+    console.error("[MusicBrainz] request failed", { url: urlString, error });
+    throw error;
+  }
+
+  if (!response.ok) {
+    let bodySnippet = "";
+    try {
+      bodySnippet = (await response.text()).slice(0, 300);
+    } catch {
+      /* ignore */
+    }
+    const message = `MusicBrainz request failed (${response.status})`;
+    console.error("[MusicBrainz] request failed", {
+      url: urlString,
+      status: response.status,
+      statusText: response.statusText,
+      body: bodySnippet || undefined,
+    });
+    throw new Error(message);
+  }
+
+  return (await response.json()) as T;
+}

package/lib/musicbrainz/fetch-release-tracks.ts

@@ -0,0 +1,53 @@
+import { fetchMusicBrainzJson } from "@/lib/musicbrainz/fetch-musicbrainz-json";
+import { musicBrainzRecordingToTrack } from "@/lib/musicbrainz/musicbrainz-recording-to-track";
+import type { MusicBrainzReleaseDetail } from "@/lib/musicbrainz/types";
+import type { Track } from "@/types/track";
+
+/**
+ * Load all recordings on a MusicBrainz release as app tracks.
+ */
+export async function fetchReleaseTracks(
+  releaseId: string,
+  albumTitle: string,
+  artistName: string,
+  signal?: AbortSignal,
+): Promise<Track[]> {
+  const url = new URL(`https://musicbrainz.org/ws/2/release/${releaseId}`);
+  url.searchParams.set("inc", "recordings+artist-credits+media");
+  url.searchParams.set("fmt", "json");
+
+  const body = await fetchMusicBrainzJson<MusicBrainzReleaseDetail>(
+    url,
+    signal,
+  );
+  const hints = { artist: artistName, album: albumTitle };
+  const out: Track[] = [];
+  const seen = new Set<string>();
+
+  for (const medium of body.media ?? []) {
+    for (const track of medium.tracks ?? []) {
+      const recording = track.recording;
+      const recordingId = recording?.id;
+      if (!recordingId || seen.has(recordingId)) continue;
+      seen.add(recordingId);
+
+      const merged = recording ?? {
+        id: track.id,
+        title: track.title,
+        length: track.length,
+        "artist-credit": body["artist-credit"],
+      };
+
+      const row = musicBrainzRecordingToTrack(merged, hints, albumTitle);
+      if (!row.title || row.title === "Unknown title") {
+        row.title = track.title?.trim() || row.title;
+      }
+      if (track.length && Number.isFinite(track.length)) {
+        row.durationSec = Math.round(track.length / 1000);
+      }
+      out.push(row);
+    }
+  }
+
+  return out;
+}

package/lib/musicbrainz/group-tracks-by-album.ts

@@ -0,0 +1,26 @@
+import {
+  albumCompositeKey,
+  artistDisplayName,
+} from "@/lib/library/favorite-keys";
+import type { Track } from "@/types/track";
+
+/**
+ * Group tracks by album title and artist (composite key).
+ */
+export function groupTracksByAlbum(
+  tracks: readonly Track[],
+): Map<string, Track[]> {
+  const m = new Map<string, Track[]>();
+  for (const t of tracks) {
+    const key = albumCompositeKey(t.album, artistDisplayName(t.artist));
+    const arr = m.get(key) ?? [];
+    arr.push(t);
+    m.set(key, arr);
+  }
+  for (const arr of m.values()) {
+    arr.sort((a, b) =>
+      a.title.localeCompare(b.title, undefined, { sensitivity: "base" }),
+    );
+  }
+  return m;
+}

package/lib/musicbrainz/group-tracks-by-artist.ts

@@ -0,0 +1,23 @@
+import { artistDisplayName } from "@/lib/library/favorite-keys";
+import type { Track } from "@/types/track";
+
+/**
+ * Group MusicBrainz (or other) tracks by display artist name.
+ */
+export function groupTracksByArtist(
+  tracks: readonly Track[],
+): Map<string, Track[]> {
+  const m = new Map<string, Track[]>();
+  for (const t of tracks) {
+    const a = artistDisplayName(t.artist);
+    const arr = m.get(a) ?? [];
+    arr.push(t);
+    m.set(a, arr);
+  }
+  for (const arr of m.values()) {
+    arr.sort((a, b) =>
+      a.title.localeCompare(b.title, undefined, { sensitivity: "base" }),
+    );
+  }
+  return m;
+}

package/lib/musicbrainz/merge-tracks-by-id.ts

@@ -0,0 +1,16 @@
+import type { Track } from "@/types/track";
+
+/**
+ * Append tracks without duplicate ids.
+ */
+export function mergeTracksById(
+  target: Track[],
+  incoming: readonly Track[],
+): void {
+  const seen = new Set(target.map((t) => t.id));
+  for (const t of incoming) {
+    if (seen.has(t.id)) continue;
+    seen.add(t.id);
+    target.push(t);
+  }
+}

package/lib/musicbrainz/musicbrainz-recording-to-track.ts

@@ -0,0 +1,42 @@
+import type { MusicBrainzSearchHints } from "@/lib/musicbrainz/build-musicbrainz-lucene-queries";
+import { pickPreferredRelease } from "@/lib/musicbrainz/pick-preferred-release";
+import type { MusicBrainzRecording } from "@/lib/musicbrainz/types";
+import type { Track } from "@/types/track";
+
+/**
+ * Map a MusicBrainz recording entity to an app track.
+ */
+export function musicBrainzRecordingToTrack(
+  recording: MusicBrainzRecording,
+  hints: MusicBrainzSearchHints = {},
+  albumOverride?: string,
+): Track {
+  const artist =
+    recording["artist-credit"]
+      ?.map((credit) => credit.name?.trim() || credit.artist?.name?.trim())
+      .filter(Boolean)
+      .join(" & ") ?? "Unknown artist";
+
+  const release = pickPreferredRelease(recording.releases, hints);
+  const album =
+    albumOverride?.trim() ||
+    release?.["release-group"]?.title?.trim() ||
+    release?.title?.trim() ||
+    "Unknown album";
+
+  const title = recording.title?.trim() || "Unknown title";
+  const youtubeQuery = `${title} ${artist}`.trim();
+
+  return {
+    id: `musicbrainz:${recording.id}`,
+    title,
+    artist,
+    album,
+    durationSec:
+      recording.length && Number.isFinite(recording.length)
+        ? Math.round(recording.length / 1000)
+        : 0,
+    source: "musicbrainz",
+    youtubeQuery,
+  };
+}

package/lib/musicbrainz/pick-preferred-release.ts

@@ -0,0 +1,32 @@
+import type { MusicBrainzReleaseRef } from "@/lib/musicbrainz/types";
+import type { MusicBrainzSearchHints } from "@/lib/musicbrainz/build-musicbrainz-lucene-queries";
+
+/**
+ * Choose the release entry that best matches search hints (album/artist).
+ */
+export function pickPreferredRelease(
+  releases: readonly MusicBrainzReleaseRef[] | undefined,
+  hints: MusicBrainzSearchHints,
+): MusicBrainzReleaseRef | undefined {
+  if (!releases?.length) return undefined;
+
+  const albumHint = hints.album?.trim().toLowerCase();
+  if (albumHint) {
+    const exact = releases.find((r) => {
+      const title = r.title?.trim().toLowerCase() ?? "";
+      const rgTitle = r["release-group"]?.title?.trim().toLowerCase() ?? "";
+      return title === albumHint || rgTitle === albumHint;
+    });
+    if (exact) return exact;
+
+    const partial = releases.find((r) => {
+      const title = r.title?.trim().toLowerCase() ?? "";
+      const rgTitle = r["release-group"]?.title?.trim().toLowerCase() ?? "";
+      return title.includes(albumHint) || rgTitle.includes(albumHint);
+    });
+    if (partial) return partial;
+  }
+
+  const official = releases.find((r) => r.status === "Official");
+  return official ?? releases[0];
+}

package/lib/musicbrainz/pick-release-group-release-id.ts

@@ -0,0 +1,12 @@
+import type { MusicBrainzReleaseGroup } from "@/lib/musicbrainz/types";
+
+/**
+ * Pick a representative release id from a release group search hit.
+ */
+export function pickReleaseGroupReleaseId(
+  group: MusicBrainzReleaseGroup,
+): string | null {
+  const releases = group.releases ?? [];
+  const official = releases.find((r) => r.status === "Official");
+  return official?.id ?? releases[0]?.id ?? null;
+}

package/lib/musicbrainz/release-group-artist-name.ts

@@ -0,0 +1,13 @@
+import type { MusicBrainzReleaseGroup } from "@/lib/musicbrainz/types";
+
+/**
+ * Display artist for a release group.
+ */
+export function releaseGroupArtistName(group: MusicBrainzReleaseGroup): string {
+  return (
+    group["artist-credit"]
+      ?.map((c) => c.name?.trim() || c.artist?.name?.trim())
+      .filter(Boolean)
+      .join(" & ") ?? "Unknown artist"
+  );
+}