@freqhole/playlistz 0.0.1

package/.changeset/config.json

@@ -0,0 +1,11 @@
+{
+    "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
+    "changelog": "@changesets/cli/changelog",
+    "commit": false,
+    "fixed": [],
+    "linked": [],
+    "access": "public",
+    "baseBranch": "main",
+    "updateInternalDependencies": "patch",
+    "ignore": []
+}

package/.changeset/nice-wolves-thank.md

@@ -0,0 +1,5 @@
+---
+"@freqhole/playlistz": patch
+---
+
+zomg, hello world! listen to more playlistz! 💖

package/.freqhole-versions.json

@@ -0,0 +1,4 @@
+{
+    "@freqhole/api-client": "0.1.31",
+    "@freqhole/midden": "0.1.31"
+}

package/.github/copilot-instructions.md

@@ -0,0 +1,201 @@
+# freqhole-playlistz Development Guide
+
+## Project Overview
+
+freqhole-playlistz is a music playlist management tool built on top of the main freqhole project. It provides a standalone web interface for creating, editing, and sharing playlists.
+
+## Code Style
+
+### Lowercase Prose Preference
+
+Write comments, documentation, and user-facing messages in lowercase conversational style.
+
+**Keep uppercase for:**
+
+- Acronyms: API, HTTP, JSON, SQL, CRUD, REST, CLI
+- Proper nouns: Rust, TypeScript, GitHub, SQLite, PostgreSQL
+- Code identifiers: function names, type names, constants
+- Special markers: TODO, FIXME, NOTE, WARNING
+
+**Use lowercase for:**
+
+- Regular comments explaining logic
+- Documentation/docstrings
+- Error messages and user-facing strings
+- Log messages
+
+**Examples:**
+
+```rust
+// ✅ GOOD
+// extract album metadata from file tags
+let metadata = parse_tags(&file)?;
+
+return Err(GrimoireError::NotFound("playlist not found".to_string()));
+
+// TODO: add support for batch operations
+```
+
+```rust
+// ❌ AVOID
+// Extract Album Metadata From File Tags
+let metadata = parse_tags(&file)?;
+
+return Err(GrimoireError::NotFound("Playlist Not Found".to_string()));
+
+// Todo: Add Support For Batch Operations
+```
+
+### No Emojis in Code
+
+Avoid emojis in comments, error messages, or any code. Use them only in markdown documentation if appropriate.
+
+## Conventions
+
+- **Naming**: Use `snake_case` for Rust and TypeScript (tho `camelCase` is used)
+- **Documentation**: AI-generated docs live in `docs/`, with `docs/INDEX.md` as the entry point
+
+## E2E Testing Conventions
+
+### Selectors - prefer `data-testid`
+
+Use `data-testid` attributes as the primary selector for interactive elements and structural containers. This decouples tests from copy, tooltips, and class names.
+
+**Add `data-testid` to:**
+
+- Icon-only buttons with no visible text (hamburger, edit, share, close, remove)
+- Panel/container roots used for scoping child locators
+- App-state sentinels (e.g. the visually-hidden `<h1>` that signals the app has loaded)
+
+**Naming scheme:**
+
+| Type              | Pattern               | Examples                                                       |
+| ----------------- | --------------------- | -------------------------------------------------------------- |
+| panels / drawers  | `[name]-panel`        | `all-playlists-panel`, `share-panel`, `edit-panel`             |
+| icon buttons      | `btn-[action]`        | `btn-edit-playlist`, `btn-share-playlist`, `btn-all-playlists` |
+| close buttons     | `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`                             |
+| content cells     | `[component]-[field]` | `song-duration`, `song-count`                                  |
+| app sentinel      | `app-ready`           | signals initial load is done                                   |
+
+**When `getByText` / `getByRole` is still fine:**
+
+- Asserting that specific _content_ is visible: `expect(page.getByText("song-00")).toBeVisible()`
+
+**Always use `data-testid` for:**
+
+- Buttons (even ones with visible text labels) - copy changes; testids don't
+- Form inputs - use testid, not placeholder text
+
+**Avoid:**
+
+- `getByTitle(...)` to click or wait on elements - `title` is a tooltip for UX, not a test hook; it can collide when shared and changes with UI state
+- `.first()` on a click target - this means the selector is ambiguous; fix it with a scoped container or a testid instead
+- `page.getByRole("heading", { name: "playlistz" })` as the app-ready sentinel - use `getByTestId("app-ready")`
+
+### ARIA attributes for state
+
+Use ARIA attributes to express interactive state on elements. This is good accessibility practice and produces stable, semantic selectors in tests - no asserting on border colors, class names, or theme tokens to detect selected/active state.
+
+**Preferred attributes and when to use them:**
+
+| Attribute       | Element                         | When                                                      |
+| --------------- | ------------------------------- | --------------------------------------------------------- |
+| `aria-pressed`  | toggle buttons                  | button is in an "on" state (e.g. mode active, panel open) |
+| `aria-selected` | tab-like buttons, playlist rows | item is the current selection                             |
+| `aria-current`  | nav-style items                 | the currently active page/view/step                       |
+| `aria-expanded` | buttons that open panels        | panel is open                                             |
+| `aria-checked`  | custom checkboxes / toggles     | item is checked                                           |
+| `aria-busy`     | containers loading data         | async operation in progress                               |
+| `aria-disabled` | buttons that are disabled       | disabled state (use alongside `disabled` attr)            |
+
+**Examples in source:**
+
+```tsx
+// mode toggle button - aria-pressed reflects active state
+<button
+  data-testid="btn-mode-public"
+  aria-pressed={settings().mode === "public"}
+  onClick={() => void handleSaveSettings({ mode: "public" })}
+>
+  anyone (public)
+</button>
+
+// hamburger that opens a panel - aria-expanded reflects open state
+<button
+  data-testid="btn-all-playlists"
+  aria-expanded={showAllPlaylists()}
+>...</button>
+```
+
+**Examples in tests - assert state without touching styles:**
+
+```ts
+// good: semantic, stable
+await expect(page.getByTestId("btn-mode-public")).toHaveAttribute(
+  "aria-pressed",
+  "true"
+);
+await expect(page.getByTestId("btn-all-playlists")).toHaveAttribute(
+  "aria-expanded",
+  "true"
+);
+
+// bad: couples the test to the current theme/design
+await expect(page.getByTestId("btn-mode-public")).toHaveClass(
+  /border-magenta-500/
+);
+```
+
+**Avoid:**
+
+- Asserting on CSS classes or inline styles to detect active/selected state
+- Using `aria-label` as a test hook when a `data-testid` would be cleaner (aria-label is for screen reader copy, which can change)
+
+### Logging for E2E debugging
+
+Use the `log` utility (`src/utils/log.ts`) - never raw `console.log` in source files.
+
+**Levels** (lowest to highest): `trace` < `debug` < `info` < `warn` < `error`
+
+- `trace` - call-by-call service internals (off by default, even in dev)
+- `debug` - normal dev noise (on in dev, off in prod)
+- `warn` / `error` - always on
+
+**Tags** use dotted namespaces: `"automerge.repo"`, `"playlist.sync"`, `"idb.docindex"`.
+
+To turn on trace logging for a specific area during e2e debugging, set `localStorage` before reload:
+
+```ts
+// in browser devtools or a page.evaluate():
+localStorage.setItem("logLevel", "trace");
+localStorage.setItem("logFilter", "automerge.repo,playlist.doc");
+```
+
+Or via env at test time:
+
+```
+VITE_LOG_LEVEL=trace VITE_LOG_FILTER=playlist npm run test:e2e
+```
+
+Keep `console.log` / `console.warn` out of committed source - use `log.trace` for traces you want to keep around but silent by default.
+
+### Timeouts
+
+Lean on the global Playwright timeouts configured in `config/playwright.config.ts`:
+
+- `timeout` - per-test timeout (default 30s; slow tests call `test.setTimeout()`)
+- `actionTimeout` - single interaction (click, fill, etc.)
+- `navigationTimeout` - `goto` / `waitForURL`
+- `expect.timeout` - default assertion timeout for `expect(...).toBeVisible()` etc.
+
+**Only add inline `{ timeout: N }` when:**
+
+- The wait is genuinely longer than the global default (e.g. waiting 15s for IDB file processing to complete)
+- The wait is genuinely shorter than the global default and you want a faster failure signal (e.g. `{ timeout: 1000 }` on a "must not be visible" assertion)
+
+**Avoid:**
+
+- Duplicating the global default: `{ timeout: 5000 }` when the global expect timeout is already 5000
+- Sprinkling `waitForTimeout(300)` as a "let things settle" patch - prefer waiting for a specific element state instead
+- Overly generous timeouts that mask real bugs (a test that "passes" in 28s is hiding something)

