@bendyline/squisq 2.1.0 → 2.3.0

package/src/transform/templateSelector.ts

@@ -1,389 +0,0 @@
-/**
- * Template Selector
- *
- * Selects which extracted elements to promote to visual template blocks
- * and handles color scheme rotation, image interleaving, and template
- * variety. Ported and generalized from qualla-internal's TemplateSelector.
- */
-
-import type { Block, TransitionType } from '../schemas/Doc.js';
-import type {
-  TemplateBlock,
-  AccentImage,
-  AccentPosition,
-  ImageWithCaptionInput,
-  SectionHeaderInput,
-  QuoteBlockInput,
-  FullBleedQuoteInput,
-  StatHighlightInput,
-} from '../schemas/BlockTemplates.js';
-import type { ExtractedElement } from '../generate/contentExtractor.js';
-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[] = [
-  'left-strip',
-  'right-strip',
-  'bottom-strip',
-  'corner-inset',
-];
-
-/** Ambient motions to rotate on image blocks. */
-const AMBIENT_MOTIONS: Array<'zoomIn' | 'zoomOut' | 'panLeft' | 'panRight'> = [
-  'zoomIn',
-  'zoomOut',
-  'panLeft',
-  'panRight',
-];
-
-/** A selected element paired with its source block. */
-interface SelectedExtraction {
-  element: ExtractedElement;
-  sourceBlock: Block;
-  /** Index in the original analyzed blocks array. */
-  sourceIndex: number;
-}
-
-/** Result of template selection. */
-export interface SelectionResult {
-  /** Replacement blocks: a mix of original blocks and new template blocks. */
-  blocks: Array<Block | TemplateBlock>;
-  /** How many blocks were transformed. */
-  transformedCount: number;
-  /** How many blocks were inserted (images, section headers). */
-  insertedCount: number;
-}
-
-/**
- * Select extractions and build a transformed block sequence.
- *
- * @param analyzed - Analyzed blocks from blockAnalyzer.
- * @param config - The transform style configuration.
- * @param images - Available images for interleaving.
- * @param seed - Random seed for deterministic output.
- */
-export function selectAndBuild(
-  analyzed: AnalyzedBlock[],
-  config: TransformStyleConfig,
-  images: TransformImage[],
-  seed: number,
-): SelectionResult {
-  const rng = new SeededRandom(seed);
-
-  // 1. Collect all extractions across all blocks, filtered by config
-  const candidates = collectCandidates(analyzed, config);
-
-  // 2. Determine how many blocks to transform. `transformRatio` scales
-  // with block count; an optional duration-based budget (slides per
-  // minute) caps runaway promotion on long dense documents.
-  const ratioCap = Math.max(1, Math.floor(analyzed.length * config.transformRatio));
-  const slidesPerMinute = config.budget?.slidesPerMinute;
-  const totalDurationSeconds = analyzed.reduce((sum, ab) => sum + (ab.block.duration || 0), 0);
-  const budgetCap =
-    slidesPerMinute && totalDurationSeconds > 0
-      ? Math.max(1, Math.round((totalDurationSeconds / 60) * slidesPerMinute))
-      : Infinity;
-  const maxTransforms = Math.min(ratioCap, budgetCap);
-  const selected = candidates.slice(0, maxTransforms);
-
-  // 3. Build the output block sequence
-  const result = buildBlockSequence(analyzed, selected, config, images, rng);
-
-  return result;
-}
-
-/**
- * Collect candidate extractions from all analyzed blocks, sorted by
- * a combined score of confidence and type preference.
- */
-function collectCandidates(
-  analyzed: AnalyzedBlock[],
-  config: TransformStyleConfig,
-): SelectedExtraction[] {
-  const candidates: SelectedExtraction[] = [];
-
-  for (let i = 0; i < analyzed.length; i++) {
-    const ab = analyzed[i];
-    // Skip blocks with no meaningful text
-    if (ab.bodyWordCount < 5) continue;
-
-    for (const element of ab.extractions) {
-      if (element.confidence < config.minConfidence) continue;
-
-      candidates.push({
-        element,
-        sourceBlock: ab.block,
-        sourceIndex: i,
-      });
-    }
-  }
-
-  // Sort by: preferred type rank (lower = better), then confidence (higher = better)
-  const typeRank = new Map(config.preferredTypes.map((t, i) => [t, i]));
-  const maxRank = config.preferredTypes.length;
-
-  candidates.sort((a, b) => {
-    const rankA = typeRank.get(a.element.type) ?? maxRank;
-    const rankB = typeRank.get(b.element.type) ?? maxRank;
-    if (rankA !== rankB) return rankA - rankB;
-    return b.element.confidence - a.element.confidence;
-  });
-
-  // Deduplicate: if the same extracted text appears multiple times
-  // (e.g., from overlapping parent/child blocks), keep only the
-  // highest-ranked occurrence.
-  const seenTexts = new Set<string>();
-  const deduplicated: SelectedExtraction[] = [];
-  for (const candidate of candidates) {
-    const key = candidate.element.text.trim().toLowerCase();
-    if (seenTexts.has(key)) continue;
-    seenTexts.add(key);
-    deduplicated.push(candidate);
-  }
-
-  return deduplicated;
-}
-
-/**
- * Build the output block sequence, replacing source blocks with template
- * blocks where extractions were selected, and interleaving images.
- */
-function buildBlockSequence(
-  analyzed: AnalyzedBlock[],
-  selected: SelectedExtraction[],
-  config: TransformStyleConfig,
-  images: TransformImage[],
-  rng: SeededRandom,
-): SelectionResult {
-  // Map: sourceIndex → list of selected extractions for that block
-  const blockExtractions = new Map<number, SelectedExtraction[]>();
-  for (const sel of selected) {
-    const list = blockExtractions.get(sel.sourceIndex) ?? [];
-    list.push(sel);
-    blockExtractions.set(sel.sourceIndex, list);
-  }
-
-  // Limit extractions per block: cap at blocksPerSection.max and ensure
-  // template type variety within each block (no two same-type extractions).
-  for (const [idx, list] of blockExtractions) {
-    const diverse: SelectedExtraction[] = [];
-    const usedTypes = new Set<string>();
-    for (const sel of list) {
-      if (usedTypes.has(sel.element.type)) continue;
-      usedTypes.add(sel.element.type);
-      diverse.push(sel);
-      if (diverse.length >= config.blocksPerSection.max) break;
-    }
-    blockExtractions.set(idx, diverse);
-  }
-
-  const blocks: Array<Block | TemplateBlock> = [];
-  let transformedCount = 0;
-  let insertedCount = 0;
-  let colorIndex = 0;
-  let blockIdCounter = 0;
-  let imageIndex = 0;
-  let accentPositionIndex = 0;
-  let elementsSinceImage = 0;
-  let prevTemplateType = '';
-
-  // Calculate image interleaving interval
-  const totalTransformed = Array.from(blockExtractions.values()).reduce(
-    (sum, list) => sum + list.length,
-    0,
-  );
-  const imageInterval =
-    config.interleaveImages && images.length > 0 && totalTransformed > 0
-      ? Math.max(2, Math.floor(totalTransformed / (images.length + 1)))
-      : Infinity;
-
-  for (let i = 0; i < analyzed.length; i++) {
-    const ab = analyzed[i];
-    const extractions = blockExtractions.get(i);
-
-    if (!extractions || extractions.length === 0) {
-      // Keep the original block unchanged
-      blocks.push(ab.block);
-      continue;
-    }
-
-    // Insert section header before a group of transformed blocks (if enabled)
-    if (config.insertSectionHeaders && ab.block.title) {
-      const headerBlock: SectionHeaderInput = {
-        template: 'sectionHeader',
-        id: `transform-header-${blockIdCounter++}`,
-        duration: ab.block.duration > 0 ? Math.min(3, ab.block.duration * 0.2) : 3,
-        audioSegment: ab.block.audioSegment,
-        title: ab.block.title,
-        colorScheme: config.colorSchemes[colorIndex % config.colorSchemes.length],
-        sourceBlockId: ab.block.id,
-      };
-      blocks.push(headerBlock);
-      insertedCount++;
-    }
-
-    // Convert each selected extraction to a template block.
-    // Track the last template used globally (not just within this block)
-    // to avoid consecutive same-template slides across the entire output.
-    for (const sel of extractions) {
-      const colorScheme = config.colorSchemes[colorIndex % config.colorSchemes.length];
-
-      // Build accent image if we have images in the pool
-      let accentImage: AccentImage | undefined;
-      if (images.length > 0 && config.interleaveImages) {
-        const img = images[imageIndex % images.length];
-        accentImage = {
-          src: img.src,
-          alt: img.alt ?? '',
-          position: ACCENT_POSITIONS[accentPositionIndex % ACCENT_POSITIONS.length],
-          ambientMotion: rng.pick(AMBIENT_MOTIONS) ?? 'zoomIn',
-          credit: img.credit,
-          license: img.license,
-        };
-        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: slideShare,
-        audioSegment: ab.block.audioSegment,
-        colorScheme,
-        accentImage,
-        sourceStartTime: ab.block.startTime + offsetInBlock,
-        sourceDuration: slideShare,
-        sourceBlockId: ab.block.id,
-        sourceCharOffset: sel.element.sourcePosition,
-      });
-
-      // Style-level extraction→template remap (v2 contract). Only known
-      // text-compatible pairings translate; image-backed targets consume
-      // the accent image as their background. Unknown pairings keep the
-      // default mapping.
-      const remapTarget = config.templateMap?.[sel.element.data.type];
-      if (remapTarget && remapTarget !== templateBlock.template) {
-        const translated = translateTemplateBlock(templateBlock, remapTarget);
-        if (translated) templateBlock = translated;
-      }
-
-      // Apply transition based on style
-      if (config.transitionStyle !== 'cut') {
-        const transitionType: TransitionType =
-          config.transitionStyle === 'mixed'
-            ? (rng.pick<TransitionType>(['fade', 'dissolve']) ?? 'fade')
-            : config.transitionStyle;
-        templateBlock.transition = {
-          type: transitionType,
-          duration: 0.5,
-        };
-      }
-
-      // Avoid consecutive same-template blocks by bumping color for variety
-      if (templateBlock.template === prevTemplateType) {
-        colorIndex++;
-      }
-      prevTemplateType = templateBlock.template;
-
-      blocks.push(templateBlock);
-      transformedCount++;
-      colorIndex++;
-      elementsSinceImage++;
-
-      // Interleave standalone image at intervals
-      if (
-        config.interleaveImages &&
-        imageIndex < images.length &&
-        elementsSinceImage >= imageInterval
-      ) {
-        const img = images[imageIndex];
-        const imageBlock: ImageWithCaptionInput = {
-          template: 'imageWithCaption',
-          id: `transform-img-${blockIdCounter++}`,
-          duration: 4,
-          audioSegment: ab.block.audioSegment,
-          imageSrc: img.src,
-          imageAlt: img.alt ?? '',
-          ambientMotion: rng.pick(AMBIENT_MOTIONS) ?? 'zoomIn',
-          sourceBlockId: ab.block.id,
-        };
-        blocks.push(imageBlock);
-        imageIndex++;
-        insertedCount++;
-        elementsSinceImage = 0;
-      }
-    }
-  }
-
-  return { blocks, transformedCount, insertedCount };
-}
-
-/**
- * Translate a mapped template block into a style-requested target
- * template. Only text-compatible pairings are supported; returns null
- * (keep the default) for unknown pairs or when a required input —
- * a background image for `pullQuote` — is unavailable.
- */
-function translateTemplateBlock(block: TemplateBlock, target: string): TemplateBlock | null {
-  const base = {
-    id: block.id,
-    duration: block.duration,
-    audioSegment: block.audioSegment,
-    sourceStartTime: block.sourceStartTime,
-    sourceDuration: block.sourceDuration,
-    sourceBlockId: block.sourceBlockId,
-    sourceCharOffset: block.sourceCharOffset,
-  };
-
-  if (block.template === 'quote') {
-    const quote = block as QuoteBlockInput;
-    if (target === 'fullBleedQuote') {
-      return { ...base, template: 'fullBleedQuote', text: quote.quote };
-    }
-    if (target === 'pullQuote') {
-      // pullQuote requires a full-bleed background image — reuse the
-      // accent image the selector already assigned to this block.
-      const bg = quote.accentImage;
-      if (!bg) return null;
-      return {
-        ...base,
-        template: 'pullQuote',
-        text: quote.quote,
-        attribution: quote.attribution,
-        backgroundImage: { src: bg.src, alt: bg.alt, credit: bg.credit, license: bg.license },
-      };
-    }
-    return null;
-  }
-
-  if (block.template === 'fullBleedQuote' && target === 'quote') {
-    const fbq = block as FullBleedQuoteInput;
-    return { ...base, template: 'quote', quote: fbq.text };
-  }
-
-  if (block.template === 'statHighlight' && target === 'factCard') {
-    const stat = block as StatHighlightInput;
-    return {
-      ...base,
-      template: 'factCard',
-      fact: stat.stat,
-      explanation: stat.description,
-      accentImage: stat.accentImage,
-    };
-  }
-
-  return null;
-}

