@bendyline/squisq 2.1.0 → 2.3.0

package/src/schemas/BlockTemplates.ts

@@ -1,1046 +0,0 @@
-/**
- * Block Templates Schema
- *
- * Defines a template system for AI-generated doc blocks. Instead of
- * specifying low-level layers, positions, and animations, AI can use
- * high-level templates like "title" or "statHighlight" with simple
- * content parameters.
- *
- * Templates are expanded into full Block structures at render time,
- * ensuring consistent styling and reducing AI generation errors.
- *
- * Template Types:
- * - title: Doc intro with title + subtitle
- * - sectionHeader: Colored section divider
- * - statHighlight: Big number/stat with description
- * - quote: Large centered quote
- * - factCard: Key fact with explanation
- * - twoColumn: Side-by-side comparison
- * - dateEvent: Timeline-style date + description
- * - imageWithCaption: Image with text overlay
- */
-
-import type { Layer, Block, Transition, MapTileStyle, MapMarker, MarkerStyle } from './Doc.js';
-import type { ViewportConfig, ViewportOrientation } from './Viewport.js';
-import type { LayoutHints } from './LayoutStrategy.js';
-import type { Theme } from './Theme.js';
-import { VIEWPORT_PRESETS, getViewportOrientation, calculateFontScale } from './Viewport.js';
-import { getLayoutHints, scaledFontSize as scaleFontSize } from './LayoutStrategy.js';
-
-/**
- * Name of a color scheme defined in the active theme's `colorSchemes` map.
- * Templates reference schemes by name (e.g. 'blue', 'green') and the theme
- * resolves them to actual colors at render time via `resolveColorScheme()`.
- */
-export type ColorScheme = string;
-
-/**
- * Default font family for doc text.
- * 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 = 'system-ui, -apple-system, "Segoe UI", Roboto, sans-serif';
-
-/**
- * Default font family for titles.
- */
-export const DEFAULT_TITLE_FONT = 'Georgia, "Times New Roman", serif';
-
-// ============================================
-// Accent Image System
-// ============================================
-
-/**
- * Position options for accent images on text-based blocks.
- * Accents are tasteful image additions that complement rather than overwhelm text.
- */
-export type AccentPosition =
-  | 'left-strip' // Vertical strip on left (25-30% width), text shifts right
-  | 'right-strip' // Vertical strip on right (25-30% width), text shifts left
-  | 'bottom-strip' // Horizontal strip at bottom (25-30% height), text shifts up
-  | 'corner-inset'; // Small inset image in corner with vignette edge
-
-/**
- * Accent image configuration for text-based blocks.
- * When present, the template adjusts layout to accommodate the image tastefully.
- */
-export interface AccentImage {
-  /** Path to image file (relative to article media dir) */
-  src: string;
-  /** Alt text for accessibility */
-  alt: string;
-  /** Where to position the accent image */
-  position: AccentPosition;
-  /** Ambient motion effect (subtle Ken Burns) */
-  ambientMotion?: 'zoomIn' | 'zoomOut' | 'panLeft' | 'panRight';
-  /** Photo credit / artist name */
-  credit?: string;
-  /** License identifier (e.g., 'CC BY-SA 4.0') */
-  license?: string;
-}
-
-// ============================================
-// Template Input Types
-// ============================================
-
-/**
- * Base properties shared by all template blocks.
- */
-interface BaseTemplateBlock {
-  /** Unique block ID */
-  id: string;
-  /** Block duration in seconds */
-  duration: number;
-  /** Which audio segment this block belongs to */
-  audioSegment: number;
-  /** Entry transition */
-  transition?: Transition;
-  /** Show doc's bottom layers (default: true) */
-  useBottomLayer?: boolean;
-  /** Show doc's top layers (default: true) */
-  useTopLayer?: boolean;
-  /**
-   * Start time within the audio segment when this content is spoken.
-   * Used to sync the block appearance with the narration.
-   * If not provided, blocks are distributed evenly across the segment.
-   */
-  sourceStartTime?: number;
-  /**
-   * Duration of the spoken content this block represents.
-   * Used with sourceStartTime to precisely position the block.
-   */
-  sourceDuration?: number;
-  /**
-   * Transform provenance: the id of the source Block this template block
-   * was derived from. Lets narration timing (and any per-source styling)
-   * be remapped onto transformed/summarized docs.
-   */
-  sourceBlockId?: string;
-  /** All source block ids when the block summarizes more than one. */
-  sourceBlockIds?: string[];
-  /**
-   * Char offset of the extraction inside the source block's plain text.
-   * Provenance only — NOT a time (see sourceStartTime for seconds).
-   */
-  sourceCharOffset?: number;
-  /**
-   * Per-block override for the theme's photographic image grade
-   * (`theme.style.imageTreatment`). `'none'` opts this block's imagery out;
-   * a treatment type forces that grade regardless of the theme.
-   */
-  imageTreatment?: 'none' | 'mono' | 'duotone' | 'warm' | 'cool';
-}
-
-/**
- * Title block - doc intro with large title and subtitle.
- */
-export interface TitleBlockInput extends BaseTemplateBlock {
-  template: 'title';
-  /** Main title text */
-  title: string;
-  /** Subtitle or tagline (supports \n for line breaks) */
-  subtitle?: string;
-  /** Background color (defaults to theme primary) */
-  backgroundColor?: string;
-}
-
-/**
- * Section header - section title card with optional background image.
- * Displays the section title prominently, optionally over an image.
- */
-export interface SectionHeaderInput extends BaseTemplateBlock {
-  template: 'sectionHeader';
-  /** Section title */
-  title: string;
-  /** Color scheme for the section (used for fallback background) */
-  colorScheme?: ColorScheme;
-  /** Optional background image path */
-  imageSrc?: string;
-  /** Alt text for background image */
-  imageAlt?: string;
-  /** Ambient motion for background image */
-  ambientMotion?: 'zoomIn' | 'zoomOut' | 'panLeft' | 'panRight';
-}
-
-/**
- * Stat highlight - big number with description and optional detail.
- */
-export interface StatHighlightInput extends BaseTemplateBlock {
-  template: 'statHighlight';
-  /** The statistic (e.g., "89%", "2x", "7 miles") */
-  stat: string;
-  /** Description of what the stat means */
-  description: string;
-  /** Additional detail or context */
-  detail?: string;
-  /** Color scheme for the stat */
-  colorScheme?: ColorScheme;
-  /** Optional accent image to complement the text */
-  accentImage?: AccentImage;
-}
-
-/**
- * Quote block - large centered quote text.
- */
-export interface QuoteBlockInput extends BaseTemplateBlock {
-  template: 'quote';
-  /** The quote text (supports \n for line breaks) */
-  quote: string;
-  /** Attribution (author, source) */
-  attribution?: string;
-  /** Optional accent image to complement the text */
-  accentImage?: AccentImage;
-}
-
-/**
- * Fact card - key fact with explanation.
- */
-export interface FactCardInput extends BaseTemplateBlock {
-  template: 'factCard';
-  /** The main fact or statement */
-  fact: string;
-  /** Explanation or context */
-  explanation: string;
-  /** Optional source citation */
-  source?: string;
-  /** Optional accent image to complement the text */
-  accentImage?: AccentImage;
-}
-
-/**
- * Two column - side-by-side comparison.
- */
-export interface TwoColumnInput extends BaseTemplateBlock {
-  template: 'twoColumn';
-  /** Left column content */
-  left: {
-    label: string;
-    sublabel?: string;
-  };
-  /** Right column content */
-  right: {
-    label: string;
-    sublabel?: string;
-  };
-  /** Optional header above columns */
-  header?: string;
-  /** Color schemes for left and right */
-  leftColor?: ColorScheme;
-  rightColor?: ColorScheme;
-}
-
-/**
- * Date event - timeline-style date with description.
- */
-export interface DateEventInput extends BaseTemplateBlock {
-  template: 'dateEvent';
-  /** The date (e.g., "July 14, 1974") */
-  date: string;
-  /** Description of what happened (supports \n) */
-  description: string;
-  /** Optional footer text */
-  footer?: string;
-  /** Mood: 'neutral', 'somber', 'celebratory' */
-  mood?: 'neutral' | 'somber' | 'celebratory';
-  /** Optional accent image to complement the text */
-  accentImage?: AccentImage;
-}
-
-/**
- * Image with caption - background image with text overlay.
- */
-export interface ImageWithCaptionInput extends BaseTemplateBlock {
-  template: 'imageWithCaption';
-  /** Path to image file */
-  imageSrc: string;
-  /** Alt text for accessibility */
-  imageAlt: string;
-  /** Caption text */
-  caption?: string;
-  /** Caption position */
-  captionPosition?: 'bottom' | 'top' | 'center';
-  /** Ambient motion effect: slow zoom or pan for visual interest */
-  ambientMotion?: 'zoomIn' | 'zoomOut' | 'panLeft' | 'panRight';
-  /** When true, style caption as a title (larger, centered, prominent) */
-  isTitle?: boolean;
-  /** Optional subtitle shown below the title (only when isTitle is true) */
-  subtitle?: string;
-  /** Photo credit / artist name */
-  imageCredit?: string;
-  /** License identifier (e.g., 'CC BY-SA 4.0') */
-  imageLicense?: string;
-}
-
-/**
- * Shared fields for left/right feature blocks. A "feature" pairs an
- * image on one side of the block with a title and body paragraph on
- * the other — a common editorial layout for product highlights,
- * profile callouts, or section intros.
- */
-interface FeatureInputBase extends BaseTemplateBlock {
-  /** Path to the feature image. */
-  imageSrc: string;
-  /** Alt text for accessibility. */
-  imageAlt?: string;
-  /**
-   * Explicit display width of the image, in pixels (typically pulled
-   * from a `<img width>` attribute when the WYSIWYG editor resized it).
-   * When set, the renderer treats the image as a sized asset and
-   * centers it inside its half with padding instead of stretching it
-   * to fill the cell.
-   */
-  imageWidth?: number;
-  /** Explicit display height of the image, in pixels. */
-  imageHeight?: number;
-  /** Heading / title text shown next to the image. */
-  title?: string;
-  /** Body text shown below the title. */
-  body?: string;
-}
-
-/**
- * Left feature — image on the left, title + body stacked on the right.
- */
-export interface LeftFeatureInput extends FeatureInputBase {
-  template: 'leftFeature';
-}
-
-/**
- * Right feature — image on the right, title + body stacked on the left.
- */
-export interface RightFeatureInput extends FeatureInputBase {
-  template: 'rightFeature';
-}
-
-/**
- * Map block - geographic map showing article location.
- *
- * Displays a map centered on given coordinates with optional title,
- * caption, and markers. Great for establishing geographic context.
- * See docs/MAP_TILES.md for available tile styles and attribution.
- */
-export interface MapBlockInput extends BaseTemplateBlock {
-  template: 'map';
-  /** Map center coordinates */
-  center: {
-    lat: number;
-    lng: number;
-  };
-  /** Zoom level (4-16, typically 8-12 for regional context) */
-  zoom: number;
-  /** Map tile style (default: 'terrain') */
-  mapStyle?: MapTileStyle;
-  /** Optional title overlay at top */
-  title?: string;
-  /** Optional caption at bottom */
-  caption?: string;
-  /** Optional markers to show on map */
-  markers?: MapMarker[];
-  /** Ambient motion effect: slow zoom or pan for visual interest */
-  ambientMotion?: 'zoomIn' | 'zoomOut' | 'panLeft' | 'panRight';
-  /** Pre-rendered static image path (set by prerender-maps command) */
-  staticSrc?: string;
-}
-
-/**
- * Full-bleed quote - dramatic short text filling the viewport.
- * Like a movie title card. For short, punchy sentences < 60 chars.
- */
-export interface FullBleedQuoteInput extends BaseTemplateBlock {
-  template: 'fullBleedQuote';
-  /** Short dramatic text (< 60 chars recommended) */
-  text: string;
-  /** Color scheme for text tint */
-  colorScheme?: ColorScheme;
-}
-
-/**
- * List block - 3-5 items stacked vertically with subtle numbering.
- * Good for enumerations like "things to see" or "key features".
- */
-export interface ListBlockInput extends BaseTemplateBlock {
-  template: 'list';
-  /** List items (3-5 recommended) */
-  items: string[];
-  /** Optional header above the list */
-  title?: string;
-  /** Color scheme for numbering accents */
-  colorScheme?: ColorScheme;
-  /** Optional accent image */
-  accentImage?: AccentImage;
-}
-
-/**
- * Tree block — renders a hierarchical filesystem-style treeview from an
- * ASCII tree fence (file trees, dependency trees, outlines). The nested
- * `items` arrive via `templateData`, derived from the fence by the pipeline
- * (peer to how `diagram` receives `nodes`/`edges`).
- */
-export interface TreeBlockInput extends BaseTemplateBlock {
-  template: 'tree';
-  /** Nested tree items (usually via `templateData.items`). */
-  items?: TreeTemplateItem[];
-  /** Optional title above the tree. */
-  title?: string;
-  /** Color scheme for folder rows / icons. */
-  colorScheme?: ColorScheme;
-}
-
-/** One node supplied via `templateData.items` (mirrors `TreeLayerItem`). */
-export interface TreeTemplateItem {
-  id: string;
-  label: string;
-  isDir?: boolean;
-  comment?: string;
-  children: TreeTemplateItem[];
-}
-
-/**
- * One point on a timeline track. Event positions are normalized across the
- * whole timeline (0 = left edge, 1 = right edge) so events on separate tracks
- * remain horizontally comparable.
- */
-export interface TimelineTemplateEvent {
-  /** Stable id used by cross-track branch links. */
-  id: string;
-  /** Short label displayed next to the event dot. */
-  label: string;
-  /** Optional longer callout text. */
-  description?: string;
-  /** Normalized horizontal position; renderers clamp values to 0..1. */
-  position: number;
-  /** Preferred callout placement. Defaults to alternating above/below. */
-  side?: 'above' | 'below';
-  /** Description placement when it should sit opposite the event label. */
-  descriptionSide?: 'above' | 'below';
-  /** False renders the point only (useful for dense cadence tracks). */
-  callout?: boolean;
-  /** Dot treatment. Defaults to `filled`. */
-  marker?: 'filled' | 'hollow' | 'diamond';
-}
-
-/** A horizontal timeline lane with zero or more positioned events. */
-export interface TimelineTemplateTrack {
-  id: string;
-  /** Optional label displayed to the left of the track. */
-  label?: string;
-  /** Optional label displayed after the track's terminal arrow. */
-  endLabel?: string;
-  events: TimelineTemplateEvent[];
-}
-
-/**
- * A branch or relationship between two events. Source and target resolve
- * against event ids globally, so links may cross tracks.
- */
-export interface TimelineTemplateLink {
-  source: string;
-  target: string;
-  /** Optional text displayed near the branch path. */
-  label?: string;
-}
-
-/**
- * Timeline block - renders one or more horizontal tracks with event dots,
- * text callouts, and optional branches between events.
- */
-export interface TimelineBlockInput extends BaseTemplateBlock {
-  template: 'timeline';
-  /** Tracks and their events (usually supplied through `templateData`). */
-  tracks?: TimelineTemplateTrack[];
-  /** Optional branch/cross-track links between event ids. */
-  links?: TimelineTemplateLink[];
-  /** Optional title above the timeline. */
-  title?: string;
-  /** Color scheme for tracks, markers, and branch links. */
-  colorScheme?: ColorScheme;
-}
-
-/**
- * Photo grid - 2-4 images in a tiled layout.
- * Used when multiple images are available for visual variety.
- */
-export interface PhotoGridInput extends BaseTemplateBlock {
-  template: 'photoGrid';
-  /** Images to display (2-4) */
-  images: { src: string; alt: string; credit?: string; license?: string }[];
-  /** Optional caption below the grid */
-  caption?: string;
-  /** Ambient motion effect for the largest image */
-  ambientMotion?: 'zoomIn' | 'zoomOut' | 'panLeft' | 'panRight';
-}
-
-/**
- * Definition card - dictionary-style term with definition.
- * Large term at top, definition below, optional origin note.
- */
-export interface DefinitionCardInput extends BaseTemplateBlock {
-  template: 'definitionCard';
-  /** The term being defined */
-  term: string;
-  /** The definition text */
-  definition: string;
-  /** Optional etymology or origin note */
-  origin?: string;
-  /** Color scheme for term accent */
-  colorScheme?: ColorScheme;
-  /** Optional accent image */
-  accentImage?: AccentImage;
-}
-
-/**
- * Comparison bar - two horizontal bars showing relative numeric values.
- * Good for side-by-side numeric comparisons with visual weight.
- */
-export interface ComparisonBarInput extends BaseTemplateBlock {
-  template: 'comparisonBar';
-  /** Left bar label */
-  leftLabel: string;
-  /** Left bar numeric value */
-  leftValue: number;
-  /** Right bar label */
-  rightLabel: string;
-  /** Right bar numeric value */
-  rightValue: number;
-  /** Unit label (e.g., "km", "people") */
-  unit?: string;
-  /** Color scheme */
-  colorScheme?: ColorScheme;
-}
-
-/**
- * Pull quote - quote text over a full-bleed background image with dark overlay.
- * Cinematic alternative to quoteBlock when a high-quality image is available.
- */
-export interface PullQuoteInput extends BaseTemplateBlock {
-  template: 'pullQuote';
-  /** Quote text */
-  text: string;
-  /** Optional attribution */
-  attribution?: string;
-  /** Background image (fills entire viewport) */
-  backgroundImage: { src: string; alt: string; credit?: string; license?: string };
-  /** Ambient motion for background image */
-  ambientMotion?: 'zoomIn' | 'zoomOut' | 'panLeft' | 'panRight';
-}
-
-/**
- * Video with caption - background video clip with text overlay.
- * Plays a short clip from a source video, always muted (narration is the audio track).
- * Mirrors ImageWithCaptionInput but with video-specific fields.
- */
-export interface VideoWithCaptionInput extends BaseTemplateBlock {
-  template: 'videoWithCaption';
-  /** Path to video file */
-  videoSrc: string;
-  /** Path to poster frame (shown before video loads) */
-  posterSrc?: string;
-  /** Alt text for accessibility */
-  videoAlt: string;
-  /** Start time within source video (seconds) */
-  clipStart: number;
-  /** End time within source video (seconds) */
-  clipEnd: number;
-  /** Source video total duration (for validation) */
-  sourceDuration?: number;
-  /** Caption text overlay */
-  caption?: string;
-  /** Caption position */
-  captionPosition?: 'bottom' | 'top' | 'center';
-  /** Video credit / artist name */
-  videoCredit?: string;
-  /** License identifier */
-  videoLicense?: string;
-}
-
-/**
- * Video pull quote - quote text over a video clip background with dark overlay.
- * Cinematic alternative to pullQuote when a video clip is available.
- */
-export interface VideoPullQuoteInput extends BaseTemplateBlock {
-  template: 'videoPullQuote';
-  /** Quote text */
-  text: string;
-  /** Optional attribution */
-  attribution?: string;
-  /** Background video clip */
-  backgroundVideo: {
-    src: string;
-    posterSrc?: string;
-    alt: string;
-    clipStart: number;
-    clipEnd: number;
-    credit?: string;
-    license?: string;
-  };
-}
-
-/**
- * One diagram node supplied via `templateData.nodes` (canvas units, the
- * same coordinate space as `Block.x`/`Block.y`). This is the data-driven
- * alternative to child headings — used when a diagram is derived from an
- * ASCII-art fence.
- */
-export interface DiagramTemplateNode {
-  id: string;
-  /** Display label; may contain `\n` for multi-line labels. */
-  label: string;
-  x: number;
-  y: number;
-  /** Per-node width override in canvas units (defaults to the standard card width). */
-  w?: number;
-  /** Per-node height override in canvas units. */
-  h?: number;
-  /** Id of the node visually containing this one; containers draw behind their children. */
-  container?: string;
-}
-
-/** A position along one side of a diagram node, normalized from 0 to 1. */
-export interface DiagramEdgeAnchor {
-  side: 'top' | 'right' | 'bottom' | 'left';
-  /** Left→right on horizontal sides; top→bottom on vertical sides. */
-  offset: number;
-}
-
-/** An edge for `DiagramTemplateNode` lists. `directed` defaults to true. */
-export interface DiagramTemplateEdge {
-  source: string;
-  target: string;
-  /** Edge label rendered at the midpoint. */
-  label?: string;
-  /** False suppresses the end arrowhead (a plain connecting line). */
-  directed?: boolean;
-  /** Optional authored attachment on the source node. */
-  sourceAnchor?: DiagramEdgeAnchor;
-  /** Optional authored attachment on the target node. */
-  targetAnchor?: DiagramEdgeAnchor;
-  /** Per-edge path routing; ASCII-derived edges use orthogonal routing. */
-  routing?: 'straight' | 'orthogonal' | 'curved';
-}
-
-/**
- * Diagram block - renders a node-and-edge diagram.
- *
- * Two data sources, in precedence order:
- * 1. Child headings (`context.children`) — each child is a node positioned
- *    by its `x`/`y` and connected by its `connectsTo` (legacy authored form).
- * 2. `nodes`/`edges` on this input (usually via `templateData`, derived
- *    from an ASCII-art diagram fence in the block body).
- * Per-diagram options on this input control overall appearance.
- */
-export interface DiagramBlockInput extends BaseTemplateBlock {
-  template: 'diagram';
-  /** Optional diagram title displayed above the canvas. */
-  title?: string;
-  /** Color scheme for nodes and edges. */
-  colorScheme?: ColorScheme;
-  /** Node shape style (default: 'rounded'). */
-  nodeShape?: 'rounded' | 'rect' | 'pill';
-  /** Edge routing (default: 'curved'). */
-  edgeStyle?: 'curved' | 'straight' | 'orthogonal';
-  /** Marker at each edge's start (default: 'none'). */
-  startStyle?: MarkerStyle;
-  /** Marker at each edge's end (default: 'arrow'). */
-  endStyle?: MarkerStyle;
-  /** Edge line style (default: 'solid'). */
-  lineStyle?: 'solid' | 'dashed' | 'dotted';
-  /** Data-driven node list; used only when the block has no children. */
-  nodes?: DiagramTemplateNode[];
-  /** Edges for `nodes`. */
-  edges?: DiagramTemplateEdge[];
-}
-
-/**
- * Free-form 2D canvas block (`layout`). Like `drawing`/`diagram`, the
- * `layout` template is a children-driven container: each child heading is
- * one absolutely-positioned layer (`{[text …]}` / `{[rectangle …]}` /
- * `{[image …]}`), read from `context.children`. A text box's content is the
- * child's body markdown. Backed by the `layoutBlock` template.
- *
- * (Legacy documents stored layers as a base64-JSON `layers=` param on the
- * heading; the editor auto-migrates those to child sub-blocks on first edit.)
- */
-export interface RawLayersInput extends BaseTemplateBlock {
-  template: 'layout';
-}
-
-/**
- * Drawing block — renders child headings as free-form shapes on a canvas.
- *
- * Like `diagram`, the drawing template reads its content from the parent
- * block's `children` (passed via `context.children`). Each child heading
- * is a shape: its `{[shape …]}` annotation names the primitive
- * (`rectangle`/`rect`, `circle`, `line`, `arrow`, `path`, `text`) and
- * carries geometry/style as params; its `{#id}` makes it referenceable;
- * its heading text is the shape label and its body text an optional
- * sublabel. Connectors (`line`/`arrow` with `from`/`to`) join shapes by id.
- *
- * Coordinates are author-defined units; the template fits the bounding box
- * of all shapes to the viewport (same scaling as `diagram`), so authors
- * don't have to think in absolute pixels.
- *
- * Legacy drawings authored visually persist their `Layer[]` as a base64
- * `layers="…"` Pandoc param instead of children; the template decodes and
- * returns those directly when no children are present (see `drawingBlock`).
- */
-export interface DrawingBlockInput extends BaseTemplateBlock {
-  template: 'drawing';
-  /** Optional title displayed above the canvas. */
-  title?: string;
-  /** Color scheme for shapes that don't pin their own fill/stroke. */
-  colorScheme?: ColorScheme;
-  /** Default fill for shapes that don't specify one (default: 'none'). */
-  fill?: string;
-  /** Default stroke for shapes that don't specify one (default: theme text). */
-  stroke?: string;
-}
-
-/**
- * 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.
- */
-export type TemplateBlock =
-  | TitleBlockInput
-  | SectionHeaderInput
-  | StatHighlightInput
-  | QuoteBlockInput
-  | FactCardInput
-  | TwoColumnInput
-  | DateEventInput
-  | ImageWithCaptionInput
-  | LeftFeatureInput
-  | RightFeatureInput
-  | MapBlockInput
-  | FullBleedQuoteInput
-  | ListBlockInput
-  | PhotoGridInput
-  | DefinitionCardInput
-  | ComparisonBarInput
-  | PullQuoteInput
-  | VideoWithCaptionInput
-  | VideoPullQuoteInput
-  | DataTableInput
-  | DiagramBlockInput
-  | TreeBlockInput
-  | TimelineBlockInput
-  | DrawingBlockInput
-  | RawLayersInput;
-
-/**
- * A block can be either a raw Block or a TemplateBlock.
- */
-export type DocBlock = Block | TemplateBlock;
-
-/**
- * Check if a block is a template block.
- */
-export function isTemplateBlock(block: DocBlock): block is TemplateBlock {
-  return 'template' in block && typeof block.template === 'string';
-}
-
-// ============================================
-// Template Function Type
-// ============================================
-
-/**
- * Template context passed to template functions.
- * Includes viewport information for multi-aspect ratio support.
- */
-export interface TemplateContext {
-  /** Full theme (colors, typography, style, renderStyle, colorSchemes) */
-  theme: Theme;
-  /** Block index in the doc */
-  blockIndex: number;
-  /** Total number of blocks */
-  totalBlocks: number;
-  /** Target viewport configuration */
-  viewport: ViewportConfig;
-  /** Computed font scale factor for this viewport */
-  fontScale: number;
-  /** Viewport orientation (landscape, portrait, square) */
-  orientation: ViewportOrientation;
-  /** Layout hints for this orientation */
-  layout: LayoutHints;
-  /**
-   * The block's direct children (set by `materializeBlockLayers` when the block has
-   * `children`). Most templates ignore this; aggregate templates like
-   * `diagram` consume it to render each child as part of their output.
-   */
-  children?: Block[];
-  /**
-   * The source block being expanded. Used by user-defined custom
-   * templates so the token resolver can substitute `{title}`,
-   * `{content}`, `{children}`, and `{image:N}` against the block's
-   * data at render time. Built-in templates ignore this and rely on
-   * their typed `input` parameters instead.
-   */
-  block?: Block;
-}
-
-/**
- * Create a template context with viewport-derived values.
- */
-export function createTemplateContext(
-  theme: Theme,
-  blockIndex: number,
-  totalBlocks: number,
-  viewport: ViewportConfig = VIEWPORT_PRESETS.landscape,
-): TemplateContext {
-  const orientation = getViewportOrientation(viewport);
-  // Theme renderStyle may override individual layout hints (e.g. a theme
-  // that wants a lower primaryY across every template).
-  const overrides = theme.renderStyle.layoutOverrides;
-  const baseLayout = getLayoutHints(orientation);
-  return {
-    theme,
-    blockIndex,
-    totalBlocks,
-    viewport,
-    fontScale: calculateFontScale(viewport),
-    orientation,
-    layout: overrides ? { ...baseLayout, ...overrides } : baseLayout,
-  };
-}
-
-/**
- * Calculate a scaled font size for the given context.
- * Use this in templates to ensure text scales appropriately.
- *
- * @param basePx - Base font size in pixels (designed for 1920x1080)
- * @param context - Template context with viewport info
- * @param isTitle - Whether this is title text (larger scale) or body text
- */
-export function scaledFontSize(
-  basePx: number,
-  context: TemplateContext,
-  isTitle: boolean = false,
-): number {
-  return scaleFontSize(basePx, context.viewport, context.orientation, isTitle);
-}
-
-/**
- * Template function signature.
- * Takes template input and returns layers array.
- */
-export type TemplateFunction<T extends TemplateBlock> = (
-  input: T,
-  context: TemplateContext,
-) => Layer[];
-
-/**
- * Registry of all template functions.
- */
-export type TemplateRegistry = {
-  [K in TemplateBlock['template']]: TemplateFunction<Extract<TemplateBlock, { template: K }>>;
-};
-
-// ============================================
-// Persistent Layer System
-// ============================================
-
-/**
- * Configuration for persistent doc-wide layers.
- * Bottom layers render behind all block content, top layers on top.
- */
-export interface PersistentLayerConfig {
-  /** Layers rendered behind all block content */
-  bottomLayers?: PersistentLayer[];
-  /** Layers rendered on top of all block content */
-  topLayers?: PersistentLayer[];
-}
-
-/**
- * A persistent layer - either a template or raw Layer.
- */
-export type PersistentLayer = PersistentLayerTemplate | Layer;
-
-/**
- * Check if a persistent layer is a template.
- */
-export function isPersistentLayerTemplate(
-  layer: PersistentLayer,
-): layer is PersistentLayerTemplate {
-  return 'template' in layer && typeof layer.template === 'string';
-}
-
-/**
- * Template-based persistent layer for easy configuration.
- */
-export interface PersistentLayerTemplate {
-  template: PersistentLayerTemplateType;
-  config: PersistentLayerTemplateConfig;
-}
-
-/**
- * Available persistent layer template types.
- */
-export type PersistentLayerTemplateType =
-  | 'solidBackground' // Solid color fill
-  | 'gradientBackground' // CSS gradient or preset
-  | 'imageBackground' // Blurred/faded hero image
-  | 'patternBackground' // Subtle pattern (dots, grid, diagonal, noise/grain)
-  | 'vignette' // Soft radial edge darkening (top layer)
-  | 'ambientGradient' // Slowly drifting surface gradient (bottom layer)
-  | 'titleCaption' // Article title in corner
-  | 'cornerBranding' // Logo or text badge
-  | 'progressIndicator'; // Bar/dots showing position
-
-/**
- * Union of all persistent layer template configs.
- */
-export type PersistentLayerTemplateConfig =
-  | SolidBackgroundConfig
-  | GradientBackgroundConfig
-  | ImageBackgroundConfig
-  | PatternBackgroundConfig
-  | VignetteConfig
-  | AmbientGradientConfig
-  | TitleCaptionConfig
-  | CornerBrandingConfig
-  | ProgressIndicatorConfig;
-
-// ============================================
-// Background Layer Configs
-// ============================================
-
-/**
- * Solid color background.
- */
-export interface SolidBackgroundConfig {
-  type: 'solidBackground';
-  /** CSS color value */
-  color: string;
-}
-
-/**
- * Gradient background (CSS gradient or preset).
- */
-export interface GradientBackgroundConfig {
-  type: 'gradientBackground';
-  /** Custom CSS gradient string */
-  gradient?: string;
-  /** Preset gradient name */
-  preset?: 'dark-vignette' | 'radial-dark' | 'warm-sunset' | 'cool-blue' | 'earth-tones';
-}
-
-/**
- * Image background (blurred/faded hero image).
- */
-export interface ImageBackgroundConfig {
-  type: 'imageBackground';
-  /** Path to image file */
-  src: string;
-  /** Blur radius in pixels (0-20) */
-  blur?: number;
-  /** Opacity (0-1) */
-  opacity?: number;
-  /** Ambient motion effect */
-  ambientMotion?: 'zoomIn' | 'zoomOut' | 'panLeft' | 'panRight';
-}
-
-/**
- * Pattern background (subtle repeating pattern).
- */
-export interface PatternBackgroundConfig {
-  type: 'patternBackground';
-  /** Pattern type */
-  pattern: 'dots' | 'grid' | 'diagonal' | 'noise';
-  /** Pattern color */
-  color?: string;
-  /** Pattern opacity (0-1) */
-  opacity?: number;
-  /** Pattern scale multiplier */
-  scale?: number;
-}
-
-/**
- * Soft radial vignette (top layer) — transparent center darkening toward
- * the frame edges. The classic film-look framing device.
- */
-export interface VignetteConfig {
-  type: 'vignette';
-  /** Edge darkness 0-1 (default 0.3). */
-  strength?: number;
-  /** Vignette color (default black). */
-  color?: string;
-}
-
-/**
- * Slowly drifting surface gradient (bottom layer). Colors default to the
- * theme's surface family at expansion time.
- */
-export interface AmbientGradientConfig {
-  type: 'ambientGradient';
-  /** Gradient start color. */
-  from?: string;
-  /** Gradient end color. */
-  to?: string;
-  /** Drift loop duration in seconds (default 40). */
-  duration?: number;
-}
-
-// ============================================
-// Overlay Layer Configs
-// ============================================
-
-/**
- * Title caption overlay (article title in corner).
- */
-export interface TitleCaptionConfig {
-  type: 'titleCaption';
-  /** Title text */
-  title: string;
-  /** Subtitle text (e.g., short URL like "qual..la/slug") */
-  subtitle?: string;
-  /** Position on screen */
-  position: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right';
-  /** Font size in pixels (default: 18) */
-  fontSize?: number;
-  /** Show thumbnail alongside title */
-  showThumbnail?: boolean;
-  /** Thumbnail image path */
-  thumbnailSrc?: string;
-}
-
-/**
- * Corner branding overlay (logo or text badge).
- */
-export interface CornerBrandingConfig {
-  type: 'cornerBranding';
-  /** Text content or image path */
-  content: string;
-  /** Position on screen */
-  position: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right';
-  /** Whether content is an image path (vs text) */
-  isImage?: boolean;
-}
-
-/**
- * Progress indicator overlay (bar or dots showing position).
- */
-export interface ProgressIndicatorConfig {
-  type: 'progressIndicator';
-  /** Indicator style */
-  style: 'bar' | 'dots' | 'fraction';
-  /** Position on screen */
-  position: 'bottom' | 'top';
-  /** Indicator color */
-  color?: string;
-}