@bendyline/squisq 0.1.2 → 1.1.0

package/src/storage/ContentContainer.ts

@@ -0,0 +1,200 @@
+/**
+ * ContentContainer — virtual file system for document containers.
+ *
+ * A Squisq document is more than just markdown: it's a container of files
+ * including the primary markdown document, images, audio, timing data, and
+ * other media. ContentContainer provides an abstract async file system
+ * interface for reading, writing, and listing these files.
+ *
+ * Paths are forward-slash separated strings relative to the container root
+ * (e.g., 'images/hero.jpg', 'index.md'). No leading slash.
+ *
+ * Implementations:
+ * - MemoryContentContainer — in-memory Map (for zip import, tests, transient use)
+ * - SlotContentContainer — backed by IndexedDB slot storage (in the site package)
+ */
+
+/**
+ * Metadata about a file in a ContentContainer.
+ */
+export interface ContentEntry {
+  /** Relative path within the container (e.g., 'images/hero.jpg') */
+  path: string;
+  /** MIME type (e.g., 'image/jpeg') */
+  mimeType: string;
+  /** File size in bytes */
+  size: number;
+}
+
+/**
+ * Abstract async file system for document containers.
+ *
+ * All paths are forward-slash separated, relative to the container root,
+ * with no leading slash. Example: 'images/hero.jpg', 'index.md'.
+ */
+export interface ContentContainer {
+  /** Read a file's binary content. Returns null if the file does not exist. */
+  readFile(path: string): Promise<ArrayBuffer | null>;
+
+  /** Write a file. Creates or overwrites. */
+  writeFile(path: string, data: ArrayBuffer | Uint8Array, mimeType?: string): Promise<void>;
+
+  /** Remove a file. No-op if the file does not exist. */
+  removeFile(path: string): Promise<void>;
+
+  /**
+   * List files in the container.
+   * @param prefix — Optional path prefix to filter by (e.g., 'images/')
+   */
+  listFiles(prefix?: string): Promise<ContentEntry[]>;
+
+  /** Check whether a file exists. */
+  exists(path: string): Promise<boolean>;
+
+  /**
+   * Find the primary markdown document path.
+   *
+   * Discovery order: index.md → doc.md → document.md → first *.md at root.
+   * Returns null if no markdown file is found at the root level.
+   */
+  getDocumentPath(): Promise<string | null>;
+
+  /**
+   * Convenience: read the primary markdown document as a UTF-8 string.
+   * Returns null if no markdown file is found.
+   */
+  readDocument(): Promise<string | null>;
+
+  /**
+   * Convenience: write a markdown document.
+   * @param markdown — The markdown content
+   * @param filename — Filename to use (defaults to 'index.md')
+   */
+  writeDocument(markdown: string, filename?: string): Promise<void>;
+}
+
+// ============================================
+// Well-known markdown filenames in priority order
+// ============================================
+
+const MARKDOWN_PRIORITY = ['index.md', 'doc.md', 'document.md'];
+
+/**
+ * Find the primary markdown path from a list of file entries.
+ * Exported for reuse by other ContentContainer implementations.
+ */
+export function findDocumentPath(entries: ContentEntry[]): string | null {
+  // Only consider root-level files (no '/' in path)
+  const rootFiles = entries.filter((e) => !e.path.includes('/'));
+
+  for (const name of MARKDOWN_PRIORITY) {
+    if (rootFiles.some((e) => e.path.toLowerCase() === name)) {
+      return name;
+    }
+  }
+
+  // Fallback: first .md file at root
+  const firstMd = rootFiles.find((e) => e.path.toLowerCase().endsWith('.md'));
+  return firstMd?.path ?? null;
+}
+
+// ============================================
+// MemoryContentContainer
+// ============================================
+
+interface MemoryFile {
+  data: ArrayBuffer;
+  mimeType: string;
+}
+
+/**
+ * In-memory ContentContainer backed by a Map.
+ *
+ * Used for zip import (deserialize into memory), tests, and transient operations.
+ */
+export class MemoryContentContainer implements ContentContainer {
+  private files = new Map<string, MemoryFile>();
+
+  async readFile(path: string): Promise<ArrayBuffer | null> {
+    return this.files.get(path)?.data ?? null;
+  }
+
+  async writeFile(path: string, data: ArrayBuffer | Uint8Array, mimeType?: string): Promise<void> {
+    const buffer = data instanceof ArrayBuffer ? data : data.slice().buffer;
+    this.files.set(path, {
+      data: buffer,
+      mimeType: mimeType ?? guessMimeType(path),
+    });
+  }
+
+  async removeFile(path: string): Promise<void> {
+    this.files.delete(path);
+  }
+
+  async listFiles(prefix?: string): Promise<ContentEntry[]> {
+    const entries: ContentEntry[] = [];
+    for (const [path, file] of this.files) {
+      if (prefix && !path.startsWith(prefix)) continue;
+      entries.push({
+        path,
+        mimeType: file.mimeType,
+        size: file.data.byteLength,
+      });
+    }
+    return entries;
+  }
+
+  async exists(path: string): Promise<boolean> {
+    return this.files.has(path);
+  }
+
+  async getDocumentPath(): Promise<string | null> {
+    return findDocumentPath(await this.listFiles());
+  }
+
+  async readDocument(): Promise<string | null> {
+    const docPath = await this.getDocumentPath();
+    if (!docPath) return null;
+    const data = await this.readFile(docPath);
+    if (!data) return null;
+    return new TextDecoder().decode(data);
+  }
+
+  async writeDocument(markdown: string, filename?: string): Promise<void> {
+    const name = filename ?? 'index.md';
+    const data = new TextEncoder().encode(markdown);
+    await this.writeFile(name, data, 'text/markdown');
+  }
+}
+
+// ============================================
+// MIME type guessing
+// ============================================
+
+const EXTENSION_MIME_MAP: Record<string, string> = {
+  '.md': 'text/markdown',
+  '.txt': 'text/plain',
+  '.json': 'application/json',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.png': 'image/png',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav',
+  '.ogg': 'audio/ogg',
+  '.css': 'text/css',
+  '.html': 'text/html',
+  '.js': 'application/javascript',
+};
+
+function guessMimeType(path: string): string {
+  const dot = path.lastIndexOf('.');
+  if (dot === -1) return 'application/octet-stream';
+  const ext = path.slice(dot).toLowerCase();
+  return EXTENSION_MIME_MAP[ext] ?? 'application/octet-stream';
+}

