@bendyline/squisq 2.7.1 → 2.9.0

package/dist/doc/index.d.ts

@@ -1875,6 +1875,23 @@ interface RichListItem {
     markdown: MarkdownBlockNode[];
     html?: string;
 }
+/**
+ * Render Markdown block nodes as the small, sanitized HTML subset accepted by
+ * `TextLayer.content.html`. This keeps structural content (especially lists
+ * and paragraph boundaries) intact when a slide template uses one rich text
+ * layer instead of the full React Markdown renderer.
+ *
+ * Raw HTML blocks deliberately fall through to escaped plain text. The text
+ * layer renderer sanitizes this projection again, but generated HTML should
+ * still be safe before it reaches that boundary.
+ */
+declare function renderMarkdownBlocksHtml(nodes: readonly MarkdownBlockNode[]): string;
+/**
+ * Number of newline characters to retain in a plain-text projection between
+ * two Markdown blocks. A normal block boundary gets the usual two newlines;
+ * parsed source with additional blank lines keeps the larger authored gap.
+ */
+declare function markdownBlockSeparatorLines(previous: MarkdownBlockNode, next: MarkdownBlockNode): number;
 /** Extract list items without discarding their inline Markdown formatting. */
 declare function extractRichListItems(contents?: MarkdownBlockNode[]): RichListItem[];
 /**
@@ -1976,8 +1993,9 @@ interface MarkdownToDocOptions {
      * StartBlockConfig is created with a title resolved in priority order:
      * frontmatter `title:`, the first occurrence of the shallowest heading
      * (H1, else H2, else H3, …), then {@link fileName}. If the document
-     * contains an image, the first image is used as the hero. Set to false to
-     * suppress automatic cover generation.
+     * contains an image, the first image is used as the hero. A frontmatter
+     * `subtitle:` overrides the usual first-paragraph subtitle. Set to false
+     * to suppress automatic cover generation.
      */
     generateCoverBlock?: boolean;
     /**
@@ -2137,6 +2155,13 @@ interface BuildPreviewDocOptions {
      * the placeholder block id.
      */
     documentTitle?: string;
+    /**
+     * Whether unused document images become standalone interleaved
+     * `imageWithCaption` slides (default true — the slideshow behavior).
+     * Consumers with a fixed cell budget (the dashboard projection) pass
+     * false so synthetic filler slides never compete with real blocks.
+     */
+    interleaveImages?: boolean;
 }
 /**
  * Derive a display title from a file name: strip any directory prefix and the
@@ -2417,6 +2442,653 @@ declare const PAGE_BASE_CSS = "\n/* \u2500\u2500 Base \u2500\u2500\u2500\u2500\u
  */
 declare function buildPageCss(theme?: Theme): string;
 
