@bendyline/squisq 1.1.0 → 1.1.1

package/src/schemas/themeLibrary.ts

@@ -19,11 +19,32 @@ import type { Theme, ThemeColorScheme } from './Theme.js';
 // Shared constants
 // ============================================
 
-const SERIF = '"PT Serif", Georgia, "Times New Roman", serif';
-const SANS = '"Inter", "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif';
-const MONO = '"JetBrains Mono", "Fira Code", "Consolas", monospace';
-const MERRIWEATHER = '"Merriweather", Georgia, "Times New Roman", serif';
-const GEORGIA = 'Georgia, "Times New Roman", serif';
+// ── Font stacks ──────────────────────────────────────────────────
+// Each stack lists the recommended Google Font first (works when the
+// wrapping site loads it), then degrades to safe system fonts.
+// Squisq itself does NOT load Google Fonts.
+
+/** System fonts only — no external dependencies. */
+const SYSTEM_SANS = 'system-ui, -apple-system, "Segoe UI", Roboto, sans-serif';
+const SYSTEM_SERIF = 'Georgia, "Times New Roman", serif';
+const SYSTEM_MONO = 'Consolas, "Courier New", monospace';
+
+/** Theme-specific stacks with Google Font leads. */
+const PLAYFAIR = '"Playfair Display", Georgia, serif';
+const SOURCE_SERIF = '"Source Serif 4", "PT Serif", Georgia, serif';
+const INTER = '"Inter", "Segoe UI", Roboto, sans-serif';
+const OSWALD = '"Oswald", Impact, "Arial Black", sans-serif';
+const ROBOTO = '"Roboto", "Segoe UI", Arial, sans-serif';
+const MERRIWEATHER = '"Merriweather", Georgia, serif';
+const LORA = '"Lora", "Merriweather", Georgia, serif';
+const JETBRAINS_MONO = '"JetBrains Mono", "Fira Code", Consolas, monospace';
+const IBM_PLEX_SANS = '"IBM Plex Sans", "Segoe UI", Roboto, sans-serif';
+const DM_SERIF = '"DM Serif Display", Georgia, serif';
+const DM_SANS = '"DM Sans", "Segoe UI", Roboto, sans-serif';
+const CORMORANT = '"Cormorant Garamond", Garamond, Georgia, serif';
+const CRIMSON = '"Crimson Text", Georgia, serif';
+const PT_SERIF = '"PT Serif", Georgia, serif';
+const HANKEN_GROTESK = '"Hanken Grotesk", system-ui, sans-serif';
 
 /** Standard 6-scheme set used by the documentary theme (migrated from old COLOR_SCHEMES). */
 const CLASSIC_COLOR_SCHEMES: Record<string, ThemeColorScheme> = {
@@ -36,13 +57,60 @@ const CLASSIC_COLOR_SCHEMES: Record<string, ThemeColorScheme> = {
 };
 
 // ============================================
-// 1. Documentary (default — migrated from old DEFAULT_THEME)
+// 1. Standard (default — safe system fonts, no external dependencies)
+// ============================================
+
+const standard: Theme = {
+  id: 'standard',
+  name: 'Standard',
+  description: 'Clean and safe. System fonts only — no external font dependencies.',
+  colors: {
+    primary: '#3182ce',
+    secondary: '#4a5568',
+    background: '#1a202c',
+    backgroundLight: '#2d3748',
+    text: '#f7fafc',
+    textMuted: '#a0aec0',
+    highlight: '#4299e1',
+    warning: '#fc8181',
+  },
+  typography: {
+    bodyFontFamily: SYSTEM_SANS,
+    titleFontFamily: SYSTEM_SERIF,
+    monoFontFamily: SYSTEM_MONO,
+    titleWeight: 'bold',
+  },
+  style: {
+    textShadow: true,
+    overlayOpacity: 0.45,
+    animationSpeed: 1.0,
+  },
+  renderStyle: {
+    name: 'standard',
+    defaultTextAnimation: 'fadeIn',
+    defaultImageAnimation: 'slowZoom',
+    ambientMotion: true,
+    defaultTransition: { type: 'fade', duration: 0.7 },
+  },
+  colorSchemes: CLASSIC_COLOR_SCHEMES,
+  persistentLayers: {
+    bottomLayers: [
+      {
+        template: 'gradientBackground',
+        config: { type: 'gradientBackground', preset: 'dark-vignette' },
+      },
+    ],
+  },
+};
+
+// ============================================
+// 2. Documentary
 // ============================================
 
 const documentary: Theme = {
   id: 'documentary',
   name: 'Documentary',
-  description: 'Classic dark cinematic look with serif typography. The original Squisq style.',
+  description: 'Classic dark cinematic look with elegant serif typography.',
   colors: {
     primary: '#3d5a80',
     secondary: '#63b3ed',
@@ -54,8 +122,8 @@ const documentary: Theme = {
     warning: '#fc8181',
   },
   typography: {
-    bodyFontFamily: SERIF,
-    titleFontFamily: SERIF,
+    bodyFontFamily: SOURCE_SERIF,
+    titleFontFamily: PLAYFAIR,
     titleWeight: 'bold',
   },
   style: {
@@ -100,8 +168,8 @@ const minimalist: Theme = {
     warning: '#e53e3e',
   },
   typography: {
-    bodyFontFamily: SANS,
-    titleFontFamily: SANS,
+    bodyFontFamily: INTER,
+    titleFontFamily: INTER,
     titleWeight: 'bold',
     lineHeight: 1.6,
   },
@@ -149,8 +217,8 @@ const bold: Theme = {
     warning: '#fc8181',
   },
   typography: {
-    bodyFontFamily: SANS,
-    titleFontFamily: SANS,
+    bodyFontFamily: ROBOTO,
+    titleFontFamily: OSWALD,
     titleWeight: 'bold',
     titleScale: 1.15,
     bodyScale: 1.0,
@@ -201,7 +269,7 @@ const morningLight: Theme = {
     warning: '#c53030',
   },
   typography: {
-    bodyFontFamily: MERRIWEATHER,
+    bodyFontFamily: LORA,
     titleFontFamily: MERRIWEATHER,
     titleWeight: 'bold',
     lineHeight: 1.7,
@@ -247,9 +315,9 @@ const techDark: Theme = {
     warning: '#ff5252',
   },
   typography: {
-    bodyFontFamily: SANS,
-    titleFontFamily: MONO,
-    monoFontFamily: MONO,
+    bodyFontFamily: IBM_PLEX_SANS,
+    titleFontFamily: JETBRAINS_MONO,
+    monoFontFamily: JETBRAINS_MONO,
     titleWeight: 'bold',
     titleScale: 0.9,
     lineHeight: 1.5,
@@ -299,8 +367,8 @@ const magazine: Theme = {
     warning: '#fc8181',
   },
   typography: {
-    bodyFontFamily: SANS,
-    titleFontFamily: GEORGIA,
+    bodyFontFamily: DM_SANS,
+    titleFontFamily: DM_SERIF,
     titleWeight: 'bold',
     titleScale: 1.05,
     lineHeight: 1.5,
@@ -347,8 +415,8 @@ const cinematic: Theme = {
     warning: '#fc8181',
   },
   typography: {
-    bodyFontFamily: SERIF,
-    titleFontFamily: SERIF,
+    bodyFontFamily: CRIMSON,
+    titleFontFamily: CORMORANT,
     titleWeight: 'bold',
     lineHeight: 1.5,
     titleLineHeight: 1.2,
@@ -405,8 +473,8 @@ const warmEarth: Theme = {
     warning: '#e53e3e',
   },
   typography: {
-    bodyFontFamily: GEORGIA,
-    titleFontFamily: GEORGIA,
+    bodyFontFamily: HANKEN_GROTESK,
+    titleFontFamily: PT_SERIF,
     titleWeight: 'bold',
     lineHeight: 1.6,
   },
@@ -448,6 +516,7 @@ const warmEarth: Theme = {
  * All built-in themes, keyed by id.
  */
 export const THEMES: Record<string, Theme> = {
+  standard,
   documentary,
   minimalist,
   bold,
@@ -459,10 +528,10 @@ export const THEMES: Record<string, Theme> = {
 };
 
 /** The default theme id. */
-export const DEFAULT_THEME_ID = 'documentary';
+export const DEFAULT_THEME_ID = 'standard';
 
-/** The default theme (documentary — migrated from old DEFAULT_THEME). */
-export const DEFAULT_THEME: Theme = documentary;
+/** The default theme (standard — safe system fonts, no external dependencies). */
+export const DEFAULT_THEME: Theme = standard;
 
 /**
  * Resolve a theme by id. Returns the default theme when `id` is

package/src/transform/applyTransform.ts

@@ -0,0 +1,83 @@
+/**
+ * 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 { TransformStyleId, 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 styleId - Registered transform style id (e.g. 'documentary', 'magazine').
+ * @param options - Optional seed, images, theme override.
+ * @returns TransformResult with the new Doc and stats.
+ */
+export function applyTransform(
+  doc: Doc,
+  styleId: TransformStyleId,
+  options?: TransformOptions,
+): TransformResult {
+  const baseConfig = resolveTransformStyle(styleId);
+  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);
+
+  // 3. Allocate timing across the new block sequence
+  const timedBlocks = allocateTiming(selection.blocks, doc.duration);
+
+  // 4. Assemble the output Doc
+  const transformedDoc: Doc = {
+    ...doc,
+    blocks: timedBlocks,
+    themeId: options?.themeId ?? doc.themeId,
+  };
+
+  return {
+    doc: transformedDoc,
+    stats: {
+      totalInputBlocks: doc.blocks.length,
+      transformedBlocks: selection.transformedCount,
+      insertedBlocks: selection.insertedCount,
+    },
+  };
+}

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',
+};