@bendyline/squisq 2.1.0 → 2.3.0

package/src/transform/applyTransform.ts

@@ -1,122 +0,0 @@
-/**
- * Apply Transform
- *
- * Main entry point for the transform module. Takes a Doc and a style,
- * analyzes block content, selects extractions to promote, and returns
- * a new Doc with blocks optimized for visual presentation.
- *
- * The input Doc is never mutated — a fresh Doc is always returned.
- */
-
-import type { Doc } from '../schemas/Doc.js';
-import type { DocBlock, TitleBlockInput, SectionHeaderInput } from '../schemas/BlockTemplates.js';
-import type { TransformStyleInput, TransformOptions, TransformResult } from './types.js';
-import { resolveTransformStyle } from './registry.js';
-import { analyzeBlocks, extractDocImages } from './blockAnalyzer.js';
-import { selectAndBuild } from './templateSelector.js';
-import { allocateTiming } from './timingAllocator.js';
-import { hashString } from '../random/SeededRandom.js';
-
-/**
- * Apply a transform style to a Doc, producing a new Doc with blocks
- * optimized for visual presentation.
- *
- * @param doc - The source Doc (not mutated).
- * @param style - Built-in/registry id or a call-scoped declarative style.
- * @param options - Optional seed, images, theme override, and explicit registry.
- * @returns TransformResult with the new Doc and stats.
- */
-export function applyTransform(
-  doc: Doc,
-  style: TransformStyleInput,
-  options?: TransformOptions,
-): TransformResult {
-  const baseConfig = resolveTransformStyle(style, options?.registry);
-  const config = options?.overrides
-    ? { ...baseConfig, ...options.overrides, id: baseConfig.id }
-    : baseConfig;
-
-  const seed = options?.seed ?? hashString(doc.articleId || 'transform');
-
-  // Use provided images or auto-extract from the doc's markdown content
-  const images = options?.images ?? extractDocImages(doc.blocks);
-
-  // 1. Analyze blocks
-  const analyzed = analyzeBlocks(doc.blocks, {
-    minConfidence: config.minConfidence,
-    types: config.preferredTypes,
-  });
-
-  // If no blocks have meaningful content, return the doc unchanged
-  const hasContent = analyzed.some((ab) => ab.bodyWordCount >= 5);
-  if (!hasContent) {
-    return {
-      doc: { ...doc },
-      stats: {
-        totalInputBlocks: doc.blocks.length,
-        transformedBlocks: 0,
-        insertedBlocks: 0,
-      },
-    };
-  }
-
-  // 2. Select extractions and build template blocks
-  const selection = selectAndBuild(analyzed, config, images, seed);
-
-  // 2b. Pacing bookends: an opening title beat and/or a closing beat.
-  let paced: DocBlock[] = selection.blocks;
-  let pacingInserted = 0;
-  const docTitle = firstTitle(doc);
-  if (config.pacing?.intro && docTitle && !doc.startBlock) {
-    const intro: TitleBlockInput = {
-      template: 'title',
-      id: 'transform-intro',
-      duration: 4,
-      audioSegment: 0,
-      title: docTitle,
-    };
-    paced = [intro, ...paced];
-    pacingInserted++;
-  }
-  if (config.pacing?.outro && docTitle) {
-    const outro: SectionHeaderInput = {
-      template: 'sectionHeader',
-      id: 'transform-outro',
-      duration: 3,
-      audioSegment: 0,
-      title: docTitle,
-      colorScheme: config.colorSchemes[0],
-    };
-    paced = [...paced, outro];
-    pacingInserted++;
-  }
-
-  // 3. Allocate timing across the new block sequence
-  const timedBlocks = allocateTiming(paced, doc.duration);
-
-  // 4. Assemble the output Doc. A style's suggested theme applies only
-  // when neither the caller nor the doc declares one.
-  const transformedDoc: Doc = {
-    ...doc,
-    blocks: timedBlocks,
-    themeId: options?.themeId ?? doc.themeId ?? config.suggestedThemeId,
-  };
-
-  return {
-    doc: transformedDoc,
-    stats: {
-      totalInputBlocks: doc.blocks.length,
-      transformedBlocks: selection.transformedCount,
-      insertedBlocks: selection.insertedCount + pacingInserted,
-    },
-  };
-}
-
-/** First non-empty block title (the doc's working title). */
-function firstTitle(doc: Doc): string | undefined {
-  if (doc.startBlock?.title) return doc.startBlock.title;
-  for (const block of doc.blocks) {
-    if (block.title) return block.title;
-  }
-  return undefined;
-}

package/src/transform/blockAnalyzer.ts

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

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

package/src/transform/registry.ts

