@bendyline/squisq 1.0.1 → 1.1.1

package/src/transform/blockAnalyzer.ts

@@ -0,0 +1,181 @@
+/**
+ * Block Analyzer
+ *
+ * Walks Doc blocks, extracts plain text from their markdown contents,
+ * and runs the content extractor on each block to identify stats, dates,
+ * quotes, etc. that can be promoted to visual template blocks.
+ */
+
+import type { Block } from '../schemas/Doc.js';
+import type { MarkdownBlockNode, MarkdownNode } from '../markdown/types.js';
+import type { ExtractedElement, ExtractionOptions } from '../generate/contentExtractor.js';
+import type { TransformImage } from './types.js';
+import { extractContent, stripMarkdown } from '../generate/contentExtractor.js';
+import { extractPlainText, getChildren } from '../markdown/utils.js';
+
+/** An image found in a block's markdown contents. */
+export interface BlockImage {
+  /** Image URL (relative or absolute). */
+  src: string;
+  /** Alt text. */
+  alt: string;
+  /** Index of the source block in the analyzed array. */
+  sourceBlockIndex: number;
+}
+
+/** A block enriched with extraction analysis. */
+export interface AnalyzedBlock {
+  /** The original block. */
+  block: Block;
+  /** Plain text extracted from the block's contents. */
+  plainText: string;
+  /** Content extractions found in the block's text. */
+  extractions: ExtractedElement[];
+  /** Whether this block has child blocks. */
+  hasChildren: boolean;
+  /** Word count of the block's body text. */
+  bodyWordCount: number;
+  /** Images found in this block's markdown contents. */
+  images: BlockImage[];
+}
+
+/**
+ * Extract plain text from an array of MarkdownBlockNodes.
+ */
+function contentsToPlainText(contents: MarkdownBlockNode[]): string {
+  return contents.map((node) => extractPlainText(node)).join('\n');
+}
+
+/**
+ * Recursively walk a markdown node tree and collect all images.
+ */
+function collectImages(node: MarkdownNode): Array<{ src: string; alt: string }> {
+  const results: Array<{ src: string; alt: string }> = [];
+
+  if ('type' in node && node.type === 'image' && 'url' in node) {
+    const img = node as { url: string; alt?: string };
+    if (img.url) {
+      results.push({ src: img.url, alt: img.alt ?? '' });
+    }
+  }
+
+  for (const child of getChildren(node)) {
+    results.push(...collectImages(child));
+  }
+
+  return results;
+}
+
+/**
+ * Extract images from a block's markdown contents.
+ */
+function extractBlockImages(block: Block, blockIndex: number): BlockImage[] {
+  if (!block.contents || block.contents.length === 0) return [];
+
+  const images: BlockImage[] = [];
+  for (const node of block.contents) {
+    for (const img of collectImages(node)) {
+      images.push({ ...img, sourceBlockIndex: blockIndex });
+    }
+  }
+  return images;
+}
+
+/**
+ * Collect all unique images from all blocks in a Doc.
+ * Returns them as TransformImages for use in the transform pipeline.
+ */
+export function extractDocImages(blocks: Block[]): TransformImage[] {
+  const seen = new Set<string>();
+  const images: TransformImage[] = [];
+
+  function walk(blockList: Block[]): void {
+    for (const block of blockList) {
+      if (block.contents) {
+        for (const node of block.contents) {
+          for (const img of collectImages(node)) {
+            if (!seen.has(img.src)) {
+              seen.add(img.src);
+              images.push({ src: img.src, alt: img.alt });
+            }
+          }
+        }
+      }
+      if (block.children) {
+        walk(block.children);
+      }
+    }
+  }
+
+  walk(blocks);
+  return images;
+}
+
+/**
+ * Collect leaf blocks from a nested block tree.
+ * Only returns blocks that have their own `contents` but no children,
+ * preventing parent blocks from duplicating text that also appears
+ * in their children. Parent-only blocks (with a title but no body
+ * content) are included as structural placeholders.
+ */
+function collectLeafBlocks(blocks: Block[]): Block[] {
+  const result: Block[] = [];
+  for (const block of blocks) {
+    if (block.children && block.children.length > 0) {
+      // Parent block — only include it as a structural marker
+      // (title only, no body extraction) if it has no contents of its own.
+      // Then recurse into children for the actual content.
+      if (!block.contents || block.contents.length === 0) {
+        result.push(block);
+      }
+      result.push(...collectLeafBlocks(block.children));
+    } else {
+      // Leaf block — include for content analysis
+      result.push(block);
+    }
+  }
+  return result;
+}
+
+/**
+ * Analyze all blocks in a Doc, extracting text and running content extraction.
+ *
+ * @param blocks - The Doc's block array (may be nested via children).
+ * @param options - Extraction options (minConfidence, types filter).
+ * @returns Analyzed blocks with extractions, in flattened order.
+ */
+export function analyzeBlocks(blocks: Block[], options?: ExtractionOptions): AnalyzedBlock[] {
+  const flat = collectLeafBlocks(blocks);
+  const results: AnalyzedBlock[] = [];
+
+  for (const block of flat) {
+    let plainText = '';
+
+    if (block.contents && block.contents.length > 0) {
+      plainText = contentsToPlainText(block.contents);
+    } else if (block.title) {
+      plainText = block.title;
+    }
+
+    // Strip any remaining markdown syntax
+    const stripped = stripMarkdown(plainText);
+    const bodyWordCount = stripped.split(/\s+/).filter((w) => w.length > 0).length;
+
+    // Run content extraction
+    const extraction = extractContent(stripped, options);
+
+    // Extract images from markdown contents
+    const images = extractBlockImages(block, results.length);
+
+    results.push({
+      block,
+      plainText: stripped,
+      extractions: extraction.elements,
+      hasChildren: !!(block.children && block.children.length > 0),
+      bodyWordCount,
+      images,
+    });
+  }
+
+  return results;
+}

