@freqhole/playlistz 0.0.1

package/docs/E2E_TESTID_PLAN.md

@@ -0,0 +1,234 @@
+# e2e testid + component refactor plan
+
+this is the working reference for the ongoing refactor of e2e selectors and
+component structure. add new entries here as testids are added. do not remove
+entries; mark them done.
+
+---
+
+## naming conventions (summary)
+
+| type                       | pattern                     | examples                                                                                      |
+| -------------------------- | --------------------------- | --------------------------------------------------------------------------------------------- |
+| app sentinel               | `app-ready`                 | present once app shell has loaded                                                             |
+| panels                     | `[name]-panel`              | `all-playlists-panel`, `share-panel`, `edit-panel`, `song-edit-panel`                         |
+| header icon buttons        | `btn-[action]`              | `btn-all-playlists`, `btn-edit-playlist`, `btn-share-playlist`                                |
+| panel close button         | `btn-close-panel`           | single stable testid; only one panel open at a time                                           |
+| row-level buttons          | `btn-[action]-song`         | `btn-edit-song`, `btn-remove-song`, `btn-drag-song`                                           |
+| row-level playlist buttons | `btn-[action]-playlist-row` | `btn-edit-playlist-row`, `btn-share-playlist-row`, `btn-play-playlist-row`                    |
+| empty state buttons        | `btn-[action]`              | `btn-new-playlist`                                                                            |
+| form inputs                | `input-[field]`             | `input-playlist-title`, `input-playlist-description`, `input-node-name`, `input-peer-node-id` |
+| content display cells      | `[component]-[field]`       | `song-duration`, `playlist-song-count`, `playlist-total-time`, `row-song-count`               |
+| empty states               | `empty-[component]`         | `empty-songs`, `empty-playlists`                                                              |
+| action buttons             | `btn-[action]`              | `btn-download-zip`, `btn-cache-offline`, `btn-p2p-save-offline`                               |
+
+**no duplicate testids.** every `data-testid` value must be unique across the whole
+component tree. if the same semantic thing appears in two places (e.g. song count
+in the header vs. in a panel row), give each a distinct name. when no existing
+pattern fits, use `btn-[verb]-[noun]` (kebab, no underscores).
+
+**avoid `getByText` for assertions too.** content cells, counts, and state indicators
+should get testids so tests assert on structure, not copy. `getByText` is acceptable
+only when the test is explicitly verifying a user-visible string (e.g. a song title
+that was just set in setup).
+
+---
+
+## complete testid map
+
+### `src/components/index.tsx`
+
+| element                              | current test selector                        | testid             | status |
+| ------------------------------------ | -------------------------------------------- | ------------------ | ------ |
+| `<h1 class="sr-only">playlistz</h1>` | `getByRole("heading", {name:"playlistz"})`   | `app-ready`        | [ ]    |
+| empty state "new playlist" button    | `getByRole("button", {name:"new playlist"})` | `btn-new-playlist` | [ ]    |
+| "no playlistz yet" empty state       | `getByText("no playlistz yet")`              | `empty-playlists`  | [ ]    |
+
+### `src/components/playlist/index.tsx` - header action buttons
+
+| element                          | current selector                                                 | testid                       | status |
+| -------------------------------- | ---------------------------------------------------------------- | ---------------------------- | ------ |
+| hamburger (all playlists) button | `getByTitle("all playlistz")`                                    | `btn-all-playlists`          | [ ]    |
+| edit/close-edit toggle button    | `getByTitle("edit playlist")` / `getByTitle("close edit panel")` | `btn-edit-playlist`          | [ ]    |
+| share button                     | `getByTitle("share playlist")`                                   | `btn-share-playlist`         | [ ]    |
+| cache offline button             | `getByTitle("download songz for offline use")`                   | `btn-cache-offline`          | [ ]    |
+| p2p save offline button          | `getByTitle("save offline (fetch from peerz)")`                  | `btn-p2p-save-offline`       | [ ]    |
+| download zip button              | `getByTitle("download playlist as zip")`                         | `btn-download-zip`           | [ ]    |
+| song count span                  | `getByText("3 songz")`                                           | `playlist-song-count`        | [ ]    |
+| total time span                  | `getByText("0:03")` (fragile)                                    | `playlist-total-time`        | [ ]    |
+| playlist title input             | `locator("input[placeholder='playlist title']")`                 | `input-playlist-title`       | [ ]    |
+| playlist description input       | `locator("input[placeholder='add description...']")`             | `input-playlist-description` | [ ]    |
+| "no songz yet" empty state div   | `getByText("no songz yet")`                                      | `empty-songs`                | [ ]    |
+
+### `src/components/playlist/PanelMiniHeader.tsx`
+
+| element      | current selector                                                        | testid            | status   |
+| ------------ | ----------------------------------------------------------------------- | ----------------- | -------- |
+| close button | `getByTitle("close share panel")` / `getByTitle("close all playlists")` | `btn-close-panel` | [x] done |
+
+### `src/components/AllPlaylistsPanel.tsx`
+
+| element                 | current selector                                    | testid                   | status   |
+| ----------------------- | --------------------------------------------------- | ------------------------ | -------- |
+| panel root div          | `getByTestId("all-playlists-panel")`                | `all-playlists-panel`    | [x] done |
+| "new playlist" button   | `getByRole("button", {name:"new playlist"})`        | `btn-new-playlist`       | [ ]      |
+| play row button         | `getByTitle("play ...")`                            | `btn-play-playlist-row`  | [ ]      |
+| edit row button         | `getByTitle("edit playlist")` (in panel)            | `btn-edit-playlist-row`  | [ ]      |
+| share row button        | `getByTitle("share playlist")` (in panel)           | `btn-share-playlist-row` | [ ]      |
+| download zip row button | `getByTitle("download playlist as zip")` (in panel) | `btn-download-zip-row`   | [ ]      |
+| song count cell per row | `getByText("3 songz")`                              | `row-song-count`         | [ ]      |
+
+### `src/components/PlaylistSharePanel.tsx`
+
+| element                          | current selector                                       | testid                | status |
+| -------------------------------- | ------------------------------------------------------ | --------------------- | ------ |
+| panel root                       | none                                                   | `share-panel`         | [ ]    |
+| mode toggle: knock first         | `getByRole("button", {name:"knock first"})`            | `btn-mode-knock`      | [ ]    |
+| mode toggle: public              | `getByRole("button", {name:"anyone (public)"})`        | `btn-mode-public`     | [ ]    |
+| endpoint toggle button           | `getByTitle("enable endpoint")` / `"disable endpoint"` | `btn-toggle-endpoint` | [ ]    |
+| copy share link button           | `getByRole("button", {name:"copy share link"})`        | `btn-copy-share-link` | [ ]    |
+| p2p share link input (read-only) | none                                                   | `input-share-link`    | [ ]    |
+| node name input                  | `locator("input[placeholder='anonymous']")`            | `input-node-name`     | [ ]    |
+| browse peer node id input        | none                                                   | `input-peer-node-id`  | [ ]    |
+| open/browse peer button          | `getByRole("button", {name:"open", exact:true})`       | `btn-browse-peer`     | [ ]    |
+| knock request button             | `getByTitle("ask this peer for access")`               | `btn-knock-peer`      | [ ]    |
+| "enable p2p sharing" toggle      | `getByText("enable p2p sharing")`                      | `btn-enable-sharing`  | [ ]    |
+| online/offline status indicator  | `getByText("online")`                                  | `sharing-status`      | [ ]    |
+| "no pending knockz" empty state  | `getByText("no pending knockz")`                       | `empty-knock-inbox`   | [ ]    |
+| "invalid share link" error       | `getByText("invalid share link")`                      | `share-link-error`    | [ ]    |
+| "playlist added!" success msg    | `getByText("playlist added!")`                         | `share-success`       | [ ]    |
+| knock inbox section              | `getByText("knock inbox")`                             | `knock-inbox`         | [ ]    |
+
+### `src/components/PlaylistEditPanel.tsx`
+
+| element                          | current selector                           | testid             | status |
+| -------------------------------- | ------------------------------------------ | ------------------ | ------ |
+| panel root                       | none                                       | `edit-panel`       | [ ]    |
+| playlist cover background button | `getByTitle("set the page background...")` | `btn-set-bg-cover` | [ ]    |
+
+### `src/components/SongRow.tsx`
+
+| element            | current selector                     | testid            | status   |
+| ------------------ | ------------------------------------ | ----------------- | -------- |
+| duration cell      | `[data-testid='song-duration']`      | `song-duration`   | [x] done |
+| edit song button   | `getByTitle("edit song")`            | `btn-edit-song`   | [ ]      |
+| remove song button | `getByTitle("remove from playlist")` | `btn-remove-song` | [ ]      |
+| drag handle        | `getByTitle("drag to reorder")`      | `btn-drag-song`   | [ ]      |
+
+### `src/components/SongEditPanel.tsx`
+
+| element    | current selector | testid            | status |
+| ---------- | ---------------- | ----------------- | ------ |
+| panel root | none             | `song-edit-panel` | [ ]    |
+
+---
+
+## e2e helpers to update (`e2e/helpers.ts`)
+
+| function                  | current                                              | target                                       |
+| ------------------------- | ---------------------------------------------------- | -------------------------------------------- |
+| `waitForApp`              | `getByRole("heading", {name:"playlistz"}).waitFor()` | `getByTestId("app-ready").waitFor()`         |
+| `createPlaylistViaUI`     | `getByRole("button", {name:"new playlist"}).first()` | `getByTestId("btn-new-playlist")`            |
+| `createPlaylistViaUI`     | `getByTitle("all playlistz").first().click()`        | `getByTestId("btn-all-playlists").click()`   |
+| `createPlaylistViaUI`     | `getByTitle("edit playlist").first().waitFor()`      | `getByTestId("btn-edit-playlist").waitFor()` |
+| `openSharePanel`          | `getByTitle("share playlist").first().click()`       | `getByTestId("btn-share-playlist").click()`  |
+| `openSharePanel`          | `getByTestId("btn-close-panel").waitFor()`           | already correct                              |
+| `addSongs` last-song wait | `getByText("song-0N")`                               | keep - asserting content is correct          |
+
+## spec file selector audit
+
+every `getByTitle(...)`, `getByRole("button", {name:...})`, `getByText(...)` used
+to _click_ or _wait_ on an element should become `getByTestId(...)`. `getByText`
+may remain only when the assertion is verifying that specific content is visible
+(e.g. a playlist or song name the test itself just created).
+
+key replacements across all specs:
+
+| current pattern                                                    | replacement                                         |
+| ------------------------------------------------------------------ | --------------------------------------------------- |
+| `getByTitle("edit playlist")`                                      | `getByTestId("btn-edit-playlist")`                  |
+| `getByTitle("share playlist")`                                     | `getByTestId("btn-share-playlist")`                 |
+| `getByTitle("all playlistz")`                                      | `getByTestId("btn-all-playlists")`                  |
+| `getByRole("button", {name:"new playlist"})`                       | `getByTestId("btn-new-playlist")`                   |
+| `getByRole("button", {name:"knock first"})`                        | `getByTestId("btn-mode-knock")`                     |
+| `getByRole("button", {name:"anyone (public)"})`                    | `getByTestId("btn-mode-public")`                    |
+| `getByRole("button", {name:"copy share link"})`                    | `getByTestId("btn-copy-share-link")`                |
+| `getByRole("button", {name:"open", exact:true})`                   | `getByTestId("btn-browse-peer")`                    |
+| `getByTitle("enable endpoint")` / `getByTitle("disable endpoint")` | `getByTestId("btn-toggle-endpoint")`                |
+| `getByText("enable p2p sharing")` (click/wait)                     | `getByTestId("btn-enable-sharing")`                 |
+| `getByText("online")` (wait)                                       | `getByTestId("sharing-status")`                     |
+| `getByText("no pending knockz")`                                   | `getByTestId("empty-knock-inbox")`                  |
+| `getByText("invalid share link")`                                  | `getByTestId("share-link-error")`                   |
+| `getByText("playlist added!")`                                     | `getByTestId("share-success")`                      |
+| `getByText("no songz yet")`                                        | `getByTestId("empty-songs")`                        |
+| `getByText("3 songz")` in header                                   | `getByTestId("playlist-song-count")`                |
+| `getByText("3 songz")` in all-playlists row                        | `getByTestId("row-song-count")`                     |
+| `locator("input[placeholder='playlist title']")`                   | `getByTestId("input-playlist-title")`               |
+| `locator("input[placeholder='anonymous']")`                        | `getByTestId("input-node-name")`                    |
+| `getByTestId("btn-edit-playlist-row")` (in panel)                  | scope to `getByTestId("all-playlists-panel")` first |
+| `getByTestId("btn-share-playlist-row")` (in panel)                 | scope to `getByTestId("all-playlists-panel")` first |
+
+---
+
+## playwright config changes (`config/playwright.config.ts`)
+
+- add `expect: { timeout: 5000 }` to the `use` block (makes current `{ timeout: 5000 }` inline overrides redundant - remove them)
+- the global `actionTimeout: 10_000` stays; it already covers most click timeouts
+
+---
+
+## component split plan for `playlist/index.tsx` (1073 lines)
+
+this is the biggest structural win. the file contains several logical sub-components
+that should be extracted. suggested order (each extraction is independently mergeable):
+
+1. **`PlaylistHeaderActions`** - the row of header icon buttons (hamburger, edit,
+   share, cache, download). currently `playerControls()` inner function (~lines 470-800).
+   extract to `src/components/playlist/PlaylistHeaderActions.tsx`.
+
+2. **`PlaylistSongCount`** - the song count + total time display spans. small but
+   gives a stable testid home. could fold into PlaylistHeaderActions.
+
+3. **`PlaylistCoverImage`** - the desktop cover image column. currently `coverImage()`
+   inner function (~lines 805-855). extract to `src/components/playlist/PlaylistCoverImage.tsx`.
+
+4. **`PlaylistSongList`** - the rows container + empty state + all the Show/For
+   logic for song rows. currently ~lines 1000-1073. extract to
+   `src/components/playlist/PlaylistSongList.tsx`.
+
+5. **`PlaylistContainer` itself** - once the above are extracted it shrinks to
+   just panel switching logic + header + scroll container + keyboard handler.
+
+extraction order matters: start with leaf components (no internal dependencies),
+work inward. run `npm run typecheck` after each extraction.
+
+---
+
+## `waitForTimeout` audit
+
+these are the known "sleep" calls. replace with element waits where a clear signal exists:
+
+| file                     | line    | current                                | replacement                                                                   |
+| ------------------------ | ------- | -------------------------------------- | ----------------------------------------------------------------------------- |
+| `sharing-access.spec.ts` | ~75     | `waitForTimeout(300)` after mode click | wait for button to gain `border-magenta` class                                |
+| `sharing-access.spec.ts` | ~113    | `waitForTimeout(500)` after mode click | same                                                                          |
+| `sharing.spec.ts`        | ~52     | `waitForTimeout(300)` after mode click | same                                                                          |
+| `all-playlists.spec.ts`  | many    | `waitForTimeout(300)` after title blur | wait for `input-playlist-title` value to settle (hard signal) - leave for now |
+| others                   | various | `waitForTimeout(300)` after blur       | same - leave until we have a better signal                                    |
+
+items marked "leave for now" are waiting on automerge write propagation where
+there is no DOM signal. do not remove them without adding a proper wait.
+
+---
+
+## implementation order
+
+1. [x] update `copilot-instructions.md` with conventions
+2. [x] write this plan doc
+3. [ ] add all source testids (source agent)
+4. [ ] update `config/playwright.config.ts` (add `expect.timeout`)
+5. [ ] update `e2e/helpers.ts` (test agent)
+6. [ ] update all spec files (test agent)
+7. [ ] `npm run typecheck` + `npm run test:e2e -- --grep-invert "@p2p"`
+8. [ ] extract `PlaylistHeaderActions` from `playlist/index.tsx`
+9. [ ] extract remaining sub-components incrementally

