@freqhole/playlistz 0.0.1

package/docs/ROADMAP.md

@@ -0,0 +1,695 @@
+# playlistz roadmap
+
+active work is at the top, completed reference is at the bottom.
+
+status: `[ ]` not started, `[~]` in progress, `[x]` done.
+
+---
+
+## direction
+
+### modularization strategy
+
+the long-term aim is a clean package layering. currently a lot of logic lives
+in `playlistz/src/services/` that either duplicates `tomb/client/spume/`, or
+belongs in shared packages. rather than "moving things to tomb/", the goal is
+extracting reusable pieces into packages that both apps can depend on.
+
+current package layering:
+
+```
+freqhole-api-client  (framework-agnostic: storage, p2p wire, schemas, share links)
+       |
+  @freqhole/solid  (SolidJS wrappers: reactive signals over IDB, playlist hooks)
+       |
+playlistz/  +  spume/  (app-specific UI and state)
+```
+
+`freqhole-api-client` already exports: blob storage (IDB+OPFS/Cache), p2p
+identity, iroh automerge adapter, zod schemas for `PlaylistDoc` + `SongEntry`,
+knock/blob protocol messages, share link encode/decode.
+
+concrete next extractions:
+
+- **p2p node lifecycle** - `startP2P`, `stopP2P`, `getNode`, `getIdentity`,
+  accept loop, ALPN routing from `p2pService.ts` into `freqhole-api-client`
+- **blob transfer protocol** - `fetchBlobFromPeer` + `serveBlobRequest` BiStream
+  message exchange from `blobTransferService.ts` into `freqhole-api-client`
+- **new `@freqhole/solid` package** - SolidJS-specific wrappers that shouldn't
+  live in `freqhole-api-client` (no framework deps there): reactive signals over
+  IDB, playlist hooks (`usePlaylistManager` shape), drag-and-drop primitives,
+  media session bridge. both playlistz and spume could depend on this.
+- **shared e2e utilities** - `makeWav()`, `dropFiles()`, `waitForApp()` are
+  already reasonably generic; worth a `@freqhole/e2e-utils` package that playlistz
+  and any future tomb e2e suites share. `e2e/helpers/` is the extraction target.
+- **audio layer** - spume has `playerState`, `backends/`, `mediaSessionBridge`,
+  `playbackOrchestrator`; playlistz has `audioService.ts` + `streamingAudioService.ts`.
+  media session plumbing belongs in `freqhole-api-client/src/audio/mediaSession.ts`
+  (no SolidJS deps); the backend abstraction is a candidate for `@freqhole/solid`.
+
+for **`tomb/playlistz/`** specifically: it's an earlier copy of
+`freqhole/playlistz/src/services/` that has quietly diverged (lacks p2pService,
+blobTransferService, etc.). the goal is not to pick a "winner" and copy files
+over, but to have both apps depend on the shared packages above so there's nothing
+left to diverge. audit first, extract shared pieces, then the `tomb/playlistz/`
+copy just goes away naturally.
+
+for **two-browser `@p2p` e2e tests**: these need iroh relay + midden WASM
+which are built and managed in `tomb/`. the tests themselves should be shared
+or runnable from both sides; see the e2e infrastructure section.
+
+---
+
+## code conventions
+
+### underscore-prefix internal/dev exports
+
+there are currently two distinct reasons for underscore-prefix names; they
+should be treated differently:
+
+- **`_internal*`** (intended: module-private) - used inside a file but exported
+  by accident, or exported for a test that imports directly. these should NOT be
+  exported at all. move to a private helper or use vitest module mocking instead.
+
+- **`_dev*`** (intentional: dev-hook injection points) - exported specifically
+  for use by the corresponding `.dev.ts` file. the rule is:
+  - `_dev*` exports in `service.ts` are consumed only by `service.dev.ts`
+  - `service.dev.ts` registers them as `window.__*` hooks
+  - nothing else should import `_dev*` directly
+
+current state: `_devSetFetchOverride`, `_devEvictBlob`, `_devSetBlobFetchTimeout`,
+`_devFetchBlobBySha` are in `blobTransferService.ts`; `_devSeekTo`,
+`_devTriggerTrackEnd`, `_devTriggerAudioError` are in `audioService.ts`. all
+consumed only by their `.dev.ts` counterparts. pattern is working.
+
+- [ ] lint rule to enforce: `_dev*` symbols from service files may only be
+      imported by `*.dev.ts` files. use `eslint-plugin-import` `no-restricted-imports`
+      or a custom rule.
+- [ ] audit for accidentally-exported `_internal*` helpers (not `_dev*`) - these
+      should lose the export keyword or be inlined.
+
+### export hygiene
+
+services currently leak too much through their public API surface. guiding rules:
+
+- a service's public exports are what components and hooks need - no more
+- `export *` is only allowed in shim/barrel files (`e2e/helpers.ts`,
+  `e2e/helpers/index.ts`, `src/components/index.tsx`)
+- types used only inside a service file should not be exported
+- when a type is needed in two places, export it from the canonical module
+  (usually `src/types/playlist.ts`) not from the service
+
+- [ ] audit each service file: list exports, mark which are actually imported
+      elsewhere. remove or unexport any that aren't.
+- [ ] `eslint-plugin-import` `no-unused-modules` rule to surface dead exports
+
+### SolidJS reactivity patterns
+
+we have a recurring class of bugs where reactive values are read in non-reactive
+contexts. canonical mistakes and their fixes:
+
+| mistake                                 | symptom                                 | fix                                                                                       |
+| --------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------- |
+| destructure `props`                     | component never updates                 | use `props.foo` directly, or `splitProps`                                                 |
+| `onMount` for derived state             | state stale after async resolution      | `createEffect` tracks signal deps and re-runs                                             |
+| read signal in event handler, no effect | stale closure over initial value        | read inside the handler (closures over signals are fine - they call the getter each time) |
+| `createMemo` with side effects          | double-execution, stale deps            | memos are for derived values only; side effects go in `createEffect`                      |
+| spread props onto DOM element           | unknown prop warnings + reactivity loss | use `splitProps` to separate known props from rest                                        |
+
+concrete example fixed this session: `PlaylistEditPanel` used `onMount` to set
+cover image URL from `props.playlist.imageFilePath`. after page reload,
+`docToPlaylistAsync` resolves `imageFilePath` asynchronously after the panel
+mounts. the fix was `createEffect` which re-runs whenever `props.playlist.*`
+changes. `onMount` is correct only when you genuinely want "run once on mount
+with whatever the initial prop value is."
+
+- [ ] add `eslint-plugin-solid` to the project
+  - `solid/no-destructure` - catches prop destructuring
+  - `solid/reactivity` - warns on reactive values used outside reactive scope
+  - `solid/event-handlers` - naming conventions
+  - evaluate `solid/prefer-show` - probably off for now (subjective)
+- [ ] fix any violations that `eslint-plugin-solid` surfaces after adding it
+
+### .dev.ts pattern (mock isolation)
+
+services that need dev/test hooks follow this split:
+
+```
+src/services/fooService.ts       - production code. exports _dev* only as injection points
+src/services/fooService.dev.ts   - mock implementations + registerFooDevHooks()
+src/dev-hooks.ts                 - thin glue: imports and calls all register*DevHooks()
+```
+
+`dev-hooks.ts` is dynamically imported DEV-only:
+`void import("../dev-hooks.js")` inside a `if (import.meta.env.DEV)` guard
+in `src/components/index.tsx`. never present in production builds.
+
+the `window.__*` hooks declared in `src/types/global.d.ts` are the e2e-facing
+API; `e2e/helpers/hooks.ts` provides typed wrappers over them.
+
+### e2e test tagging + scripts
+
+tests are tagged by transport dependency:
+
+| tag     | meaning                                               | script          |
+| ------- | ----------------------------------------------------- | --------------- |
+| (none)  | real UI + real IDB/OPFS, no transport mock            | `test:e2e:real` |
+| `@mock` | uses `window.__mockBlobFetch` - transport substituted | `test:e2e:mock` |
+| `@p2p`  | real two-browser iroh transfer                        | `test:e2e:p2p`  |
+
+`@mock` tests are fast (run in-process, no relay), cover state-machine edge cases.
+`@p2p` tests are slow (relay dependent, 30-120s), prove the wire protocol works.
+both are needed; they test different things.
+
+time-acceleration hooks (`seekTo`, `triggerTrackEnd`, `triggerAudioError`) are
+NOT considered mock transport - don't tag tests that only use these as `@mock`.
+
+---
+
+---
+
+## pick up here
+
+last session (2026-06-12): 80/80 tests passing. mock infrastructure complete.
+ROADMAP restructured. `PlaylistEditPanel` cover-image `onMount`→`createEffect` bug fixed.
+
+**next immediate tasks (in rough priority order):**
+
+1. **`eslint-plugin-solid`** - add the plugin, fix violations. fast win, improves
+   all future SolidJS work. see "code conventions: SolidJS reactivity patterns". update .github/copilot-instructions.md and try to make it a regular point to review and address lint issues (which might mean tuning lint rules config)
+
+2. **initial blob prefetch on share link open** - wire `prefetchUpcoming()` call
+   into `sharingService.ts` after `handleShareFragment()` resolves. add one `@mock`
+   e2e test. see "active work: initial blob prefetch on share link open".
+
+3. **song row progress fraction** - `blobTransferService` already fires `onProgress`.
+   wire into `SongRow` as a thin fill or `data-download-fraction` attr + test.
+   see "active work: song row download progress fraction".
+
+4. **export audit** - run `eslint-plugin-import no-unused-modules`, trim dead exports.
+   low risk, improves readability before modularization work starts. also add ts-prune and madge circular dep check (see spume npm scripts for example) npm script and figure out a strategy, like lint runs, to review and address issues occasionally.
+
+---
+
+## active work
+
+### p2p transport: UX gaps
+
+#### initial blob prefetch on share link open
+
+when a guest opens a share link, they should hear music as soon as possible.
+the knock + automerge sync flow works, but blob transfers don't start until
+playback is triggered.
+
+- [ ] after `handleShareFragment()` resolves and the playlist doc is confirmed,
+      call `prefetchUpcoming(playlist, firstSongId, totalPlaylistDuration)` to
+      kick off blob transfers immediately
+- [ ] the trigger point is in `sharingService.ts` - wire into the existing
+      `pendingShareDocId` watch or a new `onPlaylistDocReady` callback
+- [ ] e2e test: synthetic share fragment pointing at a local doc, assert
+      `data-download-state` starts then clears for the first song (mock transport)
+- **modularization note**: the prefetch call is already in `blobTransferService.ts`;
+  only the trigger point in `sharingService.ts` needs wiring
+
+#### player loading state on share link auto-play
+
+when a guest opens a share link and the first blob isn't local yet, the player
+should communicate why playback hasn't started rather than appearing broken.
+
+- [x] `AudioPlayer.tsx` shows spinner + `aria-busy="true"` when `isFetchingBlob()`
+      is true - this covers the blob-fetch case already
+- [ ] the blob-fetch spinner and the audio-buffering spinner are currently the same
+      visual - consider a distinct "waiting for p2p" indicator (tooltip, color, or
+      icon variant) so the user knows it's a network wait, not a decode issue
+- [ ] if the initial blob fetch errors, show the error state from `blobDownloadStates`
+      on the play button rather than resetting to idle
+- **note**: initial prefetch (above) landing first makes this properly testable
+
+#### player stall detection
+
+distinct from the blob-fetch spinner (pre-play). this covers post-fetch stalls
+where the blob arrived but the audio element can't buffer fast enough.
+
+- [ ] if `audio.readyState < HAVE_FUTURE_DATA` persists for > N seconds after
+      `play()` is called, surface a "stalling" indicator on the player button
+- [ ] distinct from the normal buffering spinner - ideally a different icon or
+      tooltip explaining the stall
+- [ ] `__triggerStall(durationMs)` dev hook for unit testing; skip for e2e
+
+---
+
+### p2p transport: testing + fixtures
+
+#### longer fixtures for realistic p2p testing
+
+current committed fixtures top out at ~10s. longer tracks are needed to test
+prefetch windows and rendering under sustained transfer load.
+
+- [ ] add `long-drone-5min.mp3` to `e2e/fixtures/generate.mjs` - use ffmpeg
+      with `-t 300`, low bitrate mono to keep file size manageable
+- [ ] add a fixture with a specific total duration suitable for testing the
+      "first 30 minutes" prefetch window boundary
+- [ ] once longer fixtures exist: assert that `prefetchUpcoming` stops scheduling
+      new blobs once the 30-min budget is exhausted
+
+#### remaining mocked transport test scenarios
+
+`e2e/p2p-states.spec.ts` covers timeout, pending, retry, prefetch triggering,
+cancellation, and seek recalculation. gaps:
+
+- [ ] **progress chunks**: `__mockBlobFetch({ type: "progress", chunks: 5,
+msPerChunk: 100 })` - assert `data-download-state` is present during fetch
+      and clears on completion. (progress fraction UI is a separate item below;
+      this test only needs state transitions.)
+- [ ] once a progress fraction display exists in `SongRow`: assert the fraction
+      increments during a `{ type: "progress" }` mock fetch
+
+#### real two-browser @p2p tests
+
+mock tests cover state-machine edge cases fast; real tests prove the transport
+actually works end-to-end. both are needed.
+
+currently in `e2e/sharing.spec.ts` + `e2e/sharing-access.spec.ts`:
+
+- host creates playlist, shares link, guest opens - playlist visible
+- knock/public mode toggle (single-browser; no actual blob transfer yet)
+
+new tests to add:
+
+- [ ] **blob transfer smoke** (tagged `@p2p`, timeout 120s): host drops
+      `tone-440hz-2s.wav`, guest opens share link, wait for `data-download-state`
+      to clear, assert song plays. the canonical "does p2p actually work" test.
+- [ ] **knock blocks then unblocks** (`@p2p`): host in knock mode, guest opens
+      share link, assert `data-download-state="error"` (knock_required), host
+      approves, guest retries, blob arrives
+- [ ] **host offline mid-transfer** (`@p2p`): guest starts fetching, host closes
+      browser, assert guest shows `data-download-state="error"` gracefully
+- [ ] **prefetch before playback** (`@p2p`): host drops 3 short songs, guest
+      waits for all 3 `data-download-state` attrs to clear (prefetch window),
+      then plays - assert no stall
+
+**infrastructure note**: once blob transfer protocol is in `freqhole-api-client`,
+the e2e harness for `@p2p` tests can be shared: `tomb/` supplies the iroh relay
+and midden WASM build; playlistz e2e imports from a shared `@freqhole/e2e-utils`
+package. mocked `@mock` tests stay in `freqhole/playlistz/e2e/` and need no tomb
+infrastructure.
+
+---
+
+### share + access control UX
+
+#### per-playlist visibility modes
+
+current: one global mode (public / knock) applies to all playlists.
+
+- [ ] `PlaylistDoc` gains a `visibility: "public" | "knock" | "private"` field
+- [ ] `sharePolicy` in `automergeRepo.ts` checks per-doc visibility before
+      announcing to a peer
+- [ ] `list_playlists` and `blob_request` handlers check per-doc visibility
+      instead of global settings mode
+- [ ] ui: visibility toggle in the share panel, per-playlist
+- [ ] migration: docs without `visibility` default to global mode setting
+
+#### knock flow UX + two-browser coverage
+
+- [ ] knock inbox: show pending knock with peer node id + optional display name
+- [ ] approval ui: one-click accept / deny with "remember this peer" option
+- [ ] `aria-live` region on knock inbox for screen readers
+- [ ] two-browser `@p2p` test: knock mode, guest knocks, host approves, guest streams
+- [ ] two-browser `@p2p` test: public mode, guest streams immediately
+
+#### invite codes
+
+- [ ] short-lived signed tokens: `${docId}:${nonce}:${expiry}` (HMAC) that
+      pre-authorise a peer without a knock
+- [ ] reusable invite links: same shape, no nonce expiry, revocable by host
+- [ ] share panel: "create invite link" button copies a `#invite/...` fragment
+- [ ] invite link open flow: validates token, adds peer to ACL, auto-selects playlist
+- [ ] revocation: stored in doc's `invites` map, host can invalidate
+
+#### collaborative playlists
+
+- [ ] per-playlist `collaborative: boolean` flag in `PlaylistDoc`
+- [ ] when true: all peers with access can mutate the doc; "collaborative" badge;
+      edit panel shows `addedBy: string` per song
+- [ ] when false: originating peer only; "fork this playlist" button in share panel
+      for non-owned playlists
+
+---
+
+### ui + tooltips
+
+no toast UI in this app. prefer `title` attributes and inline tooltip-style
+affordances. kobalte may be worth adding for accessible popover/tooltip
+primitives if the complexity warrants it.
+
+#### zip download: p2p fetch state
+
+- [ ] if not all blobs are locally cached when download-zip is pressed: show a
+      spinner on the button and set `title="waiting on p2p fetch..."` while
+      missing blobs are fetched
+- [ ] if pressed again while waiting: show a confirmation tooltip (not modal) -
+      "not all songs are downloaded yet. download anyway?" with confirm/cancel
+
+#### song row download progress fraction
+
+- [ ] `blobTransferService` already fires `onProgress(fraction)` callbacks.
+      wire this into `SongRow` as a fill on the duration cell (or a thin bar)
+      so large-file downloads show incremental progress
+- [ ] `data-download-fraction` attribute for e2e assertions
+
+#### other polish
+
+- [ ] all-playlists panel: search input when `playlists().length > 10`;
+      client-side filter; "new playlist" row stays sticky
+- [ ] `PanelMiniHeader`: inline title editing and hover cover image
+- [ ] share panel "open a share link" input: after resolving, show correct
+      player state (ties into initial prefetch above)
+
+---
+
+### modularization: concrete next steps
+
+each item is independently dispatchable. see "direction" above for the overall
+package layering goal.
+
+#### extract node lifecycle to freqhole-api-client
+
+scope: `tomb/client-codegen/freqhole-api-client/`. no UI changes.
+
+`playlistz/src/services/p2pService.ts` handles node startup, identity, ALPN
+registration, and leader election. this logic is app-agnostic.
+
+- [ ] move `startP2P`, `stopP2P`, `getNode`, `getIdentity`, `waitForNode`,
+      `onLeadershipChange`, `hasExistingIdentity` into
+      `freqhole-api-client/src/p2p/node.ts`
+- [ ] `playlistz/p2pService.ts` becomes a thin wrapper that supplies the accept
+      loop callback and app-specific ALPN handlers
+- [ ] spume can adopt the same shared node lifecycle
+- [ ] update `freqhole-api-client` package exports + version
+
+#### extract blob transfer protocol to freqhole-api-client
+
+scope: `tomb/client-codegen/freqhole-api-client/` + `playlistz/src/services/`.
+
+the BiStream wire protocol lives in `blobTransferService.ts`; the IDB/storage
+layer is already in `freqhole-api-client`.
+
+- [ ] extract `fetchBlobFromPeer` + `serveBlobRequest` (BiStream message exchange)
+      into `freqhole-api-client/src/playlistz/blobProtocol.ts`
+- [ ] `blobTransferService.ts` retains app-level logic only: prefetch scheduling,
+      state signals (`blobDownloadStates`), inflight dedup, timeout, retry
+- [ ] spume's blob transfer can adopt the shared protocol functions
+- [ ] all existing `@mock` and `@p2p` e2e tests must continue to pass
+
+#### create @freqhole/solid package
+
+scope: new package in `tomb/` monorepo. no app-code changes initially.
+
+a SolidJS-specific layer over `freqhole-api-client`. exports reactive wrappers
+and hooks that both playlistz and spume can use.
+
+- [ ] scaffold `tomb/packages/solid/` (or alongside `freqhole-api-client`)
+      with its own `package.json`, `tsconfig.json`, `vite.config.ts`
+- [ ] move `usePlaylistManager`-shaped hook into the package (playlistz version
+      as reference; make it accept a `PlaylistDoc` observable rather than
+      app-specific state)
+- [ ] reactive IDB wrapper: signal that re-emits when a doc handle fires a change
+- [ ] media session bridge: `navigator.mediaSession` plumbing with no SolidJS
+      dep in `freqhole-api-client`, thin SolidJS `createEffect` wrapper in
+      `@freqhole/solid`
+- [ ] both playlistz and spume depend on the package; no duplication
+
+#### audit tomb/playlistz/ divergence
+
+scope: read-only audit, then decision. low risk.
+
+`tomb/playlistz/src/services/` is an earlier snapshot of playlistz services.
+it lacks `p2pService.ts`, `blobTransferService.ts`, `streamingAudioService.ts`.
+
+- [ ] run a diff: list which service files are in tomb/playlistz/ only, in
+      freqhole/playlistz/ only, and in both
+- [ ] for files in both: diff them and note which direction is ahead
+- [ ] output: a short audit doc or table summarising what to keep, migrate, or
+      drop. then this roadmap item updates with concrete action items.
+- [ ] longer-term goal: `tomb/playlistz/` depends on `@freqhole/solid` rather
+      than carrying its own service copies
+
+#### create @freqhole/e2e-utils package
+
+scope: new package; no changes to existing tests.
+
+`e2e/helpers/` contains utilities generic enough to share:
+`makeWav`, `dropFiles`, `waitForApp`, `resetAppState`, `loadCommittedAudioFixtures`.
+
+- [ ] scaffold `@freqhole/e2e-utils` package (alongside `freqhole-api-client`
+      or in a separate `packages/` dir)
+- [ ] move the non-app-specific helpers from `e2e/helpers/media.ts` and
+      `e2e/helpers/app.ts` into the package
+- [ ] playlistz `e2e/helpers/` becomes a thin wrapper that re-exports from
+      the package and adds app-specific helpers (`createPlaylistViaUI`, etc.)
+- [ ] `tomb/` e2e suites can then import `@freqhole/e2e-utils` directly
+
+#### audio layer convergence
+
+scope: multi-step, depends on `@freqhole/solid` existing first.
+
+- [ ] extract `navigator.mediaSession` plumbing into
+      `freqhole-api-client/src/audio/mediaSession.ts` (no SolidJS deps)
+- [ ] thin `@freqhole/solid` wrapper: `createEffect` that syncs signals to
+      the media session API
+- [ ] longer term: playlistz `audioService.ts` adopts spume's backend
+      abstraction (`playerState`, `backends/`) rather than its own raw
+      `HTMLAudioElement` wiring
+
+---
+
+## backlog
+
+items that are real but not the current focus.
+
+- **eslint-plugin-solid**: add the plugin and fix any violations. see "code
+  conventions" above for the specific rules and what to look for.
+- **export audit**: each service file has too many exports. run
+  `eslint-plugin-import no-unused-modules` and remove dead exports.
+- **songReactivity.ts workaround**: `triggerSpecificSongUpdate` is a workaround
+  for `SongRow` not reacting to doc changes directly. proper fix: derive from a
+  `playlistSongs()` signal (deferred to `@freqhole/solid` work).
+- **access-control two-browser tests**: `sharing-access.spec.ts` covers mode
+  toggles single-browser only. real two-browser knock/unblock tests are queued
+  under access control above.
+- **playback position persistence**: `savePlaybackPosition` exists in
+  `audioService.ts`; no e2e test that a reload resumes from saved position.
+- **blob GC e2e coverage**: deletion logic is implemented; no e2e test yet.
+- **repeat + shuffle e2e coverage**: signals exist, no e2e tests yet.
+
+---
+
+## completed (reference)
+
+### ui / panels
+
+**sidebar refactor (§1)**
+
+- `AllPlaylistsPanel.tsx` replaces `PlaylistSidebar.tsx` (deleted)
+- hamburger toggle, `PanelMiniHeader` shared component, `MarqueeText`, row
+  actions (play/edit/share/download), `EmptyState` for fresh installs
+- sidebar state removed from `useUIState.ts`
+- e2e: `e2e/all-playlists.spec.ts` (10 tests)
+
+**share link auto-play (§3a)**
+
+- after `handleShareFragment()`: select playlist, auto-play if idle,
+  `pendingShareDocId` watches `playlists()` reactively for docs still syncing
+
+**share panel inline layout (§3b)**
+
+- share panel animates in the song-rows area (same pattern as edit panel)
+- share button in playlist action row; `PlaylistSharePanel.tsx` inline with
+  `< >` nav, copy button, mode toggle
+
+---
+
+### p2p transport + state machine
+
+**per-song download state signal (§12a)**
+
+- `blobDownloadStates`: reactive `ReadonlyMap<sha256, "downloading" | "pending" | "error">`
+- `SongRow`: downloading - `text-blue-400 animate-pulse`; pending - `text-gray-500`;
+  error - `text-red-400 cursor-pointer`; `data-download-state` attr for e2e
+- error retry: clicking duration cell calls `fetchSongBlob(song())` directly
+
+**audio player loading state (§12b)**
+
+- `isFetchingBlob()` checks `blobDownloadStates` for current song sha
+- spinner + `aria-busy="true"` while blob is fetching or audio is buffering
+
+**prefetch window (§12c)**
+
+- `PREFETCH_CONCURRENCY = 3`, parallel batches with `Promise.allSettled`
+- `seeked` event re-calls `prefetchUpcoming` with recalculated remaining time
+- `prefetchRun` counter cancels stale runs on playlist switch
+- `pendingShas` + `clearPending()` for pending-state cleanup on cancellation
+
+**fetch timeout + retry (§15a-c)**
+
+- `BlobDownloadState` includes `"pending"` (queued but not yet started)
+- `BLOB_FETCH_TIMEOUT_MS = 30_000` (configurable via `_devSetBlobFetchTimeout`);
+  applies to both dev-override and real p2p paths
+- `_devFetchBlobBySha` + `window.__fetchBlobBySha` for programmatic retry in tests
+
+**dev hooks + .dev.ts mock isolation pattern**
+
+- `src/dev-hooks.ts`: 18-line registration glue, dynamically imported DEV-only
+  (`void import("../dev-hooks.js")` in `src/components/index.tsx`). never in prod.
+- each service that needs dev/test hooks has a paired `service.dev.ts` file:
+  - `src/services/audioService.dev.ts` - exports `registerAudioDevHooks()`
+  - `src/services/blobTransferService.dev.ts` - exports `registerBlobDevHooks()`,
+    contains `MockBlobBehaviour` type + `mockFetchBlob()` implementation
+- `_dev*` exports in the service file are injection points; only their `.dev.ts`
+  counterpart imports them
+- `src/types/global.d.ts` declares all `Window.__*` hook props
+- hooks: `__seekTo`, `__triggerTrackEnd`, `__triggerAudioError`, `__evictBlob`,
+  `__mockBlobFetch`, `__clearMockBlobFetch`, `__setBlobFetchTimeout`, `__fetchBlobBySha`
+
+**e2e helpers split**
+
+- `e2e/helpers/media.ts` - `makeWav()`, fixture loading, no `Page` dep, pure Node
+- `e2e/helpers/app.ts` - `resetAppState`, `createPlaylistViaUI`, `addSongs`,
+  `makePng`, `dropFiles`, `waitForApp`, `setPlaylistCover`
+- `e2e/helpers/hooks.ts` - typed `window.__*` wrappers + `MockBlobBehaviour` type
+  - `@mock` convention docs
+- `e2e/helpers/index.ts` - barrel re-export of all three
+- `e2e/helpers.ts` - 10-line re-export shim so existing `"./helpers.js"` imports
+  continue to work without changes
+
+**e2e: audio player + mocked p2p (§12d, §12e, §15d)**
+
+- `e2e/audio-player.spec.ts` (7 tests): autoplay-next, triggerTrackEnd, end-of-playlist
+  stopped state, real 2s fixture playthrough, error recovery, delayed blob state,
+  mock error state. two tests tagged `@mock`.
+- `e2e/p2p-states.spec.ts` (6 tests, all tagged `@mock`): pending during stall,
+  timeout→error, retry affordance, prefetch triggered on play, prefetch cancelled
+  on playlist switch, seek recalculation
+
+**playlist cover image reactive after reload**
+
+- `PlaylistEditPanel.tsx`: moved image URL loading from `onMount` to `createEffect`
+- root cause: after page reload, `docToPlaylistAsync` resolves `imageFilePath`
+  asynchronously from OPFS/Cache. `onMount` ran once before resolution and saw
+  `undefined`. `createEffect` re-runs whenever `props.playlist.imageFilePath`
+  becomes non-null.
+- lesson: `onMount` = "run once with initial prop value". `createEffect` = "run
+  whenever tracked signals change". when a prop may resolve asynchronously,
+  `createEffect` is almost always the right choice.
+
+---
+
+**dedup on import (§11b)**
+
+- `addSongToPlaylist` checks sha256 before writing; same-sha songs skip upsert
+- applies to both file-drop and zip re-import
+- e2e: `zip reimport dedup` test in `zip-bundle.spec.ts`
+
+**blob GC on playlist delete (§11d)**
+
+- `deletePlaylist` enumerates sha refs, runs `shaRefsExcluding(docId)`, removes
+  unreferenced blobs (best-effort, `Promise.allSettled`)
+
+---
+
+### zip download (§5b-c)
+
+- songs deduped by sha256 in zip; node_ids excluded
+- `e2e/zip-bundle.spec.ts`: download trigger, zip structure, reimport roundtrip,
+  standalone http server, audio playback, `--http` CLI mode, dedup test
+
+---
+
+### access control (§4a-b)
+
+- `list_playlists` + `blob_request` check `settings.mode` + `getAccessGrant`
+- `e2e/sharing-access.spec.ts`: mode toggle, default knock-first, persistence,
+  knock inbox empty state, browse-a-peer section
+
+---
+
+### state correctness (§10a-b)
+
+- `selectedPlaylistId` is the single writable signal; `selectedPlaylist` is a memo;
+  stale overwrites structurally impossible
+- `window.__processFiles` dev hook in `components/index.tsx` (DEV only)
+
+---
+
+### logging (§9)
+
+- `src/utils/log.ts`: trace < debug < info < warn < error
+- runtime: `localStorage.logLevel` / `localStorage.logFilter`
+- build-time: `VITE_LOG_LEVEL` + `VITE_LOG_FILTER`; vitest sets `VITE_LOG_LEVEL=error`
+
+---
+
+### e2e test files
+
+| file                              | tests | tags      | notes                                 |
+| --------------------------------- | ----- | --------- | ------------------------------------- |
+| `e2e/sharing.spec.ts`             | -     | @p2p      | two-browser, real iroh                |
+| `e2e/sharing-access.spec.ts`      | -     | -         | access control, single-browser        |
+| `e2e/share-link-autoplay.spec.ts` | -     | -         | synthetic share fragment              |
+| `e2e/all-playlists.spec.ts`       | 10    | -         | hamburger panel                       |
+| `e2e/song-cache-state.spec.ts`    | 17    | -         | blob cache states                     |
+| `e2e/zip-bundle.spec.ts`          | ~20   | -         | zip download + standalone roundtrip   |
+| `e2e/audio-player.spec.ts`        | 7     | 2x @mock  | playback + mock blob                  |
+| `e2e/p2p-states.spec.ts`          | 6     | all @mock | mocked p2p transport scenarios        |
+| `e2e/playlist-crud.spec.ts`       | 5     | -         | create, edit, cover image persistence |
+
+---
+
+## notes
+
+### e2e selectors and test patterns
+
+- `data-testid="song-duration"` - one per song row; also has `data-sha256` and
+  `data-download-state` attrs. always use this to select song row durations
+  (the playlist total-duration badge also shows time strings).
+- `data-testid="btn-play-playlist"` - AudioPlayer button;
+  `aria-pressed="true"/"false"` (string); `aria-busy` while fetching/buffering
+- `data-testid="now-playing-title"` - shows current song title (only when playing)
+- `data-testid="app-ready"` - app boot sentinel (visually hidden `<h1>`)
+- `data-testid="edit-panel"` - playlist edit panel root (for scoping child locators)
+- clicking song rows: if the action-buttons overlay intercepts pointer events
+  (visible on hover/play state), use `page.evaluate` / `dispatchEvent("click")`
+  rather than `.click()` or `{ force: true }` - force clicks hit the wrong target
+- `fetchBlobBySha(page, sha256)` programmatic retry (bypasses overlay entirely)
+
+### subagent dispatch notes
+
+tasks in "modularization: concrete next steps" are designed to be independently
+dispatched. when dispatching, provide:
+
+1. the task section from this doc as context
+2. the relevant source files to read first
+3. the constraint "all existing tests must pass after changes"
+
+tasks that touch `tomb/` require the tomb workspace context too:
+
+- `tomb/client-codegen/freqhole-api-client/` is the shared package directory
+- `tomb/client/spume/` is the spume frontend
+
+for linting tasks, the full list of errors from `eslint --max-warnings 0` is
+useful starting context so the subagent doesn't need to discover violations first.
+
+### general
+
+- iroh relay/nat is known flaky in two-browser tests: sometimes 8 min, sometimes
+  13s. not fixable in test code alone.
+- `fileProcessingService.ts` parses filename only (no ID3 tags). cover art via
+  `imageService.extractAlbumArt` (ID3v2 APIC parser).
+- `getBlobObjectURL` caches URLs internally; do not revoke them.
+- `PREFETCH_CONCURRENCY = 3`; `BLOB_FETCH_TIMEOUT_MS = 30_000` (let, configurable
+  via `_devSetBlobFetchTimeout`). timeout applies to both dev-override and real p2p paths.
+- `songReactivity.ts`: `triggerSpecificSongUpdate` is a workaround for `SongRow`
+  not subscribing directly to the doc handle. the proper fix is deriving from a
+  `playlistSongs()` signal - but this touches reactivity deeply, defer until
+  `@freqhole/solid` work begins.