pdfjs-reader-core 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -5,6 +5,7 @@ import * as pdfjsDist from 'pdfjs-dist';
 export { pdfjsDist as pdfjsLib };
 import * as zustand from 'zustand';
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { z } from 'zod';
 import * as pdfjs_dist_types_src_display_api from 'pdfjs-dist/types/src/display/api';
 import { ClassValue } from 'clsx';
 import * as pdfjs_dist_types_src_display_metadata from 'pdfjs-dist/types/src/display/metadata';
@@ -247,6 +248,147 @@ interface StudentModeProps {
     askAboutLongPressDuration?: number;
 }
 
+type BlockType = 'heading' | 'paragraph' | 'list_item' | 'figure' | 'figure_region' | 'caption' | 'table' | 'mcq_option';
+type DefaultAction = 'zoom_pan' | 'spotlight' | 'underline' | 'pulse';
+/** Four numbers: [x1, y1, x2, y2] in PDF coordinates (origin top-left). */
+type BBoxCoords = readonly [number, number, number, number];
+interface Block {
+    block_id: string;
+    bbox: BBoxCoords;
+    text: string | null;
+    type: BlockType;
+    parent_id: string | null;
+    confidence: number;
+    reading_order: number;
+    default_action: DefaultAction;
+    semantic_unit_id: string;
+}
+interface PageDimensionsDpi {
+    width: number;
+    height: number;
+    dpi: number;
+}
+interface PageBBoxData {
+    id: string;
+    page_number: number;
+    page_text: string;
+    page_dimensions: PageDimensionsDpi;
+    blocks: Block[];
+    created_at: string;
+}
+/** Lookup indexes used by the director + engine. */
+interface BBoxIndex {
+    byPage: Map<number, PageBBoxData>;
+    blockById: Map<string, {
+        block: Block;
+        pageNumber: number;
+    }>;
+    crossPageFigures: Array<{
+        block_id: string;
+        page: number;
+        type: 'figure' | 'figure_region' | 'caption';
+        text: string;
+    }>;
+}
+
+type EasingName = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out';
+type SpotlightShape = 'rect' | 'rounded' | 'ellipse';
+type UnderlineStyle = 'straight' | 'sketch' | 'double' | 'wavy';
+type ArrowCurve = 'straight' | 'curved' | 'zigzag';
+type PulseIntensity = 'subtle' | 'normal' | 'strong';
+type BoxStyle = 'solid' | 'dashed';
+type LabelPosition = 'top' | 'bottom' | 'left' | 'right';
+type GhostPosition = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
+type ClearTarget = 'all' | 'spotlights' | 'overlays' | string[];
+interface ActionCamera {
+    type: 'camera';
+    target_block?: string;
+    target_bbox?: BBoxCoords;
+    scale: number;
+    padding: number;
+    easing: EasingName;
+}
+interface ActionSpotlight {
+    type: 'spotlight';
+    target_block: string;
+    dim_opacity: number;
+    feather_px: number;
+    shape: SpotlightShape;
+}
+interface ActionUnderline {
+    type: 'underline';
+    target_block: string;
+    color: string;
+    style: UnderlineStyle;
+    draw_duration_ms: number;
+}
+interface ActionHighlight {
+    type: 'highlight';
+    target_block: string;
+    color: string;
+    draw_duration_ms: number;
+}
+interface ActionPulse {
+    type: 'pulse';
+    target_block: string;
+    count: number;
+    intensity: PulseIntensity;
+}
+interface ActionCallout {
+    type: 'callout';
+    from_block: string;
+    to_block: string;
+    label?: string;
+    curve: ArrowCurve;
+}
+interface ActionGhostReference {
+    type: 'ghost_reference';
+    target_page: number;
+    target_block: string;
+    position: GhostPosition;
+}
+interface ActionBox {
+    type: 'box';
+    target_block: string;
+    color: string;
+    style: BoxStyle;
+}
+interface ActionLabel {
+    type: 'label';
+    target_block: string;
+    text: string;
+    position: LabelPosition;
+}
+interface ActionClear {
+    type: 'clear';
+    targets: ClearTarget;
+}
+type StoryboardAction = ActionCamera | ActionSpotlight | ActionUnderline | ActionHighlight | ActionPulse | ActionCallout | ActionGhostReference | ActionBox | ActionLabel | ActionClear;
+interface StoryboardStep {
+    at_ms: number;
+    duration_ms: number;
+    action: StoryboardAction;
+}
+interface Storyboard {
+    version: 1;
+    reasoning: string;
+    steps: StoryboardStep[];
+}
+/** Active overlay state tracked by the engine / store. */
+interface ActiveOverlay {
+    id: string;
+    kind: StoryboardAction['type'];
+    action: StoryboardAction;
+    createdAt: number;
+    expiresAt: number;
+}
+interface CameraState {
+    scale: number;
+    x: number;
+    y: number;
+    easing: EasingName;
+}
+
 interface PDFViewerProps {
     /** URL or ArrayBuffer of the PDF file */
     src: string | ArrayBuffer | Uint8Array;
@@ -326,7 +468,7 @@ interface PageDimensions {
     height: number;
     scale: number;
 }
-type ViewMode = 'single' | 'dual' | 'continuous' | 'book';
+type ViewMode = 'single' | 'dual' | 'continuous' | 'book' | 'tutor';
 type ScrollMode = 'single' | 'continuous';
 type SidebarPanel = 'thumbnails' | 'outline' | 'search' | 'annotations' | null;
 type Theme = 'light' | 'dark' | 'sepia';
@@ -823,7 +965,7 @@ interface PDFViewerHandle {
  *
  * @example
  * ```tsx
- * import { PDFViewer } from '@pdf-reader/core';
+ * import { PDFViewer } from 'pdfjs-reader-core';
  *
  * function App() {
  *   return (
@@ -1489,6 +1631,912 @@ interface PDFLoadingScreenProps {
  */
 declare const PDFLoadingScreen: react.NamedExoticComponent<PDFLoadingScreenProps>;
 
+interface ChunkHistoryEntry {
+    text: string;
+    pageNumber: number;
+    timestamp: number;
+}
+type EngineStatus = 'idle' | 'transitioning' | 'executing';
+type LlmStatus = 'idle' | 'in-flight' | 'failed';
+interface DebugEvent {
+    id: string;
+    timestamp: number;
+    kind: 'chunk' | 'llm-request' | 'llm-response' | 'llm-error' | 'storyboard-execute' | 'fallback-fired' | 'note';
+    /** Short headline shown in the log */
+    summary: string;
+    /** Full payload (chunk text, raw LLM response, parsed storyboard, error, etc.) */
+    payload?: unknown;
+}
+interface NarrationState {
+    currentChunk: string | null;
+    currentPage: number;
+    chunkHistory: ChunkHistoryEntry[];
+    camera: CameraState;
+    activeOverlays: ActiveOverlay[];
+    engineStatus: EngineStatus;
+    llmStatus: LlmStatus;
+    lastStoryboard: Storyboard | null;
+    lastError: string | null;
+    isPaused: boolean;
+    debugEvents: DebugEvent[];
+}
+interface NarrationActions {
+    setCurrentChunk: (chunk: string | null) => void;
+    setCurrentPage: (page: number) => void;
+    pushChunkHistory: (entry: ChunkHistoryEntry) => void;
+    setCamera: (camera: Partial<CameraState>) => void;
+    addOverlay: (overlay: ActiveOverlay) => void;
+    removeOverlay: (id: string) => void;
+    clearOverlays: (predicate?: (o: ActiveOverlay) => boolean) => void;
+    setEngineStatus: (s: EngineStatus) => void;
+    setLlmStatus: (s: LlmStatus, error?: string | null) => void;
+    setLastStoryboard: (sb: Storyboard | null) => void;
+    setPaused: (paused: boolean) => void;
+    appendDebugEvent: (event: Omit<DebugEvent, 'id' | 'timestamp'>) => void;
+    clearDebugEvents: () => void;
+    reset: () => void;
+}
+type NarrationStore = NarrationState & NarrationActions;
+declare function createNarrationStore(overrides?: Partial<NarrationState>): zustand.StoreApi<NarrationStore>;
+type NarrationStoreApi = ReturnType<typeof createNarrationStore>;
+declare function makeOverlayId(action: StoryboardAction): string;
+
+declare const SYSTEM_PROMPT = "You are the cinematic director of an AI tutor's PDF visualization. The tutor speaks one \"chunk\" at a time; for each chunk you anchor the visuals onto the EXACT blocks on the page the tutor is talking about, so the reader sees the page react like a produced teaching video. Think of yourself as a motion designer layering effects on top of a document \u2014 zoom is only one tool in the kit, and often not the right one.\n\n# Your primary task\nYou are given a list of blocks for the current page under \"Page blocks\", each with a `block_id`, `text`, `type`, `bbox`, and `default_action`. Your #1 job is to decide WHICH block(s) the current chunk is referring to, and then pick the right visual action(s) to anchor there.\n\nAnchoring rules:\n- EVERY action that references a block MUST set `target_block` (or `from_block`/`to_block` for callouts) to an EXISTING `block_id` from \"Page blocks\" (or \"Cross-page figures index\" for cross-page refs). Never invent an id. Never emit a step whose target can't be found in the provided lists.\n- Match the chunk to blocks by semantic overlap with the block's `text`: quoted phrases, named entities, keywords, figure references (\"Fig 3.2\", \"the suture\"), list enumerations.\n- If no block clearly matches, emit a single `camera` step that fits the page (no overlays) and explain in `reasoning`. Do NOT spray overlays onto random blocks.\n- If multiple blocks match, pick the most specific one, or use a `callout` from one to the other.\n\n# Output shape\nOutput ONLY this JSON, nothing else:\n{\n  \"version\": 1,\n  \"reasoning\": \"<which block(s) you picked, which intent you used, and why \u2014 name the block_id>\",\n  \"steps\": [ { \"at_ms\": <int>, \"duration_ms\": <int>, \"action\": <action> }, ... ]\n}\n\n# Action shapes \u2014 ALL fields shown are REQUIRED per action type\n- camera:          { \"type\":\"camera\", \"target_block\":\"<id>\", \"scale\":1.1, \"padding\":80, \"easing\":\"ease-out\" }\n- spotlight:       { \"type\":\"spotlight\", \"target_block\":\"<id>\", \"dim_opacity\":0.65, \"feather_px\":40, \"shape\":\"rounded\" }\n- underline:       { \"type\":\"underline\", \"target_block\":\"<id>\", \"color\":\"#FBBF24\", \"style\":\"sketch\", \"draw_duration_ms\":600 }\n- highlight:       { \"type\":\"highlight\", \"target_block\":\"<id>\", \"color\":\"rgba(250,204,21,0.35)\", \"draw_duration_ms\":500 }\n- pulse:           { \"type\":\"pulse\", \"target_block\":\"<id>\", \"count\":2, \"intensity\":\"normal\" }\n- callout:         { \"type\":\"callout\", \"from_block\":\"<id>\", \"to_block\":\"<id>\", \"label\":\"<text>\", \"curve\":\"curved\" }\n- ghost_reference: { \"type\":\"ghost_reference\", \"target_page\":<int>, \"target_block\":\"<id>\", \"position\":\"top-right\" }\n- box:             { \"type\":\"box\", \"target_block\":\"<id>\", \"color\":\"#3B82F6\", \"style\":\"solid\" }\n- label:           { \"type\":\"label\", \"target_block\":\"<id>\", \"text\":\"<text>\", \"position\":\"top\" }\n- clear:           { \"type\":\"clear\", \"targets\":\"overlays\" }\n\n# When to use each action (match the effect to the narration's intent, not just the block type)\n- camera          \u2014 when focus SHIFTS to a new region. If the primary block is already on-screen and roughly centered, you may skip camera entirely and start with an overlay. When you do use camera, prefer scale 1.1\u20131.4 for gentle re-centering; reserve 1.5+ for dense figures you need to inspect closely.\n- spotlight       \u2014 when narration ISOLATES one idea, term, or sentence. Great for definitions, principles, and \"the key insight is\u2026\" moments.\n- underline       \u2014 when narration QUOTES a phrase or reads a line word-by-word. Use style \"sketch\" for handwritten feel, \"straight\" for formal, \"wavy\" for emphasis. Pairs well with spotlight.\n- highlight       \u2014 when narration FLAGS a keyword inline without full focus. Cheap, fast, great for list items, definitions-in-context, callback references.\n- pulse           \u2014 when narration says \"notice this\" / \"see here\" / \"look at the diagram\". Use with figures, icons, and anchor blocks that should catch the eye without blocking surrounding content.\n- callout         \u2014 when narration CONNECTS two things on the page: a caption to its figure, a label to a region, one list item to another. Arrow implies directional meaning.\n- ghost_reference \u2014 when narration REFERS to a block on a DIFFERENT page (\"as we saw on page 2\u2026\"). Never use for same-page references.\n- box             \u2014 when narration FRAMES a structural region: a table, a sidebar, a group of related items, a diagram subpart. Use dashed style for \"in-progress\" / \"under discussion\" regions.\n- label           \u2014 when narration attaches a NAMED TAG to a block: \"this is the definition\", \"this is an example\", \"step 3\". Keep text \u226440 chars for readability.\n- clear           \u2014 rarely needed; the engine auto-expires overlays. Use only when you explicitly want to wipe prior state before a new beat.\n\nRespect each block's `default_action` as a soft hint, but override it freely when narration intent calls for a different effect. A paragraph labeled `default_action: spotlight` can absolutely take a highlight or underline if that's what the narration asks for.\n\n# Intent Taxonomy \u2014 canonical \"recipes\" you should use as your default vocabulary\nWhen narration fits one of these patterns, emit the corresponding storyboard shape (fill in real block_ids from the page). You may also COMPOSE freely beyond these \u2014 they are a floor, not a ceiling.\n\n## define \u2014 the narration introduces or defines a term\nShape: spotlight the term + underline it + drop a label tag. No camera move if the block is already on-screen.\n{\n  \"version\": 1,\n  \"reasoning\": \"define recipe: spotlighting and underlining the term, labeling as 'definition'\",\n  \"steps\": [\n    { \"at_ms\":0,   \"duration_ms\":700, \"action\": { \"type\":\"spotlight\", \"target_block\":\"p1_para0\", \"dim_opacity\":0.6, \"feather_px\":40, \"shape\":\"rounded\" } },\n    { \"at_ms\":200, \"duration_ms\":800, \"action\": { \"type\":\"underline\", \"target_block\":\"p1_para0\", \"color\":\"#FBBF24\", \"style\":\"sketch\", \"draw_duration_ms\":700 } },\n    { \"at_ms\":900, \"duration_ms\":1200, \"action\": { \"type\":\"label\", \"target_block\":\"p1_para0\", \"text\":\"definition\", \"position\":\"top\" } }\n  ]\n}\n\n## point_out \u2014 the narration directs the viewer's eye to a figure, diagram, or specific region\nShape: gentle camera move + callout arrow from caption to figure + pulse the figure.\n{\n  \"version\": 1,\n  \"reasoning\": \"point_out recipe: drawing attention from caption p1_cap1 to figure p1_fig0\",\n  \"steps\": [\n    { \"at_ms\":0,   \"duration_ms\":600, \"action\": { \"type\":\"camera\", \"target_block\":\"p1_fig0\", \"scale\":1.3, \"padding\":80, \"easing\":\"ease-out\" } },\n    { \"at_ms\":400, \"duration_ms\":900, \"action\": { \"type\":\"callout\", \"from_block\":\"p1_cap1\", \"to_block\":\"p1_fig0\", \"label\":\"see here\", \"curve\":\"curved\" } },\n    { \"at_ms\":900, \"duration_ms\":1200, \"action\": { \"type\":\"pulse\", \"target_block\":\"p1_fig0\", \"count\":2, \"intensity\":\"normal\" } }\n  ]\n}\n\n## compare \u2014 the narration contrasts two things on the page\nShape: box A + box B + callout between them with a relational label.\n{\n  \"version\": 1,\n  \"reasoning\": \"compare recipe: framing fibrous vs synovial joints\",\n  \"steps\": [\n    { \"at_ms\":0,   \"duration_ms\":600, \"action\": { \"type\":\"box\", \"target_block\":\"p1_list5\", \"color\":\"#3B82F6\", \"style\":\"solid\" } },\n    { \"at_ms\":300, \"duration_ms\":600, \"action\": { \"type\":\"box\", \"target_block\":\"p1_list12\", \"color\":\"#F472B6\", \"style\":\"solid\" } },\n    { \"at_ms\":800, \"duration_ms\":1000, \"action\": { \"type\":\"callout\", \"from_block\":\"p1_list5\", \"to_block\":\"p1_list12\", \"label\":\"vs\", \"curve\":\"curved\" } }\n  ]\n}\n\n## emphasize \u2014 the narration stresses a keyword, warning, or takeaway\nShape: highlight + pulse. Fast, punchy, no camera.\n{\n  \"version\": 1,\n  \"reasoning\": \"emphasize recipe: highlighting key keyword and pulsing for stress\",\n  \"steps\": [\n    { \"at_ms\":0,   \"duration_ms\":500, \"action\": { \"type\":\"highlight\", \"target_block\":\"p1_list0\", \"color\":\"rgba(250,204,21,0.35)\", \"draw_duration_ms\":450 } },\n    { \"at_ms\":350, \"duration_ms\":800, \"action\": { \"type\":\"pulse\", \"target_block\":\"p1_list0\", \"count\":2, \"intensity\":\"strong\" } }\n  ]\n}\n\n# Choreography rules\n- HARD REQUIREMENT: every storyboard MUST contain at least ONE non-camera step. A lone camera step is NEVER a valid output \u2014 the viewer needs an overlay to know WHY the camera moved. If you cannot find a good overlay target, emit a `highlight` or `pulse` on your primary block as the second step.\n- Favor VARIETY that matches narration texture \u2014 a definition earns different visuals than a comparison. Don't send every chunk through the same zoom+box motion.\n- Include a camera step only when focus genuinely shifts to a new region. If the primary target is already on-screen and roughly centred, SKIP the camera entirely and start directly with an overlay.\n- Camera scale: default to **1.1** (gentle re-centre). Use **1.2\u20131.3** for normal reading distance. Use **1.4\u20131.6** ONLY for dense figures or small inline details. NEVER use a scale below 0.5 or above 4.0 \u2014 the engine rejects those. When in doubt, use 1.1.\n- Prefer overlays that OVERLAP the camera move. A camera that takes 700ms to finish while overlays fire at 200ms feels cinematic; overlays waiting until after the camera settles feel sluggish. Stagger `at_ms`: camera at 0, first overlay at 150\u2013300ms, second overlay at 600\u2013900ms.\n- 2\u20134 steps is typical; single-step overlays (no camera) are PREFERRED when the target is already visible.\n- When narration compares two things, USE the compare recipe (box + box + callout), not a single camera step. When narration says \"key takeaway\", USE emphasize (highlight + pulse).\n- Never target a block_id not present in the provided lists. If no block matches, emit a single camera step at scale 1.0 + a subtle pulse on the nearest heading; explain in `reasoning`.\n- Output ONLY valid JSON. No markdown, no code fences, no commentary, no trailing whitespace inside property values.\n\n# Forbidden outputs \u2014 these will be rejected:\n- A storyboard with only a camera step.\n- A camera step with scale < 0.5 or > 4.0.\n- target_block values not listed in \"Page blocks\" or \"Cross-page figures index\".\n- Tab characters, newlines, or explanatory text inside JSON string values.";
+interface BuildUserPromptInput {
+    chunk: string;
+    pageNumber: number;
+    page: PageBBoxData;
+    index: BBoxIndex;
+    history: ChunkHistoryEntry[];
+    camera: CameraState;
+    activeOverlays: ActiveOverlay[];
+    maxSteps?: number;
+}
+/** Truncate text to ~max chars, word-aware. */
+declare function truncate(text: string | null, max?: number): string;
+declare function buildUserPrompt(input: BuildUserPromptInput): string;
+
+interface LlmConfig {
+    endpointUrl: string;
+    model: string;
+    authToken?: string;
+    extraBody?: Record<string, unknown>;
+    maxTokens?: number;
+    temperature?: number;
+    /** If true, include response_format: json_schema (disable if the backend doesn't support it). */
+    useJsonSchema?: boolean;
+    /** If true, request streaming (default false: simpler, more reliable for non-streaming backends). */
+    stream?: boolean;
+}
+interface DirectorInput extends BuildUserPromptInput {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+interface DirectorResult {
+    storyboard: Storyboard | null;
+    raw: string;
+    error?: string;
+}
+/**
+ * Call the LLM, stream the response, extract a JSON storyboard, validate with zod.
+ * Returns { storyboard: null } with an error string on any failure path.
+ */
+declare function directStoryboard(config: LlmConfig, input: DirectorInput): Promise<DirectorResult>;
+
+interface EmbeddingProvider {
+    /** Return embeddings (normalized or raw — similarity function handles either). */
+    embed: (texts: string[]) => Promise<Float32Array[]>;
+}
+declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
+interface BlockMatch {
+    block: Block;
+    score: number;
+}
+declare function matchChunkToBlock(chunk: string, page: PageBBoxData, provider: EmbeddingProvider): Promise<BlockMatch | null>;
+/**
+ * Build a fallback storyboard from a matched block. Keys on `block.type`
+ * (7 types) rather than `block.default_action` (4 values) so every block
+ * class produces a visually distinct storyboard — not every failure rounds
+ * down to camera + box. An optional `page` lets caption blocks route to a
+ * callout→figure on the same page.
+ *
+ * Never throws — emits a clear-only storyboard when no match is supplied.
+ */
+declare function storyboardFromMatch(match: BlockMatch | null, page?: PageBBoxData): Storyboard;
+
+interface TutorModeContainerProps {
+    pageNumber: number;
+    bboxData: PageBBoxData[];
+    narrationStore: NarrationStoreApi;
+    scale: number;
+    rotation?: number;
+    /** Reactive chunk from the tutor (updates as she speaks) */
+    currentChunk?: string | null;
+    /** LLM endpoint configuration provided by the consumer */
+    llm?: LlmConfig;
+    /** Milliseconds of no new chunks before the camera returns to fit-page */
+    idleTimeoutMs?: number;
+    /** LLM call timeout in ms. Default 30000 (Qwen3-32B and similar can take 5-15s). */
+    llmTimeoutMs?: number;
+    /** Optional embedding provider for fallback matching when the LLM fails */
+    embeddingProvider?: EmbeddingProvider;
+    /** Show subtitle bar with the current chunk text (default: true) */
+    showSubtitles?: boolean;
+    /**
+     * Show the "Reset view" button (default: true). Clicking it clears all
+     * overlays and returns the camera to fit-page. If `onExitTutorMode` is
+     * also provided, it runs after the reset — useful when the host app
+     * wants the same button to also leave tutor mode entirely.
+     */
+    showExitButton?: boolean;
+    /**
+     * Optional callback fired AFTER the engine's resetVisuals. Provide this
+     * only if the host wants the reset button to also leave tutor mode /
+     * navigate away. Omit it for a pure "reset the visuals" behaviour.
+     */
+    onExitTutorMode?: () => void;
+    /**
+     * Minimum hold time (ms) for every overlay, regardless of the
+     * `duration_ms` the LLM specifies. Short LLM-emitted durations (600-1200ms)
+     * flash past too quickly to read; bump this for narration-paired UX.
+     * Default: 3500ms.
+     */
+    minOverlayDurationMs?: number;
+    className?: string;
+}
+/** Build a cross-page/block index from the raw bbox list. */
+declare function buildBBoxIndex(bboxData: PageBBoxData[]): BBoxIndex;
+declare function TutorModeContainer({ pageNumber, bboxData, narrationStore, scale, rotation, currentChunk, llm, idleTimeoutMs, llmTimeoutMs, embeddingProvider, showSubtitles, showExitButton, onExitTutorMode, minOverlayDurationMs, className, }: TutorModeContainerProps): react_jsx_runtime.JSX.Element;
+
+interface CinemaLayerProps {
+    page: PageBBoxData;
+    index: BBoxIndex;
+    overlays: ActiveOverlay[];
+    scale: number;
+}
+declare function CinemaLayer({ page, index, overlays, scale, }: CinemaLayerProps): react_jsx_runtime.JSX.Element;
+
+interface CameraViewProps {
+    camera: CameraState;
+    children: react__default.ReactNode;
+    /** total duration for the tween, in ms */
+    durationMs?: number;
+    className?: string;
+}
+/**
+ * Wraps page content in a Framer Motion container that animates scale+translate.
+ * The origin is the center of the container.
+ */
+declare function CameraView({ camera, children, durationMs, className, }: CameraViewProps): react_jsx_runtime.JSX.Element;
+
+interface SpotlightMaskProps {
+    page: PageDimensionsDpi;
+    bbox: BBoxCoords;
+    action: ActionSpotlight;
+    durationMs?: number;
+}
+/**
+ * Full-page SVG overlay: dims the entire page with action.dim_opacity,
+ * then "cuts out" a rounded/rect/ellipse hole over the target bbox so
+ * the underlying page shows through. Uses an SVG mask with a blur filter
+ * to feather the edge.
+ *
+ * Rendered in PAGE coords (viewBox spans the full page). The parent
+ * CinemaLayer applies the overall scale transform.
+ */
+declare function SpotlightMask({ page, bbox, action, durationMs, }: SpotlightMaskProps): react_jsx_runtime.JSX.Element;
+
+interface AnimatedUnderlineProps {
+    bbox: BBoxCoords;
+    action: ActionUnderline;
+}
+declare function AnimatedUnderline({ bbox, action }: AnimatedUnderlineProps): react_jsx_runtime.JSX.Element;
+
+interface AnimatedHighlightProps {
+    bbox: BBoxCoords;
+    action: ActionHighlight;
+}
+declare function AnimatedHighlight({ bbox, action }: AnimatedHighlightProps): react_jsx_runtime.JSX.Element;
+
+interface PulseOverlayProps {
+    bbox: BBoxCoords;
+    action: ActionPulse;
+}
+declare function PulseOverlay({ bbox, action }: PulseOverlayProps): react_jsx_runtime.JSX.Element;
+
+interface CalloutArrowProps {
+    fromBbox: BBoxCoords;
+    toBbox: BBoxCoords;
+    action: ActionCallout;
+}
+declare function CalloutArrow({ fromBbox, toBbox, action }: CalloutArrowProps): react_jsx_runtime.JSX.Element;
+
+interface GhostReferenceProps {
+    page: PageDimensionsDpi;
+    sourceBbox: BBoxCoords;
+    sourceBlockText: string | null;
+    sourcePageNumber: number;
+    action: ActionGhostReference;
+}
+/**
+ * Renders a floating "ghost" card referencing a block from another page.
+ * Shows a minimap of the source page with the target bbox highlighted,
+ * plus the block's text description as a caption.
+ */
+declare function GhostReference({ page, sourceBbox, sourceBlockText, sourcePageNumber, action, }: GhostReferenceProps): react_jsx_runtime.JSX.Element;
+
+interface BoxOverlayProps {
+    bbox: BBoxCoords;
+    action: ActionBox;
+}
+declare function BoxOverlay({ bbox, action }: BoxOverlayProps): react_jsx_runtime.JSX.Element;
+
+interface StickyLabelProps {
+    bbox: BBoxCoords;
+    action: ActionLabel;
+}
+declare function StickyLabel({ bbox, action }: StickyLabelProps): react_jsx_runtime.JSX.Element;
+
+interface SubtitleBarProps {
+    text: string | null;
+}
+declare function SubtitleBar({ text }: SubtitleBarProps): react_jsx_runtime.JSX.Element;
+
+interface ViewportSize {
+    width: number;
+    height: number;
+}
+
+interface EngineDeps {
+    narrationStore: NarrationStoreApi;
+    bboxIndex: BBoxIndex;
+    /** Callback to read current viewport size (pixels). */
+    getViewport: () => ViewportSize;
+    /**
+     * Minimum time (ms) an overlay stays on screen regardless of what
+     * `step.duration_ms` the LLM emitted. The schema caps duration at 5000ms
+     * and recipes typically suggest 600-1200ms — too short to register
+     * visually in a narration context. Default: 3500ms.
+     */
+    minOverlayDurationMs?: number;
+}
+declare class StoryboardEngine {
+    private deps;
+    private pendingTimers;
+    private currentStoryboardId;
+    constructor(deps: EngineDeps);
+    /**
+     * Execute a new storyboard. Cancels in-flight steps from the previous storyboard
+     * and smoothly transitions the camera/overlays from the current state.
+     */
+    execute(storyboard: Storyboard): void;
+    /** Abort all pending steps and set engine status to idle. */
+    cancelPending(): void;
+    /** Reset visuals: clear overlays, fit camera back to page. */
+    resetVisuals(): void;
+    /** Execute one step — dispatch to narrationStore. Returns true if applied. */
+    private runStep;
+    private applyCamera;
+}
+
+declare const StoryboardActionSchema: z.ZodUnion<[z.ZodEffects<z.ZodObject<{
+    type: z.ZodLiteral<"camera">;
+    target_block: z.ZodOptional<z.ZodString>;
+    target_bbox: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    scale: z.ZodDefault<z.ZodNumber>;
+    padding: z.ZodDefault<z.ZodNumber>;
+    easing: z.ZodDefault<z.ZodEnum<["linear", "ease-in", "ease-out", "ease-in-out"]>>;
+}, "strip", z.ZodTypeAny, {
+    type: "camera";
+    scale: number;
+    easing: "linear" | "ease-in" | "ease-out" | "ease-in-out";
+    padding: number;
+    target_block?: string | undefined;
+    target_bbox?: [number, number, number, number] | undefined;
+}, {
+    type: "camera";
+    scale?: number | undefined;
+    easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | undefined;
+    padding?: number | undefined;
+    target_block?: string | undefined;
+    target_bbox?: [number, number, number, number] | undefined;
+}>, {
+    type: "camera";
+    scale: number;
+    easing: "linear" | "ease-in" | "ease-out" | "ease-in-out";
+    padding: number;
+    target_block?: string | undefined;
+    target_bbox?: [number, number, number, number] | undefined;
+}, {
+    type: "camera";
+    scale?: number | undefined;
+    easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | undefined;
+    padding?: number | undefined;
+    target_block?: string | undefined;
+    target_bbox?: [number, number, number, number] | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"spotlight">;
+    target_block: z.ZodString;
+    dim_opacity: z.ZodDefault<z.ZodNumber>;
+    feather_px: z.ZodDefault<z.ZodNumber>;
+    shape: z.ZodDefault<z.ZodEnum<["rect", "rounded", "ellipse"]>>;
+}, "strip", z.ZodTypeAny, {
+    type: "spotlight";
+    shape: "rect" | "rounded" | "ellipse";
+    target_block: string;
+    dim_opacity: number;
+    feather_px: number;
+}, {
+    type: "spotlight";
+    target_block: string;
+    shape?: "rect" | "rounded" | "ellipse" | undefined;
+    dim_opacity?: number | undefined;
+    feather_px?: number | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"underline">;
+    target_block: z.ZodString;
+    color: z.ZodDefault<z.ZodString>;
+    style: z.ZodDefault<z.ZodEnum<["straight", "sketch", "double", "wavy"]>>;
+    draw_duration_ms: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    style: "straight" | "sketch" | "double" | "wavy";
+    color: string;
+    type: "underline";
+    target_block: string;
+    draw_duration_ms: number;
+}, {
+    type: "underline";
+    target_block: string;
+    style?: "straight" | "sketch" | "double" | "wavy" | undefined;
+    color?: string | undefined;
+    draw_duration_ms?: number | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"highlight">;
+    target_block: z.ZodString;
+    color: z.ZodDefault<z.ZodString>;
+    draw_duration_ms: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    color: string;
+    type: "highlight";
+    target_block: string;
+    draw_duration_ms: number;
+}, {
+    type: "highlight";
+    target_block: string;
+    color?: string | undefined;
+    draw_duration_ms?: number | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"pulse">;
+    target_block: z.ZodString;
+    count: z.ZodDefault<z.ZodNumber>;
+    intensity: z.ZodDefault<z.ZodEnum<["subtle", "normal", "strong"]>>;
+}, "strip", z.ZodTypeAny, {
+    type: "pulse";
+    target_block: string;
+    count: number;
+    intensity: "subtle" | "normal" | "strong";
+}, {
+    type: "pulse";
+    target_block: string;
+    count?: number | undefined;
+    intensity?: "subtle" | "normal" | "strong" | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"callout">;
+    from_block: z.ZodString;
+    to_block: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    curve: z.ZodDefault<z.ZodEnum<["straight", "curved", "zigzag"]>>;
+}, "strip", z.ZodTypeAny, {
+    type: "callout";
+    curve: "straight" | "curved" | "zigzag";
+    from_block: string;
+    to_block: string;
+    label?: string | undefined;
+}, {
+    type: "callout";
+    from_block: string;
+    to_block: string;
+    label?: string | undefined;
+    curve?: "straight" | "curved" | "zigzag" | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"ghost_reference">;
+    target_page: z.ZodNumber;
+    target_block: z.ZodString;
+    position: z.ZodDefault<z.ZodEnum<["top-right", "top-left", "bottom-right", "bottom-left"]>>;
+}, "strip", z.ZodTypeAny, {
+    type: "ghost_reference";
+    position: "top-right" | "top-left" | "bottom-right" | "bottom-left";
+    target_block: string;
+    target_page: number;
+}, {
+    type: "ghost_reference";
+    target_block: string;
+    target_page: number;
+    position?: "top-right" | "top-left" | "bottom-right" | "bottom-left" | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"box">;
+    target_block: z.ZodString;
+    color: z.ZodDefault<z.ZodString>;
+    style: z.ZodDefault<z.ZodEnum<["solid", "dashed"]>>;
+}, "strip", z.ZodTypeAny, {
+    style: "solid" | "dashed";
+    color: string;
+    type: "box";
+    target_block: string;
+}, {
+    type: "box";
+    target_block: string;
+    style?: "solid" | "dashed" | undefined;
+    color?: string | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"label">;
+    target_block: z.ZodString;
+    text: z.ZodString;
+    position: z.ZodDefault<z.ZodEnum<["top", "bottom", "left", "right"]>>;
+}, "strip", z.ZodTypeAny, {
+    text: string;
+    type: "label";
+    position: "top" | "bottom" | "left" | "right";
+    target_block: string;
+}, {
+    text: string;
+    type: "label";
+    target_block: string;
+    position?: "top" | "bottom" | "left" | "right" | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"clear">;
+    targets: z.ZodDefault<z.ZodUnion<[z.ZodEnum<["all", "spotlights", "overlays"]>, z.ZodArray<z.ZodString, "many">]>>;
+}, "strip", z.ZodTypeAny, {
+    type: "clear";
+    targets: "all" | "spotlights" | "overlays" | string[];
+}, {
+    type: "clear";
+    targets?: "all" | "spotlights" | "overlays" | string[] | undefined;
+}>]>;
+declare const StoryboardSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    reasoning: z.ZodDefault<z.ZodString>;
+    steps: z.ZodArray<z.ZodObject<{
+        at_ms: z.ZodDefault<z.ZodNumber>;
+        duration_ms: z.ZodDefault<z.ZodNumber>;
+        action: z.ZodUnion<[z.ZodEffects<z.ZodObject<{
+            type: z.ZodLiteral<"camera">;
+            target_block: z.ZodOptional<z.ZodString>;
+            target_bbox: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+            scale: z.ZodDefault<z.ZodNumber>;
+            padding: z.ZodDefault<z.ZodNumber>;
+            easing: z.ZodDefault<z.ZodEnum<["linear", "ease-in", "ease-out", "ease-in-out"]>>;
+        }, "strip", z.ZodTypeAny, {
+            type: "camera";
+            scale: number;
+            easing: "linear" | "ease-in" | "ease-out" | "ease-in-out";
+            padding: number;
+            target_block?: string | undefined;
+            target_bbox?: [number, number, number, number] | undefined;
+        }, {
+            type: "camera";
+            scale?: number | undefined;
+            easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | undefined;
+            padding?: number | undefined;
+            target_block?: string | undefined;
+            target_bbox?: [number, number, number, number] | undefined;
+        }>, {
+            type: "camera";
+            scale: number;
+            easing: "linear" | "ease-in" | "ease-out" | "ease-in-out";
+            padding: number;
+            target_block?: string | undefined;
+            target_bbox?: [number, number, number, number] | undefined;
+        }, {
+            type: "camera";
+            scale?: number | undefined;
+            easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | undefined;
+            padding?: number | undefined;
+            target_block?: string | undefined;
+            target_bbox?: [number, number, number, number] | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"spotlight">;
+            target_block: z.ZodString;
+            dim_opacity: z.ZodDefault<z.ZodNumber>;
+            feather_px: z.ZodDefault<z.ZodNumber>;
+            shape: z.ZodDefault<z.ZodEnum<["rect", "rounded", "ellipse"]>>;
+        }, "strip", z.ZodTypeAny, {
+            type: "spotlight";
+            shape: "rect" | "rounded" | "ellipse";
+            target_block: string;
+            dim_opacity: number;
+            feather_px: number;
+        }, {
+            type: "spotlight";
+            target_block: string;
+            shape?: "rect" | "rounded" | "ellipse" | undefined;
+            dim_opacity?: number | undefined;
+            feather_px?: number | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"underline">;
+            target_block: z.ZodString;
+            color: z.ZodDefault<z.ZodString>;
+            style: z.ZodDefault<z.ZodEnum<["straight", "sketch", "double", "wavy"]>>;
+            draw_duration_ms: z.ZodDefault<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            style: "straight" | "sketch" | "double" | "wavy";
+            color: string;
+            type: "underline";
+            target_block: string;
+            draw_duration_ms: number;
+        }, {
+            type: "underline";
+            target_block: string;
+            style?: "straight" | "sketch" | "double" | "wavy" | undefined;
+            color?: string | undefined;
+            draw_duration_ms?: number | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"highlight">;
+            target_block: z.ZodString;
+            color: z.ZodDefault<z.ZodString>;
+            draw_duration_ms: z.ZodDefault<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            color: string;
+            type: "highlight";
+            target_block: string;
+            draw_duration_ms: number;
+        }, {
+            type: "highlight";
+            target_block: string;
+            color?: string | undefined;
+            draw_duration_ms?: number | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"pulse">;
+            target_block: z.ZodString;
+            count: z.ZodDefault<z.ZodNumber>;
+            intensity: z.ZodDefault<z.ZodEnum<["subtle", "normal", "strong"]>>;
+        }, "strip", z.ZodTypeAny, {
+            type: "pulse";
+            target_block: string;
+            count: number;
+            intensity: "subtle" | "normal" | "strong";
+        }, {
+            type: "pulse";
+            target_block: string;
+            count?: number | undefined;
+            intensity?: "subtle" | "normal" | "strong" | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"callout">;
+            from_block: z.ZodString;
+            to_block: z.ZodString;
+            label: z.ZodOptional<z.ZodString>;
+            curve: z.ZodDefault<z.ZodEnum<["straight", "curved", "zigzag"]>>;
+        }, "strip", z.ZodTypeAny, {
+            type: "callout";
+            curve: "straight" | "curved" | "zigzag";
+            from_block: string;
+            to_block: string;
+            label?: string | undefined;
+        }, {
+            type: "callout";
+            from_block: string;
+            to_block: string;
+            label?: string | undefined;
+            curve?: "straight" | "curved" | "zigzag" | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"ghost_reference">;
+            target_page: z.ZodNumber;
+            target_block: z.ZodString;
+            position: z.ZodDefault<z.ZodEnum<["top-right", "top-left", "bottom-right", "bottom-left"]>>;
+        }, "strip", z.ZodTypeAny, {
+            type: "ghost_reference";
+            position: "top-right" | "top-left" | "bottom-right" | "bottom-left";
+            target_block: string;
+            target_page: number;
+        }, {
+            type: "ghost_reference";
+            target_block: string;
+            target_page: number;
+            position?: "top-right" | "top-left" | "bottom-right" | "bottom-left" | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"box">;
+            target_block: z.ZodString;
+            color: z.ZodDefault<z.ZodString>;
+            style: z.ZodDefault<z.ZodEnum<["solid", "dashed"]>>;
+        }, "strip", z.ZodTypeAny, {
+            style: "solid" | "dashed";
+            color: string;
+            type: "box";
+            target_block: string;
+        }, {
+            type: "box";
+            target_block: string;
+            style?: "solid" | "dashed" | undefined;
+            color?: string | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"label">;
+            target_block: z.ZodString;
+            text: z.ZodString;
+            position: z.ZodDefault<z.ZodEnum<["top", "bottom", "left", "right"]>>;
+        }, "strip", z.ZodTypeAny, {
+            text: string;
+            type: "label";
+            position: "top" | "bottom" | "left" | "right";
+            target_block: string;
+        }, {
+            text: string;
+            type: "label";
+            target_block: string;
+            position?: "top" | "bottom" | "left" | "right" | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"clear">;
+            targets: z.ZodDefault<z.ZodUnion<[z.ZodEnum<["all", "spotlights", "overlays"]>, z.ZodArray<z.ZodString, "many">]>>;
+        }, "strip", z.ZodTypeAny, {
+            type: "clear";
+            targets: "all" | "spotlights" | "overlays" | string[];
+        }, {
+            type: "clear";
+            targets?: "all" | "spotlights" | "overlays" | string[] | undefined;
+        }>]>;
+    }, "strip", z.ZodTypeAny, {
+        action: {
+            type: "camera";
+            scale: number;
+            easing: "linear" | "ease-in" | "ease-out" | "ease-in-out";
+            padding: number;
+            target_block?: string | undefined;
+            target_bbox?: [number, number, number, number] | undefined;
+        } | {
+            type: "spotlight";
+            shape: "rect" | "rounded" | "ellipse";
+            target_block: string;
+            dim_opacity: number;
+            feather_px: number;
+        } | {
+            style: "straight" | "sketch" | "double" | "wavy";
+            color: string;
+            type: "underline";
+            target_block: string;
+            draw_duration_ms: number;
+        } | {
+            color: string;
+            type: "highlight";
+            target_block: string;
+            draw_duration_ms: number;
+        } | {
+            type: "pulse";
+            target_block: string;
+            count: number;
+            intensity: "subtle" | "normal" | "strong";
+        } | {
+            type: "callout";
+            curve: "straight" | "curved" | "zigzag";
+            from_block: string;
+            to_block: string;
+            label?: string | undefined;
+        } | {
+            type: "ghost_reference";
+            position: "top-right" | "top-left" | "bottom-right" | "bottom-left";
+            target_block: string;
+            target_page: number;
+        } | {
+            style: "solid" | "dashed";
+            color: string;
+            type: "box";
+            target_block: string;
+        } | {
+            text: string;
+            type: "label";
+            position: "top" | "bottom" | "left" | "right";
+            target_block: string;
+        } | {
+            type: "clear";
+            targets: "all" | "spotlights" | "overlays" | string[];
+        };
+        at_ms: number;
+        duration_ms: number;
+    }, {
+        action: {
+            type: "camera";
+            scale?: number | undefined;
+            easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | undefined;
+            padding?: number | undefined;
+            target_block?: string | undefined;
+            target_bbox?: [number, number, number, number] | undefined;
+        } | {
+            type: "spotlight";
+            target_block: string;
+            shape?: "rect" | "rounded" | "ellipse" | undefined;
+            dim_opacity?: number | undefined;
+            feather_px?: number | undefined;
+        } | {
+            type: "underline";
+            target_block: string;
+            style?: "straight" | "sketch" | "double" | "wavy" | undefined;
+            color?: string | undefined;
+            draw_duration_ms?: number | undefined;
+        } | {
+            type: "highlight";
+            target_block: string;
+            color?: string | undefined;
+            draw_duration_ms?: number | undefined;
+        } | {
+            type: "pulse";
+            target_block: string;
+            count?: number | undefined;
+            intensity?: "subtle" | "normal" | "strong" | undefined;
+        } | {
+            type: "callout";
+            from_block: string;
+            to_block: string;
+            label?: string | undefined;
+            curve?: "straight" | "curved" | "zigzag" | undefined;
+        } | {
+            type: "ghost_reference";
+            target_block: string;
+            target_page: number;
+            position?: "top-right" | "top-left" | "bottom-right" | "bottom-left" | undefined;
+        } | {
+            type: "box";
+            target_block: string;
+            style?: "solid" | "dashed" | undefined;
+            color?: string | undefined;
+        } | {
+            text: string;
+            type: "label";
+            target_block: string;
+            position?: "top" | "bottom" | "left" | "right" | undefined;
+        } | {
+            type: "clear";
+            targets?: "all" | "spotlights" | "overlays" | string[] | undefined;
+        };
+        at_ms?: number | undefined;
+        duration_ms?: number | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    version: 1;
+    reasoning: string;
+    steps: {
+        action: {
+            type: "camera";
+            scale: number;
+            easing: "linear" | "ease-in" | "ease-out" | "ease-in-out";
+            padding: number;
+            target_block?: string | undefined;
+            target_bbox?: [number, number, number, number] | undefined;
+        } | {
+            type: "spotlight";
+            shape: "rect" | "rounded" | "ellipse";
+            target_block: string;
+            dim_opacity: number;
+            feather_px: number;
+        } | {
+            style: "straight" | "sketch" | "double" | "wavy";
+            color: string;
+            type: "underline";
+            target_block: string;
+            draw_duration_ms: number;
+        } | {
+            color: string;
+            type: "highlight";
+            target_block: string;
+            draw_duration_ms: number;
+        } | {
+            type: "pulse";
+            target_block: string;
+            count: number;
+            intensity: "subtle" | "normal" | "strong";
+        } | {
+            type: "callout";
+            curve: "straight" | "curved" | "zigzag";
+            from_block: string;
+            to_block: string;
+            label?: string | undefined;
+        } | {
+            type: "ghost_reference";
+            position: "top-right" | "top-left" | "bottom-right" | "bottom-left";
+            target_block: string;
+            target_page: number;
+        } | {
+            style: "solid" | "dashed";
+            color: string;
+            type: "box";
+            target_block: string;
+        } | {
+            text: string;
+            type: "label";
+            position: "top" | "bottom" | "left" | "right";
+            target_block: string;
+        } | {
+            type: "clear";
+            targets: "all" | "spotlights" | "overlays" | string[];
+        };
+        at_ms: number;
+        duration_ms: number;
+    }[];
+}, {
+    version: 1;
+    steps: {
+        action: {
+            type: "camera";
+            scale?: number | undefined;
+            easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | undefined;
+            padding?: number | undefined;
+            target_block?: string | undefined;
+            target_bbox?: [number, number, number, number] | undefined;
+        } | {
+            type: "spotlight";
+            target_block: string;
+            shape?: "rect" | "rounded" | "ellipse" | undefined;
+            dim_opacity?: number | undefined;
+            feather_px?: number | undefined;
+        } | {
+            type: "underline";
+            target_block: string;
+            style?: "straight" | "sketch" | "double" | "wavy" | undefined;
+            color?: string | undefined;
+            draw_duration_ms?: number | undefined;
+        } | {
+            type: "highlight";
+            target_block: string;
+            color?: string | undefined;
+            draw_duration_ms?: number | undefined;
+        } | {
+            type: "pulse";
+            target_block: string;
+            count?: number | undefined;
+            intensity?: "subtle" | "normal" | "strong" | undefined;
+        } | {
+            type: "callout";
+            from_block: string;
+            to_block: string;
+            label?: string | undefined;
+            curve?: "straight" | "curved" | "zigzag" | undefined;
+        } | {
+            type: "ghost_reference";
+            target_block: string;
+            target_page: number;
+            position?: "top-right" | "top-left" | "bottom-right" | "bottom-left" | undefined;
+        } | {
+            type: "box";
+            target_block: string;
+            style?: "solid" | "dashed" | undefined;
+            color?: string | undefined;
+        } | {
+            text: string;
+            type: "label";
+            target_block: string;
+            position?: "top" | "bottom" | "left" | "right" | undefined;
+        } | {
+            type: "clear";
+            targets?: "all" | "spotlights" | "overlays" | string[] | undefined;
+        };
+        at_ms?: number | undefined;
+        duration_ms?: number | undefined;
+    }[];
+    reasoning?: string | undefined;
+}>;
+type StoryboardParsed = z.infer<typeof StoryboardSchema>;
+/** Converts the zod schema to JSON Schema for use with OpenAI structured outputs.
+ *
+ * OpenAI's structured outputs validator requires:
+ * - Every property has a `type` (no bare `const`/`enum` without `type`)
+ * - All properties listed in `required`
+ * - `additionalProperties: false` on every object
+ *
+ * We model the action union as a single object with all possible fields optional
+ * at the schema level (validated strictly later by zod). This keeps the schema
+ * compatible across providers; field-level required-ness is enforced post-parse.
+ */
+interface StoryboardJsonSchemaOptions {
+    /** Block IDs valid for the CURRENT page. Constrains target_block / from_block / to_block. */
+    validBlockIds?: string[];
+    /** Block IDs valid for cross-page references (e.g., figures on other pages). */
+    validCrossPageBlockIds?: string[];
+}
+declare function storyboardJsonSchema(opts?: StoryboardJsonSchemaOptions): Record<string, unknown>;
+
+/**
+ * Lazily load a local MiniLM model (only on first call). The dynamic import
+ * keeps `@xenova/transformers` out of the main bundle unless used.
+ */
+declare function getLocalMiniLM(): Promise<EmbeddingProvider>;
+
 type ViewerStore = ViewerState & ViewerActions;
 declare function createViewerStore(initialOverrides?: Partial<ViewerState>): zustand.StoreApi<ViewerStore>;
 type ViewerStoreApi = ReturnType<typeof createViewerStore>;
@@ -2776,4 +3824,4 @@ declare function getRectIntersection(rectA: {
  */
 declare function playPageTurnSound(volume?: number): void;
 
-export { type AddNoteOptions, type AgentAPI, type AgentAPIInstance, type AgentAPIStores, type AgentActions, type AgentContext, type AgentHighlightParams, type AgentState, type AgentStore, type AgentStoreApi, type AgentToolResult, type AgentTools, type Annotation, type AnnotationActions, AnnotationLayer, type AnnotationLayerProps, type AnnotationState, type AnnotationStore, type AnnotationStoreApi, type AnnotationTool, AnnotationToolbar, type AnnotationToolbarProps, type AnnotationType, type AskAboutContext, AskAboutOverlay, type AskAboutOverlayProps, AskAboutTrigger, type AskAboutTriggerProps, BookModeContainer, type BookModeContainerProps, type Bookmark, BookmarksPanel, type BookmarksPanelProps, CanvasLayer, type CanvasLayerProps, type CharPosition, type ContextMenuItem, ContinuousScrollContainer, type ContinuousScrollContainerProps, type CoordinateHelpers, DocumentContainer, type DocumentContainerProps, type DocumentLoadingState, type DrawCircleOptions, type DrawRectOptions, type DrawingAnnotation, DrawingCanvas, type DrawingCanvasProps, type DrawingPath, DualPageContainer, type DualPageContainerProps, type ExportData, type FindTextOptions, FloatingZoomControls, type FloatingZoomControlsProps, FocusRegionLayer, type FocusRegionLayerProps, type FocusedRegion, type GoToPageOptions, type Highlight, type HighlightColor, HighlightLayer, type HighlightLayerProps, HighlightPopover, type HighlightPopoverProps, type HighlightRect, type HighlightTextOptions, HighlightsPanel, type HighlightsPanelProps, type LoadDocumentOptions, type LoadDocumentResult, type LoadDocumentWithCallbacksOptions, type LoadDocumentWithCallbacksResult, type LoadingPhase, type LoadingProgress, Minimap, type MinimapProps, MobileSidebar, type MobileSidebarProps, MobileToolbar, type MobileToolbarProps, type NoteAnnotation, type OutlineItem, OutlinePanel, type OutlinePanelProps, type PDFDocumentLoadedEvent, PDFErrorBoundary, type PDFErrorBoundaryProps, PDFLoadingScreen, type PDFLoadingScreenProps, PDFPage, type PDFPageProps, type PDFPageState, type PDFRegion, PDFThumbnailNav, type PDFThumbnailNavProps, PDFViewer, PDFViewerClient, PDFViewerContext, type PDFViewerContextValue, type PDFViewerController, type PDFViewerControllerOptions, type PDFViewerEventMap, type PDFViewerHandle, type PDFViewerProps, PDFViewerProvider, type PDFViewerProviderProps, type PageCoordinates, type PageDimensions, type PageDimensionsInfo, type Plugin, type PluginAPI, PluginManager, type PluginManagerOptions, type QuickNote, QuickNoteButton, type QuickNoteButtonProps, QuickNotePopover, type QuickNotePopoverProps, type ScrollMode, type ScrollToPageRequest, type SearchActions, type SearchAndHighlightOptions, type SearchAndHighlightResult, type SearchOptions, SearchPanel, type SearchPanelProps, type SearchResult, type SearchState, type SearchStore, type SearchStoreApi, SelectionToolbar, type SelectionToolbarProps, type ShapeAnnotation, ShapePreview, type ShapePreviewProps, ShapeRenderer, type ShapeRendererProps, type ShapeType, Sidebar, type SidebarPanel, type SidebarPanelConfig, type SidebarProps, StickyNote, type StickyNoteProps, type StoredStudentData, type StreamingProgress, type StudentActions, type StudentData, type StudentModeCallbacks, type StudentModeProps, type StudentState, type StudentStore, type StudentStoreApi, type Takeaway, TakeawaysPanel, type TakeawaysPanelProps, TextLayer, type TextLayerProps, type TextMatch, type TextSelection, type Theme, ThumbnailPanel, type ThumbnailPanelProps, Toolbar, type ToolbarItem, type ToolbarProps, type UseAgentContextOptions, type UseAgentContextReturn, type UseAnnotationsOptions, type UseAnnotationsReturn, type UseAskAboutOptions, type UseAskAboutReturn, type UseBookmarksOptions, type UseBookmarksReturn, type UseHighlightsOptions, type UseHighlightsReturn, type UsePageNavigationOptions, type UsePluginsOptions, type UsePluginsReturn, type UseQuickNotesOptions, type UseQuickNotesReturn, type UseStudentProgressOptions, type UseStudentProgressReturn, type UseTextSelectionOptions, type UseTouchGesturesOptions, type UseZoomOptions, type ViewMode, type ViewerActions, type ViewerState, type ViewerStore, type ViewerStoreApi, VirtualizedDocumentContainer, type VirtualizedDocumentContainerProps, type WithErrorBoundaryProps, applyRotation, clearHighlights, clearStudentData, cn, countTextOnPage, createAgentAPI, createAgentStore, createAnnotationStore, createPDFViewer, createPluginManager, createSearchStore, createStudentStore, createViewerStore, doRectsIntersect, downloadAnnotationsAsJSON, downloadAnnotationsAsMarkdown, downloadFile, exportAnnotationsAsJSON, exportAnnotationsAsMarkdown, exportHighlightsAsJSON, exportHighlightsAsMarkdown, extractPageText, findTextInDocument, findTextOnPage, generateDocumentId, getAllDocumentIds, getAllStudentDataDocumentIds, getMetadata, getOutline, getPage, getPageText, getPageTextContent, getPluginManager, getRectIntersection, getRotatedDimensions, getStorageStats, importHighlightsFromJSON, initializePDFJS, isPDFJSInitialized, isPointInRect, loadDocument, loadDocumentWithCallbacks, loadHighlights, loadStudentData, mergeAdjacentRects, pdfToPercent, pdfToViewport, percentToPDF, percentToViewport, playPageTurnSound, quickViewer, removeRotation, saveHighlights, saveStudentData, scaleRect, useAgentContext, useAgentStore, useAnnotationStore, useAnnotations, useAskAbout, useBookmarks, useHighlights, useIsMobile, useIsTouchDevice, usePDFViewer, usePDFViewerStores, usePageNavigation, usePlugins, useQuickNotes, useSearchStore, useStudentProgress, useStudentStore, useTextSelection, useTouchGestures, useViewerStore, useZoom, viewportToPDF, viewportToPercent, withErrorBoundary };
+export { type ActionBox, type ActionCallout, type ActionCamera, type ActionClear, type ActionGhostReference, type ActionHighlight, type ActionLabel, type ActionPulse, type ActionSpotlight, type ActionUnderline, type ActiveOverlay, type AddNoteOptions, type AgentAPI, type AgentAPIInstance, type AgentAPIStores, type AgentActions, type AgentContext, type AgentHighlightParams, type AgentState, type AgentStore, type AgentStoreApi, type AgentToolResult, type AgentTools, AnimatedHighlight, type AnimatedHighlightProps, AnimatedUnderline, type AnimatedUnderlineProps, type Annotation, type AnnotationActions, AnnotationLayer, type AnnotationLayerProps, type AnnotationState, type AnnotationStore, type AnnotationStoreApi, type AnnotationTool, AnnotationToolbar, type AnnotationToolbarProps, type AnnotationType, type ArrowCurve, type AskAboutContext, AskAboutOverlay, type AskAboutOverlayProps, AskAboutTrigger, type AskAboutTriggerProps, type BBoxCoords, type BBoxIndex, type Block, type BlockMatch, type BlockType, BookModeContainer, type BookModeContainerProps, type Bookmark, BookmarksPanel, type BookmarksPanelProps, BoxOverlay, type BoxOverlayProps, type BoxStyle, type BuildUserPromptInput, CalloutArrow, type CalloutArrowProps, type CameraState, CameraView, type CameraViewProps, CanvasLayer, type CanvasLayerProps, type CharPosition, type ChunkHistoryEntry, CinemaLayer, type CinemaLayerProps, type ClearTarget, type ContextMenuItem, ContinuousScrollContainer, type ContinuousScrollContainerProps, type CoordinateHelpers, type DebugEvent, type DefaultAction, type DirectorInput, type DirectorResult, DocumentContainer, type DocumentContainerProps, type DocumentLoadingState, type DrawCircleOptions, type DrawRectOptions, type DrawingAnnotation, DrawingCanvas, type DrawingCanvasProps, type DrawingPath, DualPageContainer, type DualPageContainerProps, type EasingName, type EmbeddingProvider, type EngineStatus, type ExportData, type FindTextOptions, FloatingZoomControls, type FloatingZoomControlsProps, FocusRegionLayer, type FocusRegionLayerProps, type FocusedRegion, type GhostPosition, GhostReference, type GhostReferenceProps, type GoToPageOptions, type Highlight, type HighlightColor, HighlightLayer, type HighlightLayerProps, HighlightPopover, type HighlightPopoverProps, type HighlightRect, type HighlightTextOptions, HighlightsPanel, type HighlightsPanelProps, type LabelPosition, type LlmConfig, type LlmStatus, type LoadDocumentOptions, type LoadDocumentResult, type LoadDocumentWithCallbacksOptions, type LoadDocumentWithCallbacksResult, type LoadingPhase, type LoadingProgress, Minimap, type MinimapProps, MobileSidebar, type MobileSidebarProps, MobileToolbar, type MobileToolbarProps, type NarrationActions, type NarrationState, type NarrationStore, type NarrationStoreApi, type NoteAnnotation, type OutlineItem, OutlinePanel, type OutlinePanelProps, type PDFDocumentLoadedEvent, PDFErrorBoundary, type PDFErrorBoundaryProps, PDFLoadingScreen, type PDFLoadingScreenProps, PDFPage, type PDFPageProps, type PDFPageState, type PDFRegion, PDFThumbnailNav, type PDFThumbnailNavProps, PDFViewer, PDFViewerClient, PDFViewerContext, type PDFViewerContextValue, type PDFViewerController, type PDFViewerControllerOptions, type PDFViewerEventMap, type PDFViewerHandle, type PDFViewerProps, PDFViewerProvider, type PDFViewerProviderProps, type PageBBoxData, type PageCoordinates, type PageDimensions, type PageDimensionsDpi, type PageDimensionsInfo, type Plugin, type PluginAPI, PluginManager, type PluginManagerOptions, type PulseIntensity, PulseOverlay, type PulseOverlayProps, type QuickNote, QuickNoteButton, type QuickNoteButtonProps, QuickNotePopover, type QuickNotePopoverProps, SYSTEM_PROMPT, type ScrollMode, type ScrollToPageRequest, type SearchActions, type SearchAndHighlightOptions, type SearchAndHighlightResult, type SearchOptions, SearchPanel, type SearchPanelProps, type SearchResult, type SearchState, type SearchStore, type SearchStoreApi, SelectionToolbar, type SelectionToolbarProps, type ShapeAnnotation, ShapePreview, type ShapePreviewProps, ShapeRenderer, type ShapeRendererProps, type ShapeType, Sidebar, type SidebarPanel, type SidebarPanelConfig, type SidebarProps, SpotlightMask, type SpotlightMaskProps, type SpotlightShape, StickyLabel, type StickyLabelProps, StickyNote, type StickyNoteProps, type StoredStudentData, type Storyboard, type StoryboardAction, StoryboardActionSchema, StoryboardEngine, type StoryboardParsed, StoryboardSchema, type StoryboardStep, type StreamingProgress, type StudentActions, type StudentData, type StudentModeCallbacks, type StudentModeProps, type StudentState, type StudentStore, type StudentStoreApi, SubtitleBar, type SubtitleBarProps, type Takeaway, TakeawaysPanel, type TakeawaysPanelProps, TextLayer, type TextLayerProps, type TextMatch, type TextSelection, type Theme, ThumbnailPanel, type ThumbnailPanelProps, Toolbar, type ToolbarItem, type ToolbarProps, TutorModeContainer, type TutorModeContainerProps, type UnderlineStyle, type UseAgentContextOptions, type UseAgentContextReturn, type UseAnnotationsOptions, type UseAnnotationsReturn, type UseAskAboutOptions, type UseAskAboutReturn, type UseBookmarksOptions, type UseBookmarksReturn, type UseHighlightsOptions, type UseHighlightsReturn, type UsePageNavigationOptions, type UsePluginsOptions, type UsePluginsReturn, type UseQuickNotesOptions, type UseQuickNotesReturn, type UseStudentProgressOptions, type UseStudentProgressReturn, type UseTextSelectionOptions, type UseTouchGesturesOptions, type UseZoomOptions, type ViewMode, type ViewerActions, type ViewerState, type ViewerStore, type ViewerStoreApi, VirtualizedDocumentContainer, type VirtualizedDocumentContainerProps, type WithErrorBoundaryProps, applyRotation, buildBBoxIndex, buildUserPrompt, clearHighlights, clearStudentData, cn, cosineSimilarity, countTextOnPage, createAgentAPI, createAgentStore, createAnnotationStore, createNarrationStore, createPDFViewer, createPluginManager, createSearchStore, createStudentStore, createViewerStore, directStoryboard, doRectsIntersect, downloadAnnotationsAsJSON, downloadAnnotationsAsMarkdown, downloadFile, exportAnnotationsAsJSON, exportAnnotationsAsMarkdown, exportHighlightsAsJSON, exportHighlightsAsMarkdown, extractPageText, findTextInDocument, findTextOnPage, generateDocumentId, getAllDocumentIds, getAllStudentDataDocumentIds, getLocalMiniLM, getMetadata, getOutline, getPage, getPageText, getPageTextContent, getPluginManager, getRectIntersection, getRotatedDimensions, getStorageStats, importHighlightsFromJSON, initializePDFJS, isPDFJSInitialized, isPointInRect, loadDocument, loadDocumentWithCallbacks, loadHighlights, loadStudentData, makeOverlayId, matchChunkToBlock, mergeAdjacentRects, pdfToPercent, pdfToViewport, percentToPDF, percentToViewport, playPageTurnSound, quickViewer, removeRotation, saveHighlights, saveStudentData, scaleRect, storyboardFromMatch, storyboardJsonSchema, truncate, useAgentContext, useAgentStore, useAnnotationStore, useAnnotations, useAskAbout, useBookmarks, useHighlights, useIsMobile, useIsTouchDevice, usePDFViewer, usePDFViewerStores, usePageNavigation, usePlugins, useQuickNotes, useSearchStore, useStudentProgress, useStudentStore, useTextSelection, useTouchGestures, useViewerStore, useZoom, viewportToPDF, viewportToPercent, withErrorBoundary };