@bendyline/squisq 1.3.0 → 1.4.1

package/dist/transform/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/transform/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,0BAA0B,EAC1B,0BAA0B,GAC3B,MAAM,eAAe,CAAC;AAYvB,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"sources":["../../src/transform/styles/documentary.ts","../../src/transform/styles/magazine.ts","../../src/transform/styles/dataDriven.ts","../../src/transform/styles/narrative.ts","../../src/transform/styles/minimal.ts","../../src/transform/registry.ts","../../src/transform/blockAnalyzer.ts","../../src/transform/templateSelector.ts","../../src/transform/timingAllocator.ts","../../src/transform/applyTransform.ts"],"sourcesContent":["import type { TransformStyleConfig } from '../types.js';\n\n/** Conservative style — sparse highlights, preserves most text as-is. */\nexport const documentaryStyle: TransformStyleConfig = {\n  id: 'documentary',\n  name: 'Documentary',\n  description: 'Conservative — highlights only the strongest stats, dates, and quotes',\n  minConfidence: 0.5,\n  transformRatio: 0.3,\n  preferredTypes: ['stat', 'date', 'quote', 'fact'],\n  colorSchemes: ['blue', 'green', 'purple'],\n  insertSectionHeaders: false,\n  interleaveImages: true,\n  blocksPerSection: { min: 1, max: 3 },\n  transitionStyle: 'fade',\n};\n","import type { TransformStyleConfig } from '../types.js';\n\n/** Visual variety — pull quotes, definitions, image-heavy layout. */\nexport const magazineStyle: TransformStyleConfig = {\n  id: 'magazine',\n  name: 'Magazine',\n  description: 'Visual variety with pull quotes, facts, and rich image layouts',\n  minConfidence: 0.4,\n  transformRatio: 0.6,\n  preferredTypes: ['quote', 'fact', 'list', 'definition', 'stat', 'impactLine'],\n  colorSchemes: ['blue', 'green', 'purple', 'orange', 'red'],\n  insertSectionHeaders: true,\n  interleaveImages: true,\n  blocksPerSection: { min: 2, max: 5 },\n  transitionStyle: 'dissolve',\n};\n","import type { TransformStyleConfig } from '../types.js';\n\n/** Numbers-forward — aggressively extracts stats, comparisons, and dates. */\nexport const dataDrivenStyle: TransformStyleConfig = {\n  id: 'data-driven',\n  name: 'Data-Driven',\n  description: 'Aggressively highlights statistics, comparisons, and timelines',\n  minConfidence: 0.3,\n  transformRatio: 0.8,\n  preferredTypes: ['stat', 'comparison', 'date', 'list', 'fact'],\n  colorSchemes: ['blue', 'orange', 'green', 'purple', 'red'],\n  insertSectionHeaders: true,\n  interleaveImages: false,\n  blocksPerSection: { min: 2, max: 6 },\n  transitionStyle: 'cut',\n};\n","import type { TransformStyleConfig } from '../types.js';\n\n/** Timeline-focused — emphasizes dates, quotes, and story arc. */\nexport const narrativeStyle: TransformStyleConfig = {\n  id: 'narrative',\n  name: 'Narrative',\n  description: 'Story-driven with timeline events, quotes, and impact moments',\n  minConfidence: 0.4,\n  transformRatio: 0.5,\n  preferredTypes: ['date', 'quote', 'impactLine', 'fact', 'stat'],\n  colorSchemes: ['blue', 'purple', 'green'],\n  insertSectionHeaders: true,\n  interleaveImages: true,\n  blocksPerSection: { min: 1, max: 4 },\n  transitionStyle: 'fade',\n};\n","import type { TransformStyleConfig } from '../types.js';\n\n/** Light touch — only the highest-confidence items get transformed. */\nexport const minimalStyle: TransformStyleConfig = {\n  id: 'minimal',\n  name: 'Minimal',\n  description: 'Light touch — only the strongest highlights, mostly text',\n  minConfidence: 0.6,\n  transformRatio: 0.2,\n  preferredTypes: ['stat', 'quote'],\n  colorSchemes: ['blue', 'green'],\n  insertSectionHeaders: false,\n  interleaveImages: false,\n  blocksPerSection: { min: 1, max: 2 },\n  transitionStyle: 'fade',\n};\n","/**\n * Transform Style Registry\n *\n * Central registry of built-in transform styles. Follows the same pattern\n * as themeLibrary.ts — a record of configs with lookup/summary helpers.\n */\n\nimport type { TransformStyleConfig, TransformStyleSummary } from './types.js';\nimport { documentaryStyle } from './styles/documentary.js';\nimport { magazineStyle } from './styles/magazine.js';\nimport { dataDrivenStyle } from './styles/dataDriven.js';\nimport { narrativeStyle } from './styles/narrative.js';\nimport { minimalStyle } from './styles/minimal.js';\n\n/** All registered transform styles, keyed by id. */\nconst TRANSFORM_STYLES: Record<string, TransformStyleConfig> = {\n  [documentaryStyle.id]: documentaryStyle,\n  [magazineStyle.id]: magazineStyle,\n  [dataDrivenStyle.id]: dataDrivenStyle,\n  [narrativeStyle.id]: narrativeStyle,\n  [minimalStyle.id]: minimalStyle,\n};\n\n/** Default style used when no id is provided. */\nexport const DEFAULT_TRANSFORM_STYLE_ID = 'documentary';\n\n/**\n * Resolve a transform style by id.\n * Returns the default style if the id is not found.\n */\nexport function resolveTransformStyle(id: string): TransformStyleConfig {\n  return TRANSFORM_STYLES[id] ?? TRANSFORM_STYLES[DEFAULT_TRANSFORM_STYLE_ID];\n}\n\n/** Get all registered style ids. */\nexport function getTransformStyleIds(): string[] {\n  return Object.keys(TRANSFORM_STYLES);\n}\n\n/** Get summary info for all styles (for UI dropdowns). */\nexport function getTransformStyleSummaries(): TransformStyleSummary[] {\n  return Object.values(TRANSFORM_STYLES).map(({ id, name, description }) => ({\n    id,\n    name,\n    description,\n  }));\n}\n","/**\n * Block Analyzer\n *\n * Walks Doc blocks, extracts plain text from their markdown contents,\n * and runs the content extractor on each block to identify stats, dates,\n * quotes, etc. that can be promoted to visual template blocks.\n */\n\nimport type { Block } from '../schemas/Doc.js';\nimport type { MarkdownBlockNode, MarkdownNode } from '../markdown/types.js';\nimport type { ExtractedElement, ExtractionOptions } from '../generate/contentExtractor.js';\nimport type { TransformImage } from './types.js';\nimport { extractContent, stripMarkdown } from '../generate/contentExtractor.js';\nimport { extractPlainText, getChildren } from '../markdown/utils.js';\n\n/** An image found in a block's markdown contents. */\nexport interface BlockImage {\n  /** Image URL (relative or absolute). */\n  src: string;\n  /** Alt text. */\n  alt: string;\n  /** Index of the source block in the analyzed array. */\n  sourceBlockIndex: number;\n}\n\n/** A block enriched with extraction analysis. */\nexport interface AnalyzedBlock {\n  /** The original block. */\n  block: Block;\n  /** Plain text extracted from the block's contents. */\n  plainText: string;\n  /** Content extractions found in the block's text. */\n  extractions: ExtractedElement[];\n  /** Whether this block has child blocks. */\n  hasChildren: boolean;\n  /** Word count of the block's body text. */\n  bodyWordCount: number;\n  /** Images found in this block's markdown contents. */\n  images: BlockImage[];\n}\n\n/**\n * Extract plain text from an array of MarkdownBlockNodes.\n */\nfunction contentsToPlainText(contents: MarkdownBlockNode[]): string {\n  return contents.map((node) => extractPlainText(node)).join('\\n');\n}\n\n/**\n * Recursively walk a markdown node tree and collect all images.\n */\nfunction collectImages(node: MarkdownNode): Array<{ src: string; alt: string }> {\n  const results: Array<{ src: string; alt: string }> = [];\n\n  if ('type' in node && node.type === 'image' && 'url' in node) {\n    const img = node as { url: string; alt?: string };\n    if (img.url) {\n      results.push({ src: img.url, alt: img.alt ?? '' });\n    }\n  }\n\n  for (const child of getChildren(node)) {\n    results.push(...collectImages(child));\n  }\n\n  return results;\n}\n\n/**\n * Extract images from a block's markdown contents.\n */\nfunction extractBlockImages(block: Block, blockIndex: number): BlockImage[] {\n  if (!block.contents || block.contents.length === 0) return [];\n\n  const images: BlockImage[] = [];\n  for (const node of block.contents) {\n    for (const img of collectImages(node)) {\n      images.push({ ...img, sourceBlockIndex: blockIndex });\n    }\n  }\n  return images;\n}\n\n/**\n * Collect all unique images from all blocks in a Doc.\n * Returns them as TransformImages for use in the transform pipeline.\n */\nexport function extractDocImages(blocks: Block[]): TransformImage[] {\n  const seen = new Set<string>();\n  const images: TransformImage[] = [];\n\n  function walk(blockList: Block[]): void {\n    for (const block of blockList) {\n      if (block.contents) {\n        for (const node of block.contents) {\n          for (const img of collectImages(node)) {\n            if (!seen.has(img.src)) {\n              seen.add(img.src);\n              images.push({ src: img.src, alt: img.alt });\n            }\n          }\n        }\n      }\n      if (block.children) {\n        walk(block.children);\n      }\n    }\n  }\n\n  walk(blocks);\n  return images;\n}\n\n/**\n * Collect leaf blocks from a nested block tree.\n * Only returns blocks that have their own `contents` but no children,\n * preventing parent blocks from duplicating text that also appears\n * in their children. Parent-only blocks (with a title but no body\n * content) are included as structural placeholders.\n */\nfunction collectLeafBlocks(blocks: Block[]): Block[] {\n  const result: Block[] = [];\n  for (const block of blocks) {\n    if (block.children && block.children.length > 0) {\n      // Parent block — only include it as a structural marker\n      // (title only, no body extraction) if it has no contents of its own.\n      // Then recurse into children for the actual content.\n      if (!block.contents || block.contents.length === 0) {\n        result.push(block);\n      }\n      result.push(...collectLeafBlocks(block.children));\n    } else {\n      // Leaf block — include for content analysis\n      result.push(block);\n    }\n  }\n  return result;\n}\n\n/**\n * Analyze all blocks in a Doc, extracting text and running content extraction.\n *\n * @param blocks - The Doc's block array (may be nested via children).\n * @param options - Extraction options (minConfidence, types filter).\n * @returns Analyzed blocks with extractions, in flattened order.\n */\nexport function analyzeBlocks(blocks: Block[], options?: ExtractionOptions): AnalyzedBlock[] {\n  const flat = collectLeafBlocks(blocks);\n  const results: AnalyzedBlock[] = [];\n\n  for (const block of flat) {\n    let plainText = '';\n\n    if (block.contents && block.contents.length > 0) {\n      plainText = contentsToPlainText(block.contents);\n    } else if (block.title) {\n      plainText = block.title;\n    }\n\n    // Strip any remaining markdown syntax\n    const stripped = stripMarkdown(plainText);\n    const bodyWordCount = stripped.split(/\\s+/).filter((w) => w.length > 0).length;\n\n    // Run content extraction\n    const extraction = extractContent(stripped, options);\n\n    // Extract images from markdown contents\n    const images = extractBlockImages(block, results.length);\n\n    results.push({\n      block,\n      plainText: stripped,\n      extractions: extraction.elements,\n      hasChildren: !!(block.children && block.children.length > 0),\n      bodyWordCount,\n      images,\n    });\n  }\n\n  return results;\n}\n","/**\n * Template Selector\n *\n * Selects which extracted elements to promote to visual template blocks\n * and handles color scheme rotation, image interleaving, and template\n * variety. Ported and generalized from qualla-internal's TemplateSelector.\n */\n\nimport type { Block } from '../schemas/Doc.js';\nimport type {\n  TemplateBlock,\n  AccentImage,\n  AccentPosition,\n  ImageWithCaptionInput,\n  SectionHeaderInput,\n} from '../schemas/BlockTemplates.js';\nimport type { ExtractedElement } from '../generate/contentExtractor.js';\nimport type { TransformStyleConfig, TransformImage } from './types.js';\nimport type { AnalyzedBlock } from './blockAnalyzer.js';\nimport { mapElementToBlock } from '../generate/templateMapper.js';\nimport { SeededRandom } from '../random/SeededRandom.js';\n\n/** Accent positions to rotate through. */\nconst ACCENT_POSITIONS: AccentPosition[] = [\n  'left-strip',\n  'right-strip',\n  'bottom-strip',\n  'corner-inset',\n];\n\n/** Ambient motions to rotate on image blocks. */\nconst AMBIENT_MOTIONS: Array<'zoomIn' | 'zoomOut' | 'panLeft' | 'panRight'> = [\n  'zoomIn',\n  'zoomOut',\n  'panLeft',\n  'panRight',\n];\n\n/** A selected element paired with its source block. */\ninterface SelectedExtraction {\n  element: ExtractedElement;\n  sourceBlock: Block;\n  /** Index in the original analyzed blocks array. */\n  sourceIndex: number;\n}\n\n/** Result of template selection. */\nexport interface SelectionResult {\n  /** Replacement blocks: a mix of original blocks and new template blocks. */\n  blocks: Array<Block | TemplateBlock>;\n  /** How many blocks were transformed. */\n  transformedCount: number;\n  /** How many blocks were inserted (images, section headers). */\n  insertedCount: number;\n}\n\n/**\n * Select extractions and build a transformed block sequence.\n *\n * @param analyzed - Analyzed blocks from blockAnalyzer.\n * @param config - The transform style configuration.\n * @param images - Available images for interleaving.\n * @param seed - Random seed for deterministic output.\n */\nexport function selectAndBuild(\n  analyzed: AnalyzedBlock[],\n  config: TransformStyleConfig,\n  images: TransformImage[],\n  seed: number,\n): SelectionResult {\n  const rng = new SeededRandom(seed);\n\n  // 1. Collect all extractions across all blocks, filtered by config\n  const candidates = collectCandidates(analyzed, config);\n\n  // 2. Determine how many blocks to transform\n  const maxTransforms = Math.max(1, Math.floor(analyzed.length * config.transformRatio));\n  const selected = candidates.slice(0, maxTransforms);\n\n  // 3. Build the output block sequence\n  const result = buildBlockSequence(analyzed, selected, config, images, rng);\n\n  return result;\n}\n\n/**\n * Collect candidate extractions from all analyzed blocks, sorted by\n * a combined score of confidence and type preference.\n */\nfunction collectCandidates(\n  analyzed: AnalyzedBlock[],\n  config: TransformStyleConfig,\n): SelectedExtraction[] {\n  const candidates: SelectedExtraction[] = [];\n\n  for (let i = 0; i < analyzed.length; i++) {\n    const ab = analyzed[i];\n    // Skip blocks with no meaningful text\n    if (ab.bodyWordCount < 5) continue;\n\n    for (const element of ab.extractions) {\n      if (element.confidence < config.minConfidence) continue;\n\n      candidates.push({\n        element,\n        sourceBlock: ab.block,\n        sourceIndex: i,\n      });\n    }\n  }\n\n  // Sort by: preferred type rank (lower = better), then confidence (higher = better)\n  const typeRank = new Map(config.preferredTypes.map((t, i) => [t, i]));\n  const maxRank = config.preferredTypes.length;\n\n  candidates.sort((a, b) => {\n    const rankA = typeRank.get(a.element.type) ?? maxRank;\n    const rankB = typeRank.get(b.element.type) ?? maxRank;\n    if (rankA !== rankB) return rankA - rankB;\n    return b.element.confidence - a.element.confidence;\n  });\n\n  // Deduplicate: if the same extracted text appears multiple times\n  // (e.g., from overlapping parent/child blocks), keep only the\n  // highest-ranked occurrence.\n  const seenTexts = new Set<string>();\n  const deduplicated: SelectedExtraction[] = [];\n  for (const candidate of candidates) {\n    const key = candidate.element.text.trim().toLowerCase();\n    if (seenTexts.has(key)) continue;\n    seenTexts.add(key);\n    deduplicated.push(candidate);\n  }\n\n  return deduplicated;\n}\n\n/**\n * Build the output block sequence, replacing source blocks with template\n * blocks where extractions were selected, and interleaving images.\n */\nfunction buildBlockSequence(\n  analyzed: AnalyzedBlock[],\n  selected: SelectedExtraction[],\n  config: TransformStyleConfig,\n  images: TransformImage[],\n  rng: SeededRandom,\n): SelectionResult {\n  // Map: sourceIndex → list of selected extractions for that block\n  const blockExtractions = new Map<number, SelectedExtraction[]>();\n  for (const sel of selected) {\n    const list = blockExtractions.get(sel.sourceIndex) ?? [];\n    list.push(sel);\n    blockExtractions.set(sel.sourceIndex, list);\n  }\n\n  // Limit extractions per block: cap at blocksPerSection.max and ensure\n  // template type variety within each block (no two same-type extractions).\n  for (const [idx, list] of blockExtractions) {\n    const diverse: SelectedExtraction[] = [];\n    const usedTypes = new Set<string>();\n    for (const sel of list) {\n      if (usedTypes.has(sel.element.type)) continue;\n      usedTypes.add(sel.element.type);\n      diverse.push(sel);\n      if (diverse.length >= config.blocksPerSection.max) break;\n    }\n    blockExtractions.set(idx, diverse);\n  }\n\n  const blocks: Array<Block | TemplateBlock> = [];\n  let transformedCount = 0;\n  let insertedCount = 0;\n  let colorIndex = 0;\n  let blockIdCounter = 0;\n  let imageIndex = 0;\n  let accentPositionIndex = 0;\n  let elementsSinceImage = 0;\n  let prevTemplateType = '';\n\n  // Calculate image interleaving interval\n  const totalTransformed = Array.from(blockExtractions.values()).reduce(\n    (sum, list) => sum + list.length,\n    0,\n  );\n  const imageInterval =\n    config.interleaveImages && images.length > 0 && totalTransformed > 0\n      ? Math.max(2, Math.floor(totalTransformed / (images.length + 1)))\n      : Infinity;\n\n  for (let i = 0; i < analyzed.length; i++) {\n    const ab = analyzed[i];\n    const extractions = blockExtractions.get(i);\n\n    if (!extractions || extractions.length === 0) {\n      // Keep the original block unchanged\n      blocks.push(ab.block);\n      continue;\n    }\n\n    // Insert section header before a group of transformed blocks (if enabled)\n    if (config.insertSectionHeaders && ab.block.title) {\n      const headerBlock: SectionHeaderInput = {\n        template: 'sectionHeader',\n        id: `transform-header-${blockIdCounter++}`,\n        duration: ab.block.duration > 0 ? Math.min(3, ab.block.duration * 0.2) : 3,\n        audioSegment: ab.block.audioSegment,\n        title: ab.block.title,\n        colorScheme: config.colorSchemes[colorIndex % config.colorSchemes.length],\n      };\n      blocks.push(headerBlock);\n      insertedCount++;\n    }\n\n    // Convert each selected extraction to a template block.\n    // Track the last template used globally (not just within this block)\n    // to avoid consecutive same-template slides across the entire output.\n    for (const sel of extractions) {\n      const colorScheme = config.colorSchemes[colorIndex % config.colorSchemes.length];\n\n      // Build accent image if we have images in the pool\n      let accentImage: AccentImage | undefined;\n      if (images.length > 0 && config.interleaveImages) {\n        const img = images[imageIndex % images.length];\n        accentImage = {\n          src: img.src,\n          alt: img.alt ?? '',\n          position: ACCENT_POSITIONS[accentPositionIndex % ACCENT_POSITIONS.length],\n          ambientMotion: rng.pick(AMBIENT_MOTIONS) ?? 'zoomIn',\n          credit: img.credit,\n          license: img.license,\n        };\n        accentPositionIndex++;\n      }\n\n      const templateBlock = mapElementToBlock(sel.element, {\n        id: `transform-${blockIdCounter++}`,\n        duration: ab.block.duration > 0 ? ab.block.duration / extractions.length : 6,\n        audioSegment: ab.block.audioSegment,\n        colorScheme,\n        accentImage,\n        sourceStartTime: sel.element.sourcePosition,\n      });\n\n      // Apply transition based on style\n      if (config.transitionStyle !== 'cut') {\n        (\n          templateBlock as TemplateBlock & { transition?: { type: string; duration: number } }\n        ).transition = {\n          type:\n            config.transitionStyle === 'mixed'\n              ? (rng.pick(['fade', 'dissolve']) ?? 'fade')\n              : config.transitionStyle,\n          duration: 0.5,\n        };\n      }\n\n      // Avoid consecutive same-template blocks by bumping color for variety\n      if (templateBlock.template === prevTemplateType) {\n        colorIndex++;\n      }\n      prevTemplateType = templateBlock.template;\n\n      blocks.push(templateBlock);\n      transformedCount++;\n      colorIndex++;\n      elementsSinceImage++;\n\n      // Interleave standalone image at intervals\n      if (\n        config.interleaveImages &&\n        imageIndex < images.length &&\n        elementsSinceImage >= imageInterval\n      ) {\n        const img = images[imageIndex];\n        const imageBlock: ImageWithCaptionInput = {\n          template: 'imageWithCaption',\n          id: `transform-img-${blockIdCounter++}`,\n          duration: 4,\n          audioSegment: ab.block.audioSegment,\n          imageSrc: img.src,\n          imageAlt: img.alt ?? '',\n          ambientMotion: rng.pick(AMBIENT_MOTIONS) ?? 'zoomIn',\n        };\n        blocks.push(imageBlock);\n        imageIndex++;\n        insertedCount++;\n        elementsSinceImage = 0;\n      }\n    }\n  }\n\n  return { blocks, transformedCount, insertedCount };\n}\n","/**\n * Timing Allocator\n *\n * Distributes timing (startTime, duration) across transformed blocks.\n * When the source Doc has audio, blocks are fitted to the overall duration.\n * When no audio is present, uses reading-time estimation.\n */\n\nimport type { Block } from '../schemas/Doc.js';\nimport type { TemplateBlock } from '../schemas/BlockTemplates.js';\nimport { isTemplateBlock } from '../schemas/BlockTemplates.js';\n\n/** Minimum block duration in seconds. */\nconst MIN_BLOCK_DURATION = 3;\n/** Maximum block duration in seconds. */\nconst MAX_BLOCK_DURATION = 20;\n/** Default duration when no timing info is available. */\nconst DEFAULT_BLOCK_DURATION = 6;\n\n/**\n * Allocate startTime and duration across a mixed array of blocks and\n * template blocks. Template blocks get timing assigned; existing blocks\n * retain their original timing when possible.\n *\n * @param blocks - The output from templateSelector (mixed Block | TemplateBlock).\n * @param totalDuration - The Doc's total duration (from audio or estimation).\n * @returns A new array of Blocks with consistent timing. Template blocks\n *          are returned as Blocks (with startTime/duration set, layers empty).\n */\nexport function allocateTiming(\n  blocks: Array<Block | TemplateBlock>,\n  totalDuration: number,\n): Block[] {\n  if (blocks.length === 0) return [];\n\n  const effectiveDuration = totalDuration > 0 ? totalDuration : estimateDefaultDuration(blocks);\n\n  // First pass: assign raw durations\n  const durations = blocks.map((block) => {\n    if (!isTemplateBlock(block) && block.duration > 0) {\n      // Existing block with known duration — keep it\n      return block.duration;\n    }\n    if (isTemplateBlock(block) && block.duration > 0) {\n      return block.duration;\n    }\n    return DEFAULT_BLOCK_DURATION;\n  });\n\n  // Scale durations to fit the total\n  const rawTotal = durations.reduce((sum, d) => sum + d, 0);\n  if (rawTotal > 0 && effectiveDuration > 0) {\n    const scale = effectiveDuration / rawTotal;\n    for (let i = 0; i < durations.length; i++) {\n      durations[i] = clampDuration(durations[i] * scale);\n    }\n  }\n\n  // Second pass: assign startTimes and build output Blocks\n  let currentTime = 0;\n  const result: Block[] = [];\n\n  for (let i = 0; i < blocks.length; i++) {\n    const block = blocks[i];\n    const duration = durations[i];\n\n    if (isTemplateBlock(block)) {\n      // Convert TemplateBlock to Block shell, preserving all template-specific\n      // fields (stat, quote, description, etc.) so they survive through to\n      // the player's template expansion step.\n      const outputBlock = {\n        ...block,\n        startTime: currentTime,\n        duration,\n        title: getTemplateTitle(block),\n      } as unknown as Block;\n      result.push(outputBlock);\n    } else {\n      // Existing block — update timing\n      result.push({\n        ...block,\n        startTime: currentTime,\n        duration,\n      });\n    }\n\n    currentTime += duration;\n  }\n\n  return result;\n}\n\n/** Clamp a duration to the min/max range. */\nfunction clampDuration(d: number): number {\n  return Math.max(MIN_BLOCK_DURATION, Math.min(MAX_BLOCK_DURATION, d));\n}\n\n/** Estimate a total duration from block contents when no audio is available. */\nfunction estimateDefaultDuration(blocks: Array<Block | TemplateBlock>): number {\n  let totalSeconds = 0;\n  for (const block of blocks) {\n    if (!isTemplateBlock(block) && block.duration > 0) {\n      totalSeconds += block.duration;\n    } else {\n      totalSeconds += DEFAULT_BLOCK_DURATION;\n    }\n  }\n  return Math.max(totalSeconds, blocks.length * MIN_BLOCK_DURATION);\n}\n\n/** Extract a display title from a template block if available. */\nfunction getTemplateTitle(block: TemplateBlock): string | undefined {\n  if ('title' in block && typeof block.title === 'string') {\n    return block.title;\n  }\n  if ('stat' in block && typeof block.stat === 'string') {\n    return block.stat;\n  }\n  if ('fact' in block && typeof block.fact === 'string') {\n    return block.fact;\n  }\n  if ('quote' in block && typeof block.quote === 'string') {\n    return block.quote.slice(0, 60);\n  }\n  return undefined;\n}\n","/**\n * Apply Transform\n *\n * Main entry point for the transform module. Takes a Doc and a style,\n * analyzes block content, selects extractions to promote, and returns\n * a new Doc with blocks optimized for visual presentation.\n *\n * The input Doc is never mutated — a fresh Doc is always returned.\n */\n\nimport type { Doc } from '../schemas/Doc.js';\nimport type { TransformStyleId, TransformOptions, TransformResult } from './types.js';\nimport { resolveTransformStyle } from './registry.js';\nimport { analyzeBlocks, extractDocImages } from './blockAnalyzer.js';\nimport { selectAndBuild } from './templateSelector.js';\nimport { allocateTiming } from './timingAllocator.js';\nimport { hashString } from '../random/SeededRandom.js';\n\n/**\n * Apply a transform style to a Doc, producing a new Doc with blocks\n * optimized for visual presentation.\n *\n * @param doc - The source Doc (not mutated).\n * @param styleId - Registered transform style id (e.g. 'documentary', 'magazine').\n * @param options - Optional seed, images, theme override.\n * @returns TransformResult with the new Doc and stats.\n */\nexport function applyTransform(\n  doc: Doc,\n  styleId: TransformStyleId,\n  options?: TransformOptions,\n): TransformResult {\n  const baseConfig = resolveTransformStyle(styleId);\n  const config = options?.overrides\n    ? { ...baseConfig, ...options.overrides, id: baseConfig.id }\n    : baseConfig;\n\n  const seed = options?.seed ?? hashString(doc.articleId || 'transform');\n\n  // Use provided images or auto-extract from the doc's markdown content\n  const images = options?.images ?? extractDocImages(doc.blocks);\n\n  // 1. Analyze blocks\n  const analyzed = analyzeBlocks(doc.blocks, {\n    minConfidence: config.minConfidence,\n    types: config.preferredTypes,\n  });\n\n  // If no blocks have meaningful content, return the doc unchanged\n  const hasContent = analyzed.some((ab) => ab.bodyWordCount >= 5);\n  if (!hasContent) {\n    return {\n      doc: { ...doc },\n      stats: {\n        totalInputBlocks: doc.blocks.length,\n        transformedBlocks: 0,\n        insertedBlocks: 0,\n      },\n    };\n  }\n\n  // 2. Select extractions and build template blocks\n  const selection = selectAndBuild(analyzed, config, images, seed);\n\n  // 3. Allocate timing across the new block sequence\n  const timedBlocks = allocateTiming(selection.blocks, doc.duration);\n\n  // 4. Assemble the output Doc\n  const transformedDoc: Doc = {\n    ...doc,\n    blocks: timedBlocks,\n    themeId: options?.themeId ?? doc.themeId,\n  };\n\n  return {\n    doc: transformedDoc,\n    stats: {\n      totalInputBlocks: doc.blocks.length,\n      transformedBlocks: selection.transformedCount,\n      insertedBlocks: selection.insertedCount,\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/{types-CkNttVSF.d.ts → types-BdZkdJ3z.d.ts}

@@ -394,6 +394,21 @@ interface MarkdownInlineMath extends MarkdownNodeBase {
     /** Math content (without $ delimiters) */
     value: string;
 }
+/**
+ * Inline FontAwesome icon. Authored as `{[name]}` (bare) or
+ * `{[fa-<family>:name]}` (qualified) in markdown source. The parser
+ * resolves the token against the FA Free catalog and emits this node;
+ * unknown / ambiguous tokens stay as literal text.
+ */
+interface MarkdownInlineIcon extends MarkdownNodeBase {
+    type: 'inlineIcon';
+    /** Token exactly as authored — e.g. `github` or `fa-solid:user`. */
+    token: string;
+    /** Resolved icon family. */
+    family: 'brands' | 'solid' | 'regular';
+    /** Resolved icon name (without the `fa-` prefix). */
+    name: string;
+}
 /**
  * A footnote reference [^id]. GFM extension.
  */
@@ -455,7 +470,7 @@ interface MarkdownTextDirective extends MarkdownNodeBase {
  */
 interface MarkdownMention extends MarkdownNodeBase {
     type: 'mention';
-    /** Namespace for the mentioned entity (e.g. `"gezel"`, `"user"`). */
+    /** Namespace for the mentioned entity (e.g. `"user"`). */
     targetKind: string;
     /** Stable identifier within the namespace. */
     targetId: string;
@@ -465,7 +480,7 @@ interface MarkdownMention extends MarkdownNodeBase {
 /** Block-level content that can appear as direct children of the document root, blockquotes, list items, etc. */
 type MarkdownBlockNode = MarkdownHeading | MarkdownParagraph | MarkdownBlockquote | MarkdownList | MarkdownCodeBlock | MarkdownThematicBreak | MarkdownTable | MarkdownHtmlBlock | MarkdownMathBlock | MarkdownLinkDefinition | MarkdownFootnoteDefinition | MarkdownContainerDirective | MarkdownLeafDirective | MarkdownDefinitionList;
 /** Inline/phrasing content that appears inside paragraphs, headings, links, etc. */
-type MarkdownInlineNode = MarkdownText | MarkdownEmphasis | MarkdownStrong | MarkdownStrikethrough | MarkdownInlineCode | MarkdownLink | MarkdownImage | MarkdownBreak | MarkdownInlineHtml | MarkdownInlineMath | MarkdownFootnoteReference | MarkdownLinkReference | MarkdownImageReference | MarkdownTextDirective | MarkdownMention;
+type MarkdownInlineNode = MarkdownText | MarkdownEmphasis | MarkdownStrong | MarkdownStrikethrough | MarkdownInlineCode | MarkdownLink | MarkdownImage | MarkdownBreak | MarkdownInlineHtml | MarkdownInlineMath | MarkdownFootnoteReference | MarkdownLinkReference | MarkdownImageReference | MarkdownTextDirective | MarkdownMention | MarkdownInlineIcon;
 /**
  * Any node in the markdown tree. Includes structural nodes (listItem,
  * tableRow, tableCell, etc.) that only appear as children of specific parents.

package/dist/types-D98li1gV.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Public types for the document version-history feature.
+ *
+ * Versions are snapshots of the primary markdown document stored alongside
+ * the document inside the same {@link ContentContainer}. They live under
+ * `.versions/<docBasename>.<sortableTimestamp>.md`. The container is the
+ * unit of persistence — when the host serializes the container to a ZIP,
+ * a real folder, or anywhere else, the version snapshots ride along.
+ */
+/**
+ * A single version snapshot record.
+ */
+interface Version {
+    /** Container-relative path, e.g. `.versions/index.20260430T152030Z.md`. */
+    path: string;
+    /** Document basename without extension, e.g. `index`. */
+    basename: string;
+    /** Parsed timestamp from the filename, in UTC. */
+    timestamp: Date;
+    /** Snapshot size in bytes. */
+    size: number;
+    /**
+     * Collision suffix index. `0` for a path with no `-N` suffix, `1` for `-2`,
+     * `2` for `-3`, and so on. Used as the tie-break for ordering snapshots
+     * that share the same UTC second.
+     */
+    collision: number;
+}
+/**
+ * Result of a {@link saveVersion} call.
+ */
+interface SaveVersionResult {
+    /** True when a new snapshot file was actually written. */
+    saved: boolean;
+    /** The newly stamped version (only when `saved` is true). */
+    version: Version | null;
+    /**
+     * Why the save behaved the way it did:
+     * - `'saved'`        — a new snapshot was written.
+     * - `'unchanged'`    — current content matches the latest snapshot byte-for-byte.
+     * - `'no-document'`  — the container has no primary markdown document.
+     * - `'empty'`        — the resolved content was empty.
+     */
+    reason: 'saved' | 'unchanged' | 'no-document' | 'empty';
+}
+/**
+ * Options for {@link saveVersion}.
+ */
+interface SaveVersionOptions {
+    /** Override the document content; otherwise the container's primary doc is read. */
+    content?: string;
+    /** Override the timestamp; defaults to `new Date()`. Useful for tests. */
+    now?: Date;
+    /** Skip the diff-vs-latest check and force a write. */
+    force?: boolean;
+    /** Override the document basename used to build the version filename. */
+    basename?: string;
+}
+/**
+ * Pruning policy passed to {@link pruneVersions}.
+ */
+type PrunePolicy = {
+    type: 'keep-last-n';
+    n: number;
+} | {
+    type: 'older-than';
+    date: Date;
+} | {
+    type: 'predicate';
+    keep: (v: Version, all: Version[]) => boolean;
+};
+/**
+ * Options for {@link revertToVersion}.
+ */
+interface RevertOptions {
+    /**
+     * Whether to snapshot the current document content before replacing it.
+     * Defaults to `true` so a revert is always recoverable.
+     */
+    snapshotCurrent?: boolean;
+}
+/**
+ * Options for {@link coalesceVersions}.
+ */
+interface CoalesceOptions {
+    /**
+     * Two adjacent snapshots whose timestamps are within `windowMs` collapse
+     * to the newer one. Defaults to 60_000 (one minute).
+     */
+    windowMs?: number;
+}
+
+export type { CoalesceOptions as C, PrunePolicy as P, RevertOptions as R, SaveVersionOptions as S, Version as V, SaveVersionResult as a };

package/dist/versions/index.d.ts

@@ -0,0 +1,128 @@
+import { C as CoalesceOptions, V as Version, P as PrunePolicy, R as RevertOptions, S as SaveVersionOptions, a as SaveVersionResult } from '../types-D98li1gV.js';
+import { C as ContentContainer } from '../ContentContainer-DNx460y8.js';
+
+/**
+ * Pure-ish version operations against a {@link ContentContainer}.
+ *
+ * These functions are the canonical implementation. {@link DocumentVersionManager}
+ * is a thin wrapper that captures a container reference for ergonomics.
+ */
+
+/**
+ * List all snapshots in the container, newest-first.
+ *
+ * @param basename Optional filter: when set, only versions whose basename
+ *   matches are returned.
+ */
+declare function listVersions(container: ContentContainer, basename?: string): Promise<Version[]>;
+/**
+ * Read the markdown content of a snapshot. Returns null if the snapshot
+ * doesn't exist.
+ */
+declare function readVersion(container: ContentContainer, version: Version | string): Promise<string | null>;
+/**
+ * Save a new snapshot of the document if its content differs from the
+ * latest existing snapshot.
+ */
+declare function saveVersion(container: ContentContainer, options?: SaveVersionOptions): Promise<SaveVersionResult>;
+/**
+ * Revert the document to a prior snapshot. By default, the *current*
+ * document is snapshotted first so the revert is itself recoverable.
+ */
+declare function revertToVersion(container: ContentContainer, version: Version | string, options?: RevertOptions): Promise<{
+    reverted: boolean;
+    snapshotted: Version | null;
+}>;
+/**
+ * Delete snapshots that don't satisfy the policy. Returns the deleted
+ * versions in their original (newest-first) order.
+ */
+declare function pruneVersions(container: ContentContainer, policy: PrunePolicy, basename?: string): Promise<Version[]>;
+/**
+ * Collapse adjacent snapshots that occurred close together — keeping the
+ * newer one — to keep history readable across rapid edits.
+ */
+declare function coalesceVersions(container: ContentContainer, options?: CoalesceOptions, basename?: string): Promise<Version[]>;
+
+/**
+ * Convenience wrapper around the version operations that captures a
+ * {@link ContentContainer} reference and an optional basename override.
+ *
+ * Hosts that prefer a stable handle (e.g. to pass into a UI component)
+ * use this; everything it does is also reachable as a free function.
+ */
+
+interface DocumentVersionManagerOptions {
+    /**
+     * Override the document basename used in version filenames. Defaults to
+     * the basename of `container.getDocumentPath()` resolved at call time.
+     */
+    basename?: string;
+}
+declare class DocumentVersionManager {
+    private readonly container;
+    private readonly basename;
+    constructor(container: ContentContainer, options?: DocumentVersionManagerOptions);
+    saveVersion(options?: SaveVersionOptions): Promise<SaveVersionResult>;
+    listVersions(): Promise<Version[]>;
+    readVersion(version: Version | string): Promise<string | null>;
+    revertToVersion(version: Version | string, options?: RevertOptions): Promise<{
+        reverted: boolean;
+        snapshotted: Version | null;
+    }>;
+    pruneVersions(policy: PrunePolicy): Promise<Version[]>;
+    coalesceVersions(options?: CoalesceOptions): Promise<Version[]>;
+}
+
+/**
+ * Sortable, human-readable timestamps for version filenames.
+ *
+ * Format: ISO 8601 basic, UTC, second precision, `Z` suffix —
+ * e.g. `20260430T152030Z`. Lexicographic order matches chronological order,
+ * so `listFiles` returns versions in time order without parsing.
+ */
+/**
+ * Format a Date as a sortable, filename-safe UTC timestamp string.
+ */
+declare function formatVersionTimestamp(date: Date): string;
+/**
+ * Parse a version timestamp string back to a Date. Returns null if the input
+ * doesn't match the expected format.
+ */
+declare function parseVersionTimestamp(stamp: string): Date | null;
+/**
+ * The pattern a valid version timestamp matches. Exported so other modules
+ * can validate filenames without re-deriving the regex.
+ */
+declare const VERSION_TIMESTAMP_PATTERN: RegExp;
+
+/**
+ * Path conventions for version snapshots.
+ *
+ * Snapshots live at `<VERSIONS_PREFIX><basename>.<timestamp>[<-suffix>].md`.
+ * The optional numeric suffix (`-2`, `-3`, ...) is appended only when two
+ * snapshots collide on the same UTC second.
+ */
+/** Subfolder (inside the ContentContainer) that holds version snapshots. */
+declare const VERSIONS_PREFIX = ".versions/";
+/**
+ * Strip the directory and extension from a document path to produce the
+ * basename used in version filenames. `subdir/index.md` -> `index`.
+ */
+declare function getDocBasename(documentPath: string): string;
+/**
+ * Build a version snapshot path. Optionally append a collision suffix
+ * (e.g. `2`, `3`) when two saves land on the same UTC second.
+ */
+declare function buildVersionPath(basename: string, date: Date, collision?: number): string;
+/**
+ * Parse a version snapshot path. Returns null if it doesn't match the
+ * convention (so unrelated files stored under `.versions/` are ignored).
+ */
+declare function parseVersionPath(path: string): {
+    basename: string;
+    timestamp: Date;
+    collision: number;
+} | null;
+
+export { CoalesceOptions, DocumentVersionManager, type DocumentVersionManagerOptions, PrunePolicy, RevertOptions, SaveVersionOptions, SaveVersionResult, VERSIONS_PREFIX, VERSION_TIMESTAMP_PATTERN, Version, buildVersionPath, coalesceVersions, formatVersionTimestamp, getDocBasename, listVersions, parseVersionPath, parseVersionTimestamp, pruneVersions, readVersion, revertToVersion, saveVersion };

package/dist/versions/index.js

@@ -0,0 +1,35 @@
+import {
+  DocumentVersionManager,
+  VERSIONS_PREFIX,
+  buildVersionPath,
+  coalesceVersions,
+  getDocBasename,
+  listVersions,
+  parseVersionPath,
+  pruneVersions,
+  readVersion,
+  revertToVersion,
+  saveVersion
+} from "../chunk-VLJJHDAC.js";
+import {
+  VERSION_TIMESTAMP_PATTERN,
+  formatVersionTimestamp,
+  parseVersionTimestamp
+} from "../chunk-JELIRVDP.js";
+export {
+  DocumentVersionManager,
+  VERSIONS_PREFIX,
+  VERSION_TIMESTAMP_PATTERN,
+  buildVersionPath,
+  coalesceVersions,
+  formatVersionTimestamp,
+  getDocBasename,
+  listVersions,
+  parseVersionPath,
+  parseVersionTimestamp,
+  pruneVersions,
+  readVersion,
+  revertToVersion,
+  saveVersion
+};
+//# sourceMappingURL=index.js.map

package/dist/versions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/squisq",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "Headless utilities for doc/block rendering, spatial math, Markdown, and storage",
   "license": "MIT",
   "author": "Bendyline",
@@ -85,13 +85,40 @@
       "types": "./dist/transform/index.d.ts",
       "import": "./dist/transform/index.js",
       "default": "./dist/transform/index.js"
+    },
+    "./versions": {
+      "types": "./dist/versions/index.d.ts",
+      "import": "./dist/versions/index.js",
+      "default": "./dist/versions/index.js"
+    },
+    "./jsonForm": {
+      "types": "./dist/jsonForm/index.d.ts",
+      "import": "./dist/jsonForm/index.js",
+      "default": "./dist/jsonForm/index.js"
+    },
+    "./imageEdit": {
+      "types": "./dist/imageEdit/index.d.ts",
+      "import": "./dist/imageEdit/index.js",
+      "default": "./dist/imageEdit/index.js"
+    },
+    "./icons": {
+      "types": "./dist/icons/index.d.ts",
+      "import": "./dist/icons/index.js",
+      "default": "./dist/icons/index.js"
+    },
+    "./recommend": {
+      "types": "./dist/recommend/index.d.ts",
+      "import": "./dist/recommend/index.js",
+      "default": "./dist/recommend/index.js"
     }
   },
   "scripts": {
     "build": "tsup",
+    "dev": "concurrently -n js,dts -c blue,gray -r \"tsup --watch --no-dts --no-clean\" \"tsup --watch --dts-only --no-clean\"",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "genson-js": "0.0.8",
     "hast-util-from-html": "2.0.3",
     "localforage": "1.10.0",
     "ngeohash": "0.6.3",

package/src/__tests__/colorUtils.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect } from 'vitest';
+import {
+  isHex,
+  oklchLighten,
+  oklchDarken,
+  oklchSetChroma,
+  contrastRatio,
+  pickContrastingText,
+  deriveScale,
+  relativeLuminance,
+} from '../schemas/colorUtils.js';
+
+describe('isHex', () => {
+  it('accepts #rgb and #rrggbb', () => {
+    expect(isHex('#fff')).toBe(true);
+    expect(isHex('#123abc')).toBe(true);
+    expect(isHex('#FF0080')).toBe(true);
+  });
+  it('rejects malformed strings', () => {
+    expect(isHex('fff')).toBe(false);
+    expect(isHex('#1234')).toBe(false);
+    expect(isHex('#xyz')).toBe(false);
+    expect(isHex('rgb(0,0,0)')).toBe(false);
+  });
+});
+
+describe('oklchLighten / oklchDarken', () => {
+  it('lighten produces a lighter color (higher luminance)', () => {
+    const dark = '#101010';
+    const lighter = oklchLighten(dark, 0.2);
+    expect(relativeLuminance(lighter)).toBeGreaterThan(relativeLuminance(dark));
+  });
+
+  it('darken produces a darker color (lower luminance)', () => {
+    const light = '#e0e0e0';
+    const darker = oklchDarken(light, 0.2);
+    expect(relativeLuminance(darker)).toBeLessThan(relativeLuminance(light));
+  });
+
+  it('round-trips approximately stable for moderate adjustments', () => {
+    const seed = '#3182ce';
+    const round = oklchDarken(oklchLighten(seed, 0.1), 0.1);
+    // sRGB gamut clamping prevents perfect round-trip; expect within a small epsilon.
+    expect(round).toMatch(/^#[0-9a-f]{6}$/);
+    const lumDiff = Math.abs(relativeLuminance(seed) - relativeLuminance(round));
+    expect(lumDiff).toBeLessThan(0.05);
+  });
+
+  it('returns a hex string', () => {
+    expect(oklchLighten('#3182ce', 0.1)).toMatch(/^#[0-9a-f]{6}$/);
+    expect(oklchDarken('#3182ce', 0.1)).toMatch(/^#[0-9a-f]{6}$/);
+  });
+
+  it('falls back to input on parse failure', () => {
+    expect(oklchLighten('not-a-color', 0.1)).toBe('not-a-color');
+  });
+});
+
+describe('oklchSetChroma', () => {
+  it('reducing chroma toward 0 desaturates a color', () => {
+    const vivid = '#ff3366';
+    const muted = oklchSetChroma(vivid, 0.1);
+    // Muted version's R/G/B channels should be much closer to each other than vivid.
+    const parse = (h: string) => [
+      parseInt(h.slice(1, 3), 16),
+      parseInt(h.slice(3, 5), 16),
+      parseInt(h.slice(5, 7), 16),
+    ];
+    const [vr, vg, vb] = parse(vivid);
+    const [mr, mg, mb] = parse(muted);
+    const vSpread = Math.max(vr, vg, vb) - Math.min(vr, vg, vb);
+    const mSpread = Math.max(mr, mg, mb) - Math.min(mr, mg, mb);
+    expect(mSpread).toBeLessThan(vSpread);
+  });
+});
+
+describe('contrastRatio', () => {
+  it('white-on-black is the maximum (≈21)', () => {
+    expect(contrastRatio('#ffffff', '#000000')).toBeCloseTo(21, 0);
+  });
+  it('same-color is 1', () => {
+    expect(contrastRatio('#aabbcc', '#aabbcc')).toBeCloseTo(1, 5);
+  });
+  it('is symmetric', () => {
+    expect(contrastRatio('#222', '#ddd')).toBeCloseTo(contrastRatio('#ddd', '#222'), 5);
+  });
+});
+
+describe('pickContrastingText', () => {
+  it('returns dark text for light backgrounds', () => {
+    expect(pickContrastingText('#ffffff')).toBe('#1a202c');
+    expect(pickContrastingText('#f7fafc')).toBe('#1a202c');
+  });
+  it('returns light text for dark backgrounds', () => {
+    expect(pickContrastingText('#000000')).toBe('#f7fafc');
+    expect(pickContrastingText('#1a202c')).toBe('#f7fafc');
+  });
+  it('respects custom light/dark options', () => {
+    expect(pickContrastingText('#000000', '#fefefe', '#020202')).toBe('#fefefe');
+  });
+});
+
+describe('deriveScale', () => {
+  it('produces 5 stops with base in the middle', () => {
+    const scale = deriveScale('#3182ce', 0.15);
+    expect(scale.base).toBe('#3182ce');
+    expect(relativeLuminance(scale.lighter2)).toBeGreaterThan(relativeLuminance(scale.lighter1));
+    expect(relativeLuminance(scale.lighter1)).toBeGreaterThan(relativeLuminance(scale.base));
+    expect(relativeLuminance(scale.base)).toBeGreaterThan(relativeLuminance(scale.darker1));
+    expect(relativeLuminance(scale.darker1)).toBeGreaterThan(relativeLuminance(scale.darker2));
+  });
+});

package/src/__tests__/getLayers.test.ts

@@ -11,7 +11,7 @@ import type { Block, Layer, TextLayer, ShapeLayer } from '../schemas/Doc.js';
 
 function makeTemplateBlock(overrides: Partial<TemplateBlock> = {}): TemplateBlock {
   return {
-    template: 'titleBlock',
+    template: 'title',
     id: 'test-title-1',
     duration: 5,
     audioSegment: 0,
@@ -43,7 +43,7 @@ const defaultContext: RenderContext = {
 
 describe('getLayers', () => {
   it('generates layers for a known template block', () => {
-    const block = makeTemplateBlock({ template: 'titleBlock', title: 'Test Title' });
+    const block = makeTemplateBlock({ template: 'title', title: 'Test Title' });
     const layers = getLayers(block, defaultContext);
 
     expect(Array.isArray(layers)).toBe(true);
@@ -83,6 +83,31 @@ describe('getLayers', () => {
     expect(layers).toEqual(existingLayers);
   });
 
+  it('resolves legacy template aliases through TEMPLATE_ALIASES', () => {
+    // Regression: `getLayers` previously did `block.template in templateRegistry`
+    // without alias resolution, so docs authored with the legacy long ids
+    // (`titleBlock`, `quoteBlock`, `mapBlock`, `listBlock`) rendered as
+    // empty SVG cards in the linear/document view — `hasTemplate()` accepts
+    // the alias, so `isAnnotatedBlock` returns true and the card wrapper
+    // renders, but the registry lookup below would miss the alias and the
+    // layer array came back empty.
+    const aliasedToCanonical: Array<[string, string]> = [
+      ['titleBlock', 'title'],
+      ['quoteBlock', 'quote'],
+      ['listBlock', 'list'],
+    ];
+    for (const [alias] of aliasedToCanonical) {
+      const block = makeTemplateBlock({
+        template: alias as TemplateBlock['template'],
+        title: 'Aliased',
+        items: ['a', 'b', 'c'],
+        quote: 'q',
+      } as Partial<TemplateBlock>);
+      const layers = getLayers(block, defaultContext);
+      expect(layers.length).toBeGreaterThan(0);
+    }
+  });
+
   it('returns empty array for unknown template', () => {
     const block = {
       template: 'totally_nonexistent',
@@ -103,7 +128,7 @@ describe('getLayers', () => {
   });
 
   it('uses default context values when context is omitted', () => {
-    const block = makeTemplateBlock({ template: 'titleBlock', title: 'Defaults' });
+    const block = makeTemplateBlock({ template: 'title', title: 'Defaults' });
     const layers = getLayers(block);
 
     expect(Array.isArray(layers)).toBe(true);
@@ -147,7 +172,7 @@ describe('getLayers', () => {
     };
 
     it('injects persistent bottom and top layers around block layers', () => {
-      const block = makeTemplateBlock({ template: 'titleBlock', title: 'With Persistent' });
+      const block = makeTemplateBlock({ template: 'title', title: 'With Persistent' });
       const layers = getLayers(block, { ...defaultContext, persistentLayers: persistentConfig });
 
       // First layer should be the bottom persistent layer
@@ -160,7 +185,7 @@ describe('getLayers', () => {
 
     it('respects useBottomLayer: false opt-out', () => {
       const block = makeTemplateBlock({
-        template: 'titleBlock',
+        template: 'title',
         title: 'No Bottom',
         useBottomLayer: false,
       });
@@ -174,7 +199,7 @@ describe('getLayers', () => {
 
     it('respects useTopLayer: false opt-out', () => {
       const block = makeTemplateBlock({
-        template: 'titleBlock',
+        template: 'title',
         title: 'No Top',
         useTopLayer: false,
       });
@@ -187,7 +212,7 @@ describe('getLayers', () => {
     });
 
     it('skips injection when no persistent layers are configured', () => {
-      const block = makeTemplateBlock({ template: 'titleBlock', title: 'No Persistent' });
+      const block = makeTemplateBlock({ template: 'title', title: 'No Persistent' });
       const withoutPersistent = getLayers(block, defaultContext);
       const withEmptyPersistent = getLayers(block, {
         ...defaultContext,