@bendyline/squisq 1.5.2 → 2.0.1

package/src/spatial/Geohash.ts

@@ -194,6 +194,3 @@ export function geohashOverlapsBounds(
     hashWest > bounds.east
   );
 }
-
-// Re-export for backwards compatibility with existing imports.
-export { haversineDistance };

package/src/storage/ContentContainer.ts

@@ -92,9 +92,8 @@ export function findDocumentPath(entries: ContentEntry[]): string | null {
   const rootFiles = entries.filter((e) => !e.path.includes('/'));
 
   for (const name of MARKDOWN_PRIORITY) {
-    if (rootFiles.some((e) => e.path.toLowerCase() === name)) {
-      return name;
-    }
+    const match = rootFiles.find((e) => e.path.toLowerCase() === name);
+    if (match) return match.path;
   }
 
   // Fallback: first .md file at root
@@ -120,21 +119,30 @@ 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;
+    const stored = this.files.get(path)?.data;
+    // A container owns its bytes. Returning the backing buffer would let a
+    // caller mutate stored state without going through writeFile().
+    return stored ? stored.slice(0) : null;
   }
 
   async writeFile(path: string, data: ArrayBuffer | Uint8Array, mimeType?: string): Promise<void> {
     // Copy to a standalone ArrayBuffer. Uint8Array/Buffer may share a larger
     // backing buffer (e.g., Node's buffer pool), so we must slice to the
     // exact byte range to avoid storing stale pool data.
-    let buffer: ArrayBuffer;
-    if (data instanceof ArrayBuffer) {
-      buffer = data;
+    // ArrayBuffer.isView is cross-realm-safe (unlike `instanceof
+    // ArrayBuffer`, which fails for values created in jsdom/iframes).
+    let source: Uint8Array;
+    if (ArrayBuffer.isView(data)) {
+      source = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
     } else {
-      buffer = data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength) as ArrayBuffer;
+      source = new Uint8Array(data);
     }
+    // Always materialize in this realm, including for iframe ArrayBuffers and
+    // views backed by SharedArrayBuffer.
+    const owned = new Uint8Array(source.byteLength);
+    owned.set(source);
     this.files.set(path, {
-      data: buffer,
+      data: owned.buffer,
       mimeType: mimeType ?? guessMimeType(path),
     });
   }

package/src/storage/ScopedContentContainer.ts

@@ -16,20 +16,48 @@
 
 import type { ContentContainer, ContentEntry } from './ContentContainer.js';
 
-/** Normalize a prefix: strip leading/trailing slashes, ensure no `..` segments. */
-function normalizePrefix(prefix: string): string {
-  let p = prefix.trim();
-  while (p.startsWith('/')) p = p.slice(1);
-  while (p.endsWith('/')) p = p.slice(0, -1);
-  if (p.length === 0) {
-    throw new Error('ScopedContentContainer: prefix must not be empty');
+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}`);
   }
-  if (p.split('/').some((seg) => seg === '..' || seg === '.')) {
+
+  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: prefix must not contain '.' or '..' segments: ${prefix}`,
+      `ScopedContentContainer: ${label} must not contain '.' or '..' segments: ${original}`,
     );
   }
