@freqhole/playlistz 0.0.1

package/docs/TODO.md

@@ -0,0 +1,167 @@
+# TODO
+
+in rough prio
+
+## 0
+
+[x] so need to refactor the "standalone" mode a bit; so i want to use playlistz.js convention (as in <script src="playlistz.js"></script> in html) file for one or more playlists data, instead of embedding into .html file, then don't need to template the .html file...
+
+[x] some kind of interactive (and also script-able) cli mjs script to take a bunch of audio files + playlist metadata and generate a standalone playlistz.js, maybe also a .html and sw.js generator? then i could just build a freqhole-playlistz.js file. is there a way i could have the same freqhole-playlistz.js be used in a browser like <script type="module" src="freqhole-playlistz.js"></script> as well as in node like `node freqhole-playlistz.js --generate-html` or even start a lil' express static file server?
+
+[] freqhole could dispense takeout download linkz that generated playlist data.zip with this (package lib thing?)
+[] some kind of npm or github package lib thing, so prolly CI github action .yml filez to build + deploy npm package, some kind of cli tool, single .html + sw.js file
+
+## 1
+
+[x] need more immediate ui feedback for when drag-n-drop is loading playlist
+
+[x] play/pause needs some more work so it resumes position. song positions (e.g. the background fill on the song row) shouldn't disappear when pausing song, or skipping to a different track. when playing a track, start playback at last-left-off position, unless that position is >95% of the track time, then can restart at the beginning but don't clear the background position fill until the track starts over again at the beginning (or if the user manually seeks the track time). so play/pause of each song should track per-song playback state, and the global play/pause should track playing and pausing the current song (right now it just starts back at the beginning). there should be code that's doing this? please make sure to dig before adding new code. keep test coverage up.
+
+[x] this `<` `>` menu toggle is still not right =? could it be at the bottom of the page, after all the playlist songz? orrrr could it be only shown in the "modal" window view? so like edit buttonz on playlist will bring open a modal that's sized to the playlist size but include the `<` `>` menu toggle button then can show the sidebar stuff then! OH! the edit modalz could be in the sidebar content area! then there could be a `<` toggle button to current all-playlistz, search, + new playlist stuff!! yesss.
+
+i'd like to re-work the edit playlist + edit song modals and how this `<` `>` sidebar menu toggle works.
+
+so first, the edit playlist modal doesn't need to be a "modal", how i'd like it to work is by dropping out the song rows and then rendering a panel in the space where the song rows were that's the same content as the edit playlist modal. i'd like to animate the transitions here, so that the first, say 5 song rows drop out one by one, and then the animaton ramps up and clears them all out, so like one by one (in quick succession) each row falls straight down out of view. then the edit panel expands to fill in the space. when it's close, the reverse happens, panel shrinks down and song rows go back up.
+
+when a song edit modal opens, in a similar way, the selected song row stays and all the other song rows + playlist header either drops down (if after/below the current song) or goes up and out if above the current song, including the playlist header section, then the edit song panel fills into the now-open space. when exiting, the animation goes in reverse, so the panel shrinks down to close and the other rows come back in from above or below.
+
+right, so then it's only when one of these edit panels are open, that i want to show sidebar `<` `>` menu toggle button and sidebar contents. i guess also want to show the sidebar if there's 0 playlists.
+
+## 2
+
+[x] edit playlist form controlz + idb persistence for how background image filter is set
+[] does sw.js need more work?
+
+## 3
+
+[] i guess it could have a midden iroh wasm client...
+
+so this is a bigger ask: i'd like to introduce iroh p2p networking into playlistz. i'd like for it to be interoperable with the existing freqhole setup i've got already over in tomb/client/midden, and i think playlistz would also need to use the freqhole-api-client over in tomb/client-codegen/freqhole-api-client. the idea, for now is that playlistz can just use `file:../tomb/...` npm package ref for freqhole-api-client and midden (or we can just cp midden's dist output; i'll look into publishing these two packages at some point, maybe, for now just want to use file: path link). the playlistz data model will need some changes to fit better with freqhole's playlist schema, namely supportig multiple cover and song images (with one having a primary property), song image "waveform" types, playlist + song entity url linkz, and song lyrics.
+
+for the playlistz app interface, i want to add a new "share" icon button to the playlist, after the zip download icon button, that will open a share panel (similar to the edit playlist panel), that will let a user do an initial midden endpoint setup, so setup things like a name, avatar image, some settings to set if all playlists are public or if they require knock access requests.
+
+i'd like to start a new "freqhole-playlistz" ALPN that both freqhole and the playlistz web app can use to communicate. spume can track and generate base64 share links that contain node ids and some other helpful info to display a share link, e.g. https://spume.freqhole.net/#?share=eyJpIjoiOTRjZGZlMjhjMWE1MDJhOCIsImsiOiJwbGF5bGlzdCIsInMiOnsibiI6IjBkMGRlNTQwY2E1NWMzMzdkMzZhNmEwN2M3N2I1NGMwYTJhMjM0NDgyOWNiMzE0MDczY2U1YTA5NGVkZGQyNDAifSwidCI6ImRhbmNlMnRoaXMiLCJ2IjoxfQ so i'd like playlistz app to have a similar way to share. the idea would be playlistz app can read freqhole playlistz that are shared with it (and the user has proper access and the ability to send knock requests). otherwise the playlistz web app can share it's playlistz with other playlistz app users (e.g. without freqhole) so either anyone (if public) or require an access knock request (want to borrow as much from freqhole's knock stuff as possible here). the browser node will need to do like accept_bi on the iroh endpoint so it can process incoming requests from other nodes.
+
+while i don't plan for this playlistz app to run on the same domain as spume, i want it to be able to read spume's indexed db, opfs, and iroh secret key if it is. so ideally we'd be able to share a lot of the same indexed db logic as well. in some sensible way, so that tomb/\* code doesn't have to know about playlistz app, so maybe some this has to come out of freqhole-api-client, or just have the same indexed and opfs key and schemas so it will interop-- gonna need to find a delicate balance here.
+
+so, then, first i'd like you to dig around the tomb/ and playlistz/ code to get a better sense of how this will be implemented in these codebases and then start a new .md file in playlistz/docs/ with a plan for implementing all this stuff and track progress as we work thru and complete all the work, keep open questions out of the plan doc and let's just have a conversation about anything that comes up. ideally you would include as much technical details as possible in the plan doc, and then dispatch claude sonnet 4.6 subagents for as much work here as possible. this is a lot of "feature" but also a lot of the code needed to do this has pretty much been worked out in tomb/, so a big part of this is will be digging around the code there and finding good ways to share it in playlistz/ app, which might mean some refactoring or just re-implementing the same patterns in playlistz/ if it's too much of a chore to refactor and share (ideally i'd think a good amount of code from tomb could be shared, atleast in terms of biz logic, of course playlistz will have it's own presentational aesthetic and frontend ui implementation)
+
+FREQHOLE_ALPN.to_vec(),
+AUTOMERGE_ALPN.to_vec(),
+FRIENDZ_ALPN.to_vec(),
+ADMIN_ALPN.to_vec(),
+EVENTS_ALPN.to_vec(),
+iroh_blobs::ALPN.to_vec(),
+
+                in tomb/client/midden/src/lib.rs
+
+# THU, JUN 11, 2026
+
+so i guess if we could do webauthn-rs passkey stuff (in a https:// web browser) then it could be perhaps possible for two nodes to validate a user? like if the charnel tauri app and rathole cli could be, more or less, a hub server, where users can register their passkey for that user, then with passkey validation, they could write a new peer node id device for access? like a https://spume.freqhole.net/?query_auth_node_id=abcdef123456..&return_to_node_id=0202aaabbbdcba.. could open, init a new iroh endpoint that calls the query auth node id and validates passkey, then inserts a new allowed peer node for self, and then sends some kind of success/fail token back to the return_to node?
+
+[] double click playlist in sidebar to start playing it.
+[] move share modal from sidebar to main page content, try to emulate the edit playlist layout, so will need to animate out the current playlist details and then show like:
+
+```
+[share modal, where the playlist header is, with transparent background so current playlist background image comes thru.  x (close icon button in top right)]
+
+[$(playlist img) $(playlisttitle) `<` `>` buttons to show share detail panel for stuff related to playlist, currently this is only the share link text input + copy to clipboard button; will include other stuff here in the near future]
+```
+
+so then also move the share button from the sidebar nav, back into the playlist detail action buttons: after the edit button, before the download button.
+
+---
+
+okay, so i'm hoping you can help me work on the playlistz/ code here in this workspace. what i'm hoping to do is re-work the layout and navigation to be a bit more consistent. so currently, the main layout for a playlist is like:
+
+a playlist header section
+
+```
+PLAYLIST_NAME (editable div)             |       |
+PLAYLIST_DESCRIPTION (also editable div) | cover |
+                 song count + total time |  img  |
+PLAY/PAUSE BUTTON       [ACTION BUTTONS]
+```
+
+and then under that song rows. when the edit mode is toggled, the header stays in place, and the song rows section switched out to the edit panel and the edit button in the action buttons section of the header gets a magenta border style. this is working great and how i'd like it to work.
+
+however, then, the "all playlists" view and action button, and the share view and action button don't quite work like this.
+
+the share view should be easy, we just need to keep the playlist header section in place, like the edit mode does it.
+
+and then a similar thing for the all playlists view, the currently selected playlist header section then just becomes a row w/ sticky top + bottom position. and then the other playlists are added as rows also with the same header section as row. currently the row view here for all playlists is much different, which i want to change, and re-use the same playlist header section for row view as much as possible. it will probably need some variation when in row-form. having a dedicated row for adding a playlist is great, and i'd like to keep that, it should also be sticky bottom position (and play well with the other active playlist sticky row).
+
+then the all playlists view and share view don't need `x` close or headers shown.
+
+so thoughts about this? i really hope it's clear what i'm asking here, we'll probably need to refactor the edit playlist + song row container into a more generic app layout structure of files and components and hooks etc. needed to support this. do you have any questions for me about this work?
+
+---
+
+some issues now with the narrow mobile views? i think the playlist header
+
+71144
+
+---
+
+some more things:
+
+there should be a search query input somewhere, i think on the `new playlist` row in all playlists view? it needs so many playlists to show, let's remove that, and show a search input all the time. the search input can also take share links, then we can remove the `open a share link` and `browse a peer's playlistz` in the share panel (need to make it so it can figure out if a knock is needed)-- the search bar should be able to detect a node_id or a share link and handle accordingly.
+
+for now, i want to hide the `node id:` display in the share panel.
+
+also when there's no knocks, we don't need to show any empty state, like:
+
+```
+knock inbox
+no pending knockz
+```
+
+when browsing a users playlists, it should work the same way all playlists does in addition to a new field, after the date last modified in the playlists rows, that includes the display name of the remote user (and possibly an avatar, can we work this into the iroh sharing? might be more involved.); remember we need to keep the currently selected playlist visible in this all playlists view.
+
+i also want to work more on a "collaborative" playlist sharing setting, where other users can do all the automerge syncing stuff so all the peers that are allowed to edit the playlist, sync together. otherwise, if not a collaborative playlist (or a peer that isn't allowed to collaborate in editing the playlist) should not send their automerge docs changes back. however, i do want to be able to let the peer keep getting playlist edits. it would be nice to have some ui feedback for when a playlist is in this "subscribed" mode and will get updates, i suppose then what to do if the user makes local changes to a subscribed playlist and then new changes come in? i feel like we should just let automerge sync, in the even there's any conflicts, it'd be great to show something in the share edit panel that let's the user either: 1. accept all the incoming changes (their local changes will get overwritten) or 2. add the remote playlist as a new playlist, and then unsubscribe their local copy from the remote automerge document since it's now a standalone fork. every playlist is gonna need it's own list of peer nodes that can collaborate.
+
+i think also, each playlist is gonna need to have it's sharing mode explicitly set and started, so by default a playlist should not be shared until the user explicity chooses something from the "who can browse my playlistz?" options, which would be `public` (anyone can read and sync updates, but not make edits), knock first. and then i'm not quite sure where the new "collaborative" toggle would come in, or how it would work. maybe it could work like this:
+
+so when a playlist creator shares a playlist with another user, say it's "knock first" setting, they paste the link into the search input, or just click it, then they go thru the knock flow (oh by the way the knock requests should also include a short free-form message text with the label "say who you are and mention something only the admin would know (but no passwords or secrets!)"), then when the playlist is added the UI is in, like read-only mode, so no new songs can get added, the name or description can't be edited, no new images or drag and drop reordering. in the edit menu, we can add two buttons, one that will turn the playlist into just a local fork copy that's basically like a user's own playlist and the other is a "collaborate" button that then will issue another knock access request to be a collaborator.
+
+so then in the playlist creator's share panel, need to be able to accept both kinds of knock requests, and manage who's collaborators.
+
+for now i want to keep the global share endpoint on/off toggle and display name, but i'd like to move the display name to the top of the share panel, and have the name just be a short text (like a pill badge) and then it can be clicked to open a text-input that can change the display name and then `x` to close (will auto set the displayname on key change events so no save button needed), perhaps this is where a user could set an avatar image? see skein/ for examples on how i handle profile avatars?
+
+---
+
+remote "playlist deleted" toast
+
+✗registration failed: failed to start registration
+
+6d8bdc333c74279db9bb090d9f2d61c0ec7b79e1da223e4accc4435adb1e6ae7
+2914-whoosh-snail-koala-yodel
+
+https://www.youtube.com/watch?v=HJgjZ6vbHI0&list=RDHJgjZ6vbHI0&start_radio=1
+
+if there's precheck config, add review step to add music fetch from url flow so user can confirm what yt-dlp will fetch
+
+route passkeys over p2p! browser users can use passkey to auth with a remote (in addition to knock access requests and invite codes). also can link out to spume.freqhole.net so charnel app users (desktop or android apps) so users can use browser for passkey.
+
+---
+
+[x] update freqhole.net docs for recent features
+
+[x] yank ci job that tries to update .mdx file updated at, just have the single script that reads git commits (force?) update them all in one go, i can just run this locally on my machine where i have the git history (unlike ci).
+
+[x] after deleting a playlist, need to route to a different playlist (or show empty state if the last playlist was deleted).
+
+[x] is it possible to register a new passkey with a web browser client that already has access to a remote? i guess i just need to test this more.
+
+[x] users should be able to generate their own account-link invite codes. should be set to pretty quick expire time (say maybe around 30mins or 1hr). users should also be able to update their own usernames (but not to a username that's already in use in the db, so need friendly message for this case: "ohey, that handle is already taken; if you ask the admin nicely, they might be able to help."). perhaps there's a user profile view in the settings, linked where the "manage passkeys" is, so remove the "manage passkeys" link there and move the link to the username + role (after the "singed in as") and then add a new settings view, we can probably just add the passkey stuff from `#/settings/remotes/$(remote_name)/passkeys` to this new user profile view that can do all this stuff?
+
+[ ] sync all music from library to another remote (i.e. push all music files, images, and most all metadata to a remote, de-dupe by blake3 or sha256 hashes). where in the ui to add this? maybe it's a rathole thing? would be nice in spume so collections built up in web browser can get synced to a more stable remote. >----
+------> OR MAYBE: like "federation" so two freqhole instances can share up to all the sqlite (or indexed db) db data? but otherwise selectively pick & choose: like share these users, passkeys, or these tags, or just user favorites and playlists, etc etc etc.
+
+[x] publish freqhole-api-client and midden to npm so it's easier to use in playlistz. so need to setup @freqhole npm org package namespace and update package names, and then publish once from local machine, then add ci to publish new packages on tag (avoid draft releases). >----> NEED TO PUBLISH ONCE FROM LOCALHOST:
+
+[ ] playlistz <-> freqhole playlist sync
+
+[ ] has the time come to improve the last_seen_at user peer nodes? would make gossip and updating peerz when playlist changes a bit easier
+
+[ ] graph viz has bugz where sometimes a selected artist causes the graph to collapse and then the selected artist node disappears and a bunch of hub nodes are rendered but it's, like real wonky.

package/docs/bundle-embedding-plan.md

@@ -0,0 +1,134 @@
+# bundle embedding plan
+
+the zip bundle needs to include `freqhole-playlistz.js` and `freqhole-playlistz-cli.mjs`
+so that the standalone `index.html` is fully self-contained (no network required).
+
+## current approach (problems)
+
+`buildPlaylistZip` fetches the bundle at zip-build time:
+
+```ts
+fetch(`${window.location.origin}/freqhole-playlistz.js`);
+```
+
+problems:
+
+- in vite dev mode, `origin/freqhole-playlistz.js` may not be served unless
+  `npm run build` has been run and the dev server is set to serve `dist/`
+- in spume/charnel (tauri), the origin is `tauri://localhost` and the asset
+  may or may not be registered depending on tauri's asset protocol config
+- the caller must pass `appBundleUrl` to override; the fallback is fragile
+- the cli build path (`freqhole-playlistz-cli.mjs`) has the same fragility
+
+## option A: seed zip baked into the package (recommended)
+
+as part of the playlistz package build (`npm run build`), generate a
+`dist/bundle-seed.zip` that contains only the two js files:
+
+```
+dist/bundle-seed.zip
+  freqhole-playlistz.js
+  freqhole-playlistz-cli.mjs
+```
+
+`buildPlaylistZip` opens this seed zip and adds playlist content (audio, images,
+html, playlistz.js) into it, rather than starting from scratch. this means:
+
+- the bundle is always available as a package asset (no network request)
+- callers pass nothing extra - it just works
+- the zip builder imports the seed as a base64-encoded or raw buffer included
+  in the package (via `?url` or `?raw` vite import, or `fs.readFileSync` in node)
+
+### implementation steps
+
+1. add a `build:seed-zip` npm script that runs after `build:standalone`:
+
+   ```
+   node scripts/build-seed-zip.mjs
+   ```
+
+   reads `dist/freqhole-playlistz.js` + `dist/freqhole-playlistz-cli.mjs`,
+   builds a zip, writes to `dist/bundle-seed.zip`
+
+2. in `zipBuilder.ts`, import the seed zip:
+
+   ```ts
+   // vite: import as url so it can be fetched from the package
+   import seedZipUrl from "../../dist/bundle-seed.zip?url";
+   // or in node/cli context: read via fs
+   ```
+
+   then `JSZip.loadAsync(await fetch(seedZipUrl).then(r => r.arrayBuffer()))` to
+   get a base zip, then add content into it.
+
+3. the cli path can read the seed zip via `fs.readFileSync` relative to the
+   package root - no network request needed.
+
+### dev-mode handling
+
+in vite dev mode, `?url` imports still work (vite serves them as assets). the
+seed zip is static content, so vite just serves the file. **callers no longer
+need to pass `appBundleUrl`** at all.
+
+---
+
+## option B: fetch from cdn / freqhole.net
+
+provide fallback urls for npm cdn and a self-hosted mirror:
+
+```ts
+const BUNDLE_URLS = [
+  `${window.location.origin}/freqhole-playlistz.js`, // local server (preferred)
+  "https://cdn.freqhole.net/playlistz/0.0.1/freqhole-playlistz.js",
+  "https://unpkg.com/@freqhole/playlistz@0.0.1/dist/freqhole-playlistz.js",
+  "https://cdn.jsdelivr.net/npm/@freqhole/playlistz@0.0.1/dist/freqhole-playlistz.js",
+];
+```
+
+problems with option B:
+
+- requires publishing the package to npm (or maintaining a cdn)
+- requires a network request at zip-build time (breaks offline use)
+- version pinning is manual - easy to get stale bundles
+- does not solve the vite dev mode problem
+
+option B is useful as a **last-resort fallback** (e.g. if the seed zip is
+somehow missing from the package), not as the primary mechanism.
+
+---
+
+## option C: embed the bundle as a base64 string at build time
+
+embed the bundle bytes directly into the js bundle via a vite/rollup plugin or
+a `?raw` import followed by btoa. this avoids a separate zip asset.
+
+problems:
+
+- doubles the package size (bundle is ~8MB; base64 is ~11MB)
+- the embedded bundle cannot be updated without rebuilding the package
+- not practical for the cli path
+
+---
+
+## recommended approach
+
+**primary**: option A (seed zip baked into the package).
+
+**fallback order when seed zip is unavailable**:
+
+1. try `${window.location.origin}/freqhole-playlistz.js` (local server)
+2. warn and omit the bundle from the zip (zip still works for playing
+   on an http server that serves the bundle separately)
+
+---
+
+## vite dev mode notes
+
+in dev mode (`npm run dev`), vite does not serve `dist/`. to test the zip
+bundle download in dev mode, either:
+
+- run `npm run build:standalone` first (generates `dist/freqhole-playlistz.js`)
+  and configure vite to serve `dist/` as a static folder
+- or use option A's seed zip which vite serves as a static asset import
+
+this is tracked as a known limitation until option A is implemented.

package/docs/standalone-refactor.md

@@ -0,0 +1,184 @@
+# standalone refactor plan
+
+## goal
+
+refactor the standalone build from a single self-contained `freqhole-playlistz.html` (with all js/css inlined) into:
+
+- `freqhole-playlistz.js` - dual-use ESM bundle: registers web component in browser, runs as CLI in Node
+- `playlistz.js` - data file (generated by cli or freqhole takeout); sets `window.__PLAYLISTZ__`
+- `index.html` - static, minimal, generated once by cli; never needs to be re-templated
+- `sw.js` - static service worker, generated by cli
+
+the `index.html` becomes truly static - only `playlistz.js` and `data/` change when playlist content changes.
+
+`playlistz.js` is generated by two different paths that share the same template functions:
+
+- **in-app download**: the existing "download zip" button generates `playlistz.js` + `index.html` + `sw.js` and bundles them into a zip
+- **cli**: `npx freqhole-playlistz --init` / `--generate-data` writes the same files to disk
+
+both paths import the shared template functions from `src/utils/standaloneTemplates.ts`.
+
+## output directory layout
+
+```
+output/
+  freqhole-playlistz.js   # app bundle (from npm or built locally)
+  playlistz.js            # playlist data (generated by cli)
+  index.html              # static shell (generated by cli)
+  sw.js                   # service worker (generated by cli)
+  data/
+    song1.mp3
+    song2.mp3
+    playlist-cover.jpg
+    song1-cover.jpg
+```
+
+## freqhole-playlistz.js structure
+
+the built file wraps everything in environment guards:
+
+```js
+// css injector + solid web component bundle, guarded for browser
+const isBrowser =
+  typeof window !== "undefined" && typeof customElements !== "undefined";
+if (isBrowser) {
+  // inject compiled css into document.head at runtime
+  (() => {
+    const s = document.createElement("style");
+    s.textContent = "...";
+    document.head.appendChild(s);
+  })();
+  // solid web component registration
+  // ...vite-built bundle...
+}
+
+// node cli entrypoint
+const isNode = typeof process !== "undefined" && process.versions?.node;
+if (isNode) {
+  const { fileURLToPath } = await import("node:url");
+  const isMain = process.argv[1] === fileURLToPath(import.meta.url);
+  if (isMain) {
+    // cli dispatch
+  }
+}
+```
+
+format must be ESM (`format: 'es'`) to support `import.meta.url` and top-level `await` in both environments.
+
+## playlistz.js data format
+
+supports one or more playlists:
+
+```js
+window.__PLAYLISTZ__ = [
+  {
+    playlist: { id, title, description, rev, imageExtension, imageMimeType, safeFilename },
+    songs: [ { id, title, artist, album, duration, originalFilename, fileSize, sha, ... }, ... ]
+  },
+  // ...more playlists
+];
+```
+
+the structure is validated with Zod schemas defined in `src/utils/standaloneTemplates.ts`. this is used:
+
+- in `standaloneService.ts` when the web component reads `window.__PLAYLISTZ__` at init
+- in the cli when reading a user-provided `playlistz.js` or generating one from audio files
+- in the download zip service when assembling the export bundle
+
+the web component checks `window.__PLAYLISTZ__` on init and calls `initializeStandalonePlaylist()` for each entry. `standaloneService.ts` already handles single-playlist init - needs to be extended to loop over multiple entries.
+
+## shared template utilities (`src/utils/standaloneTemplates.ts`)
+
+a new file that both the browser app and the Node cli can import. browser-compatible (no Node-only APIs). exports:
+
+- `FreqholePlaylistSchema` - Zod schema for a single `{ playlist, songs }` entry (replaces raw `StandaloneData` interface in `standaloneService.ts`)
+- `FreqholePlaylistzSchema` - Zod schema for `window.__PLAYLISTZ__`, i.e. `z.array(FreqholePlaylistSchema)`
+- `generatePlaylistzJs(playlists)` - serializes the entries array to `window.__PLAYLISTZ__ = [...];
+` string
+- `generateIndexHtml()` - returns the minimal static `index.html` as a string; template is read from `src/templates/index.html` at Vite build time and inlined as a string constant
+- `generateSwJs()` - returns `sw.js` content as a string; `public/sw.js` is read at Vite build time and inlined as a string constant
+
+both `generateIndexHtml()` and `generateSwJs()` just return pre-baked string constants - no runtime file I/O in browser or Node.
+
+the download zip service (`playlistDownloadService.ts`) already generates the zip bundle - it will call these functions instead of its own templating. the cli calls the same functions and writes files to disk.
+
+## changes required
+
+### phase 1 - build refactor (`build-component.js`)
+
+- [x] output format changed to `'es'` for vite rollup, then post-processed to IIFE by esbuild
+- [x] css minified via esbuild `transform` with `loader: 'css'`, newlines stripped, injected as a string constant prepended to the browser bundle
+- [x] css asset removed from bundle output (no separate `.css` file)
+- [x] emit `freqhole-playlistz.js` instead of inlining js into html
+- [x] browser bundle wrapped in `if (isBrowser) { ... }` shell
+- [x] `if (isNode) { ... }` cli shell appended (stub for phase 6)
+- [x] emit static `index.html` from `generateIndexHtml()`
+- [x] emit `sw.js` from `readServiceWorker()`
+- [x] removed `generateStandaloneHtml()` from `build-component.js`
+- [x] esbuild `transform` post-pass: minifies js + css together, produces `.map` sourcemap file, outputs IIFE format (no `type="module"` needed, works on `file://` urls)
+- [x] `index.html` uses plain `<script src>` (not `type="module"`) for `file://` compatibility
+
+### phase 2 - shared template utilities (`src/utils/standaloneTemplates.ts`)
+
+- [x] `zod` added as a dependency
+- [x] `FreqholePlaylistSchema` and `FreqholePlaylistzSchema` defined; inferred types exported
+- [x] `generatePlaylistzJs(playlists)` implemented
+- [x] `generateIndexHtml()` implemented (plain `<script src>`, no `type="module"`)
+- [x] `generateSwJs()` implemented via `?raw` import of `public/sw.js`
+- [x] unit tests for all three generators and schema parse/reject cases
+
+### phase 3 - web component init (`web-component.tsx`, `components/index.tsx`)
+
+- [x] `connectedCallback` checks `window.__PLAYLISTZ__`, parses with `FreqholePlaylistzSchema`, calls `initializeStandalonePlaylist()` for each entry
+- [x] `window.STANDALONE_MODE` / `window.DEFERRED_PLAYLIST_DATA` mechanism removed
+- [x] `global.d.ts` updated with `__PLAYLISTZ__` type declaration
+
+### phase 4 - multi-playlist standalone support (`standaloneService.ts`)
+
+- [x] raw interfaces replaced with Zod-inferred types from `standaloneTemplates.ts`; `StandaloneData` kept as a backwards-compat alias
+- [x] `initializeAllStandalonePlaylists(playlists)` added as array wrapper
+- [x] sha-based smart update logic unchanged
+- [x] tests updated with multi-playlist init case
+
+### phase 5 - download zip refactor (`playlistDownloadService.ts`)
+
+- [x] `generatePlaylistzJs()`, `generateIndexHtml()`, `generateSwJs()` used instead of inline templating
+- [x] zip layout: `playlistz.js` + `index.html` + `sw.js` in root, audio/image files in `data/`; `freqhole-playlistz.js` not included
+- [x] no more `fetch('./sw.js')` network call during zip generation
+- [x] download service tests updated
+
+### phase 6 - cli (`dist/freqhole-playlistz-cli.mjs`)
+
+- [x] two-file output: `freqhole-playlistz.js` (browser IIFE, no Node globals) + `freqhole-playlistz-cli.mjs` (Node ESM, no browser globals)
+- [x] `--help` - usage
+- [x] `--http [dir]` - static file server with range request support; defaults to `./data`; respects `PORT` env var
+- [x] `--check [file]` - validates `playlistz.js` (defaults to `./playlistz.js`); field-level error messages; checks audio + image files exist on disk; skips `http://`/`https://` urls
+- [x] `--init <dir>` - writes `index.html` + `sw.js` (baked in at build time) to target dir
+- [x] `--generate-data <audio-dir>` - reads audio files, generates `playlistz.js` via `generatePlaylistzJs()`
+
+cli source lives in `src/cli/` with modules: `index.ts` (dispatch), `http.ts` (server), `check.ts` (validator), `init.ts` (file writer).
+
+### phase 7 - npm package setup
+
+- [x] add `"bin": { "freqhole-playlistz": "./dist/freqhole-playlistz.js" }` to `package.json`
+- [x] add `"type": "module"` to `package.json` if not already set
+- [x] verify `npx freqhole-playlistz --help` works from a clean install
+
+## testing considerations
+
+- existing `standaloneService.test.ts` covers single-playlist init - extend with multi-playlist cases
+- `standaloneTemplates.ts`: unit tests for all three generators and schema parse/reject cases
+- new unit tests for cli arg parsing and file generation functions
+- the http range request server should have tests for partial content responses
+- `web-component.tsx` init path needs tests for `window.__PLAYLISTZ__` detection
+- `playlistDownloadService.ts`: verify zip output contains correct files with correct content
+
+## progress
+
+- [x] phase 1 - build refactor
+- [x] phase 2 - shared template utilities + zod schemas
+- [x] phase 3 - web component init
+- [x] phase 4 - multi-playlist standalone support
+- [x] phase 5 - download zip refactor
+- [x] phase 6 - cli (`--http`, `--check`, `--init`)
+- [x] phase 7 - npm package setup