@freqhole/playlistz 0.0.1

package/e2e/p2p-states.spec.ts

@@ -0,0 +1,302 @@
+// e2e: p2p blob transfer state machine - mocked transport scenarios.
+//
+// all tests use __mockBlobFetch + __evictBlob to simulate p2p behaviour
+// deterministically in a single browser without a real peer connection.
+//
+// companion to audio-player.spec.ts which covers the basic happy path.
+// this file focuses on: pending state, timeout, retry, prefetch triggering,
+// and prefetch cancellation on playlist switch.
+
+import { test, expect } from "@playwright/test";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  resetAppState,
+  createPlaylistViaUI,
+  addSongs,
+  seekTo,
+  mockBlobFetch,
+  clearMockBlobFetch,
+  evictBlob,
+  setBlobFetchTimeout,
+  fetchBlobBySha,
+  currentSong,
+} from "./helpers.js";
+
+const FIXTURES_DIR = join(dirname(fileURLToPath(import.meta.url)), "fixtures");
+
+test.beforeEach(async ({ page }) => {
+  await resetAppState(page);
+});
+
+// import a committed fixture via the __processFiles dev hook
+async function importFixture(
+  page: Parameters<typeof evictBlob>[0],
+  filename: string,
+  mimeType = "audio/wav"
+): Promise<void> {
+  const bytes = readFileSync(join(FIXTURES_DIR, filename));
+  const result = await page.evaluate(
+    async ({ b64, name, mime }: { b64: string; name: string; mime: string }) => {
+      const bin = atob(b64);
+      const arr = new Uint8Array(bin.length);
+      for (let i = 0; i < bin.length; i++) arr[i] = bin.charCodeAt(i);
+      const file = new File([arr], name, { type: mime });
+      const hook = (
+        window as Window & { __processFiles?: (files: File[]) => Promise<void> }
+      ).__processFiles;
+      if (!hook) return "hook-missing";
+      await hook([file]);
+      return "ok";
+    },
+    { b64: Buffer.from(bytes).toString("base64"), name: filename, mime: mimeType }
+  );
+  if (result !== "ok") throw new Error(`importFixture failed: ${result}`);
+}
+
+// get the sha256 of the first song row's blob
+async function firstSongSha(
+  page: Parameters<typeof evictBlob>[0]
+): Promise<string | null> {
+  const cell = page.getByTestId("song-duration").first();
+  await cell.waitFor({ timeout: 8000 });
+  return cell.getAttribute("data-sha256");
+}
+
+// --- pending state ---
+
+test("prefetch marks songs pending before fetch starts @mock", async ({ page }) => {
+  test.setTimeout(30_000);
+  await createPlaylistViaUI(page);
+  // 3 songs: song-00 plays, song-01 and song-02 should enter pending state
+  await addSongs(page, 3, 2);
+
+  // stall fetches so we can observe pending state before resolve
+  await mockBlobFetch(page, { type: "stall" });
+
+  // evict all blobs so prefetch has something to fetch
+  const cells = page.getByTestId("song-duration");
+  const count = await cells.count();
+  for (let i = 0; i < count; i++) {
+    const sha = await cells.nth(i).getAttribute("data-sha256");
+    if (sha) await evictBlob(page, sha);
+  }
+
+  // start playback on song-00 - this triggers prefetchUpcoming for songs 1+2
+  await page.getByText("song-00").dblclick();
+  await expect
+    .poll(() => currentSong(page), { timeout: 10000 })
+    .toBe("song-00");
+
+  // at least one upcoming song should show pending or downloading state while fetches are stalled
+  await expect(
+    page.locator("[data-testid='song-duration'][data-download-state]").first()
+  ).toBeVisible({ timeout: 5000 });
+
+  // clean up
+  await clearMockBlobFetch(page);
+});
+
+// --- fetch timeout ---
+
+test("blob fetch timeout: song shows error state after timeout @mock", async ({
+  page,
+}) => {
+  test.setTimeout(20_000);
+  await createPlaylistViaUI(page);
+  await importFixture(page, "tone-440hz-2s.wav");
+  await expect(page.getByText("tone-440hz-2s")).toBeVisible({ timeout: 10000 });
+
+  const durationCell = page.getByTestId("song-duration").first();
+  const sha256 = await firstSongSha(page);
+
+  if (sha256) {
+    await evictBlob(page, sha256);
+    // set a very short timeout so the test doesn't wait 30s
+    await setBlobFetchTimeout(page, 500);
+    await mockBlobFetch(page, { type: "stall" });
+  }
+
+  await page.getByText("tone-440hz-2s").dblclick();
+
+  if (sha256) {
+    // after ~500ms timeout, state should flip to error
+    await expect(durationCell).toHaveAttribute("data-download-state", "error", {
+      timeout: 5000,
+    });
+    await clearMockBlobFetch(page);
+    // reset timeout to default
+    await setBlobFetchTimeout(page, 30_000);
+  }
+});
+
+// --- retry on error ---
+
+test("error duration cell has retry affordance and retry clears error state @mock", async ({ page }) => {
+  test.setTimeout(20_000);
+  await createPlaylistViaUI(page);
+  await importFixture(page, "tone-440hz-2s.wav");
+  await expect(page.getByText("tone-440hz-2s")).toBeVisible({ timeout: 10000 });
+
+  const durationCell = page.getByTestId("song-duration").first();
+  const sha256 = await firstSongSha(page);
+
+  if (sha256) {
+    await evictBlob(page, sha256);
+    // make the fetch error immediately
+    await mockBlobFetch(page, { type: "error", code: "not_found" });
+  }
+
+  await page.getByText("tone-440hz-2s").dblclick();
+
+  if (sha256) {
+    await expect(durationCell).toHaveAttribute("data-download-state", "error", {
+      timeout: 8000,
+    });
+
+    // error state should expose a retry affordance (cursor-pointer class)
+    await expect(durationCell).toHaveClass(/cursor-pointer/);
+
+    // switch mock to instant and trigger retry programmatically.
+    // clicking the cell via Playwright is unreliable here because the
+    // song-row action-buttons overlay sits on top of the duration cell.
+    await mockBlobFetch(page, { type: "instant" });
+    await fetchBlobBySha(page, sha256);
+
+    // error state should clear after successful retry
+    await expect(durationCell).not.toHaveAttribute(
+      "data-download-state",
+      "error",
+      { timeout: 5000 }
+    );
+    await clearMockBlobFetch(page);
+  }
+});
+
+// --- prefetch triggered on play ---
+
+test("prefetch activates for upcoming songs when playback starts @mock", async ({
+  page,
+}) => {
+  test.setTimeout(30_000);
+  await createPlaylistViaUI(page);
+  await addSongs(page, 3, 2);
+
+  // evict all blobs so there's something to prefetch
+  const cells = page.getByTestId("song-duration");
+  const count = await cells.count();
+  for (let i = 0; i < count; i++) {
+    const sha = await cells.nth(i).getAttribute("data-sha256");
+    if (sha) await evictBlob(page, sha);
+  }
+
+  // instant mock - prefetch should complete quickly
+  await mockBlobFetch(page, { type: "instant" });
+
+  await page.getByText("song-00").dblclick();
+  await expect
+    .poll(() => currentSong(page), { timeout: 10000 })
+    .toBe("song-00");
+
+  // after a short wait, the upcoming songs' download states should clear
+  // (instant mock means they resolve immediately - no "downloading" lingers)
+  await page.waitForTimeout(1000);
+  const anyDownloading = await page.evaluate(() => {
+    const cells = document.querySelectorAll("[data-download-state]");
+    return Array.from(cells).some(
+      (el) => el.getAttribute("data-download-state") === "downloading"
+    );
+  });
+  expect(anyDownloading).toBe(false);
+
+  await clearMockBlobFetch(page);
+});
+
+// --- prefetch cancels on playlist switch ---
+
+test("prefetch for old playlist cancels when switching to new playlist @mock", async ({
+  page,
+}) => {
+  test.setTimeout(40_000);
+
+  // create playlist A with 3 songs
+  await createPlaylistViaUI(page);
+  await addSongs(page, 3, 2);
+
+  // evict all blobs from playlist A
+  const cells = page.getByTestId("song-duration");
+  const count = await cells.count();
+  for (let i = 0; i < count; i++) {
+    const sha = await cells.nth(i).getAttribute("data-sha256");
+    if (sha) await evictBlob(page, sha);
+  }
+
+  // stall fetches - playlist A prefetch will hang
+  await mockBlobFetch(page, { type: "stall" });
+
+  // start playback on playlist A song-00 (triggers prefetch for song-01, song-02)
+  await page.getByText("song-00").dblclick();
+  await expect
+    .poll(() => currentSong(page), { timeout: 10000 })
+    .toBe("song-00");
+
+  // create playlist B and switch to it - this should cancel playlist A's prefetch
+  await createPlaylistViaUI(page);
+  await addSongs(page, 1, 2);
+
+  // switch mock to instant so playlist B can prefetch cleanly
+  await mockBlobFetch(page, { type: "instant" });
+
+  // after switching, playlist A's stalled prefetches should be abandoned.
+  // the pending/downloading states on those shas should not appear on playlist B's songs.
+  await page.waitForTimeout(800);
+
+  // playlist B's song row should be visible (strict-safe: use testid, not song name text)
+  await expect(page.getByTestId("song-duration").first()).toBeVisible();
+  // pending states should be cleared after switching playlists.
+  // (in-flight "downloading" states may persist until the stall mock times out -
+  // that is expected. what matters is queued-but-not-started "pending" states are gone.)
+  const pendingCount = await page.evaluate(() =>
+    document.querySelectorAll("[data-download-state='pending']").length
+  );
+  expect(pendingCount).toBe(0);
+
+  await clearMockBlobFetch(page);
+});
+
+// --- seek recalculates prefetch window ---
+
+test("seeking forward recalculates the prefetch window @mock", async ({ page }) => {
+  test.setTimeout(30_000);
+  await createPlaylistViaUI(page);
+  await addSongs(page, 4, 2); // 4x 2s songs
+
+  // evict songs 2-4 blobs so there's something to prefetch
+  const cells = page.getByTestId("song-duration");
+  const count = await cells.count();
+  for (let i = 1; i < count; i++) {
+    const sha = await cells.nth(i).getAttribute("data-sha256");
+    if (sha) await evictBlob(page, sha);
+  }
+
+  // use instant mock so prefetch resolves immediately
+  await mockBlobFetch(page, { type: "instant" });
+
+  await page.getByText("song-00").dblclick();
+  await expect
+    .poll(() => currentSong(page), { timeout: 10000 })
+    .toBe("song-00");
+
+  // seek near the end of song-00 - should re-trigger prefetchUpcoming
+  await seekTo(page, 1.8);
+
+  // brief wait then assert no downloading states are stuck
+  await page.waitForTimeout(800);
+  const downloading = await page.evaluate(() =>
+    document.querySelectorAll("[data-download-state='downloading']").length
+  );
+  expect(downloading).toBe(0);
+
+  await clearMockBlobFetch(page);
+});

