@freqhole/playlistz 0.0.1

package/dist/sw.js

@@ -0,0 +1,134 @@
+// playlistz service worker
+//
+// caches the app shell files (freqhole-playlistz.js, playlistz.js, index.html, sw.js).
+// audio and image files in data/ are NOT pre-cached; the app ui handles that separately.
+//
+// bumping CACHE_VERSION forces all clients to receive fresh app files on next load.
+const CACHE_VERSION = "v2";
+const CACHE_NAME = `playlistz-${CACHE_VERSION}`;
+
+// app shell files to cache on install
+const APP_SHELL = [
+  "freqhole-playlistz.js",
+  "playlistz.js",
+  "index.html",
+  "sw.js",
+];
+
+// install: cache app shell and skip waiting so this sw activates immediately
+self.addEventListener("install", (event) => {
+  event.waitUntil(
+    caches.open(CACHE_NAME).then((cache) =>
+      cache.addAll(APP_SHELL).catch((err) => {
+        // some files may not exist (e.g. playlistz.js before first generate run)
+        console.warn("playlistz sw: pre-cache partial failure:", err);
+      }),
+    ).then(() => self.skipWaiting()),
+  );
+});
+
+// activate: delete old caches, claim all clients immediately
+self.addEventListener("activate", (event) => {
+  event.waitUntil(
+    caches.keys()
+      .then((names) =>
+        Promise.all(
+          names
+            .filter((n) => n.startsWith("playlistz-") && n !== CACHE_NAME)
+            .map((n) => caches.delete(n)),
+        ),
+      )
+      .then(() => self.clients.claim()),
+  );
+});
+
+// fetch: cache-first for app shell files, network-pass-through for everything else
+self.addEventListener("fetch", (event) => {
+  const url = new URL(event.request.url);
+  const filename = url.pathname.split("/").pop() ?? "";
+  const isAppShell = APP_SHELL.includes(filename) || url.pathname === "/" || url.pathname === "";
+
+  if (!isAppShell) {
+    return; // let browser handle data/ assets (audio, images)
+  }
+
+  event.respondWith(
+    caches.match(event.request).then((cached) => {
+      if (cached) return cached;
+      return fetch(event.request).then((response) => {
+        if (response.ok) {
+          caches.open(CACHE_NAME).then((cache) => cache.put(event.request, response.clone()));
+        }
+        return response;
+      });
+    }).catch(() => caches.match("index.html")),
+  );
+});
+
+// message: handle reset/clear from the page via window.__playlistzReset()
+self.addEventListener("message", (event) => {
+  if (event.data?.type === "PLAYLISTZ_RESET") {
+    event.waitUntil(
+      caches.keys()
+        .then((names) => Promise.all(names.map((n) => caches.delete(n))))
+        .then(() => self.clients.matchAll())
+        .then((clients) => clients.forEach((c) => c.postMessage({ type: "PLAYLISTZ_RESET_DONE" }))),
+    );
+  }
+});
+
+
+self.addEventListener("install", (event) => {
+  console.log("playlistz service worker: installing...");
+  event.waitUntil(
+    caches
+      .open(CACHE_NAME)
+      .then((cache) => {
+        console.log("playlistz service worker: caching app shell");
+        return cache.addAll(urlsToCache);
+      })
+      .catch((error) => {
+        console.error(
+          "playlistz service worker: failed to cache app shell:",
+          error
+        );
+      })
+  );
+});
+
+self.addEventListener("fetch", (event) => {
+  event.respondWith(
+    caches
+      .match(event.request)
+      .then((response) => {
+        // return cached version or fetch from network
+        if (response) {
+          return response;
+        }
+        return fetch(event.request);
+      })
+      .catch((error) => {
+        console.error("playlistz service worker: fetch failed:", error);
+        throw error;
+      })
+  );
+});
+
+self.addEventListener("activate", (event) => {
+  console.log("playlistz service worker: activating...");
+  event.waitUntil(
+    caches.keys().then((cacheNames) => {
+      return Promise.all(
+        cacheNames.map((cacheName) => {
+          if (cacheName !== CACHE_NAME) {
+            console.log(
+              "playlistz service worker: deleting old cache:",
+              cacheName
+            );
+            return caches.delete(cacheName);
+          }
+        })
+      );
+    })
+  );
+});