@@ -1,217 +0,0 @@
-/**
- * Transform Style Registry
- *
- * Immutable built-in lookup plus explicit caller-owned custom registries.
- * There is deliberately no process-global mutable registry.
- */
-
-import type { TransformStyleConfig, TransformStyleInput, TransformStyleRegistry } from './types.js';
-import { documentaryStyle } from './styles/documentary.js';
-import { magazineStyle } from './styles/magazine.js';
-import { dataDrivenStyle } from './styles/dataDriven.js';
-import { narrativeStyle } from './styles/narrative.js';
-import { minimalStyle } from './styles/minimal.js';
-import { cloneAndFreezeData } from '../internal/immutable.js';
-
-/** All built-in transform styles, keyed by id. */
-const TRANSFORM_STYLES: Readonly<Record<string, TransformStyleConfig>> = Object.freeze({
-  [documentaryStyle.id]: cloneAndFreezeData(documentaryStyle),
-  [magazineStyle.id]: cloneAndFreezeData(magazineStyle),
-  [dataDrivenStyle.id]: cloneAndFreezeData(dataDrivenStyle),
-  [narrativeStyle.id]: cloneAndFreezeData(narrativeStyle),
-  [minimalStyle.id]: cloneAndFreezeData(minimalStyle),
-});
-
-/** Default style used when no id is provided. */
-export const DEFAULT_TRANSFORM_STYLE_ID = 'documentary';
-
-const EXTRACTION_TYPES = new Set([
-  'stat',
-  'date',
-  'quote',
-  'comparison',
-  'fact',
-  'impactLine',
-  'list',
-  'definition',
-]);
-const TRANSITION_STYLES = new Set(['cut', 'fade', 'dissolve', 'mixed']);
-
-function validateTransformStyle(style: TransformStyleConfig): void {
-  const candidate = style as unknown as Record<string, unknown>;
-  const fail = (message: string): never => {
-    throw new TypeError(`Invalid transform style: ${message}`);
-  };
-  for (const key of ['id', 'name', 'description']) {
-    if (typeof candidate[key] !== 'string' || !(candidate[key] as string).trim()) {
-      fail(`${key} must be a non-empty string`);
-    }
-  }
-  for (const key of ['minConfidence', 'transformRatio']) {
-    const value = candidate[key];
-    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1) {
-      fail(`${key} must be a finite number between 0 and 1`);
-    }
-  }
-  if (
-    !Array.isArray(candidate.preferredTypes) ||
-    candidate.preferredTypes.some((type) => !EXTRACTION_TYPES.has(type))
-  ) {
-    fail('preferredTypes contains an unknown extraction type');
-  }
-  if (
-    !Array.isArray(candidate.colorSchemes) ||
-    candidate.colorSchemes.length === 0 ||
-    candidate.colorSchemes.some((scheme) => typeof scheme !== 'string' || !scheme)
-  ) {
-    fail('colorSchemes must contain at least one non-empty string');
-  }
-  for (const key of ['insertSectionHeaders', 'interleaveImages']) {
-    if (typeof candidate[key] !== 'boolean') fail(`${key} must be a boolean`);
-  }
-  const blocks = candidate.blocksPerSection as { max?: unknown } | undefined;
-  if (!blocks || !Number.isInteger(blocks.max) || (blocks.max as number) < 1) {
-    fail('blocksPerSection.max must be a positive integer');
-  }
-  if (
-    typeof candidate.transitionStyle !== 'string' ||
-    !TRANSITION_STYLES.has(candidate.transitionStyle)
-  ) {
-    fail('transitionStyle must be cut, fade, dissolve, or mixed');
-  }
-  const templateMap = candidate.templateMap;
-  if (templateMap !== undefined) {
-    if (!templateMap || typeof templateMap !== 'object' || Array.isArray(templateMap)) {
-      fail('templateMap must be an object');
-    }
-    for (const [type, template] of Object.entries(templateMap as Record<string, unknown>)) {
-      if (!EXTRACTION_TYPES.has(type) || typeof template !== 'string' || !template) {
-        fail('templateMap must map known extraction types to non-empty template names');
-      }
-    }
-  }
-  if (
-    candidate.suggestedThemeId !== undefined &&
-    (typeof candidate.suggestedThemeId !== 'string' || !candidate.suggestedThemeId)
-  ) {
-    fail('suggestedThemeId must be a non-empty string');
-  }
-  const pacingValue = candidate.pacing;
-  if (pacingValue !== undefined) {
-    if (!pacingValue || typeof pacingValue !== 'object' || Array.isArray(pacingValue)) {
-      fail('pacing must be an object');
-    }
-    const pacing = pacingValue as { intro?: unknown; outro?: unknown };
-    for (const key of ['intro', 'outro'] as const) {
-      if (pacing[key] !== undefined && typeof pacing[key] !== 'boolean') {
-        fail(`pacing.${key} must be a boolean`);
-      }
-    }
-  }
-  const budget = candidate.budget as { slidesPerMinute?: unknown } | undefined;
-  if (
-    candidate.budget !== undefined &&
-    (!budget || typeof budget !== 'object' || Array.isArray(budget))
-  ) {
-    fail('budget must be an object');
-  }
-  if (budget && budget.slidesPerMinute !== undefined) {
-    const value = budget.slidesPerMinute;
-    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
-      fail('budget.slidesPerMinute must be a positive finite number');
-    }
-  }
-  const pageValue = candidate.page;
-  if (pageValue !== undefined) {
-    if (!pageValue || typeof pageValue !== 'object' || Array.isArray(pageValue)) {
-      fail('page must be an object');
-    }
-    const page = pageValue as { spacing?: unknown; emphasisCurve?: unknown };
-    if (
-      page.spacing !== undefined &&
-      !['compact', 'comfortable', 'generous'].includes(page.spacing as string)
-    ) {
-      fail('page.spacing must be compact, comfortable, or generous');
-    }
-    if (
-      page.emphasisCurve !== undefined &&
-      !['even', 'front-loaded'].includes(page.emphasisCurve as string)
-    ) {
-      fail('page.emphasisCurve must be even or front-loaded');
-    }
-  }
-}
-
-function styleSnapshot(style: TransformStyleConfig): TransformStyleConfig {
-  validateTransformStyle(style);
-  return cloneAndFreezeData(style);
-}
-
-/** Stored documents emitted before the canonical kebab-case id. Not exported. */
-function normalizeBuiltinStyleId(id: string): string {
-  return id === 'dataDriven' ? 'data-driven' : id;
-}
-
-function resolveBuiltinStyle(id: string): TransformStyleConfig {
-  return (
-    TRANSFORM_STYLES[normalizeBuiltinStyleId(id)] ?? TRANSFORM_STYLES[DEFAULT_TRANSFORM_STYLE_ID]
-  );
-}
-
-/**
- * Create a caller-owned registry. Custom styles are validated, cloned, and
- * deeply frozen at registration time. Built-in resolution remains in the
- * top-level helpers, separate from the registry's caller-owned state.
- */
-export function createTransformStyleRegistry(
-  initialStyles: readonly TransformStyleConfig[] = [],
-): TransformStyleRegistry {
-  const registeredStyles = new Map<string, TransformStyleConfig>();
-  const registry: TransformStyleRegistry = {
-    register(style): void {
-      const snapshot = styleSnapshot(style);
-      registeredStyles.set(snapshot.id, snapshot);
-    },
-    unregister(id): boolean {
-      return registeredStyles.delete(id);
-    },
-    get(id): TransformStyleConfig | undefined {
-      return registeredStyles.get(id);
-    },
-    list(): TransformStyleConfig[] {
-      return Array.from(registeredStyles.values());
-    },
-  };
-  for (const style of initialStyles) registry.register(style);
-  return Object.freeze(registry);
-}
-
-/**
- * Resolve a built-in id, explicit-registry id, or call-scoped style config.
- * Unknown ids fall back to the default style.
- */
-export function resolveTransformStyle(
-  style: TransformStyleInput,
-  registry?: TransformStyleRegistry,
-): TransformStyleConfig {
-  if (typeof style !== 'string') return styleSnapshot(style);
-  return registry?.get(style) ?? resolveBuiltinStyle(style);
-}
-
-/** Get built-in ids plus ids from an optional caller-owned registry. */
-export function getTransformStyleIds(registry?: TransformStyleRegistry): string[] {
-  return Array.from(
-    new Set([
-      ...Object.keys(TRANSFORM_STYLES),
-      ...(registry?.list().map((style) => style.id) ?? []),
-    ]),
-  );
-}
-
-/** Get summaries for built-ins plus an optional caller-owned registry. */
-export function getTransformStyleSummaries(registry?: TransformStyleRegistry) {
-  return getTransformStyleIds(registry).map((id) => {
-    const { name, description } = resolveTransformStyle(id, registry);
-    return { id, name, description };
-  });
-}