package/src/transform/timingAllocator.ts

@@ -1,257 +0,0 @@
-/**
- * Timing Allocator
- *
- * Distributes timing (startTime, duration) across transformed blocks.
- * When the source Doc has audio, blocks are fitted to the overall duration.
- * When no audio is present, uses reading-time estimation.
- */
-
-import type { Block } from '../schemas/Doc.js';
-import type { TemplateBlock } from '../schemas/BlockTemplates.js';
-import { isTemplateBlock } from '../schemas/BlockTemplates.js';
-
-/** Minimum block duration in seconds. */
-const MIN_BLOCK_DURATION = 3;
-/** Maximum block duration in seconds. */
-const MAX_BLOCK_DURATION = 20;
-/** Default duration when no timing info is available. */
-const DEFAULT_BLOCK_DURATION = 6;
-
-/**
- * Allocate startTime and duration across a mixed array of blocks and
- * template blocks. Template blocks get timing assigned; existing blocks
- * retain their original timing when possible.
- *
- * @param blocks - The output from templateSelector (mixed Block | TemplateBlock).
- * @param totalDuration - The Doc's total duration (from audio or estimation).
- * @returns A new array of Blocks with consistent timing. Template blocks
- *          are returned as Blocks (with startTime/duration set, layers empty).
- */
-export function allocateTiming(
-  blocks: Array<Block | TemplateBlock>,
-  totalDuration: number,
-): Block[] {
-  if (blocks.length === 0) return [];
-
-  // Template blocks carrying a numeric `sourceStartTime` are ANCHORED to
-  // the doc timeline — when the source doc is narration-timed
-  // (`applyNarrationTiming`), those anchors are where the words are
-  // actually spoken, and rescaling would tear the slides away from the
-  // voice. Anchored blocks keep their positions; floating blocks
-  // (intro/outro bookends, section headers, interleaved images) fill the
-  // gaps between anchors. With no anchors at all, behavior is the
-  // historical rescale-to-fit.
-  const hasAnchors = blocks.some(
-    (b) => isTemplateBlock(b) && typeof b.sourceStartTime === 'number',
-  );
-  return hasAnchors
-    ? allocateAnchored(blocks, totalDuration)
-    : allocateRescaled(blocks, totalDuration);
-}
-
-/** Historical behavior: scale every duration to fill the total, clamp 3–20 s. */
-function allocateRescaled(blocks: Array<Block | TemplateBlock>, totalDuration: number): Block[] {
-  const effectiveDuration = totalDuration > 0 ? totalDuration : estimateDefaultDuration(blocks);
-
-  // First pass: assign raw durations
-  const durations = blocks.map((block) => {
-    if (!isTemplateBlock(block) && block.duration > 0) {
-      // Existing block with known duration — keep it
-      return block.duration;
-    }
-    if (isTemplateBlock(block) && block.duration > 0) {
-      return block.duration;
-    }
-    return DEFAULT_BLOCK_DURATION;
-  });
-
-  // Scale durations to fit the total
-  const rawTotal = durations.reduce((sum, d) => sum + d, 0);
-  if (rawTotal > 0 && effectiveDuration > 0) {
-    const scale = effectiveDuration / rawTotal;
-    for (let i = 0; i < durations.length; i++) {
-      durations[i] = clampDuration(durations[i] * scale);
-    }
-  }
-
-  // Second pass: assign startTimes and build output Blocks
-  let currentTime = 0;
-  const result: Block[] = [];
-  for (let i = 0; i < blocks.length; i++) {
-    result.push(toOutputBlock(blocks[i], currentTime, durations[i]));
-    currentTime += durations[i];
-  }
-  return result;
-}
-
-/** Minimum duration for a floating block squeezed between anchors. */
-const MIN_FLOATING_DURATION = 1;
-
-/**
- * Anchor-aware allocation: anchored entries (template blocks with a
- * numeric `sourceStartTime`, and untransformed source Blocks with their
- * own real timing) are PLACED at their timeline positions; runs of
- * floating blocks (bookends, headers, images) distribute across the gap
- * before the next anchor. Durations then derive from consecutive starts
- * so the timeline stays CONTIGUOUS — a slide summarizing unpromoted
- * source content simply holds until the next slide begins, which is
- * what keeps every narration second covered by some block.
- */
-function allocateAnchored(blocks: Array<Block | TemplateBlock>, totalDuration: number): Block[] {
-  interface Entry {
-    block: Block | TemplateBlock;
-    anchorStart: number | null;
-    rawDuration: number;
-  }
-  const entries: Entry[] = blocks.map((block) => {
-    if (isTemplateBlock(block)) {
-      return {
-        block,
-        anchorStart: typeof block.sourceStartTime === 'number' ? block.sourceStartTime : null,
-        rawDuration: block.duration > 0 ? block.duration : DEFAULT_BLOCK_DURATION,
-      };
-    }
-    // Untransformed source blocks carry real (possibly narration) timing.
-    return {
-      block,
-      anchorStart: block.startTime,
-      rawDuration: block.duration > 0 ? block.duration : DEFAULT_BLOCK_DURATION,
-    };
-  });
-
-  // Pass 1: starts. Anchors pin their positions (the cursor then jumps
-  // past the anchor's authored span, so following floats land AFTER it).
-  // Float runs place differently by position: LEADING floats (before any
-  // anchor — intro bookends) fill the opening gap from t=0; MID floats
-  // (section headers, images) end-align just before the next anchor —
-  // a header belongs to the section it introduces; TRAILING floats
-  // (outro) run sequentially after the last anchor's span.
-  const starts = new Array<number>(entries.length);
-  let cursor = 0;
-  let seenAnchor = false;
-  let i = 0;
-  while (i < entries.length) {
-    const entry = entries[i];
-    if (entry.anchorStart !== null) {
-      const start = Math.max(cursor, entry.anchorStart);
-      starts[i] = start;
-      const hint = isTemplateBlock(entry.block)
-        ? (entry.block.sourceDuration ?? entry.rawDuration)
-        : entry.rawDuration;
-      cursor = start + Math.max(MIN_FLOATING_DURATION, hint);
-      seenAnchor = true;
-      i++;
-      continue;
-    }
-    const runStart = i;
-    while (i < entries.length && entries[i].anchorStart === null) i++;
-    const run = entries.slice(runStart, i);
-    const rawSum = run.reduce((sum, e) => sum + e.rawDuration, 0);
-    const nextAnchorStart =
-      i < entries.length ? Math.max(entries[i].anchorStart ?? cursor, cursor) : null;
-
-    if (nextAnchorStart === null) {
-      // Trailing floats: natural sizes after the last anchor's span.
-      let acc = cursor;
-      for (let k = 0; k < run.length; k++) {
-        starts[runStart + k] = acc;
-        acc += run[k].rawDuration;
-      }
-      cursor = acc;
-    } else if (!seenAnchor) {
-      // Leading floats: fill [cursor, nextAnchorStart) proportionally.
-      const gap = nextAnchorStart - cursor;
-      let acc = cursor;
-      for (let k = 0; k < run.length; k++) {
-        starts[runStart + k] = acc;
-        acc += rawSum > 0 ? (run[k].rawDuration / rawSum) * gap : gap / run.length;
-      }
-      cursor = nextAnchorStart;
-    } else {
-      // Mid floats: end-aligned at natural size, capped by the gap.
-      const gap = Math.max(0, nextAnchorStart - cursor);
-      const scale = rawSum > 0 ? Math.min(1, gap / rawSum) : 0;
-      let acc = Math.max(cursor, nextAnchorStart - rawSum * scale);
-      for (let k = 0; k < run.length; k++) {
-        starts[runStart + k] = acc;
-        acc += run[k].rawDuration * scale;
-      }
-      cursor = nextAnchorStart;
-    }
-  }
-
-  // Pass 2: strictly increasing starts, then contiguous durations.
-  for (let k = 0; k < starts.length; k++) {
-    const floor = k > 0 ? starts[k - 1] + MIN_FLOATING_DURATION : 0;
-    if (starts[k] < floor) starts[k] = floor;
-  }
-  const result: Block[] = [];
-  for (let k = 0; k < entries.length; k++) {
-    const entry = entries[k];
-    let duration: number;
-    if (k + 1 < entries.length) {
-      duration = Math.max(MIN_FLOATING_DURATION, starts[k + 1] - starts[k]);
-    } else {
-      const authored = isTemplateBlock(entry.block)
-        ? (entry.block.sourceDuration ?? entry.rawDuration)
-        : entry.rawDuration;
-      // The final block covers through the end of the doc/narration when
-      // the caller knows it runs longer.
-      duration = Math.max(MIN_FLOATING_DURATION, authored, totalDuration - starts[k]);
-    }
-    result.push(toOutputBlock(entry.block, starts[k], duration));
-  }
-  return result;
-}
-
-/**
- * Convert an entry to an output Block shell. Template blocks preserve all
- * template-specific fields (stat, quote, description, …) so they survive
- * through to the player's template expansion step.
- */
-function toOutputBlock(block: Block | TemplateBlock, startTime: number, duration: number): Block {
-  if (isTemplateBlock(block)) {
-    return {
-      ...block,
-      startTime,
-      duration,
-      title: getTemplateTitle(block),
-    } as unknown as Block;
-  }
-  return { ...block, startTime, duration };
-}
-
-/** Clamp a duration to the min/max range. */
-function clampDuration(d: number): number {
-  return Math.max(MIN_BLOCK_DURATION, Math.min(MAX_BLOCK_DURATION, d));
-}
-
-/** Estimate a total duration from block contents when no audio is available. */
-function estimateDefaultDuration(blocks: Array<Block | TemplateBlock>): number {
-  let totalSeconds = 0;
-  for (const block of blocks) {
-    if (!isTemplateBlock(block) && block.duration > 0) {
-      totalSeconds += block.duration;
-    } else {
-      totalSeconds += DEFAULT_BLOCK_DURATION;
-    }
-  }
-  return Math.max(totalSeconds, blocks.length * MIN_BLOCK_DURATION);
-}
-
-/** Extract a display title from a template block if available. */
-function getTemplateTitle(block: TemplateBlock): string | undefined {
-  if ('title' in block && typeof block.title === 'string') {
-    return block.title;
-  }
-  if ('stat' in block && typeof block.stat === 'string') {
-    return block.stat;
-  }
-  if ('fact' in block && typeof block.fact === 'string') {
-    return block.fact;
-  }
-  if ('quote' in block && typeof block.quote === 'string') {
-    return block.quote.slice(0, 60);
-  }
-  return undefined;
-}