@freqhole/playlistz 0.0.1

package/src/context/PlaylistzContext.tsx

@@ -0,0 +1,74 @@
+
+import { createContext, useContext, ParentComponent } from "solid-js";
+import { usePlaylistManager } from "../hooks/usePlaylistManager.js";
+
+import { useSongState } from "../hooks/useSongState.js";
+import { useUIState } from "../hooks/useUIState.js";
+import { useDragAndDrop } from "../hooks/useDragAndDrop.js";
+import { useImageModal } from "../hooks/useImageModal.js";
+
+interface PlaylistzContextType {
+  playlistManager: ReturnType<typeof usePlaylistManager>;
+  songState: ReturnType<typeof useSongState>;
+  uiState: ReturnType<typeof useUIState>;
+  dragAndDrop: ReturnType<typeof useDragAndDrop>;
+  imageModal: ReturnType<typeof useImageModal>;
+}
+
+const PlaylistzContext = createContext<PlaylistzContextType>();
+
+// provider component
+export const PlaylistzProvider: ParentComponent = (props) => {
+  // init all hookz once at the top level
+  const playlistManager = usePlaylistManager();
+  const songState = useSongState();
+  const uiState = useUIState();
+  const dragAndDrop = useDragAndDrop();
+  const imageModal = useImageModal();
+
+  const contextValue: PlaylistzContextType = {
+    playlistManager,
+    songState,
+    uiState,
+    dragAndDrop,
+    imageModal,
+  };
+
+  return (
+    <PlaylistzContext.Provider value={contextValue}>
+      {props.children}
+    </PlaylistzContext.Provider>
+  );
+};
+
+// hook to use the context
+export function usePlaylistzContext() {
+  const context = useContext(PlaylistzContext);
+  if (!context) {
+    throw new Error(
+      "usePlaylistzContext must be used within a PlaylistzProvider"
+    );
+  }
+  return context;
+}
+
+// individual hookz for convenience
+export function usePlaylistzManager() {
+  return usePlaylistzContext().playlistManager;
+}
+
+export function usePlaylistzSongs() {
+  return usePlaylistzContext().songState;
+}
+
+export function usePlaylistzUI() {
+  return usePlaylistzContext().uiState;
+}
+
+export function usePlaylistzDragDrop() {
+  return usePlaylistzContext().dragAndDrop;
+}
+
+export function usePlaylistzImageModal() {
+  return usePlaylistzContext().imageModal;
+}

package/src/dev-hooks.ts

@@ -0,0 +1,35 @@
+// dev-only module: registers window.__* test hooks.
+//
+// this file is dynamically imported only when import.meta.env.DEV is true
+// (see src/components/index.tsx). never present in production builds.
+//
+// the actual mock implementations live next to their service:
+//   src/services/audioService.dev.ts       - __seekTo, __triggerTrackEnd, __triggerAudioError
+//   src/services/blobTransferService.dev.ts - __mockBlobFetch, __clearMockBlobFetch,
+//                                             __evictBlob, __setBlobFetchTimeout, __fetchBlobBySha
+//
+// this file only imports and calls the register functions.
+
+import { registerAudioDevHooks } from "./services/audioService.dev.js";
+import { registerBlobDevHooks } from "./services/blobTransferService.dev.js";
+import { getAllDocIndexEntries, addDocIndexEntry } from "./services/docIndexService.js";
+import type { DocIndexEntry } from "./services/indexedDBService.js";
+
+registerAudioDevHooks();
+registerBlobDevHooks();
+
+// docIndex test hooks: allow e2e tests to read/patch docIndex entries without
+// raw idb access, so they use the same service layer as the app.
+(window as Window & {
+  __getDocIndexEntries?: () => Promise<DocIndexEntry[]>;
+  __patchDocIndexEntry?: (docId: string, patch: Partial<DocIndexEntry>) => Promise<void>;
+}).__getDocIndexEntries = getAllDocIndexEntries;
+
+(window as Window & {
+  __patchDocIndexEntry?: (docId: string, patch: Partial<DocIndexEntry>) => Promise<void>;
+}).__patchDocIndexEntry = async (docId: string, patch: unknown) => {
+  const entries = await getAllDocIndexEntries();
+  const existing = entries.find((e) => e.docId === docId);
+  if (!existing) throw new Error(`docIndex entry not found: ${docId}`);
+  await addDocIndexEntry({ ...existing, ...(patch as Partial<DocIndexEntry>) });
+};

package/src/hooks/createDocIndexQuery.ts

