@bendyline/squisq 2.0.1 → 2.2.0

package/src/schemas/Doc.ts

@@ -1,1052 +0,0 @@
-/**
- * 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.
- */
-
-import type { Transition } from './Transitions.js';
-export type { Transition, TransitionType, TransitionDirection } from './Transitions.js';
-
-// ============================================
-// Core Types
-// ============================================
-
-/**
- * A directed connection from one block to another.
- *
- * Populated from a heading's Pandoc-style `{connectsTo=…}` attribute
- * (e.g. `## Step 1 {#step1 connectsTo=foo:flow,bar}`). Each item is
- * `target` or `target:type`. Used by diagram-style layouts that draw
- * edges between blocks.
- */
-export interface BlockConnection {
-  /** Target block id (matches another block's `id`). */
-  target: string;
-  /** Optional connection type/label (e.g., "flow", "requires"). */
-  type?: string;
-}
-
-/**
- * Configuration for the Start/resting block shown before playback begins.
- */
-export interface StartBlockConfig {
-  /** Hero image path (relative to article media). When omitted, a theme-driven background is used. */
-  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 structural problem detected while converting or validating a document.
- *
- * Diagnostics ride on `Doc.diagnostics` so any consumer — the editor, the
- * CLI `validate` command, or an agent re-parsing its own output — gets the
- * same feedback without watching the console. Conversion never throws for
- * content problems; it degrades gracefully and records a diagnostic.
- */
-export interface DocDiagnostic {
-  /** `error` = the author's intent could not be honored (e.g. unparseable
-   *  data fence); `warning` = something looks wrong but rendering proceeds
-   *  with a fallback (e.g. unknown template name); `info` = nothing is
-   *  broken, but the author may want to know (e.g. a redundant annotation). */
-  severity: 'error' | 'warning' | 'info';
-  /** Stable machine-readable code (e.g. `unknown-template`, `duplicate-id`,
-   *  `unresolved-connection`, `data-fence-parse`, `missing-asset`). */
-  code: string;
-  /** Human-readable description, including a suggestion when one exists. */
-  message: string;
-  /** Id of the block the problem belongs to, when attributable. */
-  blockId?: string;
-  /** 1-based line number in the markdown source, when known. */
-  line?: number;
-}
-
-/**
- * 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>;
-
-  /**
-   * User-defined block templates inlined into this doc.
-   *
-   * Populated from the markdown frontmatter key
-   * `squisq-custom-templates`. The template-expansion pipeline
-   * (`expandDocBlocks` in `doc/templates/index.ts`) merges these into
-   * the registry before walking blocks, so a heading annotated
-   * `{[myhero]}` resolves against a doc-defined template named `myhero`.
-   *
-   * Library templates (stored in localStorage on the editor side) are
-   * NOT auto-loaded here — applying a library template to a block
-   * copies its definition into this list so the doc remains
-   * self-sufficient for SSR and export.
-   */
-  customTemplates?: import('./CustomTemplates.js').CustomTemplateDefinition[];
-
-  /**
-   * User-defined themes inlined into this doc.
-   *
-   * The theme analog of {@link Doc.customTemplates}. Populated from the
-   * markdown frontmatter key `squisq-custom-themes`. Exactly one is active
-   * at a time — selected by id via `squisq-theme` / {@link Doc.themeId},
-   * the doc-level counterpart of a block's `{[name]}` template annotation —
-   * but the payload is a list so a doc can carry a small catalog and stay
-   * self-sufficient for SSR / export. `resolveThemeForDoc(doc, id)` resolves
-   * against this list first (pure, doc-scoped) before built-ins, mirroring
-   * how `buildRegistry` resolves custom templates.
-   */
-  customThemes?: import('./Theme.js').Theme[];
-
-  /**
-   * Structural problems found while building this doc (unknown templates,
-   * unparseable data fences, duplicate ids, unresolved connections, …).
-   * Populated by `markdownToDoc()`; extended by `validateMarkdownDoc()`.
-   * Absent when the document is clean.
-   */
-  diagnostics?: DocDiagnostic[];
-
-  /**
-   * Document-spanning timed media (e.g. a full-length narration MP3/MP4),
-   * authored as a media annotation in the preamble (before the first
-   * heading) with `anchor=document`. Each clip is timed from the document
-   * start and may play across every block. See `resolveMediaSchedule`.
-   */
-  documentMedia?: import('./Media.js').MediaClip[];
-}
-
-/**
- * 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)
- *
- * Four adjacent fields carry template information — do not confuse them:
- * - `template` — the *resolved* template id this block renders with.
- * - `templateOverrides` — raw `{[…]}` inline params (always strings).
- * - `templateData` — structured inputs from a data fence / GFM table
- *   (parsed types, not strings).
- * - `sourceAnnotation.template` — the raw *requested* template name for a
- *   standalone-annotation block (before alias resolution).
- * Merge order at render time: template defaults → `templateData` →
- * `templateOverrides`.
- */
-export interface Block {
-  /** Unique identifier for this block.
-   *  Defaults to a slug derived from the heading text. May be overridden by
-   *  a Pandoc-style `{#custom-id}` attribute on the heading. */
-  id: string;
-
-  /** When this block appears (seconds from start).
-   *  Overridden by a heading attribute `startTime=…` when present. */
-  startTime: number;
-
-  /** How long this block is visible (seconds).
-   *  Overridden by a heading attribute `duration=…` when present. */
-  duration: number;
-
-  /** Which audio segment this block belongs to (0-indexed) */
-  audioSegment: number;
-
-  /**
-   * Transform provenance: the source block id this block was derived
-   * from (see `BaseTemplateBlock.sourceBlockId`). Present on blocks a
-   * transform produced; lets a persisted transformed Doc keep its typed
-   * link back to the source content.
-   */
-  sourceBlockId?: string;
-  /** All source block ids when this block summarizes several. */
-  sourceBlockIds?: string[];
-  /** Char offset of the extraction inside the source block's plain text. */
-  sourceCharOffset?: number;
-
-  /**
-   * Pre-computed visual layers, rendered back-to-front.
-   *
-   * Optional — template-derived blocks typically omit this and compute
-   * layers on demand via `materializeBlockLayers()` 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;
-
-  /** Resolved template id this block renders with (see the quartet note above). */
-  template?: string;
-
-  /**
-   * True when `template` was chosen by content-aware auto-picking
-   * (`markdownToDoc`'s `autoTemplates`) rather than authored. Ephemeral:
-   * `docToMarkdown` does not materialize auto-picked templates as heading
-   * annotations, keeping the markdown round-trip lossless.
-   */
-  autoTemplate?: boolean;
-
-  /**
-   * True when this block was produced from a *standalone* `{[templateName …]}`
-   * annotation paragraph in another block's body (rather than from a heading).
-   * Such blocks have no `sourceHeading`; `docToMarkdown` re-emits their
-   * annotation as a synthesized paragraph before their `contents` so the
-   * markdown round-trips. See `annotationBlocks.ts`.
-   *
-   * Presence-marker: only ever `true` (never `false`). Test with
-   * `block.standaloneAnnotation` presence, not as a boolean toggle.
-   */
-  standaloneAnnotation?: true;
-
-  /**
-   * The annotation a standalone block was built from — the raw (un-resolved)
-   * template name and its params, in author order. Round-tripped by
-   * `docToMarkdown` (via `serializeAnnotation`) and read by validation as the
-   * raw requested template name (symmetric with
-   * `sourceHeading.templateAnnotation`). Present only when
-   * `standaloneAnnotation` is true.
-   */
-  sourceAnnotation?: { template?: string; params?: Record<string, 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) ──
-
-  /**
-   * 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 a heading's `{[templateName key=value]}`
-   * annotation. Only carries template-specific params (e.g. `colorScheme=blue`).
-   * Block-level metadata lives in `x` / `y` / `connectsTo` / `metadata` and is
-   * sourced from the Pandoc-style `{#id .class key=value}` attribute block instead.
-   */
-  templateOverrides?: Record<string, string>;
-
-  /**
-   * Structured template inputs sourced from the block's body content:
-   * a ```json data / ```yaml data fence under the heading, or — for the
-   * `dataTable` template — the first GFM table in the section. Unlike
-   * `templateOverrides` (always strings), values here keep their parsed
-   * types (arrays, numbers, nested objects). Merge order at render time:
-   * template defaults → `templateData` → `templateOverrides`.
-   */
-  templateData?: Record<string, unknown>;
-
-  // ── Block-level metadata from Pandoc-style `{#id .class key=value}` ──
-
-  /**
-   * X coordinate for diagram-style positioning (in author-defined units).
-   * Sourced from a heading attribute `x=…`.
-   */
-  x?: number;
-
-  /**
-   * Y coordinate for diagram-style positioning (in author-defined units).
-   * Sourced from a heading attribute `y=…`.
-   */
-  y?: number;
-
-  /**
-   * Outgoing connections to other blocks, by id. Sourced from a heading
-   * attribute `connectsTo=target1,target2:type,target3`.
-   */
-  connectsTo?: BlockConnection[];
-
-  /**
-   * CSS-style class tokens from a heading's Pandoc attribute (e.g. `{.important .v2}`).
-   * Parsed and stored; downstream consumers may use them for styling or filtering.
-   */
-  classes?: string[];
-
-  /**
-   * Free-form metadata for heading attribute keys outside the typed registry
-   * (anything that isn't `x` / `y` / `connectsTo` / `startTime` / `duration`).
-   * Values are raw strings exactly as authored.
-   */
-  metadata?: Record<string, string>;
-
-  /**
-   * Timed media clips attached to this block, authored as body-level
-   * `{[audio …]}` / `{[video …]}` annotations. Each clip is timed relative
-   * to this block's `startTime` (via `startAt`) and optionally spills past
-   * the block's end. See `MediaClip` / `resolveMediaSchedule`.
-   */
-  media?: import('./Media.js').MediaClip[];
-}
-
-// ============================================
-// Layer Types
-// ============================================
-
-/**
- * A visual element within a block.
- * Layers are composited back-to-front (first layer is background).
- */
-export type Layer =
-  | ImageLayer
-  | TextLayer
-  | ShapeLayer
-  | PathLayer
-  | MapLayer
-  | VideoLayer
-  | TableLayer
-  | TreeLayer;
-
-interface BaseLayer {
-  /** Unique identifier for this layer */
-  id: string;
-
-  /** Position and size */
-  position: Position;
-
-  /** Animation to apply */
-  animation?: Animation;
-}
-
-/**
- * Photographic treatment applied to an image layer — a theme-level "grade"
- * so the same photo looks native in every theme. Rendered as CSS filter
- * functions, which behave identically in the browser player and headless
- * frame capture (video/still export).
- */
-export interface ImageTreatment {
-  /**
-   * mono: desaturate toward archival black & white.
-   * duotone: single-hue tint (hue taken from `color`).
-   * warm / cool: gentle temperature grade.
-   */
-  type: 'none' | 'mono' | 'duotone' | 'warm' | 'cool';
-  /** Blend strength 0..1. Default 0.6. */
-  strength?: number;
-  /** Duotone tint color (themes default this to their primary). */
-  color?: string;
-}
-
-/**
- * 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;
-    /** Theme-derived photographic grade (see ImageTreatment). */
-    treatment?: ImageTreatment;
-    /** Gaussian blur radius in px (background/atmosphere imagery). */
-    blur?: number;
-  };
-}
-
-/**
- * Text layer - displays text with styling.
- */
-export interface TextLayer extends BaseLayer {
-  type: 'text';
-  content: {
-    /**
-     * Plain text (supports \n for line breaks). Source of truth for plain
-     * consumers — PDF/markdown export, search, accessibility — and the SVG
-     * `<text>` fallback. When `html` is set, this is its plain-text
-     * projection and must be kept in sync.
-     */
-    text: string;
-    /**
-     * Optional sanitized **inline** HTML for rich formatting (bold/italic/
-     * links, and — for layout textboxes — headings/lists). When present the
-     * renderer draws it via `<foreignObject>` instead of SVG `<text>`. Treated
-     * as untrusted and re-sanitized at render time. See `RichTextLayer` in
-     * `@bendyline/squisq-react`.
-     */
-    html?: string;
-    /** Text styling */
-    style: TextStyle;
-  };
-}
-
-/**
- * A two-stop linear gradient fill, shared by shape/path fills and text
- * backgrounds. When present it overrides the solid `fill` color.
- *
- * `angle` is in degrees: 0 = top→bottom, 90 = left→right, increasing
- * clockwise. Defaults to 0. Rendered as an SVG `<linearGradient>` in
- * objectBoundingBox units so it scales with the layer's box.
- */
-export interface LinearGradient {
-  from: string;
-  to: string;
-  angle?: number;
-}
-
-/** Border line style, mapped to an SVG stroke-dasharray by the renderer. */
-export type BorderStyle = 'solid' | 'dashed' | 'dotted';
-
-/**
- * Shape layer - simple geometric shapes for visual accents.
- */
-/**
- * Repeating SVG pattern fill for a shape (dots, grid, diagonal lines).
- * Rendered as a native `<pattern>` def — fully vector and export-safe.
- */
-export interface ShapePattern {
-  kind: 'dots' | 'grid' | 'diagonal';
-  /** Pattern ink color. */
-  color: string;
-  /** Tile size in px (default 24). */
-  size?: number;
-  /** Pattern opacity 0–1 (default 1; tint via a translucent color or this). */
-  opacity?: number;
-}
-
-/**
- * Procedural filter applied to a shape. `noise` renders static film grain
- * via SVG feTurbulence — deliberately not animated so frame capture and
- * the live player agree.
- */
-export interface ShapeFilter {
-  type: 'noise';
-  /** feTurbulence base frequency (default 0.8 — fine grain). */
-  baseFrequency?: number;
-  /** Grain opacity 0–1 (default 0.05). */
-  opacity?: number;
-}
-
-export interface ShapeLayer extends BaseLayer {
-  type: 'shape';
-  content: {
-    /** Shape type */
-    shape: 'rect' | 'circle' | 'line';
-    /** Fill color (CSS color or 'none') */
-    fill?: string;
-    /** Fill opacity 0–1 (applies to solid and gradient fills). */
-    fillOpacity?: number;
-    /** Gradient fill; overrides `fill` when set. */
-    gradient?: LinearGradient;
-    /** Repeating pattern fill; overrides `fill`/`gradient` when set. */
-    pattern?: ShapePattern;
-    /** Procedural filter (film grain). */
-    filter?: ShapeFilter;
-    /** Stroke color */
-    stroke?: string;
-    /** Stroke width in pixels */
-    strokeWidth?: number;
-    /** Border line style (solid/dashed/dotted). Default solid. */
-    borderStyle?: BorderStyle;
-    /** Corner radius for rect */
-    borderRadius?: number;
-  };
-}
-
-/**
- * End-of-line marker style for a path/connector endpoint.
- * `arrow` is a filled triangle (the classic arrowhead); `open` is a stroked
- * V; `diamond`/`circle`/`square` are filled glyphs; `none` draws nothing.
- */
-export type MarkerStyle = 'none' | 'arrow' | 'open' | 'diamond' | 'circle' | 'square';
-
-/**
- * Path layer - renders an SVG `<path>` for arbitrary curves, connectors,
- * arrows, or filled regions. Used by the diagram template for edges
- * between nodes, the drawing template for non-rect/circle/line shapes, and
- * available to any template that needs a custom geometry.
- *
- * The `position` field carries the layer's bounding box (so animations
- * and clipping work the same as for other layers), but the actual
- * geometry is encoded in the `d` attribute using absolute SVG path
- * coordinates relative to the block viewport.
- */
-export interface PathLayer extends BaseLayer {
-  type: 'path';
-  content: {
-    /** SVG path `d` attribute (e.g. "M 10 10 L 90 90"). Absolute viewBox coords. */
-    d: string;
-    /**
-     * Named shape kind (e.g. `'diamond'`, `'star'`, `'arrow-right'`) for
-     * path layers that represent one of Squisq's standard shapes. When
-     * set, the renderer re-derives `d` from the layer's `position` box
-     * (resolved against the viewport) instead of using the stored `d` —
-     * so the shape moves, resizes, and adapts to any aspect ratio like
-     * the native rect/circle/line layers do. Plain paths (connectors,
-     * freehand) leave this unset and keep their absolute `d`.
-     */
-    shapeKind?: string;
-    /** Stroke color (default: theme text color). */
-    stroke?: string;
-    /** Stroke width in pixels (default: 2). */
-    strokeWidth?: number;
-    /** Optional fill color (default: 'none' — pure connectors). */
-    fill?: string;
-    /** Fill opacity 0–1 (applies to solid and gradient fills). */
-    fillOpacity?: number;
-    /** Gradient fill; overrides `fill` when set. */
-    gradient?: LinearGradient;
-    /**
-     * Border line style (solid/dashed/dotted). A convenience over
-     * `dasharray` for named shapes; when set the renderer derives the
-     * dash pattern from it (scaled by stroke width).
-     */
-    borderStyle?: BorderStyle;
-    /** Optional stroke dash pattern (SVG `stroke-dasharray` syntax). */
-    dasharray?: string;
-    /** Marker at the path start. */
-    startMarker?: MarkerStyle;
-    /** Marker at the path end. */
-    endMarker?: MarkerStyle;
-  };
-}
-
-/**
- * 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;
-    /**
-     * Seconds into the owning block before this video begins playing
-     * (the block-relative `startAt`). Default 0 — plays from block start.
-     */
-    startAt?: number;
-    /**
-     * When true, the video keeps playing past the block's end (the
-     * playback scheduler re-homes it to the player level). Default false.
-     */
-    spillover?: boolean;
-    /** Video credit / artist name */
-    credit?: string;
-    /** License identifier (e.g., 'CC BY-SA 4.0') */
-    license?: string;
-  };
-}
-
-/**
- * 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;
-}
-
-/**
- * One node in a `TreeLayer` — a JSON-serializable hierarchy item (mirrors
- * the treeview codec's `TreeItem`). Rendered as an indented filesystem-style
- * row with a folder/file icon and connector rails.
- */
-export interface TreeLayerItem {
-  id: string;
-  label: string;
-  /** True renders a folder (container) icon; else a file (leaf) icon. */
-  isDir?: boolean;
-  /** Trailing comment shown muted after the label. */
-  comment?: string;
-  children: TreeLayerItem[];
-}
-
-/**
- * A hierarchical treeview rendered as interactive HTML inside a
- * `<foreignObject>` (like `TableLayer`): folder/file icons, connector
- * rails, and collapse chevrons. Interactive (collapse/expand) in the live
- * React player; captured fully-expanded and static in frame/PDF export.
- */
-export interface TreeLayer extends BaseLayer {
-  type: 'tree';
-  content: {
-    items: TreeLayerItem[];
-    style: TreeLayerStyle;
-  };
-}
-
-/** Styling options for a TreeLayer. */
-export interface TreeLayerStyle {
-  /** Leaf (file) row text color. */
-  rowColor: string;
-  /** Container (folder) row text color. */
-  dirColor: string;
-  /** Connector rail / branch color. */
-  connectorColor: string;
-  /** Icon color. */
-  iconColor: string;
-  /** Muted comment color. */
-  commentColor: string;
-  /** Font size in pixels. */
-  fontSize: number;
-  /** Row label font family. */
-  fontFamily?: string;
-  /** Monospace font for the connector rails. */
-  monoFontFamily?: string;
-  /** Indent step per depth level, in pixels. */
-  indentPx: number;
-  /** FontAwesome icon token for containers (default `folder`). */
-  folderIcon?: string;
-  /** FontAwesome icon token for leaves (default `file`). */
-  fileIcon?: 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';
-  /** Font style. Also the inherited baseline for rich `content.html`. */
-  fontStyle?: 'normal' | 'italic';
-  /** Text color (CSS color) */
-  color: string;
-  /** Horizontal text alignment within the layer's position box. */
-  textAlign?: 'left' | 'center' | 'right';
-  /**
-   * Vertical alignment of the text within the layer's position box.
-   * Requires a `position.height` to have an effect. When omitted, the
-   * vertical baseline is derived from `position.anchor` (legacy behavior).
-   */
-  verticalAlign?: 'top' | 'middle' | 'bottom';
-  /** Line height multiplier */
-  lineHeight?: number;
-  /** Add drop shadow for readability over images */
-  shadow?: boolean;
-  /** Background color for text box */
-  background?: string;
-  /** Background opacity 0–1 (applies to solid and gradient backgrounds). */
-  backgroundOpacity?: number;
-  /** Gradient background; overrides `background` when set. */
-  backgroundGradient?: LinearGradient;
-  /** Border (stroke) color for the text box. */
-  borderColor?: string;
-  /** Border width in pixels. A border renders when > 0 and a color is set. */
-  borderWidth?: number;
-  /** Border line style (solid/dashed/dotted). Default solid. */
-  borderStyle?: BorderStyle;
-  /** 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
-
-// ============================================
-// 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 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.
- */
-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;
-  /**
-   * 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[];
-}
-
-/**
- * Caption track for a doc.
- */
-export interface CaptionTrack {
-  /** Caption phrases in chronological order */
-  phrases: CaptionPhrase[];
-  /** When the captions were generated. Optional so that conversion stays
-   *  deterministic — `markdownToDoc()` only sets it when the caller
-   *  supplies a timestamp via `captionsGeneratedAt`. */
-  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;
-}
-
-// ============================================
-// 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
-// ============================================
-
-/**
- * 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;
-}