package/src/storage/MediaProviderFromContainer.ts

@@ -0,0 +1,92 @@
+/**
+ * MediaProviderFromContainer — bridges ContentContainer to MediaProvider.
+ *
+ * Creates a MediaProvider that resolves relative paths by reading binary data
+ * from a ContentContainer and generating blob URLs. Blob URLs are cached and
+ * revoked on dispose().
+ *
+ * This allows any ContentContainer (memory, slot-backed, zip-loaded) to be
+ * used with existing rendering components (DocPlayer, ImageLayer, VideoLayer)
+ * that consume MediaProvider.
+ */
+
+import type { MediaProvider, MediaEntry } from '../schemas/MediaProvider.js';
+import type { ContentContainer } from './ContentContainer.js';
+
+/**
+ * Create a MediaProvider backed by a ContentContainer.
+ *
+ * @param container — The ContentContainer to read/write media from
+ * @returns A MediaProvider that resolves paths to blob URLs
+ */
+export function createMediaProviderFromContainer(container: ContentContainer): MediaProvider {
+  const blobUrlCache = new Map<string, string>();
+
+  return {
+    async resolveUrl(relativePath: string): Promise<string> {
+      const cached = blobUrlCache.get(relativePath);
+      if (cached) return cached;
+
+      const data = await container.readFile(relativePath);
+      if (!data) return relativePath;
+
+      const entries = await container.listFiles();
+      const entry = entries.find((e) => e.path === relativePath);
+      const mimeType = entry?.mimeType ?? 'application/octet-stream';
+
+      const blob = new Blob([data], { type: mimeType });
+      const url = URL.createObjectURL(blob);
+      blobUrlCache.set(relativePath, url);
+      return url;
+    },
+
+    async listMedia(): Promise<MediaEntry[]> {
+      const entries = await container.listFiles();
+      return entries
+        .filter((e) => !e.path.toLowerCase().endsWith('.md'))
+        .map((e) => ({
+          name: e.path,
+          mimeType: e.mimeType,
+          size: e.size,
+        }));
+    },
+
+    async addMedia(
+      name: string,
+      data: ArrayBuffer | Blob | Uint8Array,
+      mimeType: string,
+    ): Promise<string> {
+      // Invalidate any cached blob URL for this path before overwriting
+      const cached = blobUrlCache.get(name);
+      if (cached) {
+        URL.revokeObjectURL(cached);
+        blobUrlCache.delete(name);
+      }
+
+      let buffer: ArrayBuffer | Uint8Array;
+      if (data instanceof Blob) {
+        buffer = await data.arrayBuffer();
+      } else {
+        buffer = data;
+      }
+      await container.writeFile(name, buffer, mimeType);
+      return name;
+    },
+
+    async removeMedia(relativePath: string): Promise<void> {
+      const cached = blobUrlCache.get(relativePath);
+      if (cached) {
+        URL.revokeObjectURL(cached);
+        blobUrlCache.delete(relativePath);
+      }
+      await container.removeFile(relativePath);
+    },
+
+    dispose(): void {
+      for (const url of blobUrlCache.values()) {
+        URL.revokeObjectURL(url);
+      }
+      blobUrlCache.clear();
+    },
+  };
+}