@@ -0,0 +1,53 @@
+// solid hook: reactive list of docIndex entries for the sidebar.
+//
+// follows the same live-query pattern as usePlaylistsQuery:
+// - initial fetch on mount
+// - BroadcastChannel listener for cross-tab invalidation
+// - onCleanup closes the channel when the owner is disposed
+
+import { createSignal, onCleanup } from "solid-js";
+import type { Accessor } from "solid-js";
+import { getAllDocIndexEntries, DOC_INDEX_CHANGE_EVENT } from "../services/docIndexService.js";
+import { DB_NAME, DOC_INDEX_STORE } from "../services/indexedDBService.js";
+import type { DocIndexEntry } from "../services/indexedDBService.js";
+import { log } from "../utils/log.js";
+
+// returns a solid accessor that stays up-to-date with the docIndex store.
+// call inside a component or createRoot.
+export function createDocIndexQuery(): Accessor<DocIndexEntry[]> {
+  const [entries, setEntries] = createSignal<DocIndexEntry[]>([], {
+    equals: false,
+  });
+
+  let _refreshCalls = 0;
+  async function refresh(): Promise<void> {
+    _refreshCalls++;
+    log.debug("docindex", "refresh #", String(_refreshCalls));
+    const all = await getAllDocIndexEntries();
+    log.debug("docindex", "refresh #", String(_refreshCalls), "got", String(all.length), "entries");
+    setEntries(all);
+  }
+
+  void refresh();
+
+  // BroadcastChannel: cross-tab invalidation
+  const bc = new BroadcastChannel(`${DB_NAME}-changes`);
+  bc.onmessage = (e: MessageEvent) => {
+    if (e.data?.type === "mutation" && e.data.store === DOC_INDEX_STORE) {
+      log.debug("docindex", "broadcast invalidation received");
+      void refresh();
+    }
+  };
+
+  // CustomEvent: same-page invalidation - works on file:// (null origin)
+  // where BroadcastChannel may not deliver same-page messages reliably.
+  const onDocIndexChanged = () => { void refresh(); };
+  window.addEventListener(DOC_INDEX_CHANGE_EVENT, onDocIndexChanged);
+
+  onCleanup(() => {
+    bc.close();
+    window.removeEventListener(DOC_INDEX_CHANGE_EVENT, onDocIndexChanged);
+  });
+
+  return entries;
+}

package/src/hooks/createDocStore.test.ts

