@bendyline/squisq 1.5.2 → 2.0.0

package/dist/doc/index.d.ts

@@ -1,5 +1,2334 @@
-export { AccentLayout, AudioSegmentTiming, BASE_INPUT_DESCRIPTORS, CONTAINER_TEMPLATES, ClipBox, ConnectorPort, ConnectorRouting, ConnectorSnapPoint, CoverBlockInput, DEFAULT_LAYOUT, DataFenceParseResult, DeriveTemplateInputsOptions, DiagramEdge, DiagramLayout, DiagramLayoutOptions, DiagramNodePosition, DocStylePreset, DrawingConnector, DrawingLayout, DrawingLayoutOptions, DrawingShape, DrawingShapeKind, ExpandDocBlocksOptions, ExtractedTableData, FirstImage, InputCoercion, LayoutLayerDefaults, LayoutLayersResult, MarkdownToDocOptions, MarkdownValidationResult, PATH_SHAPE_KINDS, RenderContext, RuntimeTemplateRegistry, SHAPE_NAMES, TEMPLATE_ALIASES, TEMPLATE_INPUT_DESCRIPTORS, TEMPLATE_METADATA, TemplateInputDescriptor, TemplateMetadata, TemplateParamFinding, ValidateOptions, 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 } from '../story/index.js';
-export { D as DEFAULT_THEME, g as getAvailableThemes, b as getThemeSummaries, r as resolveTheme } from '../themeLibrary-CehcJhzz.js';
-export { z as DocBlock, G as FRONTMATTER_CUSTOM_TEMPLATES_KEY, H as FRONTMATTER_CUSTOM_THEMES_KEY, U as LayoutHints, a5 as PersistentLayerConfig, af as RenderStyle, at as TemplateBlock, au as TemplateContext, az as Theme, aA as ThemeColorPalette, aB as ThemeColorScheme, aE as ThemeStyle, aF as ThemeTypography, aJ as VIEWPORT_PRESETS, aN as ViewportConfig, 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 '../types-DlAZ7MW4.js';
-import '../ContentContainer-BXUlIf18.js';
+import { aw as TemplateBlock, ax as TemplateContext, V as Layer, p as CustomTemplateDefinition, az as TemplateRegistry, aC as Theme, a_ as ViewportConfig, a8 as PersistentLayerConfig, G as DocBlock, a7 as PersistentLayer, aO as TitleBlockInput, al as SectionHeaderInput, ar as StatHighlightInput, ag as QuoteBlockInput, L as FactCardInput, aV as TwoColumnInput, u as DateEventInput, T as ImageWithCaptionInput, Y as LeftFeatureInput, aj as RightFeatureInput, $ as MapBlockInput, aq as StartBlockConfig, O as FullBleedQuoteInput, _ as ListBlockInput, ac as PhotoGridInput, w as DefinitionCardInput, n as ComparisonBarInput, af as PullQuoteInput, aZ as VideoWithCaptionInput, aY as VideoPullQuoteInput, t as DataTableInput, x as DiagramBlockInput, aQ as TreeBlockInput, aK as TimelineBlockInput, B as Block, I as DrawingBlockInput, a3 as MarkerStyle, A as AccentImage, S as ImageTreatment, a as AccentPosition, c as Animation, d as AnimationType, aE as ThemeColorScheme, F as Doc, aF as ThemeRegistry, H as DocDiagnostic, E as DiagramTemplateNode, z as DiagramTemplateEdge, aN as TimelineTemplateTrack, aM as TimelineTemplateLink } from '../Doc-ylqWKDc_.js';
+export { J as FRONTMATTER_CUSTOM_TEMPLATES_KEY, K as FRONTMATTER_CUSTOM_THEMES_KEY, X as LayoutHints, ai as RenderStyle, aD as ThemeColorPalette, aI as ThemeStyle, aJ as ThemeTypography, aW as VIEWPORT_PRESETS, a$ as ViewportOrientation, b0 as ViewportPreset, b5 as createTemplateContext, bc as getLayoutHints, bf as getTwoColumnPositions, bg as getViewport, bh as getViewportOrientation, bj as isTemplateBlock, bm as scaledFontSize } from '../Doc-ylqWKDc_.js';
+import { I as MarkdownNode, $ as TransitionType, _ as TransitionDirection, M as MarkdownBlockNode, q as MarkdownHeading, m as MarkdownDocument, P as MarkdownTable, h as MarkdownCodeBlock, C as MarkdownList } from '../types-BwMPl2CB.js';
+import { C as CoercedBlockMeta } from '../annotationCoercion-Dr_DY9Hx.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-RjVgLpUi.js';
+
+/** Runtime registry composition for built-in and document-scoped templates. */
+
+/** Built-in templates keyed by the ids used in document annotations. */
+declare const templateRegistry: TemplateRegistry;
+/** Broad runtime view used after a template name has selected its function. */
+type RuntimeTemplateRegistry = Record<string, (input: TemplateBlock, context: TemplateContext) => Layer[]>;
+/** Merge document-scoped templates without mutating the built-in registry. */
+declare function buildRegistry(custom?: readonly CustomTemplateDefinition[]): RuntimeTemplateRegistry;
+
+/**
+ * Canonical block-to-layer materialization contract.
+ *
+ * Timeline scheduling and UI components both delegate here so template
+ * lookup, custom templates, ownership, render style, persistent layers,
+ * failure policy, and diagnostics cannot drift by render mode.
+ */
+
+/** How a failed template render is represented in the returned layer graph. */
+type LayerMaterializationFailureMode = 'fallback' | 'empty';
+/** A structured, inspectable explanation for a template render failure. */
+type LayerMaterializationDiagnostic = {
+    code: 'unknown-template';
+    template: string;
+    message: string;
+} | {
+    code: 'invalid-template-result';
+    template: string;
+    message: string;
+    receivedType: string;
+} | {
+    code: 'template-error';
+    template: string;
+    message: string;
+    cause: unknown;
+};
+/** Identifies which path produced a materialized layer graph. */
+type LayerMaterializationSource = 'authored' | 'template' | 'fallback' | 'empty';
+/**
+ * Complete result from {@link materializeBlockLayers}. Failures are data, not
+ * console side effects: callers can display, report, or ignore the diagnostic.
+ */
+interface BlockLayerMaterialization {
+    layers: Layer[];
+    source: LayerMaterializationSource;
+    diagnostic?: LayerMaterializationDiagnostic;
+}
+/**
+ * The single public context for turning a block into renderable layers.
+ *
+ * Theme persistent layers are inherited by default. Pass
+ * `persistentLayers: false` to opt out, or a config to replace the theme's
+ * persistent layers wholesale.
+ */
+interface MaterializeBlockLayersOptions {
+    /** Theme used by templates and render-style post-processing. */
+    theme?: Theme;
+    /** Target viewport. Defaults to the landscape preset. */
+    viewport?: ViewportConfig;
+    /** Theme inheritance override for persistent layers. */
+    persistentLayers?: PersistentLayerConfig | false;
+    /** Zero-based position in the flattened render sequence. */
+    blockIndex?: number;
+    /** Number of blocks in the flattened render sequence. */
+    totalBlocks?: number;
+    /** Document-scoped custom templates; built-ins win name collisions. */
+    customTemplates?: readonly CustomTemplateDefinition[];
+    /** Failed templates render a visible fallback by default. */
+    failureMode?: LayerMaterializationFailureMode;
+}
+/**
+ * Turn any doc block into an owned, render-ready layer graph.
+ *
+ * This is the only recommended public materialization entry point.
+ */
+declare function materializeBlockLayers(block: DocBlock, options?: MaterializeBlockLayersOptions): BlockLayerMaterialization;
+
+/**
+ * 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>;
+
+/** Resolve a historical template id to its canonical registry key. */
+declare function resolveTemplateName(name: string): string;
+/** Templates that consume their child headings rather than rendering them. */
+declare const CONTAINER_TEMPLATES: ReadonlySet<string>;
+/** True when `name` (or its alias) consumes child blocks. */
+declare function isContainerTemplate(name: string | undefined): boolean;
+
+/**
+ * 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[];
+/**
+ * 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.
+ * Shared persistent-layer primitive used by `materializeBlockLayers`.
+ */
+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 a node-and-edge diagram from one of two data sources:
+ * 1. Child headings (`context.children`) — the legacy authored form; each
+ *    child becomes a node positioned by `x`/`y` and connected by
+ *    `connectsTo` (see `diagramLayout.ts` for auto-placement rules).
+ * 2. `input.nodes`/`input.edges` (usually via `templateData`) — the
+ *    data-driven form derived from an ASCII-art diagram fence. Nodes may
+ *    carry per-node sizes and a `container` reference; containers draw
+ *    behind their children as translucent grouping cards.
+ *
+ * Layout coordinates 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[];
+
+/**
+ * Tree Template
+ *
+ * Renders a hierarchical filesystem-style treeview (folder/file icons +
+ * connector rails, collapsible in the live player) from an ASCII tree fence.
+ * Emits a single `TreeLayer` (foreignObject HTML, like `dataTable`) plus an
+ * optional title + themed background.
+ *
+ * Data source: `input.items` (a nested `TreeLayerItem[]`), populated from
+ * `templateData.items` which the pipeline derives from the tree fence.
+ */
+
+declare function treeBlock(input: TreeBlockInput, context: TemplateContext): Layer[];
+
+/**
+ * Timeline Template
+ *
+ * Renders one or more left-to-right tracks with positioned event markers,
+ * callout stems/text, and optional branch links. It deliberately composes
+ * existing shape/path/text layers so every current render/export surface can
+ * display timelines without a timeline-specific React layer.
+ */
+
+declare function timelineBlock(input: TimelineBlockInput, 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;
+}
+interface ConnectorAnchor {
+    side: 'top' | 'right' | 'bottom' | 'left';
+    offset: 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[];
+/** Resolve a normalized authored anchor to a concrete point on a box. */
+declare function anchorPoint(box: ClipBox, anchor: ConnectorAnchor): 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;
+    port?: ConnectorPort;
+}, end: {
+    x: number;
+    y: number;
+    port?: ConnectorPort;
+}): 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.
+ */
+
+/**
+ * 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 | false;
+    /**
+     * 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[];
+    /** Failed templates render a visible fallback by default. */
+    failureMode?: LayerMaterializationFailureMode;
+    /** Receives structured template failures without hidden console output. */
+    onDiagnostic?: (diagnostic: LayerMaterializationDiagnostic, block: DocBlock, blockIndex: number) => void;
+}
+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. */
+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;
+
+/** Text fitting shared by the live diagram canvas and template renderer. */
+declare const DIAGRAM_LABEL_LINE_HEIGHT = 1.25;
+declare const DIAGRAM_LABEL_HORIZONTAL_PADDING = 24;
+declare const DIAGRAM_LABEL_VERTICAL_PADDING = 16;
+declare const DIAGRAM_LABEL_MIN_FONT_SIZE = 10;
+interface DiagramLabelFit {
+    fontSize: number;
+    lineCount: number;
+    /** Upward shift that centers the full line group around the node midpoint. */
+    firstLineOffset: number;
+    textWidth: number;
+}
+/**
+ * Fit a plain diagram label inside a node card using the same character-width
+ * estimate and word wrapping as React's `TextLayer`.
+ */
+declare function fitDiagramLabel(text: string, boxWidth: number, boxHeight: number, preferredFontSize: number): DiagramLabelFit;
+
+/**
+ * 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;
+}
+/**
+ * Public accessor for {@link pinnedMeta}: the timing/meta values an author
+ * pinned on a block (heading `{key=value}` attrs or `{[key=value]}`
+ * annotation params). Consumers use this to tell "author pinned this"
+ * from "derive it" — e.g. narration timing never overwrites a pinned
+ * `duration=`/`startTime=`.
+ */
+declare function getPinnedBlockMeta(block: Block): CoercedBlockMeta;
+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;
+/**
+ * Extract the plain text from a block's body contents (excluding heading text).
+ *
+ * Exported because the narration script builder and the narration timing
+ * resolver must derive the *same* spoken text per block that captions and
+ * reading-time use — one source of truth for "what does this block say".
+ */
+declare function getBlockBodyText(block: Block): string;
+
+/**
+ * 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.
+ *
+ */
+
+/**
+ * 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 an
+ * optional caller-owned registry, then built-ins 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. Inline custom themes ship with the doc, exactly like custom
+ * templates; host-level themes can be supplied through an explicit registry.
+ */
+
+/**
+ * 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 caller-registry or built-in theme for that id, else the default theme.
+ */
+declare function resolveThemeForDoc(doc: ThemeResolvable | null | undefined, explicitId?: string, registry?: ThemeRegistry): Theme;
+
+/**
+ * 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 narration 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>;
+
+/**
+ * Apply narration timing from a document-anchored take to a Doc's block
+ * timeline.
+ *
+ * When a doc carries a document-spanning narration clip (a preamble
+ * `{[audio src=… anchor=document]}` → `doc.documentMedia`) whose
+ * `.timing.json` sidecar has per-block ranges (v3, written by the
+ * teleprompter's aligner), the blocks are re-timed so playback and
+ * exports advance in sync with the recorded voice. Runs as step 0 of
+ * `resolveAudioMapping`, so every surface that resolves audio gets it.
+ *
+ * Precedence: author-pinned `duration=`/`startTime=` heading attrs win
+ * over narration ranges (a conflicting pin gets an `info` diagnostic);
+ * narration ranges win over per-block audio-segment mapping and
+ * reading-time estimates.
+ */
+
+interface NarrationResolution {
+    doc: Doc;
+    /** False → the doc is returned unchanged (no clip / no sidecar / no match). */
+    applied: boolean;
+    /** The narration media path, for callers that bundle assets. */
+    clipSrc?: string;
+}
+/**
+ * Find the doc's document-anchored narration clip, load its timing
+ * sidecar, and re-time the blocks from its ranges. Pure with respect to
+ * the input doc — returns a new Doc (or the original when nothing
+ * applies).
+ */
+declare function applyNarrationTiming(doc: Doc, container: ContentContainer): Promise<NarrationResolution>;
+
+/**
+ * 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 `materializeBlockLayers()`.
+ */
+
+/**
+ * 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[];
+
+/**
+ * Public types for the ASCII diagram codec.
+ *
+ * Coordinates are grid-native: `col`/`row` count character cells from the
+ * top-left of the art (0-based), `wCols`/`hRows` include the borders. The
+ * mapping helpers in `mapping.ts` convert to/from diagram canvas units
+ * via {@link ASCII_CHAR_W} / {@link ASCII_CHAR_H}.
+ */
+interface AsciiDiagramNode {
+    /**
+     * Stable id: slug of the first label line, deduplicated with `-2`/`-3`
+     * suffixes in reading order. Identical art always re-parses to
+     * identical ids (editor selection and edges resolve by id).
+     */
+    id: string;
+    /** Interior text lines joined with `\n` (trimmed, blank lines dropped). May be `''`. */
+    label: string;
+    /** Left column of the box (0-based, includes the border). */
+    col: number;
+    /** Top row of the box (0-based, includes the border). */
+    row: number;
+    /** Full box width in columns, borders included. */
+    wCols: number;
+    /** Full box height in rows, borders included. */
+    hRows: number;
+    /** Id of the box that strictly contains this one, when nested. */
+    containerId?: string;
+}
+interface AsciiDiagramEdge {
+    source: string;
+    target: string;
+    /** Edge label parsed from an embedded horizontal run (`──label──▶`). */
+    label?: string;
+    /** False when the line carried no arrowhead. */
+    directed: boolean;
+}
+interface AsciiDiagram {
+    /** Nodes in reading order (row, then col). Containers are ordinary nodes with children pointing at them. */
+    nodes: AsciiDiagramNode[];
+    /** Deduplicated edges, sorted by (source, target, label). */
+    edges: AsciiDiagramEdge[];
+    /** Character vocabulary detected in the source; render emits the same style. */
+    style: 'unicode' | 'ascii';
+    /** Non-fatal parse notes (loose text, dropped labels, ambiguous buses, …). */
+    warnings: string[];
+}
+interface AsciiDiagramDetection {
+    isDiagram: boolean;
+    /** Present when `isDiagram` — avoids a second parse in callers. */
+    diagram?: AsciiDiagram;
+    /** Machine-greppable accept/reject reasons, e.g. `too-few-boxes(1)`, `loose-ratio(0.41)`. */
+    reasons: string[];
+}
+/**
+ * Canvas pixels per grid column/row. Sized so a typical 12-col × 3-row
+ * ASCII box maps close to the native 180×64 diagram card, and a 60–100
+ * column diagram fits the 1600×900 diagram viewport.
+ */
+declare const ASCII_CHAR_W = 14;
+declare const ASCII_CHAR_H = 28;
+
+/**
+ * ASCII diagram parser: box-and-line art → semantic nodes/edges.
+ *
+ * Pure and deterministic; never throws. Unparseable input degrades to an
+ * empty diagram (plus warnings), never an exception — callers decide what
+ * to do with sparse results (the detector requires ≥2 nodes, for example).
+ *
+ * Pipeline: normalize → char grid → box tracing (corner walks; `+` is
+ * resolved smallest-rectangle-first) → containment tree → labels/ids →
+ * edge extraction (mask box perimeters + leaf interiors, then connected
+ * components of line/arrow cells with label "bridges") → loose text.
+ */
+
+declare function parseAsciiDiagram(text: string): AsciiDiagram;
+
+/**
+ * ASCII diagram renderer: semantic nodes/edges → box-and-line art.
+ *
+ * Deterministic (no clock, no randomness; every iteration order is an
+ * explicit sort) and designed as a fixpoint partner for `parse.ts`:
+ *
+ * - `parseAsciiDiagram(renderAsciiDiagram(d))` preserves node ids, labels,
+ *   containment, and the edge tuple set of `d`.
+ * - After one normalization cycle the output is byte-stable:
+ *   `renderAsciiDiagram(parseAsciiDiagram(renderAsciiDiagram(d))) ===
+ *   renderAsciiDiagram(d)`.
+ *
+ * Grid positions come from the nodes; container rects are DERIVED from
+ * their children each render (a container's own col/row are ignored), so
+ * moving children can never orphan them outside their box.
+ */
+
+interface RenderAsciiDiagramOptions {
+    /** Character vocabulary; defaults to the diagram's own detected style. */
+    style?: 'unicode' | 'ascii';
+}
+declare function renderAsciiDiagram(diagram: AsciiDiagram, options?: RenderAsciiDiagramOptions): string;
+
+/**
+ * ASCII diagram detection: is this fence content a box-and-line diagram?
+ *
+ * False positives are the expensive failure (they hide real code behind a
+ * canvas / template); false negatives just leave a code block alone. Every
+ * rejection path records a machine-greppable reason so the corpus tests
+ * act as the contract for any future threshold tuning.
+ */
+
+/** Fence languages eligible for diagram detection (plus no language at all). */
+declare const ASCII_DIAGRAM_FENCE_LANGS: ReadonlySet<string>;
+declare function isEligibleAsciiFenceLang(lang: string | null | undefined): boolean;
+/**
+ * True when the fence LANGUAGE is the explicit `diagram` tag — an author-set
+ * "this is a diagram" marker that survives round-trips (the language class
+ * round-trips; fence meta does not). Detection of a tagged fence is lenient
+ * (≥1 box, no lattice rejector) so a degenerate diagram stays a diagram.
+ */
+declare function isExplicitDiagramLang(lang: string | null | undefined): boolean;
+interface DetectDiagramOptions {
+    /** The fence is explicitly `diagram`-tagged: accept ≥1 box, skip rejectors. */
+    explicit?: boolean;
+}
+declare function detectAsciiDiagram(text: string, opts?: DetectDiagramOptions): AsciiDiagramDetection;
+/** Convenience gate for pipeline callers: lang allowlist + content detection. */
+declare function isAsciiDiagramFence(node: MarkdownCodeBlock): boolean;
+
+/**
+ * ASCII diagram REPAIR — an opt-in, best-effort pass that reconstructs a
+ * clean, well-formed diagram from broken box-and-line art.
+ *
+ * The motivating case: hand-drawn architecture art whose labels overflow
+ * their boxes and shove every following column out of alignment row-to-row
+ * (e.g. a rename widened the labels). Conservative detection correctly
+ * declines such art (`garbled-labels`) so it renders as a faithful code
+ * block — but a user can then ask to "repair" it. This is that repair.
+ *
+ * It is deliberately AGGRESSIVE and lossy — never on the auto-detection path
+ * (a mistake there would hide real code). It is only invoked when the user
+ * explicitly opts in, and the result is a fully editable diagram, so an
+ * imperfect edge or two is fine (the canvas lets the user fix them).
+ *
+ * Pipeline:
+ *  1. Aggressive box tracing (walls may cross edge routing).
+ *  2. Row-band label recovery — the key trick: even when a box's columns are
+ *     desynced from its borders, each label ROW is internally consistent, so
+ *     its `│…│` segments map to the band's boxes by reading order.
+ *  3. Best-effort edge recovery (facing-border adjacency + arrowhead
+ *     direction).
+ *  4. Re-render clean via `renderAsciiDiagram` — the output re-parses cleanly.
+ */
+
+interface RepairResult {
+    /** The reconstructed diagram model (grid-native coordinates). */
+    diagram: AsciiDiagram;
+    /** Clean, re-rendered box-and-line art — re-parses to `diagram`. */
+    art: string;
+}
+/**
+ * True when a fence is a box diagram too broken for clean detection but worth
+ * offering to repair: it has box corners and aggressively traces ≥2 boxes,
+ * yet conservative detection declines it. Clean diagrams (already detected)
+ * and non-box art both return false, so the three states partition cleanly.
+ */
+declare function isRepairableDiagram(text: string): boolean;
+/**
+ * Reconstruct a clean diagram from broken art. Returns `null` when fewer than
+ * two boxes can be recovered (nothing worth repairing).
+ */
+declare function repairAsciiDiagram(text: string): RepairResult | null;
+
+/**
+ * Mapping between the grid-native ASCII diagram model and the diagram
+ * canvas / template model (canvas units, the same space as `Block.x`/`y`).
+ *
+ * Quantization uses plain `round()` per axis — monotonic and local, so a
+ * small canvas nudge either changes nothing or moves exactly one cell
+ * (cluster-based schemes flap under small moves and churn the art).
+ */
+
+declare function asciiCellToCanvas(col: number, row: number): {
+    x: number;
+    y: number;
+};
+declare function canvasToAsciiCell(x: number, y: number): {
+    col: number;
+    row: number;
+};
+/** Grid model → template/canvas model (`templateData.nodes`/`edges`). */
+declare function asciiDiagramToTemplateData(diagram: AsciiDiagram): {
+    nodes: DiagramTemplateNode[];
+    edges: DiagramTemplateEdge[];
+};
+/** Template/canvas model → grid model, quantizing positions and sizes. */
+declare function asciiDiagramFromTemplateData(nodes: readonly DiagramTemplateNode[], edges: readonly DiagramTemplateEdge[], options?: {
+    style?: 'unicode' | 'ascii';
+}): AsciiDiagram;
+/**
+ * Legacy heading-based diagram children → ASCII diagram model. Used to
+ * migrate `### Node {#id x= y= connectsTo=}` sections to ASCII fences;
+ * positions run through the shared `computeDiagramLayout` so unpinned
+ * children get the same grid placement as the legacy renderer.
+ */
+declare function asciiDiagramFromBlocks(children: readonly Block[], options?: {
+    style?: 'unicode' | 'ascii';
+}): AsciiDiagram;
+
+/**
+ * Public model for authored ASCII timelines.
+ *
+ * Source columns and rows are retained so separate tracks share one spatial
+ * scale and pointer callouts can land between authored milestone dots. The
+ * template mapping normalizes columns only at the final rendering boundary.
+ */
+type AsciiTimelineStyle = 'unicode' | 'ascii';
+type AsciiTimelineSide = 'above' | 'below';
+type AsciiTimelineMarker = 'filled' | 'hollow' | 'diamond';
+interface AsciiTimelineEvent {
+    /** Stable slug id, deduplicated across every track. */
+    id: string;
+    /** Short callout heading. */
+    label: string;
+    /** Optional longer callout/body text. */
+    description?: string;
+    /** Zero-based source-grid column of the event anchor. */
+    column: number;
+    /** Authored/default callout placement around the track. */
+    side?: AsciiTimelineSide;
+    /** Placement for `description` when it differs from the label side. */
+    descriptionSide?: AsciiTimelineSide;
+    /** False renders a cadence/tick point without a text callout. */
+    callout?: boolean;
+    /** Visual point vocabulary inferred from the authored marker. */
+    marker?: AsciiTimelineMarker;
+}
+interface AsciiTimelineTrack {
+    /** Stable track id. */
+    id: string;
+    /** Optional label shown to the left of the rendered track. */
+    label?: string;
+    /** Optional axis/end label authored after the terminal arrow. */
+    endLabel?: string;
+    /** Zero-based source row containing this track's horizontal axis. */
+    row: number;
+    /** Inclusive source-grid bounds of the axis. */
+    startColumn: number;
+    endColumn: number;
+    events: AsciiTimelineEvent[];
+}
+interface AsciiTimelineLink {
+    /** Source event id. */
+    source: string;
+    /** Target event id. */
+    target: string;
+    /** Optional branch/link label. */
+    label?: string;
+}
+interface AsciiTimeline {
+    tracks: AsciiTimelineTrack[];
+    links: AsciiTimelineLink[];
+    /** Source-grid dimensions, shared by every track. */
+    width: number;
+    height: number;
+    style: AsciiTimelineStyle;
+    /** Non-fatal parse notes (unresolved links, unlabeled events, and so on). */
+    warnings: string[];
+}
+interface AsciiTimelineDetection {
+    isTimeline: boolean;
+    /** Present on acceptance so callers do not need to parse twice. */
+    timeline?: AsciiTimeline;
+    /** Machine-readable accept/reject reasons. */
+    reasons: string[];
+}
+
+/** ASCII timeline parser: horizontal tracks + point/callout art -> model. */
+
+interface AsciiTimelineStats {
+    axisLines: number;
+    markerCount: number;
+    strongMarkerCount: number;
+    horizontalChars: number;
+    pointerCount: number;
+    branchDeclarations: number;
+    /** True for high-confidence multi-lane flow art with a return edge. */
+    wrappedFlow?: boolean;
+}
+declare function parseAsciiTimeline(text: string): AsciiTimeline;
+declare function parseAsciiTimelineWithStats(text: string): {
+    timeline: AsciiTimeline;
+    stats: AsciiTimelineStats;
+};
+
+/**
+ * ASCII timeline renderer: semantic tracks/events -> canonical timeline art.
+ *
+ * The canonical authored form keeps the rail visually continuous and moves
+ * event payloads onto pointer callouts:
+ *
+ *                       ▲ T28 :: delta 28 {#t28 column=12}
+ *   Kernel {#kernel start=8 end=72}: ───●────────────────○────►
+ *                                                ▼ T29 {#t29 column=36}
+ *
+ * Links follow the tracks as declarations. This form is compact, readable in
+ * raw Markdown, and is the exact grammar consumed by `parse.ts`. Rendering is
+ * deterministic and normalizes parser-sensitive text/ids up front, so it is a
+ * byte fixpoint after one render:
+ *
+ *   renderAsciiTimeline(parseAsciiTimeline(renderAsciiTimeline(t))) ===
+ *   renderAsciiTimeline(t)
+ */
+
+interface RenderAsciiTimelineOptions {
+    /** Character vocabulary; defaults to the timeline's detected style. */
+    style?: AsciiTimelineStyle;
+}
+/** Render a timeline into deterministic, parser-canonical ASCII/Unicode art. */
+declare function renderAsciiTimeline(timeline: AsciiTimeline, options?: RenderAsciiTimelineOptions): string;
+
+/** Conservative detection for authored ASCII timeline fences. */
+
+declare const ASCII_TIMELINE_FENCE_LANGS: ReadonlySet<string>;
+declare function isEligibleAsciiTimelineFenceLang(lang: string | null | undefined): boolean;
+declare function isExplicitTimelineLang(lang: string | null | undefined): boolean;
+interface DetectAsciiTimelineOptions {
+    /** Explicit `timeline` language: allow one-point/ASCII-marker tracks. */
+    explicit?: boolean;
+}
+declare function detectAsciiTimeline(text: string, options?: DetectAsciiTimelineOptions): AsciiTimelineDetection;
+declare function isAsciiTimelineFence(node: MarkdownCodeBlock): boolean;
+
+/** Mapping from source-grid timeline data to normalized template inputs. */
+
+declare function asciiTimelineToTemplateData(timeline: AsciiTimeline): {
+    tracks: TimelineTemplateTrack[];
+    links: TimelineTemplateLink[];
+};
+
+/**
+ * Conservative parser for two-or-more-lane flow art whose last edge wraps
+ * around the right margin. This dialect is common in AI-authored architecture
+ * notes and sequence sketches:
+ *
+ *   CLIENT                 KERNEL
+ *   ──────                 ──────
+ *   input ──► command ────► validate
+ *                            ├─ invalid → rejected ─┐
+ *   surfaced ◄─────────────────────────────────────┘
+ *
+ * It is intentionally strict. Every nonblank row must be a heading,
+ * underline, connector-only row, parenthetical continuation, or prose joined
+ * by an explicit arrow. Accepted art is converted to the ordinary timeline
+ * model, after which the canonical timeline renderer owns the authored form.
+ */
+
+/** Parse the wrapped-flow dialect, or return null without claiming the art. */
+declare function parseWrappedFlowTimeline(text: string): AsciiTimeline | null;
+/** High-confidence predicate used by the editor's lossless rewrite gate. */
+declare function isWrappedFlowTimelineSource(text: string): boolean;
+
+/**
+ * Public types for the ASCII treeview codec.
+ *
+ * A tree is a hierarchy of labelled nodes (file trees, dependency trees,
+ * category outlines). Unlike the diagram codec's spatial grid model, the
+ * tree model is a plain nested structure — rendering is a deterministic
+ * tree-walk, so the parse↔render fixpoint is structural and trivially
+ * byte-stable.
+ */
+interface TreeNode {
+    /**
+     * Stable id: slug of the label, deduplicated with `-2`/`-3` suffixes in
+     * document (depth-first) order. Identical art re-parses to identical ids
+     * (the outline widget's selection resolves by id).
+     */
+    id: string;
+    /** Display label, verbatim (may keep a trailing `/`). */
+    label: string;
+    /** Child nodes (empty for leaves). */
+    children: TreeNode[];
+    /** True when this node reads as a container (trailing `/` or has children). */
+    isDir?: boolean;
+    /** Trailing `# …` / `<-- …` comment, preserved across round-trips. */
+    comment?: string;
+}
+interface Tree {
+    /** Top-level nodes (a forest — usually one root for a file tree). */
+    roots: TreeNode[];
+    /** Character vocabulary detected in the source; render emits the same. */
+    style: 'unicode' | 'ascii';
+    /** Non-fatal parse notes (ragged dedents, dropped lines, …). */
+    warnings: string[];
+}
+interface TreeDetection {
+    isTree: boolean;
+    /** Present when `isTree` — avoids a second parse in callers. */
+    tree?: Tree;
+    /** Machine-greppable accept/reject reasons. */
+    reasons: string[];
+}
+
+/**
+ * ASCII tree parser: file-tree / outline art → nested nodes.
+ *
+ * Pure, deterministic, never throws. Handles the many renditions AI emits:
+ * Unicode connectors (`├── `/`└── `/`│   `), ASCII (`|-- `/`` `-- ``/`+-- `),
+ * bullet-indented (`- `/`* `), and pure indentation. Depth is recovered by
+ * finding where each line's LABEL begins (after any connector/indent
+ * prefix) and running the standard outline indent-stack — this unifies all
+ * renditions and tolerates ragged dedents.
+ */
+
+declare function parseTree(text: string): Tree;
+
+/**
+ * ASCII tree renderer: nested nodes → clean tree art.
+ *
+ * A deterministic depth-first walk emitting rail/branch prefixes. The
+ * fixpoint is structural: `parseTree(renderTree(t))` preserves the node
+ * hierarchy + labels + comments, and `renderTree(parseTree(renderTree(t)))`
+ * is byte-identical (idempotent after one normalization cycle). Unlike the
+ * diagram renderer there is no spatial layout, so jitter is impossible.
+ */
+
+interface RenderTreeOptions {
+    /** Character vocabulary; defaults to the tree's own detected style. */
+    style?: 'unicode' | 'ascii';
+}
+declare function renderTree(tree: Tree, options?: RenderTreeOptions): string;
+
+/**
+ * ASCII tree detection: is this fence content a file-tree / outline?
+ *
+ * The mirror image of the diagram detector. A diagram has ≥2 closed boxes;
+ * a tree has ZERO closed boxes plus connector-branch structure. The two
+ * partition the `├──` glyph space cleanly, so a fence is at most one of
+ * them. Auto-detection is deliberately conservative (requires connector
+ * branches — the unambiguous AI file-tree signal); the parser still handles
+ * pure-indentation renditions for explicitly `{[tree]}`-annotated fences.
+ */
+
+/** Fence languages eligible for tree detection (plus no language at all). */
+declare const TREE_FENCE_LANGS: ReadonlySet<string>;
+declare function isEligibleTreeFenceLang(lang: string | null | undefined): boolean;
+/**
+ * True when the fence LANGUAGE is the explicit `tree` tag — an author-set
+ * "this is a tree" marker that survives markdown ↔ Tiptap round-trips (the
+ * language class round-trips; fence meta does not). Detection of a tagged
+ * fence is lenient (no connector requirement) so a flattened/degenerate
+ * tree stays a tree.
+ */
+declare function isExplicitTreeLang(lang: string | null | undefined): boolean;
+interface DetectTreeOptions {
+    /** The fence is explicitly `tree`-tagged: skip the connector requirement. */
+    explicit?: boolean;
+}
+declare function detectTree(text: string, opts?: DetectTreeOptions): TreeDetection;
+/** Convenience gate for pipeline callers: lang allowlist + content detection. */
+declare function isTreeFence(node: MarkdownCodeBlock): boolean;
+
+/**
+ * Mapping between the tree model and the template/layer data model, plus a
+ * nested-markdown-list → tree walker (none exists in core — `extractListItems`
+ * flattens, losing depth).
+ */
+
+/** JSON-serializable tree item carried on `templateData.items` / a `TreeLayer`. */
+interface TreeItem {
+    id: string;
+    label: string;
+    isDir?: boolean;
+    comment?: string;
+    children: TreeItem[];
+}
+/** Tree model → template/layer items (structure-preserving). */
+declare function treeToTemplateData(tree: Tree): {
+    items: TreeItem[];
+};
+/** Template/layer items → tree model (editor write-back / render). */
+declare function treeFromTemplateData(items: readonly TreeItem[], options?: {
+    style?: 'unicode' | 'ascii';
+}): Tree;
+/**
+ * Recursively convert a nested markdown bullet list into a tree. Used by
+ * `deriveTemplateInputs` when an author explicitly `{[tree]}`-annotates a
+ * block whose body is a nested list rather than a fence.
+ */
+declare function treeFromMarkdownList(list: MarkdownList): Tree;
+/** Find the first top-level markdown list in a block's body, if any. */
+declare function findFirstList(contents: MarkdownBlockNode[] | undefined): MarkdownList | undefined;
+
+export { ASCII_CHAR_H, ASCII_CHAR_W, ASCII_DIAGRAM_FENCE_LANGS, ASCII_TIMELINE_FENCE_LANGS, type AccentLayout, type AsciiDiagram, type AsciiDiagramDetection, type AsciiDiagramEdge, type AsciiDiagramNode, type AsciiTimeline, type AsciiTimelineDetection, type AsciiTimelineEvent, type AsciiTimelineLink, type AsciiTimelineMarker, type AsciiTimelineSide, type AsciiTimelineStats, type AsciiTimelineStyle, type AsciiTimelineTrack, type AudioSegmentTiming, BASE_INPUT_DESCRIPTORS, type BlockLayerMaterialization, CONTAINER_TEMPLATES, type ClipBox, type ConnectorAnchor, type ConnectorPort, type ConnectorRouting, type ConnectorSnapPoint, type CoverBlockInput, DEFAULT_LAYOUT, DIAGRAM_LABEL_HORIZONTAL_PADDING, DIAGRAM_LABEL_LINE_HEIGHT, DIAGRAM_LABEL_MIN_FONT_SIZE, DIAGRAM_LABEL_VERTICAL_PADDING, type DataFenceParseResult, type DeriveTemplateInputsOptions, type DetectAsciiTimelineOptions, type DiagramEdge, type DiagramLabelFit, type DiagramLayout, type DiagramLayoutOptions, type DiagramNodePosition, DocBlock, type DrawingConnector, type DrawingLayout, type DrawingLayoutOptions, type DrawingShape, type DrawingShapeKind, type ExpandDocBlocksOptions, type ExtractedTableData, type FirstImage, type InputCoercion, type LayerMaterializationDiagnostic, type LayerMaterializationFailureMode, type LayerMaterializationSource, type LayoutLayerDefaults, type LayoutLayersResult, type MarkdownToDocOptions, type MarkdownValidationResult, type MaterializeBlockLayersOptions, type NarrationResolution, PATH_SHAPE_KINDS, PersistentLayerConfig, type RenderAsciiDiagramOptions, type RenderAsciiTimelineOptions, type RenderTreeOptions, type RepairResult, type RuntimeTemplateRegistry, SHAPE_NAMES, TEMPLATE_INPUT_DESCRIPTORS, TEMPLATE_METADATA, TREE_FENCE_LANGS, TemplateBlock, TemplateContext, type TemplateInputDescriptor, type TemplateMetadata, type TemplateParamFinding, Theme, ThemeColorScheme, type Tree, type TreeDetection, type TreeItem, type TreeNode, type ValidateOptions, ViewportConfig, adjustY, anchorPoint, applyNarrationTiming, applyRenderStyleToLayers, asciiCellToCanvas, asciiDiagramFromBlocks, asciiDiagramFromTemplateData, asciiDiagramToTemplateData, asciiTimelineToTemplateData, buildRegistry, canvasToAsciiCell, clipEndpoints, clipPoint, coerceTemplateParams, comparisonBar, computeDiagramLayout, computeDrawingLayout, computeLayoutLayers, connectorPath, countBlocks, coverBlock, createAccentLayers, cssFilterForTreatment, dataTable, dateEvent, definitionCard, deriveTemplateInputs, detectAsciiDiagram, detectAsciiTimeline, detectTree, diagramBlock, docToMarkdown, drawingBlock, expandCoverBlock, expandDocBlocks, expandPersistentLayers, extractBlockquoteText, extractBodyPlainText, extractFirstImage, extractImages, extractListItems, extractTableData, extractTableFromContents, factCard, fallbackBlockLayers, findFirstList, findFirstTable, fitDiagramLabel, flattenBlocks, flattenRenderableBlocks, fullBleedQuote, getAccentLayout, getAnimationProgress, getAnimationStyle, getAvailableTemplates, getBlockBodyText, getBlockDepth, getDefaultAnimation, getDefaultAnimationDuration, getOverlayOpacity, getPersistentLayersFromTheme, getPinnedBlockMeta, getTemplateHint, getThemeFont, getTransitionClass, hasTemplate, imageWithCaption, isAsciiDiagramFence, isAsciiTimelineFence, isContainerTemplate, isDataFence, isEligibleAsciiFenceLang, isEligibleAsciiTimelineFenceLang, isEligibleTreeFenceLang, isExplicitDiagramLang, isExplicitTimelineLang, isExplicitTreeLang, isRepairableDiagram, isShapeName, isTreeFence, isWrappedFlowTimelineSource, layoutBlock, leftFeature, lineStyleDasharray, lintTemplateParams, listBlock, mapBlock, markdownToDoc, markerPath, materializeBlockLayers, nearestSnapPoint, normalizeShapeKind, parseAsciiDiagram, parseAsciiTimeline, parseAsciiTimelineWithStats, parseDataFence, parseTree, parseWrappedFlowTimeline, parseYamlSubset, photoGrid, pullQuote, quoteBlock, readCustomTemplatesFromFrontmatter, readCustomThemesFromFrontmatter, renderAsciiDiagram, renderAsciiTimeline, renderTree, repairAsciiDiagram, replaceDataFence, resolveAudioMapping, resolveColorScheme, resolvePersistentLayers, resolveTemplateName, resolveThemeForDoc, rightFeature, scaleAnimationDuration, scoreTextSimilarity, sectionHeader, shapePath, shouldUseShadow, snapEndpoints, snapPoints, statHighlight, templateRegistry, themeWantsAmbientMotion, themedEntrance, themedFontSize, themedImageTreatment, themedScrim, themedSurfaceGradient, timelineBlock, titleBlock, treeBlock, treeFromMarkdownList, treeFromTemplateData, treeToTemplateData, twoColumn, validateMarkdownDoc, validateMarkdownSource, videoPullQuote, videoWithCaption, wrapWithPersistentLayers, writeCustomTemplatesToFrontmatter, writeCustomThemesToFrontmatter };