-  return p;
+  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');
 }
 
 /**
@@ -50,10 +78,9 @@ export class ScopedContentContainer implements ContentContainer {
     this.prefixSlash = `${this.prefix}/`;
   }
 
-  private toParent(path: string): string {
-    let p = path;
-    while (p.startsWith('/')) p = p.slice(1);
-    return this.prefixSlash + p;
+  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. */
@@ -75,7 +102,10 @@ export class ScopedContentContainer implements ContentContainer {
   }
 
   async listFiles(prefix?: string): Promise<ContentEntry[]> {
-    const parentPrefix = prefix ? this.toParent(prefix) : this.prefixSlash;
+    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) {

package/src/transform/applyTransform.ts

@@ -10,7 +10,7 @@
 
 import type { Doc } from '../schemas/Doc.js';
 import type { DocBlock, TitleBlockInput, SectionHeaderInput } from '../schemas/BlockTemplates.js';
-import type { TransformStyleId, TransformOptions, TransformResult } from './types.js';
+import type { TransformStyleInput, TransformOptions, TransformResult } from './types.js';
 import { resolveTransformStyle } from './registry.js';
 import { analyzeBlocks, extractDocImages } from './blockAnalyzer.js';
 import { selectAndBuild } from './templateSelector.js';
@@ -22,16 +22,16 @@ import { hashString } from '../random/SeededRandom.js';
  * optimized for visual presentation.
  *
  * @param doc - The source Doc (not mutated).
- * @param styleId - Registered transform style id (e.g. 'documentary', 'magazine').
- * @param options - Optional seed, images, theme override.
+ * @param style - Built-in/registry id or a call-scoped declarative style.
+ * @param options - Optional seed, images, theme override, and explicit registry.
  * @returns TransformResult with the new Doc and stats.
  */
 export function applyTransform(
   doc: Doc,
-  styleId: TransformStyleId,
+  style: TransformStyleInput,
   options?: TransformOptions,
 ): TransformResult {
-  const baseConfig = resolveTransformStyle(styleId);
+  const baseConfig = resolveTransformStyle(style, options?.registry);
   const config = options?.overrides
     ? { ...baseConfig, ...options.overrides, id: baseConfig.id }
     : baseConfig;

package/src/transform/index.ts

@@ -1,5 +1,5 @@
 export { applyTransform } from './applyTransform.js';
-export { registerTransformStyle, unregisterTransformStyle } from './registry.js';
+export { createTransformStyleRegistry } from './registry.js';
 
 export {
   resolveTransformStyle,
@@ -10,8 +10,10 @@ export {
 
 export type {
   TransformStyleId,
+  TransformStyleInput,
   TransformStyleSummary,
   TransformStyleConfig,
+  TransformStyleRegistry,
   TransformImage,
   TransformOptions,
   TransformResult,

package/src/transform/registry.ts

@@ -1,78 +1,198 @@
 /**
  * Transform Style Registry
  *
- * Central registry of built-in transform styles plus a dynamic
- * registration API. Follows the same pattern as themeLibrary.ts /
- * `registerTheme` — registered styles take precedence over built-ins,
- * unknown ids fall back to the default.
+ * Immutable built-in lookup plus explicit caller-owned custom registries.
+ * There is deliberately no process-global mutable registry.
  */
 
-import type { TransformStyleConfig, TransformStyleSummary } from './types.js';
+import type { TransformStyleConfig, TransformStyleInput, TransformStyleRegistry } from './types.js';
 import { documentaryStyle } from './styles/documentary.js';
 import { magazineStyle } from './styles/magazine.js';
 import { dataDrivenStyle } from './styles/dataDriven.js';
 import { narrativeStyle } from './styles/narrative.js';
 import { minimalStyle } from './styles/minimal.js';
+import { cloneAndFreezeData } from '../internal/immutable.js';
 
 /** All built-in transform styles, keyed by id. */
-const TRANSFORM_STYLES: Record<string, TransformStyleConfig> = {
-  [documentaryStyle.id]: documentaryStyle,
-  [magazineStyle.id]: magazineStyle,
-  [dataDrivenStyle.id]: dataDrivenStyle,
-  [narrativeStyle.id]: narrativeStyle,
-  [minimalStyle.id]: minimalStyle,
-};
-
-/**
- * Id aliases: the data-driven style's file/export are named `dataDriven`
- * but its registered id is hyphenated — accept both.
- */
-const STYLE_ALIASES: Record<string, string> = {
-  dataDriven: 'data-driven',
-};
-
-/** Host-registered custom styles (registered ids win over built-ins). */
-const registeredStyles = new Map<string, TransformStyleConfig>();
+const TRANSFORM_STYLES: Readonly<Record<string, TransformStyleConfig>> = Object.freeze({
+  [documentaryStyle.id]: cloneAndFreezeData(documentaryStyle),
+  [magazineStyle.id]: cloneAndFreezeData(magazineStyle),
+  [dataDrivenStyle.id]: cloneAndFreezeData(dataDrivenStyle),
+  [narrativeStyle.id]: cloneAndFreezeData(narrativeStyle),
+  [minimalStyle.id]: cloneAndFreezeData(minimalStyle),
+});
 
 /** Default style used when no id is provided. */
 export const DEFAULT_TRANSFORM_STYLE_ID = 'documentary';
 
-/**
- * Register (or replace) a custom transform style at runtime. Hosts use
- * this the same way they use `registerTheme` — to add product-specific
- * styles without forking the registry.
- */
-export function registerTransformStyle(style: TransformStyleConfig): void {
-  registeredStyles.set(style.id, style);
+const EXTRACTION_TYPES = new Set([
+  'stat',
+  'date',
+  'quote',
+  'comparison',
+  'fact',
+  'impactLine',
+  'list',
+  'definition',
+]);
+const TRANSITION_STYLES = new Set(['cut', 'fade', 'dissolve', 'mixed']);
+
+function validateTransformStyle(style: TransformStyleConfig): void {
+  const candidate = style as unknown as Record<string, unknown>;
+  const fail = (message: string): never => {
+    throw new TypeError(`Invalid transform style: ${message}`);
+  };
+  for (const key of ['id', 'name', 'description']) {
+    if (typeof candidate[key] !== 'string' || !(candidate[key] as string).trim()) {
+      fail(`${key} must be a non-empty string`);
+    }
+  }
+  for (const key of ['minConfidence', 'transformRatio']) {
+    const value = candidate[key];
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1) {
+      fail(`${key} must be a finite number between 0 and 1`);
+    }
+  }
+  if (
+    !Array.isArray(candidate.preferredTypes) ||
+    candidate.preferredTypes.some((type) => !EXTRACTION_TYPES.has(type))
+  ) {
+    fail('preferredTypes contains an unknown extraction type');
+  }
+  if (
+    !Array.isArray(candidate.colorSchemes) ||
+    candidate.colorSchemes.length === 0 ||
+    candidate.colorSchemes.some((scheme) => typeof scheme !== 'string' || !scheme)
+  ) {
+    fail('colorSchemes must contain at least one non-empty string');
+  }
+  for (const key of ['insertSectionHeaders', 'interleaveImages']) {
+    if (typeof candidate[key] !== 'boolean') fail(`${key} must be a boolean`);
+  }
+  const blocks = candidate.blocksPerSection as { max?: unknown } | undefined;
+  if (!blocks || !Number.isInteger(blocks.max) || (blocks.max as number) < 1) {
+    fail('blocksPerSection.max must be a positive integer');
+  }
+  if (
+    typeof candidate.transitionStyle !== 'string' ||
+    !TRANSITION_STYLES.has(candidate.transitionStyle)
+  ) {
+    fail('transitionStyle must be cut, fade, dissolve, or mixed');
+  }
+  const templateMap = candidate.templateMap;
+  if (templateMap !== undefined) {
+    if (!templateMap || typeof templateMap !== 'object' || Array.isArray(templateMap)) {
+      fail('templateMap must be an object');
+    }
+    for (const [type, template] of Object.entries(templateMap as Record<string, unknown>)) {
+      if (!EXTRACTION_TYPES.has(type) || typeof template !== 'string' || !template) {
+        fail('templateMap must map known extraction types to non-empty template names');
+      }
+    }
+  }
+  if (
+    candidate.suggestedThemeId !== undefined &&
+    (typeof candidate.suggestedThemeId !== 'string' || !candidate.suggestedThemeId)
+  ) {
+    fail('suggestedThemeId must be a non-empty string');
+  }
+  const pacingValue = candidate.pacing;
+  if (pacingValue !== undefined) {
+    if (!pacingValue || typeof pacingValue !== 'object' || Array.isArray(pacingValue)) {
+      fail('pacing must be an object');
+    }
+    const pacing = pacingValue as { intro?: unknown; outro?: unknown };
+    for (const key of ['intro', 'outro'] as const) {
+      if (pacing[key] !== undefined && typeof pacing[key] !== 'boolean') {
+        fail(`pacing.${key} must be a boolean`);
+      }
+    }
+  }
+  const budget = candidate.budget as { slidesPerMinute?: unknown } | undefined;
+  if (
+    candidate.budget !== undefined &&
+    (!budget || typeof budget !== 'object' || Array.isArray(budget))
+  ) {
+    fail('budget must be an object');
+  }
+  if (budget && budget.slidesPerMinute !== undefined) {
+    const value = budget.slidesPerMinute;
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+      fail('budget.slidesPerMinute must be a positive finite number');
+    }
+  }
 }
 
-/** Remove a previously registered custom style. */
-export function unregisterTransformStyle(id: string): void {
-  registeredStyles.delete(id);
+function styleSnapshot(style: TransformStyleConfig): TransformStyleConfig {
+  validateTransformStyle(style);
+  return cloneAndFreezeData(style);
 }
 
-/**
- * Resolve a transform style by id. Registered styles win over built-ins;
- * aliases are honored; unknown ids fall back to the default style.
- */
-export function resolveTransformStyle(id: string): TransformStyleConfig {
-  const canonical = STYLE_ALIASES[id] ?? id;
+/** Stored documents emitted before the canonical kebab-case id. Not exported. */
+function normalizeBuiltinStyleId(id: string): string {
+  return id === 'dataDriven' ? 'data-driven' : id;
+}
+
+function resolveBuiltinStyle(id: string): TransformStyleConfig {
   return (
-    registeredStyles.get(canonical) ??
-    TRANSFORM_STYLES[canonical] ??
-    TRANSFORM_STYLES[DEFAULT_TRANSFORM_STYLE_ID]
+    TRANSFORM_STYLES[normalizeBuiltinStyleId(id)] ?? TRANSFORM_STYLES[DEFAULT_TRANSFORM_STYLE_ID]
   );
 }
 
-/** Get all known style ids (built-ins plus registered). */
-export function getTransformStyleIds(): string[] {
-  return Array.from(new Set([...Object.keys(TRANSFORM_STYLES), ...registeredStyles.keys()]));
+/**
+ * Create a caller-owned registry. Custom styles are validated, cloned, and
+ * deeply frozen at registration time. Built-in resolution remains in the
+ * top-level helpers, separate from the registry's caller-owned state.
+ */
+export function createTransformStyleRegistry(
+  initialStyles: readonly TransformStyleConfig[] = [],
+): TransformStyleRegistry {
+  const registeredStyles = new Map<string, TransformStyleConfig>();
+  const registry: TransformStyleRegistry = {
+    register(style): void {
+      const snapshot = styleSnapshot(style);
+      registeredStyles.set(snapshot.id, snapshot);
+    },
+    unregister(id): boolean {
+      return registeredStyles.delete(id);
+    },
+    get(id): TransformStyleConfig | undefined {
+      return registeredStyles.get(id);
+    },
+    list(): TransformStyleConfig[] {
+      return Array.from(registeredStyles.values());
+    },
+  };
+  for (const style of initialStyles) registry.register(style);
+  return Object.freeze(registry);
+}
+
+/**
+ * Resolve a built-in id, explicit-registry id, or call-scoped style config.
+ * Unknown ids fall back to the default style.
+ */
+export function resolveTransformStyle(
+  style: TransformStyleInput,
+  registry?: TransformStyleRegistry,
+): TransformStyleConfig {
+  if (typeof style !== 'string') return styleSnapshot(style);
+  return registry?.get(style) ?? resolveBuiltinStyle(style);
+}
+
+/** Get built-in ids plus ids from an optional caller-owned registry. */
+export function getTransformStyleIds(registry?: TransformStyleRegistry): string[] {
+  return Array.from(
+    new Set([
+      ...Object.keys(TRANSFORM_STYLES),
+      ...(registry?.list().map((style) => style.id) ?? []),
+    ]),
+  );
 }
 
-/** Get summary info for all styles (for UI dropdowns). */
-export function getTransformStyleSummaries(): TransformStyleSummary[] {
-  return getTransformStyleIds().map((id) => {
-    const { name, description } = resolveTransformStyle(id);
+/** Get summaries for built-ins plus an optional caller-owned registry. */
+export function getTransformStyleSummaries(registry?: TransformStyleRegistry) {
+  return getTransformStyleIds(registry).map((id) => {
+    const { name, description } = resolveTransformStyle(id, registry);
     return { id, name, description };
   });
 }

package/src/transform/templateSelector.ts

@@ -22,6 +22,7 @@ import type { TransformStyleConfig, TransformImage } from './types.js';
 import type { AnalyzedBlock } from './blockAnalyzer.js';
 import { mapElementToBlock } from '../generate/templateMapper.js';
 import { SeededRandom } from '../random/SeededRandom.js';
+import { estimateTimeFromText } from '../timing/narrationTiming.js';
 
 /** Accent positions to rotate through. */
 const ACCENT_POSITIONS: AccentPosition[] = [
@@ -219,6 +220,7 @@ function buildBlockSequence(
         audioSegment: ab.block.audioSegment,
         title: ab.block.title,
         colorScheme: config.colorSchemes[colorIndex % config.colorSchemes.length],
+        sourceBlockId: ab.block.id,
       };
       blocks.push(headerBlock);
       insertedCount++;
@@ -245,13 +247,27 @@ function buildBlockSequence(
         accentPositionIndex++;
       }
 
+      // `sourcePosition` is a CHAR OFFSET into the analyzed plain text;
+      // `sourceStartTime` is doc-timeline SECONDS. Convert via spoken-word
+      // proportion over the source block's timing — which, when the doc
+      // carries a narration take (applyNarrationTiming ran upstream), is
+      // the recorded voice: summarized slides land where the words are
+      // actually spoken.
+      const slideShare = ab.block.duration > 0 ? ab.block.duration / extractions.length : 6;
+      const offsetInBlock =
+        ab.block.duration > 0
+          ? estimateTimeFromText(ab.plainText, sel.element.sourcePosition, ab.block.duration)
+          : 0;
       let templateBlock = mapElementToBlock(sel.element, {
         id: `transform-${blockIdCounter++}`,
-        duration: ab.block.duration > 0 ? ab.block.duration / extractions.length : 6,
+        duration: slideShare,
         audioSegment: ab.block.audioSegment,
         colorScheme,
         accentImage,
-        sourceStartTime: sel.element.sourcePosition,
+        sourceStartTime: ab.block.startTime + offsetInBlock,
+        sourceDuration: slideShare,
+        sourceBlockId: ab.block.id,
+        sourceCharOffset: sel.element.sourcePosition,
       });
 
       // Style-level extraction→template remap (v2 contract). Only known
@@ -302,6 +318,7 @@ function buildBlockSequence(
           imageSrc: img.src,
           imageAlt: img.alt ?? '',
           ambientMotion: rng.pick(AMBIENT_MOTIONS) ?? 'zoomIn',
+          sourceBlockId: ab.block.id,
         };
         blocks.push(imageBlock);
         imageIndex++;
@@ -327,6 +344,8 @@ function translateTemplateBlock(block: TemplateBlock, target: string): TemplateB
     audioSegment: block.audioSegment,
     sourceStartTime: block.sourceStartTime,
     sourceDuration: block.sourceDuration,
+    sourceBlockId: block.sourceBlockId,
+    sourceCharOffset: block.sourceCharOffset,
   };
 
   if (block.template === 'quote') {