@bendyline/squisq 0.1.1

package/dist/story/index.d.ts

@@ -0,0 +1,691 @@
+import { z as PersistentLayer, L as Layer, E as PersistentLayerConfig, a9 as TitleBlockInput, $ as TemplateContext, U as SectionHeaderInput, Y as StatHighlightInput, S as QuoteBlockInput, F as FactCardInput, ad as TwoColumnInput, m as DateEventInput, t as ImageWithCaptionInput, M as MapBlockInput, X as StartBlockConfig, r as FullBleedQuoteInput, v as ListBlockInput, N as PhotoGridInput, o as DefinitionCardInput, h as ComparisonBarInput, R as PullQuoteInput, ah as VideoWithCaptionInput, ag as VideoPullQuoteInput, A as AccentImage, a as AccentPosition, a4 as Theme, ai as ViewportConfig, q as DocBlock, B as Block, _ as TemplateBlock, a1 as TemplateRegistry, b as Animation, c as AnimationType, ac as TransitionType, a6 as ThemeColorScheme, p as Doc } from '../themeLibrary-DySHPcgj.js';
+export { j as DEFAULT_THEME, u as LayoutHints, T as RenderStyle, a5 as ThemeColorPalette, a7 as ThemeStyle, a8 as ThemeTypography, ae as VIEWPORT_PRESETS, aj as ViewportOrientation, ak as ViewportPreset, an as createTemplateContext, aq as getAvailableThemes, at as getLayoutHints, aw as getThemeSummaries, ax as getTwoColumnPositions, ay as getViewport, az as getViewportOrientation, aB as isTemplateBlock, aD as resolveTheme, aE as scaledFontSize } from '../themeLibrary-DySHPcgj.js';
+import { p as MarkdownHeading, l as MarkdownDocument } from '../types-DHiv_Pnm.js';
+
+/**
+ * Persistent Layers Expansion
+ *
+ * Expands persistent layer templates (solid backgrounds, gradients, overlays)
+ * into raw Layer arrays. These layers are injected into each block based on
+ * per-block flags (useBottomLayer, useTopLayer).
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ *
+ * Related Files:
+ * - schemas/BlockTemplates.ts - PersistentLayerConfig types
+ */
+
+/**
+ * Expand all persistent layers in a config to raw Layer arrays.
+ */
+declare function expandPersistentLayers(layers: PersistentLayer[] | undefined): Layer[];
+/** Legacy style preset names. Prefer using `Theme.persistentLayers` directly. */
+type DocStylePreset = 'minimal' | 'documentary' | 'branded' | 'cinematic' | 'clean';
+/**
+ * Get a PersistentLayerConfig from a style preset.
+ *
+ * @param preset - Style preset name
+ * @param articleTitle - Article title for title caption
+ * @param heroSrc - Optional hero image for cinematic style
+ */
+declare function getDocStyleConfig(preset: DocStylePreset, articleTitle: string, heroSrc?: string, subtitle?: string): PersistentLayerConfig;
+
+/**
+ * Title Block Template
+ *
+ * Large title with optional subtitle for doc intros.
+ * Centered text with fade-in animations.
+ * Adapts font sizes and positioning for different viewports.
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+declare function titleBlock(input: TitleBlockInput, context: TemplateContext): Layer[];
+
+/**
+ * Section Header Template
+ *
+ * Section title card with optional background image.
+ * Used to introduce new sections of a story.
+ * When an image is provided, displays like a title slide with the image as background.
+ * Without an image, falls back to a colored background.
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+declare function sectionHeader(input: SectionHeaderInput, context: TemplateContext): Layer[];
+
+/**
+ * Stat Highlight Template
+ *
+ * Large statistic/number with description and optional detail.
+ * Great for emphasizing key data points.
+ * Adapts font sizes and positioning for different viewports.
+ *
+ * Supports optional accent images that appear as tasteful side/bottom strips.
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+declare function statHighlight(input: StatHighlightInput, context: TemplateContext): Layer[];
+
+/**
+ * Quote Block Template
+ *
+ * Large centered quote with optional attribution.
+ * Good for impactful statements or descriptions.
+ * Adapts font sizes and positioning for different viewports.
+ *
+ * Supports optional accent images that appear as tasteful side/bottom strips.
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+declare function quoteBlock(input: QuoteBlockInput, context: TemplateContext): Layer[];
+
+/**
+ * Fact Card Template
+ *
+ * Key fact with explanation and optional source.
+ * Useful for presenting important information clearly.
+ * Adapts font sizes and positioning for different viewports.
+ *
+ * Supports optional accent images that appear as tasteful side/bottom strips.
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+declare function factCard(input: FactCardInput, context: TemplateContext): Layer[];
+
+/**
+ * Two Column Template
+ *
+ * Side-by-side comparison of two items.
+ * Each column has a label and optional sublabel.
+ * Adapts font sizes and positioning for different viewports.
+ *
+ * Portrait mode: Stacks columns vertically (top/bottom) instead of side-by-side.
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+declare function twoColumn(input: TwoColumnInput, context: TemplateContext): Layer[];
+
+/**
+ * Date Event Template
+ *
+ * Timeline-style slide with prominent date and description.
+ * Supports different moods: neutral, somber, celebratory.
+ * Adapts font sizes and positioning for different viewports.
+ *
+ * Supports optional accent images that appear as tasteful side/bottom strips.
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+declare function dateEvent(input: DateEventInput, context: TemplateContext): Layer[];
+
+/**
+ * Image With Caption Template
+ *
+ * Full-screen background image with text overlay.
+ * Supports Ken Burns animation effects (zoom, pan).
+ * Adapts caption positioning and font sizes for different viewports.
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+declare function imageWithCaption(input: ImageWithCaptionInput, context: TemplateContext): Layer[];
+
+/**
+ * Map Block Template
+ *
+ * Full-screen geographic map with optional title and caption overlays.
+ * Great for establishing geographic context at the start of a doc
+ * or when discussing location-specific content.
+ * Adapts font sizes and positioning for different viewports.
+ *
+ * Map tiles are fetched from free/open-source providers.
+ * See docs/MAP_TILES.md for available styles and attribution requirements.
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+declare function mapBlock(input: MapBlockInput, context: TemplateContext): Layer[];
+
+/**
+ * Cover Block Template
+ *
+ * Full-screen hero image with title overlay, shown before playback starts.
+ * This is the "poster for the doc, displaying the
+ * article's hero image with elegant title treatment.
+ *
+ * Features:
+ * - Full-screen hero image with Ken Burns ambient motion
+ * - Gradient overlay for text readability
+ * - Large centered title with optional subtitle
+ * - No animation delays (shown at rest, not during playback)
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+/**
+ * Input for coverBlock template - matches StartBlockConfig
+ */
+interface CoverBlockInput {
+    /** Path to hero image */
+    heroSrc: string;
+    /** Alt text for the hero image */
+    heroAlt?: string;
+    /** Title to display over the hero */
+    title: string;
+    /** Optional subtitle */
+    subtitle?: string;
+    /** Ambient motion for the hero image */
+    ambientMotion?: 'zoomIn' | 'zoomOut' | 'panLeft' | 'panRight';
+    /** Photo credit / artist name */
+    heroCredit?: string;
+    /** License identifier */
+    heroLicense?: string;
+}
+/**
+ * Generate cover block layers from StartBlockConfig.
+ */
+declare function coverBlock(input: CoverBlockInput, context: TemplateContext): Layer[];
+/**
+ * Expand a StartBlockConfig into a renderable Block.
+ * This is used by the player to render the cover block at rest.
+ */
+declare function expandCoverBlock(config: StartBlockConfig, context: TemplateContext): Layer[];
+
+/**
+ * Full Bleed Quote Template
+ *
+ * Short dramatic text filling the viewport like a movie title card.
+ * Designed for punchy text under 60 characters. Uses massive font
+ * centered on a dark vignette background.
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+declare function fullBleedQuote(input: FullBleedQuoteInput, context: TemplateContext): Layer[];
+
+/**
+ * List Block Template
+ *
+ * Displays 3-5 items in a numbered vertical list with staggered animations.
+ * Good for enumerations like "things to see", "key features", or "tips".
+ * Supports optional accent images.
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+declare function listBlock(input: ListBlockInput, context: TemplateContext): Layer[];
+
+/**
+ * Photo Grid Template
+ *
+ * Displays 2-4 images in a tiled layout for visual variety.
+ * Layout adapts based on image count and viewport orientation:
+ *
+ * Landscape:
+ * - 2 images: side-by-side 50/50
+ * - 3 images: one large left (60%) + two stacked right
+ * - 4 images: 2x2 grid
+ *
+ * Portrait (9:16): images stack horizontally (top/bottom) instead of
+ * side-by-side, giving each image full width on narrow screens.
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+declare function photoGrid(input: PhotoGridInput, context: TemplateContext): Layer[];
+
+/**
+ * Definition Card Template
+ *
+ * Dictionary-style slide with a large term and its definition.
+ * Good for explaining local words, place names, or cultural concepts.
+ * Supports optional accent images.
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+declare function definitionCard(input: DefinitionCardInput, context: TemplateContext): Layer[];
+
+/**
+ * Comparison Bar Template
+ *
+ * Two horizontal bars showing relative numeric values side by side.
+ * Bar widths are proportional to the values for immediate visual comparison.
+ * Good for population, distance, or measurement comparisons.
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+declare function comparisonBar(input: ComparisonBarInput, context: TemplateContext): Layer[];
+
+/**
+ * Pull Quote Template
+ *
+ * Quote text over a full-bleed background image with dark overlay.
+ * Cinematic alternative to quoteBlock when a high-quality image is available.
+ * Combines the visual impact of imageWithCaption with the text focus of quoteBlock.
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+declare function pullQuote(input: PullQuoteInput, context: TemplateContext): Layer[];
+
+/**
+ * Video With Caption Template
+ *
+ * Full-screen background video clip with text overlay. Mirrors the structure of
+ * imageWithCaption but uses a VideoLayer instead of an ImageLayer. The video
+ * plays muted — narration audio is the only sound track.
+ *
+ * Adapts caption positioning and font sizes for different viewports.
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ *
+ * Related Files:
+ * - shared/story/templates/imageWithCaption.ts — image equivalent
+ * - schemas/StoryScript.ts — VideoLayer type
+ * - site/src/components/story/layers/VideoLayer.tsx — rendering component
+ */
+
+declare function videoWithCaption(input: VideoWithCaptionInput, context: TemplateContext): Layer[];
+
+/**
+ * Video Pull Quote Template
+ *
+ * Quote text over a video clip background with dark overlay.
+ * Cinematic alternative to pullQuote when a video clip is available.
+ * Combines the visual dynamism of live video with the text focus of quoteBlock.
+ *
+ * The video plays muted — narration audio is the only sound track.
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ *
+ * Related Files:
+ * - shared/story/templates/pullQuote.ts — image-based equivalent
+ * - schemas/StoryScript.ts — VideoLayer type
+ * - site/src/components/story/layers/VideoLayer.tsx — rendering component
+ */
+
+declare function videoPullQuote(input: VideoPullQuoteInput, context: TemplateContext): Layer[];
+
+/**
+ * Accent Image Utility
+ *
+ * Creates image layers and layout adjustments for accent images on text-based slides.
+ * Accent images are tasteful additions that complement text without overwhelming it.
+ *
+ * Layout patterns:
+ * - left-strip: 35% width vertical strip on left, text area shifted to right 65%
+ * - right-strip: 35% width vertical strip on right, text area shifted to left 65%
+ * - bottom-strip: 35% height horizontal strip at bottom, text area in upper 65%
+ * - corner-inset: Small 25% corner image with gradient vignette
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+/**
+ * Layout adjustments when an accent image is present.
+ * Templates use these values to reposition their text content.
+ */
+interface AccentLayout {
+    /** X offset for text center (e.g., '64%' for left-strip) */
+    textCenterX: string;
+    /** Width available for text content */
+    textWidth: string;
+    /** Y offset adjustment for vertical positioning */
+    textYAdjust: number;
+    /** Whether to adjust Y positions (for bottom-strip) */
+    adjustY: boolean;
+}
+/**
+ * Default layout when no accent image is present.
+ */
+declare const DEFAULT_LAYOUT: AccentLayout;
+/**
+ * Get layout adjustments based on accent position.
+ */
+declare function getAccentLayout(position: AccentPosition): AccentLayout;
+/**
+ * Create layers for an accent image.
+ * Returns the image layer and any overlay/gradient layers needed.
+ */
+declare function createAccentLayers(accent: AccentImage, slideId: string): Layer[];
+/**
+ * Adjust a Y position value based on accent layout.
+ * Used by templates to shift content when bottom-strip is present.
+ */
+declare function adjustY(originalY: string | number, layout: AccentLayout): string;
+
+/**
+ * Block Template Registry
+ *
+ * Central registry of all block templates. Provides functions to:
+ * - Look up templates by name
+ * - Expand template blocks into full Layer arrays
+ * - Convert a template-based doc script into a renderable format
+ *
+ * Supports multiple viewport configurations for different aspect ratios.
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+/**
+ * Registry mapping template names to their implementation functions.
+ * Note: coverBlock is not in the registry as it's used directly for start blocks,
+ * not as a regular template in the block sequence.
+ */
+declare const templateRegistry: TemplateRegistry;
+/**
+ * Expand a template block into a full Block with layers.
+ */
+declare function expandTemplateBlock(templateBlock: TemplateBlock, context: TemplateContext): Block;
+/**
+ * Audio segment timing info for aligning blocks with audio.
+ */
+interface AudioSegmentTiming {
+    /** Start time of this segment in the overall timeline */
+    startTime: number;
+    /** Duration of this segment */
+    duration: number;
+}
+/**
+ * Options for expanding doc blocks.
+ */
+interface ExpandDocBlocksOptions {
+    /** Theme for template rendering (defaults to DEFAULT_THEME) */
+    theme?: Theme;
+    /** Viewport configuration (defaults to 16:9 landscape) */
+    viewport?: ViewportConfig;
+    /** Persistent layers for visual consistency across blocks */
+    persistentLayers?: PersistentLayerConfig;
+    /**
+     * Audio segment timing information.
+     * When provided, blocks are timed relative to their audio segment's start time,
+     * ensuring proper synchronization with audio playback.
+     */
+    audioSegments?: AudioSegmentTiming[];
+}
+/**
+ * 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.
+ */
+declare function getAvailableTemplates(): string[];
+/**
+ * Check if a template exists.
+ */
+declare function hasTemplate(name: string): boolean;
+
+/**
+ * Animation Utilities
+ *
+ * Helper functions for mapping Doc animations to CSS classes and styles.
+ * Generates the appropriate animation class names and CSS custom properties
+ * for duration, delay, and easing.
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+interface AnimationResult {
+    /** CSS class name to apply */
+    className: string;
+    /** Inline styles for CSS custom properties */
+    style: Record<string, string>;
+}
+/**
+ * Get CSS class and styles for an animation.
+ */
+declare function getAnimationStyle(animation: Animation | undefined, _currentTime?: number): AnimationResult;
+/**
+ * Get default duration for an animation type.
+ */
+declare function getDefaultAnimationDuration(type: AnimationType): number;
+/**
+ * Get transition class for slide entry/exit.
+ */
+declare function getTransitionClass(type: TransitionType, entering: boolean): string;
+/**
+ * Calculate animation progress (0-1) based on current time.
+ */
+declare function getAnimationProgress(animation: Animation, currentTime: number, slideDuration: number): number;
+
+/**
+ * Theme Utilities
+ *
+ * Template-facing helpers that read from the Theme object on the
+ * TemplateContext. Templates call these instead of hard-coding style
+ * decisions, so the same template code adapts to any theme.
+ */
+
+/**
+ * Resolve a named color scheme from the theme, with a safe fallback.
+ * Templates call this instead of `COLOR_SCHEMES[name]`.
+ */
+declare function resolveColorScheme(context: TemplateContext, name: string | undefined): ThemeColorScheme;
+/**
+ * Calculate a theme-aware scaled font size.
+ * Applies the theme's typography scale multipliers on top of the
+ * viewport-based font scale from LayoutStrategy.
+ *
+ * @param basePx  Base font size designed for 1920×1080
+ * @param context Template context (includes fontScale, layout, theme)
+ * @param isTitle Whether this is title text (uses titleScale) or body (bodyScale)
+ */
+declare function themedFontSize(basePx: number, context: TemplateContext, isTitle?: boolean): number;
+/**
+ * Scale an animation duration by the theme's animationSpeed multiplier.
+ * A speed of 1.0 returns the base duration unchanged.
+ */
+declare function scaleAnimationDuration(baseDuration: number, context: TemplateContext): number;
+/**
+ * Get the theme's default animation type for a layer kind.
+ * Returns `undefined` when the theme doesn't specify one (template picks its own).
+ */
+declare function getDefaultAnimation(context: TemplateContext, layerType: 'text' | 'image'): AnimationType | undefined;
+/**
+ * Whether the theme defaults to text shadows.
+ * Templates should consult this when choosing `shadow: true/false`.
+ */
+declare function shouldUseShadow(context: TemplateContext): boolean;
+/**
+ * Get the theme's overlay opacity for image-backed blocks.
+ */
+declare function getOverlayOpacity(context: TemplateContext): number;
+/**
+ * Read a per-template hint from the theme's renderStyle.
+ * Returns `fallback` when the hint isn't defined.
+ *
+ * @example
+ * ```ts
+ * const entrance = getTemplateHint(context, 'statHighlight', 'entrance', 'subtle');
+ * ```
+ */
+declare function getTemplateHint<T extends string | number | boolean>(context: TemplateContext, templateName: string, key: string, fallback: T): T;
+
+/**
+ * Markdown → Doc Conversion
+ *
+ * Converts a MarkdownDocument into a hierarchical Doc whose Block tree
+ * mirrors the heading structure of the markdown. Every heading (H1–H6)
+ * becomes a Block; body content between headings populates `contents`;
+ * sub-headings nest as `children`.
+ *
+ * This enables using BlockTemplates to supply alternate visualizations
+ * for each section of a markdown document.
+ *
+ * @example
+ * ```ts
+ * import { parseMarkdown } from '@bendyline/squisq/markdown';
+ * import { markdownToDoc } from '@bendyline/squisq/doc';
+ *
+ * const md = parseMarkdown('# Intro\n\nHello world\n\n## Details\n\nMore text');
+ * const doc = markdownToDoc(md);
+ * // doc.blocks[0].sourceHeading.depth === 1  ("# Intro")
+ * // doc.blocks[0].contents  → [paragraph("Hello world")]
+ * // doc.blocks[0].children[0].sourceHeading.depth === 2  ("## Details")
+ * ```
+ */
+
+/**
+ * Options for markdownToDoc().
+ */
+interface MarkdownToDocOptions {
+    /** Article ID for the generated Doc. Default: 'markdown-doc' */
+    articleId?: string;
+    /** Default template name for heading blocks. Default: 'sectionHeader' */
+    defaultTemplate?: string;
+    /** Default duration per block in seconds. Default: 5 */
+    defaultDuration?: number;
+    /** Custom ID generator. Receives the heading node and its index. */
+    generateId?: (heading: MarkdownHeading, index: number) => string;
+}
+/**
+ * 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[];
+/**
+ * Count the total number of blocks in a nested tree (including children at all levels).
+ */
+declare function countBlocks(blocks: Block[]): number;
+/**
+ * Get the heading depth for a block. Returns 0 for preamble blocks (no heading).
+ */
+declare function getBlockDepth(block: Block): number;
+
+/**
+ * Doc → Markdown Conversion
+ *
+ * Converts a Doc with a heading-driven Block hierarchy back into a
+ * MarkdownDocument. This is the reverse of markdownToDoc() and enables
+ * round-tripping: edit a Doc's block tree, then serialize back to markdown.
+ *
+ * **Algorithm:**
+ * Walk the block tree depth-first. For each block:
+ * 1. If it has a `sourceHeading`, emit that heading node
+ * 2. Emit all nodes in `contents`
+ * 3. Recurse into `children`
+ *
+ * @example
+ * ```ts
+ * import { markdownToDoc, docToMarkdown } from '@bendyline/squisq/doc';
+ * import { parseMarkdown, stringifyMarkdown } from '@bendyline/squisq/markdown';
+ *
+ * const md = '# Hello\n\nWorld\n';
+ * const doc = markdownToDoc(parseMarkdown(md));
+ * const roundTripped = stringifyMarkdown(docToMarkdown(doc));
+ * ```
+ */
+
+/**
+ * Convert a Doc with heading-driven blocks back to a MarkdownDocument.
+ *
+ * Walks the block tree depth-first, emitting heading nodes and contents
+ * in document order. Blocks without a `sourceHeading` (preamble blocks)
+ * emit only their contents.
+ *
+ * If a block has a `template` or `templateOverrides` that aren't already
+ * reflected in the heading's `templateAnnotation`, the annotation is
+ * injected so the round-trip preserves template assignments.
+ *
+ * @param doc - A Doc whose blocks may have `sourceHeading`, `contents`, and `children`
+ * @returns A MarkdownDocument that can be stringified back to markdown
+ */
+declare function docToMarkdown(doc: Doc): MarkdownDocument;
+
+/**
+ * getLayers — Compute visual layers for a block on demand.
+ *
+ * This is the preferred way to obtain renderable layers for a block.
+ * Instead of storing pre-computed layers on the Block object, call
+ * `getLayers(block, context)` to derive them from the block's template
+ * name, content, and the current render context (theme, viewport, etc.).
+ *
+ * For raw blocks that already carry a `layers` array, those layers are
+ * returned directly (with optional persistent layer injection).
+ *
+ * @example
+ * ```ts
+ * import { getLayers } from '@bendyline/squisq/doc';
+ *
+ * const layers = getLayers(block, {
+ *   theme: DEFAULT_THEME,
+ *   viewport: VIEWPORT_PRESETS.landscape,
+ *   blockIndex: 0,
+ *   totalBlocks: 10,
+ * });
+ * ```
+ */
+
+/**
+ * Context needed to compute layers for a block.
+ *
+ * Captures the visual rendering parameters: theme colors, viewport
+ * configuration, persistent layers, and the block's position within
+ * the doc (for template functions that vary output by index).
+ */
+interface RenderContext {
+    /** Theme for template rendering. Defaults to DEFAULT_THEME (documentary). */
+    theme?: Theme;
+    /** Target viewport configuration. Defaults to 16:9 landscape. */
+    viewport?: ViewportConfig;
+    /** Persistent layers injected behind and/or on top of all block content. */
+    persistentLayers?: PersistentLayerConfig;
+    /** 0-based index of this block in the sequence. Defaults to 0. */
+    blockIndex?: number;
+    /** Total number of blocks in the doc. Defaults to 1. */
+    totalBlocks?: number;
+}
+/**
+ * Compute the visual layers for a block.
+ *
+ * Resolution order:
+ * 1. If the block already has a non-empty `layers` array, use it (raw block).
+ * 2. If the block has a `template` name that exists in the registry,
+ *    call the template function to generate layers.
+ * 3. Otherwise return an empty array.
+ *
+ * Persistent layers (bottom/top) from the render context are injected
+ * around the result unless the block opts out via `useBottomLayer: false`
+ * or `useTopLayer: false`.
+ *
+ * @param block   A Block or TemplateBlock to render.
+ * @param context Render context (theme, viewport, persistent layers, position).
+ * @returns The computed Layer[] for the block, ready for BlockRenderer.
+ */
+declare function getLayers(block: DocBlock, context?: RenderContext): Layer[];
+
+export { type AccentLayout, type AudioSegmentTiming, type CoverBlockInput, DEFAULT_LAYOUT, DocBlock, type DocStylePreset, type ExpandDocBlocksOptions, type MarkdownToDocOptions, PersistentLayerConfig, type RenderContext, TemplateBlock, TemplateContext, Theme, ThemeColorScheme, ViewportConfig, adjustY, comparisonBar, countBlocks, coverBlock, createAccentLayers, dateEvent, definitionCard, docToMarkdown, expandCoverBlock, expandDocBlocks, expandPersistentLayers, expandTemplateBlock, factCard, flattenBlocks, fullBleedQuote, getAccentLayout, getAnimationProgress, getAnimationStyle, getAvailableTemplates, getBlockDepth, getDefaultAnimation, getDefaultAnimationDuration, getDocStyleConfig, getLayers, getOverlayOpacity, getTemplateHint, getTransitionClass, hasTemplate, imageWithCaption, listBlock, mapBlock, markdownToDoc, photoGrid, pullQuote, quoteBlock, resolveColorScheme, scaleAnimationDuration, sectionHeader, shouldUseShadow, statHighlight, templateRegistry, themedFontSize, titleBlock, twoColumn, videoPullQuote, videoWithCaption };