@@ -0,0 +1,303 @@
+// tests for createDocStore solid adapter.
+//
+// uses a lightweight mock DocHandle (no automerge wasm needed) to test
+// the solid reactivity layer and zod facade independently.
+
+import { describe, it, expect, vi } from "vitest";
+import { createRoot } from "solid-js";
+import type {
+  DocHandleChangePayload,
+  DocHandleDeletePayload,
+} from "@automerge/automerge-repo";
+import { createDocStore, changeDoc } from "./createDocStore.js";
+import type { DocHandle } from "@automerge/automerge-repo";
+import type { PlaylistDoc } from "@freqhole/api-client/playlistz";
+
+// --- minimal mock DocHandle ---
+
+type EventName = "change" | "delete";
+type HandlerFn = (payload: unknown) => void;
+
+function createMockHandle(initialDoc: unknown = undefined): {
+  handle: DocHandle<unknown>;
+  setDoc: (doc: unknown) => void;
+  emitChange: (doc: unknown) => void;
+  emitDelete: () => void;
+  resolveReady: () => void;
+  rejectReady: (err: unknown) => void;
+  offSpy: ReturnType<typeof vi.fn>;
+} {
+  let currentDoc = initialDoc;
+  const handlers = new Map<EventName, Set<HandlerFn>>();
+  let readyResolve: () => void;
+  let readyReject: (err: unknown) => void;
+
+  const readyPromise = new Promise<void>((res, rej) => {
+    readyResolve = res;
+    readyReject = rej;
+  });
+
+  const offSpy = vi.fn();
+
+  const handle = {
+    doc: () => currentDoc,
+    whenReady: () => readyPromise,
+    on: (event: EventName, handler: HandlerFn) => {
+      if (!handlers.has(event)) handlers.set(event, new Set());
+      handlers.get(event)!.add(handler);
+    },
+    off: offSpy,
+    change: vi.fn((fn: (d: unknown) => void) => {
+      fn(currentDoc);
+      const set = handlers.get("change");
+      if (set) {
+        const payload: DocHandleChangePayload<unknown> = {
+          handle: handle as unknown as DocHandle<unknown>,
+          doc: currentDoc as ReturnType<typeof handle.doc>,
+          patches: [],
+          patchInfo: {
+            before: currentDoc as ReturnType<typeof handle.doc>,
+            after: currentDoc as ReturnType<typeof handle.doc>,
+            source: "change",
+          },
+        };
+        set.forEach((h) => h(payload));
+      }
+    }),
+  } as unknown as DocHandle<unknown>;
+
+  return {
+    handle,
+    setDoc: (d: unknown) => {
+      currentDoc = d;
+    },
+    emitChange: (doc: unknown) => {
+      currentDoc = doc;
+      const set = handlers.get("change");
+      if (set) {
+        const payload: DocHandleChangePayload<unknown> = {
+          handle: handle as unknown as DocHandle<unknown>,
+          doc: doc as ReturnType<typeof handle.doc>,
+          patches: [],
+          patchInfo: {
+            before: doc as ReturnType<typeof handle.doc>,
+            after: doc as ReturnType<typeof handle.doc>,
+            source: "change",
+          },
+        };
+        set.forEach((h) => h(payload));
+      }
+    },
+    emitDelete: () => {
+      const set = handlers.get("delete");
+      if (set) {
+        const payload: DocHandleDeletePayload<unknown> = {
+          handle: handle as unknown as DocHandle<unknown>,
+        };
+        set.forEach((h) => h(payload));
+      }
+    },
+    resolveReady: () => readyResolve(),
+    rejectReady: (err: unknown) => readyReject(err),
+    offSpy,
+  };
+}
+
+describe("createDocStore", () => {
+  it("returns loading=true and default doc when handle doc is undefined", () => {
+    createRoot((dispose) => {
+      const { handle } = createMockHandle(undefined);
+      const { doc, loading } = createDocStore(handle);
+
+      expect(loading()).toBe(true);
+      // zod defaults produce version 1 empty doc
+      expect(doc().version).toBe(1);
+      expect(doc().title).toBe("");
+
+      dispose();
+    });
+  });
+
+  it("returns loading=false immediately when handle already has a doc", () => {
+    createRoot((dispose) => {
+      const initialDoc = {
+        version: 1,
+        title: "loaded",
+        description: "",
+        createdAt: new Date().toISOString(),
+        lastModified: new Date().toISOString(),
+        lastModifiedBy: "",
+        images: [],
+        urls: [],
+        songs: {},
+        order: [],
+        peers: {},
+      };
+      const { handle } = createMockHandle(initialDoc);
+      const { doc, loading } = createDocStore(handle);
+
+      expect(loading()).toBe(false);
+      expect(doc().title).toBe("loaded");
+
+      dispose();
+    });
+  });
+
+  it("updates doc signal on handle change event", () => {
+    createRoot((dispose) => {
+      const { handle, emitChange } = createMockHandle({
+        version: 1,
+        title: "original",
+        description: "",
+        createdAt: new Date().toISOString(),
+        lastModified: new Date().toISOString(),
+        lastModifiedBy: "",
+        images: [],
+        urls: [],
+        songs: {},
+        order: [],
+        peers: {},
+      });
+      const { doc } = createDocStore(handle);
+
+      expect(doc().title).toBe("original");
+
+      emitChange({
+        version: 1,
+        title: "updated",
+        description: "",
+        createdAt: new Date().toISOString(),
+        lastModified: new Date().toISOString(),
+        lastModifiedBy: "",
+        images: [],
+        urls: [],
+        songs: {},
+        order: [],
+        peers: {},
+      });
+
+      expect(doc().title).toBe("updated");
+
+      dispose();
+    });
+  });
+
+  it("degrades corrupt doc to zod defaults on change", () => {
+    createRoot((dispose) => {
+      const { handle, emitChange } = createMockHandle({ version: 1 });
+      const { doc } = createDocStore(handle);
+
+      // emit a corrupt doc that fails zod validation
+      emitChange({ version: 999, badField: true });
+
+      // zod degrades to defaults
+      expect(doc().version).toBe(1);
+      expect(doc().title).toBe("");
+
+      dispose();
+    });
+  });
+
+  it("sets loading=false when delete event fires", () => {
+    createRoot((dispose) => {
+      const { handle, emitDelete } = createMockHandle(undefined);
+      const { loading } = createDocStore(handle);
+
+      expect(loading()).toBe(true);
+      emitDelete();
+      expect(loading()).toBe(false);
+
+      dispose();
+    });
+  });
+
+  it("sets loading=false when whenReady resolves", async () => {
+    await createRoot(async (dispose) => {
+      const { handle, resolveReady, setDoc } = createMockHandle(undefined);
+      const { loading } = createDocStore(handle);
+
+      expect(loading()).toBe(true);
+
+      setDoc({
+        version: 1,
+        title: "",
+        description: "",
+        createdAt: new Date().toISOString(),
+        lastModified: new Date().toISOString(),
+        lastModifiedBy: "",
+        images: [],
+        urls: [],
+        songs: {},
+        order: [],
+        peers: {},
+      });
+      resolveReady();
+
+      // flush microtasks
+      await Promise.resolve();
+      await Promise.resolve();
+
+      expect(loading()).toBe(false);
+
+      dispose();
+    });
+  });
+
+  it("sets loading=false when whenReady rejects", async () => {
+    await createRoot(async (dispose) => {
+      const { handle, rejectReady } = createMockHandle(undefined);
+      const { loading } = createDocStore(handle);
+
+      rejectReady(new Error("unavailable"));
+
+      await Promise.resolve();
+      await Promise.resolve();
+
+      expect(loading()).toBe(false);
+
+      dispose();
+    });
+  });
+
+  it("unsubscribes handlers on cleanup (off called with correct args)", () => {
+    const { handle, offSpy } = createMockHandle({ version: 1 });
+
+    const dispose = createRoot((disposeRoot) => {
+      createDocStore(handle);
+      return disposeRoot;
+    });
+
+    dispose();
+
+    // off should have been called for both "change" and "delete"
+    expect(offSpy).toHaveBeenCalledWith("change", expect.any(Function));
+    expect(offSpy).toHaveBeenCalledWith("delete", expect.any(Function));
+  });
+
+  it("degrades null/undefined doc to zod defaults", () => {
+    createRoot((dispose) => {
+      const { handle, emitChange } = createMockHandle({ version: 1 });
+      const { doc } = createDocStore(handle);
+
+      emitChange(null);
+      expect(doc().version).toBe(1);
+      expect(doc().title).toBe("");
+
+      dispose();
+    });
+  });
+});
+
+describe("changeDoc", () => {
+  it("calls handle.change with the mutator function", () => {
+    const mockChange = vi.fn();
+    const handle = {
+      change: mockChange,
+    } as unknown as DocHandle<PlaylistDoc>;
+
+    const mutator = vi.fn();
+    changeDoc(handle, mutator);
+
+    expect(mockChange).toHaveBeenCalledWith(mutator);
+  });
+});