package/docs/IROH_P2P_PLAN.md

@@ -0,0 +1,302 @@
+# iroh p2p networking plan
+
+> NOTE: partially superseded by [AUTOMERGE_P2P_PLAN.md](AUTOMERGE_P2P_PLAN.md) - playlist sync now uses automerge docs instead of the hand-rolled wire protocol and spume idb store mirroring. the packaging, identity interop, web locks, blob store, and knock sections here remain authoritative and are referenced from the new plan.
+
+introduce iroh p2p networking into playlistz, interoperable with freqhole (tomb/). playlistz consumes `midden` (rust->wasm iroh client) and `freqhole-api-client` (generated TS client + zod schemas) via `file:` package refs. a new `freqhole-playlistz/1` ALPN lets playlistz apps share playlists with each other and with freqhole servers, including public sharing and knock access requests. share links use the same base64url token format as spume.
+
+progress is tracked with checkboxes in each phase. this doc holds decisions and technical detail; open questions live in conversation, decisions get folded back in here.
+
+## reference map
+
+key code in tomb/ this plan builds on:
+
+| concern                    | location                                                                                                                                                                                                                        |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------- | ------------ |
+| midden wasm bindings       | `tomb/client/midden/src/lib.rs`, build via `tomb/client/midden/Makefile` (wasm-pack, bundler target), output `tomb/client/midden/pkg/`                                                                                          |
+| midden JS API              | `MiddenNode` (create/create_from_key/create_with_alpns, accept, open_bi, blob import/download), `BiStream` (write_message/read_message 4-byte BE length framing, write_line/read_line ndjson, read_to_end/write_raw_and_finish) |
+| ALPN registry              | hardcoded in `create_with_secret_key()` in midden lib.rs: `freqhole/1`, `iroh/automerge-repo/1`, `freqhole-friendz/1`, `freqhole-admin/1`, `freqhole-events/1`, `freqhole-radio/1`, iroh-blobs                                  |
+| api client                 | `tomb/client-codegen/freqhole-api-client/` - raw TS source, exports `FreqholeClient`, `HttpTransport`, `WasmTransport`, `AdminClient`, generated `codegen/schema.ts` + `codegen/routes.ts`                                      |
+| freqhole playlist schema   | `tomb/grimoire/src/music/entities/playlists/models.rs` + `PlaylistSchema` in schema.ts                                                                                                                                          |
+| freqhole song schema       | `tomb/grimoire/src/music/entities/songs/models.rs` + `SongSchema`                                                                                                                                                               |
+| image metadata             | `ImageMetadata { blob_id, is_primary (0/1), blob_type: "original"                                                                                                                                                               | "thumbnail" | "waveform"                                                                                                      | "preview" }` |
+| entity urls                | `EntityUrl { id?, name?, url }` on playlists and songs                                                                                                                                                                          |
+| spume identity persistence | IDB db `freqhole_app` v8, store `app_state` (keyPath `id`), record key `p2p_identity`: `{ id, secret_key: Uint8Array(32), node_id: string, created_at: number }`                                                                |
+| spume opfs blobs           | opfs `/blobs/{blobId}` where blobId = sha256 hex of content                                                                                                                                                                     |
+| share token format         | `tomb/client/spume/src/utils/permalink.ts` + `components/share/buildSharePayload.ts` - `SharePayloadV1`, canonical JSON (sorted keys) -> base64url no padding                                                                   |
+| knock model                | `KnockRequest { id, node_id, username, message, status: pending                                                                                                                                                                 | accepted    | rejected, created_at, processed_at?, processed_by? }`, public routes `POST /api/knock`, `GET /api/knock/status` |
+| spume midden init          | `tomb/client/spume/src/app/api/client.ts` - getP2PIdentity -> create_from_key or create+save, then blob server                                                                                                                  |
+| vite wasm config           | `tomb/client/spume/vite.config.ts` - `vite-plugin-wasm` + `vite-plugin-top-level-await`, `target: "esnext"`, no COOP/COEP needed (midden is single-threaded, no SharedArrayBuffer)                                              |
+
+key playlistz internals affected:
+
+| concern           | location                                                                                                                                                                                                         |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| data model        | `src/types/playlist.ts` (Playlist, Song)                                                                                                                                                                         |
+| idb               | `src/services/indexedDBService.ts` - db `musicPlaylistDB` v6, stores: playlists, songs, playbackPositions, lastPlayed, settings; live queries with fields whitelist + BroadcastChannel `musicPlaylistDB-changes` |
+| audio storage     | inline `song.audioData: ArrayBuffer` in songs store, `song.sha` = sha256 of audio bytes                                                                                                                          |
+| image storage     | inline `imageData`/`thumbnailData` ArrayBuffers + `imageType` mime on playlist/song records                                                                                                                      |
+| export format     | `src/utils/standaloneTemplates.ts` zod schemas, `window.__PLAYLISTZ__`, `playlistz.js`                                                                                                                           |
+| edit panel flyout | `src/components/playlist/index.tsx` + `useSongState` signals (`editingPlaylist`, `editingSong`)                                                                                                                  |
+| build             | `config/vite.config.ts` (dev/app), `build-component.js` (standalone IIFE web component + cli)                                                                                                                    |
+
+## architecture decisions
+
+### guiding principle: one shared storage/p2p layer
+
+every piece of browser storage or p2p plumbing built here should end up in exactly one place - `freqhole-api-client` (already shared) or its new `storage` subpath - with spume and playlistz as thin consumers. accept slower implementation now for one maintained codepath later. concretely the rule is: before writing storage/transfer code in playlistz, check spume for an equivalent; if one exists, extract it to the shared package (and migrate spume to the extracted version) rather than reimplementing. app-specific orchestration (reactivity, UI state, each app's own record shapes) stays in each app.
+
+### packages
+
+- `package.json` gains `"midden": "file:../tomb/client/midden/pkg"` and `"freqhole-api-client": "file:../tomb/client-codegen/freqhole-api-client"`.
+- freqhole-api-client is raw TS source (no build step), bundles fine with vite. zod versions are compatible (playlistz ^4.4.3, client requires ^4.3.5).
+- midden requires `vite-plugin-wasm` + `vite-plugin-top-level-await` in `config/vite.config.ts`. no COOP/COEP headers needed.
+- single-file standalone: we will attempt to bundle midden's wasm INTO `freqhole-playlistz.js`. approach: build midden with wasm-pack `web` target (its `init(input)` accepts raw bytes), base64-inline `midden_bg.wasm` in `build-component.js` (esbuild `binary`/define step), decode + `init(bytes)` at runtime. p2p stays behind a lazy dynamic import so the app boots fine if wasm init fails (e.g. exotic browsers); if the inline approach proves unworkable the fallback is hosted-only p2p with the standalone build failing soft.
+- shared storage namespace: new browser-storage code that both spume and playlistz can use lives in `freqhole-api-client` under a dedicated subpath export, e.g. `freqhole-api-client/storage` (`src/storage/` - idb db/store constants + open helpers, blob store (opfs + cache fallback), identity records, rolling blob cache). strictly browser-agnostic of either app's UI; spume migrates to it opportunistically. keeps tomb code unaware of playlistz while sharing the exact schemas.
+
+### ALPN
+
+- new ALPN string: `freqhole-playlistz/1`.
+- registered two ways:
+  1. playlistz (JS side) uses `MiddenNode.create_with_alpns(keyBytes, ["freqhole-playlistz/1"])`.
+  2. tomb side: add `const PLAYLISTZ_ALPN: &[u8] = b"freqhole-playlistz/1";` to midden lib.rs alpn list and grimoire/freqhole server accept loop so freqhole nodes can answer playlistz protocol requests.
+- playlistz runs the JS `accept()` loop (not `start_blob_server()`); midden's `accept()` handles iroh-blobs ALPN internally in rust and surfaces all other ALPNs to JS as `BiStream`, so inbound blob serving still works alongside the playlistz protocol handler.
+
+### identity interop with spume
+
+- identity record shape is spume's exactly: `{ id: "p2p_identity", secret_key: Uint8Array(32), node_id, created_at }`.
+- playlistz NEVER creates or upgrades `freqhole_app` - it has zero version coupling to spume's db. detection without accidental creation: `indexedDB.databases()` where available; fallback is `indexedDB.open(name)` with an `onupgradeneeded` handler that aborts the versionchange transaction (upgradeneeded only fires for a missing db when opening without a version, and aborting cancels creation).
+- startup resolution order:
+  1. `freqhole_app` exists with an `app_state` store -> read `p2p_identity` from it; if the store exists but has no identity, write ours there (plain writes to an existing store need no version bump).
+  2. otherwise -> identity lives in playlistz's own `musicPlaylistDB` `settings` store under key `p2p_identity` (same record shape).
+  3. no identity anywhere -> `MiddenNode.create()`, persist per the same order (spume db if present, else local).
+- result: on spume's domain playlistz transparently shares spume's node identity; standalone domains self-contain; a stale playlistz deploy can never block a spume db upgrade.
+- playlistz-specific p2p settings (profile name, avatar, public/knock policy) live in playlistz's own `settings` store, not in `freqhole_app`.
+
+### single live node per origin (web locks)
+
+two tabs (or spume + playlistz on one domain) initializing midden from the same secret key would put two live endpoints with the same node id on the network. guard with the Web Locks API:
+
+- exclusive lock name `freqhole-iroh-node` (origin-scoped, so spume and playlistz contend for the same lock when co-hosted).
+- leader tab: acquires the lock (held until tab close), inits the midden node, runs the accept loop, serves blobs.
+- non-leader tabs: detect the held lock (`navigator.locks.request(..., { ifAvailable: true })` returning null), stay passive, and queue a normal lock request so leadership fails over automatically when the leader tab closes (init node only once the lock is granted).
+- share panel surfaces lock state: "sharing active in this tab" (leader), "sharing is active in another tab" (passive, with the queued takeover noted), or "not started".
+- the lock helper lives in `freqhole-api-client/storage` so spume can adopt the same guard (it currently has this bug too).
+
+### spume storage alignment
+
+long-term goal: playlistz and spume on the same domain share playlists, songs, and images through identical idb/opfs schemas. tomb code never references playlistz; the shared shapes live in `freqhole-api-client/storage`. concretely, now:
+
+- iroh identity: spume's record shape and (when present) spume's db, via the read-only access rules above.
+- image blob bytes: spume's exact model - opfs `/blobs/{blobId}` (blobId = sha256 hex of content) with Cache API fallback (`freqhole-blobs` cache, key `https://blob.local/{blobId}`) for browsers without opfs. blob metadata in spume's exact `freqhole_blobs` idb db (v1, store `blobs`, keyPath `blob_id`, record `{ blob_id, storage_type: "opfs"|"cache", storage_path, mime_type, file_size, created_at }`). this replaces the earlier idea of a playlistz-local `imageBlobs` store.
+- naming: new playlistz fields use shapes that adapt 1:1 to spume's `freqhole_music` records (`is_primary` boolean<->0/1, blob ids as sha256) so a later convergence to spume's `freqhole_music` stores (playlists keyPath `playlist_id`, songs keyPath `id` + `by_sha256` index, composite `playlist_songs` store) is a data migration, not a redesign.
+- audio bytes: p2p-fetched audio goes straight into the shared blob store (opfs) instead of inline `audioData` - see data model below. on a shared domain this means spume and playlistz read the same `/blobs/{sha256}` file rather than duplicating the song. migrating EXISTING inline `audioData` to opfs is the deferred part, not the write path.
+- deferred (tracked in "later" below): migrating legacy inline `audioData` to the blob store, adopting spume's `freqhole_music` stores outright, and the rolling ~30min download cache (spume's `freqhole_cache_metadata` blobCache) for remote playback.
+
+extraction inventory (what moves from spume into `freqhole-api-client/storage`):
+
+| spume source                                                                                                                                       | shareability                                                                   | action                                                                                                 |
+| -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
+| `src/music/services/storage/blobs.ts` (opfs + Cache API fallback, `freqhole_blobs` metadata db, object-url session cache)                          | fully generic, only depends on `idb`                                           | extract verbatim; spume re-exports from shared package                                                 |
+| `src/music/services/cache/blobCache.ts` + `cacheNames.ts` + `inProgressTracking.ts`                                                                | generic idb/Cache/eviction core wrapped in spume reactive + remoteManager glue | split: extract the core, leave spume's reactive wrapper consuming it (deferred with the rolling cache) |
+| `freqhole-api-client` `WasmTransport` (`fetchBlobWithProgress`, `download_verified_streaming`, `import_blob`/`release_blob`, `uploadViaIrohBlobs`) | already shared                                                                 | playlistz consumes as-is                                                                               |
+| `src/music/services/storage/blobResolver.ts`, `audioAccess.ts`                                                                                     | spume-specific orchestration (freqhole_music songs, remotes, sync queue)       | stays in spume; playlistz writes its own thin equivalent over the shared layers                        |
+
+### data model changes (freqhole schema fit)
+
+new types in `src/types/playlist.ts`, mirroring freqhole's wire shapes but with JS-friendly booleans:
+
+```ts
+type BlobKind = "original" | "thumbnail" | "waveform" | "preview";
+
+interface ImageRef {
+  blobId: string; // sha256 hex of image bytes (matches spume opfs naming)
+  isPrimary: boolean; // converts to/from freqhole is_primary 0/1
+  blobType: BlobKind;
+}
+
+interface EntityUrl {
+  id?: string;
+  name?: string;
+  url: string;
+}
+```
+
+- `Playlist` gains: `images?: ImageRef[]`, `urls?: EntityUrl[]`, `isPublic?: boolean`.
+- `Song` gains: `images?: ImageRef[]`, `urls?: EntityUrl[]`, `lyrics?: string`, `blake3?: string` (for iroh-blobs transfer; computed via midden `hash_blake3` or at import), `audioBlobId?: string` (sha256, audio bytes in the shared blob store).
+- image bytes move to the shared blob store (opfs `/blobs/{sha256}` + `freqhole_blobs` metadata db, see spume storage alignment). multiple covers per playlist/song with one primary.
+- legacy `imageData`/`thumbnailData`/`imageType` fields remain readable; DB_VERSION 7 migration converts each existing record's inline image into two blob store entries (original + thumbnail) and an `images` array with `isPrimary: true`. inline fields are then deleted from records.
+- audio dual path: songs have EITHER inline `audioData` (existing local imports, unchanged) OR `audioBlobId` pointing at opfs (all p2p-fetched audio). a single accessor in audio loading checks `audioBlobId` first, falls back to `audioData`; everything downstream sees a Blob/object url either way. local file imports keep writing `audioData` for now; flipping them to the blob store (plus migrating existing records) is the deferred opfs move, which then becomes a backend swap behind the same accessor. `sha` remains the content identity, `blake3` sits next to it for p2p.
+- live query fields whitelists in `createPlaylistsQuery` / `createPlaylistSongsQuery` MUST gain: `images`, `urls`, `isPublic`, `lyrics`, `blake3`, `audioBlobId` (lesson learned: missing whitelist fields are silently stripped on every re-emit).
+- export schemas in `standaloneTemplates.ts` and import logic in `standaloneService.ts` / `playlistDownloadService.ts` gain the new fields (multiple images written to `data/` in zips, primary first).
+- UI for the new metadata (lyrics, urls, non-primary image management, waveform rendering) is deferred; phase 1 only keeps the existing single-cover editing experience working on top of the new model. no client-side waveform generation - waveform blobs only arrive from freqhole and are stored for later rendering.
+
+### wire protocol: freqhole-playlistz/1
+
+message framing: `BiStream.write_message` / `read_message` (4-byte BE u32 length prefix) carrying utf-8 JSON. every request/response is zod-validated. one request per stream open; responses may be multi-message for listings followed by clean EOF.
+
+```ts
+// request envelope
+{ v: 1, type: string, ...payload }
+
+// types (requester -> responder):
+{ v: 1, type: "hello" }
+  -> { v: 1, type: "hello", profile: { name, nodeId, avatarBlobId?, public: boolean }, playlistCount }
+{ v: 1, type: "list_playlists" }
+  -> { v: 1, type: "playlists", playlists: PlaylistSummary[] }   // requires access if not public
+{ v: 1, type: "get_playlist", playlistId }
+  -> { v: 1, type: "playlist", playlist: WirePlaylist }          // full metadata incl songs, image refs, blake3s
+{ v: 1, type: "get_blob", blobId }                               // small images only; audio goes via iroh-blobs
+  -> { v: 1, type: "blob", mimeType, dataBase64 }
+{ v: 1, type: "knock", name, message }
+  -> { v: 1, type: "knock_status", status: "pending" | "accepted" | "rejected" }
+{ v: 1, type: "knock_status", knockId }
+  -> { v: 1, type: "knock_status", status }
+{ v: 1, type: "error", code, message }                           // any failure
+```
+
+- `WirePlaylist` maps playlistz fields to freqhole-compatible naming (snake_case, `is_public` 0/1 free: we keep JSON booleans since this protocol is playlistz-defined; the freqhole server side adapter does the conversion).
+- audio transfer: requester gets `blake3` hashes from `get_playlist`, then uses midden `download_verified_streaming(peer_addr, blake3, size, on_chunk, on_progress)` over the iroh-blobs ALPN. responder pre-imports audio buffers into midden's blob store (`import_blob`) on share activation and tracks active blobs.
+- access control on the responder: if profile is public, all reads allowed. otherwise reads require the requester node_id to be in the local `accessGrants` (populated by accepting knocks). knock requests always allowed.
+
+### knock model (local, borrowed from freqhole)
+
+new `knocks` IDB store (keyPath `id`):
+
+```ts
+interface KnockRecord {
+  id: string; // uuid
+  nodeId: string; // requester iroh node id (inbound) or responder node id (outbound)
+  direction: "inbound" | "outbound";
+  name: string;
+  message: string;
+  status: "pending" | "accepted" | "rejected";
+  createdAt: number;
+  processedAt?: number;
+}
+```
+
+plus an `accessGrants` store (keyPath `nodeId`): `{ nodeId, name, grantedAt }`. accepting an inbound knock writes a grant; the share panel lists pending knocks with accept/reject. outbound knocks are re-checked on startup (mirrors spume's pendingKnockChecker) via `knock_status` requests.
+
+### share links
+
+same token scheme as spume so links are cross-compatible: canonical JSON (sorted keys, no whitespace) -> base64url without padding, payload `SharePayloadV1`:
+
+```ts
+{ v: 1, k: "playlist", i: <playlistId>, s: { n: <nodeId hex> }, t?: <title> }
+```
+
+- url shape: `<app origin>/#?share=<token>`.
+- on load, playlistz parses `location.hash`, decodes the token, opens a "remote playlist" view: hello -> knock if needed -> get_playlist -> stream songs on demand (with local caching into the normal stores, marked with a `sourceNodeId` so synced copies are distinguishable).
+- decoding tolerates unknown fields and `s.h` (http origin) for freqhole-server-sourced shares; fetching via http transport when `s.h` is present and `s.n` is absent.
+
+### reading freqhole playlists (playlistz as client of freqhole)
+
+- uses `freqhole-api-client`'s `WasmTransport` with the shared midden node against a freqhole server peer addr - same path spume uses, e.g. `client.music.listPlaylists`, `query_playlist_songs`, blob downloads via `download_verified_by_id`/blake3.
+- knock to a freqhole server uses the existing public knock route via `proxy_request` (`POST /api/knock`), not the playlistz ALPN.
+- a freqhole-sourced playlist maps into playlistz's model through an adapter (`images[].is_primary` 0/1 -> boolean, `media_blob_id` + `blake3` -> song download, `lyrics`, `urls` direct).
+
+### share panel UI
+
+- new share icon button in the playlist header action row, after the zip download button (`src/components/playlist/index.tsx`).
+- new `sharingPlaylist` boolean signal in `useSongState` following the `editingPlaylist` pattern; `isEditing()` includes it so the row flyout animation runs; `SharePanel` renders in the same slot as `PlaylistEditPanel`.
+- panel contents:
+  - first-run endpoint setup: profile name, avatar image upload, policy toggle (all playlists public vs knock required). persisted in settings store; activates the midden node + accept loop.
+  - node status: node id (copyable), connectivity.
+  - per-playlist share controls: generate/copy share link, toggle playlist public override.
+  - inbound knocks list with accept/reject.
+  - remotes: known peers (granted/outbound-knocked), with last-seen.
+
+### open share link UI
+
+- global `p2pConfigured` state (derived from settings store: endpoint setup completed) exposed via context, reactive on the settings store.
+- when `p2pConfigured` is true, the sidebar's `+ new playlist` row splits into two side-by-side buttons: the existing primary `+ new playlist`, and a non-primary `open share link` button.
+- `open share link` opens a panel (share panel chrome, different content): a text input for a pasted link, status/validation text below it, and a primary `open` action.
+- token extraction is forgiving: accept a bare token or any URL from any domain - scan the pasted string for the base64url payload chunk (e.g. after `#?share=`, `?share=`, `/o/`, or the longest base64url-decodable JSON segment), decode, validate against SharePayloadV1. validation feedback shows kind/title/node id preview before opening.
+- on confirm, runs the same remote playlist flow as a `#?share=` page load.
+
+## implementation phases
+
+### phase 1: data model + storage groundwork (no p2p yet)
+
+- [ ] `freqhole-api-client/storage` subpath in tomb: extract spume's idb constants/types (`freqhole_app`, `freqhole_blobs`, p2p identity record) and opfs blob store (write/read/delete `/blobs/{sha256}`, cache api fallback) into `src/storage/`; keep spume compiling (it can adopt the shared module later or immediately, whichever is cheaper)
+- [ ] add `ImageRef`, `EntityUrl`, `BlobKind` types; extend `Playlist`/`Song` interfaces (`images`, `urls`, `isPublic`, `lyrics`, `blake3`)
+- [ ] playlistz consumes the shared blob store for image bytes; DB_VERSION 7: `knocks` + `accessGrants` stores; migration converting inline image fields to blob store entries + `images` arrays
+- [ ] update live query fields whitelists (playlists + songs queries)
+- [ ] imageService: resolve `ImageRef[]` -> object urls (primary first) via blob store; keep `getImageUrlForContext` API + current single-cover edit UX working
+- [ ] export/import: standaloneTemplates schemas + playlistDownloadService + standaloneService support multiple images, lyrics, urls (backward compatible with existing zips)
+- [ ] tests for migration, blob store crud (opfs mocked), query field passthrough, export/import roundtrip
+
+### phase 2: package + build wiring
+
+- [ ] add `file:` deps (midden pkg, freqhole-api-client); npm install; verify midden pkg builds from tomb (`make build` in tomb/client/midden)
+- [ ] add `vite-plugin-wasm` + `vite-plugin-top-level-await` to `config/vite.config.ts` and vitest config as needed
+- [ ] gate all midden imports behind a lazy `import()` in a single `src/services/p2p/middenNode.ts` module
+- [ ] single-file attempt: midden `web`-target build (add a `build-web` target to the existing `tomb/client/midden/Makefile` emitting `pkg-web/` via `wasm-pack build -t web -d pkg-web`), base64-inline `midden_bg.wasm` into `freqhole-playlistz.js` via `build-component.js`, runtime decode + `init(bytes)`; verify standalone zip still works on `file://` (with and without p2p available)
+- [ ] smoke test: create node in dev app, log node id
+
+### phase 3: p2p core service
+
+- [ ] `freqhole-api-client/storage`: identity resolution (detect `freqhole_app` without creating it, read/write `p2p_identity`, local-settings fallback) + `freqhole-iroh-node` web lock helper (leader election, lock state callback)
+- [ ] `src/services/p2p/identity.ts`: playlistz wiring of the shared identity resolution (local fallback = `musicPlaylistDB` settings key `p2p_identity`)
+- [ ] `src/services/p2p/middenNode.ts`: leader-gated singleton init (acquire lock -> `create_from_key`/`create` + `create_with_alpns` for `freqhole-playlistz/1`), node id accessor, ready + lock-state signals
+- [ ] `src/services/p2p/acceptLoop.ts`: `accept()` loop dispatching by `stream.alpn()`; playlistz protocol handler entry
+- [ ] tomb side: add `PLAYLISTZ_ALPN` to midden lib.rs registered list (and bump midden version, rebuild pkg)
+- [ ] tests with a mocked midden module + mocked `navigator.locks`
+
+### phase 4: playlistz wire protocol
+
+- [ ] `src/services/p2p/protocol.ts`: zod schemas for all message types (versioned envelope), encode/decode helpers over `write_message`/`read_message`
+- [ ] responder handlers: hello, list_playlists, get_playlist, get_blob, knock, knock_status with access checks (public/grants)
+- [ ] requester client: typed functions mirroring the handlers
+- [ ] blob serving: on share activation import audio buffers into midden blob store; release on deactivation; track imported hashes
+- [ ] audio fetch path: `download_verified_streaming` -> shared blob store (`storeBlob`, opfs) + set `song.audioBlobId`; audio accessor resolves `audioBlobId` || `audioData` (reuse streamingAudioService progress UX)
+- [ ] protocol unit tests (handler logic against fake streams)
+
+### phase 5: knocks + access grants
+
+- [ ] knock crud in indexedDBService (knocks, accessGrants stores) with live queries
+- [ ] inbound knock handling in responder (dedupe by nodeId, pending record)
+- [ ] outbound knock + startup status recheck
+- [ ] accept/reject actions writing grants
+- [ ] tests
+
+### phase 6: share panel UI
+
+- [ ] `sharingPlaylist` signal in useSongState + flyout wiring in playlist container; share icon button after zip download button
+- [ ] `src/components/SharePanel.tsx`: endpoint setup form (name, avatar via blob store, public/knock policy), node id display, lock/leadership status ("sharing active in this tab" / "active in another tab" / "not started"), per-playlist share link generation, knock inbox, remotes list
+- [ ] settings persistence (settings store keys: `p2pProfile`, `p2pPolicy`, `p2pEnabled`) + reactive `p2pConfigured` global state in context
+- [ ] sidebar: when `p2pConfigured`, split `+ new playlist` into two side-by-side buttons (primary `+ new playlist`, non-primary `open share link`)
+- [ ] `open share link` panel: paste input, forgiving base64url token extraction from any url/string, validation preview (kind/title/node id), primary open action
+- [ ] component tests
+
+### phase 7: share links + remote playlist view
+
+- [ ] `src/utils/shareToken.ts`: SharePayloadV1-compatible encode/decode (canonical json, base64url)
+- [ ] hash route parsing on startup (`#?share=`)
+- [ ] remote playlist flow: hello -> (knock) -> get_playlist -> render read-only remote playlist with per-song fetch/stream + local save, `sourceNodeId` tagging
+- [ ] tests for token roundtrip + spume token compatibility fixtures
+
+### phase 8: freqhole server interop
+
+- [ ] adapter `src/services/p2p/freqholeAdapter.ts`: freqhole `PlaylistSchema`/`SongQueryResult` -> playlistz model (0/1 -> boolean, media_blob_id/blake3 mapping)
+- [ ] `WasmTransport` client usage for browsing/syncing freqhole playlists the user has access to
+- [ ] knock to freqhole servers via public knock route over `proxy_request`
+- [ ] tomb side: freqhole server answers `freqhole-playlistz/1` (grimoire handler translating protocol requests to playlist queries)
+- [ ] end-to-end test against a local freqhole server
+
+### phase 9: polish + docs
+
+- [ ] error surfaces (connection failures, denied access, stale grants)
+- [ ] perf: lazy wasm init only when share panel opened or share link present
+- [ ] docs/INDEX.md entry + user-facing share flow writeup
+- [ ] full test pass, coverage thresholds maintained
+
+## later (deliberately deferred, designed for)
+
+these are out of scope for the phases above but the decisions above keep their cost low:
+
+- **metadata UI**: rendering/editing lyrics, entity urls, multiple non-primary images, waveform display. the data model, storage, wire protocol, and export formats all carry these fields from phase 1; only components are missing.
+- **rolling download cache + download-everything**: adopt spume's blobCache pattern (`freqhole_cache_metadata` db, ~30min rolling window of remote audio, plus a one-shot save-offline-everything action) as a shared module in `freqhole-api-client/storage`. playlistz's `streamingAudioService` + `offlineService.cacheAudioFile` are the integration points; spume migrates to the shared module too.
+- **full idb convergence**: move playlistz playlists/songs onto spume's `freqhole_music` store layout (playlists keyPath `playlist_id` with `by_source_remote_id`/`by_last_synced_at` indices, songs `by_sha256`, composite `playlist_songs`) so same-domain apps share one library. field shapes already adapt 1:1; this becomes a data migration plus swapping store constants for the shared ones.
+- **legacy audio bytes into the shared blob model**: p2p audio already lands in opfs via `audioBlobId`; this item is flipping local file imports to do the same and migrating existing inline `audioData` records (background task: hash, `storeBlob`, set `audioBlobId`, delete `audioData`). pure backend swap behind the existing accessor.
+- **freqhole-generated playlistz zips (takeout)**: freqhole server dispenses zip bundles in playlistz's export format (playlistz.js + data/). the export schema gains an optional `sourceNodeId` on the playlist header so bundles carry their origin node id and can knock/sync back to the source. needs a grimoire takeout job + the standalone import path honoring `sourceNodeId`.