@freqhole/playlistz 0.0.1

package/src/web-component.tsx

@@ -0,0 +1,98 @@
+import { render } from "solid-js/web";
+import { Playlistz } from "./components/index.js";
+import { FreqholePlaylistzSchema } from "./utils/standaloneTemplates.js";
+import { initializeStandalonePlaylist } from "./services/standaloneService.js";
+import "./styles.css";
+
+// expose a reset helper on window so devs can clear all playlistz state from
+// the browser console: await window.__playlistzReset()
+if (typeof window !== "undefined") {
+  (window as unknown as Record<string, unknown>).__playlistzReset =
+    async () => {
+      // tell the service worker to clear its caches
+      if ("serviceWorker" in navigator && navigator.serviceWorker.controller) {
+        navigator.serviceWorker.controller.postMessage({
+          type: "PLAYLISTZ_RESET",
+        });
+      }
+      // clear all playlistz IDB databases
+      const dbs = (await indexedDB.databases?.()) ?? [];
+      await Promise.all(
+        dbs
+          .filter((d) => d.name)
+          .map(
+            (d) =>
+              new Promise<void>((res, rej) => {
+                const req = indexedDB.deleteDatabase(d.name!);
+                req.onsuccess = () => res();
+                req.onerror = () => rej(req.error);
+              })
+          )
+      );
+      // clear all caches
+      if ("caches" in window) {
+        const names = await caches.keys();
+        await Promise.all(names.map((n) => caches.delete(n)));
+      }
+      console.log(
+        "playlistz: all caches and IDB databases cleared. reload to restart fresh."
+      );
+    };
+}
+
+customElements.define(
+  "freqhole-playlistz",
+  class extends HTMLElement {
+    static get observedAttributes() {
+      return ["data-playlistz"];
+    }
+
+    connectedCallback() {
+      render(() => <Playlistz />, this);
+
+      const attr = this.getAttribute("data-playlistz");
+      if (attr) {
+        this._initFromJson(attr);
+      }
+    }
+
+    // fired when data-playlistz is set after the element is already connected
+    // (e.g. dynamically injected or set by a script that runs after registration)
+    attributeChangedCallback(
+      name: string,
+      _old: string | null,
+      val: string | null
+    ) {
+      if (name === "data-playlistz" && val) {
+        this._initFromJson(val);
+      }
+    }
+
+    private _initFromJson(json: string) {
+      try {
+        const parsed = JSON.parse(json);
+        const result = FreqholePlaylistzSchema.safeParse(parsed);
+        if (!result.success) {
+          console.error("invalid data-playlistz attribute:", result.error);
+          return;
+        }
+        this._initFromEntries(result.data);
+      } catch (err) {
+        console.error("failed to parse data-playlistz attribute:", err);
+      }
+    }
+
+    private _initFromEntries(
+      entries: ReturnType<typeof FreqholePlaylistzSchema.parse>
+    ) {
+      for (const entry of entries) {
+        initializeStandalonePlaylist(entry, {
+          setSelectedPlaylist: () => {},
+          setPlaylistSongs: () => {},
+          setSidebarCollapsed: () => {},
+          setError: (err) => console.error("standalone init error:", err),
+        }).catch((err) => console.error("standalone init failed:", err));
+      }
+    }
+  }
+);

package/src/zip-bundle/index.ts

@@ -0,0 +1,7 @@
+export { buildPlaylistZip, cleanupOpfsTempFile } from "./zipBuilder.js";
+export type {
+  BlobFetcher,
+  PlaylistZipEntry,
+  PlaylistZipSong,
+  PlaylistZipOptions,
+} from "./types.js";

package/src/zip-bundle/m3u.ts