package/docs/AUTOMERGE_P2P_PLAN.md

@@ -0,0 +1,233 @@
+# automerge p2p plan: playlist docs over iroh
+
+each playlist becomes an automerge document, synced peer-to-peer over iroh using skein's proven stack (automerge-repo + a midden BiStream network adapter). this supersedes the sync-protocol portions of [IROH_P2P_PLAN.md](IROH_P2P_PLAN.md): instead of hand-rolling a freqhole-playlistz request/response protocol for playlist data and mirroring spume's indexeddb stores, playlist state is a CRDT that merges automatically between any number of peers. several sections of the old plan carry over unchanged and are referenced below rather than duplicated.
+
+## why automerge docs
+
+- multi-node playlist sync (the hard part of the old plan: diffing, conflict handling, partial updates, re-sync after offline) is automerge-repo's entire job.
+- clean separation of concerns with spume: playlistz does not adopt spume's `freqhole_music` idb schema. instead, a central set of schemas in `freqhole-api-client` defines the playlist doc shape, and small converter utils map spume/freqhole records -> playlist docs (and back). interop is at the schema level, not the storage level.
+- freqhole interop still works through the `freqhole-playlistz/1` ALPN: a freqhole node answers a small JSON protocol (list playlists, knock), and the actual playlist payloads convert into local automerge docs on the playlistz side.
+- skein has already validated the whole stack in production: automerge-repo v2 over iroh QUIC via wasm, CBOR framing, reconnect/backoff, share strings, even a headless hub peer (reliquary) for always-on availability.
+
+## reference map
+
+### skein/ (the stack we adopt)
+
+| what                                                                                                                                                                                      | where                                                                   |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| midden wasm node (iroh 0.97, BiStream, accept loop, iroh-blobs, `create_with_alpns`)                                                                                                      | `skein/midden/src/lib.rs`                                               |
+| automerge ALPN constant `iroh/automerge-repo/1`                                                                                                                                           | `skein/midden/src/lib.rs`, `skein/loam/src/p2p/iroh-network-adapter.ts` |
+| `IrohNetworkAdapter` (automerge-repo NetworkAdapter over BiStream: CBOR-encoded `Message`s, 4-byte BE length frames, reconnect backoff, alpn handler registry, connection summary for UI) | `skein/loam/src/p2p/iroh-network-adapter.ts`                            |
+| identity persistence (`p2p_identity` record `{ secret_key, node_id, created_at }` in a small kv idb, lazy midden start)                                                                   | `skein/loam/src/p2p/identity.ts`, `skein/loam/src/storage/meta-db.ts`   |
+| repo wiring (`new Repo({ storage: IndexedDBStorageAdapter, network: [BroadcastChannelNetworkAdapter, irohAdapter] })`)                                                                    | `skein/loam/src/standalone/boot.ts`                                     |
+| share strings (`base64({ n: nodeId, d: docId })`, url fragment `#share/<b64>`)                                                                                                            | `skein/loam/src/p2p/share-string.ts`                                    |
+| doc facade pattern (zod-validated reads over a DocHandle, `change()` + `on("change")`)                                                                                                    | `skein/loam/src/widgets/widget-doc.ts`                                  |
+| blob worker (blake3/sha256 hashing + opfs writes off the main thread)                                                                                                                     | `skein/loam/src/workers/blob-worker.ts`                                 |
+| reliquary headless hub peer (rust, sqlite-persisted automerge docs, serves sync + blobs while browsers are offline)                                                                       | `skein/reliquary/`                                                      |
+
+### carried over from IROH_P2P_PLAN.md (still authoritative there)
+
+- guiding principle: one shared storage/p2p layer in `freqhole-api-client`.
+- midden packaging: vite wasm plugins, single-file standalone attempt (`build-web` target, base64-inline wasm).
+- identity interop with spume: read-only `freqhole_app` access rules, fallback to local settings store.
+- single live node per origin: web locks leader election + share panel lock status.
+- image/audio blob bytes: shared opfs blob store (`/blobs/{sha256}`, `freqhole_blobs` metadata db, Cache API fallback) extracted from spume into `freqhole-api-client/storage`.
+- blob transfer: iroh-blobs verified streaming (`download_verified_streaming`, `import_blob`/`release_blob` via `WasmTransport`).
+- knock concept and share panel UX (adapted below to the doc model).
+
+## architecture decisions
+
+### packages
+
+- new deps: `@automerge/automerge`, `@automerge/automerge-repo`, `@automerge/automerge-repo-storage-indexeddb`, `@automerge/automerge-repo-network-broadcastchannel` (skein uses `^3.2.5` / `^2.5.5`; match those).
+- midden: use tomb's midden (`file:../tomb/client/midden/pkg`), NOT skein's. automerge sync needs no rust-side support - the adapter drives everything in JS over generic BiStreams - so the only requirement is registering the ALPN string: `create_with_alpns(key, ["iroh/automerge-repo/1", "freqhole-playlistz/1"])`. tomb's midden already has BiStream/open_bi/accept with identical framing (both middens descend from the same code).
+- `freqhole-api-client` gains a `schemas` (or extends `storage`) subpath: zod schema for the playlist doc, `ImageRef`/`EntityUrl`/`BlobKind`, and converter utils (`spumePlaylistToDoc`, `freqholePlaylistToDoc`, `docToFreqholePlaylist`...). this is the single source of truth both apps and future converters share.
+- the `IrohNetworkAdapter` is ported from skein into `freqhole-api-client` (parameterized over the identity getter instead of importing skein's identity module) so spume can later adopt the same adapter. skein keeps its own copy for now; convergence is a "later" item coordinated across repos.
+
+### shared package layout (freqhole-api-client)
+
+goal: enough playlistz domain logic lives in `freqhole-api-client` + midden that any tomb client (spume, charnel) or skein can "talk playlistz" by importing these subpaths. playlistz itself keeps only solid reactivity, repo wiring, and UI.
+
+```
+tomb/client-codegen/freqhole-api-client/
+  package.json                 # subpath exports added (raw TS, no build step)
+  src/
+    storage/                   # shared browser storage layer
+      blobs.ts                 # extracted verbatim from spume src/music/services/storage/blobs.ts
+      identity.ts              # p2p_identity resolution (read-only freqhole_app + local fallback)
+      webLocks.ts              # "freqhole-iroh-node" leader election helper
+      index.ts
+    playlistz/                 # the "talk playlistz" domain package
+      schema.ts                # PlaylistDoc/SongEntry/ImageRef/EntityUrl/BlobKind zod schemas + parseDoc helper
+      mutations.ts             # pure (doc, args) => void helpers usable inside handle.change:
+                               #   upsertSong, removeSong, reorderSongs, setPrimaryImage, addImage,
+                               #   setMetadata, addPeer, stampLastSeen, setAclRole, tombstone
+      convert.ts               # spumePlaylistToDoc, freqholePlaylistToDoc, docToFreqholePlaylist
+      shareLink.ts             # encode/decode base64url { v, n, d, t? } + #share/ fragment helpers
+      protocol.ts              # freqhole-playlistz/1 zod message schemas (hello, list_playlists,
+                               #   knock, knock_status, error) + BiStream encode/decode helpers
+      index.ts
+    automerge/                 # transport-level automerge-over-iroh
+      IrohNetworkAdapter.ts    # ported from skein loam, identity getter + ALPN injected via constructor
+      index.ts
+```
+
+- `package.json` exports map: `"."` (unchanged), `"./storage"`, `"./playlistz"`, `"./automerge"` -> the respective `src/*/index.ts`.
+- dependency policy: `@automerge/automerge-repo` becomes a **peerDependency** (consuming apps own the version; the adapter only imports `NetworkAdapter`, `cbor`, and types). `zod` stays a regular dep. `storage/` and `playlistz/` must not import automerge - mutation helpers are plain functions over plain objects, which is what keeps them shareable.
+- `src/codegen/` stays codegen-owned (never hand-edit `schema.ts`/`routes.ts`); the new subdirs are hand-written and import from codegen types where useful.
+- existing tests run via `npm test` (`tsx src/test.ts`, custom runner under `src/test/`); new modules follow that convention.
+
+### document model
+
+one automerge doc per playlist. the doc id (automerge document id) is the playlist's global identity.
+
+```ts
+interface PlaylistDoc {
+  version: 1;
+  title: string;
+  description: string;
+  createdAt: string; // ISO
+  lastModified: string; // ISO
+  lastModifiedBy: string; // node id
+  images: ImageRef[]; // { blobId: sha256, isPrimary, blobType }
+  urls: EntityUrl[];
+  songs: Record<string, SongEntry>; // keyed by song id
+  order: string[]; // song ids, automerge list (move-friendly)
+  peers: Record<
+    string,
+    { nodeId: string; joinedAt: string; lastSeenAt?: string }
+  >;
+  acl?: Record<string, { role: "owner" | "editor" | "viewer" }>;
+  deleted?: boolean; // tombstone
+}
+
+interface SongEntry {
+  id: string;
+  title: string;
+  artist: string;
+  album: string;
+  duration: number;
+  mimeType: string;
+  fileSize: number;
+  sha256: string; // content identity, blob store key
+  blake3?: string; // iroh-blobs transfer hash
+  images: ImageRef[];
+  urls: EntityUrl[];
+  lyrics?: string;
+}
+```
+
+- binary payloads (audio, images, waveforms) are NOT in the doc - docs carry hashes; bytes live in the shared opfs blob store and transfer via iroh-blobs. this is exactly skein's file-widget pattern.
+- field shapes match the freqhole wire schemas (camelCase here, converters handle `is_primary` 0/1 etc.) so spume idb -> playlist doc is a flat mapping.
+- doc reads go through a zod-validated facade (skein's `createWidgetDoc` pattern): corrupt or future-versioned peer data degrades to defaults instead of crashing.
+
+### local storage layout
+
+- NO MIGRATION: playlistz has no deployed users, so the idb schema is greenfield - no upgrade paths from the v6 layout, no legacy-record converters, no dual-path fallbacks. the old `playlists`/`songs` stores are simply gone.
+- automerge-repo persists doc storage via `IndexedDBStorageAdapter` in a db named `freqhole-automerge` (explicit name so a future spume adoption shares the same repo storage on a shared domain).
+- `musicPlaylistDB` restarts at version 1 with only non-shared state: `playbackPositions`, `lastPlayed`, `settings`, `knocks`, `accessGrants`, plus a `docIndex` store mapping automerge doc id -> `{ title, addedAt, source: "local" | "shared" | "freqhole" }` for the sidebar listing without loading every doc.
+- all binary bytes (audio, images, waveforms) go straight to the shared opfs blob store keyed by sha256 - no inline `audioData`/`imageData` anywhere. one accessor: sha256 -> blob store -> object url.
+
+### reactivity
+
+the live-query system (`createPlaylistsQuery`/`createPlaylistSongsQuery` + BroadcastChannel) is replaced for playlist/song state by a thin solid adapter over doc handles:
+
+- `createDocStore(handle)`: solid signal updated from `handle.on("change")`, zod-parsed. cross-tab updates arrive via `BroadcastChannelNetworkAdapter` (automerge-repo syncs between tabs natively - this replaces the manual BroadcastChannel invalidation, and the whitelist-stripping bug class disappears entirely).
+- sidebar lists from the `docIndex` store (small, still a live query); opening a playlist materializes its doc store.
+- mutations become `handle.change(doc => ...)` calls inside the existing manager hooks; component props/interfaces stay the same so UI churn is contained to the data layer.
+
+### network + sharing
+
+- repo network: `[BroadcastChannelNetworkAdapter, IrohNetworkAdapter]`. the iroh adapter lazily starts midden only when an identity exists (skein's deferred-start pattern), gated by the web locks leader election from the old plan.
+- share links: skein's format, playlistz-flavored: `base64url({ v: 1, n: nodeId, d: docId, t?: title })`, url fragment `#share/<b64>`. opening one: `repo.find(docId)` + `irohAdapter.addPeer(nodeId)`; automerge-repo syncs the doc from the peer, write `docIndex` entry, done. no import step, and edits flow both ways thereafter.
+- access model: the doc id is an unguessable bearer capability (same trust model as spume's share tokens). repo `sharePolicy` controls proactive announcement: only announce docs to peers recorded in that doc's `peers`/acl. revocation = acl edit + tombstone awareness in UI (true cryptographic revocation is out of scope, as it is in skein).
+- knock flow (for "browse this node's playlists" rather than a direct doc link): small JSON protocol on `freqhole-playlistz/1` - `hello`, `list_playlists` (returns doc ids + titles for public docs, or knock-gated), `knock`, `knock_status`. accepted knocks grant doc ids; sync then happens over the automerge ALPN. knock records + grants in `musicPlaylistDB` (knocks/accessGrants stores from the old plan, unchanged).
+- per-playlist ephemeral presence (who's listening, now-playing) is possible later via `handle.broadcast` - designed for, not built now.
+
+### freqhole interop
+
+- tomb side: grimoire/freqhole server answers `freqhole-playlistz/1` (list/knock as above) and serves blobs via iroh-blobs - same tomb-side work items as the old plan.
+- importing a freqhole playlist: fetch its records over the protocol, run `freqholePlaylistToDoc` from the shared schemas package, create a local automerge doc. the freqhole node does not speak automerge; it is a data source, and the doc becomes the live local copy.
+- spume convergence: if/when spume wants doc-backed playlists, it reuses the schemas + adapter from `freqhole-api-client` and `spumePlaylistToDoc`. until then, nothing in tomb references playlistz.
+
+## implementation phases
+
+note: the 26 pre-existing freqhole-api-client test failures (route/client coverage mismatches) have been fixed - `npm test` is fully green there (413 passed, 0 failed).
+
+### phase 1: shared schemas + converters (tomb)
+
+- [x] `freqhole-api-client`: `PlaylistDoc`/`SongEntry`/`ImageRef`/`EntityUrl` zod schemas
+- [x] converter utils: `spumePlaylistToDoc`, `freqholePlaylistToDoc` (+ inverse where lossless)
+- [x] blob store extraction from spume (`storage/blobs.ts` verbatim) into `freqhole-api-client/storage`; spume re-exports
+- [x] unit tests (schema round-trips, converter fixtures)
+
+### phase 2: midden packaging + identity (playlistz + tomb)
+
+- [x] midden dep + vite wasm plugins; single-file standalone attempt (per old plan phase 2)
+- [x] identity resolution + web locks helper in `freqhole-api-client/storage` (per old plan phase 3, unchanged)
+- [x] tomb midden: `create_with_alpns` accepts arbitrary extras (verified - generic string array, no rust change needed); `PLAYLISTZ_ALPN` registered at runtime by playlistz `p2pService` via `create_with_alpns(key, [AUTOMERGE_ALPN, PLAYLISTZ_ALPN])`
+- [ ] smoke test: node boots, automerge + playlistz ALPNs registered
+
+### phase 3: repo + doc layer (playlistz)
+
+- [x] port `IrohNetworkAdapter` into `freqhole-api-client` (identity getter parameterized); adapter unit tests with mocked midden + `navigator.locks`
+- [x] repo singleton: `IndexedDBStorageAdapter("freqhole-automerge")` + broadcast + iroh adapters, leader-gated midden start (`src/services/automergeRepo.ts`, `src/services/p2pService.ts`)
+- [x] `createDocStore` solid adapter with zod facade (`src/hooks/createDocStore.ts`, plus `createDocIndexQuery` + `docIndexService`)
+- [x] fresh `musicPlaylistDB` v1 schema: `docIndex`, knocks, accessGrants, playbackPositions, lastPlayed, settings (no migration code - old stores dropped)
+
+status: green. playlistz typecheck clean, 514 tests passing; freqhole-api-client 413 passing; spume 42 passing. note: `parsePlaylistDoc` plainifies raw docs before zod parsing - automerge proxies carry symbol keys (`_am_objectId`, `_am_datatype_`) that zod records reject.
+
+### phase 4: UI on docs (playlistz)
+
+- [x] sidebar from `docIndex`; playlist view from doc store
+- [x] mutations through `handle.change` in `usePlaylistManager`/`useSongState` (interfaces unchanged)
+- [x] export/import + standalone zip updated to serialize from docs
+- [x] full test suite green on the doc-backed data layer
+
+status: green (playlistz 470 tests, typecheck clean). notes:
+
+- `src/services/playlistDocService.ts` is the doc-backed CRUD layer; the old playlist/song idb CRUD is gone and `musicPlaylistDB` is at v1 with only local-state stores.
+- view-shape adapters (`docToPlaylist`, `songEntryToSong`) keep the component-facing `Playlist`/`Song` types stable; image/audio bytes resolve on demand from the blob store by sha256.
+- display filter settings (`bgFilter*`, `coverFilter*`) moved into the shared `PlaylistDoc` schema + `setMetadata` so they sync with the playlist.
+- standalone idempotency: settings record `standalone:<playlistId>` -> `{ rev, docId }`; rev bump updates the existing doc instead of duplicating.
+
+### phase 5: p2p sharing (playlistz)
+
+- [x] share panel: endpoint setup (name, public/knock), node id, lock status, connection summary, knock inbox (`src/components/SharePanel.tsx`, opened from the sidebar header)
+- [x] open-share-link flow (`#share/` fragment + paste panel): find doc, add peer, index it (`sharingService.openShareLink` / `handleShareFragment`)
+- [x] sharePolicy + peers recorded in doc on join; `reconnectKnownPeers` on leadership (skein's `registerAndReconnectPeers` pattern)
+- [x] knock protocol on `freqhole-playlistz/1` (responder + requester) with knock inbox UI; grants can be scoped to specific docIds
+
+status: green. `src/services/sharingService.ts` owns the whole phase 5 surface (settings, links, knock, responder loop). per-playlist "copy p2p share link" button in the playlist header. p2p resumes on boot only when an identity already exists (`resumeSharingIfEnabled`); first start stays a user action in the share panel. avatar upload UI deferred (`ShareSettings.avatarSha` is plumbed).
+
+### phase 6: blob transfer (playlistz)
+
+- [x] audio/image fetch via iroh-blobs into the shared blob store with progress (`blobTransferService.fetchBlobForDoc`; audioService falls back to p2p fetch when a doc-backed song's blob is missing locally)
+- [x] serving: import-on-demand of local blobs (`import_blob`, released after 10 min idle); ~30 min playback prefetch after each play (`prefetchUpcoming`); "save offline" button fetches all missing blobs for a playlist (`savePlaylistOffline`)
+
+status: green. blob handshake rides the playlistz ALPN (`blob_request` -> `blob_ready { blake3, size }`), then `download_verified_streaming` over the iroh-blobs ALPN (handled rust-side in midden's accept loop). chunk callbacks copy via `chunk.slice()` since wasm buffers may be reused. unit tests: `sharingService.test.ts` (27) + `blobTransferService.test.ts` (16); e2e: `e2e/sharing.spec.ts` (4 + a two-context real-relay p2p test, skippable via `PLAYLISTZ_E2E_SKIP_P2P=1`).
+
+### phase 7: freqhole side (tomb)
+
+- [ ] grimoire `freqhole-playlistz/1` responder (list/knock) + blob serving by blake3
+- [ ] playlistz import flow: protocol fetch -> `freqholePlaylistToDoc` -> local doc (maybe defer this part)
+
+## later (deliberately deferred, designed for)
+
+- ephemeral presence per playlist (`handle.broadcast`): listening-along indicators, live cursors over the song list.
+- reliquary-style headless hub for playlistz (or reuse of reliquary itself): always-on doc + blob availability when browsers are closed.
+- spume adopting doc-backed playlists via the shared schemas/adapter.
+- skein/loam converging on the `freqhole-api-client` copy of `IrohNetworkAdapter`.
+- waveform/lyrics/urls editing UI on top of the doc fields.
+
+## subagent dispatch notes
+
+implementation work is dispatched to subagents per module. shared constraints for every dispatch:
+
+- lowercase prose in comments/errors/logs; no emojis; no em dashes; npm.
+- tomb work: freqhole-api-client is raw TS consumed directly - typecheck with `npm run typecheck`, test via `npm test` (tsx runner). spume changes must keep `npm test` green in `tomb/client/spume`.
+- playlistz work: vitest via `npm test` (455+ passing, keep green); idb wrapper from `idb` package; fake-indexeddb in tests; coverage thresholds 70%.
+- source references: skein adapter at `skein/loam/src/p2p/iroh-network-adapter.ts`, share strings at `skein/loam/src/p2p/share-string.ts`, doc facade at `skein/loam/src/widgets/widget-doc.ts`, spume blob store at `tomb/client/spume/src/music/services/storage/blobs.ts`, identity record shape `{ id: "p2p_identity", secret_key: Uint8Array(32), node_id, created_at }`.
+- playlistz idb is greenfield: no deployed users, no migration code, schema changes are free. current types in `playlistz/src/types/playlist.ts` are reference only - the doc schema in `freqhole-api-client/playlistz` is now the source of truth.
+- parallelizable units (disjoint files): storage extraction vs playlistz domain package vs adapter port. anything touching `freqhole-api-client/package.json` is done by the orchestrator first to avoid conflicts.
+- each dispatch must state: exact files to create/modify, what NOT to touch (codegen dirs, unrelated services), test expectations, and the style constraints above.

package/docs/COLLABORATIVE_SHARING_PLAN.md

@@ -0,0 +1,188 @@
+# collaborative sharing plan
+
+tracks design + implementation for per-playlist sharing modes, read-only subscribed mode, knock-with-message flow, collaborator access, and the fork/unsubscribe pattern.
+
+---
+
+## status
+
+| area                                       | status |
+| ------------------------------------------ | ------ |
+| data model: per-playlist sharing fields    | [ ]    |
+| playlist read-only subscribed mode (ui)    | [ ]    |
+| knock-with-message on search bar hit       | [ ]    |
+| fork / unsubscribe from remote doc         | [ ]    |
+| collaborator knock request + accept        | [ ]    |
+| automerge sync policy (read-only vs rw)    | [ ]    |
+| per-playlist sharing mode ui (share panel) | [ ]    |
+| conflict resolution ui                     | [ ]    |
+
+---
+
+## data model
+
+### playlist doc schema additions
+
+```ts
+// additions to the automerge playlist doc
+interface PlaylistDoc {
+  // existing fields...
+
+  // sharing mode for this playlist. unset = not shared (private).
+  sharingMode?: "public" | "knock";
+
+  // node ids with write permission (collaborators).
+  // owner's node id is always implicitly a collaborator.
+  collaborators?: Record<string, true>;
+
+  // read-only subscribers: node ids allowed to receive updates but not push changes.
+  subscribers?: Record<string, true>;
+
+  // source info: set when this doc was received from a remote peer.
+  // null = owned by this user.
+  remoteSource?: {
+    nodeId: string; // peer who shared it
+    displayName?: string; // their display name at time of sync
+    addedAt: number; // timestamp when local copy was added
+    forked: boolean; // true once the user has forked to a local copy
+  };
+}
+```
+
+changes to `grimoire`-side playlist model need to mirror these fields so freqhole + playlistz stay interoperable.
+
+### docIndex additions
+
+```ts
+interface DocIndexEntry {
+  // existing fields...
+  remoteNodeId?: string; // peer this was received from (if any)
+  remoteName?: string; // their display name
+  isForked?: boolean; // true if the user forked from the remote
+}
+```
+
+---
+
+## knock-with-message flow
+
+the search bar detects a share link and triggers `openShareLink`. before that resolves, if the peer's mode is "knock", a knock dialog should appear inline in the all-playlists panel.
+
+### ui flow
+
+1. user pastes share link into search bar
+2. `decodeShareToken` extracts `nodeId`
+3. app tries `queryPeerPlaylists(nodeId)` - if `knockRequired: true`:
+   - show a knock form in-panel:
+     ```
+     [name (pre-filled from local display name)]
+     [say who you are and mention something only the admin would know (but no passwords or secrets!)]
+     [send knock]  [cancel]
+     ```
+4. `knockOnPeer(nodeId, { name, message })` - extend `KnockMessage` type to include `message?: string`
+5. status shows "knock sent - waiting for access..."
+6. when the owner accepts, the pending share link is opened automatically (the search bar retains the link until resolved)
+
+### service changes
+
+- `knockOnPeer` in `sharingService.ts`: add optional `message` param, include it in the `knock` protocol message
+- `KnockRecord` in `indexedDBService.ts`: already has `message` field - just needs to be surfaced in `knockOnPeer` call and knock accept ui
+
+---
+
+## per-playlist sharing mode
+
+currently sharing mode (`public` / `knock`) is a global endpoint setting. it needs to move to per-playlist.
+
+### changes
+
+- `sharingService.ts`: `getShareSettings()` keeps the global endpoint mode as a fallback default
+- `PlaylistSharePanel.tsx`: "who can browse my playlistz?" buttons save to the current playlist doc's `sharingMode` field (not global settings)
+- the protocol responder in `sharingService.ts` (`handlePlaylistzStream`) checks `doc.sharingMode` when deciding whether to require a knock for `list_playlists` and `blob_request` messages
+
+---
+
+## read-only subscribed mode
+
+when a user adds a remote playlist (via share link or browse), it starts in **subscribed** mode:
+
+- automerge sync is receive-only: local changes are not pushed back to the owner
+- the ui reflects read-only state:
+  - title / description inputs are disabled
+  - drag-to-reorder is disabled
+  - add-song buttons are hidden
+  - edit panel shows two buttons instead of normal edit controls:
+    - **fork** - detaches from the remote doc, making a local editable copy
+    - **collaborate** - sends a collaborator knock request to the owner
+
+### ui sentinel
+
+`selectedPlaylist().remoteSource && !selectedPlaylist().remoteSource.forked` → read-only mode
+
+the main playlist component passes a `readOnly` prop down to song rows, title input, and the edit panel.
+
+### fork behavior
+
+1. user clicks "fork" in edit panel
+2. a new automerge doc is created from the current doc snapshot
+3. `remoteSource.forked = true` is written to the original doc's index entry
+4. the new doc is added to the index as a locally-owned playlist
+5. original subscribed doc is removed from the index (user no longer receives updates)
+6. new playlist is selected
+
+the original automerge doc handle should be closed/unregistered so the repo stops syncing it.
+
+---
+
+## collaborator access
+
+### requesting collaboration
+
+1. user clicks "collaborate" in the edit panel of a subscribed playlist
+2. a knock is sent with `type: "collaborate_request"` (new knock type)
+3. ui shows "collaboration request sent" status
+
+### accepting collaboration
+
+in the share panel's knock inbox:
+
+- knock items with `type: "collaborate_request"` show a different label
+- "accept (collaborator)" grants write access: adds the requester's node id to `doc.collaborators`
+- once in `collaborators`, the automerge sync policy for that peer switches from read-only to bidirectional
+
+### automerge sync policy
+
+the `sharePolicy` in `automergeRepo.ts` currently uses `peers` map in the doc. it needs to distinguish:
+
+- `collaborators` map → full sync (push + receive)
+- `subscribers` map → receive-only (announce doc to them, reject their changes)
+- neither → no access
+
+implementing receive-only at the automerge layer requires the `sharePolicy` to filter outbound sync messages per-peer. this may need a custom `SharePolicy` implementation.
+
+---
+
+## conflict resolution ui
+
+when a subscribed playlist receives incoming changes that conflict with local edits (automerge detects divergence):
+
+show a banner in the share panel (or edit panel header):
+
+```
+incoming changes from [peer name]
+[accept incoming — your changes will be overwritten]
+[fork to new playlist — unsubscribe your copy]
+```
+
+- **accept incoming**: call `doc.merge(remoteDoc)` explicitly, discarding local branch
+- **fork to new playlist**: same as the fork flow above
+
+detecting divergence: automerge doesn't expose conflict detection directly. a practical heuristic is comparing the doc's `updatedAt` timestamp against the last-known remote sync timestamp.
+
+---
+
+## open questions to resolve in session
+
+- how to implement receive-only automerge sync at the repo level without forking automerge-repo? (may need a wrapper around the network adapter that drops outbound sync for non-collaborator docs)
+- should per-playlist `sharingMode` be stored in the automerge doc itself (shared with peers) or only in the local docIndex? storing in the doc means the owner's mode change propagates to subscribers automatically.
+- when a collaborator is added, do all existing subscribers also see the collaborator's changes? (probably yes, since the automerge doc is shared)