@bendyline/squisq 0.1.1

package/src/schemas/Doc.ts

@@ -0,0 +1,565 @@
+/**
+ * Doc Schema
+ *
+ * Defines the JSON format for AI-scriptable visual docs that accompany
+ * audio narration. A Doc describes a sequence of animated blocks
+ * with text overlays, images, and transitions synchronized to audio.
+ *
+ * The format is designed to be:
+ * 1. AI-generatable - Claude can create scripts from article content
+ * 2. Browser-renderable - SVG + CSS animations (ES2015 compatible)
+ * 3. Video-exportable - Frame-by-frame capture via Playwright
+ *
+ * Timing: Blocks are timed to match narration audio segments. Each article
+ * has 3-6 MP3 files (intro + sections), and blocks are grouped by segment.
+ */
+
+// ============================================
+// Core Types
+// ============================================
+
+/**
+ * Configuration for the Start/resting block shown before playback begins.
+ */
+export interface StartBlockConfig {
+  /** Hero image path (relative to article media) */
+  heroSrc: string;
+  /** Alt text for the hero image */
+  heroAlt?: string;
+  /** Title to display over the hero */
+  title: string;
+  /** Optional subtitle */
+  subtitle?: string;
+  /** Ambient motion for the hero image */
+  ambientMotion?: 'zoomIn' | 'zoomOut' | 'panLeft' | 'panRight';
+  /** Photo credit / artist name for the hero image */
+  heroCredit?: string;
+  /** License identifier for the hero image */
+  heroLicense?: string;
+}
+
+/**
+ * A complete visual doc for an article.
+ */
+export interface Doc {
+  /** Article ID this doc belongs to */
+  articleId: string;
+
+  /** Total duration in seconds (sum of all audio segments) */
+  duration: number;
+
+  /** Ordered list of blocks */
+  blocks: Block[];
+
+  /** Audio track configuration */
+  audio: AudioTrack;
+
+  /** Caption track for closed captions (generated by postprocess-doc) */
+  captions?: CaptionTrack;
+
+  /**
+   * Start/resting block shown before playback begins.
+   * Displays hero image with title - acts as a "poster" for the doc.
+   * The player shows this until the user starts playback.
+   */
+  startBlock?: StartBlockConfig;
+
+  /**
+   * Persistent layers rendered on every block (behind and/or on top of content).
+   * Used for consistent branding overlays, background gradients, etc.
+   */
+  persistentLayers?: import('./BlockTemplates.js').PersistentLayerConfig;
+
+  /**
+   * Optional theme identifier. Resolved at render time via `resolveTheme()`.
+   * When omitted, the renderer uses the default theme ('documentary').
+   */
+  themeId?: string;
+
+  /** Optional metadata */
+  meta?: {
+    generatedAt?: string;
+    generatedBy?: string;
+    version?: number;
+  };
+
+  /**
+   * YAML frontmatter from the source markdown.
+   * Carries rendering hints like `document-render-as` and custom metadata.
+   */
+  frontmatter?: Record<string, unknown>;
+}
+
+/**
+ * A single block in the doc.
+ *
+ * Blocks can be flat (audio-synced timeline) or nested (markdown-driven hierarchy).
+ * When derived from markdown, a block corresponds to a heading section:
+ * - `sourceHeading` references the original MarkdownHeading node
+ * - `contents` holds the body markdown between this heading and the next
+ * - `children` holds sub-heading blocks (e.g., H2s under an H1)
+ */
+export interface Block {
+  /** Unique identifier for this block */
+  id: string;
+
+  /** When this block appears (seconds from start) */
+  startTime: number;
+
+  /** How long this block is visible (seconds) */
+  duration: number;
+
+  /** Which audio segment this block belongs to (0-indexed) */
+  audioSegment: number;
+
+  /**
+   * Pre-computed visual layers, rendered back-to-front.
+   *
+   * Optional — template-derived blocks typically omit this and compute
+   * layers on demand via `getLayers()` from `@bendyline/squisq/doc`.
+   * Raw blocks (e.g., hand-crafted by AI) may provide layers directly.
+   */
+  layers?: Layer[];
+
+  /** Entry transition from previous block */
+  transition?: Transition;
+
+  /** Template name that generated this block (for debugging) */
+  template?: string;
+
+  // ── Markdown-driven hierarchy (optional) ──
+
+  /**
+   * Nested sub-blocks (heading hierarchy).
+   * When a doc is derived from markdown, sub-headings within this
+   * heading's section become child blocks. For example, H2 blocks
+   * under an H1 block appear here.
+   */
+  children?: Block[];
+
+  /**
+   * Markdown body content for this block's section.
+   * Contains the block-level markdown nodes (paragraphs, lists, code,
+   * blockquotes, etc.) that appear between this heading and the next
+   * heading or sub-heading. Empty for pure structural blocks.
+   */
+  contents?: import('../markdown/types.js').MarkdownBlockNode[];
+
+  /**
+   * Reference to the MarkdownHeading node that created this block.
+   * Present when the block was derived from markdown via markdownToDoc().
+   * Enables round-tripping back to markdown and provides heading depth.
+   * Absent for the preamble block (content before the first heading).
+   */
+  sourceHeading?: import('../markdown/types.js').MarkdownHeading;
+
+  /**
+   * Template overrides extracted from markdown directives.
+   * For example, `### Data Section {template=chart colorScheme=blue}`
+   * would produce `{ template: 'chart', colorScheme: 'blue' }`.
+   * Allows per-block customization of template selection and parameters.
+   */
+  templateOverrides?: Record<string, string>;
+}
+
+// ============================================
+// Layer Types
+// ============================================
+
+/**
+ * A visual element within a block.
+ * Layers are composited back-to-front (first layer is background).
+ */
+export type Layer = ImageLayer | TextLayer | ShapeLayer | MapLayer | VideoLayer;
+
+interface BaseLayer {
+  /** Unique identifier for this layer */
+  id: string;
+
+  /** Position and size */
+  position: Position;
+
+  /** Animation to apply */
+  animation?: Animation;
+}
+
+/**
+ * Image layer - displays an image with optional Ken Burns effect.
+ */
+export interface ImageLayer extends BaseLayer {
+  type: 'image';
+  content: {
+    /** Path to image file (relative to article media dir) */
+    src: string;
+    /** Alt text for accessibility */
+    alt: string;
+    /** How to fit image in bounds */
+    fit?: 'cover' | 'contain' | 'fill';
+    /** Photo credit / artist name */
+    credit?: string;
+    /** License identifier (e.g., 'CC BY-SA 4.0') */
+    license?: string;
+  };
+}
+
+/**
+ * Text layer - displays text with styling.
+ */
+export interface TextLayer extends BaseLayer {
+  type: 'text';
+  content: {
+    /** Text to display (supports \n for line breaks) */
+    text: string;
+    /** Text styling */
+    style: TextStyle;
+  };
+}
+
+/**
+ * Shape layer - simple geometric shapes for visual accents.
+ */
+export interface ShapeLayer extends BaseLayer {
+  type: 'shape';
+  content: {
+    /** Shape type */
+    shape: 'rect' | 'circle' | 'line';
+    /** Fill color (CSS color or 'none') */
+    fill?: string;
+    /** Stroke color */
+    stroke?: string;
+    /** Stroke width in pixels */
+    strokeWidth?: number;
+    /** Corner radius for rect */
+    borderRadius?: number;
+  };
+}
+
+/**
+ * Map layer - displays a geographic map with optional markers.
+ *
+ * Maps are rendered as composite tile images from free tile providers.
+ * Supported styles use open-source/free tiles requiring attribution.
+ */
+export interface MapLayer extends BaseLayer {
+  type: 'map';
+  content: {
+    /** Center coordinates for the map */
+    center: {
+      lat: number;
+      lng: number;
+    };
+    /** Zoom level (0-18, typically 8-14 for doc blocks) */
+    zoom: number;
+    /** Map tile style */
+    style: MapTileStyle;
+    /** Optional markers to display on the map */
+    markers?: MapMarker[];
+    /** Pre-rendered static image path (for video export reliability) */
+    staticSrc?: string;
+    /** Show attribution text (default: true) */
+    showAttribution?: boolean;
+  };
+}
+
+/**
+ * Video layer - displays a short video clip, always muted (narration provides audio).
+ *
+ * Rendered via an HTML5 <video> element inside <foreignObject>, similar to how
+ * ImageLayer uses <img> for Ken Burns effects. clipStart/clipEnd define the window
+ * within the source video to play. During Playwright frame capture (seekTo mode),
+ * the video is seeked programmatically rather than playing in real time.
+ */
+export interface VideoLayer extends BaseLayer {
+  type: 'video';
+  content: {
+    /** Path to video file (relative to article media dir) */
+    src: string;
+    /** Path to poster frame (shown before video loads / during seek) */
+    posterSrc?: string;
+    /** Alt text for accessibility */
+    alt: string;
+    /** How to fit video in bounds */
+    fit?: 'cover' | 'contain' | 'fill';
+    /** Start time within the source video (seconds) */
+    clipStart: number;
+    /** End time within the source video (seconds) */
+    clipEnd: number;
+    /** Total source video duration (for validation) */
+    sourceDuration?: number;
+    /** Video credit / artist name */
+    credit?: string;
+    /** License identifier (e.g., 'CC BY-SA 4.0') */
+    license?: string;
+  };
+}
+
+/**
+ * Available map tile styles from free/open-source providers.
+ */
+export type MapTileStyle =
+  | 'terrain' // OpenTopoMap - topographic/terrain (default)
+  | 'satellite' // ESRI World Imagery
+  | 'road' // OpenStreetMap standard
+  | 'toner' // Stadia Toner (high contrast B&W)
+  | 'watercolor'; // Stadia Watercolor (artistic)
+
+/**
+ * A marker to display on the map.
+ */
+export interface MapMarker {
+  /** Marker latitude */
+  lat: number;
+  /** Marker longitude */
+  lng: number;
+  /** Optional label text */
+  label?: string;
+  /** Marker color (CSS color, default: #ef4444) */
+  color?: string;
+  /** Marker icon type */
+  icon?: 'pin' | 'circle' | 'star';
+}
+
+// ============================================
+// Position & Styling
+// ============================================
+
+/**
+ * Position and dimensions for a layer.
+ * Values can be pixels (number) or percentages (string like "50%").
+ */
+export interface Position {
+  /** X position (pixels or percentage) */
+  x: number | string;
+  /** Y position (pixels or percentage) */
+  y: number | string;
+  /** Width (pixels or percentage) */
+  width?: number | string;
+  /** Height (pixels or percentage) */
+  height?: number | string;
+  /** Anchor point for positioning */
+  anchor?: 'center' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+}
+
+/**
+ * Text styling options.
+ */
+export interface TextStyle {
+  /** Font size in pixels */
+  fontSize: number;
+  /** Font family (defaults to system sans-serif) */
+  fontFamily?: string;
+  /** Font weight */
+  fontWeight?: 'normal' | 'bold';
+  /** Text color (CSS color) */
+  color: string;
+  /** Text alignment */
+  textAlign?: 'left' | 'center' | 'right';
+  /** Line height multiplier */
+  lineHeight?: number;
+  /** Add drop shadow for readability over images */
+  shadow?: boolean;
+  /** Background color for text box */
+  background?: string;
+  /** Padding around text (pixels) */
+  padding?: number;
+  /** Maximum number of lines before truncation (adds "..." to last line) */
+  maxLines?: number;
+}
+
+// ============================================
+// Animation & Transitions
+// ============================================
+
+/**
+ * Animation to apply to a layer.
+ */
+export interface Animation {
+  /** Animation type */
+  type: AnimationType;
+  /** Duration in seconds (defaults to layer's block duration) */
+  duration?: number;
+  /** Delay before animation starts (seconds) */
+  delay?: number;
+  /** CSS easing function */
+  easing?: string;
+  /** For Ken Burns: zoom direction */
+  direction?: 'in' | 'out';
+  /** For pan animations: pan direction */
+  panDirection?: 'left' | 'right' | 'up' | 'down';
+}
+
+/**
+ * Available animation types.
+ */
+export type AnimationType =
+  | 'none'
+  | 'fadeIn'
+  | 'fadeOut'
+  | 'slowZoom' // Slow zoom with optional pan
+  | 'zoomIn'
+  | 'zoomOut'
+  | 'panLeft'
+  | 'panRight'
+  | 'typewriter'; // Text appears letter by letter
+
+/**
+ * Transition between blocks.
+ */
+export interface Transition {
+  /** Transition type */
+  type: TransitionType;
+  /** Duration in seconds */
+  duration: number;
+}
+
+export type TransitionType =
+  | 'cut' // Instant switch
+  | 'fade' // Cross-fade
+  | 'dissolve' // Soft dissolve
+  | 'slideLeft' // New block enters from right
+  | 'slideRight'; // New block enters from left
+
+// ============================================
+// Audio Configuration
+// ============================================
+
+/**
+ * Audio track configuration.
+ * Articles have multiple MP3 segments (intro + sections).
+ */
+export interface AudioTrack {
+  /** Audio segments in playback order */
+  segments: AudioSegment[];
+}
+
+// ============================================
+// Captions
+// ============================================
+
+/**
+ * A single caption phrase to display during playback.
+ */
+export interface CaptionPhrase {
+  /** The text to display */
+  text: string;
+  /** Start time in seconds (relative to doc start) */
+  startTime: number;
+  /** End time in seconds */
+  endTime: number;
+  /** Which audio segment this caption belongs to (0-indexed) */
+  audioSegment: number;
+}
+
+/**
+ * Caption track for a doc.
+ */
+export interface CaptionTrack {
+  /** Caption phrases in chronological order */
+  phrases: CaptionPhrase[];
+  /** When the captions were generated */
+  generatedAt: string;
+  /** Algorithm version for regeneration detection */
+  version: number;
+}
+
+/**
+ * A single audio segment (one MP3 file).
+ */
+export interface AudioSegment {
+  /** Path to MP3 file (relative to article media dir) */
+  src: string;
+  /** Segment name (e.g., "intro", "history") */
+  name: string;
+  /** Duration in seconds */
+  duration: number;
+  /** Start time in overall timeline (calculated) */
+  startTime: number;
+}
+
+// ============================================
+// Helper Functions
+// ============================================
+
+/**
+ * Calculate total duration from audio segments.
+ */
+export function calculateDuration(audio: AudioTrack): number {
+  return audio.segments.reduce((sum, seg) => sum + seg.duration, 0);
+}
+
+/**
+ * Find which audio segment is playing at a given time.
+ */
+export function getSegmentAtTime(audio: AudioTrack, time: number): number {
+  let elapsed = 0;
+  for (let i = 0; i < audio.segments.length; i++) {
+    elapsed += audio.segments[i].duration;
+    if (time < elapsed) return i;
+  }
+  return audio.segments.length - 1;
+}
+
+/**
+ * Find which block should be visible at a given time.
+ */
+export function getBlockAtTime(blocks: Block[], time: number): Block | null {
+  for (let i = blocks.length - 1; i >= 0; i--) {
+    const block = blocks[i];
+    if (time >= block.startTime && time < block.startTime + block.duration) {
+      return block;
+    }
+  }
+  return blocks[0] || null;
+}
+
+/**
+ * Find the caption phrase that should be displayed at a given time.
+ */
+export function getCaptionAtTime(
+  captions: CaptionTrack | undefined,
+  time: number,
+): CaptionPhrase | null {
+  if (!captions || !captions.phrases.length) return null;
+
+  for (const phrase of captions.phrases) {
+    if (time >= phrase.startTime && time < phrase.endTime) {
+      return phrase;
+    }
+  }
+  return null;
+}
+
+/**
+ * Validate a Doc for completeness.
+ */
+export function validateDoc(script: Doc): string[] {
+  const errors: string[] = [];
+
+  if (!script.articleId) {
+    errors.push('Missing articleId');
+  }
+
+  if (!script.blocks || script.blocks.length === 0) {
+    errors.push('No blocks defined');
+  }
+
+  if (!script.audio || !script.audio.segments || script.audio.segments.length === 0) {
+    errors.push('No audio segments defined');
+  }
+
+  // Check for gaps in block coverage
+  const totalDuration = script.duration;
+  let covered = 0;
+  for (const block of script.blocks) {
+    if (block.startTime > covered + 0.1) {
+      errors.push(`Gap in blocks: ${covered}s to ${block.startTime}s`);
+    }
+    covered = Math.max(covered, block.startTime + block.duration);
+  }
+
+  if (covered < totalDuration - 0.1) {
+    errors.push(`Blocks end at ${covered}s but audio is ${totalDuration}s`);
+  }
+
+  return errors;
+}