@bendyline/squisq 1.1.0 → 1.2.0

package/src/markdown/convert.ts

@@ -181,17 +181,25 @@ function extractTemplateAnnotation(
  */
 function parseAnnotationTokens(inner: string): HeadingTemplateAnnotation {
   const tokens = inner.split(/\s+/);
-  const template = tokens[0];
   const params: Record<string, string> = {};
 
-  for (let i = 1; i < tokens.length; i++) {
+  // If the first token contains '=', there's no template name —
+  // the annotation is purely key-value (e.g., `{[audio=intro.mp3]}`).
+  const firstIsParam = tokens[0].indexOf('=') > 0;
+  const template = firstIsParam ? undefined : tokens[0];
+  const startIdx = firstIsParam ? 0 : 1;
+
+  for (let i = startIdx; i < tokens.length; i++) {
     const eqIdx = tokens[i].indexOf('=');
     if (eqIdx > 0) {
       params[tokens[i].slice(0, eqIdx)] = tokens[i].slice(eqIdx + 1);
     }
   }
 
-  const result: HeadingTemplateAnnotation = { template };
+  const result: HeadingTemplateAnnotation = {};
+  if (template) {
+    result.template = template;
+  }
   if (Object.keys(params).length > 0) {
     result.params = params;
   }
@@ -202,14 +210,16 @@ function parseAnnotationTokens(inner: string): HeadingTemplateAnnotation {
  * Serialize a HeadingTemplateAnnotation back to `{[templateName key=value …]}` text.
  */
 function serializeTemplateAnnotation(annotation: HeadingTemplateAnnotation): string {
-  let result = `{[${annotation.template}`;
+  const parts: string[] = [];
+  if (annotation.template) {
+    parts.push(annotation.template);
+  }
   if (annotation.params) {
     for (const [key, value] of Object.entries(annotation.params)) {
-      result += ` ${key}=${value}`;
+      parts.push(`${key}=${value}`);
     }
   }
-  result += ']}';
-  return result;
+  return `{[${parts.join(' ')}]}`;
 }
 
 /**

package/src/markdown/types.ts

@@ -118,8 +118,10 @@ interface MarkdownNodeBase {
  * → `{ template: 'chart', params: { colorScheme: 'blue' } }`
  */
 export interface HeadingTemplateAnnotation {
-  /** Template name (first token inside `{[…]}`) */
-  template: string;
+  /** Template name (first token inside `{[…]}`).
+   *  Optional when the annotation contains only key=value pairs
+   *  (e.g., `{[audio=intro.mp3]}`). */
+  template?: string;
   /** Optional key-value parameters (remaining `key=value` tokens) */
   params?: Record<string, string>;
 }

package/src/schemas/BlockTemplates.ts

@@ -39,12 +39,12 @@ export type ColorScheme = string;
  * PT Serif provides a classic, readable appearance for documentary-style content.
  * Used as a fallback in TextLayer when no font is specified.
  */
-export const DEFAULT_DOC_FONT = '"PT Serif", Georgia, "Times New Roman", serif';
+export const DEFAULT_DOC_FONT = 'system-ui, -apple-system, "Segoe UI", Roboto, sans-serif';
 
 /**
  * Default font family for titles.
  */
-export const DEFAULT_TITLE_FONT = '"PT Serif", Georgia, "Times New Roman", serif';
+export const DEFAULT_TITLE_FONT = 'Georgia, "Times New Roman", serif';
 
 // ============================================
 // Accent Image System
@@ -429,6 +429,24 @@ export interface VideoPullQuoteInput extends BaseTemplateBlock {
   };
 }
 
+/**
+ * Data table - renders a themed table with headers and rows.
+ * Ideal for structured data, comparisons, and reference information.
+ */
+export interface DataTableInput extends BaseTemplateBlock {
+  template: 'dataTable';
+  /** Optional title displayed above the table */
+  title?: string;
+  /** Header cell values */
+  headers: string[];
+  /** Data rows (array of cell value arrays) */
+  rows: string[][];
+  /** Per-column alignment */
+  align?: (('left' | 'right' | 'center') | null)[];
+  /** Color scheme for the table header */
+  colorScheme?: ColorScheme;
+}
+
 /**
  * Union of all template block types.
  */
@@ -449,7 +467,8 @@ export type TemplateBlock =
   | ComparisonBarInput
   | PullQuoteInput
   | VideoWithCaptionInput
-  | VideoPullQuoteInput;
+  | VideoPullQuoteInput
+  | DataTableInput;
 
 /**
  * A block can be either a raw Block or a TemplateBlock.

package/src/schemas/Doc.ts

@@ -127,6 +127,13 @@ export interface Block {
   /** Template name that generated this block (for debugging) */
   template?: string;
 
+  /**
+   * Display title for template rendering.
+   * Extracted from the sourceHeading when the block is created by markdownToDoc().
+   * Templates like sectionHeader and titleBlock read this for their title layer.
+   */
+  title?: string;
+
   // ── Markdown-driven hierarchy (optional) ──
 
   /**
@@ -170,7 +177,7 @@ export interface Block {
  * A visual element within a block.
  * Layers are composited back-to-front (first layer is background).
  */
-export type Layer = ImageLayer | TextLayer | ShapeLayer | MapLayer | VideoLayer;
+export type Layer = ImageLayer | TextLayer | ShapeLayer | MapLayer | VideoLayer | TableLayer;
 
 interface BaseLayer {
   /** Unique identifier for this layer */
@@ -293,6 +300,48 @@ export interface VideoLayer extends BaseLayer {
   };
 }
 
+/**
+ * Table layer - renders a data table with themed styling.
+ * Uses foreignObject inside SVG for HTML-based table layout.
+ */
+export interface TableLayer extends BaseLayer {
+  type: 'table';
+  content: {
+    /** Header cell values */
+    headers: string[];
+    /** Data rows (array of cell value arrays) */
+    rows: string[][];
+    /** Per-column alignment */
+    align?: (('left' | 'right' | 'center') | null)[];
+    /** Visual styling */
+    style: TableLayerStyle;
+  };
+}
+
+/**
+ * Styling options for a TableLayer.
+ */
+export interface TableLayerStyle {
+  /** Header row background color */
+  headerBackground: string;
+  /** Header row text color */
+  headerColor: string;
+  /** Body cell background color */
+  cellBackground: string;
+  /** Body cell text color */
+  cellColor: string;
+  /** Border/divider color */
+  borderColor: string;
+  /** Font size in pixels */
+  fontSize: number;
+  /** Font family */
+  fontFamily?: string;
+  /** Header font family (falls back to fontFamily) */
+  headerFontFamily?: string;
+  /** Corner radius for the table container */
+  borderRadius?: number;
+}
+
 /**
  * Available map tile styles from free/open-source providers.
  */
@@ -436,6 +485,19 @@ export interface AudioTrack {
 // Captions
 // ============================================
 
+/**
+ * A single word with precise timing, used for word-level highlighting
+ * in social-style captions. Populated from TTS timing data when available.
+ */
+export interface CaptionWord {
+  /** The word text */
+  text: string;
+  /** Start time in seconds (relative to doc start) */
+  startTime: number;
+  /** End time in seconds */
+  endTime: number;
+}
+
 /**
  * A single caption phrase to display during playback.
  */
@@ -448,6 +510,13 @@ export interface CaptionPhrase {
   endTime: number;
   /** Which audio segment this caption belongs to (0-indexed) */
   audioSegment: number;
+  /**
+   * Optional per-word timing from TTS timing data.
+   * When present, enables precise word-level highlighting in social
+   * caption style. When absent, word timing is interpolated evenly
+   * across the phrase duration.
+   */
+  words?: CaptionWord[];
 }
 
 /**
@@ -476,6 +545,39 @@ export interface AudioSegment {
   startTime: number;
 }
 
+// ============================================
+// Audio Timing Data (from TTS)
+// ============================================
+
+/**
+ * A single word-level timing bookmark from TTS synthesis.
+ * Used for precise audio-to-content mapping and word-level caption sync.
+ */
+export interface AudioBookmark {
+  /** Unique identifier (e.g., "word-0", "word-1") */
+  id: string;
+  /** Timestamp in seconds from audio start */
+  time: number;
+  /** Character offset in the source text */
+  charOffset: number;
+  /** The word text at this position */
+  textFragment?: string;
+}
+
+/**
+ * Timing data for an audio segment, typically from a `.timing.json` file
+ * generated alongside TTS audio. Contains the source text and per-word
+ * timing bookmarks for precise content matching and caption sync.
+ */
+export interface AudioTimingData {
+  /** The normalized plain text that was synthesized */
+  sourceText: string;
+  /** Word-level timing bookmarks */
+  bookmarks: AudioBookmark[];
+  /** Total audio duration in seconds */
+  duration: number;
+}
+
 // ============================================
 // Helper Functions
 // ============================================

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