@@ -0,0 +1,45 @@
+// m3u8 generator for the zip bundle.
+// takes pre-computed file paths rather than raw song/playlist types,
+// so it works in both playlistz and spume contexts.
+
+export interface M3UZipSong {
+  title: string;
+  artist: string;
+  album: string;
+  duration: number;
+  audioPath: string;   // relative path written into the m3u8, e.g. "data/song.mp3"
+  imagePath?: string;  // relative path for cover, e.g. "data/song-cover.jpg"
+}
+
+export interface M3UZipPlaylist {
+  id: string;
+  title: string;
+  description?: string;
+  rev?: number;
+  imagePath?: string;  // relative path for playlist cover
+}
+
+export function generateM3UContent(
+  playlist: M3UZipPlaylist,
+  songs: M3UZipSong[],
+): string {
+  let out = "#EXTM3U\n";
+  out += `# Playlist: ${playlist.title}\n`;
+  out += `# PlaylistId: ${playlist.id}\n`;
+  out += `# PlaylistRev: ${playlist.rev ?? 0}\n`;
+  if (playlist.description) out += `# Description: ${playlist.description}\n`;
+  if (playlist.imagePath)   out += `# PlaylistImage: ${playlist.imagePath}\n`;
+  out += "\n";
+
+  for (const song of songs) {
+    const duration = Math.round(song.duration);
+    out += `#EXTINF:${duration}, ${song.artist} - ${song.title}\n`;
+    out += `# Title: ${song.title}\n`;
+    out += `# Artist: ${song.artist}\n`;
+    out += `# Album: ${song.album}\n`;
+    if (song.imagePath) out += `# Image: ${song.imagePath}\n`;
+    out += `${song.audioPath}\n\n`;
+  }
+
+  return out;
+}

package/src/zip-bundle/types.ts

@@ -0,0 +1,50 @@
+// types for the zip-bundle export.
+// no playlistz-internal type dependencies - safe to import from spume or node.
+
+// key is sha256 hex (64 chars). both playlistz (IDB) and spume (Song.sha256)
+// carry this. callers close over whatever mapping turns sha256 into bytes.
+export type BlobFetcher = (sha256: string) => Promise<ArrayBuffer | undefined>;
+
+export interface PlaylistZipSong {
+  id: string;
+  title: string;
+  artist?: string;
+  album?: string;
+  duration: number;
+  originalFilename: string;
+  mimeType: string;
+  sha?: string;        // audio blob sha256 - BlobFetcher key
+  imageSha?: string;   // cover image sha256 - BlobFetcher key
+  imageType?: string;  // mime type of cover image
+  fileSize?: number;
+  lyrics?: string;
+}
+
+export interface PlaylistZipEntry {
+  playlist: {
+    id: string;
+    title: string;
+    description?: string;
+    rev?: number;
+    imageSha?: string;    // sha256 of playlist cover image blob
+    imageType?: string;   // mime type of playlist cover image
+    bgFilterEnabled?: boolean;
+    bgFilterBlur?: number;
+    bgFilterContrast?: number;
+    bgFilterBrightness?: number;
+    coverFilterEnabled?: boolean;
+    coverFilterBlur?: number;
+  };
+  songs: PlaylistZipSong[];
+}
+
+export interface PlaylistZipOptions {
+  includeImages?: boolean;
+  generateM3U?: boolean;
+  includeHTML?: boolean;
+  // explicit url to fetch freqhole-playlistz.js for embedding.
+  // when omitted in a browser context falls back to
+  // window.location.origin + "/freqhole-playlistz.js".
+  // set to null to skip embedding the app bundle entirely.
+  appBundleUrl?: string | null;
+}

package/src/zip-bundle/utils.ts

