@bendyline/squisq 0.1.1

package/dist/themeLibrary-DySHPcgj.d.ts

@@ -0,0 +1,1352 @@
+import { M as MarkdownBlockNode, p as MarkdownHeading } from './types-DHiv_Pnm.js';
+
+/**
+ * Viewport Configuration
+ *
+ * Defines viewport dimensions for doc rendering across different aspect ratios.
+ * Templates use this configuration to adapt their layouts appropriately.
+ *
+ * Supported aspect ratios:
+ * - landscape (16:9) - Default, standard video/presentation format
+ * - portrait (9:16) - Vertical video, mobile stories
+ * - square (1:1) - Social media posts
+ * - standard (4:3) - Legacy presentation format
+ */
+/**
+ * Viewport configuration for doc rendering.
+ */
+interface ViewportConfig {
+    /** Canonical width in virtual pixels */
+    width: number;
+    /** Canonical height in virtual pixels */
+    height: number;
+    /** Human-readable name for debugging/display */
+    name: string;
+}
+/**
+ * Standard viewport presets for common aspect ratios.
+ */
+declare const VIEWPORT_PRESETS: {
+    /** 16:9 landscape (default, 1080p) */
+    readonly landscape: {
+        readonly width: 1920;
+        readonly height: 1080;
+        readonly name: "16:9 Landscape";
+    };
+    /** 9:16 portrait (vertical video, stories) */
+    readonly portrait: {
+        readonly width: 1080;
+        readonly height: 1920;
+        readonly name: "9:16 Portrait";
+    };
+    /** 1:1 square (social media) */
+    readonly square: {
+        readonly width: 1080;
+        readonly height: 1080;
+        readonly name: "1:1 Square";
+    };
+    /** 4:3 standard (legacy) */
+    readonly standard: {
+        readonly width: 1440;
+        readonly height: 1080;
+        readonly name: "4:3 Standard";
+    };
+};
+/**
+ * Viewport preset name.
+ */
+type ViewportPreset = keyof typeof VIEWPORT_PRESETS;
+/**
+ * Viewport orientation derived from aspect ratio.
+ */
+type ViewportOrientation = 'landscape' | 'portrait' | 'square';
+/**
+ * Get a viewport configuration from a preset name or return the config if already a ViewportConfig.
+ */
+declare function getViewport(viewport: ViewportPreset | ViewportConfig): ViewportConfig;
+declare function calculateFontScale(viewport: ViewportConfig): number;
+/**
+ * Determine if viewport is landscape, portrait, or square.
+ */
+declare function getViewportOrientation(viewport: ViewportConfig): ViewportOrientation;
+/**
+ * Get aspect ratio as a string (e.g., "16:9", "9:16", "1:1").
+ */
+declare function getAspectRatioString(viewport: ViewportConfig): string;
+
+/**
+ * Layout Strategy
+ *
+ * Provides orientation-specific layout hints for slide templates.
+ * Templates use these hints to position content appropriately for
+ * different aspect ratios (landscape, portrait, square).
+ *
+ * Key adaptations by orientation:
+ * - Portrait: Larger relative text, stacked layouts instead of side-by-side
+ * - Square: Balanced layout with moderate adjustments
+ * - Landscape: Default/reference layout
+ */
+
+/**
+ * Layout hints for template positioning based on orientation.
+ */
+interface LayoutHints {
+    /** Primary content Y position (percentage string, e.g., "35%") */
+    primaryY: string;
+    /** Secondary content Y position (percentage string) */
+    secondaryY: string;
+    /** Tertiary/detail Y position (percentage string) */
+    tertiaryY: string;
+    /** Title font size multiplier (relative to base) */
+    titleScale: number;
+    /** Body text font size multiplier (relative to base) */
+    bodyScale: number;
+    /** Two-column: left X position (percentage string) */
+    columnLeftX: string;
+    /** Two-column: right X position (percentage string) */
+    columnRightX: string;
+    /** Two-column in portrait: top Y position for stacked layout */
+    columnTopY: string;
+    /** Two-column in portrait: bottom Y position for stacked layout */
+    columnBottomY: string;
+    /** Whether two-column should stack vertically */
+    stackColumns: boolean;
+    /** Max text width (percentage string) for wrapping */
+    maxTextWidth: string;
+    /** Horizontal padding from edges (percentage string) */
+    horizontalPadding: string;
+    /** Caption position Y for imageWithCaption (percentage string) */
+    captionY: string;
+    /** Caption font size multiplier */
+    captionScale: number;
+}
+/**
+ * Get layout hints for a given orientation.
+ */
+declare function getLayoutHints(orientation: ViewportOrientation): LayoutHints;
+/**
+ * Calculate a scaled font size based on viewport and layout hints.
+ *
+ * @param basePx - Base font size in pixels (designed for 1920x1080)
+ * @param viewport - Target viewport configuration
+ * @param orientation - Viewport orientation
+ * @param isTitle - Whether this is title text (uses titleScale) or body (uses bodyScale)
+ */
+declare function scaledFontSize$1(basePx: number, viewport: ViewportConfig, orientation: ViewportOrientation, isTitle?: boolean): number;
+/**
+ * Get position for two-column layout based on orientation.
+ * Returns { left: {x, y}, right: {x, y} } positions.
+ */
+declare function getTwoColumnPositions(orientation: ViewportOrientation): {
+    left: {
+        x: string;
+        y: string;
+    };
+    right: {
+        x: string;
+        y: string;
+    };
+};
+/**
+ * Get safe text bounds for a given orientation.
+ * Returns margins to keep text away from edges.
+ */
+declare function getSafeTextBounds(orientation: ViewportOrientation): {
+    left: string;
+    right: string;
+    top: string;
+    bottom: string;
+};
+
+/**
+ * Theme System
+ *
+ * A Theme bundles color palette, typography, visual style, render-style
+ * algorithm, and per-block color schemes into one JSON-serializable object.
+ * Builders choose a theme from the built-in library or create a custom one
+ * via `createTheme(base, overrides)`.
+ *
+ * Design principles:
+ * - Fully JSON-serializable (no functions) — storable in config / APIs.
+ * - Doc carries an optional `themeId` pointer; resolution happens at render time.
+ * - `createTheme` deep-merges a base theme with partial overrides.
+ */
+
+/**
+ * Core color palette for a theme. Every color is a CSS color string.
+ */
+interface ThemeColorPalette {
+    /** Primary accent color */
+    primary: string;
+    /** Secondary accent color */
+    secondary: string;
+    /** Background color (typically dark) */
+    background: string;
+    /** Lighter background for contrast panels */
+    backgroundLight: string;
+    /** Main text color */
+    text: string;
+    /** Muted/secondary text color */
+    textMuted: string;
+    /** Highlight/emphasis color */
+    highlight: string;
+    /** Warning/alert color */
+    warning: string;
+}
+/**
+ * A named color scheme used by templates for per-block color variation
+ * (e.g., statHighlight or sectionHeader).
+ */
+interface ThemeColorScheme {
+    /** Background fill */
+    bg: string;
+    /** Primary text tint */
+    text: string;
+    /** Accent / secondary tint */
+    accent: string;
+}
+/**
+ * Typography settings for a theme.
+ */
+interface ThemeTypography {
+    /** Font family for body / description text */
+    bodyFontFamily: string;
+    /** Font family for titles and headings */
+    titleFontFamily: string;
+    /** Font family for code / monospaced text (optional) */
+    monoFontFamily?: string;
+    /** Multiplier applied to LayoutHints.titleScale (default 1.0) */
+    titleScale?: number;
+    /** Multiplier applied to LayoutHints.bodyScale (default 1.0) */
+    bodyScale?: number;
+    /** Default body line height (default 1.4) */
+    lineHeight?: number;
+    /** Default title line height */
+    titleLineHeight?: number;
+    /** Default title font weight */
+    titleWeight?: 'normal' | 'bold';
+}
+/**
+ * Global visual-style knobs that templates consult.
+ */
+interface ThemeStyle {
+    /** Default border radius for cards / shapes (px) */
+    borderRadius?: number;
+    /** Whether templates should default to text shadows */
+    textShadow?: boolean;
+    /** Darkness of overlay on image-backed blocks (0–1) */
+    overlayOpacity?: number;
+    /** Multiplier on all animation durations (1.0 = normal, <1 faster, >1 slower) */
+    animationSpeed?: number;
+    /** Default horizontal padding for text (percentage string, e.g. "5%") */
+    blockPadding?: string;
+}
+/**
+ * Render-style algorithm preset. Controls layout tweaks, default animations,
+ * transitions, and per-template behavioral hints.
+ */
+interface RenderStyle {
+    /** Identifier for this algorithmic approach (e.g. "documentary", "magazine") */
+    name: string;
+    /** Partial overrides merged onto the orientation-based LayoutHints */
+    layoutOverrides?: Partial<LayoutHints>;
+    /** Default entrance animation for text layers */
+    defaultTextAnimation?: AnimationType;
+    /** Default animation for background / image layers */
+    defaultImageAnimation?: AnimationType;
+    /** Whether to apply Ken Burns ambient motion to images by default */
+    ambientMotion?: boolean;
+    /** Default block-to-block transition */
+    defaultTransition?: {
+        type: TransitionType;
+        duration?: number;
+    };
+    /**
+     * Per-template behavioral hints. Keys are template names, values are
+     * string/number/boolean maps that templates can read to vary their output.
+     *
+     * @example
+     * ```
+     * { statHighlight: { entrance: 'dramatic' }, titleBlock: { showAccentLine: false } }
+     * ```
+     */
+    templateHints?: Record<string, Record<string, string | number | boolean>>;
+}
+/**
+ * A complete, JSON-serializable theme definition.
+ */
+interface Theme {
+    /** Unique identifier (e.g. "documentary") */
+    id: string;
+    /** Human-readable display name */
+    name: string;
+    /** Short description for theme pickers */
+    description?: string;
+    /** Color palette */
+    colors: ThemeColorPalette;
+    /** Typography settings */
+    typography: ThemeTypography;
+    /** Global visual-style knobs */
+    style: ThemeStyle;
+    /** Algorithmic render-style preset */
+    renderStyle: RenderStyle;
+    /**
+     * Named color schemes for per-block color variation.
+     * Templates reference these by name (e.g. "blue", "warm").
+     */
+    colorSchemes: Record<string, ThemeColorScheme>;
+    /** Optional persistent layers baked into the theme */
+    persistentLayers?: PersistentLayerConfig;
+}
+/**
+ * Recursively makes every property optional.
+ */
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+/**
+ * Create a new theme by deep-merging overrides onto a base theme.
+ * The returned theme gets its own `id` if one is provided in overrides,
+ * otherwise keeps the base theme's `id` suffixed with "-custom".
+ *
+ * @example
+ * ```ts
+ * const myTheme = createTheme(THEMES.documentary, {
+ *   colors: { primary: '#ff0000' },
+ *   typography: { bodyFontFamily: '"Inter", sans-serif' },
+ * });
+ * ```
+ */
+declare function createTheme(base: Theme, overrides: DeepPartial<Theme>): Theme;
+
+/**
+ * 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 "titleBlock" 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:
+ * - titleBlock: Doc intro with title + subtitle
+ * - sectionHeader: Colored section divider
+ * - statHighlight: Big number/stat with description
+ * - quoteBlock: Large centered quote
+ * - factCard: Key fact with explanation
+ * - twoColumn: Side-by-side comparison
+ * - dateEvent: Timeline-style date + description
+ * - imageWithCaption: Image with text overlay
+ */
+
+/**
+ * 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()`.
+ */
+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.
+ */
+declare const DEFAULT_DOC_FONT = "\"PT Serif\", Georgia, \"Times New Roman\", serif";
+/**
+ * Default font family for titles.
+ */
+declare const DEFAULT_TITLE_FONT = "\"PT Serif\", Georgia, \"Times New Roman\", serif";
+/**
+ * Position options for accent images on text-based blocks.
+ * Accents are tasteful image additions that complement rather than overwhelm text.
+ */
+type AccentPosition = 'left-strip' | 'right-strip' | 'bottom-strip' | 'corner-inset';
+/**
+ * Accent image configuration for text-based blocks.
+ * When present, the template adjusts layout to accommodate the image tastefully.
+ */
+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;
+}
+/**
+ * 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;
+}
+/**
+ * Title block - doc intro with large title and subtitle.
+ */
+interface TitleBlockInput extends BaseTemplateBlock {
+    template: 'titleBlock';
+    /** 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.
+ */
+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.
+ */
+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.
+ */
+interface QuoteBlockInput extends BaseTemplateBlock {
+    template: 'quoteBlock';
+    /** 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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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;
+}
+/**
+ * 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.
+ */
+interface MapBlockInput extends BaseTemplateBlock {
+    template: 'mapBlock';
+    /** 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.
+ */
+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".
+ */
+interface ListBlockInput extends BaseTemplateBlock {
+    template: 'listBlock';
+    /** 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;
+}
+/**
+ * Photo grid - 2-4 images in a tiled layout.
+ * Used when multiple images are available for visual variety.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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;
+    };
+}
+/**
+ * Union of all template block types.
+ */
+type TemplateBlock = TitleBlockInput | SectionHeaderInput | StatHighlightInput | QuoteBlockInput | FactCardInput | TwoColumnInput | DateEventInput | ImageWithCaptionInput | MapBlockInput | FullBleedQuoteInput | ListBlockInput | PhotoGridInput | DefinitionCardInput | ComparisonBarInput | PullQuoteInput | VideoWithCaptionInput | VideoPullQuoteInput;
+/**
+ * A block can be either a raw Block or a TemplateBlock.
+ */
+type DocBlock = Block | TemplateBlock;
+/**
+ * Check if a block is a template block.
+ */
+declare function isTemplateBlock(block: DocBlock): block is TemplateBlock;
+/**
+ * Template context passed to template functions.
+ * Includes viewport information for multi-aspect ratio support.
+ */
+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;
+}
+/**
+ * Create a template context with viewport-derived values.
+ */
+declare function createTemplateContext(theme: Theme, blockIndex: number, totalBlocks: number, viewport?: ViewportConfig): TemplateContext;
+/**
+ * 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
+ */
+declare function scaledFontSize(basePx: number, context: TemplateContext, isTitle?: boolean): number;
+/**
+ * Template function signature.
+ * Takes template input and returns layers array.
+ */
+type TemplateFunction<T extends TemplateBlock> = (input: T, context: TemplateContext) => Layer[];
+/**
+ * Registry of all template functions.
+ */
+type TemplateRegistry = {
+    [K in TemplateBlock['template']]: TemplateFunction<Extract<TemplateBlock, {
+        template: K;
+    }>>;
+};
+/**
+ * Configuration for persistent doc-wide layers.
+ * Bottom layers render behind all block content, top layers on top.
+ */
+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.
+ */
+type PersistentLayer = PersistentLayerTemplate | Layer;
+/**
+ * Check if a persistent layer is a template.
+ */
+declare function isPersistentLayerTemplate(layer: PersistentLayer): layer is PersistentLayerTemplate;
+/**
+ * Template-based persistent layer for easy configuration.
+ */
+interface PersistentLayerTemplate {
+    template: PersistentLayerTemplateType;
+    config: PersistentLayerTemplateConfig;
+}
+/**
+ * Available persistent layer template types.
+ */
+type PersistentLayerTemplateType = 'solidBackground' | 'gradientBackground' | 'imageBackground' | 'patternBackground' | 'titleCaption' | 'cornerBranding' | 'progressIndicator';
+/**
+ * Union of all persistent layer template configs.
+ */
+type PersistentLayerTemplateConfig = SolidBackgroundConfig | GradientBackgroundConfig | ImageBackgroundConfig | PatternBackgroundConfig | TitleCaptionConfig | CornerBrandingConfig | ProgressIndicatorConfig;
+/**
+ * Solid color background.
+ */
+interface SolidBackgroundConfig {
+    type: 'solidBackground';
+    /** CSS color value */
+    color: string;
+}
+/**
+ * Gradient background (CSS gradient or preset).
+ */
+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).
+ */
+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).
+ */
+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;
+}
+/**
+ * Title caption overlay (article title in corner).
+ */
+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).
+ */
+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).
+ */
+interface ProgressIndicatorConfig {
+    type: 'progressIndicator';
+    /** Indicator style */
+    style: 'bar' | 'dots' | 'fraction';
+    /** Position on screen */
+    position: 'bottom' | 'top';
+    /** Indicator color */
+    color?: string;
+}
+
+/**
+ * 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.
+ */
+/**
+ * Configuration for the Start/resting block shown before playback begins.
+ */
+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.
+ */
+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?: 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)
+ */
+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;
+    /**
+     * 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?: 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?: 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>;
+}
+/**
+ * A visual element within a block.
+ * Layers are composited back-to-front (first layer is background).
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+type MapTileStyle = 'terrain' | 'satellite' | 'road' | 'toner' | 'watercolor';
+/**
+ * A marker to display on the map.
+ */
+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 and dimensions for a layer.
+ * Values can be pixels (number) or percentages (string like "50%").
+ */
+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.
+ */
+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 to apply to a layer.
+ */
+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.
+ */
+type AnimationType = 'none' | 'fadeIn' | 'fadeOut' | 'slowZoom' | 'zoomIn' | 'zoomOut' | 'panLeft' | 'panRight' | 'typewriter';
+/**
+ * Transition between blocks.
+ */
+interface Transition {
+    /** Transition type */
+    type: TransitionType;
+    /** Duration in seconds */
+    duration: number;
+}
+type TransitionType = 'cut' | 'fade' | 'dissolve' | 'slideLeft' | 'slideRight';
+/**
+ * Audio track configuration.
+ * Articles have multiple MP3 segments (intro + sections).
+ */
+interface AudioTrack {
+    /** Audio segments in playback order */
+    segments: AudioSegment[];
+}
+/**
+ * A single caption phrase to display during playback.
+ */
+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.
+ */
+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).
+ */
+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;
+}
+/**
+ * Calculate total duration from audio segments.
+ */
+declare function calculateDuration(audio: AudioTrack): number;
+/**
+ * Find which audio segment is playing at a given time.
+ */
+declare function getSegmentAtTime(audio: AudioTrack, time: number): number;
+/**
+ * Find which block should be visible at a given time.
+ */
+declare function getBlockAtTime(blocks: Block[], time: number): Block | null;
+/**
+ * Find the caption phrase that should be displayed at a given time.
+ */
+declare function getCaptionAtTime(captions: CaptionTrack | undefined, time: number): CaptionPhrase | null;
+/**
+ * Validate a Doc for completeness.
+ */
+declare function validateDoc(script: Doc): string[];
+
+/**
+ * Built-in Theme Library
+ *
+ * Ships 8 curated themes covering documentary, editorial, minimal, and
+ * cinematic styles. Each theme is fully JSON-serializable.
+ *
+ * Usage:
+ * ```ts
+ * import { THEMES, resolveTheme } from '@bendyline/squisq/schemas';
+ *
+ * const theme = resolveTheme('minimalist'); // look up by id
+ * const theme = THEMES.documentary;         // direct access
+ * ```
+ */
+
+/**
+ * All built-in themes, keyed by id.
+ */
+declare const THEMES: Record<string, Theme>;
+/** The default theme id. */
+declare const DEFAULT_THEME_ID = "documentary";
+/** The default theme (documentary — migrated from old DEFAULT_THEME). */
+declare const DEFAULT_THEME: Theme;
+/**
+ * Resolve a theme by id. Returns the default theme when `id` is
+ * undefined or not found in the library.
+ */
+declare function resolveTheme(id: string | undefined): Theme;
+/**
+ * Get all available theme ids.
+ */
+declare function getAvailableThemes(): string[];
+/**
+ * Get a summary of all themes (id + name + description) for theme pickers.
+ */
+declare function getThemeSummaries(): Array<{
+    id: string;
+    name: string;
+    description?: string;
+}>;
+
+export { type TemplateContext as $, type AccentImage as A, type Block as B, type CaptionPhrase as C, DEFAULT_DOC_FONT as D, type PersistentLayerConfig as E, type FactCardInput as F, type GradientBackgroundConfig as G, type PersistentLayerTemplate as H, type ImageBackgroundConfig as I, type PersistentLayerTemplateConfig as J, type PersistentLayerTemplateType as K, type Layer as L, type MapBlockInput as M, type PhotoGridInput as N, type Position as O, type PatternBackgroundConfig as P, type ProgressIndicatorConfig as Q, type PullQuoteInput as R, type QuoteBlockInput as S, type RenderStyle as T, type SectionHeaderInput as U, type ShapeLayer as V, type SolidBackgroundConfig as W, type StartBlockConfig as X, type StatHighlightInput as Y, THEMES as Z, type TemplateBlock as _, type AccentPosition as a, type TemplateFunction as a0, type TemplateRegistry as a1, type TextLayer as a2, type TextStyle as a3, type Theme as a4, type ThemeColorPalette as a5, type ThemeColorScheme as a6, type ThemeStyle as a7, type ThemeTypography as a8, type TitleBlockInput as a9, isPersistentLayerTemplate as aA, isTemplateBlock as aB, scaledFontSize$1 as aC, resolveTheme as aD, scaledFontSize as aE, validateDoc as aF, type TitleCaptionConfig as aa, type Transition as ab, type TransitionType as ac, type TwoColumnInput as ad, VIEWPORT_PRESETS as ae, type VideoLayer as af, type VideoPullQuoteInput as ag, type VideoWithCaptionInput as ah, type ViewportConfig as ai, type ViewportOrientation as aj, type ViewportPreset as ak, calculateDuration as al, calculateFontScale as am, createTemplateContext as an, createTheme as ao, getAspectRatioString as ap, getAvailableThemes as aq, getBlockAtTime as ar, getCaptionAtTime as as, getLayoutHints as at, getSafeTextBounds as au, getSegmentAtTime as av, getThemeSummaries as aw, getTwoColumnPositions as ax, getViewport as ay, getViewportOrientation as az, type Animation as b, type AnimationType as c, type AudioSegment as d, type AudioTrack as e, type CaptionTrack as f, type ColorScheme as g, type ComparisonBarInput as h, type CornerBrandingConfig as i, DEFAULT_THEME as j, DEFAULT_THEME_ID as k, DEFAULT_TITLE_FONT as l, type DateEventInput as m, type DeepPartial as n, type DefinitionCardInput as o, type Doc as p, type DocBlock as q, type FullBleedQuoteInput as r, type ImageLayer as s, type ImageWithCaptionInput as t, type LayoutHints as u, type ListBlockInput as v, type MapLayer as w, type MapMarker as x, type MapTileStyle as y, type PersistentLayer as z };