package/e2e/playback.spec.ts

@@ -0,0 +1,56 @@
+// e2e: audio playback with synthetic WAV tones.
+
+import { test, expect } from "@playwright/test";
+import { resetAppState, createPlaylistViaUI, addSongs } from "./helpers.js";
+
+test.beforeEach(async ({ page }) => {
+  await resetAppState(page);
+});
+
+test("double-clicking a song row starts playback", async ({ page }) => {
+  await createPlaylistViaUI(page);
+  await addSongs(page, 2, 2);
+
+  // desktop rows play on double click
+  await page.getByText("song-00").dblclick();
+
+  // the playlist play button switches to its "playing" state (magenta bg + pause icon)
+  await expect(page.locator("button.bg-magenta-500").first()).toBeVisible({
+    timeout: 10000,
+  });
+});
+
+test("decoded duration shows in the row", async ({ page }) => {
+  await createPlaylistViaUI(page);
+  // 2-second tone -> row should show 0:02 once metadata is decoded
+  await addSongs(page, 1, 2);
+
+  await expect(page.getByText("0:02").first()).toBeVisible({ timeout: 15000 });
+});
+
+test("all-playlists thumbnail shows a play icon while the playlist plays", async ({
+  page,
+}) => {
+  await createPlaylistViaUI(page);
+  await addSongs(page, 2, 2);
+
+  // start playback on the first playlist
+  await page.getByText("song-00").dblclick();
+  await expect(page.locator("button.bg-magenta-500").first()).toBeVisible({
+    timeout: 10000,
+  });
+
+  // create a second playlist so the first one (playing) appears as a row
+  // (the selected playlist is excluded from panel rows)
+  await page.getByTestId("btn-all-playlists").click();
+  await page.getByTestId("btn-new-playlist").click();
+  await page.getByTestId("btn-edit-playlist").waitFor();
+
+  // open the panel - the first playlist (still playing) is now a row
+  await page.getByTestId("btn-all-playlists").click();
+  await page.getByTestId("all-playlists-panel").waitFor();
+
+  await expect(page.getByTestId("row-playing-indicator")).toBeVisible({
+    timeout: 8000,
+  });
+});