package/src/transform/index.ts

@@ -0,0 +1,20 @@
+export { applyTransform } from './applyTransform.js';
+
+export {
+  resolveTransformStyle,
+  getTransformStyleIds,
+  getTransformStyleSummaries,
+  DEFAULT_TRANSFORM_STYLE_ID,
+} from './registry.js';
+
+export type {
+  TransformStyleId,
+  TransformStyleSummary,
+  TransformStyleConfig,
+  TransformImage,
+  TransformOptions,
+  TransformResult,
+} from './types.js';
+
+export type { AnalyzedBlock, BlockImage } from './blockAnalyzer.js';
+export { analyzeBlocks, extractDocImages } from './blockAnalyzer.js';

package/src/transform/registry.ts

@@ -0,0 +1,47 @@
+/**
+ * Transform Style Registry
+ *
+ * Central registry of built-in transform styles. Follows the same pattern
+ * as themeLibrary.ts — a record of configs with lookup/summary helpers.
+ */
+
+import type { TransformStyleConfig, TransformStyleSummary } 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';
+
+/** All registered 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,
+};
+
+/** Default style used when no id is provided. */
+export const DEFAULT_TRANSFORM_STYLE_ID = 'documentary';
+
+/**
+ * Resolve a transform style by id.
+ * Returns the default style if the id is not found.
+ */
+export function resolveTransformStyle(id: string): TransformStyleConfig {
+  return TRANSFORM_STYLES[id] ?? TRANSFORM_STYLES[DEFAULT_TRANSFORM_STYLE_ID];
+}
+
+/** Get all registered style ids. */
+export function getTransformStyleIds(): string[] {
+  return Object.keys(TRANSFORM_STYLES);
+}
+
+/** Get summary info for all styles (for UI dropdowns). */
+export function getTransformStyleSummaries(): TransformStyleSummary[] {
+  return Object.values(TRANSFORM_STYLES).map(({ id, name, description }) => ({
+    id,
+    name,
+    description,
+  }));
+}

package/src/transform/styles/dataDriven.ts

@@ -0,0 +1,16 @@
+import type { TransformStyleConfig } from '../types.js';
+
+/** Numbers-forward — aggressively extracts stats, comparisons, and dates. */
+export const dataDrivenStyle: TransformStyleConfig = {
+  id: 'data-driven',
+  name: 'Data-Driven',
+  description: 'Aggressively highlights statistics, comparisons, and timelines',
+  minConfidence: 0.3,
+  transformRatio: 0.8,
+  preferredTypes: ['stat', 'comparison', 'date', 'list', 'fact'],
+  colorSchemes: ['blue', 'orange', 'green', 'purple', 'red'],
+  insertSectionHeaders: true,
+  interleaveImages: false,
+  blocksPerSection: { min: 2, max: 6 },
+  transitionStyle: 'cut',
+};

package/src/transform/styles/documentary.ts

