@bendyline/squisq 2.1.0 → 2.2.0

package/src/storage/MediaProviderFromContainer.ts

@@ -1,92 +0,0 @@
-/**
- * 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/MemoryStorageAdapter.ts

@@ -1,37 +0,0 @@
-/**
- * In-memory storage adapter for testing and SSR environments.
- * Data does not persist across page reloads.
- */
-
-import type { StorageAdapter } from './Storage.js';
-
-export class MemoryStorageAdapter implements StorageAdapter {
-  readonly supportsEnumeration = true;
-  private store = new Map<string, string>();
-
-  async get<T>(key: string): Promise<T | null> {
-    const val = this.store.get(key);
-    if (val === undefined) return null;
-    try {
-      return JSON.parse(val) as T;
-    } catch {
-      return null;
-    }
-  }
-
-  async set<T>(key: string, value: T): Promise<void> {
-    this.store.set(key, JSON.stringify(value));
-  }
-
-  async remove(key: string): Promise<void> {
-    this.store.delete(key);
-  }
-
-  async clear(): Promise<void> {
-    this.store.clear();
-  }
-
-  async keys(): Promise<string[]> {
-    return Array.from(this.store.keys());
-  }
-}

package/src/storage/ScopedContentContainer.ts

@@ -1,143 +0,0 @@
-/**
- * ScopedContentContainer
- *
- * Wraps a parent {@link ContentContainer} and prefixes every path with a
- * fixed subfolder, presenting that subfolder as the root. Useful for
- * sidecar folders (e.g. `<imagebasename>_files/`) where a component
- * should be able to read/write/list files relative to its own root
- * without knowing where it lives in the parent tree.
- *
- * Scopes nest: `scopeContainer(scopeContainer(parent, 'a'), 'b')` is
- * equivalent to `scopeContainer(parent, 'a/b')`.
- *
- * `getDocumentPath()` always returns `null` for scoped sidecars — they
- * are not document roots.
- */
-
-import type { ContentContainer, ContentEntry } from './ContentContainer.js';
-
-interface NormalizePathOptions {
-  allowEmpty?: boolean;
-  preserveTrailingSlash?: boolean;
-}
-
-/**
- * Normalize a container-relative path without ever resolving traversal.
- * Backslashes are rejected rather than translated because a filesystem-backed
- * parent may interpret them as separators even when an in-memory parent does
- * not. Dot segments are similarly rejected instead of collapsed so an invalid
- * caller path can never escape after a later platform-specific normalization.
- */
-function normalizeRelativePath(
-  path: string,
-  label: 'prefix' | 'path',
-  options: NormalizePathOptions = {},
-): string {
-  const original = path;
-  let normalized = label === 'prefix' ? path.trim() : path;
-  if (normalized.includes('\\')) {
-    throw new Error(`ScopedContentContainer: ${label} must use forward slashes: ${original}`);
-  }
-
-  const hadTrailingSlash = normalized.endsWith('/');
-  normalized = normalized.replace(/^\/+|\/+$/g, '');
-  const segments = normalized === '' ? [] : normalized.split('/').filter(Boolean);
-  if (segments.some((segment) => segment === '.' || segment === '..')) {
-    throw new Error(
-      `ScopedContentContainer: ${label} must not contain '.' or '..' segments: ${original}`,
-    );
-  }
-  if (segments.length === 0 && !options.allowEmpty) {
-    throw new Error(`ScopedContentContainer: ${label} must not be empty`);
-  }
-
-  const result = segments.join('/');
-  return options.preserveTrailingSlash && hadTrailingSlash && result ? `${result}/` : result;
-}
-
-/** Normalize a prefix: strip leading/trailing slashes, ensure no `..` segments. */
-function normalizePrefix(prefix: string): string {
-  return normalizeRelativePath(prefix, 'prefix');
-}
-
-/**
- * A ContentContainer view rooted at a subfolder of a parent container.
- * All paths passed to / returned from this container are relative to
- * the subfolder; the parent never sees an unprefixed path.
- */
-export class ScopedContentContainer implements ContentContainer {
-  private readonly parent: ContentContainer;
-  /** Prefix without trailing slash. */
-  readonly prefix: string;
-  /** Prefix with trailing slash. */
-  private readonly prefixSlash: string;
-
-  constructor(parent: ContentContainer, prefix: string) {
-    this.parent = parent;
-    this.prefix = normalizePrefix(prefix);
-    this.prefixSlash = `${this.prefix}/`;
-  }
-
-  private toParent(path: string, options: NormalizePathOptions = {}): string {
-    const normalized = normalizeRelativePath(path, 'path', options);
-    return this.prefixSlash + normalized;
-  }
-
-  /** Strip the prefix from a parent-space path. Returns null if the path is outside the scope. */
-  private fromParent(parentPath: string): string | null {
-    if (!parentPath.startsWith(this.prefixSlash)) return null;
-    return parentPath.slice(this.prefixSlash.length);
-  }
-
-  readFile(path: string): Promise<ArrayBuffer | null> {
-    return this.parent.readFile(this.toParent(path));
-  }
-
-  writeFile(path: string, data: ArrayBuffer | Uint8Array, mimeType?: string): Promise<void> {
-    return this.parent.writeFile(this.toParent(path), data, mimeType);
-  }
-
-  removeFile(path: string): Promise<void> {
-    return this.parent.removeFile(this.toParent(path));
-  }
-
-  async listFiles(prefix?: string): Promise<ContentEntry[]> {
-    const parentPrefix =
-      prefix == null
-        ? this.prefixSlash
-        : this.toParent(prefix, { allowEmpty: true, preserveTrailingSlash: true });
-    const entries = await this.parent.listFiles(parentPrefix);
-    const out: ContentEntry[] = [];
-    for (const e of entries) {
-      const local = this.fromParent(e.path);
-      if (local === null) continue;
-      out.push({ path: local, mimeType: e.mimeType, size: e.size });
-    }
-    return out;
-  }
-
-  exists(path: string): Promise<boolean> {
-    return this.parent.exists(this.toParent(path));
-  }
-
-  /** Sidecars are not document roots. */
-  async getDocumentPath(): Promise<string | null> {
-    return null;
-  }
-
-  async readDocument(): Promise<string | null> {
-    return null;
-  }
-
-  async writeDocument(): Promise<void> {
-    throw new Error(
-      'ScopedContentContainer is a sidecar view and does not support writeDocument(). ' +
-        'Write to a specific path with writeFile() instead.',
-    );
-  }
-}
-
-/** Factory: convenience wrapper for `new ScopedContentContainer(parent, prefix)`. */
-export function scopeContainer(parent: ContentContainer, prefix: string): ScopedContentContainer {
-  return new ScopedContentContainer(parent, prefix);
-}

