@bendyline/squisq 1.4.0 → 1.5.0

package/dist/story/index.d.ts

@@ -1,8 +1,32 @@
-import { Q as PersistentLayer, z as Layer, R as PersistentLayerConfig, am as TitleBlockInput, aa as TemplateContext, a0 as SectionHeaderInput, a4 as StatHighlightInput, Z as QuoteBlockInput, F as FactCardInput, aq as TwoColumnInput, p as DateEventInput, y as ImageWithCaptionInput, H as LeftFeatureInput, $ as RightFeatureInput, M as MapBlockInput, a3 as StartBlockConfig, w as FullBleedQuoteInput, J as ListBlockInput, V as PhotoGridInput, r as DefinitionCardInput, k as ComparisonBarInput, Y as PullQuoteInput, au as VideoWithCaptionInput, at as VideoPullQuoteInput, o as DataTableInput, A as AccentImage, a as AccentPosition, af as Theme, av as ViewportConfig, t as DocBlock, B as Block, a9 as TemplateBlock, ac as TemplateRegistry, b as Animation, c as AnimationType, ap as TransitionType, ah as ThemeColorScheme, s as Doc } from '../Doc-BeSeH2iX.js';
-export { E as LayoutHints, _ as RenderStyle, ag as ThemeColorPalette, ak as ThemeStyle, al as ThemeTypography, ar as VIEWPORT_PRESETS, aw as ViewportOrientation, ax as ViewportPreset, aB as createTemplateContext, aG as getLayoutHints, aK as getTwoColumnPositions, aL as getViewport, aM as getViewportOrientation, aO as isTemplateBlock, aS as scaledFontSize } from '../Doc-BeSeH2iX.js';
-import { p as MarkdownHeading, l as MarkdownDocument } from '../types-BdZkdJ3z.js';
+import { a2 as PersistentLayer, ax as Theme, R as Layer, a3 as PersistentLayerConfig, aE as TitleBlockInput, as as TemplateContext, ag as SectionHeaderInput, am as StatHighlightInput, ab as QuoteBlockInput, H as FactCardInput, aG as TwoColumnInput, t as DateEventInput, P as ImageWithCaptionInput, T as LeftFeatureInput, ae as RightFeatureInput, W as MapBlockInput, al as StartBlockConfig, K as FullBleedQuoteInput, V as ListBlockInput, a7 as PhotoGridInput, v as DefinitionCardInput, n as ComparisonBarInput, aa as PullQuoteInput, aK as VideoWithCaptionInput, aJ as VideoPullQuoteInput, s as DataTableInput, w as DiagramBlockInput, B as Block, E as DrawingBlockInput, _ as MarkerStyle, ar as TemplateBlock, A as AccentImage, O as ImageTreatment, a as AccentPosition, aL as ViewportConfig, p as CustomTemplateDefinition, y as DocBlock, au as TemplateRegistry, c as Animation, d as AnimationType, az as ThemeColorScheme, x as Doc, z as DocDiagnostic } from '../Doc-BsMkmzH8.js';
+export { F as FRONTMATTER_CUSTOM_TEMPLATES_KEY, G as FRONTMATTER_CUSTOM_THEMES_KEY, S as LayoutHints, ad as RenderStyle, ay as ThemeColorPalette, aC as ThemeStyle, aD as ThemeTypography, aH as VIEWPORT_PRESETS, aM as ViewportOrientation, aN as ViewportPreset, aS as createTemplateContext, aY as getLayoutHints, b0 as getTwoColumnPositions, b1 as getViewport, b2 as getViewportOrientation, b4 as isTemplateBlock, b9 as scaledFontSize } from '../Doc-BsMkmzH8.js';
+import { I as MarkdownNode, $ as TransitionType, _ as TransitionDirection, M as MarkdownBlockNode, q as MarkdownHeading, m as MarkdownDocument, P as MarkdownTable, h as MarkdownCodeBlock } from '../types-DlAZ7MW4.js';
 import { C as ContentContainer } from '../ContentContainer-DNx460y8.js';
-export { D as DEFAULT_THEME, g as getAvailableThemes, b as getThemeSummaries, r as resolveTheme } from '../themeLibrary-BHjJ0Qx6.js';
+export { D as DEFAULT_THEME, g as getAvailableThemes, b as getThemeSummaries, r as resolveTheme } from '../themeLibrary-DQQKuRMx.js';
+
+/**
+ * Canonical, framework-free UI metadata for every built-in block template.
+ *
+ * This is the single source of truth for the human-readable label and the
+ * one-sentence description of each template id in {@link templateRegistry}.
+ * The editor's `TemplatePicker` renders its gallery from this map (joining
+ * each id with a locally-defined SVG icon, which can't live in this
+ * framework-free package), so a template only has to be added here and to
+ * `templateRegistry` for it to surface in the editor.
+ *
+ * `templateMetadata.test.ts` asserts this map and `templateRegistry` stay
+ * exactly 1:1 — adding a template to one without the other fails the build.
+ *
+ * Order matters: pickers iterate this object's insertion order, so it doubles
+ * as the canonical gallery order.
+ */
+interface TemplateMetadata {
+    /** Human-readable label shown in pickers (e.g. "Image with Caption"). */
+    label: string;
+    /** One-sentence description of when to reach for this template. */
+    description: string;
+}
+declare const TEMPLATE_METADATA: Record<string, TemplateMetadata>;
 
 /**
  * Persistent Layers Expansion
@@ -20,7 +44,7 @@ export { D as DEFAULT_THEME, g as getAvailableThemes, b as getThemeSummaries, r
 /**
  * Expand all persistent layers in a config to raw Layer arrays.
  */
