@freqhole/playlistz 0.0.1

package/e2e/helpers/app.ts

@@ -0,0 +1,143 @@
+// app interaction helpers: navigate, reset state, create playlists, add songs.
+//
+// these helpers drive the real app UI through Playwright. no mock transport
+// hooks here - see hooks.ts for window.__* wrappers.
+
+import { expect, type Page } from "@playwright/test";
+import { makeWav, type FixtureFile } from "./media.js";
+
+// log with a wall-clock timestamp so slow steps and stalls are visible
+// in test output (e.g. "[12:34:56] peer a: p2p node online")
+export function logTs(message: string): void {
+  const now = new Date().toTimeString().slice(0, 8);
+  console.log(`[${now}] ${message}`);
+}
+
+// generate a real PNG in the page via canvas (solid color + optional label text).
+// returns the bytes so they can be dropped or set on file inputs.
+export async function makePng(
+  page: Page,
+  opts: { width?: number; height?: number; color?: string; label?: string } = {}
+): Promise<Uint8Array> {
+  const { width = 64, height = 64, color = "#ff00ff", label = "" } = opts;
+  const base64 = await page.evaluate(
+    async ({ width, height, color, label }) => {
+      const canvas = document.createElement("canvas");
+      canvas.width = width;
+      canvas.height = height;
+      const ctx = canvas.getContext("2d")!;
+      ctx.fillStyle = color;
+      ctx.fillRect(0, 0, width, height);
+      if (label) {
+        ctx.fillStyle = "#000";
+        ctx.font = "12px monospace";
+        ctx.fillText(label, 4, height / 2);
+      }
+      const blob: Blob = await new Promise((res) =>
+        canvas.toBlob((b) => res(b!), "image/png")
+      );
+      const bytes = new Uint8Array(await blob.arrayBuffer());
+      let bin = "";
+      for (const b of bytes) bin += String.fromCharCode(b);
+      return btoa(bin);
+    },
+    { width, height, color, label }
+  );
+  return Uint8Array.from(Buffer.from(base64, "base64"));
+}
+
+// drop files onto the app (simulates drag and drop of audio files / zips).
+export async function dropFiles(page: Page, files: FixtureFile[]): Promise<void> {
+  const payload = files.map((f) => ({
+    name: f.name,
+    mimeType: f.mimeType,
+    base64: Buffer.from(f.bytes).toString("base64"),
+  }));
+  await page.evaluate(async (payload) => {
+    const dt = new DataTransfer();
+    for (const f of payload) {
+      const bin = atob(f.base64);
+      const bytes = new Uint8Array(bin.length);
+      for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+      dt.items.add(new File([bytes], f.name, { type: f.mimeType }));
+    }
+    const target = document.querySelector('[data-testid="app-root"]') ?? document.body;
+    target.dispatchEvent(
+      new DragEvent("drop", { bubbles: true, cancelable: true, dataTransfer: dt })
+    );
+  }, payload);
+}
+
+// wipe all app storage (indexeddb + localstorage) and reload for a clean slate.
+export async function resetAppState(page: Page): Promise<void> {
+  await page.goto("/");
+  await page.evaluate(async () => {
+    localStorage.clear();
+    const dbs = await indexedDB.databases();
+    await Promise.all(
+      dbs.map(
+        (db) =>
+          new Promise<void>((res) => {
+            if (!db.name) return res();
+            const req = indexedDB.deleteDatabase(db.name);
+            req.onsuccess = req.onerror = req.onblocked = () => res();
+          })
+      )
+    );
+  });
+  await page.reload();
+  await waitForApp(page);
+}
+
+// wait for the app shell to finish booting
+export async function waitForApp(page: Page): Promise<void> {
+  await page.getByTestId("app-ready").waitFor({ timeout: 10000 });
+}
+
+// create a playlist via the UI and wait for the playlist header to appear.
+// on a fresh app (no playlists): clicks the "new playlist" button in the empty state.
+// if a playlist is already selected: opens the all-playlists panel via the
+// hamburger and clicks "new playlist" there.
+export async function createPlaylistViaUI(page: Page): Promise<void> {
+  // try the always-visible empty-state button first, fall back to hamburger flow
+  const newBtn = page.getByTestId("btn-new-playlist");
+  const isVisible = await newBtn.isVisible().catch(() => false);
+  if (isVisible) {
+    await newBtn.click();
+  } else {
+    // open all-playlists panel via hamburger
+    await page.getByTestId("btn-all-playlists").click();
+    await page.getByTestId("btn-new-playlist").click();
+  }
+  await page.getByTestId("btn-edit-playlist").waitFor({ timeout: 5000 });
+  // wait for the title input to reflect the new playlist's default title,
+  // confirming the reactive binding is live before callers try to fill it
+  await expect(page.getByTestId("input-playlist-title")).toHaveValue(
+    "new playlist"
+  );
+}
+
+// add n synthetic songs to the selected playlist via drag and drop
+export async function addSongs(page: Page, count: number, durationSec = 1): Promise<void> {
+  const files: FixtureFile[] = [];
+  for (let i = 0; i < count; i++) {
+    files.push({
+      name: `song-${String(i).padStart(2, "0")}.wav`,
+      mimeType: "audio/wav",
+      bytes: makeWav(durationSec, 220 + i * 110),
+    });
+  }
+  await dropFiles(page, files);
+  // wait for the last row to show up
+  await page
+    .getByText(`song-${String(count - 1).padStart(2, "0")}`)
+    .waitFor({ timeout: 15000 });
+}
+
+// set a cover image on the playlist edit panel via the file input
+export async function setPlaylistCover(page: Page, f: FixtureFile): Promise<void> {
+  // use accept="image/*" to distinguish from the + add-songs audio input
+  const input = page.locator("input[type='file'][accept='image/*']").first();
+  await input.waitFor({ state: "attached", timeout: 5000 });
+  await input.setInputFiles({ name: f.name, mimeType: f.mimeType, buffer: Buffer.from(f.bytes) });
+}

