pdfjs-reader-core 0.4.1 → 0.4.2

package/dist/index.d.cts

@@ -1795,11 +1795,32 @@ interface TutorModeContainerProps {
      * the `backgroundColor` surround.
      */
     loadingComponent?: react__default.ReactNode;
+    /**
+     * Fired when the underlying viewer's page changes from any source — the
+     * agent API (`agentTools.goToPage / nextPage / previousPage`), the sidebar
+     * (bookmarks, thumbnails, search), or a programmatic
+     * `useViewerStore().goToPage` call. Use this to keep your own
+     * `pageNumber` state (the controlled prop you pass in) in lockstep with
+     * the viewer, so agent-driven navigation actually moves the rendered
+     * page and downstream concerns (progress save, recap, etc.) see the
+     * right value.
+     *
+     * ```tsx
+     * const [currentPage, setCurrentPage] = useState(1);
+     * <TutorModeContainer
+     *   pageNumber={currentPage}
+     *   onPageChange={setCurrentPage}   // ← bidirectional sync
+     * />
+     * ```
+     *
+     * Added in v0.4.2.
+     */
+    onPageChange?: (page: number) => void;
     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, backgroundColor, loadingComponent, 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, className, }: TutorModeContainerProps): react_jsx_runtime.JSX.Element;
 
 interface CinemaLayerProps {
     page: PageBBoxData;
@@ -1829,13 +1850,19 @@ interface SpotlightMaskProps {
     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.
+ * Design: **Theatrical spotlight.** A warm-ink dim (not pure black)
+ * closes over the whole page, then a feathered cutout reveals the
+ * target block. A thin terracotta accent ring follows the cutout shape
+ * — the same colour used by every other overlay so the spotlit region
+ * is clearly part of the same annotation system.
+ *
+ * The dim colour is warm INK (`#2a2420`) rather than `#000` so the
+ * dimmed area looks like the PDF pushed into shadow rather than
+ * blacked out. On light textbook pages this reads as "atmosphere"
+ * instead of "censorship".
  *
- * Rendered in PAGE coords (viewBox spans the full page). The parent
- * CinemaLayer applies the overall scale transform.
+ * The accent ring animates with a slight stagger after the dim, so the
+ * reveal has a subtle two-beat cadence: darken → point.
  */
 declare function SpotlightMask({ page, bbox, action, durationMs, }: SpotlightMaskProps): react_jsx_runtime.JSX.Element;
 
@@ -1849,12 +1876,40 @@ 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 {
     bbox: BBoxCoords;
     action: ActionPulse;
 }
+/**
+ * Design: **Camera viewfinder brackets.** Four L-shapes slide in from
+ * each corner of the target block, like framing crosshairs on a camera.
+ * Behind them, a soft radial glow pulses in sync with the bracket
+ * emphasis — a "look here" cue that points without blocking content.
+ *
+ * Intensity controls bracket length + stroke weight + glow strength.
+ * `count` controls how many emphasis pulses happen before the overlay
+ * settles.
+ *
+ * Brackets slide in from OUTSIDE the block then snap to the corners,
+ * which reads as "framing" rather than the usual bordered box.
+ */
 declare function PulseOverlay({ bbox, action }: PulseOverlayProps): react_jsx_runtime.JSX.Element;
 
 interface CalloutArrowProps {
@@ -1862,6 +1917,17 @@ interface CalloutArrowProps {
     toBbox: BBoxCoords;
     action: ActionCallout;
 }
+/**
+ * Design: **Editorial connector.** Hand-drawn feel via a refined stroke
+ * + a small origin dot at the "from" end (like a teacher's pen planted
+ * on the page before they draw the arrow). The arrowhead is a slender
+ * open caret rather than a heavy filled triangle — reads as annotation,
+ * not direction-signage.
+ *
+ * An optional label pill rides the arrow's trailing end using the same
+ * editorial pin language as StickyLabel (cream paper, terracotta rule,
+ * serif small-caps). Everything uses ACCENT for colour consistency.
+ */
 declare function CalloutArrow({ fromBbox, toBbox, action }: CalloutArrowProps): react_jsx_runtime.JSX.Element;
 
 interface GhostReferenceProps {
@@ -1871,24 +1937,50 @@ interface GhostReferenceProps {
     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;
+declare function GhostReference({ page, sourceBbox, sourceBlockText, action, }: GhostReferenceProps): react_jsx_runtime.JSX.Element;
 
 interface BoxOverlayProps {
     bbox: BBoxCoords;
     action: ActionBox;
 }
+/**
+ * Design: **Framed region.** A structural region marker — thinner and
+ * more refined than the previous generic 3px coloured border. A subtle
+ * accent-tinted wash fills the interior so the framed region reads as
+ * "selected" even without a thick border. Dashed style uses a custom
+ * dash pattern that matches the editorial vocabulary.
+ *
+ * Honours `action.color` when the LLM specifies something non-default,
+ * otherwise falls through to the terracotta accent so boxes fit the
+ * system.
+ */
 declare function BoxOverlay({ bbox, action }: BoxOverlayProps): react_jsx_runtime.JSX.Element;
 
 interface StickyLabelProps {
-    bbox: BBoxCoords;
+    /**
+     * Pre-computed anchor point in viewport pixels — the label will be
+     * placed at this point and positioned relative to it via
+     * `action.position`. See `LabelOverlay` for the coordinate math that
+     * maps a block's bbox + camera state to this value.
+     */
+    screenAnchor: {
+        x: number;
+        y: number;
+    };
     action: ActionLabel;
 }
-declare function StickyLabel({ bbox, action }: StickyLabelProps): react_jsx_runtime.JSX.Element;
+/**
+ * Editorial annotation pin. The label body sits a short distance from
+ * the target block, connected by a hairline stem and a small marker
+ * disc at the anchor point. Body uses a classical serif at small-caps
+ * sizing — feels like a scholar's tag, not a browser toast.
+ *
+ * Positioning math: caller pre-computes the `screenAnchor` (usually the
+ * midpoint of the block edge the label is attached to), and this
+ * component lays out the pin on the appropriate side via CSS translate
+ * offsets.
+ */
+declare function StickyLabel({ screenAnchor, action }: StickyLabelProps): react_jsx_runtime.JSX.Element;
 
 interface SubtitleBarProps {
     text: string | null;
@@ -2045,14 +2137,14 @@ declare const StoryboardActionSchema: z.ZodUnion<[z.ZodEffects<z.ZodObject<{
     intensity: z.ZodDefault<z.ZodEnum<["subtle", "normal", "strong"]>>;
 }, "strip", z.ZodTypeAny, {
     type: "pulse";
+    intensity: "subtle" | "normal" | "strong";
     target_block: string;
     count: number;
-    intensity: "subtle" | "normal" | "strong";
 }, {
     type: "pulse";
     target_block: string;
-    count?: number | undefined;
     intensity?: "subtle" | "normal" | "strong" | undefined;
+    count?: number | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"callout">;
     from_block: z.ZodString;
@@ -2225,14 +2317,14 @@ declare const StoryboardSchema: z.ZodObject<{
             intensity: z.ZodDefault<z.ZodEnum<["subtle", "normal", "strong"]>>;
         }, "strip", z.ZodTypeAny, {
             type: "pulse";
+            intensity: "subtle" | "normal" | "strong";
             target_block: string;
             count: number;
-            intensity: "subtle" | "normal" | "strong";
         }, {
             type: "pulse";
             target_block: string;
-            count?: number | undefined;
             intensity?: "subtle" | "normal" | "strong" | undefined;
+            count?: number | undefined;
         }>, z.ZodObject<{
             type: z.ZodLiteral<"callout">;
             from_block: z.ZodString;
@@ -2333,9 +2425,9 @@ declare const StoryboardSchema: z.ZodObject<{
             draw_duration_ms: number;
         } | {
             type: "pulse";
+            intensity: "subtle" | "normal" | "strong";
             target_block: string;
             count: number;
-            intensity: "subtle" | "normal" | "strong";
         } | {
             type: "callout";
             curve: "straight" | "curved" | "zigzag";
@@ -2391,8 +2483,8 @@ declare const StoryboardSchema: z.ZodObject<{
         } | {
             type: "pulse";
             target_block: string;
-            count?: number | undefined;
             intensity?: "subtle" | "normal" | "strong" | undefined;
+            count?: number | undefined;
         } | {
             type: "callout";
             from_block: string;
@@ -2451,9 +2543,9 @@ declare const StoryboardSchema: z.ZodObject<{
             draw_duration_ms: number;
         } | {
             type: "pulse";
+            intensity: "subtle" | "normal" | "strong";
             target_block: string;
             count: number;
-            intensity: "subtle" | "normal" | "strong";
         } | {
             type: "callout";
             curve: "straight" | "curved" | "zigzag";
@@ -2512,8 +2604,8 @@ declare const StoryboardSchema: z.ZodObject<{
         } | {
             type: "pulse";
             target_block: string;
-            count?: number | undefined;
             intensity?: "subtle" | "normal" | "strong" | undefined;
+            count?: number | undefined;
         } | {
             type: "callout";
             from_block: string;

package/dist/index.d.ts

@@ -1795,11 +1795,32 @@ interface TutorModeContainerProps {
      * the `backgroundColor` surround.
      */
     loadingComponent?: react__default.ReactNode;
+    /**
+     * Fired when the underlying viewer's page changes from any source — the
+     * agent API (`agentTools.goToPage / nextPage / previousPage`), the sidebar
+     * (bookmarks, thumbnails, search), or a programmatic
+     * `useViewerStore().goToPage` call. Use this to keep your own
+     * `pageNumber` state (the controlled prop you pass in) in lockstep with
+     * the viewer, so agent-driven navigation actually moves the rendered
+     * page and downstream concerns (progress save, recap, etc.) see the
+     * right value.
+     *
+     * ```tsx
+     * const [currentPage, setCurrentPage] = useState(1);
+     * <TutorModeContainer
+     *   pageNumber={currentPage}
+     *   onPageChange={setCurrentPage}   // ← bidirectional sync
+     * />
+     * ```
+     *
+     * Added in v0.4.2.
+     */
+    onPageChange?: (page: number) => void;
     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, backgroundColor, loadingComponent, 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, className, }: TutorModeContainerProps): react_jsx_runtime.JSX.Element;
 
 interface CinemaLayerProps {
     page: PageBBoxData;
@@ -1829,13 +1850,19 @@ interface SpotlightMaskProps {
     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.
+ * Design: **Theatrical spotlight.** A warm-ink dim (not pure black)
+ * closes over the whole page, then a feathered cutout reveals the
+ * target block. A thin terracotta accent ring follows the cutout shape
+ * — the same colour used by every other overlay so the spotlit region
+ * is clearly part of the same annotation system.
+ *
+ * The dim colour is warm INK (`#2a2420`) rather than `#000` so the
+ * dimmed area looks like the PDF pushed into shadow rather than
+ * blacked out. On light textbook pages this reads as "atmosphere"
+ * instead of "censorship".
  *
- * Rendered in PAGE coords (viewBox spans the full page). The parent
- * CinemaLayer applies the overall scale transform.
+ * The accent ring animates with a slight stagger after the dim, so the
+ * reveal has a subtle two-beat cadence: darken → point.
  */
 declare function SpotlightMask({ page, bbox, action, durationMs, }: SpotlightMaskProps): react_jsx_runtime.JSX.Element;
 
@@ -1849,12 +1876,40 @@ 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 {
     bbox: BBoxCoords;
     action: ActionPulse;
 }
+/**
+ * Design: **Camera viewfinder brackets.** Four L-shapes slide in from
+ * each corner of the target block, like framing crosshairs on a camera.
+ * Behind them, a soft radial glow pulses in sync with the bracket
+ * emphasis — a "look here" cue that points without blocking content.
+ *
+ * Intensity controls bracket length + stroke weight + glow strength.
+ * `count` controls how many emphasis pulses happen before the overlay
+ * settles.
+ *
+ * Brackets slide in from OUTSIDE the block then snap to the corners,
+ * which reads as "framing" rather than the usual bordered box.
+ */
 declare function PulseOverlay({ bbox, action }: PulseOverlayProps): react_jsx_runtime.JSX.Element;
 
 interface CalloutArrowProps {
@@ -1862,6 +1917,17 @@ interface CalloutArrowProps {
     toBbox: BBoxCoords;
     action: ActionCallout;
 }
+/**
+ * Design: **Editorial connector.** Hand-drawn feel via a refined stroke
+ * + a small origin dot at the "from" end (like a teacher's pen planted
+ * on the page before they draw the arrow). The arrowhead is a slender
+ * open caret rather than a heavy filled triangle — reads as annotation,
+ * not direction-signage.
+ *
+ * An optional label pill rides the arrow's trailing end using the same
+ * editorial pin language as StickyLabel (cream paper, terracotta rule,
+ * serif small-caps). Everything uses ACCENT for colour consistency.
+ */
 declare function CalloutArrow({ fromBbox, toBbox, action }: CalloutArrowProps): react_jsx_runtime.JSX.Element;
 
 interface GhostReferenceProps {
@@ -1871,24 +1937,50 @@ interface GhostReferenceProps {
     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;
+declare function GhostReference({ page, sourceBbox, sourceBlockText, action, }: GhostReferenceProps): react_jsx_runtime.JSX.Element;
 
 interface BoxOverlayProps {
     bbox: BBoxCoords;
     action: ActionBox;
 }
+/**
+ * Design: **Framed region.** A structural region marker — thinner and
+ * more refined than the previous generic 3px coloured border. A subtle
+ * accent-tinted wash fills the interior so the framed region reads as
+ * "selected" even without a thick border. Dashed style uses a custom
+ * dash pattern that matches the editorial vocabulary.
+ *
+ * Honours `action.color` when the LLM specifies something non-default,
+ * otherwise falls through to the terracotta accent so boxes fit the
+ * system.
+ */
 declare function BoxOverlay({ bbox, action }: BoxOverlayProps): react_jsx_runtime.JSX.Element;
 
 interface StickyLabelProps {
-    bbox: BBoxCoords;
+    /**
+     * Pre-computed anchor point in viewport pixels — the label will be
+     * placed at this point and positioned relative to it via
+     * `action.position`. See `LabelOverlay` for the coordinate math that
+     * maps a block's bbox + camera state to this value.
+     */
+    screenAnchor: {
+        x: number;
+        y: number;
+    };
     action: ActionLabel;
 }
-declare function StickyLabel({ bbox, action }: StickyLabelProps): react_jsx_runtime.JSX.Element;
+/**
+ * Editorial annotation pin. The label body sits a short distance from
+ * the target block, connected by a hairline stem and a small marker
+ * disc at the anchor point. Body uses a classical serif at small-caps
+ * sizing — feels like a scholar's tag, not a browser toast.
+ *
+ * Positioning math: caller pre-computes the `screenAnchor` (usually the
+ * midpoint of the block edge the label is attached to), and this
+ * component lays out the pin on the appropriate side via CSS translate
+ * offsets.
+ */
+declare function StickyLabel({ screenAnchor, action }: StickyLabelProps): react_jsx_runtime.JSX.Element;
 
 interface SubtitleBarProps {
     text: string | null;
@@ -2045,14 +2137,14 @@ declare const StoryboardActionSchema: z.ZodUnion<[z.ZodEffects<z.ZodObject<{
     intensity: z.ZodDefault<z.ZodEnum<["subtle", "normal", "strong"]>>;
 }, "strip", z.ZodTypeAny, {
     type: "pulse";
+    intensity: "subtle" | "normal" | "strong";
     target_block: string;
     count: number;
-    intensity: "subtle" | "normal" | "strong";
 }, {
     type: "pulse";
     target_block: string;
-    count?: number | undefined;
     intensity?: "subtle" | "normal" | "strong" | undefined;
+    count?: number | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"callout">;
     from_block: z.ZodString;
@@ -2225,14 +2317,14 @@ declare const StoryboardSchema: z.ZodObject<{
             intensity: z.ZodDefault<z.ZodEnum<["subtle", "normal", "strong"]>>;
         }, "strip", z.ZodTypeAny, {
             type: "pulse";
+            intensity: "subtle" | "normal" | "strong";
             target_block: string;
             count: number;
-            intensity: "subtle" | "normal" | "strong";
         }, {
             type: "pulse";
             target_block: string;
-            count?: number | undefined;
             intensity?: "subtle" | "normal" | "strong" | undefined;
+            count?: number | undefined;
         }>, z.ZodObject<{
             type: z.ZodLiteral<"callout">;
             from_block: z.ZodString;
@@ -2333,9 +2425,9 @@ declare const StoryboardSchema: z.ZodObject<{
             draw_duration_ms: number;
         } | {
             type: "pulse";
+            intensity: "subtle" | "normal" | "strong";
             target_block: string;
             count: number;
-            intensity: "subtle" | "normal" | "strong";
         } | {
             type: "callout";
             curve: "straight" | "curved" | "zigzag";
@@ -2391,8 +2483,8 @@ declare const StoryboardSchema: z.ZodObject<{
         } | {
             type: "pulse";
             target_block: string;
-            count?: number | undefined;
             intensity?: "subtle" | "normal" | "strong" | undefined;
+            count?: number | undefined;
         } | {
             type: "callout";
             from_block: string;
@@ -2451,9 +2543,9 @@ declare const StoryboardSchema: z.ZodObject<{
             draw_duration_ms: number;
         } | {
             type: "pulse";
+            intensity: "subtle" | "normal" | "strong";
             target_block: string;
             count: number;
-            intensity: "subtle" | "normal" | "strong";
         } | {
             type: "callout";
             curve: "straight" | "curved" | "zigzag";
@@ -2512,8 +2604,8 @@ declare const StoryboardSchema: z.ZodObject<{
         } | {
             type: "pulse";
             target_block: string;
-            count?: number | undefined;
             intensity?: "subtle" | "normal" | "strong" | undefined;
+            count?: number | undefined;
         } | {
             type: "callout";
             from_block: string;