@freqhole/playlistz 0.0.1

package/src/utils/standaloneTemplates.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect } from "vitest";
+import {
+  FreqholePlaylistSchema,
+  FreqholePlaylistzSchema,
+  generatePlaylistzJs,
+  generateIndexHtml,
+  type FreqholePlaylist,
+} from "./standaloneTemplates.js";
+
+// ---- helpers ----
+
+function makePlaylist(overrides: Partial<FreqholePlaylist["playlist"]> = {}): FreqholePlaylist {
+  return {
+    playlist: {
+      id: "test-id",
+      title: "test playlist",
+      description: "a description",
+      rev: 1,
+      imageExtension: ".jpg",
+      imageMimeType: "image/jpeg",
+      ...overrides,
+    },
+    songs: [
+      {
+        id: "song-1",
+        title: "song one",
+        artist: "artist a",
+        album: "album x",
+        duration: 180,
+        originalFilename: "01-song one.mp3",
+        fileSize: 4000000,
+        mimeType: "audio/mpeg",
+        safeFilename: "01-song one.mp3",
+        imageExtension: ".jpg",
+        imageMimeType: "image/jpeg",
+      },
+    ],
+  };
+}
+
+// ---- FreqholePlaylistSchema ----
+
+describe("FreqholePlaylistSchema", () => {
+  it("parses a valid playlist entry", () => {
+    const result = FreqholePlaylistSchema.safeParse(makePlaylist());
+    expect(result.success).toBe(true);
+  });
+
+  it("parses with optional fields absent", () => {
+    const result = FreqholePlaylistSchema.safeParse({
+      playlist: { id: "abc", title: "minimal" },
+      songs: [],
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.playlist.description).toBeUndefined();
+      expect(result.data.playlist.rev).toBeUndefined();
+    }
+  });
+
+  it("rejects missing required playlist id", () => {
+    const bad = { playlist: { title: "no id" }, songs: [] };
+    expect(FreqholePlaylistSchema.safeParse(bad).success).toBe(false);
+  });
+
+  it("rejects missing required playlist title", () => {
+    const bad = { playlist: { id: "x" }, songs: [] };
+    expect(FreqholePlaylistSchema.safeParse(bad).success).toBe(false);
+  });
+
+  it("rejects non-array songs field", () => {
+    const bad = { playlist: { id: "x", title: "y" }, songs: "not an array" };
+    expect(FreqholePlaylistSchema.safeParse(bad).success).toBe(false);
+  });
+
+  it("rejects song with missing required fields", () => {
+    const bad = {
+      playlist: { id: "x", title: "y" },
+      songs: [{ title: "no id" }],
+    };
+    expect(FreqholePlaylistSchema.safeParse(bad).success).toBe(false);
+  });
+
+  it("parses song with only required fields", () => {
+    const result = FreqholePlaylistSchema.safeParse({
+      playlist: { id: "x", title: "y" },
+      songs: [
+        {
+          id: "s1",
+          title: "t",
+          artist: "a",
+          album: "b",
+          duration: 60,
+          originalFilename: "f.mp3",
+          fileSize: 1000,
+        },
+      ],
+    });
+    expect(result.success).toBe(true);
+  });
+});
+
+// ---- FreqholePlaylistzSchema ----
+
+describe("FreqholePlaylistzSchema", () => {
+  it("parses an empty array", () => {
+    expect(FreqholePlaylistzSchema.safeParse([]).success).toBe(true);
+  });
+
+  it("parses multiple playlists", () => {
+    const p1 = makePlaylist({ id: "id-1", title: "playlist 1" });
+    const p2 = makePlaylist({ id: "id-2", title: "playlist 2" });
+    const result = FreqholePlaylistzSchema.safeParse([p1, p2]);
+    expect(result.success).toBe(true);
+    if (result.success) expect(result.data).toHaveLength(2);
+  });
+
+  it("rejects a non-array", () => {
+    expect(FreqholePlaylistzSchema.safeParse({ playlist: {} }).success).toBe(false);
+  });
+});
+
+// ---- generatePlaylistzJs ----
+
+describe("generatePlaylistzJs", () => {
+  it("sets data-playlistz attribute on the web component element", () => {
+    const out = generatePlaylistzJs([makePlaylist()]);
+    expect(out).toContain("setAttribute('data-playlistz'");
+    expect(out).toContain("freqhole-playlistz");
+  });
+
+  it("round-trips through JSON correctly", () => {
+    const input = [makePlaylist()];
+    const out = generatePlaylistzJs(input);
+    // extract the inner JSON string from the setAttribute call
+    const match = out.match(/setAttribute\('data-playlistz',\s*("(?:[^"\\]|\\.)*")\)/);
+    expect(match).not.toBeNull();
+    const innerJson = JSON.parse(match![1]!);
+    const parsed = JSON.parse(innerJson);
+    expect(parsed[0].playlist.id).toBe("test-id");
+    expect(parsed[0].songs[0].title).toBe("song one");
+  });
+
+  it("generates valid output for empty array", () => {
+    const out = generatePlaylistzJs([]);
+    expect(out).toContain("setAttribute('data-playlistz'");
+    // the embedded JSON should be an empty array
+    const match = out.match(/setAttribute\('data-playlistz',\s*("(?:[^"\\]|\\.)*")\)/);
+    expect(match).not.toBeNull();
+    const innerJson = JSON.parse(match![1]!);
+    expect(JSON.parse(innerJson)).toEqual([]);
+  });
+});
+
+// ---- generateIndexHtml ----
+
+describe("generateIndexHtml", () => {
+  it("includes script tag for playlistz.js (no type=module)", () => {
+    const html = generateIndexHtml();
+    expect(html).toContain('<script src="playlistz.js">');
+    expect(html).not.toContain('type="module"');
+  });
+
+  it("includes script tag for freqhole-playlistz.js", () => {
+    expect(generateIndexHtml()).toContain('<script src="freqhole-playlistz.js">');
+  });
+
+  it("includes freqhole-playlistz custom element", () => {
+    expect(generateIndexHtml()).toContain("<freqhole-playlistz>");
+  });
+
+  it("is valid html with doctype", () => {
+    expect(generateIndexHtml()).toMatch(/^<!DOCTYPE html>/);
+  });
+});

package/src/utils/standaloneTemplates.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+
+// schema for a single song entry in a freqhole playlist
+const FreqholePlaylistSongSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  artist: z.string(),
+  album: z.string(),
+  duration: z.number(),
+  originalFilename: z.string(),
+  fileSize: z.number(),
+  sha: z.string().optional(),
+  imageExtension: z.string().optional(),
+  imageMimeType: z.string().optional(),
+  imageFilePath: z.string().optional(),
+  filePath: z.string().optional(),
+  safeFilename: z.string().optional(),
+  mimeType: z.string().optional(),
+});
+
+// schema for the playlist metadata header in a freqhole playlist entry
+const FreqholePlaylistHeaderSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  description: z.string().optional(),
+  rev: z.number().optional(),
+  imageExtension: z.string().optional(),
+  imageMimeType: z.string().optional(),
+  imageFilePath: z.string().optional(),
+  safeFilename: z.string().optional(),
+  bgFilterEnabled: z.boolean().optional(),
+  bgFilterBlur: z.number().optional(),
+  bgFilterContrast: z.number().optional(),
+  bgFilterBrightness: z.number().optional(),
+  coverFilterEnabled: z.boolean().optional(),
+  coverFilterBlur: z.number().optional(),
+});
+
+// schema for a single { playlist, songs } entry - matches StandaloneData shape
+export const FreqholePlaylistSchema = z.object({
+  playlist: FreqholePlaylistHeaderSchema,
+  songs: z.array(FreqholePlaylistSongSchema),
+});
+
+// schema for the full playlistz prop value (one or more playlists)
+export const FreqholePlaylistzSchema = z.array(FreqholePlaylistSchema);
+
+export type FreqholePlaylistSong = z.infer<typeof FreqholePlaylistSongSchema>;
+export type FreqholePlaylistHeader = z.infer<typeof FreqholePlaylistHeaderSchema>;
+export type FreqholePlaylist = z.infer<typeof FreqholePlaylistSchema>;
+export type FreqholePlaylistz = z.infer<typeof FreqholePlaylistzSchema>;
+
+// generates the playlistz.js data file content for one or more playlists
+export function generatePlaylistzJs(playlists: FreqholePlaylistz): string {
+  // set the data as a web component attribute instead of a global.
+  // playlistz.js runs before freqhole-playlistz.js (both deferred), so the
+  // <freqhole-playlistz> element is in the DOM (unupgraded). setAttribute works
+  // on unupgraded elements; the data is present when connectedCallback fires.
+  const json = JSON.stringify(JSON.stringify(playlists));
+  return `(function(){var el=document.querySelector('freqhole-playlistz');if(el)el.setAttribute('data-playlistz',${json});})();\n`;
+}
+
+// generates the minimal static index.html shell - no playlist data embedded
+export function generateIndexHtml(): string {
+  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="playlistz.js" defer></script>
+  <script src="freqhole-playlistz.js" defer></script>
+</body>
+</html>
+`;
+}

package/src/utils/swTemplate.ts

@@ -0,0 +1,84 @@
+// service worker source inlined as a string.
+// public/sw.js is kept in sync with this content.
+// this string is embedded into zip bundles so they are fully self-contained.
+//
+// to reset all caches from the browser console:
+//   await window.__playlistzReset()    (registered by web-component.tsx)
+//
+// to force a cache refresh, bump CACHE_VERSION below and rebuild.
+
+const SW_JS_CONTENT = `// playlistz service worker
+//
+// caches the app shell files (freqhole-playlistz.js, playlistz.js, index.html, sw.js).
+// audio and image files in data/ are NOT pre-cached; the app ui handles that separately.
+//
+// bumping CACHE_VERSION forces all clients to receive fresh app files on next load.
+const CACHE_VERSION = "v2";
+const CACHE_NAME = \`playlistz-\${CACHE_VERSION}\`;
+
+const APP_SHELL = [
+  "freqhole-playlistz.js",
+  "playlistz.js",
+  "index.html",
+  "sw.js",
+];
+
+self.addEventListener("install", (event) => {
+  event.waitUntil(
+    caches.open(CACHE_NAME).then((cache) =>
+      cache.addAll(APP_SHELL).catch((err) => {
+        console.warn("playlistz sw: pre-cache partial failure:", err);
+      }),
+    ).then(() => self.skipWaiting()),
+  );
+});
+
+self.addEventListener("activate", (event) => {
+  event.waitUntil(
+    caches.keys()
+      .then((names) =>
+        Promise.all(
+          names
+            .filter((n) => n.startsWith("playlistz-") && n !== CACHE_NAME)
+            .map((n) => caches.delete(n)),
+        ),
+      )
+      .then(() => self.clients.claim()),
+  );
+});
+
+self.addEventListener("fetch", (event) => {
+  const url = new URL(event.request.url);
+  const filename = url.pathname.split("/").pop() ?? "";
+  const isAppShell = APP_SHELL.includes(filename) || url.pathname === "/" || url.pathname === "";
+
+  if (!isAppShell) return;
+
+  event.respondWith(
+    caches.match(event.request).then((cached) => {
+      if (cached) return cached;
+      return fetch(event.request).then((response) => {
+        if (response.ok) {
+          caches.open(CACHE_NAME).then((cache) => cache.put(event.request, response.clone()));
+        }
+        return response;
+      });
+    }).catch(() => caches.match("index.html")),
+  );
+});
+
+self.addEventListener("message", (event) => {
+  if (event.data?.type === "PLAYLISTZ_RESET") {
+    event.waitUntil(
+      caches.keys()
+        .then((names) => Promise.all(names.map((n) => caches.delete(n))))
+        .then(() => self.clients.matchAll())
+        .then((clients) => clients.forEach((c) => c.postMessage({ type: "PLAYLISTZ_RESET_DONE" }))),
+    );
+  }
+});
+`;
+
+export function generateSwJs(): string {
+  return SW_JS_CONTENT;
+}

package/src/utils/timeUtils.ts

@@ -0,0 +1,166 @@
+// Time Utilities with Global Polling System
+// Enhanced relative time function with broader time windows and efficient updates
+
+import { createSignal } from "solid-js";
+
+// Global time updater for managing all relative time signals
+const timeSignals = new Set<() => void>();
+let globalInterval: number | null = null;
+
+// Start global time updater
+function startGlobalTimeUpdater(): void {
+  if (globalInterval) return;
+
+  globalInterval = window.setInterval(() => {
+    timeSignals.forEach((update) => update());
+  }, 60000); // Update every minute
+}
+
+// Stop global time updater
+function stopGlobalTimeUpdater(): void {
+  if (globalInterval) {
+    window.clearInterval(globalInterval);
+    globalInterval = null;
+  }
+}
+
+// Create a relative time signal that updates automatically
+export function createRelativeTimeSignal(timestamp: number) {
+  const [signal, setSignal] = createSignal("");
+
+  function update() {
+    const now = Date.now();
+    const diff = now - timestamp;
+    let label;
+
+    if (diff < 60000) {
+      label = "just now";
+    } else if (diff < 3600000) {
+      const minutes = Math.floor(diff / 60000);
+      label = `${minutes} ${minutes === 1 ? "minute" : "minutes"} ago`;
+    } else if (diff < 86400000) {
+      const hours = Math.floor(diff / 3600000);
+      label = `${hours} ${hours === 1 ? "hour" : "hours"} ago`;
+    } else if (diff < 604800000) {
+      // 7 days
+      const days = Math.floor(diff / 86400000);
+      label = `${days} ${days === 1 ? "day" : "days"} ago`;
+    } else if (diff < 2629746000) {
+      // ~30.44 days (average month)
+      const weeks = Math.floor(diff / 604800000);
+      label = `${weeks} ${weeks === 1 ? "week" : "weeks"} ago`;
+    } else if (diff < 31556952000) {
+      // ~365.25 days (average year)
+      const months = Math.floor(diff / 2629746000);
+      label = `${months} ${months === 1 ? "month" : "months"} ago`;
+    } else {
+      const years = Math.floor(diff / 31556952000);
+      label = `${years} ${years === 1 ? "year" : "years"} ago`;
+    }
+
+    setSignal(label);
+  }
+
+  // Initial update
+  update();
+
+  // Register with global updater
+  timeSignals.add(update);
+
+  // Start global updater if not already started
+  if (timeSignals.size === 1) {
+    startGlobalTimeUpdater();
+  }
+
+  // Cleanup function
+  const destroy = () => {
+    timeSignals.delete(update);
+
+    // Stop global updater if no more signals
+    if (timeSignals.size === 0) {
+      stopGlobalTimeUpdater();
+    }
+  };
+
+  return {
+    signal,
+    destroy,
+    update, // Allow manual updates
+  };
+}
+
+// Format duration in seconds to human readable format
+export function formatDuration(seconds: number): string {
+  if (isNaN(seconds) || seconds < 0) return "0:00";
+
+  const hours = Math.floor(seconds / 3600);
+  const minutes = Math.floor((seconds % 3600) / 60);
+  const secs = Math.floor(seconds % 60);
+
+  if (hours > 0) {
+    return `${hours}:${minutes.toString().padStart(2, "0")}:${secs.toString().padStart(2, "0")}`;
+  } else {
+    return `${minutes}:${secs.toString().padStart(2, "0")}`;
+  }
+}
+
+// Format total playlist duration
+export function formatPlaylistDuration(totalSeconds: number): string {
+  if (isNaN(totalSeconds) || totalSeconds < 0) return "0 minutes";
+
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+
+  if (hours > 0) {
+    const hourText = hours === 1 ? "hour" : "hours";
+    if (minutes > 0) {
+      const minuteText = minutes === 1 ? "minute" : "minutes";
+      return `${hours} ${hourText}, ${minutes} ${minuteText}`;
+    } else {
+      return `${hours} ${hourText}`;
+    }
+  } else {
+    const minuteText = minutes === 1 ? "minute" : "minutes";
+    return `${minutes} ${minuteText}`;
+  }
+}
+
+// Format absolute timestamp to readable date
+export function formatAbsoluteDate(timestamp: number): string {
+  const date = new Date(timestamp);
+  const now = new Date();
+  const diff = now.getTime() - timestamp;
+
+  // If today, show time only
+  if (diff < 86400000 && date.getDate() === now.getDate()) {
+    return date.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+  }
+
+  // If this year, show month and day
+  if (date.getFullYear() === now.getFullYear()) {
+    return date.toLocaleDateString([], { month: "short", day: "numeric" });
+  }
+
+  // Otherwise show full date
+  return date.toLocaleDateString([], {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+  });
+}
+
+// Get time of day greeting
+export function getTimeGreeting(): string {
+  const hour = new Date().getHours();
+
+  if (hour < 12) return "good morning";
+  if (hour < 17) return "good afternoon";
+  if (hour < 21) return "good evening";
+  return "good night";
+}
+
+// Global cleanup function
+export function cleanupTimeUtils(): void {
+  timeSignals.clear();
+  stopGlobalTimeUpdater();
+}

package/src/utils/typeGuards.ts

@@ -0,0 +1,171 @@
+// type guards to avoid casting and improve type safety
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import type { Playlist, Song } from "../types/playlist.js";
+
+// type guard for checking if a value is a playlist
+export function isPlaylist(value: unknown): value is Playlist {
+  if (!value || typeof value !== "object") return false;
+
+  const obj = value as Record<string, unknown>;
+  return (
+    typeof obj.id === "string" &&
+    typeof obj.title === "string" &&
+    typeof obj.createdAt === "number" &&
+    typeof obj.updatedAt === "number" &&
+    Array.isArray(obj.songIds) &&
+    obj.songIds.every((id: unknown) => typeof id === "string")
+  );
+}
+
+// type guard for checking if a value is a song
+export function isSong(value: unknown): value is Song {
+  if (!value || typeof value !== "object") return false;
+
+  const obj = value as Record<string, unknown>;
+  return (
+    typeof obj.id === "string" &&
+    typeof obj.mimeType === "string" &&
+    typeof obj.originalFilename === "string" &&
+    typeof obj.title === "string" &&
+    typeof obj.artist === "string" &&
+    typeof obj.album === "string" &&
+    typeof obj.duration === "number" &&
+    typeof obj.position === "number" &&
+    typeof obj.createdAt === "number" &&
+    typeof obj.updatedAt === "number" &&
+    typeof obj.playlistId === "string"
+  );
+}
+
+// type guard for valid store names
+export function isValidStoreName(name: string): name is "playlists" | "songs" {
+  return name === "playlists" || name === "songs";
+}
+
+// type guard for ensuring an object has an id
+export function hasId(obj: unknown): obj is { id: string } {
+  return (
+    typeof obj === "object" &&
+    obj !== null &&
+    typeof (obj as any).id === "string"
+  );
+}
+
+// type guard for ensuring an object has songIds array
+export function hasSongIds(obj: unknown): obj is { songIds: string[] } {
+  return (
+    typeof obj === "object" &&
+    obj !== null &&
+    Array.isArray((obj as any).songIds) &&
+    (obj as any).songIds.every((id: unknown) => typeof id === "string")
+  );
+}
+
+// type guard for checking if value has audio data
+export function hasAudioData(
+  obj: unknown
+): obj is { audioData: ArrayBuffer; mimeType: string } {
+  return (
+    typeof obj === "object" &&
+    obj !== null &&
+    (obj as any).audioData instanceof ArrayBuffer &&
+    (obj as any).audioData.byteLength > 0 &&
+    typeof (obj as any).mimeType === "string"
+  );
+}
+
+// type guard for checking if value has image data
+export function hasImageData(obj: unknown): obj is {
+  imageData?: ArrayBuffer;
+  thumbnailData?: ArrayBuffer;
+  imageType?: string;
+} {
+  if (!obj || typeof obj !== "object") return false;
+
+  const item = obj as any;
+  const hasImage =
+    item.imageData instanceof ArrayBuffer && item.imageData.byteLength > 0;
+  const hasThumbnail =
+    item.thumbnailData instanceof ArrayBuffer &&
+    item.thumbnailData.byteLength > 0;
+  const hasType = typeof item.imageType === "string";
+
+  return (hasImage || hasThumbnail) && hasType;
+}
+
+// create a properly typed object from unknown, with validation
+export function createTypedPlaylist(data: unknown): Playlist | null {
+  if (!isPlaylist(data)) return null;
+  return data;
+}
+
+// create a properly typed song from unknown, with validation
+export function createTypedSong(data: unknown): Song | null {
+  if (!isSong(data)) return null;
+  return data;
+}
+
+// safe property access with default values
+export function safeString(
+  obj: unknown,
+  key: string,
+  defaultValue = ""
+): string {
+  if (!obj || typeof obj !== "object") return defaultValue;
+  const value = (obj as Record<string, unknown>)[key];
+  return typeof value === "string" ? value : defaultValue;
+}
+
+export function safeNumber(
+  obj: unknown,
+  key: string,
+  defaultValue = 0
+): number {
+  if (!obj || typeof obj !== "object") return defaultValue;
+  const value = (obj as Record<string, unknown>)[key];
+  return typeof value === "number" ? value : defaultValue;
+}
+
+export function safeArray<T>(
+  obj: unknown,
+  key: string,
+  defaultValue: T[] = []
+): T[] {
+  if (!obj || typeof obj !== "object") return defaultValue;
+  const value = (obj as Record<string, unknown>)[key];
+  return Array.isArray(value) ? value : defaultValue;
+}
+
+// type narrowing helpers for mutations
+export function assertPlaylist(value: unknown): asserts value is Playlist {
+  if (!isPlaylist(value)) {
+    throw new Error("expected playlist object");
+  }
+}
+
+export function assertSong(value: unknown): asserts value is Song {
+  if (!isSong(value)) {
+    throw new Error("expected song object");
+  }
+}
+
+// safe merge for updates (no casting needed)
+export function mergePlaylistUpdates(
+  existing: Playlist,
+  updates: Partial<Playlist>
+): Playlist {
+  return {
+    ...existing,
+    ...updates,
+    updatedAt: Date.now(),
+  };
+}
+
+export function mergeSongUpdates(existing: Song, updates: Partial<Song>): Song {
+  return {
+    ...existing,
+    ...updates,
+    updatedAt: Date.now(),
+  };
+}