-declare function expandPersistentLayers(layers: PersistentLayer[] | undefined): Layer[];
+declare function expandPersistentLayers(layers: PersistentLayer[] | undefined, theme?: Theme): Layer[];
 /** Legacy style preset names. Prefer using `Theme.persistentLayers` directly. */
 type DocStylePreset = 'minimal' | 'documentary' | 'branded' | 'cinematic' | 'clean';
 /**
@@ -31,12 +55,41 @@ type DocStylePreset = 'minimal' | 'documentary' | 'branded' | 'cinematic' | 'cle
  * @param heroSrc - Optional hero image for cinematic style
  */
 declare function getDocStyleConfig(preset: DocStylePreset, articleTitle: string, heroSrc?: string, subtitle?: string): PersistentLayerConfig;
+/**
+ * Get persistent layers from a Theme. Returns the theme's baked-in
+ * persistentLayers config, or an empty config when the theme has none.
+ */
+declare function getPersistentLayersFromTheme(theme: Theme): PersistentLayerConfig;
+/**
+ * Resolve the effective persistent-layer config for a doc: the doc's own
+ * config wins **wholesale** when present; only docs with no persistent
+ * layers inherit the theme's.
+ *
+ * Doc-wins-wholesale (rather than merging) protects pre-baked documents
+ * that carry their own background/branding layers — merging a theme's
+ * atmosphere on top of those would double up backgrounds and stack
+ * overlays the doc author never saw.
+ */
+declare function resolvePersistentLayers(doc: {
+    persistentLayers?: PersistentLayerConfig;
+}, theme: Theme): PersistentLayerConfig | undefined;
+/**
+ * Compose a block's layers between pre-expanded persistent bottom/top
+ * layers, honoring the per-block `useBottomLayer` / `useTopLayer` opt-outs.
+ * Single shared implementation for `expandDocBlocks` and `getLayers`.
+ */
+declare function wrapWithPersistentLayers(layers: Layer[], block: {
+    useBottomLayer?: boolean;
+    useTopLayer?: boolean;
+}, bottomLayers: Layer[], topLayers: Layer[]): Layer[];
 
 /**
  * Title Block Template
  *
  * Large title with optional subtitle for doc intros.
- * Centered text with fade-in animations.
+ * 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.
@@ -74,8 +127,10 @@ declare function statHighlight(input: StatHighlightInput, context: TemplateConte
 /**
  * Quote Block Template
  *
- * Large centered quote with optional attribution.
- * Good for impactful statements or descriptions.
+ * 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.
@@ -88,8 +143,10 @@ declare function quoteBlock(input: QuoteBlockInput, context: TemplateContext): L
 /**
  * Fact Card Template
  *
- * Key fact with explanation and optional source.
- * Useful for presenting important information clearly.
+ * 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.
@@ -206,6 +263,8 @@ interface CoverBlockInput {
     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.
@@ -347,6 +406,328 @@ declare function videoPullQuote(input: VideoPullQuoteInput, context: TemplateCon
 
 declare function dataTable(input: DataTableInput, context: TemplateContext): Layer[];
 
+/**
+ * Diagram block template.
+ *
+ * Renders the parent block's children as a node-and-edge diagram:
+ * - Each child becomes a rounded-rect node card with its title as label.
+ * - Each `child.connectsTo` entry becomes a path edge (cubic-bezier curve
+ *   with an arrowhead at the target end).
+ * - Children with `x`/`y` set are placed at those coordinates; the rest
+ *   are auto-laid out below in a square-ish grid (see `diagramLayout.ts`).
+ *
+ * Layout coordinates from `x=`/`y=` are author-defined units. The
+ * template computes a bounding box of all nodes and scales it to fit
+ * the block's viewport with padding, so users don't have to think about
+ * absolute pixel ranges.
+ */
+
+declare function diagramBlock(input: DiagramBlockInput, context: TemplateContext): Layer[];
+
+/**
+ * Diagram layout — shared between the read-only SVG render path
+ * (`diagramBlock` template) and the interactive editor (React Flow in
+ * `@bendyline/squisq-editor-react`). Same children + same options always
+ * produce the same node positions and edge list, so previews and the
+ * editor stay visually consistent.
+ *
+ * Layout rules:
+ * 1. Children with both `x` and `y` set keep their authored coordinates.
+ * 2. Children missing either coordinate are auto-placed in a square-ish
+ *    grid in declaration order, offset below the bounding box of the
+ *    explicitly-positioned children.
+ * 3. Edges come from each child's `connectsTo`. Targets that don't match
+ *    any sibling id are dropped (and counted in `warnings`).
+ */
+
+interface DiagramNodePosition {
+    /** Block id (matches `Block.id`). */
+    id: string;
+    /** Display label (block title or fallback to id). */
+    label: string;
+    /** Pixel x coordinate (canvas-relative). */
+    x: number;
+    /** Pixel y coordinate (canvas-relative). */
+    y: number;
+    /** True when the position came from `x=`/`y=` attributes; false when auto-laid out. */
+    pinned: boolean;
+    /** Optional `.class` tokens carried over from the heading. */
+    classes?: string[];
+}
+interface DiagramEdge {
+    /** Synthetic stable edge id. */
+    id: string;
+    /** Source node id. */
+    source: string;
+    /** Target node id. */
+    target: string;
+    /** Connection type from `connectsTo=target:type` (used as edge label). */
+    type?: string;
+}
+interface DiagramLayout {
+    nodes: DiagramNodePosition[];
+    edges: DiagramEdge[];
+    warnings: string[];
+}
+interface DiagramLayoutOptions {
+    /** Horizontal grid pitch between auto-laid-out nodes. Default: 260 (node width 180 + 80 air). */
+    gapX?: number;
+    /** Vertical grid pitch between auto-laid-out nodes. Default: 140. */
+    gapY?: number;
+    /** Padding around the explicit-positions bounding box before the grid starts. Default: 80. */
+    gridPad?: number;
+    /** Origin x for the grid when no explicit nodes anchor it. Default: 80. */
+    gridOriginX?: number;
+    /** Origin y for the grid when no explicit nodes anchor it. Default: 80. */
+    gridOriginY?: number;
+}
+/**
+ * Compute node positions and edges for a diagram from a parent block's
+ * children. Pure function — same inputs always produce the same output.
+ */
+declare function computeDiagramLayout(children: readonly Block[], options?: DiagramLayoutOptions): DiagramLayout;
+
+/**
+ * Drawing block template.
+ *
+ * Renders the parent block's children as free-form shapes on a canvas:
+ * - Each child becomes a shape (`rect`/`circle` → ShapeLayer, `line`/
+ *   `arrow`/`path` → PathLayer, `text` → TextLayer) with its title as a
+ *   centered label and its body text as an optional sublabel.
+ * - `line`/`arrow` children with `from`/`to` (and any child's
+ *   `connectsTo`) become connectors clipped to the shapes they join.
+ *
+ * Coordinates from `x`/`y`/`width`/`height` are author-defined units; the
+ * template fits the bounding box of all shapes to the viewport with
+ * padding (same approach as `diagramBlock`), so authors don't think in
+ * absolute pixels.
+ */
+
+declare function drawingBlock(input: DrawingBlockInput, context: TemplateContext): Layer[];
+
+/**
+ * shapeGeometry — pure SVG geometry for the drawing/diagram shape vocabulary.
+ *
+ * Three concerns, all deterministic and dependency-free:
+ *  - `shapePath(kind, x, y, w, h)` → an SVG path `d` for a named shape inscribed
+ *    in a bounding box. Returns null for the natively-rendered primitives
+ *    (rect / circle / line / text / path) so the caller can keep using a
+ *    `ShapeLayer` for those; everything else becomes a computed `PathLayer`.
+ *  - `markerPath(style, dir)` → the `<marker>` path for a line end-style, in the
+ *    standard 0–10 marker viewBox (shared by the SSR `PathLayer` renderer and the
+ *    editor's edge renderer).
+ *  - `connectorPath(routing, start, end)` + `clipEndpoints(a, b)` → the line/edge
+ *    geometry between two shapes (straight / orthogonal / curved), lifted from the
+ *    diagram template so drawings and diagrams draw identical connectors.
+ */
+
+/** 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;
+}
+/** 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;
+    };
+};
+/** Build the SVG `d` for a connector between two clipped endpoints. */
+declare function connectorPath(routing: ConnectorRouting, start: {
+    x: number;
+    y: number;
+}, end: {
+    x: number;
+    y: number;
+}): string;
+/** Map a `lineStyle` (solid|dashed|dotted) to an SVG `stroke-dasharray`. */
+declare function lineStyleDasharray(style: string | undefined): string | undefined;
+
+/**
+ * Drawing layout — shared, pure derivation of shapes + connectors from a
+ * drawing block's child headings. Same children always produce the same
+ * shapes, so SSR previews, exports, and (eventually) the editor stay
+ * visually consistent. Mirrors `diagramLayout.ts` for the richer
+ * free-form shape vocabulary.
+ *
+ * Each child heading is one shape. Its `{[shape …]}` annotation names the
+ * primitive (`child.template`) and carries geometry/style as string params
+ * (`child.templateOverrides`); `child.id` makes it referenceable;
+ * `child.title` is the label.
+ *
+ * Layout rules (parallel to the diagram):
+ * 1. Shapes with both `x` and `y` keep their authored coordinates.
+ * 2. Shapes missing either are auto-placed in a square-ish grid below the
+ *    bounding box of the explicitly-positioned shapes.
+ * 3. `line`/`arrow` shapes with `from`/`to` (or any shape's `connectsTo`)
+ *    become connectors; endpoints that match no sibling id are dropped
+ *    (and counted in `warnings`).
+ */
+
+/**
+ * The shape kinds a drawing can render. `rect`/`circle`/`line` render as a
+ * native `ShapeLayer`; everything else (and `path`/`arrow`) renders as a
+ * computed `PathLayer` (see `shapeGeometry.ts`). `text` is a `TextLayer`.
+ */
+type DrawingShapeKind = 'rect' | 'circle' | 'line' | 'arrow' | 'path' | 'text' | 'triangle' | 'right-triangle' | 'diamond' | 'pentagon' | 'hexagon' | 'octagon' | 'star' | 'star4' | 'star6' | 'parallelogram' | 'trapezoid' | 'plus' | 'chevron' | 'arrow-right' | 'arrow-left' | 'arrow-up' | 'arrow-down' | 'double-arrow' | 'callout' | 'cylinder' | 'cloud' | 'heart' | 'lightning';
+/**
+ * Author-facing shape annotation names accepted on a drawing's children
+ * (the `{[…]}` token). Shared with validation so an unknown shape gets a
+ * "did you mean" suggestion. Aliases (`rectangle`→rect, `ellipse`→circle)
+ * are included.
+ */
+declare const SHAPE_NAMES: readonly ["rectangle", "rect", "square", "circle", "ellipse", "oval", "line", "arrow", "path", "text", "triangle", "right-triangle", "diamond", "rhombus", "pentagon", "hexagon", "octagon", "star", "star4", "star6", "parallelogram", "trapezoid", "plus", "cross", "chevron", "arrow-right", "arrow-left", "arrow-up", "arrow-down", "double-arrow", "callout", "speech", "cylinder", "cloud", "heart", "lightning", "bolt"];
+/**
+ * Resolve a child's `{[…]}` annotation name to a shape kind, or `null`
+ * when it isn't a shape. Case-insensitive.
+ */
+declare function normalizeShapeKind(name: string | undefined): DrawingShapeKind | null;
+/** True when `name` is an accepted shape annotation (any alias). */
+declare function isShapeName(name: string | undefined): boolean;
+/** A positioned shape in author-defined units (top-left origin). */
+interface DrawingShape {
+    id: string;
+    kind: DrawingShapeKind;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** True when position came from `x=`/`y=`; false when auto-laid out. */
+    pinned: boolean;
+    /** Heading text used as the shape's label ('' when none). */
+    label: string;
+    /** Body text under the heading, used as a sublabel (when present). */
+    sublabel?: string;
+    /** Text content for `text` shapes (`text=` param, else label, else body). */
+    text?: string;
+    /** Raw SVG path `d` for `path` shapes. */
+    d?: string;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    borderRadius?: number;
+    dasharray?: string;
+}
+/** A connector joining two shapes by id. */
+interface DrawingConnector {
+    id: string;
+    kind: 'line' | 'arrow';
+    /** Source shape id (resolved to an existing shape). */
+    from: string;
+    /** Target shape id (resolved to an existing shape). */
+    to: string;
+    /** Optional midpoint label (heading text, or `connectsTo` type). */
+    label?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    dasharray?: string;
+    /** End-of-line markers (default: `arrow` kind → filled arrow at `to`). */
+    startMarker: MarkerStyle;
+    endMarker: MarkerStyle;
+    /** How the line is routed between the two shapes. Default: 'straight'. */
+    routing: ConnectorRouting;
+}
+interface DrawingLayout {
+    shapes: DrawingShape[];
+    connectors: DrawingConnector[];
+    warnings: string[];
+}
+interface DrawingLayoutOptions {
+    /** Horizontal spacing between auto-laid-out shapes. Default: 180. */
+    gapX?: number;
+    /** Vertical spacing between auto-laid-out shapes. Default: 140. */
+    gapY?: number;
+    /** Padding below the explicit bounding box before the grid starts. Default: 80. */
+    gridPad?: number;
+    /** Grid origin when no explicit shapes anchor it. Default: 80, 80. */
+    gridOriginX?: number;
+    gridOriginY?: number;
+}
+/**
+ * Compute shapes + connectors for a drawing from its parent block's
+ * children. Pure — same inputs always produce the same output.
+ */
+declare function computeDrawingLayout(children: readonly Block[], options?: DrawingLayoutOptions): DrawingLayout;
+
+/**
+ * Layout block template.
+ *
+ * Renders the parent block's children as free-form, **absolutely
+ * positioned** layers on a canvas (text boxes, shapes, images). Unlike
+ * `drawingBlock`, coordinates are used as-is — there is no fit-to-viewport
+ * scaling — because a layout is a fixed-canvas composition.
+ *
+ * Each child is one layer: `### {#id} {[<type> x=.. y=.. …]}`. A text box's
+ * content lives in its child body as markdown (see `computeLayoutLayers`).
+ * Children render in document order (first child = back-most layer).
+ */
+
+declare function layoutBlock(input: TemplateBlock, context: TemplateContext): Layer[];
+
+interface LayoutLayersResult {
+    layers: Layer[];
+    warnings: string[];
+}
+interface LayoutLayerDefaults {
+    /**
+     * Default ink — text color and path/line stroke — used when the author
+     * omits `color=`/`stroke=`. `layoutBlock` passes the theme text color so
+     * un-styled text stays legible on dark themes; the editor's scene canvas
+     * omits it and gets the dark-slate default that suits its fixed light
+     * surface.
+     */
+    ink?: string;
+}
+/** Minimal Block shape this derivation reads (subset of `Block`). */
+interface LayoutChildBlock {
+    id: string;
+    template?: string;
+    templateOverrides?: Record<string, string>;
+    title?: string;
+    contents?: MarkdownNode[];
+}
+/**
+ * Map a layout block's children → positioned layers. Pure: same children
+ * always produce the same layers.
+ */
+declare function computeLayoutLayers(children: readonly LayoutChildBlock[], _viewport: {
+    width: number;
+    height: number;
+}, defaults?: LayoutLayerDefaults): LayoutLayersResult;
+
 /**
  * Accent Image Utility
  *
@@ -388,7 +769,7 @@ 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): Layer[];
+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.
@@ -435,10 +816,32 @@ declare const TEMPLATE_ALIASES: Readonly<Record<string, string>>;
  * input unchanged when no alias is registered.
  */
 declare function resolveTemplateName(name: string): string;