package/e2e/helpers/hooks.ts

@@ -0,0 +1,133 @@
+// dev hook wrappers for e2e tests.
+//
+// typed wrappers around window.__* hooks registered by src/dev-hooks.ts.
+// these are only available in DEV builds (the vite dev server).
+//
+// convention: tests that use any mockBlobFetch / clearMockBlobFetch call
+// should tag their test description with "@mock" so they can be run or
+// excluded as a group:
+//
+//   test("downloads blob from peer @mock", async ({ page }) => { ... })
+//
+//   # run only transport-mocked tests:
+//   npm run test:e2e:mock
+//
+//   # run everything except mocked transport tests:
+//   npm run test:e2e:real
+//
+// the time-acceleration hooks (seekTo, triggerTrackEnd, triggerAudioError)
+// are NOT considered "mock" - they accelerate time on the real audio element
+// without substituting any service boundary. use them freely in any test.
+
+import type { Page } from "@playwright/test";
+
+// mock blob behaviour modes - single source of truth is global.d.ts (Window interface).
+// this re-derives the type so e2e tests don't need to import from src/.
+export type MockBlobBehaviour = NonNullable<Window["__mockBlobFetch"]> extends (
+  b: infer B
+) => void
+  ? B
+  : never;
+
+// --- time-acceleration hooks ---
+// these drive the real audio element without substituting any service boundary.
+
+// returns the title of the currently playing song, or null if nothing is playing.
+// use this instead of looking for a DOM element to assert playback state.
+export async function currentSong(page: Page): Promise<string | null> {
+  return page.evaluate(() => window.__currentSong?.() ?? null);
+}
+
+// seek the audio element to a specific time (seconds)
+export async function seekTo(page: Page, seconds: number): Promise<void> {
+  await page.evaluate((t) => window.__seekTo?.(t), seconds);
+}
+
+// fire the "ended" event on the audio element (advance to next track)
+export async function triggerTrackEnd(page: Page): Promise<void> {
+  await page.evaluate(() => window.__triggerTrackEnd?.());
+}
+
+// fire an audio error event (code defaults to MEDIA_ERR_SRC_NOT_SUPPORTED = 4)
+export async function triggerAudioError(page: Page, code = 4): Promise<void> {
+  await page.evaluate((c) => window.__triggerAudioError?.(c), code);
+}
+
+// --- transport mock hooks ---
+// tests that call these should be tagged @mock in their description.
+
+// override p2p blob fetching with a deterministic mock behaviour.
+// call clearMockBlobFetch in afterEach / at the end of each test.
+export async function mockBlobFetch(
+  page: Page,
+  behaviour: MockBlobBehaviour
+): Promise<void> {
+  await page.evaluate(
+    (b) => window.__mockBlobFetch?.(b),
+    behaviour as Parameters<NonNullable<typeof window.__mockBlobFetch>>[0]
+  );
+}
+
+// restore real p2p blob fetching (always call this after a transport mock test)
+export async function clearMockBlobFetch(page: Page): Promise<void> {
+  await page.evaluate(() => window.__clearMockBlobFetch?.());
+}
+
+// --- blob store control ---
+// these manipulate the local blob cache directly; not "mocking" per se,
+// but often used alongside transport mocks to create a cache-miss scenario.
+
+// remove a blob from local store (simulates a cache miss before pressing play)
+export async function evictBlob(page: Page, sha256: string): Promise<void> {
+  await page.evaluate((sha) => window.__evictBlob?.(sha), sha256);
+}
+
+// set the blob fetch timeout in ms (default 30000). use a short value in
+// tests to avoid waiting for the real 30s when testing timeout behaviour.
+// reset to 30000 after the test.
+export async function setBlobFetchTimeout(page: Page, ms: number): Promise<void> {
+  await page.evaluate((t) => window.__setBlobFetchTimeout?.(t), ms);
+}
+
+// programmatically trigger a blob fetch by sha256.
+// useful when the retry click target is obstructed by an overlay element.
+export async function fetchBlobBySha(page: Page, sha256: string): Promise<void> {
+  await page.evaluate((sha) => window.__fetchBlobBySha?.(sha), sha256);
+}
+
+// --- docIndex dev hooks (registered in src/dev-hooks.ts) ---
+
+export interface DocIndexEntry {
+  docId: string;
+  title: string;
+  addedAt: number;
+  source: "local" | "shared" | "freqhole";
+  remoteNodeId?: string;
+  remoteName?: string;
+  isForked?: boolean;
+}
+
+// return all docIndex entries from the running app (via service layer, not raw idb)
+export async function getDocIndexEntries(page: Page): Promise<DocIndexEntry[]> {
+  // the hook is registered after a dynamic import - wait for it to appear
+  await page.waitForFunction(() => typeof window.__getDocIndexEntries === "function", {
+    timeout: 5000,
+  });
+  return page.evaluate(() => window.__getDocIndexEntries!()) as Promise<DocIndexEntry[]>;
+}
+
+// patch a docIndex entry in-place (merge patch), then wait for the app to
+// re-sync its playlist list from the updated docIndex
+export async function patchDocIndexEntry(
+  page: Page,
+  docId: string,
+  patch: Partial<DocIndexEntry>
+): Promise<void> {
+  await page.waitForFunction(() => typeof window.__patchDocIndexEntry === "function", {
+    timeout: 5000,
+  });
+  await page.evaluate(
+    ({ docId, patch }) => window.__patchDocIndexEntry!(docId, patch),
+    { docId, patch }
+  );
+}