package/src/storage/index.ts

@@ -3,3 +3,6 @@ export { MemoryStorageAdapter } from './MemoryStorageAdapter.js';
 export { LocalStorageAdapter } from './LocalStorageAdapter.js';
 export { LocalForageAdapter } from './LocalForageAdapter.js';
 export type { LocalForageAdapterOptions } from './LocalForageAdapter.js';
+export type { ContentContainer, ContentEntry } from './ContentContainer.js';
+export { MemoryContentContainer, findDocumentPath } from './ContentContainer.js';
+export { createMediaProviderFromContainer } from './MediaProviderFromContainer.js';

package/src/timing/index.ts

@@ -0,0 +1,17 @@
+export {
+  DEFAULT_WORDS_PER_SECOND,
+  estimateSpokenWordCount,
+  countSpokenWords,
+  estimateTimeFromText,
+  calculatePrefixDuration,
+  estimateNarrationDuration,
+} from './narrationTiming.js';
+
+export { estimateReadingTime, estimateNarrationTime } from './readingTime.js';
+
+export type {
+  ReadingTimeEstimate,
+  ReadingTimeOptions,
+  NarrationTimeEstimate,
+  NarrationTimeOptions,
+} from './readingTime.js';

package/src/timing/narrationTiming.ts

@@ -0,0 +1,220 @@
+/**
+ * Narration timing estimation.
+ *
+ * Estimates how long text takes to speak aloud, accounting for:
+ * - Numbers spoken as multiple words (e.g., "1910" → "nineteen ten")
+ * - Pauses at commas
+ * - Year pronunciation conventions (1000–2099)
+ *
+ * Ported from qualla-internal's AudioTiming.ts (pure functions, no Node.js deps).
+ */
+
+/** Numbers are spoken more slowly than regular words (1.3× multiplier). */
+const NUMBER_SPEAKING_MULTIPLIER = 1.3;
+
+/** Comma pause in "word equivalents" — speakers pause ~0.3 words at commas. */
+const COMMA_PAUSE_PENALTY = 0.3;
+
+/** Default speaking rate in words per second (~150 WPM). */
+export const DEFAULT_WORDS_PER_SECOND = 2.5;
+
+/**
+ * Estimate how many "spoken word equivalents" a single token represents.
+ * Numbers get expanded (e.g., "175,000" → ~5 words × 1.3 multiplier).
+ */
+export function estimateSpokenWordCount(token: string): number {
+  const cleaned = token.replace(/,/g, '');
+  const num = parseFloat(cleaned);
+
+  if (isNaN(num) || !isFinite(num)) {
+    return 1; // Not a number — count as 1 word
+  }
+
+  return estimateNumberWordCount(cleaned, num) * NUMBER_SPEAKING_MULTIPLIER;
+}
+
+/**
+ * Raw word count for a number (before the speaking multiplier).
+ */
+function estimateNumberWordCount(cleaned: string, num: number): number {
+  // Handle decimals: "3.14" → words("3") + "point" + 2 digits
+  if (cleaned.includes('.')) {
+    const [whole, decimal] = cleaned.split('.');
+    const wholeNum = parseFloat(whole) || 0;
+    return estimateNumberWordCount(whole, wholeNum) + 1 + decimal.length;
+  }
+
+  const absNum = Math.abs(num);
+  let words = num < 0 ? 1 : 0; // "negative" / "minus"
+
+  if (absNum === 0) return 1; // "zero"
+
+  // Years (1000–2099) are spoken as two two-digit groups:
+  // "1910" → "nineteen ten", "2024" → "twenty twenty-four"
+  if (absNum >= 1000 && absNum <= 2099 && Number.isInteger(absNum)) {
+    const yearStr = absNum.toString();
+    if (yearStr.length === 4) {
+      const firstTwo = parseInt(yearStr.slice(0, 2));
+      const lastTwo = parseInt(yearStr.slice(2));
+
+      // First part
+      if (firstTwo >= 10 && firstTwo <= 19) {
+        words += 1;
+      } else if (firstTwo >= 20 && firstTwo <= 99) {
+        words += firstTwo % 10 === 0 ? 1 : 2;
+      } else {
+        words += 2; // "two thousand"
+      }
+
+      // Second part
+      if (lastTwo === 0) {
+        if (firstTwo >= 10 && firstTwo <= 99 && firstTwo !== 20) {
+          words += 1; // "hundred"
+        }
+      } else if (lastTwo >= 1 && lastTwo <= 9) {
+        words += 2; // "oh five"
+      } else if (lastTwo >= 10 && lastTwo <= 19) {
+        words += 1;
+      } else {
+        words += lastTwo % 10 === 0 ? 1 : 2;
+      }
+
+      return Math.max(words, 2);
+    }
+  }
+
+  // General number handling — each magnitude group adds words
+  let remaining = absNum;
+
+  if (remaining >= 1_000_000_000) {
+    const billions = Math.floor(remaining / 1_000_000_000);
+    words += estimateNumberWordCount(String(billions), billions);
+    words += 1; // "billion"
+    remaining %= 1_000_000_000;
+  }
+
+  if (remaining >= 1_000_000) {
+    const millions = Math.floor(remaining / 1_000_000);
+    words += estimateNumberWordCount(String(millions), millions);
+    words += 1; // "million"
+    remaining %= 1_000_000;
+  }
+
+  if (remaining >= 1_000) {
+    const thousands = Math.floor(remaining / 1_000);
+    words += estimateNumberWordCount(String(thousands), thousands);
+    words += 1; // "thousand"
+    remaining %= 1_000;
+  }
+
+  if (remaining >= 100) {
+    words += 2; // digit + "hundred"
+    remaining %= 100;
+  }
+
+  if (remaining >= 1) {
+    if (remaining >= 20) {
+      words += remaining % 10 === 0 ? 1 : 2;
+    } else {
+      words += 1; // 1–19
+    }
+  }
+
+  return Math.max(words, 1);
+}
+
+/**
+ * Count "spoken word equivalents" in a block of text,
+ * expanding numbers and adding comma pauses.
+ */
+export function countSpokenWords(text: string): number {
+  const tokens = text.split(/\s+/).filter((w) => w.length > 0);
+  let count = 0;
+
+  for (const token of tokens) {
+    // Strip punctuation only at token boundaries so internal punctuation
+    // (e.g., decimals like "3.14" or digit-grouping commas "1,000") is preserved.
+    const stripped = token.replace(/^[.,!?;:'"()[\]{}]+|[.,!?;:'"()[\]{}]+$/g, '');
+    count += estimateSpokenWordCount(stripped);
+
+    // Count only punctuation commas for pauses: exclude digit-grouping commas
+    // (i.e., commas with digits on both sides, like in "1,234").
+    let punctuationCommaCount = 0;
+    for (let i = 0; i < token.length; i++) {
+      if (token[i] === ',') {
+        const prev = i > 0 ? token[i - 1] : '';
+        const next = i < token.length - 1 ? token[i + 1] : '';
+        const prevIsDigit = prev >= '0' && prev <= '9';
+        const nextIsDigit = next >= '0' && next <= '9';
+        if (!(prevIsDigit && nextIsDigit)) {
+          punctuationCommaCount++;
+        }
+      }
+    }
+    count += punctuationCommaCount * COMMA_PAUSE_PENALTY;
+  }
+
+  return count;
+}
+
+/**
+ * Estimate audio time at a character offset using word-proportion mapping.
+ *
+ * Given the full source text and a character position, returns the
+ * estimated time (in seconds) at which that position would be spoken.
+ *
+ * @param text - Full source text
+ * @param charOffset - Character offset to estimate timing for
+ * @param totalDuration - Total audio duration in seconds
+ * @returns Estimated time in seconds
+ */
+export function estimateTimeFromText(
+  text: string,
+  charOffset: number,
+  totalDuration: number,
+): number {
+  const textBefore = text.slice(0, charOffset);
+  const spokenWordsBefore = countSpokenWords(textBefore);
+  const totalSpokenWords = countSpokenWords(text);
+
+  if (totalSpokenWords === 0) return 0;
+  return (spokenWordsBefore / totalSpokenWords) * totalDuration;
+}
+
+/**
+ * Estimate how long a spoken prefix adds to audio duration.
+ *
+ * When audio includes a spoken title or header before the main content,
+ * this calculates the extra duration to offset timing calculations.
+ *
+ * @param prefix - Prefix text (e.g., an article title spoken before the body)
+ * @param wordsPerSecond - Speaking rate (default: 2.5)
+ * @returns Estimated duration in seconds
+ */
+export function calculatePrefixDuration(
+  prefix: string,
+  wordsPerSecond: number = DEFAULT_WORDS_PER_SECOND,
+): number {
+  if (!prefix) return 0;
+
+  const words = prefix.split(/\s+/).filter((w) => w.length > 0);
+  const newlineCount = (prefix.match(/\n\n/g) || []).length;
+  const pauseTime = newlineCount * 0.5;
+
+  return words.length / wordsPerSecond + pauseTime;
+}
+
+/**
+ * Estimate narration duration for a block of text.
+ *
+ * @param text - The text to estimate
+ * @param wordsPerSecond - Speaking rate (default: 2.5, i.e. ~150 WPM)
+ * @returns Duration in seconds
+ */
+export function estimateNarrationDuration(
+  text: string,
+  wordsPerSecond: number = DEFAULT_WORDS_PER_SECOND,
+): number {
+  const spokenWords = countSpokenWords(text);
+  return spokenWords / wordsPerSecond;
+}

package/src/timing/readingTime.ts

@@ -0,0 +1,94 @@
+/**
+ * Reading time estimation.
+ *
+ * Estimates how long it takes to read text silently vs. narrate it aloud.
+ * Uses configurable words-per-minute rates.
+ */
+
+import { countSpokenWords, DEFAULT_WORDS_PER_SECOND } from './narrationTiming.js';
+
+/** Default silent reading rate (adults average ~200–250 WPM). */
+const DEFAULT_READING_WPM = 200;
+
+/** Result of a reading-time estimate. */
+export interface ReadingTimeEstimate {
+  /** Number of words (plain word count, not spoken equivalents). */
+  words: number;
+  /** Estimated minutes (decimal). */
+  minutes: number;
+  /** Estimated seconds (rounded). */
+  seconds: number;
+}
+
+/** Options for reading-time estimation. */
+export interface ReadingTimeOptions {
+  /** Words per minute for silent reading (default: 200). */
+  wordsPerMinute?: number;
+}
+
+/**
+ * Estimate silent reading time for a block of text.
+ *
+ * @param text - The text to estimate
+ * @param options - Optional configuration
+ * @returns Word count + time estimate
+ */
+export function estimateReadingTime(
+  text: string,
+  options?: ReadingTimeOptions,
+): ReadingTimeEstimate {
+  const configuredWpm = options?.wordsPerMinute;
+  const wpm =
+    typeof configuredWpm === 'number' && configuredWpm > 0 ? configuredWpm : DEFAULT_READING_WPM;
+  const words = text.split(/\s+/).filter((w) => w.length > 0).length;
+  const minutes = words / wpm;
+
+  return {
+    words,
+    minutes,
+    seconds: Math.round(minutes * 60),
+  };
+}
+
+/** Result of a narration-time estimate. */
+export interface NarrationTimeEstimate {
+  /** Spoken word equivalents (numbers expanded, comma pauses added). */
+  spokenWords: number;
+  /** Estimated minutes (decimal). */
+  minutes: number;
+  /** Estimated seconds (rounded). */
+  seconds: number;
+}
+
+/** Options for narration-time estimation. */
+export interface NarrationTimeOptions {
+  /** Words per second for narration (default: 2.5 ≈ 150 WPM). */
+  wordsPerSecond?: number;
+}
+
+/**
+ * Estimate narration (spoken) time for a block of text.
+ *
+ * Unlike silent reading, this accounts for numbers being spoken as
+ * multiple words and pauses at commas.
+ *
+ * @param text - The text to estimate
+ * @param options - Optional configuration
+ * @returns Spoken word equivalents + time estimate
+ */
+export function estimateNarrationTime(
+  text: string,
+  options?: NarrationTimeOptions,
+): NarrationTimeEstimate {
+  const providedWps = options?.wordsPerSecond;
+  const wps =
+    typeof providedWps === 'number' && providedWps > 0 ? providedWps : DEFAULT_WORDS_PER_SECOND;
+  const spokenWords = countSpokenWords(text);
+  const totalSeconds = spokenWords / wps;
+
+  return {
+    spokenWords,
+    minutes: totalSeconds / 60,
+    seconds: Math.round(totalSeconds),
+  };
+}