+/**
+ * Container templates render their parent block by consuming the block's
+ * child headings (via `context.children`) — `diagram` draws them as nodes,
+ * `drawing` as shapes, `layout` as absolutely-positioned layers. Those
+ * children are therefore NOT independently renderable slides/sections;
+ * render paths use {@link isContainerTemplate} to skip descending into
+ * them (see `flattenRenderableBlocks`).
+ */
+declare const CONTAINER_TEMPLATES: ReadonlySet<string>;
+/** True when `name` (or its alias) is a children-consuming container template. */
+declare function isContainerTemplate(name: string | undefined): boolean;
+/**
+ * Merge user-defined custom templates onto the built-in registry.
+ * Built-in names take precedence on collision — a user can't shadow
+ * `title` or `diagram` from a custom definition. Returns a frozen view
+ * so callers don't accidentally mutate the global registry.
+ */
+type RuntimeTemplateRegistry = Record<string, (input: TemplateBlock, ctx: TemplateContext) => Layer[]>;
+declare function buildRegistry(custom?: readonly CustomTemplateDefinition[]): RuntimeTemplateRegistry;
 /**
  * Expand a template block into a full Block with layers.
+ *
+ * `registry` lets callers swap in a registry that includes user-defined
+ * custom templates. Defaults to the built-in registry when omitted.
  */