@@ -0,0 +1,16 @@
+import type { TransformStyleConfig } from '../types.js';
+
+/** Conservative style — sparse highlights, preserves most text as-is. */
+export const documentaryStyle: TransformStyleConfig = {
+  id: 'documentary',
+  name: 'Documentary',
+  description: 'Conservative — highlights only the strongest stats, dates, and quotes',
+  minConfidence: 0.5,
+  transformRatio: 0.3,
+  preferredTypes: ['stat', 'date', 'quote', 'fact'],
+  colorSchemes: ['blue', 'green', 'purple'],
+  insertSectionHeaders: false,
+  interleaveImages: true,
+  blocksPerSection: { min: 1, max: 3 },
+  transitionStyle: 'fade',
+};

package/src/transform/styles/index.ts

@@ -0,0 +1,5 @@
+export { documentaryStyle } from './documentary.js';
+export { magazineStyle } from './magazine.js';
+export { dataDrivenStyle } from './dataDriven.js';
+export { narrativeStyle } from './narrative.js';
+export { minimalStyle } from './minimal.js';

package/src/transform/styles/magazine.ts

@@ -0,0 +1,16 @@
+import type { TransformStyleConfig } from '../types.js';
+
+/** Visual variety — pull quotes, definitions, image-heavy layout. */
+export const magazineStyle: TransformStyleConfig = {
+  id: 'magazine',
+  name: 'Magazine',
+  description: 'Visual variety with pull quotes, facts, and rich image layouts',
+  minConfidence: 0.4,
+  transformRatio: 0.6,
+  preferredTypes: ['quote', 'fact', 'list', 'definition', 'stat', 'impactLine'],
+  colorSchemes: ['blue', 'green', 'purple', 'orange', 'red'],
+  insertSectionHeaders: true,
+  interleaveImages: true,
+  blocksPerSection: { min: 2, max: 5 },
+  transitionStyle: 'dissolve',
+};

package/src/transform/styles/minimal.ts

@@ -0,0 +1,16 @@
+import type { TransformStyleConfig } from '../types.js';
+
+/** Light touch — only the highest-confidence items get transformed. */
+export const minimalStyle: TransformStyleConfig = {
+  id: 'minimal',
+  name: 'Minimal',
+  description: 'Light touch — only the strongest highlights, mostly text',
+  minConfidence: 0.6,
+  transformRatio: 0.2,
+  preferredTypes: ['stat', 'quote'],
+  colorSchemes: ['blue', 'green'],
+  insertSectionHeaders: false,
+  interleaveImages: false,
+  blocksPerSection: { min: 1, max: 2 },
+  transitionStyle: 'fade',
+};

package/src/transform/styles/narrative.ts

@@ -0,0 +1,16 @@
+import type { TransformStyleConfig } from '../types.js';
+
+/** Timeline-focused — emphasizes dates, quotes, and story arc. */
+export const narrativeStyle: TransformStyleConfig = {
+  id: 'narrative',
+  name: 'Narrative',
+  description: 'Story-driven with timeline events, quotes, and impact moments',
+  minConfidence: 0.4,
+  transformRatio: 0.5,
+  preferredTypes: ['date', 'quote', 'impactLine', 'fact', 'stat'],
+  colorSchemes: ['blue', 'purple', 'green'],
+  insertSectionHeaders: true,
+  interleaveImages: true,
+  blocksPerSection: { min: 1, max: 4 },
+  transitionStyle: 'fade',
+};

package/src/transform/templateSelector.ts

@@ -0,0 +1,294 @@
+/**
+ * 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 } from '../schemas/Doc.js';
+import type {
+  TemplateBlock,
+  AccentImage,
+  AccentPosition,
+  ImageWithCaptionInput,
+  SectionHeaderInput,
+} 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';
+
+/** 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
+  const maxTransforms = Math.max(1, Math.floor(analyzed.length * config.transformRatio));
+  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],
+      };
+      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++;
+      }
+
+      const templateBlock = mapElementToBlock(sel.element, {
+        id: `transform-${blockIdCounter++}`,
+        duration: ab.block.duration > 0 ? ab.block.duration / extractions.length : 6,
+        audioSegment: ab.block.audioSegment,
+        colorScheme,
+        accentImage,
+        sourceStartTime: sel.element.sourcePosition,
+      });
+
+      // Apply transition based on style
+      if (config.transitionStyle !== 'cut') {
+        (
+          templateBlock as TemplateBlock & { transition?: { type: string; duration: number } }
+        ).transition = {
+          type:
+            config.transitionStyle === 'mixed'
+              ? (rng.pick(['fade', 'dissolve']) ?? 'fade')
+              : config.transitionStyle,
+          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',
+        };
+        blocks.push(imageBlock);
+        imageIndex++;
+        insertedCount++;
+        elementsSinceImage = 0;
+      }
+    }
+  }
+
+  return { blocks, transformedCount, insertedCount };
+}