package/src/hooks/createDocStore.ts

@@ -0,0 +1,90 @@
+// solid adapter over an automerge DocHandle for PlaylistDoc.
+//
+// usage inside a solid component or reactive root:
+//
+//   const handle = await findPlaylistDoc(url);
+//   const { doc, loading } = createDocStore(handle);
+//   // doc() is always a zod-parsed PlaylistDoc (defaults on corrupt/missing)
+//   // loading() is true until the handle is ready or terminal
+
+import { createSignal, onCleanup } from "solid-js";
+import type { Accessor } from "solid-js";
+import type {
+  DocHandle,
+  DocHandleChangePayload,
+  DocHandleDeletePayload,
+} from "@automerge/automerge-repo";
+import {
+  parsePlaylistDoc,
+  type PlaylistDoc,
+} from "@freqhole/api-client/playlistz";
+
+export interface DocStore {
+  doc: Accessor<PlaylistDoc>;
+  loading: Accessor<boolean>;
+}
+
+// create a reactive solid store backed by an automerge DocHandle.
+// the doc accessor is always a zod-validated PlaylistDoc snapshot -
+// corrupt or future-versioned peer data degrades to defaults.
+// loading becomes false once whenReady() resolves or rejects.
+export function createDocStore(handle: DocHandle<unknown>): DocStore {
+  // try to read whatever the handle has now (may be undefined before ready)
+  let initialRaw: unknown;
+  try {
+    initialRaw = handle.doc();
+  } catch {
+    initialRaw = undefined;
+  }
+
+  const [loading, setLoading] = createSignal(initialRaw === undefined);
+  const [doc, setDoc] = createSignal<PlaylistDoc>(
+    parsePlaylistDoc(initialRaw),
+    { equals: false }
+  );
+
+  // resolve handle readiness in the background
+  handle
+    .whenReady()
+    .then(() => {
+      let current: unknown;
+      try {
+        current = handle.doc();
+      } catch {
+        current = undefined;
+      }
+      setLoading(false);
+      setDoc(parsePlaylistDoc(current));
+    })
+    .catch(() => {
+      setLoading(false);
+    });
+
+  const changeHandler = (payload: DocHandleChangePayload<unknown>) => {
+    setDoc(parsePlaylistDoc(payload.doc));
+  };
+
+  const deleteHandler = (_payload: DocHandleDeletePayload<unknown>) => {
+    setLoading(false);
+  };
+
+  handle.on("change", changeHandler);
+  handle.on("delete", deleteHandler);
+
+  onCleanup(() => {
+    handle.off("change", changeHandler);
+    handle.off("delete", deleteHandler);
+  });
+
+  return { doc, loading };
+}
+
+// convenience wrapper: apply a mutation to a playlist doc handle.
+// the mutatorFn receives a mutable automerge draft and should modify it
+// in place (safe to call the shared mutation helpers from freqhole-api-client).
+export function changeDoc(
+  handle: DocHandle<PlaylistDoc>,
+  mutatorFn: (draft: PlaylistDoc) => void
+): void {
+  handle.change(mutatorFn);
+}