package/src/transform/styles/dataDriven.ts

@@ -1,18 +0,0 @@
-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: { max: 6 },
-  transitionStyle: 'cut',
-  suggestedThemeId: 'tech-dark',
-  page: { spacing: 'compact', emphasisCurve: 'even' },
-};

package/src/transform/styles/documentary.ts

@@ -1,18 +0,0 @@
-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: { max: 3 },
-  transitionStyle: 'fade',
-  suggestedThemeId: 'documentary',
-  page: { spacing: 'generous', emphasisCurve: 'front-loaded' },
-};

package/src/transform/styles/index.ts

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

@@ -1,19 +0,0 @@
-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: { max: 5 },
-  transitionStyle: 'dissolve',
-  suggestedThemeId: 'magazine',
-  templateMap: { quote: 'pullQuote', impactLine: 'fullBleedQuote' },
-  page: { spacing: 'comfortable', emphasisCurve: 'front-loaded' },
-};

package/src/transform/styles/minimal.ts

@@ -1,18 +0,0 @@
-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: { max: 2 },
-  transitionStyle: 'fade',
-  suggestedThemeId: 'minimalist',
-  page: { spacing: 'generous', emphasisCurve: 'even' },
-};

package/src/transform/styles/narrative.ts

@@ -1,19 +0,0 @@
-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: { max: 4 },
-  transitionStyle: 'fade',
-  suggestedThemeId: 'cinematic',
-  pacing: { intro: true, outro: true },
-  page: { spacing: 'comfortable', emphasisCurve: 'even' },
-};