package/e2e/playlist-crud.spec.ts

@@ -0,0 +1,126 @@
+// e2e: playlist creation, song adding, and persistence across reloads.
+
+import { test, expect } from "@playwright/test";
+import {
+  resetAppState,
+  createPlaylistViaUI,
+  addSongs,
+  waitForApp,
+  makePng,
+} from "./helpers.js";
+
+test.beforeEach(async ({ page }) => {
+  await resetAppState(page);
+});
+
+test("create a playlist via the sidebar", async ({ page }) => {
+  await createPlaylistViaUI(page);
+  await expect(page.getByTestId("empty-songs")).toBeVisible();
+  await expect(page.getByTestId("input-playlist-title")).toHaveValue(
+    "new playlist"
+  );
+});
+
+test("add songs via drag and drop", async ({ page }) => {
+  await createPlaylistViaUI(page);
+  await addSongs(page, 3);
+
+  await expect(page.getByText("song-00")).toBeVisible();
+  await expect(page.getByText("song-01")).toBeVisible();
+  await expect(page.getByText("song-02")).toBeVisible();
+  await expect(page.getByTestId("playlist-song-count").first()).toBeVisible();
+});
+
+test("songs survive a page reload", async ({ page }) => {
+  // regression: after reload the song registry was empty and every
+  // row rendered "song not found"
+  await createPlaylistViaUI(page);
+  await addSongs(page, 2);
+
+  await page.reload();
+  await waitForApp(page);
+
+  await expect(page.getByText("song-00")).toBeVisible({ timeout: 10000 });
+  await expect(page.getByText("song-01")).toBeVisible();
+  await expect(page.getByText("song not found")).toHaveCount(0);
+});
+
+test("playlist title edit persists across reload", async ({ page }) => {
+  await createPlaylistViaUI(page);
+
+  const title = page.getByTestId("input-playlist-title");
+  await title.fill("doom mix");
+  await title.blur();
+  await page.waitForTimeout(500);
+
+  await page.reload();
+  await waitForApp(page);
+
+  await expect(page.getByTestId("input-playlist-title")).toHaveValue(
+    "doom mix",
+    { timeout: 10000 }
+  );
+});
+
+test("playlist cover image persists across reload", async ({ page }) => {
+  // regression: images appeared once then were "lost" after reload
+  await createPlaylistViaUI(page);
+  await addSongs(page, 1);
+
+  // open the edit panel and upload a cover
+  await page.getByTestId("btn-edit-playlist").click();
+  const fileInput = page.locator("input[type='file']").first();
+  await fileInput.waitFor({ state: "attached", timeout: 5000 });
+
+  const png = await makePng(page, { color: "#00ffcc", label: "cover" });
+  await fileInput.setInputFiles({
+    name: "cover.png",
+    mimeType: "image/png",
+    buffer: Buffer.from(png),
+  });
+
+  // cover preview appears in the edit panel
+  await expect(page.getByTestId("edit-panel").locator("img[alt='playlist cover']").first()).toBeVisible(
+    { timeout: 10000 }
+  );
+
+  await page.reload();
+  await waitForApp(page);
+
+  // re-open edit panel and confirm the cover is still there from blob store
+  await page.getByTestId("btn-edit-playlist").click();
+  await expect(page.getByTestId("edit-panel").locator("img[alt='playlist cover']").first()).toBeVisible({
+    timeout: 10000,
+  });
+});
+
+test("selected playlist is restored after a page reload", async ({ page }) => {
+  // create two playlists and select the second one, then reload.
+  // the app should re-select the second playlist rather than defaulting
+  // to the first one.
+  await createPlaylistViaUI(page);
+  await page.getByTestId("input-playlist-title").fill("first");
+  await page.getByTestId("input-playlist-title").blur();
+
+  // create a second playlist via the all-playlists panel
+  await page.getByTestId("btn-all-playlists").click();
+  await page.getByTestId("btn-new-playlist").click();
+  await page.getByTestId("btn-edit-playlist").waitFor({ timeout: 5000 });
+  await page.getByTestId("input-playlist-title").click({ clickCount: 3 });
+  await page.getByTestId("input-playlist-title").fill("second");
+  await page.getByTestId("input-playlist-title").blur();
+
+  // "second" is currently selected
+  await expect(page.getByTestId("input-playlist-title")).toHaveValue("second");
+
+  // wait a moment for the saveSetting idb write to complete
+  await page.waitForTimeout(300);
+
+  await page.reload();
+  await waitForApp(page);
+
+  // should restore "second", not fall back to "first"
+  await expect(page.getByTestId("input-playlist-title")).toHaveValue("second", {
+    timeout: 10000,
+  });
+});

