pdfjs-reader-core 0.4.3 → 0.5.1

package/dist/index.d.cts

@@ -1681,7 +1681,7 @@ declare function createNarrationStore(overrides?: Partial<NarrationState>): zust
 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.";
+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  \"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  \"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  \"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  \"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  \"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;
@@ -1744,6 +1744,30 @@ declare function matchChunkToBlock(chunk: string, page: PageBBoxData, provider:
  */
 declare function storyboardFromMatch(match: BlockMatch | null, page?: PageBBoxData): Storyboard;
 
+/**
+ * Input passed to a consumer-supplied `storyboardProvider`. Gives the
+ * provider everything the built-in director already has access to, so
+ * the consumer can decide how much context to forward to their own
+ * endpoint (typically: just `chunk` + `pageNumber`, since bbox is
+ * usually cached server-side).
+ */
+interface StoryboardProviderInput {
+    chunk: string;
+    pageNumber: number;
+    /** The current page's bbox data — included in case the provider wants
+     *  to forward it, though usually the provider's backend already has
+     *  this cached. */
+    page: PageBBoxData;
+    /** Last few chunks the tutor has spoken, for conversational context. */
+    history: ReadonlyArray<{
+        text: string;
+        pageNumber: number;
+        timestamp: number;
+    }>;
+    /** AbortSignal — if the consumer's fetch supports it, wire it up so
+     *  a newer chunk cancels a stale in-flight request. */
+    signal: AbortSignal;
+}
 interface TutorModeContainerProps {
     pageNumber: number;
     bboxData: PageBBoxData[];
@@ -1752,8 +1776,26 @@ interface TutorModeContainerProps {
     rotation?: number;
     /** Reactive chunk from the tutor (updates as she speaks) */
     currentChunk?: string | null;
-    /** LLM endpoint configuration provided by the consumer */
+    /** LLM endpoint configuration used by the built-in director. */
     llm?: LlmConfig;
+    /**
+     * Consumer-owned director. When provided, this is called per chunk
+     * INSTEAD OF `directStoryboard(llm, …)`. Return a storyboard matching
+     * `StoryboardSchema` (or `null` to skip the chunk). The library still
+     * validates the return value, runs salvage (range clamp, overlay-
+     * presence), and emits debug events, so DebugLog telemetry is
+     * identical to the built-in path.
+     *
+     * Use this when your backend owns the system prompt + bbox context
+     * (e.g. a fine-tuned director endpoint) and you want to iterate on
+     * prompt/model choices without a library upgrade.
+     *
+     * Priority: if BOTH `storyboardProvider` and `llm` are set, the
+     * provider wins and `llm` is ignored.
+     *
+     * Added in v0.5.0.
+     */
+    storyboardProvider?: (input: StoryboardProviderInput) => Promise<Storyboard | null>;
     /** 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). */
@@ -1820,7 +1862,7 @@ interface TutorModeContainerProps {
 }
 /** 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, backgroundColor, loadingComponent, onPageChange, className, }: TutorModeContainerProps): react_jsx_runtime.JSX.Element;
+declare function TutorModeContainer({ pageNumber, bboxData, narrationStore, scale, rotation, currentChunk, llm, idleTimeoutMs, llmTimeoutMs, embeddingProvider, showSubtitles, showExitButton, onExitTutorMode, minOverlayDurationMs, backgroundColor, loadingComponent, onPageChange, storyboardProvider, className, }: TutorModeContainerProps): react_jsx_runtime.JSX.Element;
 
 interface CinemaLayerProps {
     page: PageBBoxData;
@@ -1876,21 +1918,6 @@ interface AnimatedHighlightProps {
     bbox: BBoxCoords;
     action: ActionHighlight;
 }
-/**
- * Design: **Real highlighter stroke.** A flat rectangle feels digital;
- * a real highlighter has fibrous texture, a soft inner + harder outer
- * edge, a slight over-bleed past the baseline, and visible uneven
- * starts/ends where the pen hit and lifted the paper.
- *
- * Implementation:
- * - Double-stroke — a broad soft wash behind a tighter primary stroke
- *   so the mark has depth where they overlap.
- * - Slight vertical over-bleed (2–3 px above/below the bbox) so the
- *   highlight doesn't look clipped to the text baseline.
- * - Rounded caps + uneven left/right ends via tapered start/finish
- *   for the "pen hit the page" look.
- * - Feathered edge mask via SVG filter for the fibrous marker feel.
- */
 declare function AnimatedHighlight({ bbox, action }: AnimatedHighlightProps): react_jsx_runtime.JSX.Element;
 
 interface PulseOverlayProps {
@@ -2220,7 +2247,7 @@ declare const StoryboardActionSchema: z.ZodUnion<[z.ZodEffects<z.ZodObject<{
 }>]>;
 declare const StoryboardSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
-    reasoning: z.ZodDefault<z.ZodString>;
+    reasoning: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     steps: z.ZodArray<z.ZodObject<{
         at_ms: z.ZodDefault<z.ZodNumber>;
         duration_ms: z.ZodDefault<z.ZodNumber>;
@@ -3949,4 +3976,4 @@ declare function getRectIntersection(rectA: {
  */
 declare function playPageTurnSound(volume?: number): void;
 
-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 };
+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, type StoryboardProviderInput, 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 };

package/dist/index.d.ts

@@ -1681,7 +1681,7 @@ declare function createNarrationStore(overrides?: Partial<NarrationState>): zust
 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.";
+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  \"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  \"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  \"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  \"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  \"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;
@@ -1744,6 +1744,30 @@ declare function matchChunkToBlock(chunk: string, page: PageBBoxData, provider:
  */
 declare function storyboardFromMatch(match: BlockMatch | null, page?: PageBBoxData): Storyboard;
 
+/**
+ * Input passed to a consumer-supplied `storyboardProvider`. Gives the
+ * provider everything the built-in director already has access to, so
+ * the consumer can decide how much context to forward to their own
+ * endpoint (typically: just `chunk` + `pageNumber`, since bbox is
+ * usually cached server-side).
+ */
+interface StoryboardProviderInput {
+    chunk: string;
+    pageNumber: number;
+    /** The current page's bbox data — included in case the provider wants
+     *  to forward it, though usually the provider's backend already has
+     *  this cached. */
+    page: PageBBoxData;
+    /** Last few chunks the tutor has spoken, for conversational context. */
+    history: ReadonlyArray<{
+        text: string;
+        pageNumber: number;
+        timestamp: number;
+    }>;
+    /** AbortSignal — if the consumer's fetch supports it, wire it up so
+     *  a newer chunk cancels a stale in-flight request. */
+    signal: AbortSignal;
+}
 interface TutorModeContainerProps {
     pageNumber: number;
     bboxData: PageBBoxData[];
@@ -1752,8 +1776,26 @@ interface TutorModeContainerProps {
     rotation?: number;
     /** Reactive chunk from the tutor (updates as she speaks) */
     currentChunk?: string | null;
-    /** LLM endpoint configuration provided by the consumer */
+    /** LLM endpoint configuration used by the built-in director. */
     llm?: LlmConfig;
+    /**
+     * Consumer-owned director. When provided, this is called per chunk
+     * INSTEAD OF `directStoryboard(llm, …)`. Return a storyboard matching
+     * `StoryboardSchema` (or `null` to skip the chunk). The library still
+     * validates the return value, runs salvage (range clamp, overlay-
+     * presence), and emits debug events, so DebugLog telemetry is
+     * identical to the built-in path.
+     *
+     * Use this when your backend owns the system prompt + bbox context
+     * (e.g. a fine-tuned director endpoint) and you want to iterate on
+     * prompt/model choices without a library upgrade.
+     *
+     * Priority: if BOTH `storyboardProvider` and `llm` are set, the
+     * provider wins and `llm` is ignored.
+     *
+     * Added in v0.5.0.
+     */
+    storyboardProvider?: (input: StoryboardProviderInput) => Promise<Storyboard | null>;
     /** 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). */
@@ -1820,7 +1862,7 @@ interface TutorModeContainerProps {
 }
 /** 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, backgroundColor, loadingComponent, onPageChange, className, }: TutorModeContainerProps): react_jsx_runtime.JSX.Element;
+declare function TutorModeContainer({ pageNumber, bboxData, narrationStore, scale, rotation, currentChunk, llm, idleTimeoutMs, llmTimeoutMs, embeddingProvider, showSubtitles, showExitButton, onExitTutorMode, minOverlayDurationMs, backgroundColor, loadingComponent, onPageChange, storyboardProvider, className, }: TutorModeContainerProps): react_jsx_runtime.JSX.Element;
 
 interface CinemaLayerProps {
     page: PageBBoxData;
@@ -1876,21 +1918,6 @@ interface AnimatedHighlightProps {
     bbox: BBoxCoords;
     action: ActionHighlight;
 }
-/**
- * Design: **Real highlighter stroke.** A flat rectangle feels digital;
- * a real highlighter has fibrous texture, a soft inner + harder outer
- * edge, a slight over-bleed past the baseline, and visible uneven
- * starts/ends where the pen hit and lifted the paper.
- *
- * Implementation:
- * - Double-stroke — a broad soft wash behind a tighter primary stroke
- *   so the mark has depth where they overlap.
- * - Slight vertical over-bleed (2–3 px above/below the bbox) so the
- *   highlight doesn't look clipped to the text baseline.
- * - Rounded caps + uneven left/right ends via tapered start/finish
- *   for the "pen hit the page" look.
- * - Feathered edge mask via SVG filter for the fibrous marker feel.
- */
 declare function AnimatedHighlight({ bbox, action }: AnimatedHighlightProps): react_jsx_runtime.JSX.Element;
 
 interface PulseOverlayProps {
@@ -2220,7 +2247,7 @@ declare const StoryboardActionSchema: z.ZodUnion<[z.ZodEffects<z.ZodObject<{
 }>]>;
 declare const StoryboardSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
-    reasoning: z.ZodDefault<z.ZodString>;
+    reasoning: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     steps: z.ZodArray<z.ZodObject<{
         at_ms: z.ZodDefault<z.ZodNumber>;
         duration_ms: z.ZodDefault<z.ZodNumber>;
@@ -3949,4 +3976,4 @@ declare function getRectIntersection(rectA: {
  */
 declare function playPageTurnSound(volume?: number): void;
 
-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 };
+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, type StoryboardProviderInput, 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 };