package/e2e/helpers/index.ts

@@ -0,0 +1,12 @@
+// barrel re-export for e2e/helpers/.
+//
+// existing spec files import from "../helpers.js" - this keeps that working.
+// new code can import directly from the sub-modules for clarity:
+//   import { makeWav } from "../helpers/media.js"
+//   import { resetAppState } from "../helpers/app.js"
+//   import { mockBlobFetch } from "../helpers/hooks.js"
+
+export * from "./media.js";
+export * from "./app.js";
+export * from "./hooks.js";
+export * from "./hooks.js";

package/e2e/helpers/media.ts

@@ -0,0 +1,125 @@
+// synthetic media generation and fixture file loading.
+//
+// no Playwright Page imports here - everything is pure data or Node fs ops.
+// used by both app helpers and spec files directly.
+
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const FIXTURES_DIR = join(dirname(fileURLToPath(import.meta.url)), "../fixtures");
+const USER_PROVIDED_DIR = join(FIXTURES_DIR, "user-provided");
+
+// --- synthetic audio ---
+
+// build a valid mono 16-bit PCM WAV file with a sine tone.
+// durationSec controls both file size and the decoded duration shown in the UI.
+export function makeWav(durationSec = 1, freqHz = 440): Uint8Array {
+  const sampleRate = 8000;
+  const numSamples = Math.floor(sampleRate * durationSec);
+  const dataSize = numSamples * 2;
+  const buf = new ArrayBuffer(44 + dataSize);
+  const view = new DataView(buf);
+  const writeStr = (offset: number, s: string) => {
+    for (let i = 0; i < s.length; i++) view.setUint8(offset + i, s.charCodeAt(i));
+  };
+  writeStr(0, "RIFF");
+  view.setUint32(4, 36 + dataSize, true);
+  writeStr(8, "WAVE");
+  writeStr(12, "fmt ");
+  view.setUint32(16, 16, true); // fmt chunk size
+  view.setUint16(20, 1, true); // PCM
+  view.setUint16(22, 1, true); // mono
+  view.setUint32(24, sampleRate, true);
+  view.setUint32(28, sampleRate * 2, true); // byte rate
+  view.setUint16(32, 2, true); // block align
+  view.setUint16(34, 16, true); // bits per sample
+  writeStr(36, "data");
+  view.setUint32(40, dataSize, true);
+  for (let i = 0; i < numSamples; i++) {
+    const sample = Math.sin((2 * Math.PI * freqHz * i) / sampleRate);
+    view.setInt16(44 + i * 2, Math.floor(sample * 0x4fff), true);
+  }
+  return new Uint8Array(buf);
+}
+
+// --- fixture file type ---
+
+export interface FixtureFile {
+  name: string;
+  mimeType: string;
+  bytes: Uint8Array;
+}
+
+const AUDIO_EXT: Record<string, string> = {
+  ".mp3": "audio/mpeg",
+  ".wav": "audio/wav",
+  ".flac": "audio/flac",
+  ".ogg": "audio/ogg",
+  ".m4a": "audio/mp4",
+};
+
+const IMAGE_EXT: Record<string, string> = {
+  ".png":  "image/png",
+  ".jpg":  "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+};
+
+function loadAudioDir(dir: string): FixtureFile[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => Object.keys(AUDIO_EXT).some((ext) => f.toLowerCase().endsWith(ext)))
+    .map((f) => {
+      const ext = Object.keys(AUDIO_EXT).find((e) => f.toLowerCase().endsWith(e))!;
+      return {
+        name: f,
+        mimeType: AUDIO_EXT[ext]!,
+        bytes: new Uint8Array(readFileSync(join(dir, f))),
+      };
+    });
+}
+
+function loadImageDir(dir: string): FixtureFile[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => Object.keys(IMAGE_EXT).some((ext) => f.toLowerCase().endsWith(ext)))
+    .map((f) => {
+      const ext = Object.keys(IMAGE_EXT).find((e) => f.toLowerCase().endsWith(e))!;
+      return {
+        name: f,
+        mimeType: IMAGE_EXT[ext]!,
+        bytes: new Uint8Array(readFileSync(join(dir, f))),
+      };
+    });
+}
+
+// committed audio fixtures (WAV sine waves, generated by generate.mjs).
+// always available; never returns [].
+export function loadCommittedAudioFixtures(): FixtureFile[] {
+  return loadAudioDir(FIXTURES_DIR);
+}
+
+// committed image fixtures (PNG patterns, generated by generate.mjs).
+// always available; never returns [].
+export function loadCommittedImageFixtures(): FixtureFile[] {
+  return loadImageDir(FIXTURES_DIR);
+}
+
+// load all audio files from both committed fixtures and user-provided/.
+// user-provided/ is gitignored so returns [] when not present.
+export function loadRealAudioFixtures(): FixtureFile[] {
+  return [...loadAudioDir(FIXTURES_DIR), ...loadAudioDir(USER_PROVIDED_DIR)];
+}
+
+// load all image files from both committed fixtures and user-provided/.
+export function loadRealImageFixtures(): FixtureFile[] {
+  return [...loadImageDir(FIXTURES_DIR), ...loadImageDir(USER_PROVIDED_DIR)];
+}
+
+// load a single committed fixture by filename
+export function fixture(name: string): FixtureFile {
+  const ext = `.${name.split(".").pop()!.toLowerCase()}`;
+  const mimeType = AUDIO_EXT[ext] ?? IMAGE_EXT[ext] ?? "application/octet-stream";
+  return { name, mimeType, bytes: new Uint8Array(readFileSync(join(FIXTURES_DIR, name))) };
+}

package/e2e/helpers.ts

@@ -0,0 +1,10 @@
+// re-export shim - the helpers have been split into e2e/helpers/:
+//
+//   helpers/media.ts  - makeWav, fixture loading (no Page deps)
+//   helpers/app.ts    - resetAppState, createPlaylistViaUI, addSongs, etc.
+//   helpers/hooks.ts  - window.__* dev hook wrappers + MockBlobBehaviour type
+//
+// existing spec imports ("./helpers.js") continue to work unchanged.
+// new spec files should import directly from the sub-modules for clarity.
+
+export * from "./helpers/index.js";