package/src/storage/Storage.ts

@@ -1,28 +0,0 @@
-/**
- * Storage - Abstract persistence interface
- *
- * Defines the contract for persistent storage across different environments.
- * All values are JSON-serialized, so any serializable value can be stored.
- * Keys can be automatically namespaced with a configurable prefix.
- */
-
-/** Storage adapter interface - implemented by environment-specific adapters */
-export interface StorageAdapter {
-  /** Get a value by key, returns null if not found */
-  get<T>(key: string): Promise<T | null>;
-
-  /** Set a value for a key */
-  set<T>(key: string, value: T): Promise<void>;
-
-  /** Remove a value by key */
-  remove(key: string): Promise<void>;
-
-  /** Clear all stored values (within our namespace) */
-  clear(): Promise<void>;
-
-  /** Get all keys (within our namespace) */
-  keys(): Promise<string[]>;
-
-  /** Check if this adapter supports enumeration */
-  readonly supportsEnumeration: boolean;
-}

package/src/storage/index.ts

@@ -1,9 +0,0 @@
-export type { StorageAdapter } from './Storage.js';
-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 { ScopedContentContainer, scopeContainer } from './ScopedContentContainer.js';
-export { createMediaProviderFromContainer } from './MediaProviderFromContainer.js';

package/src/timing/index.ts

@@ -1,17 +0,0 @@
-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

@@ -1,220 +0,0 @@
-/**
- * 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

@@ -1,94 +0,0 @@
-/**
- * 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),
-  };
-}