-declare function expandTemplateBlock(templateBlock: TemplateBlock, context: TemplateContext): Block;
+declare function expandTemplateBlock(templateBlock: TemplateBlock, context: TemplateContext, registry?: RuntimeTemplateRegistry): Block;
 /**
  * Audio segment timing info for aligning blocks with audio.
  */
@@ -464,18 +867,13 @@ interface ExpandDocBlocksOptions {
      * 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[];
 }
-/**
- * Expand all template blocks in a doc, calculating start times.
- * Injects persistent layers (bottom/top) based on per-block flags.
- *
- * When audioSegments is provided, blocks are timed relative to their audio segment's
- * start time, ensuring blocks appear when their audio is playing. Blocks within each
- * segment are distributed proportionally across the segment duration.
- *
- * @param blocks - Array of template or raw blocks
- * @param options - Expansion options including theme, viewport, and persistent layers
- */
 declare function expandDocBlocks(blocks: DocBlock[], options?: ExpandDocBlocksOptions): Block[];
 /**
  * Get list of available template names.
@@ -515,7 +913,7 @@ declare function getDefaultAnimationDuration(type: AnimationType): number;
 /**
  * Get transition class for slide entry/exit.
  */
-declare function getTransitionClass(type: TransitionType, entering: boolean): string;
+declare function getTransitionClass(type: TransitionType, entering: boolean, direction?: TransitionDirection): string;
 /**
  * Calculate animation progress (0-1) based on current time.
  */