package/.github/workflows/changesets.yml

@@ -0,0 +1,50 @@
+# on every push to main, run the changesets action:
+#   - changesets pending  -> open/update the "Version Packages" PR on
+#     changeset-release/main (runs `npm run version` = changeset version).
+#   - no changesets pending (version PR just merged + tag pushed) ->
+#     npm-publish.yml handles the actual registry publish on the tag event.
+name: changesets
+
+on:
+  push:
+    branches: [main]
+
+concurrency:
+  group: changesets-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  version:
+    name: open / update version PR
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: install deps
+        run: npm ci
+
+      - name: configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: changesets - open/update version PR
+        uses: changesets/action@v1
+        with:
+          version: npm run version
+          # no publish here - npm-publish.yml handles it on the version tag
+          commit: "chore: version packages"
+          title: "chore: version packages"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,124 @@
+# publish @freqhole/playlistz to npm when a version tag is pushed.
+# the version tag is created by the "Version Packages" PR merge
+# (changesets/action creates it via the version PR).
+#
+# after publishing, opens a PR in tomb/ to bump @freqhole/playlistz
+# to the new version so consumers stay up-to-date.
+name: npm publish
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    name: publish @freqhole/playlistz
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          registry-url: "https://registry.npmjs.org"
+
+      - name: install deps
+        run: npm ci
+
+      - name: build
+        run: npm run build
+
+      - name: verify package version matches tag
+        if: github.ref_type == 'tag'
+        run: |
+          PKG_VERSION=$(node -p "require('./package.json').version")
+          TAG_VERSION=${GITHUB_REF_NAME#v}
+          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
+            echo "package version $PKG_VERSION does not match tag $TAG_VERSION"
+            exit 1
+          fi
+
+      - name: skip if already published
+        id: exists
+        run: |
+          PKG_NAME=$(node -p "require('./package.json').name")
+          PKG_VERSION=$(node -p "require('./package.json').version")
+          if npm view "$PKG_NAME@$PKG_VERSION" version >/dev/null 2>&1; then
+            echo "published=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "published=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: publish
+        if: steps.exists.outputs.published == 'false'
+        run: npm publish --access public --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  # ---- bump @freqhole/playlistz in tomb/ ----
+  bump-tomb:
+    name: bump @freqhole/playlistz in tomb
+    needs: publish
+    runs-on: ubuntu-24.04
+    steps:
+      - name: checkout tomb
+        uses: actions/checkout@v4
+        with:
+          repository: freqhole/tomb
+          token: ${{ secrets.TOMB_PAT }}
+          fetch-depth: 1
+
+      - name: setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: get new version
+        id: ver
+        run: |
+          TAG=${GITHUB_REF_NAME:-$(curl -s https://registry.npmjs.org/@freqhole/playlistz/latest | node -p "JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8')).version")}
+          echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
+
+      - name: update @freqhole/playlistz in tomb/client/spume/package.json
+        run: |
+          VERSION=${{ steps.ver.outputs.version }}
+          node -e "
+            const fs = require('fs');
+            const path = 'client/spume/package.json';
+            const pkg = JSON.parse(fs.readFileSync(path, 'utf-8'));
+            if (pkg.dependencies?.['@freqhole/playlistz']) {
+              pkg.dependencies['@freqhole/playlistz'] = VERSION;
+            }
+            if (pkg.devDependencies?.['@freqhole/playlistz']) {
+              pkg.devDependencies['@freqhole/playlistz'] = VERSION;
+            }
+            fs.writeFileSync(path, JSON.stringify(pkg, null, 2) + '\n');
+          "
+
+      - name: configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: open PR in tomb
+        run: |
+          VERSION=${{ steps.ver.outputs.version }}
+          BRANCH="chore/bump-playlistz-${VERSION}"
+          git checkout -b "$BRANCH"
+          git add client/spume/package.json
+          git commit -m "chore: bump @freqhole/playlistz to ${VERSION}"
+          git push origin "$BRANCH"
+          gh pr create \
+            --title "chore: bump @freqhole/playlistz to ${VERSION}" \
+            --body "Automated bump of @freqhole/playlistz to ${VERSION} after npm publish." \
+            --base main \
+            --head "$BRANCH"
+        env:
+          GH_TOKEN: ${{ secrets.TOMB_PAT }}

package/.github/workflows/pr-checks.yml

@@ -0,0 +1,103 @@
+# fast checks on every pull request to main.
+# skips the "Version Packages" changeset PR (it only bumps versions and changelogs).
+name: pr checks
+
+on:
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: pr-checks-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  # ---- changeset presence check ----
+  changeset:
+    name: changeset required
+    if: github.head_ref != 'changeset-release/main'
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: install deps
+        run: npm ci
+
+      - name: check for changeset
+        run: npx changeset status --since=origin/main
+
+  # ---- type-check + lint ----
+  lint:
+    name: type-check + lint
+    if: github.head_ref != 'changeset-release/main'
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: install deps
+        run: npm ci
+
+      - name: type-check
+        run: npm run typecheck
+
+      - name: lint
+        run: npm run lint
+
+  # ---- unit tests ----
+  test:
+    name: unit tests
+    if: github.head_ref != 'changeset-release/main'
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: install deps
+        run: npm ci
+
+      - name: test
+        run: npm test
+
+  # ---- e2e tests ----
+  e2e:
+    name: e2e tests
+    if: github.head_ref != 'changeset-release/main'
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: install deps
+        run: npm ci
+
+      - name: install playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      - name: build standalone bundle (needed by e2e tests)
+        run: npm run build:standalone
+
+      - name: e2e tests
+        run: npm run test:e2e

package/README.md

@@ -0,0 +1,30 @@
+# P L A Y L I S T Z
+
+make some music playlistz in yr browser!
+
+## devel
+
+```sh
+
+# do this once
+npm install
+
+# run hot-reloading dev server
+npm run dev
+
+# build standalone .html page (+ sw.js)
+npm run build:standalone
+
+# build web-component
+npm run build
+
+# run way-too-mocked up testz
+npm test
+
+# or
+npm run test:watch
+npm run test:coverage
+```
+
+---
+made with 💖 in NYC

package/build-component.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/* global console, process */
+import { build } from "vite";
+import solid from "vite-plugin-solid";
+import tailwindcss from "@tailwindcss/vite";
+import wasm from "vite-plugin-wasm";
+import topLevelAwait from "vite-plugin-top-level-await";
+import { transform, build as esbuild } from "esbuild";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const skipClear = process.argv.includes("--no-clear");
+
+function readServiceWorker() {
+  const swPath = path.resolve("public/sw.js");
+  return fs.existsSync(swPath) ? fs.readFileSync(swPath, "utf-8") : null;
+}
+
+function generateIndexHtml() {
+  // this is the dev server / standalone shell - no playlistz.js here.
+  // zip bundles get their own index.html (with playlistz.js) from standaloneTemplates.ts.
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>playlistz</title>
+  <meta name="apple-mobile-web-app-capable" content="yes">
+  <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
+  <meta name="mobile-web-app-capable" content="yes">
+  <meta name="theme-color" content="#000000">
+</head>
+<body>
+  <freqhole-playlistz></freqhole-playlistz>
+  <script src="freqhole-playlistz.js" defer></script>
+</body>
+</html>
+`;
+}
+
+async function buildStandalone() {
+  const distDir = path.resolve("dist");
+  if (!skipClear) {
+    if (fs.existsSync(distDir)) fs.rmSync(distDir, { recursive: true, force: true });
+  }
+  fs.mkdirSync(distDir, { recursive: true });
+
+  const indexHtml = generateIndexHtml();
+  const swJs = readServiceWorker() ?? "";
+
+  // ---- browser bundle ----
+  console.log("building freqhole-playlistz.js...");
+  let browserCode = "";
+  let cssCode = "";
+
+  await build({
+    configFile: false,
+    plugins: [
+      wasm(), topLevelAwait(), solid({ typescript: true, jsx: "preserve" }), tailwindcss(),
+      {
+        name: "capture-browser-bundle",
+        enforce: "post",
+        async generateBundle(_, bundle) {
+          const jsChunk = Object.values(bundle).find(
+            (f) => f.type === "chunk" && typeof f.code === "string",
+          );
+          const cssAsset = Object.values(bundle).find(
+            (f) => f.type === "asset" && String(f.fileName).endsWith(".css"),
+          );
+          if (!jsChunk) { console.error("no js chunk found"); return; }
+          for (const [fileName, file] of Object.entries(bundle)) {
+            if (file.type === "asset" && fileName.endsWith(".wasm")) {
+              const b64 = Buffer.from(file.source).toString("base64");
+              const dataUri = `data:application/wasm;base64,${b64}`;
+              jsChunk.code = jsChunk.code.split(`/${fileName}`).join(dataUri);
+              delete bundle[fileName];
+              console.log(`  inlined wasm: ${fileName} (${(b64.length / 1024 / 1024).toFixed(1)} mb)`);
+            }
+          }
+          cssCode = cssAsset ? String(cssAsset.source) : "";
+          browserCode = jsChunk.code;
+          for (const key of Object.keys(bundle)) delete bundle[key];
+        },
+      },
+    ],
+    build: {
+      outDir: "dist", target: "esnext", minify: false, sourcemap: false, emptyOutDir: false,
+      rollupOptions: {
+        input: "./src/web-component.tsx",
+        output: {
+          format: "es", entryFileNames: "playlistz-entry.js",
+          chunkFileNames: "playlistz-[hash].js", assetFileNames: "playlistz.[ext]",
+          inlineDynamicImports: true,
+        },
+        external: ["@freqhole/midden"],
+      },
+    },
+  });
+
+  let cssInjector = "";
+  if (cssCode) {
+    const cssMinified = (await transform(cssCode, { loader: "css", minify: true })).code.replace(/\n/g, "");
+    cssInjector = `(()=>{const s=document.createElement('style');s.textContent=${JSON.stringify(cssMinified)};document.head.appendChild(s);})();\n`;
+  }
+  const { code: browserMinified } = await transform(cssInjector + browserCode, {
+    minify: true, sourcemap: false, format: "iife", target: "esnext",
+  });
+  fs.writeFileSync(path.resolve("dist/freqhole-playlistz.js"), browserMinified, "utf-8");
+  console.log(`generated: freqhole-playlistz.js (${(browserMinified.length / 1024 / 1024).toFixed(2)} mb)`);
+
+  // ---- cli bundle ----
+  console.log("building freqhole-playlistz.cli.mjs...");
+  const cliOut = path.resolve("dist/freqhole-playlistz.cli.mjs");
+  const cliEntry = path.resolve(__dirname, "src/cli/index.ts");
+  await esbuild({
+    entryPoints: [cliEntry],
+    bundle: true, platform: "node", format: "esm", outfile: cliOut,
+    minify: true, sourcemap: false,
+    banner: { js: "#!/usr/bin/env node" },
+    define: { "import.meta.url": '"file://"' },
+  });
+  let cliCode = fs.readFileSync(cliOut, "utf-8");
+  cliCode = cliCode.replace('"__INDEX_HTML__"', JSON.stringify(indexHtml));
+  cliCode = cliCode.replace('"__SW_JS__"', JSON.stringify(swJs));
+  fs.writeFileSync(cliOut, cliCode, "utf-8");
+  fs.chmodSync(cliOut, 0o755);
+  console.log("generated: freqhole-playlistz.cli.mjs");
+
+  // ---- static assets ----
+  fs.writeFileSync(path.resolve("dist/index.html"), indexHtml, "utf-8");
+  if (swJs) fs.writeFileSync(path.resolve("dist/sw.js"), swJs, "utf-8");
+  console.log("generated: index.html, sw.js");
+
+  console.log("\nbuild completed!");
+  console.log("  browser: dist/freqhole-playlistz.js");
+  console.log("  cli:     dist/freqhole-playlistz.cli.mjs");
+}
+
+buildStandalone().catch((err) => { console.error("build failed:", err); process.exit(1); });