@bendyline/squisq 1.5.2 → 2.0.0

package/dist/story/index.d.ts

@@ -1,1801 +0,0 @@
-import { a4 as PersistentLayer, az as Theme, S as Layer, a5 as PersistentLayerConfig, aG as TitleBlockInput, au as TemplateContext, ai as SectionHeaderInput, ao as StatHighlightInput, ad as QuoteBlockInput, I as FactCardInput, aI as TwoColumnInput, u as DateEventInput, Q as ImageWithCaptionInput, V as LeftFeatureInput, ag as RightFeatureInput, Y as MapBlockInput, an as StartBlockConfig, L as FullBleedQuoteInput, X as ListBlockInput, a9 as PhotoGridInput, w as DefinitionCardInput, n as ComparisonBarInput, ac as PullQuoteInput, aM as VideoWithCaptionInput, aL as VideoPullQuoteInput, t as DataTableInput, x as DiagramBlockInput, B as Block, F as DrawingBlockInput, a0 as MarkerStyle, at as TemplateBlock, A as AccentImage, P as ImageTreatment, a as AccentPosition, aN as ViewportConfig, p as CustomTemplateDefinition, z as DocBlock, aw as TemplateRegistry, c as Animation, d as AnimationType, aB as ThemeColorScheme, y as Doc, E as DocDiagnostic } from '../Doc-BBVGq1_9.js';
-export { G as FRONTMATTER_CUSTOM_TEMPLATES_KEY, H as FRONTMATTER_CUSTOM_THEMES_KEY, U as LayoutHints, af as RenderStyle, aA as ThemeColorPalette, aE as ThemeStyle, aF as ThemeTypography, aJ as VIEWPORT_PRESETS, aO as ViewportOrientation, aP as ViewportPreset, aU as createTemplateContext, a_ as getLayoutHints, b2 as getTwoColumnPositions, b3 as getViewport, b4 as getViewportOrientation, b6 as isTemplateBlock, bb as scaledFontSize } from '../Doc-BBVGq1_9.js';
-import { I as MarkdownNode, $ as TransitionType, _ as TransitionDirection, M as MarkdownBlockNode, q as MarkdownHeading, m as MarkdownDocument, P as MarkdownTable, h as MarkdownCodeBlock } from '../types-DlAZ7MW4.js';
-import { C as ContentContainer } from '../ContentContainer-BXUlIf18.js';
-export { D as DEFAULT_THEME, g as getAvailableThemes, b as getThemeSummaries, r as resolveTheme } from '../themeLibrary-CehcJhzz.js';
-
-/**
- * Canonical, framework-free UI metadata for every built-in block template.
- *
- * This is the single source of truth for the human-readable label and the
- * one-sentence description of each template id in {@link templateRegistry}.
- * The editor's `TemplatePicker` renders its gallery from this map (joining
- * each id with a locally-defined SVG icon, which can't live in this
- * framework-free package), so a template only has to be added here and to
- * `templateRegistry` for it to surface in the editor.
- *
- * `templateMetadata.test.ts` asserts this map and `templateRegistry` stay
- * exactly 1:1 — adding a template to one without the other fails the build.
- *
- * Order matters: pickers iterate this object's insertion order, so it doubles
- * as the canonical gallery order.
- */
-interface TemplateMetadata {
-    /** Human-readable label shown in pickers (e.g. "Image with Caption"). */
-    label: string;
-    /** One-sentence description of when to reach for this template. */
-    description: string;
-}
-declare const TEMPLATE_METADATA: Record<string, TemplateMetadata>;
-
-/**
- * Persistent Layers Expansion
- *
- * Expands persistent layer templates (solid backgrounds, gradients, overlays)
- * into raw Layer arrays. These layers are injected into each block based on
- * per-block flags (useBottomLayer, useTopLayer).
- *
- * This is shared code used by both site and efb-app doc renderers.
- *
- * Related Files:
- * - schemas/BlockTemplates.ts - PersistentLayerConfig types
- */
-
-/**
- * Expand all persistent layers in a config to raw Layer arrays.
- */
-declare function expandPersistentLayers(layers: PersistentLayer[] | undefined, theme?: Theme): Layer[];
-/** Legacy style preset names. Prefer using `Theme.persistentLayers` directly. */
-type DocStylePreset = 'minimal' | 'documentary' | 'branded' | 'cinematic' | 'clean';
-/**
- * Get a PersistentLayerConfig from a style preset.
- *
- * @param preset - Style preset name
- * @param articleTitle - Article title for title caption
- * @param heroSrc - Optional hero image for cinematic style
- */
-declare function getDocStyleConfig(preset: DocStylePreset, articleTitle: string, heroSrc?: string, subtitle?: string): PersistentLayerConfig;
-/**
- * Get persistent layers from a Theme. Returns the theme's baked-in
- * persistentLayers config, or an empty config when the theme has none.
- */
-declare function getPersistentLayersFromTheme(theme: Theme): PersistentLayerConfig;
-/**
- * Resolve the effective persistent-layer config for a doc: the doc's own
- * config wins **wholesale** when present; only docs with no persistent
- * layers inherit the theme's.
- *
- * Doc-wins-wholesale (rather than merging) protects pre-baked documents
- * that carry their own background/branding layers — merging a theme's
- * atmosphere on top of those would double up backgrounds and stack
- * overlays the doc author never saw.
- */
-declare function resolvePersistentLayers(doc: {
-    persistentLayers?: PersistentLayerConfig;
-}, theme: Theme): PersistentLayerConfig | undefined;
-/**
- * Compose a block's layers between pre-expanded persistent bottom/top
- * layers, honoring the per-block `useBottomLayer` / `useTopLayer` opt-outs.
- * Single shared implementation for `expandDocBlocks` and `getLayers`.
- */
-declare function wrapWithPersistentLayers(layers: Layer[], block: {
-    useBottomLayer?: boolean;
-    useTopLayer?: boolean;
-}, bottomLayers: Layer[], topLayers: Layer[]): Layer[];
-
-/**
- * Title Block Template
- *
- * Large title with optional subtitle for doc intros.
- * Centered text with fade-in animations, composed as one lockup:
- * accent rule, title, and subtitle are spaced from the title's
- * estimated height instead of fixed slots that collide on wrap.
- * Adapts font sizes and positioning for different viewports.
- *
- * This is shared code used by both site and efb-app doc renderers.
- */
-
-declare function titleBlock(input: TitleBlockInput, context: TemplateContext): Layer[];
-
-/**
- * Section Header Template
- *
- * Section title card with optional background image.
- * Used to introduce new sections of a story.
- * When an image is provided, displays like a title slide with the image as background.
- * Without an image, falls back to a colored background.
- *
- * This is shared code used by both site and efb-app doc renderers.
- */
-
-declare function sectionHeader(input: SectionHeaderInput, context: TemplateContext): Layer[];
-
-/**
- * Stat Highlight Template
- *
- * Large statistic/number with description and optional detail.
- * Great for emphasizing key data points.
- * Adapts font sizes and positioning for different viewports.
- *
- * Supports optional accent images that appear as tasteful side/bottom strips.
- *
- * This is shared code used by both site and efb-app doc renderers.
- */
-
-declare function statHighlight(input: StatHighlightInput, context: TemplateContext): Layer[];
-
-/**
- * Quote Block Template
- *
- * Large centered quote with optional attribution, composed as one
- * vertically-centered lockup: the attribution hangs a fixed distance
- * below the quote's estimated bottom edge instead of being pinned to a
- * far-away layout slot.
- * Adapts font sizes and positioning for different viewports.
- *
- * Supports optional accent images that appear as tasteful side/bottom strips.
- *
- * This is shared code used by both site and efb-app doc renderers.
- */
-
-declare function quoteBlock(input: QuoteBlockInput, context: TemplateContext): Layer[];
-
-/**
- * Fact Card Template
- *
- * Key fact with explanation and optional source, composed as one
- * vertically-centered lockup: each element is placed relative to the
- * estimated height of the one above it, so short content doesn't leave
- * fixed-slot voids and long content doesn't collide.
- * Adapts font sizes and positioning for different viewports.
- *
- * Supports optional accent images that appear as tasteful side/bottom strips.
- *
- * This is shared code used by both site and efb-app doc renderers.
- */
-
-declare function factCard(input: FactCardInput, context: TemplateContext): Layer[];
-
-/**
- * Two Column Template
- *
- * Side-by-side comparison of two items.
- * Each column has a label and optional sublabel.
- * Adapts font sizes and positioning for different viewports.
- *
- * Portrait mode: Stacks columns vertically (top/bottom) instead of side-by-side.
- *
- * This is shared code used by both site and efb-app doc renderers.
- */
-
-declare function twoColumn(input: TwoColumnInput, context: TemplateContext): Layer[];
-
-/**
- * Date Event Template
- *
- * Timeline-style slide with prominent date and description.
- * Supports different moods: neutral, somber, celebratory.
- * Adapts font sizes and positioning for different viewports.
- *
- * Supports optional accent images that appear as tasteful side/bottom strips.
- *
- * This is shared code used by both site and efb-app doc renderers.
- */
-
-declare function dateEvent(input: DateEventInput, context: TemplateContext): Layer[];
-
-/**
- * Image With Caption Template
- *
- * Full-screen background image with text overlay.
- * Supports Ken Burns animation effects (zoom, pan).
- * Adapts caption positioning and font sizes for different viewports.
- *
- * This is shared code used by both site and efb-app doc renderers.
- */
-
-declare function imageWithCaption(input: ImageWithCaptionInput, context: TemplateContext): Layer[];
-
-/**
- * Feature Block Templates — `leftFeature` and `rightFeature`
- *
- * Pairs a "feature" image on one side of the block with a title + body
- * paragraph on the other. The two templates are mirror images, so the
- * actual layer-builder lives here once and the per-side template files
- * just call it with a `side` parameter.
- *
- * Used for editorial layouts like product highlights, profile cards,
- * and section intros where a single image deserves to sit next to a
- * short text block rather than behind it (which is what
- * `imageWithCaption` does).
- */
-
-declare function leftFeature(input: LeftFeatureInput, context: TemplateContext): Layer[];
-declare function rightFeature(input: RightFeatureInput, context: TemplateContext): Layer[];
-
-/**
- * Map Block Template
- *
- * Full-screen geographic map with optional title and caption overlays.
- * Great for establishing geographic context at the start of a doc
- * or when discussing location-specific content.
- * Adapts font sizes and positioning for different viewports.
- *
- * Map tiles are fetched from free/open-source providers.
- * See docs/MAP_TILES.md for available styles and attribution requirements.
- *
- * This is shared code used by both site and efb-app doc renderers.
- */
-
-declare function mapBlock(input: MapBlockInput, context: TemplateContext): Layer[];
-
-/**
- * Cover Block Template
- *
- * Full-screen hero image with title overlay, shown before playback starts.
- * This is the "poster for the doc, displaying the
- * article's hero image with elegant title treatment.
- *
- * Features:
- * - Full-screen hero image with Ken Burns ambient motion
- * - Gradient overlay for text readability
- * - Large centered title with optional subtitle
- * - No animation delays (shown at rest, not during playback)
- *
- * This is shared code used by both site and efb-app doc renderers.
- */
-
-/**
- * Input for coverBlock template - matches StartBlockConfig
- */
-interface CoverBlockInput {
-    /** Path to hero image (omit for theme-driven background) */
-    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 */
-    heroCredit?: string;
-    /** License identifier */
-    heroLicense?: string;
-    /** Per-block override for the theme's photographic image grade. */
-    imageTreatment?: 'none' | 'mono' | 'duotone' | 'warm' | 'cool';
-}
-/**
- * Generate cover block layers from StartBlockConfig.
- */
-declare function coverBlock(input: CoverBlockInput, context: TemplateContext): Layer[];
-/**
- * Expand a StartBlockConfig into a renderable Block.
- * This is used by the player to render the cover block at rest.
- */
-declare function expandCoverBlock(config: StartBlockConfig, context: TemplateContext): Layer[];
-
-/**
- * Full Bleed Quote Template
- *
- * Short dramatic text filling the viewport like a movie title card.
- * Designed for punchy text under 60 characters. Uses massive font
- * centered on a dark vignette background.
- *
- * This is shared code used by both site and efb-app doc renderers.
- */
-
-declare function fullBleedQuote(input: FullBleedQuoteInput, context: TemplateContext): Layer[];
-
-/**
- * List Block Template
- *
- * Displays 3-5 items in a numbered vertical list with staggered animations.
- * Good for enumerations like "things to see", "key features", or "tips".
- * Supports optional accent images.
- *
- * This is shared code used by both site and efb-app doc renderers.
- */
-
-declare function listBlock(input: ListBlockInput, context: TemplateContext): Layer[];
-
-/**
- * Photo Grid Template
- *
- * Displays 2-4 images in a tiled layout for visual variety.
- * Layout adapts based on image count and viewport orientation:
- *
- * Landscape:
- * - 2 images: side-by-side 50/50
- * - 3 images: one large left (60%) + two stacked right
- * - 4 images: 2x2 grid
- *
- * Portrait (9:16): images stack horizontally (top/bottom) instead of
- * side-by-side, giving each image full width on narrow screens.
- *
- * This is shared code used by both site and efb-app doc renderers.
- */
-
-declare function photoGrid(input: PhotoGridInput, context: TemplateContext): Layer[];
-
-/**
- * Definition Card Template
- *
- * Dictionary-style slide with a large term and its definition.
- * Good for explaining local words, place names, or cultural concepts.
- * Supports optional accent images.
- *
- * This is shared code used by both site and efb-app doc renderers.
- */
-
-declare function definitionCard(input: DefinitionCardInput, context: TemplateContext): Layer[];
-
-/**
- * Comparison Bar Template
- *
- * Two horizontal bars showing relative numeric values side by side.
- * Bar widths are proportional to the values for immediate visual comparison.
- * Good for population, distance, or measurement comparisons.
- *
- * This is shared code used by both site and efb-app doc renderers.
- */
-
-declare function comparisonBar(input: ComparisonBarInput, context: TemplateContext): Layer[];
-
-/**
- * Pull Quote Template
- *
- * Quote text over a full-bleed background image with dark overlay.
- * Cinematic alternative to quoteBlock when a high-quality image is available.
- * Combines the visual impact of imageWithCaption with the text focus of quoteBlock.
- *
- * This is shared code used by both site and efb-app doc renderers.
- */
-
-declare function pullQuote(input: PullQuoteInput, context: TemplateContext): Layer[];
-
-/**
- * Video With Caption Template
- *
- * Full-screen background video clip with text overlay. Mirrors the structure of
- * imageWithCaption but uses a VideoLayer instead of an ImageLayer. The video
- * plays muted — narration audio is the only sound track.
- *
- * Adapts caption positioning and font sizes for different viewports.
- *
- * This is shared code used by both site and efb-app doc renderers.
- *
- * Related Files:
- * - shared/story/templates/imageWithCaption.ts — image equivalent
- * - schemas/StoryScript.ts — VideoLayer type
- * - site/src/components/story/layers/VideoLayer.tsx — rendering component
- */
-
-declare function videoWithCaption(input: VideoWithCaptionInput, context: TemplateContext): Layer[];
-
-/**
- * Video Pull Quote Template
- *
- * Quote text over a video clip background with dark overlay.
- * Cinematic alternative to pullQuote when a video clip is available.
- * Combines the visual dynamism of live video with the text focus of quoteBlock.
- *
- * The video plays muted — narration audio is the only sound track.
- *
- * This is shared code used by both site and efb-app doc renderers.
- *
- * Related Files:
- * - shared/story/templates/pullQuote.ts — image-based equivalent
- * - schemas/StoryScript.ts — VideoLayer type
- * - site/src/components/story/layers/VideoLayer.tsx — rendering component
- */
-
-declare function videoPullQuote(input: VideoPullQuoteInput, context: TemplateContext): Layer[];
-
-/**
- * Data Table Template
- *
- * Renders a themed table with header row and data rows.
- * Uses a TableLayer (foreignObject-based HTML table inside SVG)
- * for proper table layout within the viewport.
- *
- * Adapts font sizes for different viewports and uses theme colors
- * for header background, text, borders, and body cells.
- */
-
-declare function dataTable(input: DataTableInput, context: TemplateContext): Layer[];
-
-/**
- * Diagram block template.
- *
- * Renders the parent block's children as a node-and-edge diagram:
- * - Each child becomes a rounded-rect node card with its title as label.
- * - Each `child.connectsTo` entry becomes a path edge (cubic-bezier curve
- *   with an arrowhead at the target end).
- * - Children with `x`/`y` set are placed at those coordinates; the rest
- *   are auto-laid out below in a square-ish grid (see `diagramLayout.ts`).
- *
- * Layout coordinates from `x=`/`y=` are author-defined units. The
- * template computes a bounding box of all nodes and scales it to fit
- * the block's viewport with padding, so users don't have to think about
- * absolute pixel ranges.
- */
-
-declare function diagramBlock(input: DiagramBlockInput, context: TemplateContext): Layer[];
-
-/**
- * Diagram layout — shared between the read-only SVG render path
- * (`diagramBlock` template) and the interactive editor (React Flow in
- * `@bendyline/squisq-editor-react`). Same children + same options always
- * produce the same node positions and edge list, so previews and the
- * editor stay visually consistent.
- *
- * Layout rules:
- * 1. Children with both `x` and `y` set keep their authored coordinates.
- * 2. Children missing either coordinate are auto-placed in a square-ish
- *    grid in declaration order, offset below the bounding box of the
- *    explicitly-positioned children.
- * 3. Edges come from each child's `connectsTo`. Targets that don't match
- *    any sibling id are dropped (and counted in `warnings`).
- */
-
-interface DiagramNodePosition {
-    /** Block id (matches `Block.id`). */
-    id: string;
-    /** Display label (block title or fallback to id). */
-    label: string;
-    /** Pixel x coordinate (canvas-relative). */
-    x: number;
-    /** Pixel y coordinate (canvas-relative). */
-    y: number;
-    /** True when the position came from `x=`/`y=` attributes; false when auto-laid out. */
-    pinned: boolean;
-    /** Optional `.class` tokens carried over from the heading. */
-    classes?: string[];
-}
-interface DiagramEdge {
-    /** Synthetic stable edge id. */
-    id: string;
-    /** Source node id. */
-    source: string;
-    /** Target node id. */
-    target: string;
-    /** Connection type from `connectsTo=target:type` (used as edge label). */
-    type?: string;
-}
-interface DiagramLayout {
-    nodes: DiagramNodePosition[];
-    edges: DiagramEdge[];
-    warnings: string[];
-}
-interface DiagramLayoutOptions {
-    /** Horizontal grid pitch between auto-laid-out nodes. Default: 260 (node width 180 + 80 air). */
-    gapX?: number;
-    /** Vertical grid pitch between auto-laid-out nodes. Default: 140. */
-    gapY?: number;
-    /** Padding around the explicit-positions bounding box before the grid starts. Default: 80. */
-    gridPad?: number;
-    /** Origin x for the grid when no explicit nodes anchor it. Default: 80. */
-    gridOriginX?: number;
-    /** Origin y for the grid when no explicit nodes anchor it. Default: 80. */
-    gridOriginY?: number;
-}
-/**
- * Compute node positions and edges for a diagram from a parent block's
- * children. Pure function — same inputs always produce the same output.
- */
-declare function computeDiagramLayout(children: readonly Block[], options?: DiagramLayoutOptions): DiagramLayout;
-
-/**
- * Drawing block template.
- *
- * Renders the parent block's children as free-form shapes on a canvas:
- * - Each child becomes a shape (`rect`/`circle` → ShapeLayer, `line`/
- *   `arrow`/`path` → PathLayer, `text` → TextLayer) with its title as a
- *   centered label and its body text as an optional sublabel.
- * - `line`/`arrow` children with `from`/`to` (and any child's
- *   `connectsTo`) become connectors clipped to the shapes they join.
- *
- * Coordinates from `x`/`y`/`width`/`height` are author-defined units; the
- * template fits the bounding box of all shapes to the viewport with
- * padding (same approach as `diagramBlock`), so authors don't think in
- * absolute pixels.
- */
-
-declare function drawingBlock(input: DrawingBlockInput, context: TemplateContext): Layer[];
-
-/**
- * shapeGeometry — pure SVG geometry for the drawing/diagram shape vocabulary.
- *
- * Three concerns, all deterministic and dependency-free:
- *  - `shapePath(kind, x, y, w, h)` → an SVG path `d` for a named shape inscribed
- *    in a bounding box. Returns null for the natively-rendered primitives
- *    (rect / circle / line / text / path) so the caller can keep using a
- *    `ShapeLayer` for those; everything else becomes a computed `PathLayer`.
- *  - `markerPath(style, dir)` → the `<marker>` path for a line end-style, in the
- *    standard 0–10 marker viewBox (shared by the SSR `PathLayer` renderer and the
- *    editor's edge renderer).
- *  - `connectorPath(routing, start, end)` + `snapEndpoints(a, b)` → the line/edge
- *    geometry between two shapes (straight / orthogonal / curved), lifted from the
- *    diagram template so drawings and diagrams draw identical connectors. The older
- *    `clipEndpoints(a, b)` helper remains for free-angle clipping, but rendered
- *    connectors use snapped ports so authored lines land on stable attachment points.
- */
-
-/** Connector routing styles. */
-type ConnectorRouting = 'straight' | 'orthogonal' | 'curved';
-/**
- * Shape kinds rendered as computed paths (everything except the primitives the
- * renderer draws natively). Used by templates to decide ShapeLayer vs PathLayer.
- */
-declare const PATH_SHAPE_KINDS: Set<string>;
-/**
- * SVG path `d` for a named shape inscribed in `[x, y, w, h]`, or null when the
- * kind is rendered natively (rect / circle / line / text / path / arrow).
- */
-declare function shapePath(kind: string, x: number, y: number, w: number, h: number): string | null;
-/**
- * The `<marker>` path for a line end-style, in the 0–10 marker viewBox.
- * `dir` selects orientation (`end` points along +x; `start` is mirrored).
- * Returns null for `'none'`. `filled` shapes paint with the stroke color;
- * non-filled (`open`) draw as a stroked outline.
- */
-declare function markerPath(style: MarkerStyle, dir: 'start' | 'end'): {
-    d: string;
-    filled: boolean;
-} | null;
-interface ClipBox {
-    cx: number;
-    cy: number;
-    rx: number;
-    ry: number;
-}
-type ConnectorPort = 'top' | 'right' | 'bottom' | 'left' | 'top-left' | 'top-right' | 'bottom-right' | 'bottom-left';
-interface ConnectorSnapPoint {
-    port: ConnectorPort;
-    x: number;
-    y: number;
-}
-/** Intersection of the center-to-center line with `from`'s bounding box. */
-declare function clipPoint(from: ClipBox, to: ClipBox): {
-    x: number;
-    y: number;
-};
-/** Clip both endpoints of an edge to the two shapes it joins. */
-declare function clipEndpoints(a: ClipBox, b: ClipBox): {
-    start: {
-        x: number;
-        y: number;
-    };
-    end: {
-        x: number;
-        y: number;
-    };
-};
-/** The stable connector ports exposed around a shape/card box. */
-declare function snapPoints(box: ClipBox): ConnectorSnapPoint[];
-/** Nearest stable connector port on `box` to an arbitrary point. */
-declare function nearestSnapPoint(box: ClipBox, point: {
-    x: number;
-    y: number;
-}): ConnectorSnapPoint;
-/**
- * Pick the pair of connector ports, one on each box, with the shortest
- * distance between them. This gives stable attachments to side/corner handles
- * instead of arbitrary center-ray intersections.
- */
-declare function snapEndpoints(a: ClipBox, b: ClipBox): {
-    start: ConnectorSnapPoint;
-    end: ConnectorSnapPoint;
-};
-/** Build the SVG `d` for a connector between two clipped endpoints. */
-declare function connectorPath(routing: ConnectorRouting, start: {
-    x: number;
-    y: number;
-}, end: {
-    x: number;
-    y: number;
-}): string;
-/** Map a `lineStyle` (solid|dashed|dotted) to an SVG `stroke-dasharray`. */
-declare function lineStyleDasharray(style: string | undefined): string | undefined;
-
-/**
- * Drawing layout — shared, pure derivation of shapes + connectors from a
- * drawing block's child headings. Same children always produce the same
- * shapes, so SSR previews, exports, and (eventually) the editor stay
- * visually consistent. Mirrors `diagramLayout.ts` for the richer
- * free-form shape vocabulary.
- *
- * Each child heading is one shape. Its `{[shape …]}` annotation names the
- * primitive (`child.template`) and carries geometry/style as string params
- * (`child.templateOverrides`); `child.id` makes it referenceable;
- * `child.title` is the label.
- *
- * Layout rules (parallel to the diagram):
- * 1. Shapes with both `x` and `y` keep their authored coordinates.
- * 2. Shapes missing either are auto-placed in a square-ish grid below the
- *    bounding box of the explicitly-positioned shapes.
- * 3. `line`/`arrow` shapes with `from`/`to` (or any shape's `connectsTo`)
- *    become connectors; endpoints that match no sibling id are dropped
- *    (and counted in `warnings`).
- */
-
-/**
- * The shape kinds a drawing can render. `rect`/`circle`/`line` render as a
- * native `ShapeLayer`; everything else (and `path`/`arrow`) renders as a
- * computed `PathLayer` (see `shapeGeometry.ts`). `text` is a `TextLayer`.
- */
-type DrawingShapeKind = 'rect' | 'circle' | 'line' | 'arrow' | 'path' | 'text' | 'triangle' | 'right-triangle' | 'diamond' | 'pentagon' | 'hexagon' | 'octagon' | 'star' | 'star4' | 'star6' | 'parallelogram' | 'trapezoid' | 'plus' | 'chevron' | 'arrow-right' | 'arrow-left' | 'arrow-up' | 'arrow-down' | 'double-arrow' | 'callout' | 'cylinder' | 'cloud' | 'heart' | 'lightning';
-/**
- * Author-facing shape annotation names accepted on a drawing's children
- * (the `{[…]}` token). Shared with validation so an unknown shape gets a
- * "did you mean" suggestion. Aliases (`rectangle`→rect, `ellipse`→circle)
- * are included.
- */
-declare const SHAPE_NAMES: readonly ["rectangle", "rect", "square", "circle", "ellipse", "oval", "line", "arrow", "path", "text", "triangle", "right-triangle", "diamond", "rhombus", "pentagon", "hexagon", "octagon", "star", "star4", "star6", "parallelogram", "trapezoid", "plus", "cross", "chevron", "arrow-right", "arrow-left", "arrow-up", "arrow-down", "double-arrow", "callout", "speech", "cylinder", "cloud", "heart", "lightning", "bolt"];
-/**
- * Resolve a child's `{[…]}` annotation name to a shape kind, or `null`
- * when it isn't a shape. Case-insensitive.
- */
-declare function normalizeShapeKind(name: string | undefined): DrawingShapeKind | null;
-/** True when `name` is an accepted shape annotation (any alias). */
-declare function isShapeName(name: string | undefined): boolean;
-/** A positioned shape in author-defined units (top-left origin). */
-interface DrawingShape {
-    id: string;
-    kind: DrawingShapeKind;
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    /** True when position came from `x=`/`y=`; false when auto-laid out. */
-    pinned: boolean;
-    /** Heading text used as the shape's label ('' when none). */
-    label: string;
-    /** Body text under the heading, used as a sublabel (when present). */
-    sublabel?: string;
-    /** Text content for `text` shapes (`text=` param, else label, else body). */
-    text?: string;
-    /** Raw SVG path `d` for `path` shapes. */
-    d?: string;
-    fill?: string;
-    stroke?: string;
-    strokeWidth?: number;
-    borderRadius?: number;
-    dasharray?: string;
-}
-/** A connector joining two shapes by id. */
-interface DrawingConnector {
-    id: string;
-    kind: 'line' | 'arrow';
-    /** Source shape id (resolved to an existing shape). */
-    from: string;
-    /** Target shape id (resolved to an existing shape). */
-    to: string;
-    /** Optional midpoint label (heading text, or `connectsTo` type). */
-    label?: string;
-    stroke?: string;
-    strokeWidth?: number;
-    dasharray?: string;
-    /** End-of-line markers (default: `arrow` kind → filled arrow at `to`). */
-    startMarker: MarkerStyle;
-    endMarker: MarkerStyle;
-    /** How the line is routed between the two shapes. Default: 'straight'. */
-    routing: ConnectorRouting;
-}
-interface DrawingLayout {
-    shapes: DrawingShape[];
-    connectors: DrawingConnector[];
-    warnings: string[];
-}
-interface DrawingLayoutOptions {
-    /** Horizontal spacing between auto-laid-out shapes. Default: 180. */
-    gapX?: number;
-    /** Vertical spacing between auto-laid-out shapes. Default: 140. */
-    gapY?: number;
-    /** Padding below the explicit bounding box before the grid starts. Default: 80. */
-    gridPad?: number;
-    /** Grid origin when no explicit shapes anchor it. Default: 80, 80. */
-    gridOriginX?: number;
-    gridOriginY?: number;
-}
-/**
- * Compute shapes + connectors for a drawing from its parent block's
- * children. Pure — same inputs always produce the same output.
- */
-declare function computeDrawingLayout(children: readonly Block[], options?: DrawingLayoutOptions): DrawingLayout;
-
-/**
- * Layout block template.
- *
- * Renders the parent block's children as free-form, **absolutely
- * positioned** layers on a canvas (text boxes, shapes, images). Unlike
- * `drawingBlock`, coordinates are used as-is — there is no fit-to-viewport
- * scaling — because a layout is a fixed-canvas composition.
- *
- * Each child is one layer: `### {#id} {[<type> x=.. y=.. …]}`. A text box's
- * content lives in its child body as markdown (see `computeLayoutLayers`).
- * Children render in document order (first child = back-most layer).
- */
-
-declare function layoutBlock(input: TemplateBlock, context: TemplateContext): Layer[];
-
-interface LayoutLayersResult {
-    layers: Layer[];
-    warnings: string[];
-}
-interface LayoutLayerDefaults {
-    /**
-     * Default ink — text color and path/line stroke — used when the author
-     * omits `color=`/`stroke=`. `layoutBlock` passes the theme text color so
-     * un-styled text stays legible on dark themes; the editor's scene canvas
-     * omits it and gets the dark-slate default that suits its fixed light
-     * surface.
-     */
-    ink?: string;
-}
-/** Minimal Block shape this derivation reads (subset of `Block`). */
-interface LayoutChildBlock {
-    id: string;
-    template?: string;
-    templateOverrides?: Record<string, string>;
-    title?: string;
-    contents?: MarkdownNode[];
-}
-/**
- * Map a layout block's children → positioned layers. Pure: same children
- * always produce the same layers.
- */
-declare function computeLayoutLayers(children: readonly LayoutChildBlock[], _viewport: {
-    width: number;
-    height: number;
-}, defaults?: LayoutLayerDefaults): LayoutLayersResult;
-
-/**
- * Accent Image Utility
- *
- * Creates image layers and layout adjustments for accent images on text-based slides.
- * Accent images are tasteful additions that complement text without overwhelming it.
- *
- * Layout patterns:
- * - left-strip: 35% width vertical strip on left, text area shifted to right 65%
- * - right-strip: 35% width vertical strip on right, text area shifted to left 65%
- * - bottom-strip: 35% height horizontal strip at bottom, text area in upper 65%
- * - corner-inset: Small 25% corner image with gradient vignette
- *
- * This is shared code used by both site and efb-app doc renderers.
- */
-
-/**
- * Layout adjustments when an accent image is present.
- * Templates use these values to reposition their text content.
- */
-interface AccentLayout {
-    /** X offset for text center (e.g., '64%' for left-strip) */
-    textCenterX: string;
-    /** Width available for text content */
-    textWidth: string;
-    /** Y offset adjustment for vertical positioning */
-    textYAdjust: number;
-    /** Whether to adjust Y positions (for bottom-strip) */
-    adjustY: boolean;
-}
-/**
- * Default layout when no accent image is present.
- */
-declare const DEFAULT_LAYOUT: AccentLayout;
-/**
- * Get layout adjustments based on accent position.
- */
-declare function getAccentLayout(position: AccentPosition): AccentLayout;
-/**
- * Create layers for an accent image.
- * Returns the image layer and any overlay/gradient layers needed.
- */
-declare function createAccentLayers(accent: AccentImage, slideId: string, treatment?: ImageTreatment): Layer[];
-/**
- * Adjust a Y position value based on accent layout.
- * Used by templates to shift content when bottom-strip is present.
- */
-declare function adjustY(originalY: string | number, layout: AccentLayout): string;
-
-/**
- * Block Template Registry
- *
- * Central registry of all block templates. Provides functions to:
- * - Look up templates by name
- * - Expand template blocks into full Layer arrays
- * - Convert a template-based doc script into a renderable format
- *
- * Supports multiple viewport configurations for different aspect ratios.
- *
- * This is shared code used by both site and efb-app doc renderers.
- */
-
-/**
- * Registry mapping template ids (the strings that appear in
- * `{[name]}` markdown annotations) to their implementation functions.
- *
- * Some implementation functions keep historical "Block" suffixes
- * (`titleBlock`, `quoteBlock`, `mapBlock`, `listBlock`) for source
- * readability — the registry surfaces them under the cleaner short
- * ids (`title`, `quote`, `map`, `list`). {@link TEMPLATE_ALIASES} keeps
- * the legacy long ids resolvable for documents written before the
- * rename.
- *
- * Note: coverBlock is not in the registry as it's used directly for
- * start blocks, not as a regular template in the block sequence.
- */
-declare const templateRegistry: TemplateRegistry;
-/**
- * Back-compat: maps legacy template ids (kept around for documents
- * authored before the "Block" suffix was dropped) to the canonical
- * short ids. Resolved by {@link resolveTemplateName} so both the
- * registry lookup and `hasTemplate()` accept either form.
- */
-declare const TEMPLATE_ALIASES: Readonly<Record<string, string>>;
-/**
- * Resolve a template id through {@link TEMPLATE_ALIASES}. Returns the
- * input unchanged when no alias is registered.
- */
-declare function resolveTemplateName(name: string): string;
-/**
- * Container templates render their parent block by consuming the block's
- * child headings (via `context.children`) — `diagram` draws them as nodes,
- * `drawing` as shapes, `layout` as absolutely-positioned layers. Those
- * children are therefore NOT independently renderable slides/sections;
- * render paths use {@link isContainerTemplate} to skip descending into
- * them (see `flattenRenderableBlocks`).
- */
-declare const CONTAINER_TEMPLATES: ReadonlySet<string>;
-/** True when `name` (or its alias) is a children-consuming container template. */
-declare function isContainerTemplate(name: string | undefined): boolean;
-/**
- * Merge user-defined custom templates onto the built-in registry.
- * Built-in names take precedence on collision — a user can't shadow
- * `title` or `diagram` from a custom definition. Returns a frozen view
- * so callers don't accidentally mutate the global registry.
- */
-type RuntimeTemplateRegistry = Record<string, (input: TemplateBlock, ctx: TemplateContext) => Layer[]>;
-declare function buildRegistry(custom?: readonly CustomTemplateDefinition[]): RuntimeTemplateRegistry;
-/**
- * Expand a template block into a full Block with layers.
- *
- * `registry` lets callers swap in a registry that includes user-defined
- * custom templates. Defaults to the built-in registry when omitted.
- */
-declare function expandTemplateBlock(templateBlock: TemplateBlock, context: TemplateContext, registry?: RuntimeTemplateRegistry): Block;
-/**
- * Audio segment timing info for aligning blocks with audio.
- */
-interface AudioSegmentTiming {
-    /** Start time of this segment in the overall timeline */
-    startTime: number;
-    /** Duration of this segment */
-    duration: number;
-}
-/**
- * Options for expanding doc blocks.
- */
-interface ExpandDocBlocksOptions {
-    /** Theme for template rendering (defaults to DEFAULT_THEME) */
-    theme?: Theme;
-    /** Viewport configuration (defaults to 16:9 landscape) */
-    viewport?: ViewportConfig;
-    /** Persistent layers for visual consistency across blocks */
-    persistentLayers?: PersistentLayerConfig;
-    /**
-     * Audio segment timing information.
-     * When provided, blocks are timed relative to their audio segment's start time,
-     * ensuring proper synchronization with audio playback.
-     */
-    audioSegments?: AudioSegmentTiming[];
-    /**
-     * User-defined custom templates to merge onto the built-in registry
-     * before expanding blocks. Typically passed straight from
-     * `Doc.customTemplates`. Built-in names take precedence on collision.
-     */
-    customTemplates?: readonly CustomTemplateDefinition[];
-}
-declare function expandDocBlocks(blocks: DocBlock[], options?: ExpandDocBlocksOptions): Block[];
-/**
- * Get list of available template names.
- */
-declare function getAvailableTemplates(): string[];
-/**
- * Check if a template exists. Accepts both the canonical short id
- * (`title`, `quote`, `map`, `list`) and legacy aliases
- * (`titleBlock`, `quoteBlock`, `mapBlock`, `listBlock`).
- */
-declare function hasTemplate(name: string): boolean;
-
-/**
- * Animation Utilities
- *
- * Helper functions for mapping Doc animations to CSS classes and styles.
- * Generates the appropriate animation class names and CSS custom properties
- * for duration, delay, and easing.
- *
- * This is shared code used by both site and efb-app doc renderers.
- */
-
-interface AnimationResult {
-    /** CSS class name to apply */
-    className: string;
-    /** Inline styles for CSS custom properties */
-    style: Record<string, string>;
-}
-/**
- * Get CSS class and styles for an animation.
- */
-declare function getAnimationStyle(animation: Animation | undefined, _currentTime?: number): AnimationResult;
-/**
- * Get default duration for an animation type.
- */
-declare function getDefaultAnimationDuration(type: AnimationType): number;
-/**
- * Get transition class for slide entry/exit.
- */
-declare function getTransitionClass(type: TransitionType, entering: boolean, direction?: TransitionDirection): string;
-/**
- * Calculate animation progress (0-1) based on current time.
- */
-declare function getAnimationProgress(animation: Animation, currentTime: number, slideDuration: number): number;
-
-/**
- * Theme Utilities
- *
- * Template-facing helpers that read from the Theme object on the
- * TemplateContext. Templates call these instead of hard-coding style
- * decisions, so the same template code adapts to any theme.
- */
-
-/**
- * Resolve a named color scheme from the theme, with a safe fallback.
- * Templates call this instead of `COLOR_SCHEMES[name]`.
- */
-declare function resolveColorScheme(context: TemplateContext, name: string | undefined): ThemeColorScheme;
-/**
- * Get the theme font family for a given role, resolved to a CSS string.
- * Templates call this to set `fontFamily` on text layers.
- *
- * Theme fields are structured `FontFamily` references (`{ stackId }` or
- * `{ custom: { name, fallback } }`); this helper resolves them to a
- * CSS font-family string with safe fallbacks.
- */
-declare function getThemeFont(context: TemplateContext, role: 'title' | 'body' | 'mono'): string;
-/**
- * Calculate a theme-aware scaled font size.
- * Applies the theme's typography scale multipliers on top of the
- * viewport-based font scale from LayoutStrategy.
- *
- * @param basePx  Base font size designed for 1920×1080
- * @param context Template context (includes fontScale, layout, theme)
- * @param isTitle Whether this is title text (uses titleScale) or body (bodyScale)
- */
-declare function themedFontSize(basePx: number, context: TemplateContext, isTitle?: boolean): number;
-/**
- * Scale an animation duration by the theme's animationSpeed multiplier.
- * A speed of 1.0 returns the base duration unchanged.
- */
-declare function scaleAnimationDuration(baseDuration: number, context: TemplateContext): number;
-/**
- * Get the theme's default animation type for a layer kind.
- * Returns `undefined` when the theme doesn't specify one (template picks its own).
- */
-declare function getDefaultAnimation(context: TemplateContext, layerType: 'text' | 'image'): AnimationType | undefined;
-/**
- * Theme-aware entrance animation for a template layer.
- *
- * The theme's `renderStyle.defaultTextAnimation` / `defaultImageAnimation`
- * overrides the entrance *type*; the template keeps its authored duration,
- * delay, and stagger. Templates opt in per layer:
- *
- * ```ts
- * animation: themedEntrance(context, 'text', { type: 'fadeIn', duration: 2 })
- * ```
- *
- * `slowZoom` is excluded — it's an ambient treatment handled by the
- * `applyRenderStyleToLayers` post-pass, not an entrance.
- */
-declare function themedEntrance(context: TemplateContext, layerType: 'text' | 'image', fallback: Animation): Animation;
-/**
- * Whether the theme defaults to text shadows.
- * Templates should consult this when choosing `shadow: true/false`.
- */
-declare function shouldUseShadow(context: TemplateContext): boolean;
-/**
- * Get the theme's overlay opacity for image-backed blocks.
- */
-declare function getOverlayOpacity(context: TemplateContext): number;
-/**
- * Resolve the effective photographic treatment for a block's imagery.
- *
- * Precedence: the block's `imageTreatment` override ('none' opts out, a
- * type forces that grade) → the theme's `style.imageTreatment` → none.
- * Duotone tints default to the theme primary. Templates pass the result
- * straight into `ImageLayer.content.treatment`.
- */
-declare function themedImageTreatment(context: TemplateContext, override?: 'none' | 'mono' | 'duotone' | 'warm' | 'cool'): ImageTreatment | undefined;
-/**
- * Theme-derived surface gradient for text-first templates.
- *
- * Runs from the theme's alternate surface into a slightly deepened
- * background, staying inside the theme's own hue. Templates must use
- * this instead of hard-coding a dark endpoint (`#0f1520`, `#1e2030`, …):
- * hard-coded navy endpoints made light themes render dark panels and
- * warm themes drift cold halfway down the block.
- */
-declare function themedSurfaceGradient(context: TemplateContext, angleDeg?: number): string;
-/**
- * Translucent overlay tint derived from the theme background, for text
- * bands/scrims painted over imagery. Light themes get a light scrim with
- * dark theme text on top; dark themes get the familiar dark scrim —
- * `theme.colors.text` stays legible on it by construction.
- */
-declare function themedScrim(context: TemplateContext, alpha?: number): string;
-/**
- * Read a per-template hint from the theme's renderStyle.
- * Returns `fallback` when the hint isn't defined.
- *
- * @example
- * ```ts
- * const entrance = getTemplateHint(context, 'statHighlight', 'entrance', 'subtle');
- * ```
- */
-declare function getTemplateHint<T extends string | number | boolean>(context: TemplateContext, templateName: string, key: string, fallback: T): T;
-
-/**
- * Render-style post-pass — applies a theme's mechanical motion defaults to
- * template-generated layers.
- *
- * This is the intent-free half of theme motion (see `themedEntrance` in
- * [themeUtils.ts](./themeUtils.ts) for the intent-bearing half): it never
- * decides *what kind* of entrance a layer gets, only
- *
- *  1. scales existing animation durations/delays by the theme's
- *     `style.animationSpeed` multiplier (1.4 = calmer/slower, 0.7 = snappier,
- *     1.0 = no-op), and
- *  2. gives full-bleed cover imagery with no authored animation a gentle,
- *     deterministic Ken Burns when the theme opts into ambient motion.
- *
- * Applied ONLY to template-generated layers — raw authored `block.layers`
- * are never touched, and an explicit `animation` (including
- * `{ type: 'none' }`) always wins.
- */
-
-/**
- * Whether the theme asks for ambient Ken Burns on otherwise-static imagery.
- * `defaultImageAnimation: 'slowZoom'` is treated as an alias for the boolean
- * (that's what themes authoring it were reaching for).
- */
-declare function themeWantsAmbientMotion(theme: Theme): boolean;
-/**
- * Apply the theme's mechanical motion defaults to a block's
- * template-generated layers. Pure: returns new layer objects where a change
- * applies and the original objects where none does.
- *
- * @param layers Template-generated layers (never raw authored layers)
- * @param block  The source block — supplies the ambient-motion seed and duration
- * @param theme  Resolved theme
- */
-declare function applyRenderStyleToLayers(layers: Layer[], block: {
-    id: string;
-    duration?: number;
-}, theme: Theme): Layer[];
-
-/**
- * Image treatment → CSS filter derivation.
- *
- * Treatments are theme-level photographic grades (see `ImageTreatment` in
- * [Doc.ts](../../schemas/Doc.ts)). They compile to plain CSS `filter`
- * functions so the same string works on a foreignObject `<img>`, an SVG
- * `<image>` element, and in headless frame capture — no SVG filter defs to
- * coordinate, no renderer-specific code paths.
- */
-
-/**
- * Build the CSS `filter` value for a treatment and/or blur.
- * Returns `undefined` when there is nothing to apply.
- */
-declare function cssFilterForTreatment(treatment?: ImageTreatment, blur?: number): string | undefined;
-
-/**
- * Template input derivation — build a template's required inputs from a
- * block's heading + markdown body.
- *
- * Used by:
- * - `markdownToDoc`'s content-aware auto template picking, so an
- *   auto-picked `quote`/`statHighlight`/`leftFeature` block carries the
- *   inputs its template needs through every render path (player, linear
- *   view, exports).
- * - `LinearDocView` / editor previews, to render annotated blocks whose
- *   authors didn't spell out every template param.
- *
- * Two modes:
- * - strict (default): returns `null` when an essential input can't be
- *   derived (no image for a feature block, no table for dataTable…) —
- *   auto-picking uses this to fall back to the structural default.
- * - placeholders: returns visible placeholder values instead of failing —
- *   preview surfaces use this so a half-authored block still renders.
- */
-
-/** First image discovered in a block's body, with explicit dimensions when present. */
-interface FirstImage {
-    src: string;
-    alt: string;
-    width?: number;
-    height?: number;
-}
-/** Plain text of a block's body contents (excluding the heading). */
-declare function extractBodyPlainText(contents?: MarkdownBlockNode[]): string;
-/** Extract list items as plain text. */
-declare function extractListItems(contents?: MarkdownBlockNode[]): string[];
-/**
- * Find images referenced anywhere in block contents — both markdown
- * shorthand `![alt](url)` (type `image`) and raw HTML `<img>` tags
- * (type `htmlBlock`/`htmlInline`). The WYSIWYG editor emits the HTML form
- * whenever a user resizes an image, so missing that path silently breaks
- * every resized image.
- *
- * @param limit Stop after this many images (default: all).
- */
-declare function extractImages(contents: MarkdownBlockNode[] | undefined, limit?: number): FirstImage[];
-/** First image in a block's body, or null. */
-declare function extractFirstImage(contents: MarkdownBlockNode[] | undefined): FirstImage | null;
-/** Extract table data (headers, rows, alignment) from block contents. */
-declare function extractTableFromContents(contents?: MarkdownBlockNode[]): {
-    headers: string[];
-    rows: string[][];
-    align?: (('left' | 'right' | 'center') | null)[];
-} | null;
-/** First blockquote's plain text, or ''. */
-declare function extractBlockquoteText(contents?: MarkdownBlockNode[]): string;
-interface DeriveTemplateInputsOptions {
-    /**
-     * Return visible placeholder values instead of `null` when an essential
-     * input can't be derived (preview surfaces). Default false (strict).
-     */
-    placeholders?: boolean;
-}
-/**
- * Derive a template's inputs from a block's heading text and body nodes.
- * Returns the input fields to merge onto the block, or `null` in strict
- * mode when an essential input is missing.
- */
-declare function deriveTemplateInputs(templateName: string, headingText: string, contents: MarkdownBlockNode[] | undefined, options?: DeriveTemplateInputsOptions): Record<string, unknown> | null;
-
-/**
- * Markdown → Doc Conversion
- *
- * Converts a MarkdownDocument into a hierarchical Doc whose Block tree
- * mirrors the heading structure of the markdown. Every heading (H1–H6)
- * becomes a Block; body content between headings populates `contents`;
- * sub-headings nest as `children`.
- *
- * This enables using BlockTemplates to supply alternate visualizations
- * for each section of a markdown document.
- *
- * @example
- * ```ts
- * import { parseMarkdown } from '@bendyline/squisq/markdown';
- * import { markdownToDoc } from '@bendyline/squisq/doc';
- *
- * const md = parseMarkdown('# Intro\n\nHello world\n\n## Details\n\nMore text');
- * const doc = markdownToDoc(md);
- * // doc.blocks[0].sourceHeading.depth === 1  ("# Intro")
- * // doc.blocks[0].contents  → [paragraph("Hello world")]
- * // doc.blocks[0].children[0].sourceHeading.depth === 2  ("## Details")
- * ```
- */
-
-/**
- * Options for markdownToDoc().
- */
-interface MarkdownToDocOptions {
-    /** Article ID for the generated Doc. Default: 'markdown-doc' */
-    articleId?: string;
-    /** Default template name for heading blocks. Default: 'sectionHeader' */
-    defaultTemplate?: string;
-    /** Default duration per block in seconds. Default: 5 */
-    defaultDuration?: number;
-    /** Custom ID generator. Receives the heading node and its index. */
-    generateId?: (heading: MarkdownHeading, index: number) => string;
-    /**
-     * Whether to auto-generate a cover startBlock from the first H1 heading.
-     * When true (default), a StartBlockConfig is created using the first H1's
-     * text as the title. If the document contains an image, the first image
-     * is used as the hero. Set to false to suppress automatic cover generation.
-     */
-    generateCoverBlock?: boolean;
-    /**
-     * Timestamp recorded as `captions.generatedAt`. When omitted, the field
-     * is left unset so that conversion is fully deterministic — the same
-     * markdown always converts to an identical Doc (important for snapshot
-     * tests, caching, and agents that verify their output by re-converting).
-     */
-    captionsGeneratedAt?: string;
-    /**
-     * Content-aware template auto-picking for unannotated headings
-     * (default: true). When a heading block carries a strong content signal
-     * — a table, images, a blockquote, a list, a stat-looking line — the
-     * matching template is applied (with inputs derived from the body)
-     * instead of the structural `defaultTemplate`. Explicit `{[template]}`
-     * annotations always win. Authors can also disable per document with
-     * frontmatter `squisq-auto-templates: false`.
-     */
-    autoTemplates?: boolean;
-}
-declare function markdownToDoc(markdownDoc: MarkdownDocument, options?: MarkdownToDocOptions): Doc;
-/**
- * Flatten a nested block tree into a depth-first ordered array.
- * Useful for calculating sequential timing or iterating all blocks.
- */
-declare function flattenBlocks(blocks: Block[]): Block[];
-/**
- * Flatten the block tree into the list of *independently renderable*
- * blocks — like {@link flattenBlocks}, but it does NOT descend into the
- * children of a container template (`diagram`, `drawing`; see
- * `isContainerTemplate`). Those children are consumed by the parent's
- * render (as nodes / shapes), so they must not also surface as their own
- * slides or sections.
- *
- * Use this anywhere a doc is flattened for rendering (slideshow, video,
- * static pages). Use {@link flattenBlocks} when you genuinely need every
- * block regardless of role — validation, timing, duplicate-id checks.
- */
-declare function flattenRenderableBlocks(blocks: Block[]): Block[];
-/**
- * Count the total number of blocks in a nested tree (including children at all levels).
- */
-declare function countBlocks(blocks: Block[]): number;
-/**
- * Get the heading depth for a block. Returns 0 for preamble blocks (no heading).
- */
-declare function getBlockDepth(block: Block): number;
-
-/**
- * Doc → Markdown Conversion
- *
- * Converts a Doc with a heading-driven Block hierarchy back into a
- * MarkdownDocument. This is the reverse of markdownToDoc() and enables
- * round-tripping: edit a Doc's block tree, then serialize back to markdown.
- *
- * **Algorithm:**
- * Walk the block tree depth-first. For each block:
- * 1. If it has a `sourceHeading`, emit that heading node
- * 2. Emit all nodes in `contents`
- * 3. Recurse into `children`
- *
- * @example
- * ```ts
- * import { markdownToDoc, docToMarkdown } from '@bendyline/squisq/doc';
- * import { parseMarkdown, stringifyMarkdown } from '@bendyline/squisq/markdown';
- *
- * const md = '# Hello\n\nWorld\n';
- * const doc = markdownToDoc(parseMarkdown(md));
- * const roundTripped = stringifyMarkdown(docToMarkdown(doc));
- * ```
- */
-
-/**
- * Convert a Doc with heading-driven blocks back to a MarkdownDocument.
- *
- * Walks the block tree depth-first, emitting heading nodes and contents
- * in document order. Blocks without a `sourceHeading` (preamble blocks)
- * emit only their contents.
- *
- * If a block has a `template` or `templateOverrides` that aren't already
- * reflected in the heading's `templateAnnotation`, the annotation is
- * injected so the round-trip preserves template assignments.
- *
- * @param doc - A Doc whose blocks may have `sourceHeading`, `contents`, and `children`
- * @returns A MarkdownDocument that can be stringified back to markdown
- */
-declare function docToMarkdown(doc: Doc): MarkdownDocument;
-
-/**
- * Frontmatter serialization for user-defined custom templates (layouts).
- *
- * Custom template definitions live in the document's YAML frontmatter
- * under the key `squisq-custom-templates`. They're stored as a single
- * **compact JSON** object keyed by template name:
- *
- * ```yaml
- * squisq-custom-templates: {"hero":{"lb":"Hero Section","ly":[{"ty":"text",…}]}}
- * ```
- *
- * Squisq's frontmatter parser is line-based; a JSON object literal
- * round-trips through it verbatim (no leading quote to strip, single
- * line), so the value is written **unquoted** and stays human-readable
- * and diffable — important for a codebase edited by people and agents.
- *
- * The JSON is kept small by:
- *   - keying definitions by `name` (drops the `name` field + array wrapper),
- *   - omitting the viewport when it's the 1920×1080 default,
- *   - renaming well-known property names to two-letter codes via
- *     {@link LONG_TO_SHORT} (e.g. `fontSize` → `fz`).
- *
- * The rename is a generic, recursive, bijective pass: **any property not
- * in the map passes through unchanged**, so the format is lossless even
- * as the Layer schema grows — new fields are simply stored under their
- * full name until (optionally) added to the map.
- *
- * Back-compat: the reader still accepts the historical base64-of-JSON
- * payload and a structured array, so older documents load unchanged.
- * The first save migrates them to the compact form.
- *
- * The `encodeLayersForFrontmatter` / `decodeLayersFromFrontmatter` pair
- * handles a single Layer array for the editor's `dataLayers="…"` Pandoc
- * param path; that path stays base64 (it's a different, per-block
- * mechanism) and is re-exported here for locality.
- */
-
-/**
- * Base64-encode a Layer array as JSON, UTF-8 safe. Used by the editor's
- * per-block `dataLayers="…"` Pandoc param (not the doc-level template
- * list, which uses the compact JSON above).
- *
- * `btoa` only accepts Latin1 strings — any character outside that range
- * (e.g. an em-dash in a description) throws — so we round through
- * `TextEncoder`. Works in Node ≥18 and browsers.
- */
-declare function encodeLayersForFrontmatter(layers: readonly Layer[]): string;
-/** Inverse of {@link encodeLayersForFrontmatter}. Returns [] on parse failure. */
-declare function decodeLayersFromFrontmatter(encoded: string): Layer[];
-/**
- * Read the `squisq-custom-templates` frontmatter key and decode it into
- * an array of CustomTemplateDefinitions. Returns undefined when the key
- * is absent or unparseable so callers can omit the field from the Doc.
- *
- * Accepts, in order: the compact JSON object (current), a base64-JSON
- * string (legacy), and an already-structured array/object (in case a
- * richer YAML parser delivers it). Malformed payloads return undefined
- * rather than failing the whole doc load.
- */
-declare function readCustomTemplatesFromFrontmatter(frontmatter: Record<string, unknown> | undefined): CustomTemplateDefinition[] | undefined;
-/**
- * Encode a list of custom template definitions into the compact JSON
- * object described in the module header. Returns undefined when the
- * input list is empty so callers can leave the key off the output.
- */
-declare function writeCustomTemplatesToFrontmatter(templates: readonly CustomTemplateDefinition[] | undefined, options?: {
-    pretty?: boolean;
-}): string | undefined;
-
-/**
- * Frontmatter serialization for user-defined custom themes.
- *
- * The theme analog of {@link ./customTemplatesFrontmatter.ts}. Custom Theme
- * definitions live in the document's YAML frontmatter under the key
- * `squisq-custom-themes`, stored as a single **compact JSON** object keyed
- * by theme id:
- *
- * ```yaml
- * squisq-custom-themes: {"my-brand":{"schemaVersion":"1","id":"my-brand",…}}
- * ```
- *
- * Squisq's frontmatter parser is line-based; a JSON object literal
- * round-trips through it verbatim (single line, no leading quote to strip),
- * so the value is written **unquoted** and stays human-readable and diffable
- * — the same mechanism the custom-templates codec relies on.
- *
- * Only one theme is *active* per doc (selected by id via the `squisq-theme`
- * frontmatter key / `Doc.themeId`), but the payload is a keyed map — parallel
- * to custom templates — so a doc can carry a small catalog and switch between
- * them, and `resolveThemeForDoc` can resolve any of them doc-scoped.
- *
- * Malformed entries are dropped (via `validateTheme`) rather than failing the
- * whole doc load, matching the tolerant behavior of the templates reader.
- */
-
-/**
- * Read the custom themes inlined into a document's frontmatter. Returns
- * undefined when the key is absent or holds no valid theme, so callers can
- * omit the field from the Doc.
- */
-declare function readCustomThemesFromFrontmatter(frontmatter: Record<string, unknown> | undefined): Theme[] | undefined;
-/**
- * Encode a list of custom themes into the compact JSON object described in
- * the module header (keyed by theme id). Returns undefined when the input is
- * empty so callers can leave the key off the output.
- */
-declare function writeCustomThemesToFrontmatter(themes: readonly Theme[] | undefined, options?: {
-    pretty?: boolean;
-}): string | undefined;
-
-/**
- * Doc-scoped theme resolution.
- *
- * The theme analog of how `buildRegistry` resolves custom templates: pure and
- * doc-scoped, with no global state. `resolveThemeForDoc` looks up the active
- * theme id in the doc's own custom themes first, then falls back to the
- * built-in / globally-registered themes via `resolveTheme`.
- *
- * It accepts either a squisq `Doc` (which carries a typed `customThemes`
- * array) or anything with raw `frontmatter` — notably a `MarkdownDocument`,
- * which is the shape every export pipeline pivots through. In the latter case
- * the inline themes are decoded from the `squisq-custom-themes` frontmatter
- * payload. Either way, resolution needs no `registerTheme` call — an inline
- * custom theme ships with the doc, exactly like custom templates.
- */
-
-/**
- * The minimal shape `resolveThemeForDoc` needs. Satisfied by both the squisq
- * `Doc` (typed `customThemes` + `themeId`) and a `MarkdownDocument` (raw
- * `frontmatter` carrying the encoded payload).
- */
-interface ThemeResolvable {
-    themeId?: string;
-    customThemes?: Theme[];
-    frontmatter?: Record<string, unknown>;
-}
-/**
- * Resolve the Theme a document should render with.
- *
- * @param doc - the document (may carry inline custom themes plus a `themeId`
- *   / `squisq-theme` frontmatter selector).
- * @param explicitId - an id that overrides the doc's own selection (e.g. the
- *   editor's theme dropdown, or an export `--theme` option). When omitted, the
- *   doc's `themeId` / frontmatter theme id is used.
- * @returns the matching inline custom theme (doc-scoped) when present, else
- *   the built-in / registered theme for that id, else the default theme.
- */
-declare function resolveThemeForDoc(doc: ThemeResolvable | null | undefined, explicitId?: string): Theme;
-
-/**
- * getLayers — Compute visual layers for a block on demand.
- *
- * This is the preferred way to obtain renderable layers for a block.
- * Instead of storing pre-computed layers on the Block object, call
- * `getLayers(block, context)` to derive them from the block's template
- * name, content, and the current render context (theme, viewport, etc.).
- *
- * For raw blocks that already carry a `layers` array, those layers are
- * returned directly (with optional persistent layer injection).
- *
- * @example
- * ```ts
- * import { getLayers } from '@bendyline/squisq/doc';
- *
- * const layers = getLayers(block, {
- *   theme: DEFAULT_THEME,
- *   viewport: VIEWPORT_PRESETS.landscape,
- *   blockIndex: 0,
- *   totalBlocks: 10,
- * });
- * ```
- */
-
-/**
- * Context needed to compute layers for a block.
- *
- * Captures the visual rendering parameters: theme colors, viewport
- * configuration, persistent layers, and the block's position within
- * the doc (for template functions that vary output by index).
- */
-interface RenderContext {
-    /** Theme for template rendering. Defaults to DEFAULT_THEME (documentary). */
-    theme?: Theme;
-    /** Target viewport configuration. Defaults to 16:9 landscape. */
-    viewport?: ViewportConfig;
-    /** Persistent layers injected behind and/or on top of all block content. */
-    persistentLayers?: PersistentLayerConfig;
-    /** 0-based index of this block in the sequence. Defaults to 0. */
-    blockIndex?: number;
-    /** Total number of blocks in the doc. Defaults to 1. */
-    totalBlocks?: number;
-}
-/**
- * Compute the visual layers for a block.
- *
- * Resolution order:
- * 1. If the block already has a non-empty `layers` array, use it (raw block).
- * 2. If the block has a `template` name that exists in the registry,
- *    call the template function to generate layers.
- * 3. Otherwise return an empty array.
- *
- * Persistent layers (bottom/top) from the render context are injected
- * around the result unless the block opts out via `useBottomLayer: false`
- * or `useTopLayer: false`.
- *
- * @param block   A Block or TemplateBlock to render.
- * @param context Render context (theme, viewport, persistent layers, position).
- * @returns The computed Layer[] for the block, ready for BlockRenderer.
- */
-declare function getLayers(block: DocBlock, context?: RenderContext): Layer[];
-
-/**
- * Audio Mapping
- *
- * Associates audio segments (MP3 files) with document blocks.
- * Supports two modes:
- *
- * 1. **Explicit annotation**: Blocks with `{[audio=filename.mp3]}` in their
- *    heading annotation are directly mapped to that audio file.
- *
- * 2. **Auto-matching**: When no annotations exist but the container has MP3s
- *    with `.timing.json` files, matches MP3s to blocks by comparing the
- *    timing.json `sourceText` against block text content (word overlap).
- *    Falls back to filename-based matching (slugified title comparison).
- */
-
-/**
- * Calculate Jaccard similarity between two texts (word overlap).
- * Returns 0–1 where 1 = identical word sets.
- */
-declare function scoreTextSimilarity(a: string, b: string): number;
-/**
- * Resolve audio mapping for a Doc using a ContentContainer.
- *
- * Tries explicit `{[audio=filename.mp3]}` annotations first,
- * then falls back to auto-matching by content similarity.
- *
- * Returns a new Doc with `audio.segments` populated and blocks
- * assigned to the correct `audioSegment` indices.
- *
- * @param doc - The source Doc (not mutated).
- * @param container - ContentContainer with MP3 and timing files.
- * @returns New Doc with audio segments resolved, or original doc if no matches.
- */
-declare function resolveAudioMapping(doc: Doc, container: ContentContainer): Promise<Doc>;
-
-/**
- * Structured template data from markdown body content.
- *
- * Attribute strings on a heading annotation are fine for scalar params,
- * but tabular or nested inputs (dataTable rows, map markers, chart data)
- * don't pack well into a single quoted line. This module supplies the two
- * structured channels instead:
- *
- * 1. **Data fences** — a fenced code block whose info string is
- *    `json data` or `yaml data`, placed in a heading's body content:
- *
- *    ````markdown
- *    ## Quarterly numbers {[dataTable]}
- *
- *    ```json data
- *    { "headers": ["Q", "Revenue"], "rows": [["Q1", "1.2M"], ["Q2", "1.4M"]] }
- *    ```
- *    ````
- *
- *    The parsed object lands on `block.templateData` and merges into the
- *    template input (after defaults, before `{[…]}` string overrides).
- *    The `data` marker keeps ordinary ```json code samples — which should
- *    render as code — out of the template input.
- *
- * 2. **GFM tables** — for the `dataTable` template, the first table in the
- *    section body supplies `headers` / `rows` / `align` when the author
- *    didn't provide them explicitly.
- *
- * YAML support is a documented subset (this package has no YAML
- * dependency): top-level `key: scalar`, `key: [inline, array]`, `key:`
- * followed by an indented `- item` block sequence (scalars or inline
- * arrays), and `key:` followed by *one level* of indented `subkey: scalar`
- * lines (a nested map, e.g. `center:` + indented `lat:` / `lng:`). Deeper
- * nesting, and mixing list items with mapping keys under one key, are
- * rejected with a clear error — use a `json data` fence for those.
- */
-
-/**
- * Whether a code block is a structured-data fence: lang `json`/`yaml`/`yml`
- * with the word `data` in the fence meta (` ```json data `).
- */
-declare function isDataFence(node: MarkdownCodeBlock): boolean;
-interface DataFenceParseResult {
-    /** Parsed key→value map. Undefined when parsing failed. */
-    data?: Record<string, unknown>;
-    /** Parse failure description. Undefined when parsing succeeded. */
-    error?: string;
-}
-/**
- * Parse a data fence's content into a key→value map. JSON fences must
- * contain a top-level object (arrays have no key to merge under); YAML
- * fences are parsed with {@link parseYamlSubset}.
- */
-declare function parseDataFence(node: MarkdownCodeBlock): DataFenceParseResult;
-/**
- * Return a new contents array with the first data fence's code content
- * replaced by `data` (pretty-printed JSON). The fence node keeps its
- * language and `data` marker; only `value` changes. When no data fence
- * exists, a new ` ```json data ` fence is appended instead.
- *
- * Pure: neither `contents` nor its nodes are mutated. This is the write
- * half of the data-fence channel — editors update `block.templateData`
- * and call this to reflect the change back into `block.contents`.
- */
-declare function replaceDataFence(contents: MarkdownBlockNode[], data: Record<string, unknown>): MarkdownBlockNode[];
-/**
- * Parse the supported YAML subset (see module doc) into a key→value map.
- * Throws an Error with a line-anchored message on anything outside the
- * subset, so callers can surface a precise diagnostic.
- */
-declare function parseYamlSubset(src: string): Record<string, unknown>;
-interface ExtractedTableData {
-    headers: string[];
-    rows: string[][];
-    align?: (('left' | 'right' | 'center') | null)[];
-}
-/** Find the first GFM table among a block's body contents. */
-declare function findFirstTable(contents: MarkdownBlockNode[] | undefined): MarkdownTable | undefined;
-/**
- * Extract `headers` / `rows` / `align` (the `dataTable` input shape) from a
- * GFM table node. The first row is the header row.
- */
-declare function extractTableData(table: MarkdownTable): ExtractedTableData;
-
-/**
- * Markdown document validation.
- *
- * `validateMarkdownSource()` gives authors and agents fast, structural
- * feedback on a squisq markdown document — the same checks the renderer
- * applies, surfaced as diagnostics instead of degraded slides:
- *
- * - unknown template names (with a did-you-mean suggestion)
- * - unknown drawing shapes, and shape annotations used outside a `{[drawing]}`
- * - `{[…]}` text that was not recognized as an annotation (bad quoting,
- *   non-heading placement, unknown inline icon)
- * - malformed heading-attribute values (`x=abc`, bad `startTime`) and
- *   non-numeric drawing-shape geometry
- * - `connectsTo` / drawing `from`/`to` targets that don't resolve,
- *   duplicate block ids, unparseable data fences (reported by `markdownToDoc`)
- * - image references missing from the provided asset set (.dbk contents)
- *
- * The CLI exposes this as `squisq validate <input>`; agents can also call
- * it directly and iterate until the diagnostics list is empty.
- */
-
-interface ValidateOptions {
-    /**
-     * Known asset paths for image/video reference checks — typically the
-     * file list of a .dbk container or the document's folder. Relative
-     * references not present here produce a `missing-asset` warning.
-     * When omitted, asset checks are skipped.
-     */
-    assets?: ReadonlySet<string> | ((path: string) => boolean);
-    /**
-     * Additional template names to accept beyond the built-in registry and
-     * the document's own `customTemplates` (e.g. app-registered templates).
-     */
-    extraTemplates?: readonly string[];
-}
-interface MarkdownValidationResult {
-    /** All findings, in source order where line information exists. */
-    diagnostics: DocDiagnostic[];
-    errorCount: number;
-    warningCount: number;
-    infoCount: number;
-    /** The converted Doc (conversion diagnostics are included above). */
-    doc: Doc;
-}
-/**
- * Validate a squisq markdown source string. Parses, converts (collecting
- * the conversion's own diagnostics), and runs the structural checks above.
- */
-declare function validateMarkdownSource(source: string, options?: ValidateOptions): MarkdownValidationResult;
-/**
- * Validate an already-parsed MarkdownDocument. See {@link validateMarkdownSource}.
- */
-declare function validateMarkdownDoc(markdownDoc: MarkdownDocument, options?: ValidateOptions): MarkdownValidationResult;
-
-/**
- * Fallback Block Rendering
- *
- * The graceful-degradation guarantee: a block whose template can't render —
- * unknown template name, template function threw, or returned a non-array —
- * still renders its heading and body text as a plain, readable card instead
- * of a blank slide. A small notice line names the problem so authors (and
- * agents reviewing screenshots) can see *why* the block degraded.
- *
- * This is intentionally not a registered template: it can't be requested by
- * name, only reached when a requested template fails. See `getLayers()`.
- */
-
-/**
- * Render a block's heading + body text as plain layers, with a notice line
- * describing why the requested template didn't render.
- *
- * @param block   The block that failed to render via its template.
- * @param context Template context (theme, viewport).
- * @param notice  Short problem description, e.g. `Unknown template "photGrid"`.
- */
-declare function fallbackBlockLayers(block: DocBlock, context: TemplateContext, notice: string): Layer[];
-
-/**
- * Template input descriptors — a typed catalog of the inline `{[…]}` params
- * each built-in template understands, plus the pure coercion + lint logic
- * that consumes it.
- *
- * Two jobs, one source of truth:
- *
- * - **Coercion (`coerceTemplateParams`)** turns a flat `key → raw string`
- *   param map (from a `{[name key=value]}` annotation, always strings) into a
- *   partial typed input the template functions can consume directly — e.g.
- *   `center="47.6,-122.3"` → `{ lat: 47.6, lng: -122.3 }`, `zoom=9` → `9`.
- *   This is what makes `{[map center="47.6,-122.3" zoom=9]}` render with no
- *   changes to any template function. Unknown keys ALWAYS pass through
- *   untouched (as strings), so coercion is never lossy; coercion failures are
- *   returned as `warnings` and the raw string is preserved.
- *
- * - **Linting (`lintTemplateParams`)** checks a param map against the
- *   descriptors and reports unknown keys (with a did-you-mean suggestion),
- *   values outside a closed enum / that fail coercion, and missing required
- *   inputs. The document validator surfaces these as diagnostics.
- *
- * This mirrors the proven block-meta descriptor pattern in
- * `markdown/annotationCoercion.ts` (`BLOCK_META_KEY_DESCRIPTORS`), extended
- * from block geometry/timing to per-template content inputs.
- *
- * The descriptors are the `{[…]}` counterpart of the template input
- * interfaces in `schemas/BlockTemplates.ts` — only keys/enums that provably
- * exist on those interfaces are declared. Keys that can't be meaningfully
- * expressed as a single inline string (e.g. a `dataTable`'s `rows`) are still
- * declared with `coerce: 'string'` so they aren't mis-flagged as unknown.
- */
-/** How a raw `{[…]}` param string is coerced into a typed input value. */
-type InputCoercion = 'string' | 'number' | 'boolean' | 'latLng' | 'labeledPair' | 'stringList';
-/**
- * Editor/validator-facing description of a single template input key: what it
- * does, how to coerce its raw string, and either its closed set of valid
- * values or a free-form format hint. `values`/`valueHint` are mutually
- * exclusive (a key has a closed enum OR a hint, not both).
- */
-interface TemplateInputDescriptor {
-    /** The `{[name key=…]}` param key, matching the template input interface. */
-    key: string;
-    /** One-line description of the input. */
-    description: string;
-    /** Coercion strategy for the raw string (default `'string'`). */
-    coerce?: InputCoercion;
-    /** Closed set of valid values, for keys backed by an enum. */
-    values?: readonly string[];
-    /** Format hint shown when the value is free-form (no closed set). */
-    valueHint?: string;
-    /** When true, the validator warns if the key is absent and can't be derived. */
-    required?: boolean;
-}
-/** A single lint finding produced by {@link lintTemplateParams}. */
-interface TemplateParamFinding {
-    kind: 'unknown-input' | 'invalid-input-value' | 'missing-input';
-    key: string;
-    message: string;
-    /** Did-you-mean candidate (for `unknown-input`). */
-    suggestion?: string;
-}
-/**
- * Inputs shared by every template via `BaseTemplateBlock`. Merged into each
- * template's known-key set for coercion + lint. Block-level timing/geometry
- * keys (`duration`, `x`, `y`, …) are NOT here — those stay owned by the
- * block-meta registry (`KNOWN_BLOCK_META_KEYS`) and are folded into the lint
- * known-key set separately.
- */
-declare const BASE_INPUT_DESCRIPTORS: readonly TemplateInputDescriptor[];
-/**
- * Per-template input descriptors, keyed by canonical template id. A template
- * absent from this map has no descriptors and is exempt from lint (custom
- * templates and not-yet-described built-ins).
- */
-declare const TEMPLATE_INPUT_DESCRIPTORS: Readonly<Record<string, readonly TemplateInputDescriptor[]>>;
-/**
- * Coerce a flat `{[…]}` param map into a partial typed template input.
- *
- * Known descriptor keys are coerced per their `coerce` strategy; unknown keys
- * (and `string`-typed keys) pass through unchanged. A coercion failure leaves
- * the raw string in place and adds a human-readable `warnings` entry — the
- * output is never lossy. Returns a fresh object; the caller must NOT feed
- * `templateOverrides` back in — only the ephemeral merged input is coerced.
- */
-declare function coerceTemplateParams(template: string | undefined, params: Record<string, string>): {
-    input: Record<string, unknown>;
-    warnings: string[];
-};
-/**
- * Lint a template's `{[…]}` params against its descriptors. Returns findings
- * for unknown keys, values outside a closed enum / that fail coercion, and
- * missing required inputs. Templates without descriptors (custom or
- * not-yet-described built-ins) return `[]`.
- */
-declare function lintTemplateParams(template: string, params: Record<string, string>): TemplateParamFinding[];
-
-export { type AccentLayout, type AudioSegmentTiming, BASE_INPUT_DESCRIPTORS, CONTAINER_TEMPLATES, type ClipBox, type ConnectorPort, type ConnectorRouting, type ConnectorSnapPoint, type CoverBlockInput, DEFAULT_LAYOUT, type DataFenceParseResult, type DeriveTemplateInputsOptions, type DiagramEdge, type DiagramLayout, type DiagramLayoutOptions, type DiagramNodePosition, DocBlock, type DocStylePreset, type DrawingConnector, type DrawingLayout, type DrawingLayoutOptions, type DrawingShape, type DrawingShapeKind, type ExpandDocBlocksOptions, type ExtractedTableData, type FirstImage, type InputCoercion, type LayoutLayerDefaults, type LayoutLayersResult, type MarkdownToDocOptions, type MarkdownValidationResult, PATH_SHAPE_KINDS, PersistentLayerConfig, type RenderContext, type RuntimeTemplateRegistry, SHAPE_NAMES, TEMPLATE_ALIASES, TEMPLATE_INPUT_DESCRIPTORS, TEMPLATE_METADATA, TemplateBlock, TemplateContext, type TemplateInputDescriptor, type TemplateMetadata, type TemplateParamFinding, Theme, ThemeColorScheme, type ValidateOptions, ViewportConfig, adjustY, applyRenderStyleToLayers, buildRegistry, clipEndpoints, clipPoint, coerceTemplateParams, comparisonBar, computeDiagramLayout, computeDrawingLayout, computeLayoutLayers, connectorPath, countBlocks, coverBlock, createAccentLayers, cssFilterForTreatment, dataTable, dateEvent, decodeLayersFromFrontmatter, definitionCard, deriveTemplateInputs, diagramBlock, docToMarkdown, drawingBlock, encodeLayersForFrontmatter, expandCoverBlock, expandDocBlocks, expandPersistentLayers, expandTemplateBlock, extractBlockquoteText, extractBodyPlainText, extractFirstImage, extractImages, extractListItems, extractTableData, extractTableFromContents, factCard, fallbackBlockLayers, findFirstTable, flattenBlocks, flattenRenderableBlocks, fullBleedQuote, getAccentLayout, getAnimationProgress, getAnimationStyle, getAvailableTemplates, getBlockDepth, getDefaultAnimation, getDefaultAnimationDuration, getDocStyleConfig, getLayers, getOverlayOpacity, getPersistentLayersFromTheme, getTemplateHint, getThemeFont, getTransitionClass, hasTemplate, imageWithCaption, isContainerTemplate, isDataFence, isShapeName, layoutBlock, leftFeature, lineStyleDasharray, lintTemplateParams, listBlock, mapBlock, markdownToDoc, markerPath, nearestSnapPoint, normalizeShapeKind, parseDataFence, parseYamlSubset, photoGrid, pullQuote, quoteBlock, readCustomTemplatesFromFrontmatter, readCustomThemesFromFrontmatter, replaceDataFence, resolveAudioMapping, resolveColorScheme, resolvePersistentLayers, resolveTemplateName, resolveThemeForDoc, rightFeature, scaleAnimationDuration, scoreTextSimilarity, sectionHeader, shapePath, shouldUseShadow, snapEndpoints, snapPoints, statHighlight, templateRegistry, themeWantsAmbientMotion, themedEntrance, themedFontSize, themedImageTreatment, themedScrim, themedSurfaceGradient, titleBlock, twoColumn, validateMarkdownDoc, validateMarkdownSource, videoPullQuote, videoWithCaption, wrapWithPersistentLayers, writeCustomTemplatesToFrontmatter, writeCustomThemesToFrontmatter };