@@ -563,6 +961,21 @@ declare function scaleAnimationDuration(baseDuration: number, context: TemplateC
  * 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`.
@@ -572,6 +985,32 @@ 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.
@@ -583,6 +1022,126 @@ declare function getOverlayOpacity(context: TemplateContext): number;
  */
 declare function getTemplateHint<T extends string | number | boolean>(context: TemplateContext, templateName: string, key: string, fallback: T): T;
 
+/**
+ * Render-style post-pass — applies a theme's mechanical motion defaults to
+ * template-generated layers.
+ *
+ * This is the intent-free half of theme motion (see `themedEntrance` in
+ * [themeUtils.ts](./themeUtils.ts) for the intent-bearing half): it never
+ * decides *what kind* of entrance a layer gets, only
+ *
+ *  1. scales existing animation durations/delays by the theme's
+ *     `style.animationSpeed` multiplier (1.4 = calmer/slower, 0.7 = snappier,
+ *     1.0 = no-op), and
+ *  2. gives full-bleed cover imagery with no authored animation a gentle,
+ *     deterministic Ken Burns when the theme opts into ambient motion.
+ *
+ * Applied ONLY to template-generated layers — raw authored `block.layers`
+ * are never touched, and an explicit `animation` (including
+ * `{ type: 'none' }`) always wins.
+ */
+
+/**
+ * Whether the theme asks for ambient Ken Burns on otherwise-static imagery.
+ * `defaultImageAnimation: 'slowZoom'` is treated as an alias for the boolean
+ * (that's what themes authoring it were reaching for).
+ */
+declare function themeWantsAmbientMotion(theme: Theme): boolean;
+/**
+ * Apply the theme's mechanical motion defaults to a block's
+ * template-generated layers. Pure: returns new layer objects where a change
+ * applies and the original objects where none does.
+ *
+ * @param layers Template-generated layers (never raw authored layers)
+ * @param block  The source block — supplies the ambient-motion seed and duration
+ * @param theme  Resolved theme
+ */
+declare function applyRenderStyleToLayers(layers: Layer[], block: {
+    id: string;
+    duration?: number;
+}, theme: Theme): Layer[];
+
+/**
+ * Image treatment → CSS filter derivation.
+ *
+ * Treatments are theme-level photographic grades (see `ImageTreatment` in
+ * [Doc.ts](../../schemas/Doc.ts)). They compile to plain CSS `filter`
+ * functions so the same string works on a foreignObject `<img>`, an SVG
+ * `<image>` element, and in headless frame capture — no SVG filter defs to
+ * coordinate, no renderer-specific code paths.
+ */
+
+/**
+ * Build the CSS `filter` value for a treatment and/or blur.
+ * Returns `undefined` when there is nothing to apply.
+ */
+declare function cssFilterForTreatment(treatment?: ImageTreatment, blur?: number): string | undefined;
+
+/**
+ * Template input derivation — build a template's required inputs from a
+ * block's heading + markdown body.
+ *
+ * Used by:
+ * - `markdownToDoc`'s content-aware auto template picking, so an
+ *   auto-picked `quote`/`statHighlight`/`leftFeature` block carries the
+ *   inputs its template needs through every render path (player, linear
+ *   view, exports).
+ * - `LinearDocView` / editor previews, to render annotated blocks whose
+ *   authors didn't spell out every template param.
+ *
+ * Two modes:
+ * - strict (default): returns `null` when an essential input can't be
+ *   derived (no image for a feature block, no table for dataTable…) —
+ *   auto-picking uses this to fall back to the structural default.
+ * - placeholders: returns visible placeholder values instead of failing —
+ *   preview surfaces use this so a half-authored block still renders.
+ */
+
+/** First image discovered in a block's body, with explicit dimensions when present. */
+interface FirstImage {
+    src: string;
+    alt: string;
+    width?: number;
+    height?: number;
+}
+/** Plain text of a block's body contents (excluding the heading). */
+declare function extractBodyPlainText(contents?: MarkdownBlockNode[]): string;
+/** Extract list items as plain text. */
+declare function extractListItems(contents?: MarkdownBlockNode[]): string[];
+/**
+ * Find images referenced anywhere in block contents — both markdown
+ * shorthand `![alt](url)` (type `image`) and raw HTML `<img>` tags
+ * (type `htmlBlock`/`htmlInline`). The WYSIWYG editor emits the HTML form
+ * whenever a user resizes an image, so missing that path silently breaks
+ * every resized image.
+ *
+ * @param limit Stop after this many images (default: all).
+ */
+declare function extractImages(contents: MarkdownBlockNode[] | undefined, limit?: number): FirstImage[];
+/** First image in a block's body, or null. */
+declare function extractFirstImage(contents: MarkdownBlockNode[] | undefined): FirstImage | null;
+/** Extract table data (headers, rows, alignment) from block contents. */
+declare function extractTableFromContents(contents?: MarkdownBlockNode[]): {
+    headers: string[];
+    rows: string[][];
+    align?: (('left' | 'right' | 'center') | null)[];
+} | null;
+/** First blockquote's plain text, or ''. */
+declare function extractBlockquoteText(contents?: MarkdownBlockNode[]): string;
+interface DeriveTemplateInputsOptions {
+    /**
+     * Return visible placeholder values instead of `null` when an essential
+     * input can't be derived (preview surfaces). Default false (strict).
+     */
+    placeholders?: boolean;
+}
+/**
+ * Derive a template's inputs from a block's heading text and body nodes.
+ * Returns the input fields to merge onto the block, or `null` in strict
+ * mode when an essential input is missing.
+ */
+declare function deriveTemplateInputs(templateName: string, headingText: string, contents: MarkdownBlockNode[] | undefined, options?: DeriveTemplateInputsOptions): Record<string, unknown> | null;
+
 /**
  * Markdown → Doc Conversion
  *
@@ -626,28 +1185,43 @@ interface MarkdownToDocOptions {
      * 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;
 }
-/**
- * Convert a MarkdownDocument into a Doc with a heading-driven Block hierarchy.
- *
- * **Algorithm:**
- * 1. Walk the document's top-level children sequentially
- * 2. Each MarkdownHeading starts a new block at its depth level
- * 3. Non-heading nodes accumulate as `contents` on the current block
- * 4. Sub-headings (deeper depth) nest as `children` of the current block
- * 5. Same-level or shallower headings close the current block and start a sibling/ancestor
- * 6. Content before the first heading goes into a "preamble" block with no sourceHeading
- *
- * @param markdownDoc - A parsed MarkdownDocument
- * @param options - Conversion options
- * @returns A Doc whose blocks mirror the markdown heading structure
- */
 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).
  */
@@ -697,6 +1271,151 @@ declare function getBlockDepth(block: Block): number;
  */
 declare function docToMarkdown(doc: Doc): MarkdownDocument;
 
+/**
+ * Frontmatter serialization for user-defined custom templates (layouts).
+ *
+ * Custom template definitions live in the document's YAML frontmatter
+ * under the key `squisq-custom-templates`. They're stored as a single
+ * **compact JSON** object keyed by template name:
+ *
+ * ```yaml
+ * squisq-custom-templates: {"hero":{"lb":"Hero Section","ly":[{"ty":"text",…}]}}
+ * ```
+ *
+ * Squisq's frontmatter parser is line-based; a JSON object literal
+ * round-trips through it verbatim (no leading quote to strip, single
+ * line), so the value is written **unquoted** and stays human-readable
+ * and diffable — important for a codebase edited by people and agents.
+ *
+ * The JSON is kept small by:
+ *   - keying definitions by `name` (drops the `name` field + array wrapper),
+ *   - omitting the viewport when it's the 1920×1080 default,
+ *   - renaming well-known property names to two-letter codes via
+ *     {@link LONG_TO_SHORT} (e.g. `fontSize` → `fz`).
+ *
+ * The rename is a generic, recursive, bijective pass: **any property not
+ * in the map passes through unchanged**, so the format is lossless even
+ * as the Layer schema grows — new fields are simply stored under their
+ * full name until (optionally) added to the map.
+ *
+ * Back-compat: the reader still accepts the historical base64-of-JSON
+ * payload and a structured array, so older documents load unchanged.
+ * The first save migrates them to the compact form.
+ *
+ * The `encodeLayersForFrontmatter` / `decodeLayersFromFrontmatter` pair
+ * handles a single Layer array for the editor's `dataLayers="…"` Pandoc
+ * param path; that path stays base64 (it's a different, per-block
+ * mechanism) and is re-exported here for locality.
+ */
+
+/**
+ * Base64-encode a Layer array as JSON, UTF-8 safe. Used by the editor's
+ * per-block `dataLayers="…"` Pandoc param (not the doc-level template
+ * list, which uses the compact JSON above).
+ *
+ * `btoa` only accepts Latin1 strings — any character outside that range
+ * (e.g. an em-dash in a description) throws — so we round through
+ * `TextEncoder`. Works in Node ≥18 and browsers.
+ */
+declare function encodeLayersForFrontmatter(layers: readonly Layer[]): string;
+/** Inverse of {@link encodeLayersForFrontmatter}. Returns [] on parse failure. */
+declare function decodeLayersFromFrontmatter(encoded: string): Layer[];
+/**
+ * Read the `squisq-custom-templates` frontmatter key and decode it into
+ * an array of CustomTemplateDefinitions. Returns undefined when the key
+ * is absent or unparseable so callers can omit the field from the Doc.
+ *
+ * Accepts, in order: the compact JSON object (current), a base64-JSON
+ * string (legacy), and an already-structured array/object (in case a
+ * richer YAML parser delivers it). Malformed payloads return undefined
+ * rather than failing the whole doc load.
+ */
+declare function readCustomTemplatesFromFrontmatter(frontmatter: Record<string, unknown> | undefined): CustomTemplateDefinition[] | undefined;
+/**
+ * Encode a list of custom template definitions into the compact JSON
+ * object described in the module header. Returns undefined when the
+ * input list is empty so callers can leave the key off the output.
+ */
+declare function writeCustomTemplatesToFrontmatter(templates: readonly CustomTemplateDefinition[] | undefined): 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): string | undefined;
+
+/**
+ * Doc-scoped theme resolution.
+ *
+ * The theme analog of how `buildRegistry` resolves custom templates: pure and
+ * doc-scoped, with no global state. `resolveThemeForDoc` looks up the active
+ * theme id in the doc's own custom themes first, then falls back to the
+ * built-in / globally-registered themes via `resolveTheme`.
+ *
+ * It accepts either a squisq `Doc` (which carries a typed `customThemes`
+ * array) or anything with raw `frontmatter` — notably a `MarkdownDocument`,
+ * which is the shape every export pipeline pivots through. In the latter case
+ * the inline themes are decoded from the `squisq-custom-themes` frontmatter
+ * payload. Either way, resolution needs no `registerTheme` call — an inline
+ * custom theme ships with the doc, exactly like custom templates.
+ */
+
+/**
+ * The minimal shape `resolveThemeForDoc` needs. Satisfied by both the squisq
+ * `Doc` (typed `customThemes` + `themeId`) and a `MarkdownDocument` (raw
+ * `frontmatter` carrying the encoded payload).
+ */
+interface ThemeResolvable {
+    themeId?: string;
+    customThemes?: Theme[];
+    frontmatter?: Record<string, unknown>;
+}
+/**
+ * Resolve the Theme a document should render with.
+ *
+ * @param doc - the document (may carry inline custom themes plus a `themeId`
+ *   / `squisq-theme` frontmatter selector).
+ * @param explicitId - an id that overrides the doc's own selection (e.g. the
+ *   editor's theme dropdown, or an export `--theme` option). When omitted, the
+ *   doc's `themeId` / frontmatter theme id is used.
+ * @returns the matching inline custom theme (doc-scoped) when present, else
+ *   the built-in / registered theme for that id, else the default theme.
+ */
+declare function resolveThemeForDoc(doc: ThemeResolvable | null | undefined, explicitId?: string): Theme;
+
 /**
  * getLayers — Compute visual layers for a block on demand.
  *
@@ -794,4 +1513,151 @@ declare function scoreTextSimilarity(a: string, b: string): number;
  */
 declare function resolveAudioMapping(doc: Doc, container: ContentContainer): Promise<Doc>;
 
-export { type AccentLayout, type AudioSegmentTiming, type CoverBlockInput, DEFAULT_LAYOUT, DocBlock, type DocStylePreset, type ExpandDocBlocksOptions, type MarkdownToDocOptions, PersistentLayerConfig, type RenderContext, TEMPLATE_ALIASES, TemplateBlock, TemplateContext, Theme, ThemeColorScheme, ViewportConfig, adjustY, comparisonBar, countBlocks, coverBlock, createAccentLayers, dataTable, dateEvent, definitionCard, docToMarkdown, expandCoverBlock, expandDocBlocks, expandPersistentLayers, expandTemplateBlock, factCard, flattenBlocks, fullBleedQuote, getAccentLayout, getAnimationProgress, getAnimationStyle, getAvailableTemplates, getBlockDepth, getDefaultAnimation, getDefaultAnimationDuration, getDocStyleConfig, getLayers, getOverlayOpacity, getTemplateHint, getThemeFont, getTransitionClass, hasTemplate, imageWithCaption, leftFeature, listBlock, mapBlock, markdownToDoc, photoGrid, pullQuote, quoteBlock, resolveAudioMapping, resolveColorScheme, resolveTemplateName, rightFeature, scaleAnimationDuration, scoreTextSimilarity, sectionHeader, shouldUseShadow, statHighlight, templateRegistry, themedFontSize, titleBlock, twoColumn, videoPullQuote, videoWithCaption };
+/**
+ * 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]`, and
+ * `key:` followed by an indented `- item` block sequence whose items are
+ * scalars or inline arrays. Nested maps are rejected with a clear error —
+ * use a `json data` fence for deeply nested input.
+ */
+
+/**
+ * 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;
+/**
+ * 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;
+    /** The converted Doc (conversion diagnostics are included above). */
+    doc: Doc;
+}
+/**
+ * Validate a squisq markdown source string. Parses, converts (collecting
+ * the conversion's own diagnostics), and runs the structural checks above.
+ */
+declare function validateMarkdownSource(source: string, options?: ValidateOptions): MarkdownValidationResult;
+/**
+ * Validate an already-parsed MarkdownDocument. See {@link validateMarkdownSource}.
+ */
+declare function validateMarkdownDoc(markdownDoc: MarkdownDocument, options?: ValidateOptions): MarkdownValidationResult;
+
+/**
+ * Fallback Block Rendering
+ *
+ * The graceful-degradation guarantee: a block whose template can't render —
+ * unknown template name, template function threw, or returned a non-array —
+ * still renders its heading and body text as a plain, readable card instead
+ * of a blank slide. A small notice line names the problem so authors (and
+ * agents reviewing screenshots) can see *why* the block degraded.
+ *
+ * This is intentionally not a registered template: it can't be requested by
+ * name, only reached when a requested template fails. See `getLayers()`.
+ */
+
+/**
+ * Render a block's heading + body text as plain layers, with a notice line
+ * describing why the requested template didn't render.
+ *
+ * @param block   The block that failed to render via its template.
+ * @param context Template context (theme, viewport).
+ * @param notice  Short problem description, e.g. `Unknown template "photGrid"`.
+ */
+declare function fallbackBlockLayers(block: DocBlock, context: TemplateContext, notice: string): Layer[];
+
+export { type AccentLayout, type AudioSegmentTiming, CONTAINER_TEMPLATES, type ClipBox, type ConnectorRouting, type CoverBlockInput, DEFAULT_LAYOUT, type DataFenceParseResult, type DeriveTemplateInputsOptions, type DiagramEdge, type DiagramLayout, type DiagramLayoutOptions, type DiagramNodePosition, DocBlock, type DocStylePreset, type DrawingConnector, type DrawingLayout, type DrawingLayoutOptions, type DrawingShape, type DrawingShapeKind, type ExpandDocBlocksOptions, type ExtractedTableData, type FirstImage, type LayoutLayerDefaults, type LayoutLayersResult, type MarkdownToDocOptions, type MarkdownValidationResult, PATH_SHAPE_KINDS, PersistentLayerConfig, type RenderContext, type RuntimeTemplateRegistry, SHAPE_NAMES, TEMPLATE_ALIASES, TEMPLATE_METADATA, TemplateBlock, TemplateContext, type TemplateMetadata, Theme, ThemeColorScheme, type ValidateOptions, ViewportConfig, adjustY, applyRenderStyleToLayers, buildRegistry, clipEndpoints, clipPoint, 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, listBlock, mapBlock, markdownToDoc, markerPath, normalizeShapeKind, parseDataFence, parseYamlSubset, photoGrid, pullQuote, quoteBlock, readCustomTemplatesFromFrontmatter, readCustomThemesFromFrontmatter, resolveAudioMapping, resolveColorScheme, resolvePersistentLayers, resolveTemplateName, resolveThemeForDoc, rightFeature, scaleAnimationDuration, scoreTextSimilarity, sectionHeader, shapePath, shouldUseShadow, statHighlight, templateRegistry, themeWantsAmbientMotion, themedEntrance, themedFontSize, themedImageTreatment, themedScrim, themedSurfaceGradient, titleBlock, twoColumn, validateMarkdownDoc, validateMarkdownSource, videoPullQuote, videoWithCaption, wrapWithPersistentLayers, writeCustomTemplatesToFrontmatter, writeCustomThemesToFrontmatter };