+/**
+ * Supplemental rich-media layout for slideshow blocks.
+ *
+ * Templates still own their no-media composition. When an explicitly
+ * selected text-first template also contains media that it did not consume,
+ * this module selects a second composition with a reserved media rectangle
+ * and maps the template's foreground into the companion content rectangle.
+ * The exhaustive per-template policy selects by viewport orientation, media
+ * aspect, and item count so placement does not depend on a template's name or
+ * incidental overlap between its layers.
+ */
+
+interface LayerRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+/**
+ * Dashboard cell zoom policy.
+ *
+ * A cell's "zoom" multiplies the type scale (`TemplateContext.fontScale`)
+ * its block renders with — the %-based composition still targets the cell,
+ * but titles and body text render 1.5×/2× so a sparse block fills its slot
+ * instead of floating in whitespace. Zoom is deliberately a CLOSED ladder
+ * (100% / 150% / 200%), and a dashboard uses at most TWO unique levels —
+ * base 1× plus one boost — so cells still read as consistently sized
+ * rather than each block being fitted independently.
+ *
+ * Levels come from three places, strongest first: an explicit `zoom` on a
+ * custom layout's cell definition (author intent — never changed), the
+ * automatic density pick (short text-led blocks get boosted; spatial,
+ * media, chart, and display-scaled templates always render 1×), and the
+ * `squisq-dashboard-zoom: off` frontmatter kill-switch that pins every
+ * non-explicit cell to 1×.
+ */
+/** The closed set of zoom multipliers a dashboard cell may render at. */
+declare const DASHBOARD_ZOOM_LEVELS: readonly [1, 1.5, 2];
+type DashboardZoomLevel = (typeof DASHBOARD_ZOOM_LEVELS)[number];
+/** Automatic zoom behavior: density-based boosts, or everything at 1×. */
+type DashboardZoomMode = 'auto' | 'off';
+/**
+ * Normalize an authored zoom value to a ladder level. Accepts multipliers
+ * (`1`, `1.5`, `2`) and percentages (`100`, `150`, `200`, `'200%'`).
+ * Returns undefined for anything off the ladder.
+ */
+declare function normalizeDashboardZoom(value: unknown): DashboardZoomLevel | undefined;
+/** One cell's input to the zoom policy. */
+interface DashboardZoomCandidate {
+    /** Resolved template name of the block in this cell. */
+    template?: string;
+    /** Plain-text length of the block's title + body. */
+    textLength: number;
+    /** Author-pinned level from the layout's cell definition. */
+    explicit?: DashboardZoomLevel;
+}
+/** The density pick for one cell, before the two-level quantization. */
+declare function desiredCellZoom(candidate: DashboardZoomCandidate): DashboardZoomLevel;
+/**
+ * Resolve every cell's final zoom level.
+ *
+ * Explicit levels are honored verbatim. Automatic picks are then
+ * quantized so the dashboard as a whole uses at most base 1× plus ONE
+ * boost level: when both 1.5× and 2× are wanted, the boost with the most
+ * cells wins (explicit pins count double so autos rally to the author's
+ * level; ties boost to 2×), and the other autos snap to it.
+ */
+declare function resolveDashboardZooms(candidates: readonly DashboardZoomCandidate[], mode: DashboardZoomMode): DashboardZoomLevel[];
+
+/**
+ * Dashboard layout model.
+ *
+ * A dashboard renders a document's blocks onto ONE canvas: a layout places
+ * N cells (as %-rects) over the canvas's content area, and each cell hosts
+ * one rendered block. Where `materializeBlockLayers` is the slide
+ * projection and `materializePageSections` is the page projection,
+ * `materializeDashboard` (in this directory) is the dashboard projection —
+ * this module holds the layout *definition* shape shared by built-in and
+ * user-authored layouts, plus the geometry helpers that resolve a
+ * definition against a concrete viewport.
+ *
+ * Positions are `%`-strings relative to the layout's CONTENT rect (the
+ * canvas minus the optional title band), mirroring the custom-template
+ * convention: one definition renders at any aspect ratio unchanged.
+ */
+
+/**
+ * One cell of a dashboard layout. `x`/`y`/`width`/`height` are `%`-strings
+ * relative to the content rect. `block` is an optional 1-based explicit
+ * block assignment ("render block N here"); cells without one fill in
+ * document order.
+ */
+interface DashboardCellDefinition {
+    x: string;
+    y: string;
+    width: string;
+    height: string;
+    /** 1-based candidate-block index this cell explicitly renders. */
+    block?: number;
+    /**
+     * Type-scale multiplier for the block rendered here: 1, 1.5, or 2
+     * (percent spellings 100/150/200 are accepted and normalized). Pins the
+     * cell's zoom and exempts it from the automatic density pick.
+     */
+    zoom?: number;
+}
+/** Where and how tall the optional document-title band renders. */
+interface DashboardTitleSlotDefinition {
+    /** Which canvas edge hosts the band. Default 'top'. */
+    placement: 'top' | 'bottom';
+    /** Band height as a `%`-string of the canvas height. Default '9%'. */
+    height: string;
+}
+/**
+ * A dashboard layout definition — JSON-serializable so built-ins and
+ * frontmatter-authored custom layouts share one schema.
+ */
+interface DashboardLayoutDefinition {
+    /** Slug id used by `squisq-dashboard-layout` (lowercase, hyphens). */
+    name: string;
+    /** Human-facing picker label. */
+    label: string;
+    description?: string;
+    /**
+     * Per-orientation cell arrays. `landscape` is required and defines the
+     * layout's capacity. Fallbacks when a variant is absent:
+     * square → landscape cells (%-stretch), portrait → transposed landscape.
+     * Variants that are present must match landscape's cell count.
+     */
+    cells: {
+        landscape: DashboardCellDefinition[];
+        portrait?: DashboardCellDefinition[];
+        square?: DashboardCellDefinition[];
+    };
+    /** Overrides the default title band when the doc shows a title. */
+    titleSlot?: DashboardTitleSlotDefinition;
+    /** False excludes the layout from auto-pick (picker-only). Default true. */
+    auto?: boolean;
+}
+interface DashboardLayoutValidationError {
+    path: string;
+    message: string;
+}
+interface DashboardLayoutValidationResult {
+    valid: boolean;
+    errors: DashboardLayoutValidationError[];
+    /** The normalized definition when `valid` is true. */
+    layout?: DashboardLayoutDefinition;
+}
+/** A resolved cell: canvas-unit rect plus the optional explicit pins. */
+interface ResolvedDashboardCell {
+    rect: LayerRect;
+    block?: number;
+    /** Author-pinned zoom level from the cell definition. */
+    zoom?: DashboardZoomLevel;
+}
+/**
+ * Validate an untrusted layout definition (frontmatter, host input) into a
+ * normalized {@link DashboardLayoutDefinition}. Never throws; malformed
+ * definitions come back as `{ valid: false, errors }`.
+ */
+declare function validateDashboardLayoutDefinition(input: unknown): DashboardLayoutValidationResult;
+/** Number of blocks the layout can display. */
+declare function layoutCapacity(def: DashboardLayoutDefinition): number;
+/**
+ * Swap each cell's axes (x↔y, width↔height) — the automatic portrait
+ * rendition for layouts that only define landscape cells. A row of cells
+ * becomes a column; grids become their transpose.
+ */
+declare function transposeCells(cells: readonly DashboardCellDefinition[]): DashboardCellDefinition[];
+/**
+ * Pick the orientation variant (with fallbacks) and resolve its `%`-strings
+ * against a concrete content rect, producing canvas-unit cell rects.
+ */
+declare function resolveLayoutCells(def: DashboardLayoutDefinition, orientation: ViewportOrientation, contentRect: LayerRect): ResolvedDashboardCell[];
+
+/**
+ * Built-in dashboard layouts.
+ *
+ * Built-ins use the exact same JSON-serializable schema as user-authored
+ * custom layouts (`squisq-dashboard-layouts` frontmatter), so pickers,
+ * validation, and the auto-pick ladder treat both uniformly. Gutters are
+ * baked into the `%` rects (the photoGrid convention) rather than being a
+ * separate spacing model.
+ */
+
+/**
+ * The built-in layout library, ordered by capacity — the auto-pick ladder
+ * walks this order. `hero-top` opts out of auto-pick (`auto: false`) so
+ * `grid-2x2` wins the 4-block case; it stays available in pickers.
+ */
+declare const BUILTIN_DASHBOARD_LAYOUTS: readonly DashboardLayoutDefinition[];
+/** Picker-facing summary of a layout. */
+interface DashboardLayoutSummary {
+    id: string;
+    label: string;
+    description?: string;
+    capacity: number;
+    /** True for layouts defined by the document rather than built in. */
+    custom: boolean;
+}
+/** Summaries of the built-in layouts, in ladder order. */
+declare function getDashboardLayoutSummaries(): DashboardLayoutSummary[];
+/**
+ * Every layout available to a document: its frontmatter-defined custom
+ * layouts first (they win name collisions), then the built-ins. This is
+ * the list pickers and CLI `--layout` validation enumerate.
+ */
+declare function listDashboardLayouts(doc: Pick<Doc, 'frontmatter'> | undefined): DashboardLayoutSummary[];
+
+/**
+ * Dashboard layout selection: id lookup plus the auto-pick ladder that
+ * chooses the smallest layout able to hold every block.
+ */
+
+/** The sentinel layout id meaning "pick the best layout for the doc". */
+declare const DASHBOARD_AUTO_LAYOUT_ID = "auto";
+/**
+ * Resolve a layout id against the document's custom layouts (which win
+ * name collisions) and then the built-ins. Undefined when unknown.
+ */
+declare function resolveDashboardLayoutDefinition(id: string, customLayouts?: readonly DashboardLayoutDefinition[]): DashboardLayoutDefinition | undefined;
+/**
+ * Auto-pick the best layout for a block count: the smallest-capacity
+ * auto-eligible layout that fits every block, preferring a custom layout
+ * over a built-in at equal capacity. When even the largest layout cannot
+ * hold the count, the largest wins and the caller reports the overflow.
+ *
+ * Orientation deliberately does not change WHICH layout wins — it selects
+ * the cell variant later (via `resolveLayoutCells`) so the same document
+ * keeps the same layout identity across aspect ratios.
+ */
+declare function chooseDashboardLayout(blockCount: number, _orientation: ViewportOrientation, customLayouts?: readonly DashboardLayoutDefinition[]): DashboardLayoutDefinition;
+
+/**
+ * Dashboard cell style — the "how it's dressed" axis, orthogonal to the
+ * layout's "where things go".
+ *
+ * A layout answers how many cells there are and what shape they take; a
+ * style answers what a cell LOOKS like: whether the block simply fills its
+ * rect (`basic`, the historical behavior), sits on a raised card, sits in a
+ * flat outlined panel, or on an accent-tinted card. Every style derives its
+ * colors, radius, and accents from the ACTIVE THEME (`colors`,
+ * `style.borderRadius`, `colorSchemes`), so a gezellig dashboard reads as
+ * gezellig and a tech-dark one reads as tech-dark — a style never carries
+ * its own palette.
+ *
+ * Geometry is core-owned like everything else in the dashboard pipeline:
+ * this module returns the card rect the block renders into plus the chrome
+ * layers painted behind it (CELL-LOCAL coordinates — the same space
+ * `materializeDashboard` hands renderers for the title band) and over it
+ * (CARD-LOCAL, so a host clips them with the card's own corner radius).
+ */
+
+/** The closed set of dashboard cell styles. */
+declare const DASHBOARD_STYLE_IDS: readonly ["basic", "card", "panel", "accent"];
+type DashboardStyleId = (typeof DASHBOARD_STYLE_IDS)[number];
+declare const DEFAULT_DASHBOARD_STYLE: DashboardStyleId;
+/** Picker-facing summary of a style (mirrors `DashboardLayoutSummary`). */
+interface DashboardStyleSummary {
+    id: DashboardStyleId;
+    label: string;
+    description: string;
+}
+/** The style library, in picker order. */
+declare const DASHBOARD_STYLES: readonly DashboardStyleSummary[];
+/** Normalize an authored style value; undefined when unrecognized. */
+declare function resolveDashboardStyleId(value: unknown): DashboardStyleId | undefined;
+/**
+ * The canvas fill behind the cells. Card-like styles tint it away from the
+ * card surface (down on light themes, up on dark ones) so cards read as
+ * raised rather than as invisible rectangles on matching paper; flat styles
+ * keep the theme background exactly.
+ */
+declare function dashboardCanvasFill(style: DashboardStyleId, theme: Theme): string;
+/**
+ * The accent color for cell `index`. Styles that show an accent rotate
+ * through the theme's own `colorSchemes` (insertion order — the same
+ * vocabulary page mode's `accentRotation` rotates), falling back to the
+ * palette's primary when a theme declares no schemes.
+ */
+declare function dashboardCellAccent(theme: Theme, index: number): string;
+/** The chrome + geometry a style contributes to one cell. */
+interface DashboardCellChrome {
+    /** Card rect in canvas units (the block fills exactly this box). */
+    cardRect: LayerRect;
+    /** Box the block renders into — identical to {@link cardRect}. */
+    contentRect: LayerRect;
+    /** Chrome layers painted BEHIND the block, in cell-local coordinates. */
+    layers: Layer[];
+    /**
+     * Chrome layers painted ON TOP of the block, in card-local coordinates
+     * (origin at the card rect, so a host can clip them with the card's own
+     * radius). Borders and accents live here: a template that paints its own
+     * opaque surface would otherwise bury them.
+     */
+    overlayLayers: Layer[];
+    /** Card corner radius in canvas units. */
+    radius: number;
+    /** CSS `border-radius` for the CONTENT box, percentage-based. */
+    contentRadiusPct?: string;
+}
+/**
+ * Build one cell's chrome. Returns null for `basic`, which paints nothing
+ * and leaves the block filling the layout's rect exactly as before.
+ *
+ * The block fills the CARD, rather than sitting in a padded well inside it:
+ * templates already carry their own internal padding, and many paint an
+ * opaque surface or gradient of their own. Letting that surface BE the card
+ * face is what keeps a card from reading as a box inside a box; the chrome
+ * contributes the elevation behind it and the border/accent over it.
+ *
+ * Elevation is drawn as stacked translucent rects rather than an SVG blur
+ * filter: it stays vector-pure, rasterizes identically in the player and in
+ * headless capture, and costs three shapes.
+ */
+declare function buildDashboardCellChrome(style: DashboardStyleId, options: {
+    theme: Theme;
+    rect: LayerRect;
+    index: number;
+}): DashboardCellChrome | null;
+/**
+ * Whether a block's own full-bleed theme-background layer should be
+ * dropped in this style. Card-like styles paint the surface themselves, so
+ * an opaque backdrop from the template would hide the card's tint and
+ * square off its corners. Only a fill that exactly matches the theme
+ * background is ever dropped — a template's accent or gradient backdrop is
+ * authored intent and stays.
+ */
+declare function stripsBlockBackdrop(style: DashboardStyleId): boolean;
+/**
+ * Remove a leading full-bleed rect whose fill is exactly the theme
+ * background. Matches `createBackgroundLayer`'s output shape.
+ */
+declare function stripBlockBackdropLayer(layers: readonly Layer[], theme: Theme): Layer[];
+
+/**
+ * Dashboard settings persisted in Markdown frontmatter.
+ *
+ * Framework-free (model: `coverSlideSettings.ts`) so the editor, player,
+ * and export pipelines resolve one canonical document contract:
+ *
+ * - `squisq-dashboard-layout`: layout id or `auto` (default `auto`).
+ * - `squisq-dashboard-title`: whether the document title band renders
+ *   (default true; the band only appears when a title actually resolves).
+ * - `squisq-dashboard-style`: cell style variant (default `basic`) — the
+ *   dressing axis that is orthogonal to the layout's geometry.
+ */
+
+interface DashboardSettings {
+    /** Preferred layout id, or {@link DASHBOARD_AUTO_LAYOUT_ID}. */
+    layout: string;
+    /** Whether the document-title band renders when a title resolves. */
+    showTitle: boolean;
+    /** Cell zoom behavior: density-based `auto` boosts, or `off` (all 1×). */
+    zoom: DashboardZoomMode;
+    /** Cell style variant (chrome around each block). */
+    style: DashboardStyleId;
+}
+declare const DASHBOARD_FRONTMATTER_KEYS: Readonly<{
+    layout: {
+        canonical: string;
+        legacy: string;
+    };
+    showTitle: {
+        canonical: string;
+        legacy: string;
+    };
+    zoom: {
+        canonical: string;
+        legacy: string;
+    };
+    style: {
+        canonical: string;
+        legacy: string;
+    };
+}>;
+declare const DEFAULT_DASHBOARD_SETTINGS: Readonly<DashboardSettings>;
+/**
+ * Caller overrides. `style` is deliberately widened to `string`: hosts pass
+ * raw CLI/UI values through, and an unrecognized one normalizes away rather
+ * than needing a cast at every call site.
+ */
+type DashboardSettingsOverrides = Partial<Omit<DashboardSettings, 'style'>> & {
+    style?: DashboardStyleId | string;
+};
+/** Resolve dashboard settings from frontmatter, then apply caller overrides. */
+declare function resolveDashboardSettings(frontmatter: Record<string, unknown> | undefined, overrides?: DashboardSettingsOverrides): DashboardSettings;
+
+/**
+ * Frontmatter serialization for user-defined dashboard layouts.
+ *
+ * Custom layout definitions live in the document's YAML frontmatter under
+ * `squisq-dashboard-layouts` as a single **compact JSON** object keyed by
+ * layout name (the exact convention `squisq-custom-templates` uses — see
+ * `customTemplatesFrontmatter.ts` for the rationale):
+ *
+ * ```yaml
+ * squisq-dashboard-layouts: {"kpi-wall":{"lb":"KPI Wall","ce":{"ls":[{"x":"0%","y":"0%","wd":"50%","hg":"100%","bk":1},…]}}}
+ * ```
+ *
+ * The value is written unquoted on a single line so the line-based
+ * frontmatter parser round-trips it verbatim. Well-known property names
+ * shrink to two-letter codes via {@link LONG_TO_SHORT}; unmapped keys pass
+ * through unchanged, so the format stays lossless as the schema grows.
+ */
+
+/** Canonical frontmatter key for custom dashboard layouts. */
+declare const FRONTMATTER_DASHBOARD_LAYOUTS_KEY = "squisq-dashboard-layouts";
+/**
+ * Read the `squisq-dashboard-layouts` key into validated layout
+ * definitions. Returns undefined when the key is absent or unparseable;
+ * individual malformed entries are dropped rather than failing the doc.
+ */
+declare function readDashboardLayoutsFromFrontmatter(frontmatter: Record<string, unknown> | undefined): DashboardLayoutDefinition[] | undefined;
+/**
+ * Encode layout definitions into the compact JSON object described in the
+ * module header. Returns undefined for an empty list so callers can omit
+ * the key entirely.
+ */
+declare function writeDashboardLayoutsToFrontmatter(layouts: readonly DashboardLayoutDefinition[] | undefined, options?: {
+    pretty?: boolean;
+}): string | undefined;
+
+/**
+ * Dashboard projection — the third sibling of the slide projection
+ * (`buildPreviewDoc` + `materializeBlockLayers`) and the page projection
+ * (`materializePageSections`).
+ *
+ * `materializeDashboard(doc, options)` turns a markdown-derived Doc into
+ * ONE canvas: a layout's cells (canvas-unit rects) each holding one block
+ * rendered AT the cell's size — a synthetic per-cell viewport, so
+ * templates re-compose for the cell's orientation and typography scales
+ * via `calculateFontScale` (the same strategy embedded spatial media uses
+ * inside `materializeBlockLayers`). Core owns every geometry decision;
+ * React consumers position cells with the CSS-ready `rectPct` values, and
+ * non-React consumers flatten everything into a single canvas-level
+ * `Layer[]` via {@link composeDashboardLayers}.
+ *
+ * Candidate blocks come from `buildPreviewDoc` (with image interleaving
+ * off) so template resolution and derived inputs match the slideshow
+ * exactly. Blocks beyond the layout's capacity are not rendered — that is
+ * reported as an `overflow` diagnostic, never a console side effect.
+ */
+
+interface MaterializeDashboardOptions {
+    /** Theme used by cell templates and the canvas backdrop. */
+    theme?: Theme;
+    /** Canvas viewport. Defaults to the landscape preset. */
+    viewport?: ViewportConfig;
+    /**
+     * Layout override: an id, {@link DASHBOARD_AUTO_LAYOUT_ID}, or an inline
+     * definition. Overrides the doc's `squisq-dashboard-layout` frontmatter.
+     */
+    layout?: string | DashboardLayoutDefinition;
+    /** Custom layouts; defaults to the doc's `squisq-dashboard-layouts`. */
+    customLayouts?: readonly DashboardLayoutDefinition[];
+    /** Document-scoped custom templates; defaults to `doc.customTemplates`. */
+    customTemplates?: readonly CustomTemplateDefinition[];
+    /** Title-band override; overrides `squisq-dashboard-title` frontmatter. */
+    showTitle?: boolean;
+    /** Host-supplied title fallback (file name), as in `buildPreviewDoc`. */
+    documentTitle?: string;
+    /** Cell zoom override; overrides `squisq-dashboard-zoom` frontmatter. */
+    zoom?: DashboardZoomMode;
+    /** Cell style override; overrides `squisq-dashboard-style` frontmatter. */
+    style?: DashboardStyleId | string;
+    /** Per-cell failure policy, forwarded to `materializeBlockLayers`. */
+    failureMode?: LayerMaterializationFailureMode;
+}
+/** CSS-ready percentages of the FULL canvas for absolute positioning. */
+interface DashboardRectPct {
+    left: string;
+    top: string;
+    width: string;
+    height: string;
+}
+/**
+ * A cell's style chrome — the card/panel surface painted BEHIND the block.
+ * Shaped like {@link DashboardTitle}: layers live in the frame's own
+ * viewport space, so a renderer positions one box and draws into it.
+ * Absent under the `basic` style, which paints no chrome at all.
+ */
+interface DashboardCellFrame {
+    /** The layout's full cell rect in canvas units (chrome's own box). */
+    rect: LayerRect;
+    /** The frame rect as percentages of the full canvas. */
+    rectPct: DashboardRectPct;
+    /** Viewport the chrome layers were composed against. */
+    viewport: ViewportConfig;
+    /** Chrome layers painted BEHIND the block, in frame-local coordinates. */
+    layers: Layer[];
+    /**
+     * Chrome layers painted ON TOP of the block — borders and accents, which
+     * a template's own opaque surface would otherwise bury. Composed against
+     * {@link DashboardCellFrame.overlayViewport} and positioned at the
+     * block's own rect, so the same clip rounds them to the card's corners.
+     */
+    overlayLayers: Layer[];
+    /** Viewport the overlay layers were composed against (the card box). */
+    overlayViewport: ViewportConfig;
+    /**
+     * CSS `border-radius` (percentage-based, so it scales with any rendered
+     * size) for the block's content box, matching the card's corners. React
+     * consumers apply it with `overflow: hidden` to clip full-bleed cell art.
+     */
+    contentRadiusPct?: string;
+}
+/** One populated dashboard cell. */
+interface DashboardCell {
+    /** Cell ordinal in the layout (0-based, layout order). */
+    index: number;
+    /** The projected slide block rendered in this cell. */
+    block: Block;
+    /** Index in the candidate block sequence (for keys/debugging). */
+    blockIndex: number;
+    /** Layers materialized against {@link DashboardCell.viewport} (un-prefixed). */
+    layers: Layer[];
+    /**
+     * The block's rect in canvas units. Equals the layout cell under `basic`;
+     * under a card style it is the cell inset by the card's padding ring.
+     */
+    rect: LayerRect;
+    /** Block rect as percentages of the full canvas. */
+    rectPct: DashboardRectPct;
+    /** Style chrome painted behind the block; absent under `basic`. */
+    frame?: DashboardCellFrame;
+    /** The synthetic per-cell viewport the layers were rendered against. */
+    viewport: ViewportConfig;
+    /**
+     * Type-scale multiplier the block rendered with (1, 1.5, or 2) — the
+     * layout stays cell-composed, but themed type renders this much larger
+     * so sparse blocks fill their slot. Already baked into `layers`.
+     */
+    zoom: DashboardZoomLevel;
+    source: LayerMaterializationSource;
+    diagnostic?: LayerMaterializationDiagnostic;
+}
+interface DashboardDiagnostic {
+    type: 'overflow' | 'unknown-layout' | 'invalid-cell-assignment' | 'empty-doc';
+    message: string;
+    /** Ids of blocks hidden by an `overflow`. */
+    hiddenBlockIds?: string[];
+    /** The unresolvable id behind an `unknown-layout`. */
+    requestedLayout?: string;
+}
+/** The rendered document-title band. */
+interface DashboardTitle {
+    text: string;
+    rect: LayerRect;
+    rectPct: DashboardRectPct;
+    viewport: ViewportConfig;
+    layers: Layer[];
+}
+interface DashboardMaterialization {
+    layout: DashboardLayoutDefinition;
+    layoutSource: 'option' | 'frontmatter' | 'auto';
+    /** The resolved cell style variant. */
+    style: DashboardStyleId;
+    viewport: ViewportConfig;
+    cells: DashboardCell[];
+    /** Null when the title band is disabled or no title resolves. */
+    title: DashboardTitle | null;
+    /** Canvas-level base fill + theme/doc persistent layers, applied once. */
+    backdrop: {
+        fill: string;
+        bottomLayers: Layer[];
+        topLayers: Layer[];
+    };
+    diagnostics: DashboardDiagnostic[];
+}
+declare function materializeDashboard(doc: Doc, options?: MaterializeDashboardOptions): DashboardMaterialization;
+/**
+ * Flatten a materialization into one canvas-level `Layer[]` for non-React
+ * consumers. Every cell/title layer is mapped into its canvas rect with a
+ * unique id prefix (templates reuse ids like `title`, so the prefix is
+ * what keeps the flat canvas collision-free). Paint order: backdrop
+ * bottom, then per cell its style chrome followed by its block, then the
+ * title band and the backdrop top.
+ *
+ * The flat canvas has no clipping concept, so a cell's full-bleed art is
+ * not rounded to its card corners here the way a React host clips it with
+ * `frame.contentRadiusPct`.
+ */
+declare function composeDashboardLayers(materialization: DashboardMaterialization): Layer[];
+
+/**
+ * Flashcard-mode projection.
+ *
+ * Flashcards are a study rendition of the existing heading-driven Block tree,
+ * not a visual template. The projection keeps rich Markdown nodes and nested
+ * blocks intact so React and future exporters can render the same authored
+ * content without reducing cards to strings.
+ */
+
+type FlashcardKind = 'basic' | 'multiple-choice';
+type FlashcardSourceMode = 'auto' | 'explicit';
+interface FlashcardFace {
+    /** Blocks rendered on this face, in source order. */
+    blocks: Block[];
+}
+interface FlashcardChoice {
+    id: string;
+    sourceBlockId: string;
+    content: FlashcardFace;
+    correct: boolean;
+}
+interface Flashcard {
+    id: string;
+    sourceBlockId: string;
+    kind: FlashcardKind;
+    /** Optional parent heading used as a compact deck/category label. */
+    label?: string;
+    front: FlashcardFace;
+    /** Basic-card answer, or the correct answer for a multiple-choice card. */
+    back: FlashcardFace;
+    choices?: FlashcardChoice[];
+    /** Parent-owned body shown after reveal/grading for multi-child cards. */
+    explanation?: FlashcardFace;
+}
+type FlashcardDiagnosticCode = 'empty-front' | 'empty-back' | 'multiple-choice-needs-distractor' | 'multiple-correct-answers';
+interface FlashcardDiagnostic {
+    severity: 'warning' | 'error';
+    code: FlashcardDiagnosticCode;
+    message: string;
+    blockId: string;
+}
+interface FlashcardDeck {
+    title?: string;
+    cards: Flashcard[];
+    diagnostics: FlashcardDiagnostic[];
+}
+interface MaterializeFlashcardsOptions {
+    /**
+     * `auto` (default) discovers card-shaped blocks and honors explicit study
+     * metadata. `explicit` includes only blocks marked `study=flashcard` or
+     * `study=multiple-choice-flashcard` (and their class/template aliases).
+     */
+    source?: FlashcardSourceMode;
+}
+type FlashcardMarker = FlashcardKind | 'group';
+/** Resolve an authored study marker without changing the visual template model. */
+declare function resolveFlashcardMarker(block: Block): FlashcardMarker | undefined;
+/** Convert a nested Doc into a deterministic study deck. */
+declare function materializeFlashcards(doc: Doc, options?: MaterializeFlashcardsOptions): FlashcardDeck;
+
 /**
  * Audio Mapping
  *
@@ -3239,4 +3911,4 @@ 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, BLOCK_MEDIA_LAYOUT_POLICIES, type BlockLayerMaterialization, type BlockMediaLayoutPolicy, type BuildPreviewDocOptions, type BuiltInTemplateName, CONTAINER_TEMPLATES, COVER_SLIDE_FRONTMATTER_KEYS, COVER_SLIDE_TEMPLATE_OPTIONS, type ClipBox, type ConnectorAnchor, type ConnectorPort, type ConnectorRouting, type ConnectorSnapPoint, type CoverBlockInput, type CoverSlidePlayback, type CoverSlideSettings, type CoverSlideTemplate, type CoverSlideTemplateOption, DEFAULT_COVER_SLIDE_SETTINGS, 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 EmbeddedVideo, type ExpandDocBlocksOptions, type ExtractedTableData, type FirstImage, type InputCoercion, type LayerMaterializationDiagnostic, type LayerMaterializationFailureMode, type LayerMaterializationSource, type LayoutLayerDefaults, type LayoutLayersResult, MAX_COVER_SLIDE_DURATION_SECONDS, type MarkdownToDocOptions, type MarkdownValidationResult, type MaterializeBlockLayersOptions, type NarrationResolution, type NativeMediaLayout, type NoMediaLayout, PAGE_BASE_CSS, PATH_SHAPE_KINDS, PageSection, type PageSectionContext, type PageSectionDraft, PersistentLayerConfig, type RenderAsciiDiagramOptions, type RenderAsciiTimelineOptions, type RenderTreeOptions, type RepairResult, type ResolvedPageBlock, type RichListItem, type RuntimeTemplateRegistry, SHAPE_NAMES, type SectionExtractor, type SupplementalMediaLayoutVariant, type SupplementalMediaShape, type SupplementalMediaVariantMatrix, TABLE_FED_TEMPLATES, TEMPLATE_AUTHORING_METADATA, TEMPLATE_INPUT_DESCRIPTORS, TEMPLATE_METADATA, TREE_FENCE_LANGS, type TemplateAuthoringMetadata, type TemplateAuthoringRole, TemplateBlock, type TemplateBodyPolicy, TemplateContext, type TemplateInputDescriptor, type TemplateMediaOwnership, type TemplateMetadata, type TemplateParamFinding, Theme, ThemeColorScheme, type Tree, type TreeDetection, type TreeItem, type TreeNode, type UnconsumedMediaBehavior, type ValidateOptions, ViewportConfig, ViewportOrientation, adjustY, anchorPoint, applyNarrationTiming, applyRenderStyleToLayers, asciiCellToCanvas, asciiDiagramFromBlocks, asciiDiagramFromTemplateData, asciiDiagramToTemplateData, asciiTimelineToTemplateData, autoTemplatePreservesContent, bigText, buildPageCss, buildPageCssVars, buildPreviewDoc, buildRegistry, canvasToAsciiCell, clipEndpoints, clipPoint, coerceTemplateParams, comparisonBar, computeDiagramLayout, computeDrawingLayout, computeLayoutLayers, connectorPath, contentBlock, countBlocks, coverBlock, createAccentLayers, cssFilterForTreatment, dataTable, dateEvent, definitionCard, deriveTemplateInputs, detectAsciiDiagram, detectAsciiTimeline, detectTree, diagramBlock, docToMarkdown, documentTitleFromFileName, drawingBlock, expandCoverBlock, expandDocBlocks, expandPersistentLayers, extractBlockquoteText, extractBodyPlainText, extractEmbeddedVideos, extractFirstEmbeddedVideo, extractFirstImage, extractImages, extractListItems, extractRichListItems, extractTableData, extractTableFromContents, factCard, fallbackBlockLayers, findFirstList, findFirstTable, fitBigTextSize, fitDiagramLabel, flattenBlocks, flattenRenderableBlocks, fullBleedQuote, getAccentLayout, getAnimationProgress, getAnimationStyle, getAvailableTemplates, getBlockBodyText, getBlockDepth, getBlockMediaLayoutPolicy, getDefaultAnimation, getDefaultAnimationDuration, getOverlayOpacity, getPersistentLayersFromTheme, getPinnedBlockMeta, getTemplateHint, getThemeFont, getTransitionClass, hasTemplate, imageWithCaption, isAsciiDiagramFence, isAsciiTimelineFence, isContainerTemplate, isDataFence, isEligibleAsciiFenceLang, isEligibleAsciiTimelineFenceLang, isEligibleTreeFenceLang, isExplicitDiagramLang, isExplicitTimelineLang, isExplicitTreeLang, isRepairableDiagram, isShapeName, isTemplatedPageBlock, isTreeFence, isWrappedFlowTimelineSource, layoutBlock, leftFeature, lineStyleDasharray, lintTemplateParams, listBlock, mapBlock, markdownToDoc, markerPath, materializeBlockLayers, nearestSnapPoint, normalizeShapeKind, pageStyleDataAttributes, parseAsciiDiagram, parseAsciiTimeline, parseAsciiTimelineWithStats, parseDataFence, parseTree, parseWrappedFlowTimeline, parseYamlSubset, photoGrid, pullQuote, quoteBlock, readCustomTemplatesFromFrontmatter, readCustomThemesFromFrontmatter, renderAsciiDiagram, renderAsciiTimeline, renderTree, repairAsciiDiagram, replaceDataFence, resolveAudioMapping, resolveColorScheme, resolveCoverSlideSettings, resolvePageBlock, resolvePersistentLayers, resolveTemplateName, resolveThemeForDoc, rightFeature, scaleAnimationDuration, scoreTextSimilarity, sectionExtractors, 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 };
+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, BLOCK_MEDIA_LAYOUT_POLICIES, BUILTIN_DASHBOARD_LAYOUTS, type BlockLayerMaterialization, type BlockMediaLayoutPolicy, type BuildPreviewDocOptions, type BuiltInTemplateName, CONTAINER_TEMPLATES, COVER_SLIDE_FRONTMATTER_KEYS, COVER_SLIDE_TEMPLATE_OPTIONS, type ClipBox, type ConnectorAnchor, type ConnectorPort, type ConnectorRouting, type ConnectorSnapPoint, type CoverBlockInput, type CoverSlidePlayback, type CoverSlideSettings, type CoverSlideTemplate, type CoverSlideTemplateOption, DASHBOARD_AUTO_LAYOUT_ID, DASHBOARD_FRONTMATTER_KEYS, DASHBOARD_STYLES, DASHBOARD_STYLE_IDS, DASHBOARD_ZOOM_LEVELS, DEFAULT_COVER_SLIDE_SETTINGS, DEFAULT_DASHBOARD_SETTINGS, DEFAULT_DASHBOARD_STYLE, DEFAULT_LAYOUT, DIAGRAM_LABEL_HORIZONTAL_PADDING, DIAGRAM_LABEL_LINE_HEIGHT, DIAGRAM_LABEL_MIN_FONT_SIZE, DIAGRAM_LABEL_VERTICAL_PADDING, type DashboardCell, type DashboardCellChrome, type DashboardCellDefinition, type DashboardCellFrame, type DashboardDiagnostic, type DashboardLayoutDefinition, type DashboardLayoutSummary, type DashboardLayoutValidationError, type DashboardLayoutValidationResult, type DashboardMaterialization, type DashboardRectPct, type DashboardSettings, type DashboardSettingsOverrides, type DashboardStyleId, type DashboardStyleSummary, type DashboardTitle, type DashboardTitleSlotDefinition, type DashboardZoomCandidate, type DashboardZoomLevel, type DashboardZoomMode, 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 EmbeddedVideo, type ExpandDocBlocksOptions, type ExtractedTableData, FRONTMATTER_DASHBOARD_LAYOUTS_KEY, type FirstImage, type Flashcard, type FlashcardChoice, type FlashcardDeck, type FlashcardDiagnostic, type FlashcardDiagnosticCode, type FlashcardFace, type FlashcardKind, type FlashcardSourceMode, type InputCoercion, type LayerMaterializationDiagnostic, type LayerMaterializationFailureMode, type LayerMaterializationSource, type LayoutLayerDefaults, type LayoutLayersResult, MAX_COVER_SLIDE_DURATION_SECONDS, type MarkdownToDocOptions, type MarkdownValidationResult, type MaterializeBlockLayersOptions, type MaterializeDashboardOptions, type MaterializeFlashcardsOptions, type NarrationResolution, type NativeMediaLayout, type NoMediaLayout, PAGE_BASE_CSS, PATH_SHAPE_KINDS, PageSection, type PageSectionContext, type PageSectionDraft, PersistentLayerConfig, type RenderAsciiDiagramOptions, type RenderAsciiTimelineOptions, type RenderTreeOptions, type RepairResult, type ResolvedDashboardCell, type ResolvedPageBlock, type RichListItem, type RuntimeTemplateRegistry, SHAPE_NAMES, type SectionExtractor, type SupplementalMediaLayoutVariant, type SupplementalMediaShape, type SupplementalMediaVariantMatrix, TABLE_FED_TEMPLATES, TEMPLATE_AUTHORING_METADATA, TEMPLATE_INPUT_DESCRIPTORS, TEMPLATE_METADATA, TREE_FENCE_LANGS, type TemplateAuthoringMetadata, type TemplateAuthoringRole, TemplateBlock, type TemplateBodyPolicy, TemplateContext, type TemplateInputDescriptor, type TemplateMediaOwnership, type TemplateMetadata, type TemplateParamFinding, Theme, ThemeColorScheme, type Tree, type TreeDetection, type TreeItem, type TreeNode, type UnconsumedMediaBehavior, type ValidateOptions, ViewportConfig, ViewportOrientation, adjustY, anchorPoint, applyNarrationTiming, applyRenderStyleToLayers, asciiCellToCanvas, asciiDiagramFromBlocks, asciiDiagramFromTemplateData, asciiDiagramToTemplateData, asciiTimelineToTemplateData, autoTemplatePreservesContent, bigText, buildDashboardCellChrome, buildPageCss, buildPageCssVars, buildPreviewDoc, buildRegistry, canvasToAsciiCell, chooseDashboardLayout, clipEndpoints, clipPoint, coerceTemplateParams, comparisonBar, composeDashboardLayers, computeDiagramLayout, computeDrawingLayout, computeLayoutLayers, connectorPath, contentBlock, countBlocks, coverBlock, createAccentLayers, cssFilterForTreatment, dashboardCanvasFill, dashboardCellAccent, dataTable, dateEvent, definitionCard, deriveTemplateInputs, desiredCellZoom, detectAsciiDiagram, detectAsciiTimeline, detectTree, diagramBlock, docToMarkdown, documentTitleFromFileName, drawingBlock, expandCoverBlock, expandDocBlocks, expandPersistentLayers, extractBlockquoteText, extractBodyPlainText, extractEmbeddedVideos, extractFirstEmbeddedVideo, extractFirstImage, extractImages, extractListItems, extractRichListItems, extractTableData, extractTableFromContents, factCard, fallbackBlockLayers, findFirstList, findFirstTable, fitBigTextSize, fitDiagramLabel, flattenBlocks, flattenRenderableBlocks, fullBleedQuote, getAccentLayout, getAnimationProgress, getAnimationStyle, getAvailableTemplates, getBlockBodyText, getBlockDepth, getBlockMediaLayoutPolicy, getDashboardLayoutSummaries, getDefaultAnimation, getDefaultAnimationDuration, getOverlayOpacity, getPersistentLayersFromTheme, getPinnedBlockMeta, getTemplateHint, getThemeFont, getTransitionClass, hasTemplate, imageWithCaption, isAsciiDiagramFence, isAsciiTimelineFence, isContainerTemplate, isDataFence, isEligibleAsciiFenceLang, isEligibleAsciiTimelineFenceLang, isEligibleTreeFenceLang, isExplicitDiagramLang, isExplicitTimelineLang, isExplicitTreeLang, isRepairableDiagram, isShapeName, isTemplatedPageBlock, isTreeFence, isWrappedFlowTimelineSource, layoutBlock, layoutCapacity, leftFeature, lineStyleDasharray, lintTemplateParams, listBlock, listDashboardLayouts, mapBlock, markdownBlockSeparatorLines, markdownToDoc, markerPath, materializeBlockLayers, materializeDashboard, materializeFlashcards, nearestSnapPoint, normalizeDashboardZoom, normalizeShapeKind, pageStyleDataAttributes, parseAsciiDiagram, parseAsciiTimeline, parseAsciiTimelineWithStats, parseDataFence, parseTree, parseWrappedFlowTimeline, parseYamlSubset, photoGrid, pullQuote, quoteBlock, readCustomTemplatesFromFrontmatter, readCustomThemesFromFrontmatter, readDashboardLayoutsFromFrontmatter, renderAsciiDiagram, renderAsciiTimeline, renderMarkdownBlocksHtml, renderTree, repairAsciiDiagram, replaceDataFence, resolveAudioMapping, resolveColorScheme, resolveCoverSlideSettings, resolveDashboardLayoutDefinition, resolveDashboardSettings, resolveDashboardStyleId, resolveDashboardZooms, resolveFlashcardMarker, resolveLayoutCells, resolvePageBlock, resolvePersistentLayers, resolveTemplateName, resolveThemeForDoc, rightFeature, scaleAnimationDuration, scoreTextSimilarity, sectionExtractors, sectionHeader, shapePath, shouldUseShadow, snapEndpoints, snapPoints, statHighlight, stripBlockBackdropLayer, stripsBlockBackdrop, templateRegistry, themeWantsAmbientMotion, themedEntrance, themedFontSize, themedImageTreatment, themedScrim, themedSurfaceGradient, timelineBlock, titleBlock, transposeCells, treeBlock, treeFromMarkdownList, treeFromTemplateData, treeToTemplateData, twoColumn, validateDashboardLayoutDefinition, validateMarkdownDoc, validateMarkdownSource, videoPullQuote, videoWithCaption, wrapWithPersistentLayers, writeCustomTemplatesToFrontmatter, writeCustomThemesToFrontmatter, writeDashboardLayoutsToFrontmatter };