@@ -0,0 +1,33 @@
+// shared filename/mime utilities used by both the zip builder
+// and the m3u generator. no external dependencies.
+
+export function sanitizeFilename(name: string): string {
+  return name
+    .replace(/[<>:"/\\|?*\x00-\x1f]/g, "_")
+    .replace(/\s+/g, "_")
+    .substring(0, 200);
+}
+
+export function createSafeTitle(title: string): string {
+  return title
+    .replace(/[<>:"/\\|?*]/g, "_")
+    .replace(/\s+/g, "_")
+    .toLowerCase()
+    .substring(0, 100);
+}
+
+export function getFileExtension(mimeType: string): string {
+  const map: Record<string, string> = {
+    "audio/mpeg": ".mp3",
+    "audio/mp4": ".m4a",
+    "audio/wav": ".wav",
+    "audio/flac": ".flac",
+    "audio/ogg": ".ogg",
+    "audio/webm": ".webm",
+    "image/jpeg": ".jpg",
+    "image/png": ".png",
+    "image/gif": ".gif",
+    "image/webp": ".webp",
+  };
+  return map[mimeType] ?? ".bin";
+}

package/src/zip-bundle/zipBuilder.ts

@@ -0,0 +1,309 @@
+import { Zip, ZipPassThrough } from "fflate";
+import type { BlobFetcher, PlaylistZipEntry, PlaylistZipOptions } from "./types.js";
+import { sanitizeFilename, createSafeTitle, getFileExtension } from "./utils.js";
+import { generateM3UContent } from "./m3u.js";
+import { generateIndexHtml, generatePlaylistzJs } from "../utils/standaloneTemplates.js";
+import { generateSwJs } from "../utils/swTemplate.js";
+
+// derive a MIME type from a file path extension.
+// used as a fallback when the caller didn't supply an explicit imageType.
+function mimeFromPath(filePath: string): string {
+  const ext = filePath.split(".").pop()?.toLowerCase();
+  const map: Record<string, string> = {
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    png: "image/png",
+    gif: "image/gif",
+    webp: "image/webp",
+    avif: "image/avif",
+  };
+  return (ext && map[ext]) ? map[ext]! : "image/jpeg";
+}
+
+const TEXT_ENC = new TextEncoder();
+
+// creates a streaming zip builder.
+//
+// in browsers (OPFS available): each file is written to an OPFS temp file
+// as its bytes are pushed. awaiting addFile() between files lets the OS
+// flush the write queue, so the prior file's bytes become eligible for GC
+// before the next file is fetched. this keeps peak memory at ~1 song at a time.
+//
+// in node/cli (no OPFS): chunks are accumulated in memory. for the cli path
+// playlists are usually small so this is acceptable.
+async function createStreamingZip(): Promise<{
+  addFile: (path: string, bytes: Uint8Array) => Promise<void>;
+  finish: () => Promise<Blob>;
+  tempName?: string;
+}> {
+  const opfsAvailable =
+    typeof navigator !== "undefined" &&
+    typeof navigator.storage?.getDirectory === "function" &&
+    // tauri webviews expose navigator.storage but lack FileSystemWritableFileStream;
+    // skip the OPFS attempt entirely and use the in-memory path + tauri IPC instead.
+    !(typeof window !== "undefined" && "__TAURI_INTERNALS__" in window);
+
+  if (opfsAvailable) {
+    try {
+      const opfsRoot = await navigator.storage.getDirectory();
+      const tempName = `playlistz-dl-${Date.now()}.zip`;
+      const tempHandle = await opfsRoot.getFileHandle(tempName, { create: true });
+      const writable = await tempHandle.createWritable();
+
+    // chain writes so they execute in order and we can await the tail
+    let pendingWrite: Promise<unknown> = Promise.resolve();
+    let resolveFinished!: () => void;
+    let rejectFinished!: (err: unknown) => void;
+    const finished = new Promise<void>((res, rej) => {
+      resolveFinished = res;
+      rejectFinished = rej;
+    });
+
+    const zip = new Zip((err, data, final) => {
+      if (err) { rejectFinished(err); return; }
+      pendingWrite = pendingWrite.then(() => writable.write(data));
+      if (final) {
+        pendingWrite
+          .then(() => writable.close())
+          .then(resolveFinished, rejectFinished);
+      }
+    });
+
+    return {
+      tempName,
+      async addFile(path, bytes) {
+        const entry = new ZipPassThrough(path);
+        zip.add(entry);
+        entry.push(bytes, true);
+        // await the write tail so OPFS has consumed the bytes before the
+        // caller fetches the next file. this lets the prior ArrayBuffer GC.
+        await pendingWrite;
+      },
+      async finish() {
+        zip.end();
+        await finished;
+        return tempHandle.getFile();
+      },
+    };
+    } catch {
+      // OPFS unavailable or createWritable not supported (e.g. Tauri WKWebView) -
+      // fall through to the in-memory path below
+    }
+  }
+
+  // in-memory fallback (node/cli or when OPFS write is unavailable)
+  const chunks: Uint8Array[] = [];
+  let resolveDone!: () => void;
+  let rejectDone!: (err: unknown) => void;
+  const done = new Promise<void>((res, rej) => { resolveDone = res; rejectDone = rej; });
+
+  const zip = new Zip((err, data, final) => {
+    if (err) { rejectDone(err); return; }
+    chunks.push(data);
+    if (final) resolveDone();
+  });
+
+  return {
+    async addFile(path, bytes) {
+      const entry = new ZipPassThrough(path);
+      zip.add(entry);
+      entry.push(bytes, true);
+    },
+    async finish() {
+      zip.end();
+      await done;
+      const total = chunks.reduce((acc, c) => acc + c.length, 0);
+      const buf = new Uint8Array(total);
+      let off = 0;
+      for (const c of chunks) { buf.set(c, off); off += c.length; }
+      return new Blob([buf], { type: "application/zip" });
+    },
+  };
+}
+
+// builds a self-contained playlist zip as a Blob.
+// each file is fetched and streamed into the zip one at a time so that
+// prior audio bytes can be GC'd before the next song is fetched.
+export async function buildPlaylistZip(
+  entry: PlaylistZipEntry,
+  fetchBlob: BlobFetcher,
+  options: PlaylistZipOptions = {},
+): Promise<Blob> {
+  const {
+    includeImages = true,
+    generateM3U = true,
+    includeHTML = true,
+    appBundleUrl,
+  } = options;
+
+  const rootName = createSafeTitle(entry.playlist.title) || "playlist";
+  const builder = await createStreamingZip();
+
+  // ---- playlist cover image ----
+  let playlistImagePath: string | undefined;
+  if (includeImages && entry.playlist.imageSha) {
+    const bytes = await fetchBlob(entry.playlist.imageSha);
+    if (bytes) {
+      const ext = getFileExtension(entry.playlist.imageType ?? "image/jpeg");
+      const filename = `playlist-cover${ext}`;
+      playlistImagePath = `data/${filename}`;
+      await builder.addFile(`${rootName}/${playlistImagePath}`, new Uint8Array(bytes));
+      // bytes GC-eligible after addFile resolves
+    }
+  }
+
+  // ---- songs: fetch, stream, and discard bytes one at a time ----
+  // resolvedSongs holds only metadata (no byte buffers) so it stays small.
+  const resolvedSongs: Array<{
+    song: PlaylistZipEntry["songs"][number];
+    audioPath: string;
+    imagePath?: string;
+    safeFilename: string;
+    fileSize: number;
+  }> = [];
+
+  for (const song of entry.songs) {
+    const safeFilename = song.originalFilename
+      ? sanitizeFilename(song.originalFilename)
+      : sanitizeFilename(`${song.title}.${getFileExtension(song.mimeType).slice(1)}`);
+    const safeBase = safeFilename.replace(/\.[^.]+$/, "");
+    const audioPath = `data/${safeFilename}`;
+    let fileSize = song.fileSize ?? 0;
+
+    // fetch audio and stream it immediately
+    if (song.sha) {
+      const audioBytes = await fetchBlob(song.sha);
+      if (audioBytes) {
+        fileSize = audioBytes.byteLength;
+        await builder.addFile(`${rootName}/${audioPath}`, new Uint8Array(audioBytes));
+        // audioBytes GC-eligible after addFile resolves
+      }
+    }
+
+    // fetch cover image and stream it immediately
+    let imagePath: string | undefined;
+    if (includeImages && song.imageSha) {
+      const imageBytes = await fetchBlob(song.imageSha);
+      if (imageBytes) {
+        const ext = getFileExtension(song.imageType ?? "image/jpeg");
+        const imageFilename = `${safeBase}-cover${ext}`;
+        imagePath = `data/${imageFilename}`;
+        await builder.addFile(`${rootName}/${imagePath}`, new Uint8Array(imageBytes));
+        // imageBytes GC-eligible after addFile resolves
+      }
+    }
+
+    resolvedSongs.push({ song, audioPath, imagePath, safeFilename, fileSize });
+  }
+
+  // ---- playlistz.js data file ----
+  const playlistzData = [
+    {
+      playlist: {
+        id: entry.playlist.id,
+        title: entry.playlist.title,
+        description: entry.playlist.description,
+        rev: entry.playlist.rev,
+        imageMimeType: entry.playlist.imageType ?? (playlistImagePath ? mimeFromPath(playlistImagePath) : undefined),
+        imageFilePath: playlistImagePath,
+        safeFilename: rootName,
+        bgFilterEnabled: entry.playlist.bgFilterEnabled,
+        bgFilterBlur: entry.playlist.bgFilterBlur,
+        bgFilterContrast: entry.playlist.bgFilterContrast,
+        bgFilterBrightness: entry.playlist.bgFilterBrightness,
+        coverFilterEnabled: entry.playlist.coverFilterEnabled,
+        coverFilterBlur: entry.playlist.coverFilterBlur,
+      },
+      songs: resolvedSongs.map((r) => ({
+        id: r.song.id,
+        title: r.song.title,
+        artist: r.song.artist ?? "",
+        album: r.song.album ?? "",
+        duration: r.song.duration,
+        originalFilename: r.song.originalFilename,
+        filePath: r.audioPath,
+        safeFilename: r.safeFilename,
+        fileSize: r.fileSize,
+        mimeType: r.song.mimeType,
+        sha: r.song.sha,
+        imageMimeType: r.song.imageType ?? (r.imagePath ? mimeFromPath(r.imagePath) : undefined),
+        imageFilePath: r.imagePath,
+      })),
+    },
+  ];
+  await builder.addFile(`${rootName}/playlistz.js`, TEXT_ENC.encode(generatePlaylistzJs(playlistzData)));
+
+  // ---- m3u8 file ----
+  if (generateM3U) {
+    const m3uContent = generateM3UContent(
+      {
+        id: entry.playlist.id,
+        title: entry.playlist.title,
+        description: entry.playlist.description,
+        rev: entry.playlist.rev,
+        imagePath: playlistImagePath,
+      },
+      resolvedSongs.map((r) => ({
+        title: r.song.title,
+        artist: r.song.artist ?? "",
+        album: r.song.album ?? "",
+        duration: r.song.duration,
+        audioPath: r.audioPath,
+        imagePath: r.imagePath,
+      })),
+    );
+    await builder.addFile(`${rootName}/data/${rootName}.m3u8`, TEXT_ENC.encode(m3uContent));
+  }
+
+  // ---- static shell files ----
+  if (includeHTML) {
+    await builder.addFile(`${rootName}/index.html`, TEXT_ENC.encode(generateIndexHtml()));
+    await builder.addFile(`${rootName}/sw.js`, TEXT_ENC.encode(generateSwJs()));
+
+    const bundleUrl =
+      appBundleUrl !== undefined
+        ? appBundleUrl
+        : typeof window !== "undefined"
+          ? `${window.location.origin}/freqhole-playlistz.js`
+          : null;
+
+    if (bundleUrl) {
+      try {
+        const res = await fetch(bundleUrl);
+        if (res.ok) {
+          const text = await res.text();
+          // vite dev server (and other html-first servers) return the app's
+          // index.html for unknown routes. detect and skip to avoid embedding
+          // html as the js bundle. users should run `npm run build:standalone`
+          // first so dist/freqhole-playlistz.js exists for the dev server to serve.
+          if (text.trimStart().startsWith("<!")) {
+            console.warn(
+              "freqhole-playlistz.js fetch returned HTML (vite dev mode?). " +
+              "run `npm run build:standalone` first, then retry the zip download.",
+            );
+          } else {
+            await builder.addFile(`${rootName}/freqhole-playlistz.js`, TEXT_ENC.encode(text));
+          }
+        } else {
+          console.warn("could not fetch freqhole-playlistz.js for zip bundle:", res.status);
+        }
+      } catch (err) {
+        console.warn("could not include freqhole-playlistz.js in zip:", err);
+      }
+    }
+    // note: no separate cli mjs needed - the cli is gated inside freqhole-playlistz.js
+  }
+
+  return builder.finish();
+}
+
+// delete an OPFS temp file created by buildPlaylistZip.
+// call this after the browser download or tauri save is complete.
+export async function cleanupOpfsTempFile(filename: string): Promise<void> {
+  try {
+    const root = await navigator.storage.getDirectory();
+    await root.removeEntry(filename);
+  } catch {
+    // file may have already been removed or never existed - ignore
+  }
+}

package/tailwind.config.js

@@ -0,0 +1,55 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: [
+    "./index.html",
+    "./src/**/*.{js,jsx,ts,tsx}",
+  ],
+
+  theme: {
+    extend: {
+      colors: {
+        magenta: {
+          50: "#fdf4ff",
+          100: "#fae8ff",
+          200: "#f5d0fe",
+          300: "#f0abfc",
+          400: "#e879f9",
+          500: "#d946ef", // Primary magenta
+          600: "#c026d3",
+          700: "#a21caf",
+          800: "#86198f",
+          900: "#701a75",
+        },
+        // Keep existing dark theme colors
+        dark: {
+          50: "#f8f9fa",
+          100: "#f1f3f4",
+          200: "#e8eaed",
+          300: "#dadce0",
+          400: "#bdc1c6",
+          500: "#9aa0a6",
+          600: "#80868b",
+          700: "#5f6368",
+          800: "#3c4043",
+          900: "#202124",
+        },
+      },
+      animation: {
+        slideInRight: "slideInRight 0.3s ease-out",
+        slideDown: "slideDown 0.3s ease-out",
+        pulse: "pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite",
+      },
+      keyframes: {
+        slideInRight: {
+          from: { transform: "translateX(100%)" },
+          to: { transform: "translateX(0)" },
+        },
+        slideDown: {
+          from: { transform: "translateY(-100%)" },
+          to: { transform: "translateY(0)" },
+        },
+      },
+    },
+  },
+  plugins: [],
+};

package/tsconfig.json

@@ -0,0 +1,43 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": false,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "removeComments": false,
+    "sourceMap": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "exactOptionalPropertyTypes": false,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "allowUnusedLabels": false,
+    "allowUnreachableCode": false,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "useDefineForClassFields": true,
+    "allowJs": false,
+    "checkJs": false,
+    "incremental": true,
+    "composite": false,
+    "tsBuildInfoFile": "./dist/.tsbuildinfo",
+    "jsx": "preserve",
+    "jsxImportSource": "solid-js",
+    "types": ["vite/client", "vitest/globals", "node"]
+  },
+  "include": ["src/**/*", "src/types/global.d.ts", "config/**/*", "e2e/**/*"],
+  "exclude": ["node_modules", "dist", "coverage"]
+}