package/e2e/share-link-autoplay.spec.ts

@@ -0,0 +1,129 @@
+// e2e: share link auto-play - navigate to /?#share/<token> with a local doc.
+//
+// the share link auto-play flow (§3a) works even without p2p for docs that
+// are already in local idb - repo.find() resolves from local storage.
+// we construct a synthetic #share/ token pointing at a real docId read
+// from the idb docIndex after creating a playlist.
+
+import { test, expect } from "@playwright/test";
+import {
+  resetAppState,
+  createPlaylistViaUI,
+  addSongs,
+  waitForApp,
+} from "./helpers.js";
+
+// read the first docId from the app's musicPlaylistDB docIndex store.
+// returns null if the store is empty.
+async function readFirstDocId(page: ReturnType<typeof import("@playwright/test")["test"]["info"]> extends never ? never : import("@playwright/test").Page): Promise<string | null> {
+  return page.evaluate(() => {
+    return new Promise<string | null>((resolve) => {
+      const req = indexedDB.open("musicPlaylistDB");
+      req.onerror = () => resolve(null);
+      req.onsuccess = () => {
+        const db = req.result;
+        if (!db.objectStoreNames.contains("docIndex")) { resolve(null); return; }
+        const tx = db.transaction("docIndex", "readonly");
+        const store = tx.objectStore("docIndex");
+        const all = store.getAll();
+        all.onsuccess = () => {
+          const entries = all.result as Array<{ docId: string }>;
+          resolve(entries.length > 0 ? entries[0]!.docId : null);
+        };
+        all.onerror = () => resolve(null);
+      };
+    });
+  });
+}
+
+// base64url-encode a share token (matches encodeShareToken in freqhole-api-client).
+// done in Node.js so we don't need a browser context.
+function buildShareToken(docId: string, nodeId = "local", title = "test playlist"): string {
+  const payload = JSON.stringify({ v: 1, n: nodeId, d: docId, t: title });
+  const b64 = Buffer.from(payload).toString("base64");
+  // base64url: replace + with -, / with _, strip =
+  return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+
+test.beforeEach(async ({ page }) => {
+  await resetAppState(page);
+});
+
+test("navigating to a #share/ link selects the playlist", async ({ page }) => {
+  // set up: create a playlist with songs
+  await createPlaylistViaUI(page);
+  await addSongs(page, 2);
+  await page.getByTestId("input-playlist-title").fill("share target");
+  await page.getByTestId("input-playlist-title").blur();
+  await page.waitForTimeout(500);
+
+  // read the docId from idb
+  const docId = await readFirstDocId(page);
+  expect(docId).toBeTruthy();
+
+  // navigate to a share link pointing at that docId
+  const token = buildShareToken(docId!);
+  await page.goto(`/?#share/${token}`);
+  await waitForApp(page);
+
+  // the playlist with that title should be selected
+  // (either in the edit input or as the active playlist header)
+  await expect(
+    page.getByTestId("input-playlist-title").or(
+      page.getByText("share target").first()
+    )
+  ).toBeVisible({ timeout: 10000 });
+});
+
+test("#share/ link for a doc already in idb does not show an error", async ({ page }) => {
+  await createPlaylistViaUI(page);
+  await addSongs(page, 1);
+  await page.waitForTimeout(500);
+
+  const docId = await readFirstDocId(page);
+  expect(docId).toBeTruthy();
+
+  // capture console errors
+  const errors: string[] = [];
+  page.on("console", (msg) => {
+    if (msg.type() === "error") errors.push(msg.text());
+  });
+
+  const token = buildShareToken(docId!);
+  await page.goto(`/?#share/${token}`);
+  await waitForApp(page);
+  await page.waitForTimeout(1000);
+
+  // no app-level error banner
+  await expect(page.getByText(/failed to initialize/i)).not.toBeVisible();
+  // no js errors about the share link itself
+  const shareErrors = errors.filter((e) => e.includes("share") || e.includes("invalid share link"));
+  expect(shareErrors).toHaveLength(0);
+});
+
+test("#share/ fragment is cleared from the url after processing", async ({ page }) => {
+  await createPlaylistViaUI(page);
+  await page.waitForTimeout(500);
+
+  const docId = await readFirstDocId(page);
+  expect(docId).toBeTruthy();
+
+  const token = buildShareToken(docId!);
+  await page.goto(`/?#share/${token}`);
+  await waitForApp(page);
+  await page.waitForTimeout(1000);
+
+  // handleShareFragment calls history.replaceState to clear the fragment.
+  // this is async (depends on p2p initialization), so poll until done.
+  await page.waitForFunction(
+    () => !window.location.hash.startsWith("#share/"),
+    { timeout: 10000 }
+  );
+});
+
+test("invalid #share/ token shows no crash and loads app normally", async ({ page }) => {
+  await page.goto("/?#share/thisisnotavalidtoken");
+  await waitForApp(page);
+  // app should still load without a white screen
+  await expect(page.getByRole("heading", { name: "playlistz" })).toBeAttached();
+});